--- title: "Submits a batch of historical envelopes for republish to a webhook." method: POST path: "/v2.1/accounts/{accountId}/connect/envelopes/publish/historical" tags: ["EnvelopePublish"] --- # Submits a batch of historical envelopes for republish to a webhook. `POST /v2.1/accounts/{accountId}/connect/envelopes/publish/historical` ## Request - Base URL: `https://www.docusign.net/restapi` - URL: `https://www.docusign.net/restapi/v2.1/accounts/{accountId}/connect/envelopes/publish/historical` - Auth: none declared This endpoint submits a batch of existing envelopes to a webhook of your choice. Set the webhook address with the `urlToPublishTo` request body parameter. This endpoint does not call an existing Connect configuration or create a new Connect listener to monitor new activity. It simply uses an ad hoc configuration to submit existing envelopes. You must include all the configuration data in the request body. The envelope data will always be transmitted in JSON format. XML, Salesforce, and eOriginal configuration types are not supported. Your request should match the following format: ``` { "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", "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 `processingStatus` will be set to `processing`. You can then view the status of each historical republish request in the [Bulk Actions Log](https://support.docusign.com/s/document-item?bundleId=pik1583277475390&topicId=nvf1648497452396.html). ## Path parameters - `accountId` string, required ## Request body - ConnectHistoricalEnvelopeRepublish: The request body for the `createHistoricalEnvelopePublishTransaction` endpoint. - `config` ConnectCustomConfiguration: The `connectCustomConfiguration` object describes a Connect configuration for your account. - `allowEnvelopePublish` string: Set this value to **true** to enable the webhook. The default property is **false.** - `allowSalesforcePublish` string: When **true,** Docusign sends data to the designated Salesforce account through Connect. The default value is **true.** This property is not used for the `createHistoricalEnvelopePublishTransaction` endpoint. - `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. This property is not used for the `createHistoricalEnvelopePublishTransaction` endpoint. - `allUsersExcept` string: This flag enables 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.** This property is not used for the `createHistoricalEnvelopePublishTransaction` endpoint. - `configurationType` string: The type of the configuration. Valid values: * `custom`: Creates an account-level configuration * `customrecipient`: Creates a Recipient Connect configuration * `salesforce` * `eOriginal` This property is required. - `connectId` string: The Docusign-generated ID for the Connect configuration. This property is read-only. - `deliveryMode` string: The delivery mode of the configuration. Valid values: * `SIM` * `Aggregate` This property is required. - `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. This property is required. - `enableOAuthPerConfiguration` string - `envelopeEvents` string[]: A list of envelope-level event statuses that will trigger Connect to send updates to the endpoint specified in the `url` property. When using any of [the legacy event message formats](/platform/webhooks/connect/legacy-message-formats/), you must include either the `envelopeEvents` property or the `recipientEvents` property. If you are instead using the [JSON SIM event model](/platform/webhooks/connect/json-sim-event-model/), use the [`events`](/docs/esign-rest-api/reference/connect/connectconfigurations/create/#schema__connectcustomconfiguration_events) property. The [possible event statuses](/platform/webhooks/connect/event-triggers/) are: * `Sent` * `Delivered` * `Completed` * `Declined` * `Voided` **Note:** These values are case-sensitive. This property is not used for the `createHistoricalEnvelopePublishTransaction` endpoint. - `eventData` ConnectEventData: This object lets you choose the data format of your Connect response. - `format` string: Reserved for Docusign. - `includeData` string[]: A string array of the data to be included. The default is the empty array `[]`. - `attachments`: Include attachments associated with the envelope. - `custom_fields`: Include the custom fields associated with the envelope. - `documents`: Include the documents associated with the envelope. - `extensions`: Include information about the email settings associated with the envelope. - `folders`: Include the folder where the envelope exists. - `payment_tabs`: Include the payment tabs associated with the envelope. - `powerform`: Include the PowerForms associated with the envelope. - `prefill_tabs`: Include the [pre-filled tabs](/docs/esign-rest-api/esign101/concepts/tabs/prefilled-tabs/) associated with the envelope. - `recipients`: Include the recipients associated with the envelope. - `tabs`: Include the tabs associated with the envelope. - `version` string: Set this property to `restv2.1` to return event data in JSON. If the property is not set, the event data will be returned in XML by default. - `events` string[]: 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` This property is not used for the `createHistoricalEnvelopePublishTransaction` endpoint. - `externalFolderId` string: The ID of an external folder. This property is not used for the `createHistoricalEnvelopePublishTransaction` endpoint. - `externalFolderLabel` string: The label for an external folder. This property is not used for the `createHistoricalEnvelopePublishTransaction` endpoint. - `groupIds` string[] - `includeCertificateOfCompletion` string: When **true,** the Connect Service includes the Certificate of Completion with completed envelopes. This property is not used for the `createHistoricalEnvelopePublishTransaction` endpoint. - `includeCertSoapHeader` string - `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. This property is not used for the `createHistoricalEnvelopePublishTransaction` endpoint. - `includeDocuments` string: Reserved for Docusign. - `includeEnvelopeVoidReason` string: When **true,** if the envelope is voided, the Connect Service notification will include the void reason, as entered by the person that voided the envelope. This property is not used for the `createHistoricalEnvelopePublishTransaction` endpoint. - `includeHMAC` string: When **true,** Connect will use HMAC to verify the request. This property is required. - `includeOAuth` string - `includeSenderAccountasCustomField` string: When **true,** Connect will include the sender account as custom field in the data. This property is not used for the `createHistoricalEnvelopePublishTransaction` endpoint. - `includeTimeZoneInformation` string: When **true,** Connect will include the envelope time zone information. This property is not used for the `createHistoricalEnvelopePublishTransaction` endpoint. - `integratorManaged` string - `name` string: The name of the Connect configuration. This property is required. - `oAuthConfiguration` ConnectOAuthConfig: A complex object describing a Connect OAuth configuration. - `authorizationServerUrl` string: The token URL for your authorization server or OAuth service. This property is required. - `clientId` string: The client ID assigned to your app by your authorization server or OAuth service. This property is required. - `clientSecret` string: The secret value provided by your authorization server. This property is required. - `customParameters` object - `scope` string: The scopes that your app will request from the authorization server. This property is optional. **Note:** If you are using Azure, this value is the application ID URI of the secified resource affixed with the `.default`. For example: `api://{{clientId}}/.default` - `password` string: The password for the Connect configuration. This property is not used for the `createHistoricalEnvelopePublishTransaction` endpoint. - `pausePublish` string - `recipientEvents` string[]: An array of recipient event statuses that will trigger Connect to send notifications to your webhook listener at the URL endpoint specified in the `url` property. When using any of [the legacy event message formats](/platform/webhooks/connect/legacy-message-formats/), you must include either the `envelopeEvents` property or the `recipientEvents` property. If you are instead using the [JSON SIM event model](/platform/webhooks/connect/json-sim-event-model/), use the `events` property. The [possible event statuses](/platform/webhooks/connect/event-triggers/) are: * `Sent` * `AutoResponded` * `Delivered` * `Completed` * `Declined` * `AuthenticationFailed` **Note:** These values are case-sensitive. This property is not used for the `createHistoricalEnvelopePublishTransaction` endpoint. - `requireMutualTls` string: When **true,** [Mutual TLS](/platform/webhooks/mutual-tls/) authentication is enabled. This property is not used for the `createHistoricalEnvelopePublishTransaction` endpoint. - `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. This property is required. - `salesforceApiVersion` string: The version of the Salesforce API that you are using. This property is not used for the `createHistoricalEnvelopePublishTransaction` endpoint. - `salesforceAuthcode` string - `salesforceCallBackUrl` string - `salesforceDocumentsAsContentFiles` string: When **true,** Docusign can use documents in your Salesforce account for sending and signing. This property is not used for the `createHistoricalEnvelopePublishTransaction` endpoint. - `senderOverride` string - `senderSelectableItems` string[]: This property sets the items that are available for selection when adding or editing Connect objects. This property is not used for the `createHistoricalEnvelopePublishTransaction` endpoint. - `sfObjects` ConnectSalesforceObject[]: An array of Salesforce objects. This property is not used for the `createHistoricalEnvelopePublishTransaction` endpoint. - `active` string: When **true,** the `connectSalesforceObject` is active. - `description` string: A description of the `connectSalesforceObject`. - `id` string: The ID of the `connectSalesforceObject`. - `insert` string - `onCompleteOnly` string: 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. - `dsAttribute` string - `dsLink` string: A URL that links to the information in the Docusign field. - `dsNode` string - `id` string: A unique ID for the Salesforce object. - `sfField` string - `sfFieldName` string: The name of the Salesforce field. - `sfFolder` string: The name of the Salesforce folder. - `sfLockedValue` string - `sfObject` string: The Salesforce.com object type, such as `case`, `contact`, or `opportunity`. - `sfObjectName` string: 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. - `dsAttribute` string - `dsLink` string: A URL that links to the information in the Docusign field. - `dsNode` string - `id` string: A unique ID for the Salesforce object. - `sfField` string - `sfFieldName` string: The name of the Salesforce field. - `sfFolder` string: The name of the Salesforce folder. - `sfLockedValue` string - `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. This property is required. - `soapNamespace` string: The namespace of the SOAP interface. **Note:** If `useSoapInterface` is set to **true,** you must set this value. This property is not used for the `createHistoricalEnvelopePublishTransaction` endpoint. - `urlToPublishTo` string: The web address of the listener or retrieving service endpoint. It must be an HTTPS URL. This property is required. - `userIds` string[]: 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. This property is not used for the `createHistoricalEnvelopePublishTransaction` endpoint. - `userName` string: The name of the user. This property is not used for the `createHistoricalEnvelopePublishTransaction` endpoint. - `useSoapInterface` string: When **true,** the notifications are sent to your endpoint as SOAP requests. This property is not used for the `createHistoricalEnvelopePublishTransaction` endpoint. - `envelopes` string[]: An array of envelope IDs as comma-separated strings. This property is required. For example: `["4280f274-xxxx-xxxx-xxxx-b218b7eeda08","9586h293-xxxx-xxxx-xxxx-m923b8opre71","2347w948-xxxx-xxxx-xxxx-t096b8krno89"]` ## Response `201` Successful response. ## Other responses - `400`: Error encountered. ## Changes - **2022-07-06** (v2) `26f0894c2b86`: 1 info - endpoint added - **2019-07-18** (v2) `8ad1b5a40f1b`: 1 breaking - api path removed without deprecation [Operation history](https://skmtc.dev/docusign/apis/docusign-esignature-rest-api/changes/v2.1/accounts/:accountId/connect/envelopes/publish/historical/post.md) --- [API](https://skmtc.dev/docusign/apis/docusign-esignature-rest-api.md) - [All operations](https://skmtc.dev/docusign/apis/docusign-esignature-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/docusign/apis/docusign-esignature-rest-api/revisions/77f1998c313d?raw)