> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL. > > Documentation indexes by section: > - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt > - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt > - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt > - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt > > Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth > Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks > > OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json > MCP server: https://docusign.docs.buildwithfern.com/_mcp/server # Connected Fields API concepts > Learn about the basic concepts and objects used by the Connected Fields API. 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](/docs/connected-fields-api/reference/connectedfields/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](/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](/docs/esign-rest-api/esign101/concepts/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](/extension-apps/extension-app-reference/extension-contracts/connected-fields) or **data verification** extension app. If your account has neither extension, the [TabInfo:GetConnectedFieldsTabGroups](/docs/connected-fields-api/reference/connectedfields/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](/extension-apps/extension-apps-101/supported-extensions/data-model#transform-logic) for details on how to map your data types to the [Concerto](https://concerto.accordproject.org/docs/intro/) format that Docusign uses. See [External system logic to return data model with verification markers](/extension-apps/extension-apps-101/supported-extensions/connected-fields#external-system-logic-to-return-data-model-with-verification-decorators) and [External system logic to process verification requests](/extension-apps/extension-apps-101/supported-extensions/connected-fields#external-system-logic-to-process-verification-requests) for guidance on setting up your system to work with a connected fields extension app. ![A diagram showing the execution flow for a Connected Fields API data verification flow.](/_fern-files/_img/4dd9762b0963d1766aca46c1c66d068da9dbb9bfb3607f8bc1599d6ea728b4a9.webp) To verify supported generic fields, you must install and connect a data verification extension app. See [Install Docusign Apps for Data Verification](https://support.docusign.com/s/document-item?language=en_US\&bundleId=qki1698158012210\&topicId=pyp1698158616536.html) 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](/docs/connected-fields-api/reference/connectedfields/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](https://concerto.accordproject.org/docs/design/specification/model-decorators)**.** ### 2. Extract the data from the response Extract the data from this response needed to create corresponding fields (also called [Tabs](/docs/esign-rest-api/esign101/concepts/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). **`Generic field`** ```json title="Generic field" { "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" }, ``` **`Custom field`** ```json title="Custom field" { "extensionData": { "extensionGroupId": "8f8583c6-xxxx-xxxx-xxxx-7663ac85f5cd", "actionInputKey": "countryCode", "publisherName": "John Doe", "applicationName": "My Connected Fields Test App", "actionContract": "", "extensionName": "", "actionName": "", "extensionPolicy": "None", "requiredForExtension": true, "connectedFieldsData": { "typeSystemNamespace": "com.docusign.connecteddata._WyJhZTIzMmYxZi04ZWZjLTRiOGMtYmIwOC02MjY4NDdmYWQ4YmIiLDAsImJlYzZmZTIwLTRiNmYtNGYyMi04OTM4LTU3MTYxY2Q1NjllNyIsIjA2YzUyZWQ0LWFhNjMtNDlkZC04OWI5LTc1NjgwMDE0Zjg3YyIsMF0@1.0.0", "typeName": "VerifyPhoneNumberInput", "supportedOperation": "VerifyType", "propertyName": "countryCode", "supportedUri": "/connected-data/v1/connected-objects/com.docusign.connecteddata._WyJhZTIzMmYxZi04ZWZjLTRiOGMtYmIwOC02MjY4NDdmYWQ4YmIiLDAsImJlYzZmZTIwLTRiNmYtNGYyMi04OTM4LTU3MTYxY2Q1NjllNyIsIjA2YzUyZWQ0LWFhNjMtNDlkZC04OWI5LTc1NjgwMDE0Zjg3YyIsMF0@1.0.0/VerifyPhoneNumberInput/verify" } }, "validationPattern": "^(\\+?\\(?\\d{1,6}\\)?|\\(\\+\\d{1,6}\\)|\\d{1,2}-?\\d{3})$", "tabType": "text", "tabLabel": "com.docusign.connecteddata._WyJhZTIzMmYxZi04ZWZjLTRiOGMtYmIwOC02MjY4NDdmYWQ4YmIiLDAsImJlYzZmZTIwLTRiNmYtNGYyMi04OTM4LTU3MTYxY2Q1NjllNyIsIjA2YzUyZWQ0LWFhNjMtNDlkZC04OWI5LTc1NjgwMDE0Zjg3YyIsMF0@1.0.0.VerifyPhoneNumberInput[0].countryCode" }, ``` ### 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. **`Example envelope definition`** ```json title="Example envelope definition" { "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](/docs/connected-fields-api/send-envelope-with-data-verification-fields) for a detailed walkthrough on how to programmatically send an envelope that verifies custom data, or [Connected fields in Docusign envelopes](/extension-apps/extension-apps-101/supported-extensions/connected-fields#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](/extension-apps/extension-apps-101/supported-extensions/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](/extension-apps/extension-app-reference/extension-contracts/bank-account-verification). ### Data verification extension app A data verification extension app is required to verify supported generic field values. See [Supported extensions](/extension-apps/extension-apps-101/supported-extensions) for details and a list of supported types. ## Next steps * See [How to send an envelope with extension app data verification fields](/docs/connected-fields-api/send-envelope-with-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](/extension-apps) and the [Connected fields](/extension-apps/extension-apps-101/supported-extensions/connected-fields) extension. * See [Transform logic](/extension-apps/extension-apps-101/supported-extensions/data-model#transform-logic) for details on how to map your data types to the [Concerto](https://concerto.accordproject.org/docs/intro/) format that Docusign uses. * See [External system logic to return data model with verification markers](/extension-apps/extension-apps-101/supported-extensions/connected-fields#external-system-logic-to-return-data-model-with-verification-decorators) and [External system logic to process verification requests](/extension-apps/extension-apps-101/supported-extensions/connected-fields#external-system-logic-to-process-verification-requests) for guidance on setting up your system to work with a connected fields extension app.