Skip to navigation

How to send an envelope with extension app data verification fields

View as Markdown

This topic demonstrates how to set connected fields in a document and send an envelope with a data verification field. A connected field is a field that can be verified by a connected field or data verification extension in your account.

Connected fields validate data entered in a document against an external system of record before submission. This enables users to verify different data types, such as email addresses, phone numbers, social security numbers, and other supported data verification types. This example will walk you through configuring connected fields using the ConnectedFields:TabGroups endpoint response, constructing an envelope request body containing the information needed to include a connected field, and sending that envelope via email (remote sending).

Prerequisites

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

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_PATH1}A string value that forms the root of the URL required to make calls to the Connected Fields API. The base path value in the example code is set to target the developer environment at
https://<domain>/v1
Where <domain> is api-d.docusign.com for the developer environment and api.docusign.com for production.
{BASE_PATH2}A string value that forms the root of the URL required to make calls to the eSignature REST API. The base path value in the example code is set to target the developer environment at
https://<domain>/restapi
Where <domain> is demo.docusign.net for the developer environment and is the result of the GetUserInfo call in production.
Documents to be signedYou must provide at least one document to be signed. Documents used in this how-to:
{SIGNER_EMAIL}A string value for the email address where the signer will receive a notification of the signing request.
{SIGNER_NAME}A string value for the full name of the signer.

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.

Wondering which grant type suits your integration? 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 Connected Fields 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. Call the Connected Fields API

Make a GET request to the ConnectedFields:TabGroups endpoint to retrieve a list of the extension apps in your account that support data verification, including the definitions of their required verifiable fields, that you will need to create an envelope with connected fields. The GET request will return a JSON response that includes all extension app data in the user’s account. Here’s how you make the call, but make sure to substitute your API account ID for {ACCOUNT_ID}.

response=$(mktemp ./response-cf.XXXXXX)
Status=$(curl -w '%{http_code}' -i --ssl-no-revoke --request GET https://api-d.docusign.com/v1/accounts/${account_id}/connected-fields/tab-groups \
    "${Headers[@]}" \
    --output ${response})

Step 4. Extract the tab data from the response

Next, retrieve the required tab information from the response. Begin by creating a filter to identify apps capable of verifying a connected field: data verification extension apps and connected fields extension apps. Then prompt the user to choose an extension app. Finally, extract the tab values from the extensionData object of the selected app for use in Step 5, where they will be used to construct a connected field in the envelope definition. The tab values needed to construct the connected field are:

  • app_id: The unique ID of the extension app used to verify the field data.
  • extension_group_id: The ID of the group of extensions within the extension app.
  • publisher_name: The publisher of the extension app.
  • application_name: The name of the extension app.
  • action_name: The name of the verification action in the extension app.
  • action_contract: The template defining the verification action.
  • action_input_key: The key representing the input data required for verification. The value for this property determines the actual data type to be verified.
  • extension_name: The name of the extension.
  • extension_contract: The template defining the extension.
  • required_for_extension: A boolean value that indicates whether the field must pass verification before the signer can sign the document.
  • tab_label: The label assigned to the verification field in the document.
  • connection_key: The key used to identify the connection instance.
  • connection_value: The value of the connection instance.
