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"
}'Images uploaded as company stamps
A file_upload field containing a PNG, JPEG, WebP or single-frame GIF renders the image inside its field box in newly generated signed PDFs. The image keeps its aspect ratio and is centered in the box. Other attachment types render their filename. Set the field’s assigneeRole to the signer who uploads the stamp; no separate stamp field type is required.
Uploads are bounded and verified against their recorded byte hash before rendering. Historical uploads without a recorded hash require an audited recovery or a new upload. Existing sealed PDF files are retained unchanged.