This guide walks you through creating and sending a signing envelope from scratch — uploading a document, assembling the envelope with recipients and signature fields, and triggering notifications. By the end you'll have a sent envelope with a recipient waiting to sign.
Make sure you have:
Authorization bearer token and your API key — see Authentication if notBefore creating an envelope, the document must be in Doctavian storage. Upload it via POST /signatures/document/upload as multipart form-data:
POST https://api.doctavian.com/v1/signatures/document/upload
Authorization: Bearer <token>
x-api-key: <api-key>
Content-Type: multipart/form-data
file: <your document>The response returns an id — this is what you pass as the urn value when referencing the document in the envelope create request. Copy it, you'll need it in the next step.
{
"result": {
"data": {
"files": [
{
"id": "af567f07-cafa-4d5c-830c-0f24af7555df",
"fileName": "nda-agreement.pdf"
}
]
},
"statusCode": 201,
"message": "Created"
}
}
The request body below assembles a minimal but complete envelope — one document referenced by its URN, one signer with a mandatory role, one required signature field placed on the first page, and envelope settings covering subject, message, expiry, and sender notifications.
Each section maps to a concept page if you need to go deeper:
POST https://api.doctavian.com/v1/signatures/envelope/create
Authorization: Bearer <token>
x-api-key: <api-key>
Content-Type: application/json
{
"documents": [
{
"referenceDocumentId": 1,
"name": "NDA Agreement",
"loadMethod": "Storage",
"urn": "af567f07-cafa-4d5c-830c-0f24af7555df"
}
],
"recipients": [
{
"referenceSignerId": 1,
"name": "Jane Smith",
"email": "jane.smith@example.com",
"role": "signer",
"mandatory": true
}
],
"fields": [
{
"type": "signature",
"isRequired": true,
"referenceSignerId": 1,
"referenceDocumentId": 1,
"page": 1,
"positionX": 100,
"positionY": 600,
"width": 200,
"height": 60,
"name": "signature_1"
}
],
"envelope": {
"subject": "Please sign: NDA Agreement",
"message": "Please review and sign the attached NDA at your earliest convenience.",
"senderName": "World Industries",
"senderEmail": "contracts@worldindustries.com",
"isSignOrder": false,
"expireInDays": 7,
"notifyWhenOpened": true,
"notifyWhenSigned": true
}
}A successful response returns the envelope along with system-generated IDs for every document, recipient, and field you submitted — each mapped back to the local referenceDocumentId / referenceSignerId you assigned:
{
"result": {
"statusCode": 201,
"message": "Created",
"data": {
"envelope": {
"id": "61914d53-50ec-44a9-a64f-ed473f2c82cf",
"status": "Draft"
},
"documents": [
{ "id": "eff65b7a-3b81-4e41-8b2e-70ed15b645bf" }
],
"recipients": [
{ "id": "d66078c4-96f1-4f60-8a96-f1fe00df25e6" }
],
"fields": [
{
"id": "ff9f4c27-e0b1-41a9-ad2e-330ed25d8da6",
"recipientId": "d66078c4-96f1-4f60-8a96-f1fe00df25e6",
"documentId": "eff65b7a-3b81-4e41-8b2e-70ed15b645bf"
}
]
}
}
}The envelope's system ID is at data.envelope.id — copy it, you'll need it in the next step. The field-level IDs (data.fields[].id) are what you'd reference later if signing programmatically via the API rather than through the hosted UI.
The
referenceDocumentIdandreferenceSignerIdare locally unique integers within the envelope — they link fields to their document and recipient. They are not system IDs.
See the full envelope create schema in the API Reference.
The envelope is in Draft state after creation. Send it to trigger recipient notifications:
GET https://api.doctavian.com/signatures/envelope/env_xyz789/send
Authorization: Bearer <token>
x-api-key: <api-key>A 200 OK confirms the envelope is sent. Jane Smith will receive an email with a personalised link to the signing session.