Docusign eSignature API
Docusign Developer CenterGet a developer account
HomeAPI ReferenceSDKsContext Plugin
Envelope Documents

Adds or replaces a document in an existing envelope

PUT
/v2.1/accounts/{accountId}/envelopes/{envelopeId}/documents/{documentId}

Adds or replaces a document in an existing draft or in-process envelope. An in-process envelope is one that has been sent but not yet completed or voided.

Note: When adding or modifying documents for an in-process envelope, Docusign recommends locking the envelope prior to making any changes.

To add a new document, set the documentId path parameter to a new document ID.

To replace a document, set the documentId path parameter to the document ID of the existing document. The tabs of the original document will be applied to the new document. For example, a request in cURL looks like this:

$ curl --location --request PUT 'https://demo.docusign.net/restapi/v2.1/accounts/0cdb3ff3-xxxx-xxxx-xxxx-e43af011006d/envelopes/ea4cc25b-xxxx-xxxx-xxxx-a67a0a2a4f6c/documents/1' \    --header 'Authorization: Bearer eyJ...bqg' \    --header 'Content-Disposition: filename="newDocument"' \    --header 'Content-Type: application/pdf' \    --data-binary '@/location/of/document.pdf'

Authorization

OAuth2
AuthorizationBearer <token>

OAuth 2.0 access token obtained via Authorization Code Grant or JWT Grant.

In: header

Path Parameters

accountId*string

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

documentId*string

The unique ID of the document within the envelope.

Unlike other IDs in the eSignature API, you specify the documentId yourself. Typically the first document has the ID 1, the second document 2, and so on, but you can use any numbering scheme that fits within a 32-bit signed integer (1 through 2147483647).

Tab objects have a documentId property that specifies the document on which to place the tab.

envelopeId*string

The envelope's GUID.

Example: 93be49ab-xxxx-xxxx-xxxx-f752070d71ec

Header Parameters

Content-Type*"application/pdf"

Value in

  • "application/pdf"

Request Body

multipart/form-data

documentFileBytes*string

Updated document content.

Response Body

application/json

application/json

curl -X PUT "https://example.com/v2.1/accounts/string/envelopes/string/documents/string" \  -H "Content-Type: application/pdf" \  -F documentFileBytes="string"
{  "addedRecipientIds": [    "string"  ],  "agreementType": "string",  "agreementTypeSource": "string",  "attachmentTabId": "string",  "authoritativeCopy": "string",  "availableDocumentTypes": [    {      "isDefault": "string",      "type": "string"    }  ],  "containsPdfFormFields": "string",  "display": "string",  "docGenDocumentStatus": "string",  "docGenErrors": [    {      "errorCode": "string",      "message": "string",      "tagIdentifier": "string"    }  ],  "docGenFormFields": [    {      "connectedObjectDetails": {        "recordId": "string"      },      "defaultValue": "string",      "description": "string",      "filter": "string",      "format": {        "expression": "string",        "locale": "string"      },      "fullyQualifiedPath": "string",      "hidden": "string",      "label": "string",      "name": "string",      "options": [        {          "description": "string",          "label": "string",          "selected": "string",          "value": "string"        }      ],      "order": "string",      "predefinedValidation": "string",      "readOnly": "string",      "required": "string",      "rowValues": [        {          "docGenFormFieldList": [            {}          ]        }      ],      "type": "string",      "validation": {        "errorMessage": "string",        "expression": "string"      },      "value": "string"    }  ],  "documentBase64": "string",  "documentFields": [    {      "errorDetails": {        "errorCode": "string",        "message": "string"      },      "name": "string",      "originalValue": "string",      "value": "string"    }  ],  "documentId": "string",  "documentIdGuid": "string",  "documentTemplateId": "string",  "errorDetails": {    "errorCode": "string",    "message": "string"  },  "hasDigitalSignature": "string",  "includeInDownload": "string",  "isAceGenDocument": "string",  "isDocGenDocument": "string",  "isEdited": "string",  "isExternallyAvailable": "string",  "isFlattened": "string",  "name": "string",  "order": "string",  "pages": [    {      "dpi": "string",      "errorDetails": {        "errorCode": "string",        "message": "string"      },      "height": "string",      "imageBytes": "string",      "mimeType": "string",      "pageId": "string",      "sequence": "string",      "width": "string"    }  ],  "signerMustAcknowledge": "string",  "sizeBytes": "string",  "templateLocked": "string",  "templateRequired": "string",  "type": "string",  "uri": "string"}

Retrieves a single document or all documents from an envelope GET

Retrieves a single document or all documents from an envelope. To retrieve a single document, provide the ID of the document in the `documentId` path parameter. Alternatively, by setting the `documentId` parameter to special keyword values, you can retrieve all the documents (as a combined PDF, portfolio PDF, or ZIP archive) or just the certificate of completion. See the `documentId` description for how to retrieve each format. The response body of this method is a file. If you request multiple documents, the result is a ZIP archive that contains all of the documents. In all other cases, the response is a PDF file or PDF portfolio. You can get the file name and document ID from the response's `Content-Disposition` header: ``` Content-Disposition: file; filename="NDA.pdf"; documentid="1 ``` By default, the response is the PDF file as a byte stream. For example a request/response in `curl` looks like this: ``` $ curl --request GET 'https://demo.docusign.net/restapi/v2/accounts/0cdb3ff3-xxxx-xxxx-xxxx-e43af011006d/envelopes/ea4cc25b-xxxx-xxxx-xxxx-a67a0a2a4f6c/documents/1/' \ --header 'Authorization: Bearer eyJ...bqg' HTTP/1.1 200 OK Content-Length: 167539 Content-Type: application/pdf . . . Content-Disposition: file; filename="Lorem_Ipsum.pdf"; documentid="1" Date: Tue, 23 Aug 2022 01:13:15 GMT %PDF-1.4 %˚¸˝˛ 6 0 obj <</Length 14>>stream . . . ``` By using the `Content-Transfer-Encoding` header in the request, you can obtain the PDF file encoded in base64. The same `curl` request with the base64 header would look like this: ``` $ curl --request GET 'https://demo.docusign.net/restapi/v2/accounts/0cdb3ff3-xxxx-xxxx-xxxx-e43af011006d/envelopes/ea4cc25b-xxxx-xxxx-xxxx-a67a0a2a4f6c/documents/1/' \ --header 'Authorization: Bearer eyJ...bqg' \ --header 'Content-Transfer-Encoding: base64' HTTP/1.1 200 OK Content-Length: 223384 Content-Type: application/pdf . . . Content-Disposition: file; filename="Lorem_Ipsum.pdf"; documentid="1" Content-Transfer-Encoding: base64 Date: Tue, 23 Aug 2022 01:12:30 GMT JVBERi0xLjQKJfv8/f4KNiAwIG9iago8PC9MZW. . .== ``` (In an actual `curl` request you would use the `--output` switch to save the byte stream into a file.) ### Related topics - [How to download envelope documents](https://developers.docusign.com/docs/esign-rest-api/how-to/download-envelope-documents/)

Gets the email setting overrides for an envelope GET

Retrieves the email override settings for the specified envelope.