Skip to navigation
Plan a Web Forms API integration

Identify web form instance users

View as Markdown

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.

Your application displays 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 that Docusign automatically generates after web form instance submission if the instance was created from a template-based 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 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. 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 and Limitations and Considerations for Web Forms 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, which is a required property for embedded web form instances in the Instances:createInstance API request and equivalent SDK 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 property in the recipients array. See Deliver remote web form 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:

An additional property of the Instances:createInstance request that can help your application identify web form instances is the 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 request, which returns information for a specific instance; the Instances:listInstances request, which returns information for all instances created from a web form configuration; and equivalent SDK 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)

{
    "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)

{
    "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 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 request, and their values will appear in certificates of completion:

These authentication properties can be used only for envelopes displayed in an embedded signing view. Embedded signing is used when the web form configuration’s Initiate signing session from email setting is not enabled. These properties are not supported with remote web form instances or web form instances created from standalone web form configurations.

Next steps