JSON SIM event model (Connect 2.0)
Docusign Connect supports a recommended JSON Send Individual Messages (SIM) format, as well as Legacy event message formats. Unlike messages in the previous supported formats, the JSON SIM message format is event-focused rather than envelope-focused. This means that:
- By default, rather than getting a summary of the envelope in each message, the message contains data about the triggering event. This means that each message is much smaller, more focused on the data you request, more customizable, and easier to process. Depending on the event type, you may choose to include the envelope summary as well.
- You can track and subscribe to more types of events.
- You receive an event notification status at the time it occurs.
Because the JSON SIM format provides substantial benefits over aggregate message formats, it is recommended for all apps. The JSON SIM format is supported for both account- and envelope-level Connect as well as Recipient Connect.
Message structure
The JSON SIM message structure for all events will contain:
- An
eventelement, which identifies the event that generated the message. Developers who created workflows to be triggered by checking envelope status should use this element instead for JSON SIM. For example, a workflow that is triggered from"status": "sent"should now be triggered from"event": "envelope-sent". - An additional set of standard data that will be generated for each event. This set of data will be the same for all events.
- A
dataelement, which contains all of the data unique to the event that generated the message. The contents of thedataelement will differ depending on the event generated and the set of data that you choose to subscribe to through Docusign Connect.
For example, a data element for a template-deleted event would include accountId, templateId, userId, name, and created properties, while the data element for an envelope-sent event would include accountId, envelopeId, and envelopeSummary elements.
See the JSON SIM event reference for a full list of the possible data element structures.
The accompanying example shows the structure of a JSON SIM Connect message. In this case, the event was generated after sending an envelope, and it contains data on that envelope.
You can download and view the full JSON SIM event message schema from the Docusign GitHub.
Enable JSON SIM format
You can enable the JSON SIM message format for your account through the Connect UI or by making a POST call to the /restapi/v2.1/accounts/{{accountId}}/connect endpoint and specifying a DeliveryMode, EventData, and Events as shown in the example to the right.
- The Account or Recipient Connect example to the right shows a
POST/restapi/v2.1/accounts/{{accountId}}/connectAPI call body that can be used to activate the JSON SIM format and subscribe to all event types for account or recipient Connect. - The Envelope Connect example to the right demonstrates the syntax for enabling JSON SIM format for envelope-level configurations. This is defined within the envelope’s
eventNotificationobject, alongside the other envelope-level connect values.
You can define up to 20 Connect JSON Configuration profiles in your account. See Connect Configuration Limits for details.
Optionally include an envelope summary payload
In previous Connect message formats, an envelope summary would be returned with each event. You can configure your JSON SIM options to include a streamlined version of this summary alongside envelope and recipient events, although it is not returned by default.
Important: Returning envelope summary data alongside your events increases the payload size. These events can take more time to deliver, potentially delaying your workflows. As a result, returning envelope summary data is not recommended for use cases where event delivery speed is critical, such as for in-person scenarios.
To include a set of envelope summary data in envelope and recipient event messages, you can provide a set of includeData in the POST /restapi/v2.1/accounts/{{accountId}}/connect API call that you would use to Enable JSON SIM format. For example, the includeData block below includes most elements of the envelope summary:
See for Additional Data That Connect Messages Can Include details on each of the include_data options.
JSON SIM event reference
The structure of each event supported by the JSON SIM format is listed below. For each event, note the following data elements:
Additional elements unique to each event are listed following the examples.
Envelope events
envelope-completed
envelope-corrected
envelope-created
envelope-declined
envelope-deleted
envelope-delivered
envelope-discard
envelope-purge
envelope-removed
envelope-resent
envelope-sent
envelope-voided
envelope-reminder-sent
Recipient events
recipient-authenticationfailed
recipient-autoresponded
recipient-completed
recipient-declined
recipient-delegate
recipient-delivered
recipient-finish-later
recipient-reassign
recipient-resent
recipient-sent
Template events
template-created
template-deleted
template-modified
Elastic template events
click-agreed
click-declined
SMS events
sms-opt-in
sms-opt-out
Workflow Builder events
workflow-started
Note: The uri element contains an instance-specific URI that you can use to retrieve information on that instance, such as the input that triggered the workflow, for example.
workflow-failed
Note: The uri element contains an instance-specific URI that you can use to retrieve information on that instance, such as the input that triggered the workflow, for example.
workflow-completed
Note: The uri element contains an instance-specific URI that you can use to retrieve information on that instance, such as the input that triggered the workflow, for example.