Creates a DocuSign Custom Connect definition for your account. DocuSign Connect enables the sending of real-time data updates to external applications. These updates are generated by user transactions as the envelope progresses through actions to completion. The Connect Service provides updated information about the status of these transactions and returns updates that include the actual content of document form fields. Be aware that, these updates might or might not include the document itself. For more information about Connect, see the DocuSign Connect.

Note: Connect must be enabled for your account to use this function. This cannot be used to set up Connect configurations for Salesforce or eOriginal.

Request

HTTP request

POST /v2/accounts/{accountId}/connect

Parameters

Parameter NameValueDescription
Path Parameters
accountIdstring

The external account number (int) or account ID Guid.

Responses

CodeDescriptionReference
201

Successful response.

ConnectConfigurations
400

Error encountered.

errorDetails

SDK Method

Connect::createConfiguration

Definitions

errorDetails

This object describes errors that occur. It is only valid for responses, and ignored in requests.

errorCodestring

An error code associated with the error.

messagestring

A short error message.

ConnectConfigurations

Connect configurations

allowEnvelopePublishstring

When set to true, data is sent to the urlToPublishTo web address. This option can be set to false to stop sending data while maintaining the Connect configuration information.

allUsersstring

When set to true, the tracked envelope and recipient events for all users, including users that are added a later time, are sent through Connect.

configurationTypestring

If merge field's are being used, specifies the type of the merge field. The only supported value is salesforce.

connectIdstring

Read only: the DocuSign generated ID for the Connect configuration.

enableLogstring

This turns Connect logging on or off. When set to true, logging is turned on.

envelopeEventsstring

A comma separated list of Envelope related events that are tracked through Connect. The possible event values are: Sent, Delivered, Completed, Declined, and Voided.

includeCertificateOfCompletionstring

When set to true, the Connect Service includes the Certificate of Completion with completed envelopes.

includeCertSoapHeaderstring

includeDocumentFieldsstring

When set to 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.

includeDocumentsstring

When set to true, Connect will send the PDF document along with the update XML.

includeEnvelopeVoidReasonstring

When set to true, Connect will include the voidedReason for voided envelopes.

includeSenderAccountasCustomFieldstring

When set to true, Connect will include the sender account as Custom Field in the data.

includeTimeZoneInformationstring

When set to true, Connect will include the envelope time zone information.

namestring

The name of the Connect configuration. The name helps identify the configuration in the list.

recipientEventsstring

A comma separated list of Recipient related events that will trigger a notification to your webhook Connect listener. The possible event values are: Sent, Delivered, Completed, Declined, AuthenticationFailed, and AutoResponded.

requiresAcknowledgementstring

When set to true, and 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, they'll be immediately queued with reason "Pending." Once 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 set to 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.

signMessageWithX509Certificatestring

When set to 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.

soapNamespacestring

The namespace of the SOAP interface.

The namespace value must be set if useSoapInterface is set to true.

urlToPublishTostring

The endpoint to which webhook notification messages are sent 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 ok. Free certificates from Let's Encrypt can be used.

userIdsstring

A comma separated list of userIds. 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.

Note: If allUsers is set to false then you must provide a list of user ids.

useSoapInterfacestring

When set to true, indicates that the urlToPublishTo property contains a SOAP endpoint.

Examples

Generic JSON Request/Response

