Prefill web form instance fields | Docusign

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.

The Web Forms API enables you to prefill web form instance fields with customer data from your system of record. Any known information about a customer, such as a name, account information, and contact information, can be loaded in the user’s browser with the web form instance. See these topics for details:

Prefilling fields is optional for web form instances that are embedded in a web application or displayed via a redirect to the Docusign platform. For remote web form instances that users access via an envelope email, some values must be supplied when creating instances. See Required user values for remote web form instances and Additional prefill requirements for remote web form instances for details.

Obtain information about fields that can be prefilled

Before creating a web form instance with prefilled values, your application can use a Configurations:getForm request or equivalent SDK method call to obtain information about fields in a web form configuration that can be prefilled, including the field names and types. Your application must reference the field names to supply prefill values when creating form instances. See Form field definitions for details about the field information that is available.

Supply prefill values in the request to create a web form instance

To prefill data in an Instances:createInstance request or an equivalent SDK method call that creates a web form instance, your application includes form field names and prefill values in the request’s formValues object.

Below is a sample Instances:createInstance request body that includes a formValues object. In each name/value pair in the formValues object, the name is the componentName from the form field definition. This value also appears as the API reference name in the Web Forms builder Properties panel.

{
  "clientUserId": "1234-xxxx-xxxx-efda",
    "formValues": {
      "name": "Sally Signer",
      "email": "sally.signer@email.com",
      "phone_num": {
        "countryCode": "55",
        "nationalNumber": "1133301000"
      },
      "salary": 121800.55,
      "birth_date": "1980-12-18",
      "marital_status": "single",
      "education": "advanced",
      "alerts": ["Funds_withdrawn","Account_info_changed"]
    },
  "expirationOffset": 720,
  "returnUrl": "https://developers.docusign.com"
}

To prefill a form field whose value will be saved as an envelope custom field, include the field’s componentName and a prefill value in the formValues object, just as you would with any other form field. For remote web form instances, any required envelope custom fields must be prefilled.

See the how-to guides for code examples that show how to prefill values.

Below is a list of form field types (identified by the componentType that appears in the form field definition in a Configurations:getForm response), a description of the value to supply in the formValues object, and an example of a prefill value. To learn how to obtain the allowed values for fields in which users make a selection, see Identify permitted values for dropdowns, radio buttons, and checkboxes.

`componentType`	Prefill value	Example
`TextBox`	Text	`"name": "Sally Signer"`
`Number`	A number. Use a period as the decimal separator in the request, even if the web form configuration specifies a comma as the decimal separator for the display format.	`"salary": 121800.55`
`Email`	An email address. The Web Forms API does not check whether the value is a valid email address. If an invalid email address is supplied in a request, the web form instance UI displays the message `Input must be a valid email address` below the field.	`"email": "sally.signer@email.com"`
`PhoneNumber`	A phone number defined by two properties: `countryCode`: The one-, two-, or three-digit dialing code for the country. If this value is omitted, the web form instance UI displays the default country code defined in the web form configuration. `nationalNumber`: The phone number’s area code and local number. The maximum length is 15 characters. Special characters such as spaces and hyphens can be included in prefill values. When a web form instance is submitted, special characters are removed from the `nationalNumber`, and only the digits are included in responses to requests that return submitted form values. Phone number fields are supported in standalone web form configurations, but not in template-based configurations. See Web form configuration type for more information about the two types.	"phone_num": { "countryCode": "55", "nationalNumber": "1133301000" }
`Date`	A date in the format `yyyy-mm-dd`. Use this format in the request even if a different date display format is selected in the web form configuration.	`"birth_date": "1980-12-18"`
`Select`	One of the permitted values for the dropdown as defined in the web form configuration. Case-sensitive.	`"marital_status": "single"`
`RadioButtonGroup`	One of the permitted values for the radio button group as defined in the web form configuration. Case-sensitive.	`"education": "advanced"`
`CheckboxGroup`	A string array containing one or more permitted values for the checkbox group as defined in the web form configuration. Case-sensitive.	`"alerts": ["Funds_withdrawn","Account_info_changed"]`

Note: Prefill values are not supported for FileInput (attachment) fields.

Prefill values override web form configuration defaults

A prefill value supplied in an Instances:createInstance request or equivalent SDK method call overrides any default value defined in the web form configuration. If your application does not prefill a value for a form field, the web form configuration default value, if one exists, will be displayed when the web form instance loads. Users can change default or prefilled form values before submitting a form instance, unless a field is defined in the web form configuration as read-only.

Prefill values for embedded web form instances with Docusign JS

As an alternative to prefilling values in an Instances:createInstance request or equivalent SDK method call, you can prefill them using the Docusign JS client SDK prefillValues property. Prefill values supplied through Docusign JS override those in an Instances:createInstance request, unless the prefill value is for a read-only field.

For read-only form fields, prefill values are applied as follows:

If supplied in an Instances:createInstance request, prefill values can be used to populate read-only fields.
If supplied with Docusign JS, prefill values cannot be used to populate read-only fields.

If you are using both the Web Forms API and Docusign JS, Docusign recommends prefilling via the Instances:createInstance request rather than Docusign JS because:

Prefilling through the API stores the form values on the Docusign platform. If you prefill using Docusign JS, form values are not stored on the Docusign platform until the user submits the form instance.
Passing user information through API requests is more secure than passing it through a client SDK.

You should only prefill with Docusign JS if you are not using the Web Forms API to create web form instances.

Next steps

See the how-to guides for code examples that include prefill values.
See Retrieve submitted web form instance values for information about obtaining user-entered values to write to your system of record.