> 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 # List web form instances GET https://apps-d.docusign.com/api/webforms/v1.1/accounts/{accountId}/forms/{formId}/instances 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. Retrieves all the instances of a given web form configuration. [Required authentication scopes](/docs/web-forms-api/plan-integration/authentication/): `signature`, `webforms_instance_read`. Reference: https://developers.docusign.com/docs/web-forms-api/reference/webforms/instances/listinstances ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, 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 form configuration. ### Query parameters - `client_user_id` (string, optional) — A unique identifier for a user from the client's system. This value can be anything your backend system would use to track individual form instances, such as employee IDs, email addresses, or surrogate key values. ## Response ### 200 List of all Web Form Instances with associated metadata. - `items` (list of WebFormInstance, optional) — Array of web form instance items. ## Errors ### 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 ### WebFormInstance An object that represents an instance of a web form configuration. A web form instance is displayed in a browser for a user to fill out and submit. - `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. ### 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) ### 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 **Response** ```json { "items": [ { "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" } ] } ] } ```