> 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

# Create web form instance

POST https://apps-d.docusign.com/api/webforms/v1.1/accounts/{accountId}/forms/{formId}/instances
Content-Type: application/json

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.

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](/docs/web-forms-api/plan-integration/authentication/): `signature`, `webforms_instance_write`.

### Related topics

* [How to create and embed a web form instance](/docs/web-forms-api/how-to/create-embed-web-form-instance/)

Reference: https://developers.docusign.com/docs/web-forms-api/reference/webforms/instances/createinstance

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Servers

- `https://apps-d.docusign.com/api/webforms` (Demo, default)
- `https://apps.docusign.com/api/webforms` (Production)

## Request

### Path parameters

- `accountId` (string, required) — The ID of the account to which the web form belongs.
- `formId` (string, required) — The ID of the web form configuration.

### Body (application/json)

This endpoint expects a CreateInstanceRequestBody.

- `clientUserId` (string, required) — 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.
- `formValues` (map from string to any, optional) — 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](/docs/web-forms-api/plan-integration/retrieve-configuration-details/#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](/docs/web-forms-api/plan-integration/prefill-instance-fields/#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](/docs/web-forms-api/plan-integration/deliver-remote-instances-to-users/) for more information.
- `authenticationInstant` (string, optional) — A sender-generated value that indicates the date and time that the signer was authenticated.
- `authenticationMethod` (enum, optional) — A value that most closely matches the technique your application used to authenticate the recipient / signer.
  - Allowed values: `Biometric`, `Email`, `HTTPBasicAuth`, `Kerberos`, `KnowledgeBasedAuth`, `None`, `PaperDocuments`, `Password`, `RSASecureID`, `SingleSignOn_CASiteminder`, `SingleSignOn_InfoCard`, `SingleSignOn_MicrosoftActiveDirectory`, `SingleSignOn_Other`, `SingleSignOn_Passport`, `SingleSignOn_SAML`, `Smartcard`, `SSLMutualAuth`, `X509Certificate`
- `assertionId` (string, optional) — A unique identifier of the authentication event executed by the client application.
- `securityDomain` (string, optional) — The domain in which the user authenticated.
- `returnUrl` (string, optional) — The url to which the user is redirected after the signing is completed
- `expirationOffset` (long, optional) — 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).
- `sendOption` (enum, optional)
  - Allowed values: `now`