extract_verify_info() {
    invoke_python "filter_by_verify_action('''$response''')"
}
prompt_user_choice() {
    local json_data="'''$1'''"
    unique_apps=()
    while IFS= read -r line; do
        unique_apps+=("$line")
    done < <(invoke_python "extract_unique_apps($json_data)")
    if [[ -z "$json_data" || "$json_data" == "[]" ]]; then
        echo "No data verification were found in the account. Please install a data verification app."
        echo ""
        echo "You can install a phone number verification extension app by copying the following link to your browser: "
        echo "https://apps.docusign.com/app-center/app/d16f398f-8b9a-4f94-b37c-af6f9c910c04"
        exit 1
    fi
    echo "Please select an app by entering a number:"
    for i in "${!unique_apps[@]}"; do
        echo "$((i+1)). ${unique_apps[$i]#* }"
    done
    read -p "Enter choice (1-${#unique_apps[@]}): " choice
    if [[ "$choice" =~ ^[1-${#unique_apps[@]}]$ ]]; then
        chosen_app_id="'${unique_apps[$((choice-1))]%% *}'"
        selected_data=$(invoke_python "filter_by_app_id('''$response''', $chosen_app_id)")
    else
        echo "Invalid choice. Exiting."
        exit 1
    fi
}
if [[ -z "$response" ]]; then
    echo "Error: response file variable not set."
    exit 1
fi
filtered_data=$(extract_verify_info)
if [[ -z "$filtered_data" || "$filtered_data" == "[]" ]]; then
    echo "No data verification were found in the account. Please install a data verification app."
    echo ""
    echo "You can install a phone number verification extension app by copying the following link to your browser: "
    echo "https://apps.docusign.com/app-center/app/d16f398f-8b9a-4f94-b37c-af6f9c910c04"
    exit 1
fi
prompt_user_choice "$filtered_data"

Step 5. Create the envelope definition

Next, create the envelope definition for the request body. If you’re using a Docusign SDK, you can prepare a compatible request body by creating an envelope definition using the included makeEnvelope method.

  • Set a signHere tab to collect signature information.
  • As an example for this how-to, create a text tab containing the extension app tab data extracted from Step 4. For your own apps, you may choose any verifiable tabs based on the results of your Connected Fields API call.
text_tabs=$(invoke_python "make_text_tabs_list('''$selected_data''', $chosen_app_id)")
printf \
'{
    "emailSubject": "Please sign this document",
    "documents": [
        {
            "documentBase64": "' > "$request_data"
            cat $doc1_base64 >> $request_data
            printf '",
            "name": "Lorem Ipsum",
            "fileExtension": "pdf",
            "documentId": "1"
        }
    ],
    "status": "sent",
    "recipients": {
        "signers": [
            {
                "email": "'"${SIGNER_EMAIL}"'",
                "name": "'"${SIGNER_NAME}"'",
                "recipientId": "1",
                "routingOrder": "1",
                "tabs": {
                    "signHereTabs": [
                        {
                            "anchorString": "/sn1/",
                            "anchorUnits": "pixels",
                            "anchorXOffset": "20",
                            "anchorYOffset": "10"
                        }
                    ],
                    "textTabs": ' >> "$request_data"
                        printf '%s' "$text_tabs" >> "$request_data"  # Ensure all tabs are added
                        printf '
                }
            }
        ]
    }
}' >> $request_data

Step 6. Create and send the envelope

Now that you have constructed your request body, make a POST request to the eSignature REST API Envelopes:create endpoint and include the request body to create the envelope.

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

response=$(mktemp /tmp/response-eg-001.XXXXXX)
echo ""
echo "Sending the envelope request to Docusign..."
base_path2="https://demo.docusign.net/restapi"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header "Content-Type: application/json" \
     --data-binary @${request_data} \
     --request POST ${base_path2}/v2.1/accounts/${account_id}/envelopes \
     --output $response
echo ""
echo "Response:"
cat $response
echo ""

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 email containing a signing link that they can use to open and electronically sign the document containing the connected fields using the Docusign mobile app or the Docusign website. After signing is complete, the recipient will receive a carbon copy (CC) of the email that includes all of the completed and signed documents.

Sample response
Response:
{"envelopeId":"537cb132-xxxx-xxxx-xxxx-634ac1ea51fe","uri":"/envelopes/537cb132-xxxx-xxxx-xxxx-634ac1ea51fe","statusDateTime":"2025-03-04T23:01:27.9530000Z","status":"sent"}
EnvelopeId: 537cb132-xxxx-xxxx-xxxx-634ac1ea51fe
Done. When the signer inputs the data to be verified, ensure the connection to the sender’s data verification extension app or connected fields extension app is active.

Next steps