Skip to navigation
Docusign eSignature REST APIEnvelopesEnvelopeDocuments

Add documents to envelope

View as Markdown

Adds one or more documents to an existing envelope document. <p>Note: When adding or modifying documents for an in-process envelope, DocuSign recommends locking the envelope prior to making any changes.

Authentication

Authorizationstring

OAuth 2.0 access token (JWT or auth-code grant). Sent as Authorization: Bearer <token>.

Path parameters

accountIdstringRequired

The external account number (int) or account id GUID.

envelopeIdstringRequired

The envelope’s GUID. Eg 93be49ab-afa0-4adf-933c-f752070d71ec

Query parameters

apply_document_fieldsstringOptional

When true, document fields can be added or modified while adding or modifying envelope documents.

persist_tabsstringOptional

Request

This endpoint expects an object: envelopeDefinition

accessibilitystringOptional

Sets the document reading zones for screen reader applications. This element can only be used if Document Accessibility is enabled for the account.

Note: This information is currently generated from the DocuSign web console by setting the reading zones when creating a template, exporting the reading zone string information, and adding it here.
allowMarkupstringOptional

When set to true, Document Markup is enabled for envelope. Account must have Document Markup enabled to use this

allowReassignstringOptional

When set to true, the recipient can redirect an envelope to a more appropriate recipient.

allowRecipientRecursionstringOptional

When set to true, this enables the Recursive Recipients feature and allows a recipient to appear more than once in the routing order.

allowViewHistorystringOptional
asynchronousstringOptional

When set to true, the envelope is queued for processing and the value of the status property is set to ‘Processing’. Additionally, get status calls return ‘Processing’ until completed.

Note: A transactionId is required for this call to work correctly. When the envelope is created, the status is ‘Processing’ and an envelopeId is not returned in the response. To get the envelopeId, use a GET envelope query using the transactionId or by checking the Connect notification.

attachmentslist of objectsOptional
attachmentsUristringOptional
authoritativeCopystringOptional

Specifies whether all documents in this envelope are authoritative copies. A document can set its own authoritativeCopy property to override this value. For example you can set the authoritativeCopy on an envelope level to true but can turn it off for a specific document.

authoritativeCopyDefaultstringOptional

The default authoritativeCopy setting for documents in this envelope that do not have authoritativeCopy set. If this property is not set, each document defaults to the envelope’s authoritativeCopy.

autoNavigationstringOptional

When set to true, autonavigation is set for the recipient.

brandIdstringOptional
This sets the brand profile format used for the envelope. The value in the string is the brandId associated with the profile. Account branding must be enabled for the account to use this option.
brandLockstringOptional
certificateUristringOptional
Retrieves a URI for an endpoint allowing you to easily retrieve certificate information.
completedDateTimestringOptional
Specifies the date and time this item was completed.
compositeTemplateslist of objectsOptional
A complex type that can be added to create envelopes from a combination of DocuSign templates and PDF forms. The basic envelope remains the same, while the Composite Template adds new document and template overlays into the envelope. There can be any number of Composite Template structures in the envelope.
copyRecipientDatastringOptional
createdDateTimestringOptional
Indicates the date and time the item was created.
customFieldsobjectOptional
Custom Fields
customFieldsUristringOptional
Contains a URI for an endpoint to retrieve the custom fields.
declinedDateTimestringOptional
The date and time the recipient declined the document. Read only.
deletedDateTimestringOptional
Specifies the data and time the item was deleted.
deliveredDateTimestringOptional

Reserved: For DocuSign use only.

disableResponsiveDocumentstringOptional
documentslist of objectsOptional
Complex element contains the details on the documents in the envelope.
documentsCombinedUristringOptional
documentsUristringOptional
Contains a URI for an endpoint that you can use to retrieve the documents.
emailBlurbstringOptional
Optional element. This is the same as the email body. If specified it is included in email body for all envelope recipients. This can be a maximum of 10000 characters
emailSettingsobjectOptional
emailSubjectstringOptional

Specifies the subject of the email that is sent to all recipients.

See [ML:Template Email Subject Merge Fields] for information about adding merge field information to the email subject.

enableWetSignstringOptional

When set to true, the signer is allowed to print the document and sign it on paper.

enforceSignerVisibilitystringOptional

When set to true, documents with tabs can only be viewed by signers that have a tab on that document. Recipients that have an administrative role (Agent, Editor, or Intermediaries) or informational role (Certified Deliveries or Carbon Copies) can always see all the documents in an envelope, unless they are specifically excluded using this setting when an envelope is sent. Documents that do not have tabs are always visible to all recipients, unless they are specifically excluded using this setting when an envelope is sent.

Note: Your account must have Document Visibility enabled to use this.
envelopeIdstringOptional
The envelope ID of the envelope status that failed to post.
envelopeIdStampingstringOptional

When set to true, Envelope ID Stamping is enabled.

envelopeUristringOptional
Contains a URI for an endpoint that you can use to retrieve the envelope or envelopes.
eventNotificationobjectOptional
Register a Connect webhook for a specific envelope
initialSentDateTimestringOptional
is21CFRPart11stringOptional

