> 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 # ConnectConfigurations Resource The `ConnectConfigurations` resource enables you to configure the Docusign Connect service for your account. You can use this resource to configure account-level webhooks that send notifications about every envelope sent from your account. You can set account-level webhooks to listen for events for envelopes sent by a specific user on your account, by multiple specific users, or from any of the users on your account. These events will be tracked, and can be delivered to a listening application. **Note:** To create an envelope-level webhook instead of using account-level webhooks, use the Envelopes::Create method and add an `eventNotification` object to an envelope object. Docusign Connect offers two delivery modes: * Send Individual Messages * Send Aggregated Messages By default, the Send Individual Messages mode is enabled. You can disable it (enabling Aggregated Messages mode) through Docusign Admin in the **Updates** section. **Note:** In either mode, Connect [must be enabled](https://support.docusign.com/s/document-item?bundleId=pik1583277475390\&topicId=ctv1583277395112.html) in your Docusign account. It is not enabled by default. ## Send Individual Messages Send Individual Messages (SIM) mode is the default. In this mode Docusign delivers notifications for each envelope events individually. When a final recipient completes an envelope, your listener will receive a single **Recipient Signed/Completed** event followed by a single **Envelope Signed/Completed** event for the final participating party on the agreement. For more information about SIM mode, see [Using Connect's Send Individual Messages Feature](https://www.docusign.com/blog/developers/using-connects-send-individual-messages-feature). ## Aggregated Messages In Aggregated Messages mode, Connect aggregates similar events into a single delivery. Similar or simultaneous events are aggregated, so that your listener doesn't receive extraneous messages. When the final recipient signs an envelope, the system delivers a single, aggregated Connect event, rather than separate Recipient: complete and Envelope: complete messages. This aggregation process ensures that you only receive the minimal viable number of messages about an envelope's life cycle. ## Methods supported | Method | Description | | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | [create](/docs/esign-rest-api/reference/connect/connectconfigurations/create) | POST `/restapi/v2.1/accounts/{accountId}/connect` Creates a Connect configuration. | | [createConnectOAuthConfig](/docs/esign-rest-api/reference/connect/connectconfigurations/createconnectoauthconfig) | POST `/restapi/v2.1/accounts/{accountId}/connect/oauth` Set up Connect OAuth for the specified account. | | [createConnectSecret](/docs/esign-rest-api/reference/connect/connectconfigurations/createconnectsecret) | POST `/restapi/v2.1/accounts/{accountId}/connect/secret` Generates a new connect HMAC Secret. | | [delete](/docs/esign-rest-api/reference/connect/connectconfigurations/delete) | DEL `/restapi/v2.1/accounts/{accountId}/connect/{connectId}` Deletes the specified Connect configuration. | | [deleteConnectOAuthConfig](/docs/esign-rest-api/reference/connect/connectconfigurations/deleteconnectoauthconfig) | DEL `/restapi/v2.1/accounts/{accountId}/connect/oauth` Delete the Connect OAuth configuration. | | [deleteConnectSecret](/docs/esign-rest-api/reference/connect/connectconfigurations/deleteconnectsecret) | DEL `/restapi/v2.1/accounts/{accountId}/connect/secret/{keyId}` Deletes the Connect HMAC Secret at the provided index from your account. | | [get](/docs/esign-rest-api/reference/connect/connectconfigurations/get) | GET `/restapi/v2.1/accounts/{accountId}/connect/{connectId}` Gets the details about a Connect configuration. | | [getConnectAllUsers](/docs/esign-rest-api/reference/connect/connectconfigurations/getconnectallusers) | GET `/restapi/v2.1/accounts/{accountId}/connect/{connectId}/all/users` Returns all users from the configured Connect service. | | [getConnectOAuthConfig](/docs/esign-rest-api/reference/connect/connectconfigurations/getconnectoauthconfig) | GET `/restapi/v2.1/accounts/{accountId}/connect/oauth` Retrieves the Connect OAuth information for the account. | | [getConnectSecret](/docs/esign-rest-api/reference/connect/connectconfigurations/getconnectsecret) | GET `/restapi/v2.1/accounts/{accountId}/connect/secret` Get the connect HMAC Secrets for AccountID | | [list](/docs/esign-rest-api/reference/connect/connectconfigurations/list) | GET `/restapi/v2.1/accounts/{accountId}/connect` Get Connect configuration information. | | [listUsers](/docs/esign-rest-api/reference/connect/connectconfigurations/listusers) | GET `/restapi/v2.1/accounts/{accountId}/connect/{connectId}/users` Returns users from the configured Connect service. | | [update](/docs/esign-rest-api/reference/connect/connectconfigurations/update) | PUT `/restapi/v2.1/accounts/{accountId}/connect` Updates a specified Connect configuration. | | [updateConnectOAuthConfig](/docs/esign-rest-api/reference/connect/connectconfigurations/updateconnectoauthconfig) | PUT `/restapi/v2.1/accounts/{accountId}/connect/oauth` Updates the existing Connect OAuth configuration for the account. | ## ConnectConfigurations properties | Property | Type | Description | | ----------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `allowEnvelopePublish` | string | When **true,** data is sent to the `urlToPublishTo` web address. The default value for this property is **false,** which will stop sending data while maintaining the Connect configuration information. | | `allowSalesforcePublish` | string | When **true,** Docusign sends data to the designated Salesforce account through Connect. The default value is **true.** | | `allUsers` | string | When **true,** the tracked envelope and recipient events for all users, including users that are added a later time, are sent through Connect. The default value is **false.** **Note:** If this property is **false,** make sure you set the `userIds` property to a non-empty array of user IDs. | | `allUsersExcept` | string | This flag allows you to toggle between including and excluding specified users from the configuration. When **false,** the users corresponding to the IDs in `userIds` will be included in the configuration. Conversely, when **true,** the users will be excluded from the configuration. The default value is **false.** | | `configurationType` | string | If you are using merge fields, this property specifies the type of the merge field. The only supported value is `salesforce`. | | `connectId` | string | The Docusign-generated ID for the Connect configuration. This property is read-only. | | `deliveryMode` | string | | | `disabledBy` | string | | | `enableLog` | string | When **true,** Connect logging is turned on. Docusign recommends that you enable this functionality to help troubleshoot any issues. You can have a maximum of 100 active logs in your account. You can view the entries in active logs in the **Logs** tab in the Connect console. | | `enableOAuthPerConfiguration` | string | | | `envelopeEvents` | array | An array of strings that lists envelope-related events to track through Connect. The possible event values are:- `sent`: An envelope has the status `sent` in the following scenarios: - When the envelope has been sent to recipients. - When using remote signing, this event is triggered when the email notification with a link to the documents is sent to at least one recipient. - When using embedded signing, this event is triggered when the link is ready for the recipient to sign the envelope.An envelope remains in this state until all recipients have viewed or taken action on the envelope.- `delivered`: This status is triggered when all recipients have opened the envelope, selected the **Continue** button in the interface, and viewed the documents. - `completed`: This status is triggered when all recipients have completed their assigned actions on an envelope. - `declined`: This status is triggered when a recipient has declined to sign the envelope. - `voided`: The voided status indicates that the sender has voided the envelope.**Note:** In previous versions of the API, this value was a single comma-separated string. | | `eventData` | connectEventData | Allows you to specify the format of the information the Connect webhooks returns. | | `events` | array | A comma-separated list of envelope-level event statuses that will trigger Connect to send updates to the endpoint specified in the `urlToPublishTo` property. Set this property when you are using the [JSON SIM event model](/platform/webhooks/connect/json-sim-event-model). If you are instead using any of [the legacy event message formats](/platform/webhooks/connect/legacy-message-formats), set either the `envelopeEvents` property or the `recipientEvents` property. The [possible event statuses](/platform/webhooks/connect/json-sim-event-reference) are:- `envelope-created` - `envelope-sent` - `envelope-resent` - `envelope-delivered` - `envelope-completed` - `envelope-declined` - `envelope-voided` - `recipient-authenticationfailed` - `recipient-autoresponded` - `recipient-declined` - `recipient-delivered` - `recipient-completed` - `recipient-sent` - `recipient-resent` - `template-created` - `template-modified` - `template-deleted` - `envelope-corrected` - `envelope-purge` - `envelope-deleted` - `envelope-discard` - `recipient-reassign` - `recipient-delegate` - `recipient-finish-later` - `click-agreed` - `click-declined` | | `externalFolderId` | string | The ID of an external folder. | | `externalFolderLabel` | string | The label for an external folder. | | `groupIds` | array | | | `includeCertificateOfCompletion` | string | When **true,** the Connect Service includes the Certificate of Completion with completed envelopes. | | `includeCertSoapHeader` | string | When **true,** a certificate for a SOAP header is included in messages sent through Connect. | | `includeDocumentFields` | string | When **true,** the Document Fields associated with the envelope's documents are included in the notification messages. Document Fields are optional custom name-value pairs added to documents using the API. | | `includeDocuments` | string | When **true,** Connect attaches the envelope documents to the payloads of your event notification messages. **Note:** Consider resources and scaling when adding documents to your event payloads. Documents attached to these messages are sent as base64 strings, which are larger than binary document data. This can significantly increase your payload size, opening up windows for failure. If you include documents, you must build your application to scale in these situations. | | `includeEnvelopeVoidReason` | string | When **true,** Connect will include the voidedReason for voided envelopes. | | `includeHMAC` | string | When **true,** a Hash-based Message Authentication Code (HMAC) signature is included in messages sent through Connect. For more information, see [Using HMAC Security with Docusign Connect](/platform/webhooks/connect/hmac). | | `includeOAuth` | string | | | `includeSenderAccountasCustomField` | string | When **true,** Connect will include the sender account as Custom Field in the data. | | `includeTimeZoneInformation` | string | When **true,** Connect will include the envelope time zone information. | | `integratorManaged` | string | | | `name` | string | The name of the Connect configuration. The name helps identify the configuration in the list. | | `oAuthConfiguration` | connectOAuthConfig | | | `password` | string | The user's password. This property is used only when adding a new user via a [Users: create](/docs/esign-rest-api/reference/users/users/create) request. The value must conform to the password rules defined in the account [Security Settings](https://apps-d.docusign.com/admin/authenticate?goTo=securityInfo). This property is not returned by `GET` requests and cannot be updated via `PUT` requests. | | `pausePublish` | string | | | `recipientEvents` | array | An array of strings that lists of recipient-related events that trigger a notification to your webhook Connect listener. The possible event values are:- `sent`: If a recipient type is set to receive an email notification to take action on an envelope, the recipient status is set to `sent` upon delivery of the email. - `delivered`: The recipient has viewed the documents in the envelope. This recipient status does not indicate email delivery of the documents in the envelope. - `completed`: The recipient has completed their assigned actions on an envelope. - `declined`: The recipient has declined to sign a document in the envelope. - `authenticationfailed`: At least one signer has failed the authentication check on the document. If this occurs, you have two options: - Send a reminder to the recipients, which provides the signer with another chance to access and pass the authentication. - Correct the document and modify the authentication setting. - `autoresponded`: The recipient's email system sent back an automatic response. This status is only used when **Send-on-behalf-of** is turned off for the account.**Note:** In previous versions of the API, this value was a single comma-separated string. | | `requireMutualTls` | string | When **true,** [Mutual TLS](/platform/webhooks/mutual-tls) authentication is enabled. | | `requiresAcknowledgement` | string | When **true,** event delivery acknowledgements are enabled for your Connect configuration. Docusign Connect awaits a valid 200 response from your application acknowledging that it received a message. If you do not acknowledge receiving an event notification message within 100 seconds, Docusign treats the message as a failure and places it into a failure queue. It is imperative that you acknowledge successful receipt of Connect events as they occur by sending a 200 event back. #### When **true** and Send Individual Messages (SIM) mode is activated If the HTTP status response to a notification message is not in the range of 200-299, then the message delivery failed, and the configuration is marked as down. The message will be queued and retried once per day. While a Connect configuration is marked down, subsequent notifications will not be tried. Instead they will be immediately queued with the reason `Pending`. When a message succeeds, all queued messages for the configuration will be tried immediately, in order. There is a maximum of ten retries. Alternately, you can use **Republish Connect Information** to manually republish the notification. #### When **true** and SIM mode is not activated If the HTTP Status response to a notification message is not in the range of 200-299, then the message delivery failed, and the message is queued. The message will be retried after at least a day the next time a subsequent message is successfully sent to this configuration (subscription). Subsequent notifications will be tried when they occur. There is a maximum of ten retries. Alternately, you can use **Republish Connect Information** to manually republish the notification. #### When **false** When `requiresAcknowledgement` is set to **false** and you do not acknowledge receiving an event notification message within 100 seconds, Docusign treats the message as a failure and determines that the server is unavailable. It does not retry to send the notification message, and you must handle the failure manually. | | `salesforceApiVersion` | string | The version of the Salesforce API that you are using. | | `salesforceAuthcode` | string | | | `salesforceCallBackUrl` | string | | | `salesforceCodeVerifier` | string | | | `salesforceDocumentsAsContentFiles` | string | When **true,** Docusign can use documents in your Salesforce account for sending and signing. | | `senderOverride` | string | | | `senderSelectableItems` | array | This property sets the items that are available for selection when adding or editing Connect objects. | | `sfObjects` | array | An array of Salesforce objects. | | `signMessageWithX509Certificate` | string | When **true,** Mutual TLS will be enabled for notifications. Mutual TLS must be initiated by the listener (the customer's web server) during the TLS handshake protocol. | | `soapNamespace` | string | The namespace of the SOAP interface. **Note:** If `useSoapInterface` is set to **true,** you must set this value. | | `urlToPublishTo` | string | The endpoint to which Connect should send webhook notification messages via an HTTPS POST request. The URL must start with `https`. The customer's web server must use an SSL/TLS certificate whose CA is in the Microsoft list of trusted CAs. Self-signed certificates are not acceptable, but you can use free certificates from Let's Encrypt. The maximum length of this property is 4096 bytes. | | `userIds` | array | A comma-separated list of user IDs. This sets the users associated with the tracked envelope and recipient events. When a tracked event occurs for a set user, the a notification message is sent to your Connect listener. By default, the users will be included in the configuration. If you want to exclude the users, set the `allUsersExcept` property to **true.** **Note:** If `allUsers` is set to `false`, then you must provide a list of user IDs. | | `userName` | string | The name of the user. | | `useSoapInterface` | string | When **true,** indicates that the `urlToPublishTo` property contains a SOAP endpoint. | ## API Docs - ConnectConfigurations [Create Connect configuration](https://developers.docusign.com/docs/esign-rest-api/reference/connect/connectconfigurations/create.md) - ConnectConfigurations [Set up Connect OAuth](https://developers.docusign.com/docs/esign-rest-api/reference/connect/connectconfigurations/createconnectoauthconfig.md) - ConnectConfigurations [Generate connect HMAC secret](https://developers.docusign.com/docs/esign-rest-api/reference/connect/connectconfigurations/createconnectsecret.md) - ConnectConfigurations [Delete connect configuration](https://developers.docusign.com/docs/esign-rest-api/reference/connect/connectconfigurations/delete.md) - ConnectConfigurations [Delete Connect OAuth configuration](https://developers.docusign.com/docs/esign-rest-api/reference/connect/connectconfigurations/deleteconnectoauthconfig.md) - ConnectConfigurations [Delete Connect HMAC secret at provided index](https://developers.docusign.com/docs/esign-rest-api/reference/connect/connectconfigurations/deleteconnectsecret.md) - ConnectConfigurations [Get Connect configuration](https://developers.docusign.com/docs/esign-rest-api/reference/connect/connectconfigurations/get.md) - ConnectConfigurations [Get users from configured Connect service](https://developers.docusign.com/docs/esign-rest-api/reference/connect/connectconfigurations/getconnectallusers.md) - ConnectConfigurations [Get Connect OAuth information](https://developers.docusign.com/docs/esign-rest-api/reference/connect/connectconfigurations/getconnectoauthconfig.md) - ConnectConfigurations [Get connect HMAC secrets for AccountID](https://developers.docusign.com/docs/esign-rest-api/reference/connect/connectconfigurations/getconnectsecret.md) - ConnectConfigurations [Get Connect configuration information](https://developers.docusign.com/docs/esign-rest-api/reference/connect/connectconfigurations/list.md) - ConnectConfigurations [List users](https://developers.docusign.com/docs/esign-rest-api/reference/connect/connectconfigurations/listusers.md) - ConnectConfigurations [Update Connect configuration](https://developers.docusign.com/docs/esign-rest-api/reference/connect/connectconfigurations/update.md) - ConnectConfigurations [Update Connect OAuth configuration](https://developers.docusign.com/docs/esign-rest-api/reference/connect/connectconfigurations/updateconnectoauthconfig.md) ## OpenAPI Specification The raw OpenAPI 3.1 specification for this API is available at: - [OpenAPI JSON](https://developers.docusign.com/openapi.json) - [OpenAPI YAML](https://developers.docusign.com/openapi.yaml)