- `brandId` (string, optional) — Brand Id for web form
- `recipients` (list of CreateInstanceRequestBodyRecipientsItems, optional) — 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](/docs/web-forms-api/web-forms-101/concepts/#web-form-templates), a `phoneNumber` is required as well. See [Deliver remote web form instances to users](/docs/web-forms-api/plan-integration/deliver-remote-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.
- `tags` (list of string, optional) — 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

### 200

Web Form Instance with metadata

- `id` (string, required) — Unique identifier for a webform instance that is consistent until its expiration
- `formUrl` (string, optional) — The instance url which can be rendered by the user
- `instanceToken` (string, optional) — 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
- `tokenExpirationDateTime` (datetime, optional) — The DateTime after which the token is expired and form instance is inaccessible.
- `formId` (string, optional) — Unique identifier for a webform entity that is consistent for it's lifetime
- `accountId` (string, optional) — Account identifier in which the webform resides
- `clientUserId` (string, optional) — 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.
- `tags` (list of string, optional) — Metadata to help your application identify the web form instance. Example: `["Client A", "Agreement Category B"]`
- `status` (enum, optional) — The status of the form instance
  - Allowed values: `INITIATED`, `IN_PROGRESS`, `SUBMITTED`, `EXPIRED`, `FAILED`
- `envelopes` (list of WebFormInstanceEnvelopesItems, optional) — 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](/docs/web-forms-api/web-forms-101/instance-processing/#instance-processing-template-based-web-form-configurations) 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](/docs/web-forms-api/plan-integration/deliver-remote-instances-to-users/). For this flow, an envelope is generated when the instance is created. Web form instances generated from [standalone](/docs/web-forms-api/web-forms-101/instance-processing/#instance-processing-standalone-web-form-configurations) configurations do not have envelopes associated with them.
- `instanceMetadata` (WebFormInstanceMetadata, optional) — Metadata associated with the web form instance.
- `formValues` (map from string to any, optional) — 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](/docs/web-forms-api/plan-integration/retrieve-configuration-details/#form-field-definitions) for more information. See [Request that retrieves web form instance values](/docs/web-forms-api/plan-integration/retrieve-submitted-values/#request-that-retrieves-web-form-instance-values) for an example of a `formValues` object returned by this request.
- `brandId` (string, optional) — Brand Id for web form
- `recipients` (list of WebFormInstanceRecipientsItems, optional) — This object contains information about the users who fill out a web form instance and its associated envelope. If the [web form template](/docs/web-forms-api/web-forms-101/concepts/#web-form-templates) 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

The form instance cannot be created, possibly due to validation failure.

- `errorCode` (string, optional) — A code indicating what error occurred. Possible values: * 400: Bad request * 401: Authentication information is missing or invalid * 403: Requestor not authorized * 404: Resource not found * 500: Internal server error * 503: Service is temporarily unavailable
- `message` (string, optional) — A human-readable description of the error.

### 401 Unauthorized Error

The authentication information is either missing or invalid

- `errorCode` (string, optional) — A code indicating what error occurred. Possible values: * 400: Bad request * 401: Authentication information is missing or invalid * 403: Requestor not authorized * 404: Resource not found * 500: Internal server error * 503: Service is temporarily unavailable
- `message` (string, optional) — A human-readable description of the error.

### 403 Forbidden Error

The requestor is not authorized

- `errorCode` (string, optional) — A code indicating what error occurred. Possible values: * 400: Bad request * 401: Authentication information is missing or invalid * 403: Requestor not authorized * 404: Resource not found * 500: Internal server error * 503: Service is temporarily unavailable
- `message` (string, optional) — A human-readable description of the error.

### 404 Not Found Error

The requested resource is not found

- `errorCode` (string, optional) — A code indicating what error occurred. Possible values: * 400: Bad request * 401: Authentication information is missing or invalid * 403: Requestor not authorized * 404: Resource not found * 500: Internal server error * 503: Service is temporarily unavailable
- `message` (string, optional) — A human-readable description of the error.

### 500 Internal Server Error

The service encountered an unexpected condition that prevented it from fulfilling the request

- `errorCode` (string, optional) — A code indicating what error occurred. Possible values: * 400: Bad request * 401: Authentication information is missing or invalid * 403: Requestor not authorized * 404: Resource not found * 500: Internal server error * 503: Service is temporarily unavailable
- `message` (string, optional) — A human-readable description of the error.

### 503 Service Unavailable Error

service is temporarily unavailable

- `errorCode` (string, optional) — A code indicating what error occurred. Possible values: * 400: Bad request * 401: Authentication information is missing or invalid * 403: Requestor not authorized * 404: Resource not found * 500: Internal server error * 503: Service is temporarily unavailable
- `message` (string, optional) — A human-readable description of the error.

## Types

### CreateInstanceRequestBodyRecipientsItems

- `roleName` (string, required)
- `name` (string, required)
- `email` (string, required)
- `phoneNumber` (PhoneNumber, optional) — This object defines a phone number to which Docusign sends an access code. If a phone number is needed for identity verification that is enabled for a user's role in the [web form template](/docs/web-forms-api/web-forms-101/concepts/#web-form-templates), the user must enter a code to access the web form instance or envelope. This object is **required** when identity verification is enabled and a phone number is needed; otherwise, it is **optional**.

### WebFormInstanceEnvelopesItems

- `id` (string, optional) — Envelope Id
- `createdDateTime` (datetime, optional) — The dateTime when an envelope is created.

### WebFormInstanceMetadata

Metadata associated with the web form instance.

- `expirationDateTime` (datetime, required) — The DateTime after which the webform instance is inaccessible.
- `createdDateTime` (datetime, required) — The DateTime when the webform instance is created.
- `createdBy` (WebFormUserInfo, required) — A DocuSign user within the account associated with the form.
- `lastModifiedDateTime` (datetime, optional) — The DateTime when the webform instance is last modified.
- `lastModifiedBy` (WebFormUserInfo, optional) — A DocuSign user within the account associated with the form.
- `submittedDateTime` (datetime, optional)
- `instanceSource` (enum, optional) — The method by which the form instance is created.
  - Allowed values: `PUBLIC_URL`, `API_EMBEDDED`, `API_REMOTE`, `UI_REMOTE`, `WORKFLOW`

### WebFormInstanceRecipientsItems

- `recipientViewId` (string, optional)
- `instanceRecipientStatus` (enum, optional)
  - Allowed values: `INITIATED`, `IN_PROGRESS`, `SUBMITTED`
- `roleName` (string, optional)

### PhoneNumber

This object defines a phone number to which Docusign sends an access code. If a phone number is needed for identity verification that is enabled for a user's role in the [web form template](/docs/web-forms-api/web-forms-101/concepts/#web-form-templates), the user must enter a code to access the web form instance or envelope. This object is **required** when identity verification is enabled and a phone number is needed; otherwise, it is **optional**.

- `countryCode` (string, optional) — The one-, two-, or three-digit dialing code for the country.
- `nationalNumber` (string, optional) — The phone number’s area code and local number. The maximum length is 15 characters.

### WebFormUserInfo

A DocuSign user within the account associated with the form.

- `userId` (string, optional) — DocuSign user identifier
- `userName` (string, optional) — The user's name that will be displayed in the UI. The maximum length is 150 characters.

## Examples

**Request**

```json
{
  "clientUserId": "customer_id@domain.com"
}
```

**Response**

```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "formUrl": "https://webforms-ux/v1.0/forms/82356c8f286b4e4df592af7d0984f51d",
  "instanceToken": "string",
  "tokenExpirationDateTime": "2024-01-15T09:30:00Z",
  "formId": "00000000-0000-0000-0000-000000000000",
  "accountId": "00000000-0000-0000-0000-000000000000",
  "clientUserId": "customer_id@domain.com",
  "tags": [
    "loan_application",
    "finance_dept"
  ],
  "status": "INITIATED",
  "envelopes": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "createdDateTime": "2024-01-15T09:30:00Z"
    }
  ],
  "instanceMetadata": {
    "expirationDateTime": "2023-08-16T10:30:00Z",
    "createdDateTime": "2023-08-15T10:30:00Z",
    "createdBy": {
      "userId": "00000000-0000-0000-0000-000000000000",
      "userName": "DocuSign User"
    },
    "lastModifiedDateTime": "2023-08-15T20:30:00Z",
    "lastModifiedBy": {
      "userId": "00000000-0000-0000-0000-000000000000",
      "userName": "DocuSign User"
    }
  },
  "formValues": {
    "Checkbox_hobbies": [
      "singing",
      "dancing"
    ],
    "Date_birth": "2020-01-01",
    "Email_primary": "example@example.com",
    "ID_card_attachment": {
      "documentName": "id_card.pdf"
    },
    "Number_age": 52,
    "Radio_Gender": "Female",
    "Select_state": "California",
    "Textbox_Name": "First Last"
  },
  "brandId": "00000000-0000-0000-0000-000000000000",
  "recipients": [
    {
      "recipientViewId": "00000000-0000-0000-0000-000000000000",
      "instanceRecipientStatus": "SUBMITTED",
      "roleName": "Applicant"
    }
  ]
}
```