> 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

# Identify web form instance users

> Learn how a Web Forms API integration can uniquely identify users to prefill and retrieve their form instance data.

> **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.

Your application displays [web form instances](/docs/web-forms-api/web-forms-101/concepts#web-form-instances) to users, who complete two tasks for each form instance:

* Enter values in form fields and submit the form instance.
* Sign an [envelope](/docs/web-forms-api/web-forms-101/concepts#esignature-envelopes) that Docusign automatically generates after web form instance submission if the instance was created from a [template-based](/docs/web-forms-api/plan-integration/retrieve-configuration-details#web-form-configuration-type) web form configuration. The envelope typically includes values from the web form instance for the user to review.

**Note:** It is not required that all web form instance recipients complete both a form instance and an envelope. See the [Web Forms](https://support.docusign.com/s/document-item?bundleId=gmi1660583110357\&topicId=brp1660583998599.html) user documentation for details.

A web form instance and/or envelope may be routed to additional recipients as specified in the web form configuration. However, the way the web form instance is completed varies depending on its [delivery method](/docs/web-forms-api/web-forms-101/when-to-use-embedded-or-remote-delivery). Embedded web form instances can only be completed by a single user in the view that is either embedded in your web application or to which the user is redirected at Docusign. Additional users access the web form instance via a link in an envelope email. For remote web form instances, all users access the web form instance and/or envelope via an email. See [Build a Multiple-Recipient Web Form](https://support.docusign.com/s/document-item?bundleId=gmi1660583110357\&topicId=inc1745950777430.html) and [Limitations and Considerations for Web Forms](https://support.docusign.com/s/document-item?bundleId=gmi1660583110357\&topicId=hjv1686940185785.html) for more information.

Your application should use an identifier that is available in your backend system to identify the primary user who fills out a web form instance and/or envelope. The identifier can be an email address, account number, or any other unique value. For embedded instances, this identifier must be passed in the [clientUserId](/docs/web-forms-api/reference/webforms/instances/createinstance#schema__createinstancerequestbody_clientuserid), which is a required property for embedded web form instances in the [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) API request and equivalent [SDK](/docs/web-forms-api/sdks) method calls. This will associate that user identifier with the web form instance throughout the processing of the instance. The maximum length for a `clientUserId` value is 100 characters.

For remote web form instances, `clientUserId` is not a required property. Users can be identified and differentiated by the [roleName](/docs/web-forms-api/reference/webforms/instances/createinstance#schema__createinstancerequestbody_recipients_rolename) property in the [recipients](/docs/web-forms-api/reference/webforms/instances/createinstance#schema__createinstancerequestbody_recipients) array. See [Deliver remote web form instances to users](/docs/web-forms-api/plan-integration/deliver-remote-instances-to-users) for more details on defining remote web form instance participants.

You can use these identifiers in Web Forms API requests for the following purposes:

* Retrieve data from your system of record to [prefill web form instance fields](/docs/web-forms-api/plan-integration/prefill-instance-fields) with known information about the user
* Check the [status of web form instances](/docs/web-forms-api/plan-integration/track-instance-and-envelope-status#web-form-instance-status) associated with the user
* [Retrieve user-entered form values](/docs/web-forms-api/plan-integration/retrieve-submitted-values) to write data back to the system of record

An additional property of the `Instances:createInstance` request that can help your application identify web form instances is the [tags](/docs/web-forms-api/reference/webforms/instances/createinstance#schema__createinstancerequestbody_tags) object, which can be populated with an array of string values to associate metadata with an instance. The `tags` values are included in the responses to the [Instances:getInstance](/docs/web-forms-api/reference/webforms/instances/getinstance) request, which returns information for a specific instance; the [Instances:listInstances](/docs/web-forms-api/reference/webforms/instances/listinstances) request, which returns information for all instances created from a web form configuration; and equivalent [SDK](/docs/web-forms-api/sdks) method calls.

## Example requests

The following sample request bodies for the `Instances:createInstances` method demonstrate valid request structures for both embedded and remote web form instance scenarios.

**Embedded instance (single user with** `clientUserId`**)**

```json
{
    "clientUserId": "1234-5678-abcd-0201c",
    "tags": ["embedded-instance", "single-home-purchase"]
    "formValues": {
        "name": "Sally Signer",
        "email": "sally.signer@email.com"
    },
}
```

**Remote web form instance (multiple users with** `roleName`**)**

```json
{
    "sendOption": "now",
    "tags": ["remote-instance", "duplex-purchase"],
    "recipients": [
        {
            "roleName": "signer1",
            "name": "Sally Signer",
            "email": "sally.signer@email.com"
        },
        {
            "roleName": "signer2",
            "name": "Andrew Autograph",
            "email": "andrew.autograph@email.com"
        }
    ]
}
```

## Create a record of recipient authentication

For envelopes that are associated with web form instances, Docusign creates [certificates of completion](https://support.docusign.com/s/document-item?bundleId=oeq1643226594604\&topicId=gpa1578456339545.html) that list envelope details and events. Details about your web application's envelope recipient authentication method can be recorded in certificates of completion.

To record authentication information, include these properties in the [Instances:createInstance](/docs/web-forms-api/reference/webforms/instances/createinstance) request, and their values will appear in certificates of completion:

* [authenticationMethod](/docs/web-forms-api/reference/webforms/instances/createinstance#schema__createinstancerequestbody_authenticationmethod)
* [authenticationInstant](/docs/web-forms-api/reference/webforms/instances/createinstance#schema__createinstancerequestbody_authenticationinstant)
* [assertionId](/docs/web-forms-api/reference/webforms/instances/createinstance#schema__createinstancerequestbody_assertionid)
* [securityDomain](/docs/web-forms-api/reference/webforms/instances/createinstance#schema__createinstancerequestbody_securitydomain)

> **Note**
>
> These authentication properties can be used only for envelopes displayed in an [embedded signing](/docs/esign-rest-api/esign101/concepts/embedding) view. Embedded signing is used when the web form configuration's [Initiate signing session from email](https://support.docusign.com/s/document-item?bundleId=gmi1660583110357\&topicId=bna1674685085797.html) setting is not enabled. These properties are not supported with remote web form instances or web form instances created from [standalone](/docs/web-forms-api/plan-integration/retrieve-configuration-details#web-form-configuration-type) web form configurations.

## Next steps

* See [How to create and embed a web form instance](/docs/web-forms-api/how-to/create-embed-web-form-instance) for code examples that include a `clientUserId`.
* Learn [How to create and send a web form instance](/docs/web-forms-api/how-to/create-send-instance) with code examples that include the `recipients` array.
* See [Web form instance URLs](/docs/web-forms-api/plan-integration/instance-urls) for details about what makes web form instance URLs that your application displays to users unique and secure.