This guide covers how to position signature fields on a document within an envelope — choosing field types, setting coordinates, and assigning fields to recipients. It assumes you have already created an envelope or are building on the Create and send your first envelope guide.
Fields are placed using X/Y coordinates measured in pixels from the top-left corner of the page. Width and height are also in pixels.
To find exact coordinates, open the document in a PDF viewer or browser and inspect the position visually. Most PDF viewers display cursor coordinates in points — multiply by 1.333 to convert to pixels at 96 DPI.
Instead of manual coordinates, a field can be positioned using anchorString — a distinctive piece of text placed in the document itself. At generation time, Doctavian finds that text on the page and calculates the field's position and size from the bounding box around it. The document is never modified — the anchor text stays in the file, it's just used as a coordinate reference rather than being removed.
A common approach is styling the anchor text the same colour as the page background, so it's present in the document but not visible to anyone viewing or signing it.
{
"type": "signature",
"isRequired": true,
"referenceSignerId": 1,
"referenceDocumentId": 1,
"anchorString": "_SIG_PARTY_A_",
"name": "signature_party_a"
}A field can be positioned by
anchorStringor by manual coordinates (positionX,positionY,width,height,page) — not both. Providing both returns a400error (ANCHOR_PROVIDED_POSITION_NOT_REQUIRED).
Keep anchor strings distinctive and unlikely to appear anywhere else in the document — something like _SIG_PARTY_A_ rather than a generic word, so the field never accidentally binds to the wrong occurrence of the text.
The type property determines what the recipient sees and how they interact with the field. The most commonly used types are:
| Type | What the recipient does |
|---|---|
signature | Signs by typing, drawing, uploading, or using a pre-saved signature |
initial | Provides initials rather than a full signature |
date | Pre-populated with the signing date |
text | Enters freeform text |
checkbox | Checks or unchecks a box |
See the Signature Fields Reference for the full list.
Include all fields in the fields array of the envelope create body. Each field requires a unique name, a referenceDocumentId linking it to a document, and a referenceSignerId linking it to a recipient:
"fields": [
{
"type": "signature",
"isRequired": true,
"referenceSignerId": 1,
"referenceDocumentId": 1,
"page": 1,
"positionX": 100,
"positionY": 650,
"width": 200,
"height": 60,
"name": "signature_party_a"
},
{
"type": "date",
"isRequired": true,
"referenceSignerId": 1,
"referenceDocumentId": 1,
"page": 1,
"positionX": 350,
"positionY": 650,
"width": 120,
"height": 30,
"name": "date_party_a"
},
{
"type": "initial",
"isRequired": false,
"referenceSignerId": 1,
"referenceDocumentId": 1,
"page": 2,
"positionX": 450,
"positionY": 780,
"width": 80,
"height": 40,
"name": "initial_page2"
}
]The optional properties object controls how the completed value renders in the document — font, size, colour, and alignment:
{
"type": "text",
"name": "company_name",
"referenceSignerId": 1,
"referenceDocumentId": 1,
"page": 1,
"positionX": 100,
"positionY": 200,
"width": 250,
"height": 30,
"isRequired": true,
"properties": {
"fontFamily": "Arial",
"fontSize": 12,
"color": "#333333",
"bold": false,
"textAlign": "left"
}
}In a multi-recipient envelope, assign fields to each recipient by matching referenceSignerId to the recipient's referenceSignerId:
"recipients": [
{ "referenceSignerId": 1, "name": "Jane Smith", "email": "jane@example.com", "role": "signer", "mandatory": true },
{ "referenceSignerId": 2, "name": "John Doe", "email": "john@example.com", "role": "signer", "mandatory": true }
],
"fields": [
{ "name": "sig_jane", "referenceSignerId": 1, "referenceDocumentId": 1, "type": "signature", ... },
{ "name": "sig_john", "referenceSignerId": 2, "referenceDocumentId": 1, "type": "signature", ... }
]