Skip to navigation
How-to guides

How to create and send a web form instance

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.

This topic demonstrates how to create a web form instance and send it to a recipient by email (remote web form instance delivery). After the recipient fills out the form, they will sign an envelope.

Run this code example from our Quickstart or launcher projects: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.

Prerequisites

Web form configurations cannot be created through the API. Therefore, before you create a web form instance, you must create and activate a web form configuration in your Docusign account. If you are running this from our Quickstart or launcher projects, you will receive instructions for how to create a web form configuration by uploading a compatible JSON configuration file.

If you choose not to use our launcher projects, you can follow along with this guide by creating a web form configuration with the name “Web Form Example Template” and adding the following fields:

  • A text field with the API reference name “PhoneNumber”
  • A text field with the API reference name “Company”
  • A text field with the API reference name “JobTitle”
  • A checkbox with the API reference name “Yes”

Required data

Running the code in this how-to requires this data:

Data elementDescription
{API_ACCOUNT_ID}A GUID value that identifies your account. This value is automatically generated by Docusign for any account you create. Copy the value from the API Account ID field on the Apps and Keys page.
{BASE_PATH}A string value that forms the root of the URL required to make API calls. The base path value in the example code is set to target the developer environment at
https://<domain>/webforms/v1.1
Where <domain> is apps-d.docusign.com/api for the developer environment.

Step 1. Obtain your OAuth Token

To make the API calls shown in this how-to, you need a valid OAuth access token. Docusign supports access tokens for three different recommended OAuth grant types: Public Authorization Code Grant, Confidential Authorization Code Grant, and JSON Web Token (JWT) Grant. Choose the OAuth grant type appropriate for your scenario.

Web Forms OAuth access tokens are the same ones used for our eSignature REST API, although you must request one or more Web Forms scopes to call the Web Forms API. The API calls made in this how-to require that you request the eSignature REST API signature scope and Docusign Web Forms–specific scopes webforms_instance_read, webforms_instance_write, and webforms_read when obtaining your access token.

See Authentication for guidance on your options to get an OAuth token.

Three icons that represent the three methods a user can use to obtain an OAuth token: JSON Web Token (JWT), Public Authorization Code Grant (ACG), and Confidential Authorization Code grant

Step 2. Construct your API headers

After you have a valid OAuth access token, you are ready to construct the API headers that you will pass to the API call. Construct your headers like this, but make sure to substitute your valid OAuth access token for {ACCESS_TOKEN}.

declare -a Headers=('--header' "Authorization: Bearer ${ACCESS_TOKEN}" \
            '--header' "Accept: application/json" \
			'--header' "Content-Type: application/json")

Step 3. Get the form ID

First, get the ID of the web form configuration of which you will be creating an instance. Call the Configurations:listForms endpoint, passing the value Web Form Example Template to the search query parameter. This query parameter filters the results of the API call so that only web form configurations with the name “Web Form Example Template” are returned. Save the value of id from the response so that it can be used in Step 5.

response=$(mktemp /tmp/response-cw.XXXXXX)
Status=$(curl -w '%{http_code}' --request GET ${base_path}/accounts/${ACCOUNT_ID}/forms?search=Web%20Form%20Example%20Template \
    "${Headers[@]}" \
    --output ${response})
FORM_ID=$(cat $response | sed 's/,/\n/g' | grep id | sed 's/.*\"id\":\"//g' | sed 's/\".*//g')

Step 4. Construct the request body

Next, create the request body.

Use the formValues object to prefill the fields in the web form instance. The keys in this object correspond to the API reference names of the fields in the web form configuration. You can find and edit these API reference names in the Properties tab in the web forms UI.

When sendOption is set to now, the request must supply required information for each recipient. In this example, the information is supplied in a recipients array, where each recipient object contains a roleName, name, and email. As an alternative, required user information can be supplied in the formValues object. See Deliver remote web form instances to users for details about this option.

printf \
'{
    "sendOption": "now",
    "formValues": {
        "PhoneNumber": "555-555-5555",
        "Yes": ["Yes"],
        "Company": "Tally",
        "JobTitle": "Programmer Writer"
    },
    "recipients": [
        {
            "roleName": "signer",
            "name": "'"${SIGNER_NAME}"'",
            "email": "'"${SIGNER_EMAIL}"'"
        }
    ]
}' >$request_data

Step 5. Call the Web Forms API

Now that you have constructed your API headers and request body, make a POST request to the Instances:createInstance method and include the request body to create a new instance of the web form.

Here’s how you make the call, but make sure to substitute your API account ID for {ACCOUNT_ID} and form ID for {FORM_ID}.

View the source code for this how-to on GitHub: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.

Status=$(curl -w '%{http_code}' -i --request POST ${base_path}/accounts/${ACCOUNT_ID}/forms/${FORM_ID}/instances \
    "${Headers[@]}" \
    --data-binary @${request_data} \
    --output ${response})

Expected response

If you run this code example from our Quickstart or launcher projects, you should see a JSON response similar to the code shown.

In addition, the signer receives an envelope email containing a link. On selecting the link, the user is routed to the Docusign platform, which displays an envelope with an embedded web form instance. The user fills out the web form instance and then electronically signs an envelope containing fields prefilled with the information entered in the web form. After the signing process is finished, an email is sent to the recipient, containing a copy of the signed envelope.

Sample response
{
    "id": "8be973f9-xxxx-xxxx-xxxx-015e206c8db8",
    "formId": "c669eb44-xxxx-xxxx-xxxx-1d4deb51db4d",
    "accountId": "85443307-xxxx-xxxx-xxxx-87671e153075",
    "tags": [],
    "status": "INITIATED",
    "instanceMetadata": {
        "expirationDateTime": "2025-09-19T00:18:20.781Z",
        "createdDateTime": "2025-08-20T00:18:20.781Z",
        "createdBy": {
            "userId": "53d98270-xxxx-xxxx-xxxx-6d080391b538",
            "userName": "Sally Sender"
        },
        "instanceSource": "API_REMOTE",
        "lastModifiedDateTime": "2025-08-20T00:18:20.781Z",
        "lastModifiedBy": {
            "userId": "53d98270-xxxx-xxxx-xxxx-6d080391b538",
            "userName": "Sally Sender"
        }
    },
    "webFormRecipients": [
        {
            "recipientViewId": "41f3109b-xxxx-xxxx-xxxx-eac994ad0988",
            "instanceRecipientStatus": "INITIATED",
            "roleName": "signer"
        }
    ],
    "envelopes": [
        {
            "id": "5ecac73f-xxxx-xxxx-xxxx-37d7dea5acba",
            "createdDateTime": "2025-08-20T00:18:22.667Z"
        }
    ]
}

Next steps