Request
{
  "connectId": "sample string 1",
  "configurationType": "sample string 2",
  "urlToPublishTo": "sample string 3",
  "name": "sample string 4",
  "allowEnvelopePublish": "sample string 5",
  "enableLog": "sample string 6",
  "includeDocuments": "sample string 7",
  "includeCertificateOfCompletion": "sample string 8",
  "requiresAcknowledgement": "sample string 9",
  "signMessageWithX509Certificate": "sample string 10",
  "useSoapInterface": "sample string 11",
  "includeTimeZoneInformation": "sample string 12",
  "includeEnvelopeVoidReason": "sample string 13",
  "includeSenderAccountasCustomField": "sample string 14",
  "envelopeEvents": "sample string 15",
  "recipientEvents": "sample string 16",
  "userIds": "sample string 17",
  "soapNamespace": "sample string 18",
  "allUsers": "sample string 19",
  "includeCertSoapHeader": "sample string 20",
  "includeDocumentFields": "sample string 21"
}
Response
{
  "connectId": "sample string 1",
  "configurationType": "sample string 2",
  "urlToPublishTo": "sample string 3",
  "name": "sample string 4",
  "allowEnvelopePublish": "sample string 5",
  "enableLog": "sample string 6",
  "includeDocuments": "sample string 7",
  "includeCertificateOfCompletion": "sample string 8",
  "requiresAcknowledgement": "sample string 9",
  "signMessageWithX509Certificate": "sample string 10",
  "useSoapInterface": "sample string 11",
  "includeTimeZoneInformation": "sample string 12",
  "includeEnvelopeVoidReason": "sample string 13",
  "includeSenderAccountasCustomField": "sample string 14",
  "envelopeEvents": "sample string 15",
  "recipientEvents": "sample string 16",
  "userIds": "sample string 17",
  "soapNamespace": "sample string 18",
  "allUsers": "sample string 19",
  "includeCertSoapHeader": "sample string 20",
  "includeDocumentFields": "sample string 21"
}
Generic XML Request/Response

Request
<connectCustomConfiguration xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.docusign.com/restapi">
  <allUsers>sample string 19</allUsers>
  <allowEnvelopePublish>sample string 5</allowEnvelopePublish>
  <configurationType>sample string 2</configurationType>
  <connectId>sample string 1</connectId>
  <enableLog>sample string 6</enableLog>
  <envelopeEvents>sample string 15</envelopeEvents>
  <includeCertSoapHeader>sample string 20</includeCertSoapHeader>
  <includeCertificateOfCompletion>sample string 8</includeCertificateOfCompletion>
  <includeDocumentFields>sample string 21</includeDocumentFields>
  <includeDocuments>sample string 7</includeDocuments>
  <includeEnvelopeVoidReason>sample string 13</includeEnvelopeVoidReason>
  <includeSenderAccountasCustomField>sample string 14</includeSenderAccountasCustomField>
  <includeTimeZoneInformation>sample string 12</includeTimeZoneInformation>
  <name>sample string 4</name>
  <recipientEvents>sample string 16</recipientEvents>
  <requiresAcknowledgement>sample string 9</requiresAcknowledgement>
  <signMessageWithX509Certificate>sample string 10</signMessageWithX509Certificate>
  <soapNamespace>sample string 18</soapNamespace>
  <urlToPublishTo>sample string 3</urlToPublishTo>
  <useSoapInterface>sample string 11</useSoapInterface>
  <userIds>sample string 17</userIds>
</connectCustomConfiguration> 
Response
<connectCustomConfiguration xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.docusign.com/restapi">
  <allUsers>sample string 19</allUsers>
  <allowEnvelopePublish>sample string 5</allowEnvelopePublish>
  <configurationType>sample string 2</configurationType>
  <connectId>sample string 1</connectId>
  <enableLog>sample string 6</enableLog>
  <envelopeEvents>sample string 15</envelopeEvents>
  <includeCertSoapHeader>sample string 20</includeCertSoapHeader>
  <includeCertificateOfCompletion>sample string 8</includeCertificateOfCompletion>
  <includeDocumentFields>sample string 21</includeDocumentFields>
  <includeDocuments>sample string 7</includeDocuments>
  <includeEnvelopeVoidReason>sample string 13</includeEnvelopeVoidReason>
  <includeSenderAccountasCustomField>sample string 14</includeSenderAccountasCustomField>
  <includeTimeZoneInformation>sample string 12</includeTimeZoneInformation>
  <name>sample string 4</name>
  <recipientEvents>sample string 16</recipientEvents>
  <requiresAcknowledgement>sample string 9</requiresAcknowledgement>
  <signMessageWithX509Certificate>sample string 10</signMessageWithX509Certificate>
  <soapNamespace>sample string 18</soapNamespace>
  <urlToPublishTo>sample string 3</urlToPublishTo>
  <useSoapInterface>sample string 11</useSoapInterface>
  <userIds>sample string 17</userIds>
</connectCustomConfiguration> 
}} />