> 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 extension overview > Get an overview of an extension that performs real-time custom data verification against a system of record. The connected fields extension enables you to perform real-time custom data verification of values entered in eSignature [envelopes](https://support.docusign.com/s/document-item?bundleId=ulp1643236876813\&topicId=gso1578456465211.html). Unlike the data verification [extensions](/extension-apps/extension-apps-101/supported-extensions), which verify specific types of values (such as bank account numbers and addresses), the connected fields extension can verify any data against your organization’s system of record. For example, you can use a connected fields extension to 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. In the response, your system also supplies custom messages that provide users with specific guidance about the information they must enter. In addition, your system can return autofill values for the envelope based on known information about a user. > **Note** > > In the current release, Docusign will display field labels and messages in the signing UI in the language in which the external system provides them. In a future release, translation to other languages will be supported. Because connected fields extensions verify organization-specific data, they are useful for [private extension apps](/extension-apps/extension-apps-101/choosing-private-distribution). Private extension apps can be developed and published for use by specific accounts or within your organization. This contrasts with public extension apps, which are available for all Docusign customers to view and install. ## Connected fields in Docusign envelopes After a connected fields extension app has been [installed and connected](https://support.docusign.com/s/document-item?bundleId=ous1698169987748\&topicId=ctg1698170340729.html) to a Docusign account, the fields it implements are available for custom data verification in envelopes created in the account. Expand the sections below to see how connected fields function during envelope preparation and signing. #### Preparer accesses a list of connected fields In this example, a preparer creates a [template](https://support.docusign.com/s/document-item?bundleId=xry1643227563338\&topicId=dqj1578456412286.html\&rsc_301) or [envelope](https://support.docusign.com/s/document-item?bundleId=ulp1643236876813\&topicId=gso1578456465211.html) containing a document that an organization requires customers to complete when transferring money from one fund in a financial account to another. The data that a customer must populate might include an account number, source fund, transfer amount, destination fund, and other values. For the preparer who sets up the transfer authorization document in the [Add Fields view](https://support.docusign.com/s/document-item?bundleId=ulp1643236876813\&topicId=odn1578456409392.html), the available connected fields would look like this: ![Connected fields list in eSignature Add Fields view](/_fern-files/_img/f1f43a24c43e04affc866fd1b085ece2cf41e2ea4504b20e452d1115cdfe1489.webp) #### Preparer adds connected fields to a document The preparer can add the connected field group to the document by selecting any required field in the group, dragging it to the document, and positioning the fields as needed. After completing this setup, the preparer sends the envelope to a customer for completion. ![Connected fields added to an eSignature document](/_fern-files/_img/ddfea2c868298d5bac039deafbc02f1be86da404f76ac21882695022c955fa79.webp) #### Signer populates connected fields, triggering verification A signer accesses the envelope. When the signer has populated all the required fields in the connected fields group, Docusign sends a verification request that includes the user-entered values to the external system. The system is responsible for applying verification logic to the values that Docusign sends. ![Connected fields verification in progress](/_fern-files/_img/727d036c37fbce5c953ba782872c58e2e071b112306dd4f6db46732df2a859a9.webp) #### Signing view displays verification result and message The response from the external system to Docusign must indicate whether verification succeeded or failed. The signing view displays the accompanying message that the external system returns. ![Connected fields verification error](/_fern-files/_img/3e7d884312974d8fea0a3a1c4f58baff4632c70b49fa8f463e92c71f84569b7b.webp) #### Signing view autofills suggested values The external system’s response can also supply suggested values for any of the fields. Docusign autofills the suggested values, and the signer can use them if they wish. ![Connected field with autofilled value](/_fern-files/_img/98b79528bf25dd835de1dea8c6872f39df1e8a2c5cf43fdd3988222221955774.webp) #### Signer completes the envelope after successful verification If verification succeeds, the signer can complete and submit the envelope to Docusign. ![Connected fields verification succeeded](/_fern-files/_img/35b5277b835a92f7719423e82b41d5883aa6aef3e547ad44907b8d4107ec9ffa.webp) ## Create envelopes with connected fields programmatically To create envelopes that include connected fields programmatically, use these API requests: * Connected Fields API [TabInfo:GetConnectedFieldsTabGroups](/docs/connected-fields-api/reference/connectedfields/tabinfo/getconnectedfieldstabgroups) request: Retrieves information about the connected fields extension apps installed and connected to your account, and the required connected fields associated with each extension app. * eSignature REST API [Envelopes:create](/docs/esign-rest-api/reference/envelopes/envelopes/create) request: Creates envelopes that can include connected fields from the extension apps installed to your account See [Connected fields concepts](/docs/connected-fields-api/concepts) for an overview of the API, and see [How to send an envelope with extension app data verification fields](/docs/connected-fields-api/send-envelope-with-data-verification-fields) for example code and a detailed walkthrough. ## Verification results To retrieve verification results programmatically, you can use [Docusign Connect](/platform/webhooks/connect) and implement a listener to receive the `extension-executed` event. This event is supported only with the [JSON SIM event model](/platform/webhooks/connect/json-sim-event-model). See [JSON SIM event reference](/platform/webhooks/connect/json-sim-event-model#json-sim-event-reference) for the event structure. Verification results are also included in the [envelope history](https://support.docusign.com/s/document-item?bundleId=oeq1643226594604\&topicId=dpr1578456338693.html), shown in this figure, and the [certificate of completion](https://support.docusign.com/s/document-item?bundleId=oeq1643226594604\&topicId=gpa1578456339545.html). ![Envelope history showing connected fields verification results](/_fern-files/_img/e6c5a92a09eabf798e82c505fda887a70c82a904106632ee616916eb4b485b78.webp) ## Connected fields actions A connected fields extension implements these [actions](/extension-apps/extension-apps-101/concepts/actions): | Action | Executed when | Description | | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Get Type Names](/extension-apps/extension-app-reference/extension-contracts/connected-fields#get-type-names) | The extension app establishes or refreshes a connection. This can be triggered by:- Running a [connection test](/extension-apps/build-an-extension-app/test/integration-tests#run-a-connection-test) from the Developer Console Testing module - Creating or refreshing a connection in the App Center. See [Manage Docusign App Connections](https://support.docusign.com/s/document-item?bundleId=ous1698169987748\&topicId=xyw1716318604389.html) for details. | Gets the names of the types that are used by your system of record. In the [extension app manifest](/extension-apps/extension-app-reference/app-manifest-reference/action), this action is identified as `DataIO.Version6.GetTypeNames`. The connected fields extension uses the data IO extension’s **Get Type Names** action contract because the contract details are identical. | | [Get Type Definitions](/extension-apps/extension-app-reference/extension-contracts/connected-fields#get-type-definitions) | The extension app establishes or refreshes a connection. This action is executed directly after **Get Type Names**. | Gets a set of type definitions from your system of record and returns their equivalents in the [Concerto](https://concerto.accordproject.org/docs/intro/) data model format. Docusign uses the Concerto data model to map the data from your system of record. If your system of record does not already use the Concerto data model, you must implement transform logic that defines how your records map to Concerto data types before they can be read. This transform logic should be implemented within your **Get Type Definitions** action, and is called whenever the action is executed. See [Data model](/extension-apps/extension-apps-101/supported-extensions/data-model) for details on the structure. In the extension app manifest, this action is identified as `DataIO.Version6.GetTypeDefinitions`. The connected fields extension uses the data IO extension’s **Get Type Definitions** action contract because the contract details are identical. | | [Verify](/extension-apps/extension-app-reference/extension-contracts/connected-fields#verify) | A recipient of a Docusign envelope populates all required connected fields, and when a user modifies a value in any required connected field. | Sends user-populated connected field values from an envelope to the external system for verification. The external system applies verification logic to the values and returns a response to Docusign indicating whether verification passed or failed. The response must include success or failure messages that are displayed in the signing UI. The response can also provide suggested values to be autofilled in the fields. In the extension app manifest, this action is identified as `ConnectedFields.Version1.Verify`. | ## Get Type Names and Get Type Definitions flow When your connected fields extension app is [installed and connected](https://support.docusign.com/s/document-item?bundleId=ous1698169987748\&topicId=ctg1698170340729.html) to a Docusign account, or when a connection is [refreshed](https://support.docusign.com/s/document-item?bundleId=ous1698169987748\&topicId=qkv1716320270335.html) in the Docusign App Center, the extension app will automatically get the types and type definitions of the objects that your system of record is configured to expose: 1. Docusign calls [Get Type Names](/extension-apps/extension-app-reference/extension-contracts/connected-fields#get-type-names) to get the set of types that your system of record exposes. The types are returned as a JSON object that includes the name, label, and an optional description for each type. 2. Docusign calls [Get Type Definitions](/extension-apps/extension-app-reference/extension-contracts/connected-fields#get-type-definitions), inputting the types returned by **Get Type Names**. This returns the definitions of each type that your system of record exposes for Docusign. After the Docusign platform receives the type definitions, it will display the corresponding connected fields in the eSignature [Add Fields view](https://support.docusign.com/s/document-item?bundleId=ulp1643236876813\&topicId=odn1578456409392.html) for users in your account. This enables template and envelope preparers to include the connected fields in documents that will be sent to your customers. **Important**: Docusign models data input and output definitions using a flexible schema in [Concerto](https://concerto.accordproject.org/docs/intro/). If your system of record does not already use the Concerto data model, you must implement logic to convert your type definitions into Concerto format as part of your response to the **Get Type Definitions** call. See [Data model](/extension-apps/extension-apps-101/supported-extensions/data-model) for recommendations on mapping types or [Concerto specification](https://concerto.accordproject.org/docs/category/specification) for details on specific types, syntax, and examples. ![Get Type Names and Definitions diagram](/_fern-files/_img/a6206bf1c7e7eab20350e00d036de5fbbaf3c5af30d9846e87aae82235adf01b.webp) ## Verify flow The [Verify](/extension-apps/extension-app-reference/extension-contracts/connected-fields#verify) action is executed when a user completes all required connected fields in a Docusign envelope or updates a required connected field value: 1. The **Verify** request is sent to the system of record. The request body is a JSON object that includes key-value pairs representing property names and user-populated values from the envelope, as well as a type name and a unique key that the external system can use to identify duplicate requests. 2. The external system applies any required business logic to verify the user-populated values. 3. The external system sends a response to Docusign indicating the verification result, suggested values if appropriate, and a message for the user. 4. Docusign displays the verification result, accompanying message, and any suggested values used to autofill fields in the envelope signing view. ![Connected fields Verify action diagram](/_fern-files/_img/99464686356097b056bf0d570bbbd557198cbe237fc246823025ab2822a65359.webp) ## Plan a connected fields extension implementation When planning the implementation of a connected fields extension, you’ll need to consider the following: * [eSignature envelope field mapping to data source properties](/extension-apps/extension-apps-101/supported-extensions/connected-fields#esignature-envelope-field-mapping-to-data-source-properties) * [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) * [External system logic to process verification requests](/extension-apps/extension-apps-101/supported-extensions/connected-fields#external-system-logic-to-process-verification-requests) ### eSignature envelope field mapping to data source properties Identify eSignature envelope fields whose values are to be verified, and determine which external data source properties they can be verified against. For the example case described in [Connected fields in Docusign envelopes](/extension-apps/extension-apps-101/supported-extensions/connected-fields#connected-fields-in-docusign-envelopes), the mapping might be: | eSignature document field | External data source property | | -------------------------------- | ----------------------------- | | Account Number | `account_num` | | Source Fund | `source_fund` | | Destination Fund | `destination_fund` | | Amount to Transfer | `balance` | | Transfer Date | `transferDate` | | Send Destination Fund Prospectus | `prospectus` | | Type of Account | `typeOfAccount` | | Owner Email | `email` | | Account Owner Name | `ownername` | When planning the mapping of external data source properties to Docusign envelope fields, keep in mind that each data type returned in a [Get Type Definitions](/extension-apps/extension-app-reference/extension-contracts/connected-fields#get-type-definitions) response will be automatically rendered as one of the supported envelope field types. See [Transform logic](/extension-apps/extension-apps-101/supported-extensions/data-model#transform-logic) for details. ### External system logic to return data model with verification decorators Your external system must be able to return the information Docusign needs to determine which values can be sent to your system for verification. The two requests that Docusign will send to retrieve this information are: * [Get Type Names](/extension-apps/extension-app-reference/extension-contracts/connected-fields#get-type-names): Retrieves a list of objects in the data source. * [Get Type Definitions](/extension-apps/extension-app-reference/extension-contracts/connected-fields#get-type-definitions): Retrieves definitions of the properties in the data source. This response must include decorators that mark objects as verifiable and indicate which properties are required for verification. See the [connected fields extension contract](/extension-apps/extension-app-reference/extension-contracts/connected-fields) for details about the request formats and the expected response formats. See [API proxy](/extension-apps/build-an-extension-app/it-infrastructure/api-proxy) for guidance about transforming requests and responses to the correct format. ### External system logic to process verification requests Your system must implement logic to verify user-entered envelope values according to your business requirements. For example, if Docusign sends an account owner name, account number, source fund for a transfer, destination fund, and transfer amount, your system might evaluate whether: 1. The account owner name matches the owner on record for the supplied account number. 2. The account has a position in the source fund supplied. 3. The source fund balance is greater than or equal to the transfer amount. 4. All of your organization’s other requirements for the transfer have been met. For details about the format of the verification request that Docusign sends and the required format for the response, see the [Verify](/extension-apps/extension-app-reference/extension-contracts/connected-fields#verify) action contract. See [API proxy](/extension-apps/build-an-extension-app/it-infrastructure/api-proxy) for guidance about transforming requests and responses to the correct format. ## Next steps * See [Connected fields extension contract reference](/extension-apps/extension-app-reference/extension-contracts/connected-fields) for details about the action requests and responses. * Get an overview of the process to [build an extension app](/extension-apps/build-an-extension-app). * Learn more about [private extension apps](/extension-apps/extension-apps-101/choosing-private-distribution), which are available only to specified Docusign accounts.