Document Fields
Place and manage fields on document pages.
Document Fields
Fields are positioned elements on document pages — signature boxes, text inputs, date pickers, etc. Coordinates are normalized (0–1) relative to the page dimensions.
/api/v1/documents/{id}/fields/api/v1/documents/{id}/fieldsPlace a field
/api/v1/documents/{id}/fields/{fid}Update a field
/api/v1/documents/{id}/fields/{fid}Remove a field
Field types
Supported types: digital_signature, initials, short_text, date, email, phone, number, yes_no, mcq, dropdown, calculation.
calculation fields are computed outputs, not signer inputs. Set options.formula with field references such as {{First Name}} {{Last Name}}; the signer never fills the computed field directly, and the computed value is included in the completed PDF. Use options.result_type: "text" for text interpolation or "number" for arithmetic formulas.
Place a field
| Name | Type | Description |
|---|---|---|
| label | string | Field labelSignature |
| type | FieldType | Field typedigital_signature |
| pageNumber | integer | 1-indexed page number |
| x | float | Normalized x position (0–1 from left) |
| y | float | Normalized y position (0–1 from top) |
| width | float | Normalized width (0–1) |
| height | float | Normalized height (0–1) |
| Name | Type | Description |
|---|---|---|
| isRequired | boolean | Whether the field must be filledtrue |
| isReadOnly | boolean | Pre-filled and lockedfalse |
| defaultValue | string | Pre-populated value. Use __today__ for current date. |
| options.formula | string | Formula for computed fields, e.g. {{First Name}} {{Last Name}} |
| options.result_type | text | number | Computed output type. Defaults to text for document calculation fields. |
| assigneeRole | string | Signer role that fills this fieldsigner_1 |
| direction | auto | rtl | ltr | Text direction for RTL languages |
Computed fields
Use type: "calculation" when a document field should display a value derived from other fields on the same document. Computed fields are always read-only and non-required; they require an assigneeRole so the derived value is materialized with the correct signer when they submit.
{
"label": "Full Name",
"type": "calculation",
"pageNumber": 1,
"x": 0.1,
"y": 0.2,
"width": 0.35,
"height": 0.03,
"assigneeRole": "signer_1",
"options": {
"formula": "{{First Name}} {{Last Name}}",
"result_type": "text"
}
}curl -X POST https://app.formalingo.com/api/v1/documents/DOC_ID/fields \
-H "Authorization: Bearer af_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"label": "Client Signature",
"type": "digital_signature",
"pageNumber": 3,
"x": 0.1,
"y": 0.85,
"width": 0.35,
"height": 0.06,
"isRequired": true,
"assigneeRole": "signer_1"
}'