Field types
| Type | Value filled by | Description |
|---|
signature | Signer (draw or type) | Full signature image |
initial | Signer (draw or type) | Initials only |
date | System (auto) | Current date at time of signing — signer cannot edit |
text | Signer | Free-form text input (up to 1000 chars) |
checkbox | Signer | Boolean — check or uncheck |
Coordinate system
All field positions use PDF points (1 point = 1/72 inch). The origin (0, 0) is the
bottom-left corner of each page — this is the PDF standard, not a GetSigned quirk.
┌──────────────────────────────┐ ← top of page (y = page height)
│ │
│ ┌───────────────┐ │
│ │ field here │ │
│ └───────────────┘ │
│ ↑ │
│ (x=72, y=200) │
│ │
└──────────────────────────────┘ ← bottom of page (y = 0)
| Page size | Width | Height |
|---|
| US Letter (8.5” × 11”) | 612 | 792 |
| A4 (210mm × 297mm) | 595 | 842 |
| Legal (8.5” × 14”) | 612 | 1008 |
Field parameters
{
"documentId": "doc_01HX...",
"signerId": "sgn_01HX...",
"type": "signature",
"page": 1,
"x": 72,
"y": 72,
"w": 200,
"h": 60,
"required": true
}
| Parameter | Description |
|---|
page | 1-based page number |
x | Left edge of the field in PDF points |
y | Bottom edge of the field in PDF points |
w | Width in PDF points |
h | Height in PDF points |
required | If true, signer cannot complete without filling this field |
Converting screen coordinates to PDF coordinates
If you’re placing fields from a browser-rendered PDF, you need to convert screen pixels to PDF
points. The formula accounts for the screen DPI and the PDF render scale:
function screenToPdf(
screenX: number,
screenY: number,
screenPageHeight: number,
renderScale: number // e.g. 1.5 for 150% zoom
): { x: number; y: number } {
const PDF_DPI = 72;
const SCREEN_DPI = 96;
// Convert screen pixels → PDF points
const pdfX = (screenX / renderScale) * (PDF_DPI / SCREEN_DPI);
// PDF y-axis is inverted (origin at bottom) — flip it
const pdfY = ((screenPageHeight - screenY) / renderScale) * (PDF_DPI / SCREEN_DPI);
return { x: Math.round(pdfX), y: Math.round(pdfY) };
}
The drag-drop field placer in the Console handles coordinate conversion for you. Use it to
position fields visually without writing coordinate math.
Typical field sizes
These are sensible defaults — adjust to fit your document layout.
| Field type | Recommended width | Recommended height |
|---|
signature | 180–250 pt | 50–80 pt |
initial | 80–120 pt | 40–60 pt |
date | 100–150 pt | 20–30 pt |
text | 150–300 pt | 20–30 pt |
checkbox | 16–20 pt | 16–20 pt |
Optional fields
Set required: false to make a field optional. The signer can complete it or leave it blank.
At least one field per signer must be required (GetSigned will reject an envelope where a signer
has only optional fields).
date fields are auto-filled with the signing date in the format configured on your application
(default: YYYY-MM-DD). The date is recorded at the moment the signer submits, in UTC.
