Sending files using a template

1. Purpose

This method sends documents using an existing template in WhiteDoc. In a typical workflow, an accounting system (such as an ERP) processes a request, generates a document based on that request (such as a certificate of completed work), and attaches the file to an envelope created from a template.

The process consists of the following steps:

1. Retrieve and populate the envelope XML based on the template.
2. Upload the generated file (such as a PDF of an internal order) to the WhiteDoc server.
3. Add the attachment UUID to the envelope XML.
4. Send the envelope to the counterparty for signature.

---

2. Getting Started with the API

2.1 Creating a Dedicated Integration User

We recommend creating a dedicated user account used exclusively for the API integration.

This allows you to:

• Keep integration access separate.
• Control permissions.
• Manage tokens securely.

2.2 Creating an API Token

Create an API token in the user profile.

Link:

https://edo.whitedoc.ua/profile?activeTab=application-tokens

The token is used to authenticate all API requests.

Authorization header:

Authorization: Bearer API_TOKEN

---

3. Prerequisites

The request requires a mailbox UUID
https://help.whitedoc.ua/uk/mailbox/uuid-mailbox

You also need the template UUID used to create the envelope (templateUuid), obtained in advance from the template page in WhiteDoc.

---

4. Populating an Envelope from a Template

🔗 Swagger: template-controller / envelope-controller section (methods for populating and creating an envelope from a template — fillEnvelope / sendEnvelope)

In this step, the client’s system sends XML to WhiteDoc containing the data to populate the template fields (following the field structure <field name="...">).

⚠️ The exact structure of the request to populate the template (the list of required fields and the templateUuid / templateVersion format) depends on the specific template — refer to Swagger.

---

5. Uploading a File to the WhiteDoc Server

At this stage, the client’s system uploads the generated file (such as a PDF certificate of completed work) to WhiteDoc’s file storage. The API returns an attachment UUID, which is used in the next step.

🔗 Swagger endpoint:

https://api.whitedoc.ua/swagger-ui/index.html#/envelope-controller/createAttachment

Headers

Request Format

The file is sent as multipart/form-data.

CURL Example

curl -X POST "https://api.whitedoc.ua/attachment-controller/upload" \
-H "Authorization: Bearer API_TOKEN" \
-H "Mailbox: MAILBOX_UUID" \
-F "file=@act.pdf"

Result

The client’s system receives attachment_uuid. This UUID is used to add the file to the envelope XML.

Example Response

json

{
  "uuid": "4a3d1f1a-1a6e-4f5a-9d3c-91b20a8d0e3d",
  "name": "order.pdf",
  "size": 248392
}

---

6. Adding the Attachment UUID to the Envelope XML

After the file is uploaded, the attachment is added to the envelope by inserting the attachment UUID into the document’s XML structure:

<document id="8194259e-5021-425e-9016-38b7e40975d2">
    <field name="dc8494f1-9360-4cb7-bd32-d67b831e08d7" attachmentUuid="4a3d1f1a-1a6e-4f5a-9d3c-91b20a8d0e3d">order.pdf</field>
</document>

After the attachment is added:

• the document becomes part of the envelope;
• WhiteDoc routes the document through the configured workflow.

---

7. Sending the Envelope

🔗 Swagger: envelope-controller/sendEnvelope

Method: POST. The request body contains the populated envelope XML (from Sections 3 and 5) submitted for sending. The headers are the same: Authorization and Mailbox.

Example Response

json

{
  "uuid": "6a9c4dd8-f1fd-426d-8b18-c894b85fb8a3",
  "status": "SENT",
  "created": "2026-08-17T10:00:00.000Z"
}

---

8. Subsequent Tracking

As with the base document, the envelope status is tracked through callbacks or polling (searchEnvelopes), the envelope itself is retrieved using getEnvelopeByUuid, and the complete archive is retrieved using getEnvelopeZip.

---

9. Common Errors