> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL. > > Documentation indexes by section: > - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt > - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt > - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt > - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt > > Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth > Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks > > OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json > MCP server: https://docusign.docs.buildwithfern.com/_mcp/server # Envelopes Resource The Envelope resource provides methods that allow you to manipulate and monitor envelopes. Once you have authenticated the user you can use the Envelopes: createEnvelope method to create an envelope. You can call the EnvelopeDocuments: update or EnvelopeDocuments: updateList method to add additional documents. Setting the `status` property on the envelope to `sent` allows you to send it or `created` to save it as a draft. You can receive envelope event notifications by setting the `eventNotification` properties. When the envelope or recipient status changes to one of the specified status codes, a notification is sent to a URL that you specify. If you have an envelope that you have previously saved, you can modify the subject and message, send it, void it, or place it in the purge queue using the Envelope: update method. In addition to receiving notifications you can monitor the status of the envelopes using the following methods: * Envelope: getEnvelope - To get the status of a envelope. * Envelope: listStatus - To get the envelope status for a set of envelopes. * Envelope: listStatusChanges - To get status changes information for one or more envelopes. If you need to delete a page from a document in an envelope, use the Envelope: deleteDocumentPage method. The resource also includes a number of methods that allow you to retrieve and set the initials and signature for certain types of recipients on the document. ## Methods supported | Method | Description | | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [create](/docs/esign-rest-api/reference/envelopes/envelopes/create) | POST `/restapi/v2.1/accounts/{accountId}/envelopes` Creates an envelope. | | [deleteDocumentPage](/docs/esign-rest-api/reference/envelopes/envelopes/deletedocumentpage) | DEL `/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/documents/{documentId}/pages/{pageNumber}` Deletes a page from a document in an envelope. | | [get](/docs/esign-rest-api/reference/envelopes/envelopes/get) | GET `/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}` Gets the status of a single envelope. | | [getNotificationSettings](/docs/esign-rest-api/reference/envelopes/envelopes/getnotificationsettings) | GET `/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/notification` Gets envelope notification information. | | [getPageImage](/docs/esign-rest-api/reference/envelopes/envelopes/getpageimage) | GET `/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/documents/{documentId}/pages/{pageNumber}/page_image` Gets a page image from an envelope for display. | | [getPageImages](/docs/esign-rest-api/reference/envelopes/envelopes/getpageimages) | GET `/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/documents/{documentId}/pages` Returns document page images based on input. | | [getRecipientInitialsImage](/docs/esign-rest-api/reference/envelopes/envelopes/getrecipientinitialsimage) | GET `/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients/{recipientId}/initials_image` Gets the initials image for a user. | | [getRecipientSignature](/docs/esign-rest-api/reference/envelopes/envelopes/getrecipientsignature) | GET `/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients/{recipientId}/signature` Gets signature information for a signer or sign-in-person recipient. | | [getRecipientSignatureImage](/docs/esign-rest-api/reference/envelopes/envelopes/getrecipientsignatureimage) | GET `/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients/{recipientId}/signature_image` Retrieve signature image information for a signer/sign-in-person recipient. | | [listAuditEvents](/docs/esign-rest-api/reference/envelopes/envelopes/listauditevents) | GET `/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/audit_events` Gets the envelope audit events for an envelope. | | [listStatus](/docs/esign-rest-api/reference/envelopes/envelopes/liststatus) | PUT `/restapi/v2.1/accounts/{accountId}/envelopes/status` Gets envelope statuses for a set of envelopes. | | [listStatusChanges](/docs/esign-rest-api/reference/envelopes/envelopes/liststatuschanges) | GET `/restapi/v2.1/accounts/{accountId}/envelopes` Search for specific sets of envelopes by using search filters. | | [rotateDocumentPage](/docs/esign-rest-api/reference/envelopes/envelopes/rotatedocumentpage) | PUT `/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/documents/{documentId}/pages/{pageNumber}/page_image` Rotates page image from an envelope for display. | | [update](/docs/esign-rest-api/reference/envelopes/envelopes/update) | PUT `/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}` Send, void, or modify a draft envelope. Purge documents from a completed envelope. | | [updateNotificationSettings](/docs/esign-rest-api/reference/envelopes/envelopes/updatenotificationsettings) | PUT `/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/notification` Sets envelope notifications for an existing envelope. | | [updateRecipientInitialsImage](/docs/esign-rest-api/reference/envelopes/envelopes/updaterecipientinitialsimage) | PUT `/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients/{recipientId}/initials_image` Sets the initials image for an accountless signer. | | [updateRecipientSignatureImage](/docs/esign-rest-api/reference/envelopes/envelopes/updaterecipientsignatureimage) | PUT `/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients/{recipientId}/signature_image` Sets the signature image for an accountless signer. | ## Envelopes properties | Property | Type | Description | | ----------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `accessControlListBase64` | string | Reserved for Docusign. | | `allowComments` | string | When **true,** users can add comments to the documents in the envelope. For example, if a signer has a question about the text in the document, they can add a comment to the document. | | `allowMarkup` | string | 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. | | `allowReassign` | string | When **true,** the recipient can redirect an envelope to a more appropriate recipient. | | `allowViewHistory` | string | When **true,** recipients can view the history of the envelope. | | `anySigner` | string | Deprecated. This feature has been replaced by signing groups. | | `asynchronous` | string | 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](/docs/esign-rest-api/reference/envelopes/envelopes/create) or by checking the Connect notification. | | `attachmentsUri` | string | Contains a URL for retrieving the attachments that are associated with the envelope. | | `authoritativeCopy` | string | When **true,** marks all of the documents in the envelope as authoritative copies. **Note:** You can override this value for a specific document. For example, you can set the `authoritativeCopy` property to **true** at the envelope level, but turn it off for a single document by setting the `authoritativeCopy` property for the document to **false.** | | `authoritativeCopyDefault` | string | 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`. | | `autoNavigation` | string | When **true,** autonavigation is set for the recipient. | | `brandId` | string | The ID of the brand. | | `brandLock` | string | When **true,** the `brandId` for the envelope is locked and senders cannot change the brand used for the envelope. | | `burnDefaultTabData` | string | | | `certificateUri` | string | The URI for retrieving certificate information. | | `completedDateTime` | string | Specifies the date and time this item was completed. | | `copyRecipientData` | string | | | `createdDateTime` | string | The UTC DateTime when the item was created. | | `customFields` | AccountCustomFields | An optional array of strings that enables the sender to provide custom data about the recipient. This information is returned in the envelope status but otherwise not used by Docusign. Each `customField` string can be a maximum of 100 characters. | | `customFieldsUri` | string | The URI for retrieving custom fields. | | `declinedDateTime` | string | The date and time the recipient declined the document. This property is read-only. | | `deletedDateTime` | string | Reserved for Docusign. | | `deliveredDateTime` | string | The date and time that the envelope was delivered to the recipient. This property is read-only. | | `disableResponsiveDocument` | string | When **true,** responsive documents are disabled for the envelope. | | `documentBase64` | string | 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. | | `documentsCombinedUri` | string | The URI for retrieving all of the documents associated with the envelope as a single PDF file. | | `documentsUri` | string | The URI for retrieving all of the documents associated with the envelope as separate files. | | `emailBlurb` | string | This is the same as the email body. If specified it is included in the email body for all envelope recipients. | | `emailSettings` | emailSettings | 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 method for envelope status. Use GET /email_settings to return information about the email settings. | | `emailSubject` | string | 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](/docs/esign-rest-api/reference/templates/templates/create#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. | | `enableWetSign` | string | When **true,** the signer is allowed to print the document and sign it on paper. | | `enforceSignerVisibility` | string | When **true,** the option selected in the **Document Visibility** section in your account [Sending Settings](https://admindemo.docusign.com/authenticate?goTo=sending) will be enforced for the envelope. See [Fields and Properties](https://support.docusign.com/s/document-item?rsc_301\&bundleId=pik1583277475390\&topicId=xgg1583277350154.html) 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`](/docs/esign-rest-api/reference/envelopes/envelopes/create#schema__envelopedefinition_recipients_signers_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](/docs/esign-rest-api/reference/envelopes/envelopedocumentvisibility) 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](https://support.docusign.com/en/contactSupport#) or your account manager to find out whether document visibility is available for your production account plan. | | `envelopeAttachments` | array | An array of attachment objects that provide information about the attachments that are associated with the envelope. | | `envelopeCustomMetadata` | envelopeCustomMetadata | | | `envelopeDocuments` | array | An array containing information about the documents that are included in the envelope. | | `envelopeId` | string | The envelope ID of the envelope status that failed to post. | | `envelopeIdStamping` | string | When **true,** [Envelope ID Stamping](https://support.docusign.com/s/document-item?bundleId=gbo1643332197980\&topicId=tfm1578456367923.html) 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. | | `envelopeLocation` | string | Reserved for Docusign. | | `envelopeMetadata` | envelopeMetadata | Metadata that indicates whether the `envelope` property is editable. | | `envelopeUri` | string | The URI for retrieving the envelope or envelopes. | | `expireAfter` | string | Not used. Use the [`expirations`](/docs/esign-rest-api/reference/envelopes/envelopes/create#definition__envelopedefinition_notification_expirations) property in the [`notification`](/docs/esign-rest-api/reference/envelopes/envelopes/create#definition__envelopedefinition_notification) object instead. | | `expireDateTime` | string | Not used. Use the [`expirations`](/docs/esign-rest-api/reference/envelopes/envelopes/create#definition__envelopedefinition_notification_expirations) property in the [`notification`](/docs/esign-rest-api/reference/envelopes/envelopes/create#definition__envelopedefinition_notification) object instead. | | `expireEnabled` | string | Not used. Use the [`expirations`](/docs/esign-rest-api/reference/envelopes/envelopes/create#definition__envelopedefinition_notification_expirations) property in the [`notification`](/docs/esign-rest-api/reference/envelopes/envelopes/create#definition__envelopedefinition_notification) object instead. | | `externalEnvelopeId` | string | May contain an external identifier for the envelope. | | `folders` | array | A list of folder objects. | | `hasComments` | string | When **true,** indicates that users have added comments to the envelope. | | `hasFormDataChanged` | string | Specifies if the `EnvelopeFormData` associated with any forms in the envelope has changed. | | `hasWavFile` | string | When **true,** indicates that a .wav file used for voice authentication is included in the envelope. | | `holder` | string | Reserved for Docusign. | | `initialSentDateTime` | string | The date and time the envelope was initially sent. | | `is21CFRPart11` | string | When **true,** indicates compliance with United States Food and Drug Administration (FDA) regulations on electronic records and electronic signatures (ERES). | | `isDynamicEnvelope` | string | When **true,** indicates that the envelope is a dynamic envelope. | | `isSignatureProviderEnvelope` | string | When **true,** indicates that the envelope is a signature-provided envelope. | | `isTicketRelatedEnvelope` | string | | | `lastModifiedDateTime` | string | The date and time that the item was last modified. | | `location` | string | Reserved for Docusign. | | `lockInformation` | EnvelopeLocks | Provides lock information about an envelope that a user has locked. | | `messageLock` | string | 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. | | `notification` | notification | A complex element that specifies the notification options for the envelope. It consists of:- useAccountDefaults - When **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 **true,** a reminder message is sent to the recipient. - reminderDelay - An integer that sets the number of days after the recipient receives the envelope that reminder emails are sent to the recipient. - reminderFrequency - An integer 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 **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. When 0 (zero), no warning email is sent. | | `notificationUri` | string | The URI for retrieving notifications. | | `powerForm` | powerForm | Information about any PowerForms that are included in the envelope. | | `purgeCompletedDate` | string | The date that a purge was completed. | | `purgeRequestDate` | string | The date that a purge was requested. | | `purgeState` | string | Shows the current purge state for the envelope. Valid values:- `unpurged`: There has been no successful request to purge documents. - `documents_queued`: The envelope documents have been added to the purge queue, but have not been purged. - `documents_dequeued`: The envelope documents have been taken out of the purge queue. - `documents_purged`: The envelope documents have been successfully purged. - `documents_and_metadata_queued`: The envelope documents and metadata have been added to the purge queue, but have not yet been purged. - `documents_and_metadata_purged`: The envelope documents and metadata have been successfully purged. - `documents_and_metadata_and_redact_queued`: The envelope documents and metadata have been added to the purge queue, but have not yet been purged, nor has personal information been redacted. - `documents_and_metadata_and_redact_purged`: The envelope documents and metadata have been successfully purged, and personal information has been redacted.**Related topics**- [Purging documents (eSingature Concepts)](/docs/esign-rest-api/esign101/concepts/documents/purging) - [Purging documents in an envelope (blog post)](https://www.docusign.com/blog/developers/purging-documents-envelope) | | `recipients` | EnvelopeRecipients | An array of recipient objects that provides details about the recipients of the envelope. | | `recipientsLock` | string | When **true,** prevents senders from changing, correcting, or deleting the recipient information for the envelope. | | `recipientsUri` | string | Contains a URI for an endpoint that you can use to retrieve the recipients. | | `sender` | userInfo | Information about the sender of the envelope. | | `sentDateTime` | string | The UTC DateTime when the envelope was sent. This property is read-only. | | `signerCanSignOnMobile` | string | When **true,** recipients can sign on a mobile device. **Note:** Only Admin users can change this setting. | | `signingLocation` | string | Specifies the physical location where the signing takes place. It can have two enumeration values; `inPerson` and `online`. The default value is `online`. | | `status` | string | * `completed`: The recipients have finished working with the envelope: the documents are signed and all required tabs are filled in. * `created`: The envelope is created as a draft. It can be modified and sent later. * `declined`: The envelope has been declined by the recipients. * `delivered`: The envelope has been delivered to the recipients. * `sent`: The envelope will be sent to the recipients after the envelope is created. * `signed`: The envelope has been signed by the recipients. * `voided`: The envelope is no longer valid and recipients cannot access or sign the envelope. | | `statusChangedDateTime` | string | The data and time that the status changed. | | `templatesUri` | string | The URI for retrieving the templates. | | `transactionId` | string | 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. | | `useDisclosure` | string | 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. | | `uSigState` | string | | | `voidedDateTime` | string | The date and time the envelope or template was voided. | | `voidedReason` | string | The reason the envelope or template was voided. **Note:** The string is truncated to the first 200 characters. | | `watermarkLanguage` | string | | | `workflow` | workflow | | ## API Docs - Envelopes [Create envelope](https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/create.md) - Envelopes [Delete page from document in envelope](https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/deletedocumentpage.md) - Envelopes [Get status of single envelope](https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/get.md) - Envelopes [Get envelope notification information](https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/getnotificationsettings.md) - Envelopes [Get page image from envelope for display](https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/getpageimage.md) - Envelopes [Get document page image based on input](https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/getpageimages.md) - Envelopes [Get initials image](https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/getrecipientinitialsimage.md) - Envelopes [Get recipient signature](https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/getrecipientsignature.md) - Envelopes [Get recipient signature image](https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/getrecipientsignatureimage.md) - Envelopes [Get envelope audit events](https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/listauditevents.md) - Envelopes [Get envelope statuses for set of envelopes](https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/liststatus.md) - Envelopes [List envelope status changes](https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/liststatuschanges.md) - Envelopes [Rotate page image from envelope for display](https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/rotatedocumentpage.md) - Envelopes [Send, void, or modify draft envelope](https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/update.md) - Envelopes [Set envelope notifications](https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/updatenotificationsettings.md) - Envelopes [Set initials image for accountless signer](https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/updaterecipientinitialsimage.md) - Envelopes [Set signature image for accountless signer](https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/updaterecipientsignatureimage.md) ## OpenAPI Specification The raw OpenAPI 3.1 specification for this API is available at: - [OpenAPI JSON](https://developers.docusign.com/openapi.json) - [OpenAPI YAML](https://developers.docusign.com/openapi.yaml)