Deliver remote web form instances to users

A Web Forms API integration launches an Instances:createInstance request or equivalent SDK method call to create a web form instance from a web form configuration. If the request properties indicate that a remote web form instance is to be created, Docusign sends an envelope email to each user defined in the request. Depending on the web form configuration, the link in the email may do either of the following:

• Take the user to a web form instance that is embedded in an envelope. After the user populates and submits the form instance, they sign and complete the envelope.
• Take the user directly to the envelope, if the web form configuration does not specify that web form instance submission is required for the user.

Note: Instead of delivering web form instances to users, your integration can embed form instances in your website or redirect users to form instance URLs. See When to use embedded or remote web form instance delivery for details.

Roles determine web form instance behavior for users

Roles are defined in a web form configuration. For each role, several options can be set:

• Whether users associated with the role fill out a web form instance and envelope, or just the envelope

• The order in which users in each role complete the web form instance and/or envelope. If the configuration specifies a routing order with multiple steps, a user will not receive an envelope email until the users at previous steps in the routing order have completed the web form instance and/or envelope.

  Note: When your integration sends an Instances:createInstance request, the envelope email is immediately sent to all users whose role is assigned to the first step of the routing order.

• The web form instance view that will be displayed to users in that role. When a remote web form instance is delivered to more than one user, each user sees a different view of the instance with form fields that are relevant only to them.

• Which tabs the user populates on the eSignature envelope that each user completes. Although all users who fill out a web form instance see the same envelope, they complete different tabs on the envelope. Tab assignments for each role are configured in the web form template.

• Whether or not a user is required to verify their identity before proceeding to a web form instance or envelope. Identity verification can be enabled in the web form template. See Add Phone Authentication for a Recipient for more information.

See Build a Multiple-Recipient Web Form for details on how to define a web form configuration with multiple roles and set options associated with each role.

Requirements to create remote web form instances

To create remote web form instances, your Web Forms API integration must:

1. Ensure that it creates instances from a web form configuration that supports remote web form instances. See Web form configuration support for remote web form instances for information about how to verify remote instance support.
2. In the Instances:createInstance request or equivalent SDK method call, include this property to designate the instance as remote: "sendOption": "now"
3. Supply required values for users who will receive envelope emails. See the next sections for details.

Required user values for remote web form instances

For remote web form instances, the Instances:createInstance request must include values that define each user who will receive the envelope email. User values are supplied as follows:

• At minimum, user values must be provided for the primary recipient role in the web form configuration. A primary recipient role is required for every configuration, and users in that role fill out both a web form instance and envelope.
• User values for additional recipient roles can be omitted from the Instances:createInstance request. Those recipients will be removed from the envelope process unless hard-coded user values already exist on the web form template.

The next sections describe user values that are supplied in an Instances:createInstance request.

Name

A name consists of the user’s first and last name. This value appears in the envelope email. The API integration’s business logic should supply the name for each user.

Email address

This is the email address to which the envelope email will be sent. The API integration’s business logic should supply the email address for each user.

Phone number

If a role requires a phone number as part of identity verification, the Instances:createInstance request must supply a phone number for a user with that role. When the user selects the link in the envelope email, they are routed to a page where they enter the access code sent to them via SMS or phone call. On successful identity verification, the user proceeds to the web form instance or envelope. See Add Phone Authentication for a Recipient for information about how to enable identity verification in a template.

Role name

Note: If an Instances:createInstance request supplies recipient information in the formValues object instead of the recipients object, role names are not needed in the request.

A role name associates an envelope email recipient with a web form configuration role. You can obtain role names for a configuration from the roleName property in the Configurations:getForm response’s recipientInfoMap object. You can also obtain a configuration’s role names by viewing the web form configuration in the Web Forms builder.

Options to supply required user values

User information can be supplied in one of two objects in the Instances:createInstance request:

• recipients
• formValues

Supply user values in the recipients object

The Instances:createInstance request’s recipients object can supply the required role name, name, email address, and phone number for each user. For example:

{
  "sendOption": "now",
  "recipients": [
    {
      "roleName": "signer1",
      "name": "Sally Signer",
      "email": "sally.signer@email.com",
      "phoneNumber": {
        "countryCode": "1",
        "nationalNumber": "4155551212"
      }
    },
    {
      "roleName": "signer2",
      "name": "Steven Signer",
      "email": "steven.signer@email.com",
      "phoneNumber": {
        "countryCode": "1",
        "nationalNumber": "2065551212"
      }
    }
  ]
}

Supply user values in the formValues object

The Instances:createInstance request’s formValues object can be used to define each recipient’s name, email address, and phone number. If you define these values in the formValues object, you can omit the recipients object from the Instances:createInstance request.

To supply these values in the formValues object, include key/value pairs for each recipient’s name, email address, and phone number. The key in each key/value pair is the componentName for the field that is returned in a Configurations:getForm response. These fields must be mapped to recipients on the web form template as part of the web form configuration. See Form field definitions for details.

For example:

{
  "sendOption": "now",
  "formValues": {
    "account_owner_name": "Sally Signer",
    "account_owner_email": "sally.signer@email.com",
    "account_owner_phone": {
      "countryCode": "1",
      "nationalNumber": "4155551212"
    }
    "account_approver_name": "Steven Signer",
    "account_approver_email": "steven.signer@email.com",
    "account_approver_phone": {
      "countryCode": "1",
      "nationalNumber": "2065551212"
    }
  }
}

Note: If a name, email address, or phone number for a remote web form instance recipient is populated in both the recipients object and the formValues object, the values must match. If they do not, Docusign returns an error in response to the Instances:createInstance request.

Additional prefill requirements for remote web form instances

These additional requirements for prefilling values apply when creating a remote web form instance:

• If the web form instance includes required envelope custom fields, their values must be prefilled.
• If the web form configuration has rules that include or omit documents from the envelope based on the value of web form fields, those field values must be prefilled. See Add Conditional Rules to a Web Form for more information.

Next steps

• Get an overview of the remote web form instance flow in Web form instance processing.
• See How to create and send a web form instance for code examples that demonstrate the creation of a remote web form instance.