Connected Fields API concepts

The Connected Fields API enables you to perform real-time programmatic custom data verification for values in your eSignature envelopes. The API provides an endpoint, TabInfo:GetConnectedFieldsTabGroups, which returns the full definitions of your connected fields: every field type whose data can be verified using one of your account’s Extension apps.

Your app can call this endpoint to get the types of data that can be verified, then map these connected fields to your envelope fields (also known as Tabs) before you send it. When your recipient enters data in these fields, the extension apps associated with the connected field will verify that data in real time and display a response.

For example, you can verify user-supplied values in an eSignature envelope to authorize a transfer in a financial account. Each envelope value can be mapped to a property in your system of record. When a user completes the required envelope fields, Docusign sends your system a verification request that includes the values. Your system can apply its verification logic and return the result in its response to Docusign, which then displays the result to the user.

To verify custom data programmatically with the Connected Fields API, you must first create a Connected fields or data verification extension app. If your account has neither extension, the TabInfo:GetConnectedFieldsTabGroups method will not return any data types.

For connected fields extension apps, you must:

• Implement the data verification rules that your system will enforce on the connected fields (the field types that can be verified by one or more of the extensions defined for your account)
• Define mappings for your data types to Docusign data types
• Install and connect a connected fields or data verification extension
• Create the messages that will be shown for success or when error conditions are found.

See Transform logic for details on how to map your data types to the Concerto format that Docusign uses. See External system logic to return data model with verification markers and External system logic to process verification requests for guidance on setting up your system to work with a connected fields extension app.

To verify supported generic fields, you must install and connect a data verification extension app. See Install Docusign Apps for Data Verification for details.

Once your connected fields or data verification extension app and your external system logic are implemented, send connected field data to be verified programmatically using the following steps:

1. Call the Connected Fields API endpoint

Call the Connected Fields API endpoint, TabInfo:GetConnectedFieldsTabGroups. This method returns the full models of all of your connected fields (the data structures used by your system of record and mapped in your connected fields extension app).

Note that, unlike the Connected Fields UI, the Connected Fields API endpoint returns only fields that are either mandatory or have the IsRequiredForVerifyingType decorators.

2. Extract the data from the response

Extract the data from this response needed to create corresponding fields (also called Tabs) in your envelope. This code shows example properties returned for both generic fields (used by data verification extensions) and custom fields (used by connected fields extensions).

{
    "appId": "ae832a12-xxxx-xxxx-xxxx-aa85f5d64159",
    "tabs": [
      {
        "extensionData": {
          "extensionGroupId": "2018f518-xxxx-xxxx-xxxx-fa039570f643",
          "actionInputKey": "accountNumber",
          "publisherName": "John Doe",
          "applicationName": "File Archive and Verification",
          "actionContract": "Contracts.Actions.Verify.Version1.BankAccountOwner",
          "extensionName": "My Bank Account Owner Verification Extension",
          "actionName": "My Bank Account Owner Verification Action",
          "extensionContract": "Contracts.Extensions.Verify.Version1.BankAccountOwner",
          "extensionPolicy": "None",
          "requiredForExtension": true,
          "connectionInstances": [
            {
              "connectionKey": "6e2b94da-xxxx-xxxx-xxxx-7265e8fc0797",
              "connectionValue": "authentication 4"
            }
          ]
        },
        "validationMessage": "Account number may only contain letters and numbers",
        "validationPattern": "^[0-9a-zA-Z]+$",
        "tabType": "text",
        "tabLabel": "com.docusign.extensibilityplatform.action.verify.bankaccountowner@0.4.0.VerifyBankAccountOwnerInput[0].accountNumber"
      },

3. Create the envelope definition

Create the envelope definition. When defining your fields, provide this type and extension app data in a tab’s extensionData property to mark it as a connected field whose values will be verified.

{
    "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": [
                        {
                            "requireInitialOnSharedChange": false,
                            "requireAll": false,
                            "name": "'"${application_name}"'",
                            "required": true,
                            "locked": false,
                            "disableAutoSize": false,
                            "maxLength": 4000,
                            "tabLabel": "'"${tab_label}"'",
                            "font": "lucidaconsole",
                            "fontColor": "black",
                            "fontSize": "size9",
                            "documentId": "1",
                            "recipientId": "1",
                            "pageNumber": "1",
                            "xPosition": "273",
                            "yPosition": "191",
                            "width": "84",
                            "height": "22",
                            "templateRequired": false,
                            "tabType": "text",
                            "extensionData": {
                                "extensionGroupId": "'"${extension_group_id}"'",
                                "publisherName": "'"${publisher_name}"'",
                                "applicationId": "'"${app_id}"'",
                                "applicationName": "'"${application_name}"'",
                                "actionName": "'"${action_name}"'",
                                "actionContract": "'"${action_contract}"'",
                                "extensionName": "'"${extension_name}"'",
                                "extensionContract": "'"${extension_contract}"'",
                                "requiredForExtension": "'"${required_for_extension}"'",
                                "actionInputKey": "'"${action_input_key}"'",
                                "extensionPolicy": "None",
                                "connectionInstances": [
                                    {
                                        "connectionKey": "'"${connection_key}"'",
                                        "connectionValue": "'"${connection_value}"'"
                                    }
                                ]
                            }
                        }
                    ]
                }
            }
        ]
    }
}

4. Verify data

When the recipient enters data into a tab marked as a connected field, that data will be sent to an external system for verification (or to your system of record, for custom field verification). For custom field verifications, these values will be evaluated against the verification rules that you have defined for that data type, and the success or failure message that you have defined for its category will be shown.

See How to send an envelope with extension app data verification fields for a detailed walkthrough on how to programmatically send an envelope that verifies custom data, or Connected fields in Docusign envelopes for an overview of the process to manually send an envelope using the eSignature user interface.

Note: Connected fields are not currently supported in Docusign Maestro.

The following sections describe the objects and key terms used by the Connected Fields API.

Connected fields

A connected field is a field whose type is mapped to a corresponding object type in your system of record. The values for this type can be verified by data verification or connected fields extensions defined in your account. You can verify the inputs to your connected fields by creating a connected fields extension app and defining the verification logic on your system of record (for custom data models) or using a data verification extension app (for supported standard data models).

Connected fields extension app

A connected fields extension app is required to verify custom field values. See Connected fields for details.

Custom data verification

Custom data verification is a feature, provided by the Connected Fields API, that enables you to implement verification logic for custom fields, rather than only for fields that map directly to data verification extensions, such as Bank account verification.

Data verification extension app

A data verification extension app is required to verify supported generic field values. See Supported extensions for details and a list of supported types.

Next steps

• See How to send an envelope with extension app data verification fields for a detailed walkthrough of how to send an envelope and validate the values of its connected fields.
• Learn about Extension apps and the Connected fields extension.
• See Transform logic for details on how to map your data types to the Concerto format that Docusign uses.
• See External system logic to return data model with verification markers and External system logic to process verification requests for guidance on setting up your system to work with a connected fields extension app.