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.1/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

connectSalesforceField

This object is used to match a DocuSign field to a Salesforce field so that Docusign can send information to your Salesforce account.

dsAttributestring

dsLinkstring

A URL that links to the information in the DocuSign field.

dsNodestring

idstring

A unique ID for the Salesforce object.

sfFieldstring

sfFieldNamestring

The name of the Salesforce field.

sfFolderstring

The name of the Salesforce folder.

sfLockedValuestring

connectSalesforceObject

A connectSalesforceObject is an object that updates envelope and document status or recipient status in your Salesforce account.

When you install DocuSign Connect for Salesforce, the service automatically sets up two Connect objects: one that updates envelope status and documents and one that updates recipient status. You can also customize DocuSign Connect for Salesforce by associating DocuSign objects with Salesforce objects so that DocuSign Connect for Salesforce updates or inserts the information into the Salesforce object. For more information, see DocuSign for Salesforce - Adding Completed Documents to the Notes and Attachments.

activestring

When set to true, the connectSalesforceObject is active.

descriptionstring

A description of the connectSalesforceObject.

idstring

The id of the connectSalesforceObject.

insertstring

onCompleteOnlystring

When true, Salesforce is updated only when the envelope is complete.

selectFields[connectSalesforceField]

The DocuSign and Salesforce fields that you want to use to match a Salesforce object with DocuSign information. This information tells Connect when to send updates to Salesforce.

sfObjectstring

The Salesforce.com object type, such as case, contact, or opportunity.

sfObjectNamestring

A name for the Salesforce object.

Note: You can enter any name for the object. It does not have to match the sfObject property.

updateFields[connectSalesforceField]

The DocuSign and Salesforce fields that you want to update.

Note: You can choose to update SalesForce (with information from DocuSign) only, update DocuSign only, or both.

errorDetails

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

errorCodestring

The code associated with the error condition.

messagestring

A brief message describing the error condition.

ConnectConfigurations

Contains information about a DocuSign Connect configuration.

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.

allowSalesforcePublishstring

When set to true (default), DocuSign sends data to the designated Salesforce account through Connect.

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 fields are being used, specifies the type of the merge field. The only supported value is salesforce.

connectIdstring

The DocuSign-generated ID for the Connect configuration. This property is read only.

enableLogstring

When set to true, Connect logging is turned on. We recommend that you enable this functionality, which helps you 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 console.

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.

externalFolderIdstring

The id of an external folder.

externalFolderLabelstring

The label for an external folder.

includeCertificateOfCompletionstring

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

includeCertSoapHeaderstring

When set to true, a certificate for a SOAP header is included in messages sent through Connect.

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 attaches the envelope documents to the XML 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 in base64 XML element nodes, 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.

includeEnvelopeVoidReasonstring

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

includeHMACstring

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

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.

passwordstring

The user's encrypted password hash.

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.

requireMutualTlsstring

When set to true, Mutual TLS authentication is enabled.

requiresAcknowledgementstring

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

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

salesforceAccessTokenstring

The access token to use for Salesforce integration.

salesforceApiVersionstring

The version of the Salesforce API that you are using.

salesforceDocumentsAsContentFilesstring

When set to true, DocuSign can use documents in your Salesforce account for sending and signing.

salesforceRefreshTokenstring

The Saleforce OAuth refresh token that you use to get a new Salesforceaccess token (session ID). For more information, see OAuth 2.0 Refresh Token Flow.

senderOverridestring

senderSelectableItems[array]

This property sets the items that are available for selection when adding or editing Connect objects.

sfObjects[connectSalesforceObject]

An array of Salesforce objects.

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.

Note: If useSoapInterface is set to true, you must set this value.

urlToPublishTostring

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.

userIds[array]

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.

userNamestring

The name of the user.

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> 
}} />