From the Trenches: Bulk publish historical envelopes using Docusign Connect

•

Summary•5 min read

See how to use Docusign Connect messages to export completed envelopes in bulk, using a CSV file you upload to the user interface or directly via an API call.

Through the user interface
Through the eSignature REST API
Through the Organization-Connect interface
Additional resources

Through the user interface
Through the eSignature REST API
Through the Organization-Connect interface

Additional resources

Docusign Connect is a webhook service that enables you to receive updates when specific triggering events occur in your eSignature workflows.

To use a Connect webhook, you must set up a web service (known as a webhook listener) that is available on the public internet. When a subscribed event occurs, Docusign Connect sends an HTTPS POST request to your webhook listener and your app uses the sent information to perform actions.

Docusign Connect also enables you to publish messages for envelopes in your account in bulk. This is particularly useful if you need to take your listener offline for maintenance and want a mechanism to catch up quickly to missed messages. It can also be used as a way to archive all the historical envelopes in your account.

There are two ways of publishing envelopes in bulk. I will detail the steps involved in both below.

Through the Docusign eSignature user interface
Through the eSignature REST API
Through the Organization-level Connect interface

Through the user interface

Log in to your Docusign account with a user who has administrative privileges.
Select Admin in the top menu.
Navigate to “Connect” under “Integrations” in the left nav.
In the Connect section, select Publish > Publish using CSV.
Here, you can upload a CSV file containing a list of envelope IDs you want to publish along with the configuration ID of the listener you would like to target.

You can publish up to a maximum of 9999 envelopes using a CSV file per hour.

Here's an example CSV file:

EnvelopeId, ConfigurationId
59xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, 1xxxxxxxx
28xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, 1xxxxxxxx
03xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, 1xxxxxxxx
46xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, 1xxxxxxxx

How to find your Connect configuration ID:

Log in to your Docusign account with a user who has administrative privileges.
Select Admin in the top menu.
Navigate to “Connect” under “Integrations” in the left nav.
In the “Configurations” section, all your configurations will be listed with their Configuration ID:

Through the eSignature REST API

If you have an existing integration with Docusign, you can use the EnvelopePublish : createHistoricalEnvelopePublishTransaction endpoint to submit a batch of envelopes to a URL of your choice. It does not need to be an existing configuration on your account. This endpoint uses an ad hoc configuration to publish the envelopes requested. This endpoint only supports publishing messages in JSON SIM event model format and cannot support legacy, Salesforce, or eOriginal configurations. For legacy, Salesforce, or eOriginal configurations, you would need to use the UI as described previously.

Here’s an example request to this endpoint:

{
    "envelopes": ["4280f274-xxxx-xxxx-xxxx-b218b7eeda08", "8373a938-xxxx-xxxx-xxxx-e992a2abae01"],
    "config": {
        "configurationType":"custom",
        "name": "Test",
        "urlToPublishTo":"YOUR-WEBHOOK-URL",
        "allowEnvelopePublish": "true",
        "enableLog": "true",
        "requiresAcknowledgement": "true",
        "IncludeHMAC": "true",
        "SignMessageWithX509Cert": "true",
        "deliveryMode": "SIM", // Send Individual message for each event. 
        "eventData": {
            "version": "restv2.1",
            "format": "json",
            "includedata": ["tabs","payment_tabs","custom_fields","powerform","recipients","folders","extensions","attachments", "prefill_tabs", "documents"]
        }
    }
}

If the request succeeds, it returns a 201 (Created) HTTP response code, and the response body property processingStatuswill be set to processing. You can then view the status of each historical republish request in the Bulk Actions Log.

Once you’ve successfully set up the request, the envelopes will be sequentially queued for processing, and you will see events flowing into your listener as soon as the processing finishes.

Through the Organization-Connect interface

If you have Organization-Level Connect configurations defined for your organization, you can do a bulk republish to those configurations as well, via the organization admin interface. To do this

Log in to your Docusign account with a user who has Organization administrative privileges.
Select Admin in the top menu.
Select to the Organization option in the top left.
Select the Bulk Actions option under Admin Home.
Select the three dots in the top right corner of the Connect Republish section, then on the Publish using CSV option that appears in the dropdown.
Here, you can upload a CSV file in the format mentioned below. There is also a CSV template available for you to download and view. You can instead use your own CSV file by selecting Upload File, but it must contain the required headers:

envelopeID – The envelope ID associated with the accountID.
accountID – Long AccountID GUID. You can add multiple account IDs and envelopes per site.
configurationID – This is the Organization’s configuration ID, which is located on the Organization-Level Connect homepage.
site – You can apply only one site (for example, NA1, NA2, NA3, NA4, EU, AU, CA, JP1) in the CSV file. The same site must be used in each row.

Note: You can only publish to Organization-Connect configurations from the Organization Bulk Actions menu.

You can publish up to a maximum of 19999 envelopes using a CSV file per hour.

How to find your Organization Connect configuration ID:

Log in to your Docusign account with a user who has Organization administrative privileges.
Select Admin in the top menu.
Select the Organization option in the top left of the window.
Scroll to and select Connect (Webhooks) under the Integrations tab.
Under the Configurations section, open the Filtered by dropdown, select Organization, then click Apply.
You can then see all your Organization-level Connect configurations with their configuration IDs, which you can use in your CSV.

It is currently not possible to do a bulk republish for Organization-level connect configurations via the API.

Additional resources

Karan KaushikDeveloper Support Engineer

Karan Kaushik began his Docusign career in January 2022. As a front-line developer support engineer, Karan enjoys working on complex technical problems. He is passionate about using technology to make people's day-to-day lives easier and simpler, leveraging his array of experience across information technology, cloud operations, and software development.