> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL.
>
> Documentation indexes by section:
> - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt
> - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt
> - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt
> - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt
>
> Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth
> Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks
>
> OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json
> MCP server: https://docusign.docs.buildwithfern.com/_mcp/server

# Prefill web form instance fields

> Learn how to populate web form instance fields with customer data from a system of record.

> **Note**
>
> The Web Forms API is available in all developer accounts, but only in certain production account plans. Contact [Docusign Support](https://support.docusign.com/s/?language=en_US) 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](/docs/web-forms-api/web-forms-101/concepts#web-form-instances) 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:

* [Obtain information about fields that can be prefilled](/docs/web-forms-api/plan-integration/prefill-instance-fields#obtain-information-about-fields-that-can-be-prefilled)
* [Supply prefill values in the request to create a web form instance](/docs/web-forms-api/plan-integration/prefill-instance-fields#supply-prefill-values-in-the-request-to-create-a-web-form-instance)
* [Prefill values override web form configuration defaults](/docs/web-forms-api/plan-integration/prefill-instance-fields#prefill-values-override-web-form-configuration-defaults)
* [Prefill values for embedded web form instances with Docusign JS](/docs/web-forms-api/plan-integration/prefill-instance-fields#prefill-values-for-embedded-web-form-instances-with-docusign-js)

> **Note**
>
> 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](/docs/web-forms-api/plan-integration/deliver-remote-instances-to-users#required-user-values-for-remote-web-form-instances)  and [Additional prefill requirements for remote web form instances](/docs/web-forms-api/plan-integration/deliver-remote-instances-to-users#additional-prefill-requirements-for-remote-web-form-instances) for details.

## Obtain information about fields that can be prefilled

Before creating a [web form instance](/docs/web-forms-api/web-forms-101/concepts#web-form-instances) with prefilled values, your application can use a [Configurations:getForm](/docs/web-forms-api/reference/webforms/configurations/getform) request or equivalent [SDK](/docs/web-forms-api/sdks) method call to obtain information about fields in a [web form configuration](/docs/web-forms-api/web-forms-101/concepts#web-form-configurations) 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](/docs/web-forms-api/plan-integration/prefill-instance-fields#supply-prefill-values-in-the-request-to-create-a-web-form-instance). See [Form field definitions](/docs/web-forms-api/plan-integration/retrieve-configuration-details#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](/docs/web-forms-api/reference/webforms/instances/createinstance) request or an equivalent [SDK](/docs/web-forms-api/sdks) method call that creates a [web form instance](/docs/web-forms-api/web-forms-101/concepts#web-form-instances), your application includes form field names and prefill values in the request's [formValues](/docs/web-forms-api/reference/webforms/instances/createinstance#schema__createinstancerequestbody_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](/docs/web-forms-api/plan-integration/retrieve-configuration-details#form-field-definitions).  This value also appears as the **API reference name** in the Web Forms builder [Properties panel](https://support.docusign.com/s/document-item?bundleId=gmi1660583110357\&topicId=wor1676501633875.html).

```text
{
  "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](/docs/web-forms-api/plan-integration/retrieve-configuration-details#envelope-custom-fields), 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](/docs/web-forms-api/plan-integration/deliver-remote-instances-to-users), any required envelope custom fields must be prefilled.

> **Note**
>
> See the [how-to guides](/docs/web-forms-api/how-to) 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](/docs/web-forms-api/plan-integration/retrieve-configuration-details#form-field-definitions) in a [Configurations:getForm](/docs/web-forms-api/reference/webforms/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](/docs/web-forms-api/plan-integration/retrieve-configuration-details#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](https://support.docusign.com/s/document-item?bundleId=gmi1660583110357\&topicId=zxq1673475126383.html) 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](/docs/web-forms-api/plan-integration/retrieve-configuration-details#web-form-configuration-type) for more information about the two types. | <pre />                                                |
| `Date`             | A date in the format `yyyy-mm-dd`. Use this format in the request even if a different [date display format](https://support.docusign.com/s/document-item?bundleId=gmi1660583110357\&topicId=hsg1673483253591.html) 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](/docs/web-forms-api/reference/webforms/instances/createinstance) request or equivalent [SDK](/docs/web-forms-api/sdks) method call overrides any default value defined in the [web form configuration](/docs/web-forms-api/web-forms-101/concepts#web-form-configurations). 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](/docs/web-forms-api/web-forms-101/concepts#web-form-instances) 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](/docs/web-forms-api/reference/webforms/instances/createinstance) request or equivalent SDK method call, you can prefill them using the [Docusign JS](/docs/web-forms-api/plan-integration/render-instances#use-docusign-js-to-render-web-form-instance-urls) 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](/docs/web-forms-api/how-to) for code examples that include prefill values.
* See [Retrieve submitted web form instance values](/docs/web-forms-api/plan-integration/retrieve-submitted-values) for information about obtaining user-entered values to write to your system of record.