When set to true, indicates that this module is enabled on the account.

isSignatureProviderEnvelopestringOptional
lastModifiedDateTimestringOptional
The date and time the item was last modified.
lockInformationobjectOptional
Envelope locks
messageLockstringOptional

When set to true, prevents senders from changing the contents of emailBlurb and emailSubject properties for the envelope.

Additionally, this prevents users from making changes to the contents of emailBlurb and emailSubject properties when correcting envelopes.

However, if the messageLock node is set to true and the emailSubject property is empty, senders and correctors are able to add a subject to the envelope.

notificationobjectOptional

A complex element that specifies the notification options for the envelope. It consists of:

  • useAccountDefaults - When set to true, the account default notification settings are used for the envelope.

  • reminders - A complex element that specifies reminder settings for the envelope. It consists of:

    • reminderEnabled - When set to true, a reminder message is sent to the recipient.
    • reminderDelay - An interger that sets the number of days after the recipient receives the envelope that reminder emails are sent to the recipient.
    • reminderFrequency - An interger that sets the interval, in days, between reminder emails.

  • expirations - A complex element that specifies the expiration settings for the envelope. It consists of:

    • expireEnabled - When set to true, the envelope expires (is no longer available for signing) in the set number of days. If false, the account default setting is used. If the account does not have an expiration setting, the DocuSign default value of 120 days is used.
    • expireAfter - An integer that sets the number of days the envelope is active.
    • expireWarn - An integer that sets the number of days before envelope expiration that an expiration warning email is sent to the recipient. If set to 0 (zero), no warning email is sent.
notificationUristringOptional
Contains a URI for an endpoint that you can use to retrieve the notifications.
passwordstringOptional
purgeStatestringOptional

Initiates a purge request. Valid values are:

  • documents_queued - Places envelope documents in the purge queue.
  • documents_and_metadata_queued - Places envelope documents and metadata in the purge queue.
recipientsobjectOptional
Envelope recipients
recipientsLockstringOptional

When set to true, prevents senders from changing, correcting, or deleting the recipient information for the envelope.

recipientsUristringOptional
Contains a URI for an endpoint that you can use to retrieve the recipients.
sentDateTimestringOptional
The UTC DateTime when the envelope was sent. Read only.
signerCanSignOnMobilestringOptional
signingLocationstringOptional

Specifies the physical location where the signing takes place. It can have two enumeration values; InPerson and Online. The default value is Online.

statusstringOptional

Indicates the envelope status. Valid values are:

  • sent - The envelope is sent to the recipients.
  • created - The envelope is saved as a draft and can be modified and sent later.
statusChangedDateTimestringOptional
The data and time the status changed.
templateIdstringOptional
The unique identifier of the template. If this is not provided, DocuSign will generate a value.
templateRoleslist of objectsOptional

Specifies the template recipients. Each roleName in the template must have a recipient assigned to it. This is made up by the following elements:

  • email - The recipient’s email address.
  • name - The recipient’s name.
  • roleName - The template roleName associated with the recipient.
  • clientUserId - Optional, this sets if the signer is This specifies if the recipient is embedded or remote. If the clientUserId is not null then the recipient is embedded. Note that if a ClientUserId is used and the account settings SignerMustHaveAccount or SignerMustLoginToSign are true, an error is generated on sending.
  • defaultRecipient - Optional, When set to true, this recipient is the default recipient and any tabs generated by the transformPdfFields option are mapped to this recipient.
  • routingOrder - This specifies the routing order of the recipient in the envelope.
  • accessCode - This optional element specifies the access code a recipient has to enter to validate the identity. This can be a maximum of 50 characters.
  • inPersonSignerName - Optional, if the template role is an in person signer, this is the full legal name of the signer. This can be a maximum of 100 characters.
  • emailNotification - This is an optional complex element that has a role-specific emailSubject, emailBody, and language. It follows the same format as the emailNotification node for Recipients.
  • tabs - This allows the tab values to be specified for matching to tabs in the template.
templatesUristringOptional
Contains a URI for an endpoint which you can use to retrieve the templates.
transactionIdstringOptional

Used to identify an envelope. The id is a sender-generated value and is valid in the DocuSign system for 7 days. It is recommended that a transaction ID is used for offline signing to ensure that an envelope is not sent multiple times. The transactionId property can be used determine an envelope’s status (i.e. was it created or not) in cases where the internet connection was lost before the envelope status was returned.

useDisclosurestringOptional

When set to true, the disclosure is shown to recipients in accordance with the account’s Electronic Record and Signature Disclosure frequency setting. When set to false, the Electronic Record and Signature Disclosure is not shown to any envelope recipients.

If the useDisclosure property is not set, then the account’s normal disclosure setting is used and the value of the useDisclosure property is not returned in responses when getting envelope information.

voidedDateTimestringOptional
The date and time the envelope or template was voided.
voidedReasonstringOptional
The reason the envelope or template was voided.

Response

Successful response.
envelopeDocumentslist of objectsOptional
envelopeIdstringOptional

The envelope’s GUID. Eg 93be49ab-afa0-4adf-933c-f752070d71ec

Errors

400
Bad Request Error