How to create and embed a web form instance

This topic demonstrates how to create a web form instance and embed it in your app’s HTML using the Docusign JS library. After the signer fills out the form, they will be directed to the embedded signing experience, where they will sign the document.

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:

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.

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. Set the clientUserId to a unique value that will be used to identify the user who will fill out the form.

Use the formValues object to prefill fields in the web form instance. The keys in this object correspond with 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. The expirationOffset parameter determines the amount of time in hours until the instance will expire. The form instance can be submitted and a corresponding envelope can be generated as long as the instance has not yet expired.

printf \
'{
    "clientUserId": "1234-5678-abcd-ijkl",
    "formValues": {
        "PhoneNumber": "555-555-5555",
        "Yes": ["Yes"],
        "Company": "Tally",
        "JobTitle": "Programmer Writer"
    },
    "expirationOffset": 24
}' >$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}.

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.

You will need to save the value of instanceToken to embed the form instance in your app’s HTML with the formValues provided previously in the API request body. Although the instance will not expire until the date and time described by the value of tokenExpirationDateTime, the instance token will expire after 5 minutes.

{
  "id": "8ed02b2f-xxxx-xxxx-xxxx-9c19a4243576",
  "formUrl": "https://demo.services.docusign.net/webforms-ux/v1.0/forms/52151720xxxxxxxxxxxxe0a33d1d2c5b",
  "instanceToken": "U2Fs….OAoA==",
  "tokenExpirationDateTime": "2023-12-07T23:30:03.124Z",
  "clientUserId": "1234-5678-abcd-ijkl",
  "formId": "5a62ae76-xxxx-xxxx-xxxx-fada34afe7eb",
  "accountId": "0820f9c5-xxxx-xxxx-xxxx-8a0df87f44aa",
  "tags": [],
  "status": "INITIATED",
  "instanceMetadata": {
    "expirationDateTime": "2024-05-05T23:25:03.124Z",
    "createdDateTime": "2023-12-07T23:25:03.124Z",
    "createdBy": {
      "userId": "8cb9aa3f-xxxx-xxxx-xxxx-f6ce2e16dad1",
      "userName": "Sally Signer"
    },
    "lastModifiedDateTime": "2023-12-07T23:25:03.124Z"
  }
}

Step 6. Embed the Web Form in your HTML

The best practice for embedding a web form instance in your app’s HTML is to use the Docusign JS library. The URL that will load the JS library is https://js-d.docusign.com/bundle.js for the developer environment and https://js.docusign.com/bundle.js for the production environment.

After the JS library has been loaded, construct the webFormsOptions object. The values in this object will define how the web form is rendered on the page. Set the value of the instanceToken parameter to the instance token returned in the response of the CreateInstance API call. The other optional parameters control various elements of the embedded form’s style. Use the hideProgressBar parameter to control whether the progress bar appears in the form. The minHeight parameter inside the iFrameStyles array determines the height of the iframe where the form is embedded.

Call docusign.webforms, passing the webFormsOptions object and the formUrl returned from the previous API call as parameters. Finally, mount that object in the HTML element of your choice. In this example it is mounted in a <div> with the id docusign.

-->
<script src=\"https://js.docusign.com/bundle.js\"></script>
<script>
async function loadWebform() {
  const { loadDocuSign } = window.DocuSign
  const docusign = await loadDocuSign('" . $integrationKey . "');
  const webFormOptions = {
    // Optional field that can prefill values in the form. This overrides the formValues field in the API request
    prefillValues: {},
    // Used with the runtime API workflow, for private webforms this is needed to render anything
    instanceToken: '" . $instanceToken . "',
    // Controls whether the progress bar is shown or not
    hideProgressBar: false,
    // These styles get passed directly to the iframe that is rendered
    iframeStyles: {
      minHeight: \"1500px\",
    },
    // Controls the auto resize behavior of the iframe
    autoResizeHeight: true
  };
  const webFormWidget = docusign.webforms({
    url: '" . $url . "',
    options: webFormOptions,
  });
  //Basic milestones in this workflow
  webFormWidget.on(\"ready\", (event) => {
    // event = { type: \"ready\" };
    console.log(\"debug form loaded\", event);
  });
  webFormWidget.on(\"submitted\", (event) => {
    // event = { type: \"submitted\", envelopeId: \"abcd1234\" };
    console.log(\"debug form submitted\", event);
  });
  webFormWidget.on(\"signingReady\", (event) => {
    // event = { type: \"submitted\", envelopeId: \"abcd1234\" };
    console.log(\"debug form signingReady\", event);
  });
  webFormWidget.on(\"sessionEnd\", (event) => {
    // event = { type: \"sessionEnd\", sessionEndType: \"sessionTimeout\" };
    // event = {
    //   type: 'sessionEnd',
    //   sessionEndType: \"signingResult\",
    //   signingResultType: \"signing_complete\",
    //   returnUrl: \"bigcorp.com\",
    //   envelopeId: \"abcd1234\",
    // };
    // event = { type: \"sessionEnd\", sessionEndType: \"remoteSigningInitiated\", envelopeId: \"abcd1234\" };
    console.log(\"debug form signingResult\", event);
  });
  //Less commonly used events
  webFormWidget.on(\"userActivity\", (event) => {
    // event = { type: \"userActivity\", activityType: \"click\" | \"keydown\" };
    console.log(\"debug form userActivity\", event);
  });
  webFormWidget.mount(\"#docusign\");
}
loadWebform();
</script>
<!--

Expected response

If you run this code example from our Quickstart or launcher projects, you should see the web form embedded in the results page of the example. After the signer fills out the form, they will be directed to the embedded signing experience.

Next steps

• Run this code example from our Quickstart or launcher projects: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.
• Learn more about Web form instance URLs.
• See Render embedded web form instances.
• See how to Go-Live with a completed app and find the base path for API calls in the production environment.