Skip to navigation
Docusign Web Forms APIWebFormsInstances

Create web form instance

View as Markdown

The Web Forms API is available in all developer accounts, but only in certain production account plans. Contact Docusign Support or your account manager to find out whether the Web Forms API is available for your production account plan.

Creates an instance of a web form.

This endpoint returns a formUrl and instanceToken that you combine to obtain a secure URL. Use this URL to render the web form instance in your application.

Required authentication scopes: signature, webforms_instance_write.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

accountIdstringRequiredformat: "uuid"
The ID of the account to which the web form belongs.
formIdstringRequiredformat: "uuid"
The ID of the web form configuration.

Request

This endpoint expects an object.
clientUserIdstringRequired<=100 characters
A unique identifier for a user that should originate from client's system. This value can be anything your backend system would use to track individual form instances. Examples include employee IDs, email addresses, surrogate key values, etc.
formValuesmap from strings to anyOptional

Key-value pairs used to prefill fields in the web form instance. The keys correspond to the componentName values of the formContent.components object on the WebForm (configuration) object. See Form field definitions for more information.

For keys of type TextBox, Email, Date, Select, and RadioButtonGroup, the value should be a string. For keys of type Number, the value should be a number. For keys of type CheckboxGroup, the value should be an array of strings. For keys of type PhoneNumber, the value should be an object with the properties countryCode and nationalNumber. See Supply prefill values in the request to create a web form instance for more information and an example Instances:createInstance request body with a formValues object.

Note that you do not have to include values for every component. This property is optional.

For remote web form instances, if the Instances:createInstance request does not include a recipients object, the formValues object must supply a name and email address for each user who will receive an envelope email. If a phone number is needed for identity verification, the formValues object must supply it as well if the request does not include a recipients object. See Deliver remote web form instances to users for more information.

authenticationInstantstringOptional

A sender-generated value that indicates the date and time that the signer was authenticated.

authenticationMethodenumOptional

A value that most closely matches the technique your application used to authenticate the recipient / signer.

assertionIdstringOptional
A unique identifier of the authentication event executed by the client application.
securityDomainstringOptional
The domain in which the user authenticated.
returnUrlstringOptional
The url to which the user is redirected after the signing is completed
expirationOffsetlongOptional1-23976

Specify the number of hours after which the form instance expires. For example, if the form expiration is set to 5 days, you should specify 120. The default value is 720 hours (30 days).

sendOptionenumOptional
Allowed values:
brandIdstringOptionalformat: "uuid"
Brand Id for web form
recipientslist of objectsOptional

For remote web form instances, this object defines users who will receive an envelope email. The recipients object can be included only when the sendOption property is set to now.

Instead of using the recipients object to define users who will receive an envelope email, you can use the formValues object to provide the required user information. However, if the recipients object is used, a roleName, name, and email are required for each user. If a phone number is needed for identity verification that is enabled for a user’s role in the web form template, a phoneNumber is required as well. See Deliver remote web form instances to users for more information.

For web form instances that are displayed in an embedded view or via a redirect to the Docusign platform, the recipients object should be omitted.

tagslist of stringsOptional

Set this metadata to help your application identify the web form instance. The default value is [].

Example value: ["Client A", "Agreement Category B"]

This property is optional.

Response

Web Form Instance with metadata
idstringformat: "uuid"
Unique identifier for a webform instance that is consistent until its expiration
formUrlstringOptional
The instance url which can be rendered by the user
instanceTokenstringOptional
Unique token associated with an instance that is required to render the form instance. This token is valid for 5 minutes after which it needs to be refreshed using refreshToken api
tokenExpirationDateTimedatetimeOptional
The DateTime after which the token is expired and form instance is inaccessible.
formIdstringOptionalformat: "uuid"
Unique identifier for a webform entity that is consistent for it's lifetime
accountIdstringOptionalformat: "uuid"
Account identifier in which the webform resides
clientUserIdstringOptional<=100 characters
A unique identifier for a user that should originate from client's system. This value can be anything your backend system would use to track individual form instances. Examples include employee IDs, email addresses, surrogate key values, etc.
tagslist of stringsOptional

Metadata to help your application identify the web form instance.

Example: ["Client A", "Agreement Category B"]

statusenumOptional
The status of the form instance
Allowed values:
envelopeslist of objectsOptional

This object represents the eSignature envelope that is associated with the web form instance. An instance has an associated envelope if any of the following is true:

  • The instance was created from a template-based web form configuration, was displayed to the user in an embedded view, and the user submitted the instance, which resulted in the generation of an envelope.
  • The instance was created from a template-based web form configuration, was displayed to the user via a redirect to the Docusign platform, and the user submitted the instance, which resulted in the generation of an envelope.
  • The instance was created from a template-based web form configuration, and the Instances:createInstance request specified a remote web form instance. For this flow, an envelope is generated when the instance is created.

Web form instances generated from standalone configurations do not have envelopes associated with them.

instanceMetadataobjectOptional
Metadata associated with the web form instance.
formValuesmap from strings to anyOptional

Key-value pairs that represent the current values of the fields in the web form instance. The keys correspond to the componentName values of the formContent.components object on the WebForm (configuration) object. See Form field definitions for more information.

See Request that retrieves web form instance values for an example of a formValues object returned by this request.

brandIdstringOptionalformat: "uuid"
Brand Id for web form
recipientslist of objectsOptional

This object contains information about the users who fill out a web form instance and its associated envelope.

If the web form template has roles that do not fill out the web form instance, this object does not include users associated with those roles.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
500
Internal Server Error
503
Service Unavailable Error