Add documents to envelope
Adds one or more documents to an existing envelope. The tabs of the original document will be applied to the new document.
Important: The updateList endpoint supports batch updates to envelope documents. A successful HTTP status does not guarantee that all documents were processed correctly. You must check the response for each envelopeDocument. If a document failed to update or add, its corresponding object will include an errorDetails indicating the reason for failure.
Note: When adding or modifying documents for an in-process envelope, Docusign recommends locking the envelope prior to making any changes.
If the file name of a document contains Unicode characters, you need to include a Content-Disposition header. Example:
Header: Content-Disposition
Value: file; filename=\"name\";fileExtension=ext;documentId=1
Note: This method works on documents only. To add recipient or document tabs, use methods from the EnvelopeRecipientTabs resource.
If HTML document files contain <img> elements with the src attribute set to a path or URL, those images will not be displayed. Images in HTML files must be encoded in Base64 format, like this:
<img src="data:image/gif;base64,R0lGODlh...IQAAOw==" alt="Base64 encoded image" width="150" height="150"/>
Related topics
Authentication
OAuth 2.0 access token (JWT or auth-code grant). Sent as
Authorization: Bearer <token> on every request except
GET /v2.1 and GET /service_information, which are
public discovery endpoints.
Path parameters
The external account number (int) or account ID Guid.
The envelope’s GUID.
Example: 93be49ab-xxxx-xxxx-xxxx-f752070d71ec
Request
This endpoint expects an object: envelopeDefinition
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.
When true, comments are allowed on the envelope.
When true, the Document Markup feature is enabled.
Note: To use this feature, Document Markup must be enabled at both the account and envelope levels. Only Admin users can change this setting at the account level.
When true, the recipient can redirect an envelope to a more appropriate recipient.
When true, this enables the Recursive Recipients feature and allows a recipient to appear more than once in the routing order.
When true, users can view the history of the envelope.
When 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 by
using the
transactionId or by checking the
Connect notification.
The ID of the brand, or text and formatting, to use for the envelope. To use brands, account branding must be enabled for the account.
Note: When creating an envelope using a branded template, include this value to ensure that the brand is applied.
When true, the brandId for the envelope is locked and senders cannot change the brand used for the envelope.
This value is only applicable when copying an existing envelope. Provide the ID of the envelope to clone in envelopeId.
When true, the recipient field values of the existing envelope are included. Only values from data entry fields, like checkboxes and radio buttons, will be copied. Fields that require an action, like signatures and initials, will not be included.
The date and time that the envelope was delivered to the recipient. This property is read-only.
When true, the responsive document feature is turned off for the envelope.
The document’s bytes. This field can be used to include a base64 version of the document bytes within an envelope definition instead of sending the document using a multi-part HTTP request. The maximum document size is smaller if this field is used due to the overhead of the base64 encoding.
This optional element holds the body of the email message that is sent to all envelope recipients.
Maximum Length: 10000 characters.
A complex element that allows the sender to override some envelope email setting information. This can be used to override the Reply To email address and name associated with the envelope and to override the BCC email addresses to which an envelope is sent.
When the emailSettings information is used for an envelope, it only applies to that envelope.
IMPORTANT: The emailSettings information is not returned in the GET for envelope status. Use GET /email_settings to return information about the emailSettings.
EmailSettings consists of:
- replyEmailAddressOverride - The Reply To email used for the envelope. DocuSign will verify that a correct email format is used, but does not verify that the email is active. Maximum Length: 100 characters.
- replyEmailNameOverride - The name associated with the Reply To email address. Maximum Length: 100 characters.
- bccEmailAddresses - An array of up to five email addresses to which the envelope is sent to as a BCC email. Only users with canManageAccount setting set to true can use this option. DocuSign verifies that the email format is correct, but does not verify that the email is active. Using this overrides the BCC for Email Archive information setting for this envelope. Maximum Length: 100 characters. Example: if your account has BCC for Email Archive set up for the email address ‘archive@mycompany.com’ and you send an envelope using the BCC Email Override to send a BCC email to ‘salesarchive@mycompany.com’, then a copy of the envelope is only sent to the ‘salesarchive@mycompany.com’ email address.
The subject line of the email message that is sent to all recipients.
For information about adding merge field information to the email subject, see Template Email Subject Merge Fields.
Note: The subject line is limited to 100 characters, including any merged fields.It is not truncated. It is an error if the text is longer than 100 characters.
When true, the signer is allowed to print the document and sign it on paper.
When true, the option selected in the Document Visibility section in your account Sending Settings will be enforced for the envelope. See Fields and Properties for details about document visibility options. Setting enforceSignerVisibility to true also enables you to omit documents from the specified recipients’ envelopes by using the excludedDocuments array. Recipients that have an administrative role (Agent, Editor, or Intermediaries) or informational role (Certified Deliveries or Carbon Copies) can always see all of the documents in an envelope, unless they are specifically excluded by using the excludedDocuments setting when an envelope is sent. Documents that do not have tabs are always visible to all recipients, unless they are excluded by using the excludedDocuments setting.
Note: To use this functionality, document visibility must be enabled for the account. The document visibility feature is available in all developer accounts, but only in certain production account plans. Contact Docusign Support or your account manager to find out whether document visibility is available for your production account plan.
The envelope ID.
When used as a request body in Envelopes: create, this is the ID of the envelope to clone.
When true, Envelope ID Stamping is enabled. After a document or attachment is stamped with an Envelope ID, the ID is seen by all recipients and becomes a permanent part of the document and cannot be removed.
Not used. Use the
expirations
property in the notification object instead.
Not used. Use the
expirations
property in the notification object instead.
Not used. Use the
expirations
property in the notification object instead.
When true, indicates that users have added comments to the envelope.
When true, indicates that the form data associated with the envelope has changed since it was sent. When false, this property does not appear in the response.
When true, indicates that a wave file (voice recording) is part of the envelope.
When true, indicates compliance with United States Food and Drug Administration (FDA) regulations on electronic records and electronic signatures (ERES).
When true, indicates that the envelope is a dynamic envelope.
When true, indicates that the envelope is a signature-provided envelope.
When 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.
The user’s password.
This property is used only when adding a new user via a Users: create request. The value must conform to the password rules defined in the account Security Settings.
This property is not returned by GET requests and cannot be updated via PUT requests.
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.documents_and_metadata_and_redact_queued: Places envelope documents and metadata in the purge queue and redacts personal information.
Related topics
When true, prevents senders from changing, correcting, or deleting the recipient information for the envelope.
The request body for the EnvelopeViews: createRecipient and EnvelopeViews: createSharedRecipient methods.
The UTC DateTime when the envelope was sent. This property is read-only.
When true, recipients can sign on a mobile device.
Note: Only Admin users can change this setting.
Specifies the physical location where the signing takes place. It can have two enumeration values; InPerson and Online. The default value is Online.
Indicates the envelope status. Valid values when creating an envelope are:
created: The envelope is created as a draft. It can be modified and sent later.sent: The envelope will be sent to the recipients after the envelope is created.
You can query these additional statuses once the recipients have interacted with the envelope.
completed: The recipients have finished working with the envelope: the documents are signed and all required tabs are filled in.declined: The envelope has been declined by the recipients.delivered: The envelope has been delivered to the recipients.signed: The envelope has been signed by the recipients.voided: The envelope is no longer valid and recipients cannot access or sign the envelope.
This object specifies the template recipients. Each roleName in the template must have a recipient assigned to it. This object is comprised of the following elements:
email: The recipient’s email address.name: The recipient’s name.roleName: The template roleName associated with the recipient.clientUserId: An optional property that specifies whether the recipient is embedded or remote. If theclientUserIdis not null, then the recipient is embedded. Note that if aclientUserIdis used and the account settingssignerMustHaveAccountorsignerMustLoginToSignare true, an error is generated on sending.defaultRecipient: Optional, When true, this recipient is the default recipient and any tabs generated by thetransformPdfFieldsoption 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. Maximum Length: 50 characters.inPersonSignerName: Optional. If the template role is an in-person signer, this is the full legal name of the signer. Maximum Length: 100 characters.emailNotification: This is an optional complex element that has a role-specificemailSubject,emailBody, andlanguage. It follows the same format as theemailNotificationproperty for recipients.tabs: This property enables the tab values to be specified for matching to tabs in the template.
Used to identify an envelope. The ID is a sender-generated value and is valid in the Docusign system for 7 days. Docusign recommends that you use a transaction ID for offline signing to ensure that an envelope is not sent multiple times. You can use the transactionId property to 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.
When true, the disclosure is shown to recipients in accordance with the account’s Electronic Record and Signature Disclosure frequency setting. When 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.
The reason the envelope or template was voided.
Note: The string is truncated to the first 200 characters.