Files and external documents

This document explains how to upload files and use them in DocStudio envelopes.

Upload attachment

Use this endpoint to upload a new attachment.

Method	Endpoint
POST	/api/v1/envelope/attachment

Headers

Header	Required	Description
Authorization	Yes	Bearer authorization token
Content-Type	Yes	Use multipart/form-data
Mailbox	No	Mailbox context header with the current mailbox UUID

Query parameters

Parameter	Type	Required	Description
type	string	No	Uploaded file type: all, document, file, image, or archive

Use type to specify the uploaded file category. Omit the parameter when no category is needed.

Value	Description
all	All supported file types
document	Document files
file	Files
image	Image files
archive	Archive files

Request body

The endpoint accepts multipart/form-data. The uploaded file must be passed in the required file field.

Field	Type	Required	Description
file	binary	Yes	File to upload

POST /api/v1/envelope/attachment?type=document
Authorization: Bearer {token}
Content-Type: multipart/form-data
Mailbox: {mailboxUuid}

file=@contract.pdf

Response

The endpoint returns 201 Created with information about the uploaded attachment.

{
  "filename": "contract.pdf",
  "attachmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "filesize": 204800,
  "contentType": "application/pdf",
  "updatedPdf": "string"
}

Field	Type	Description
filename	string	Uploaded file name
attachmentId	UUID	Uploaded attachment ID
filesize	integer	Uploaded file size in bytes
contentType	string	Uploaded file content type
updatedPdf	byte string	Updated PDF data, when included in the response

Save the attachmentId value from the response. This value is the uploaded file identifier that must be used later in envelope XML.

Status codes

Code	Description
201	Attachment uploaded successfully

Use the uploaded file in envelope XML

Pass response.attachmentId to the attachmentUuid attribute in envelope XML.

Upload response field	Envelope XML attribute	Description
attachmentId	attachmentUuid	Uploaded file ID returned by the upload endpoint and used as the uploaded file reference in envelope XML
filename	Field value	Uploaded file name, used as the field value when the template expects a visible file name

External document

Use this structure for an external document.

<document id="{documentId}" attachmentUuid="{attachmentId}" />

File upload field

Use this structure for a file upload field.

<document id="{documentId}">
  <field name="File" attachmentUuid="{attachmentId}">contract.pdf</field>
</document>

The field name must match the field name in the selected template. The document ID must also belong to the same template version that is used in the envelope request.

Use multipart/form-data and include the required file field. Pass the returned attachmentId to attachmentUuid. Do not use a local path, external URL, or generated UUID.

Related topics

• Authentication and application tokens

• Working with XML payloads

• Working with templates and reusable IDs

• Working with envelope fields

• Send your first envelope

• Send Envelope