Submissions & Pre-fill
Create signing submissions with pre-filled field data.
Submissions
A submission instantiates a signing workflow — it maps real people to signer roles and generates unique signing links.
GET
/api/v1/documents/{id}/submissionsRequired scope:read:submissions
POST
/api/v1/documents/{id}/submissionsCreate a submission with signers and pre-fill
Required scope:write:submissions
DELETE
/api/v1/documents/{id}/submissions/{sid}Delete a submission
Required scope:write:submissions
Create a submission
Request Body
| Name | Type | Description |
|---|---|---|
| signers | SignerInput[] | One entry per signer role. Must cover all required roles. |
SignerInput fields
| Name | Type | Description |
|---|---|---|
| role | string | Signer role identifier, e.g. signer_1signer_1 |
| name | string | Full name of the signer |
| Triggers invitation email if mail integration is configured | ||
| phone | string | Phone for SMS notifications |
| password | string | Protect the signing link with a password |
| prefill | object | Map of fieldId → value. Creates DocumentResponse records immediately. |
| prefillReadonly | boolean | If true, prefilled fields are locked for editing by the signer |
curl -X POST https://formalingo.com/api/v1/documents/DOC_ID/submissions \
-H "Authorization: Bearer af_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"signers": [
{
"role": "signer_1",
"name": "John Doe",
"email": "john@acme.com",
"prefill": {
"field-uuid-1": "John Doe",
"field-uuid-2": "Acme Corp Ltd",
"field-uuid-3": "2026-03-01"
},
"prefillReadonly": true
}
]
}'Response201
{
"success": true,
"data": {
"id": "submission-uuid",
"documentId": "doc-uuid",
"status": "pending",
"createdAt": "2026-02-25T10:00:00.000Z",
"completedAt": null,
"completedPdfUrl": null,
"signers": [
{
"id": "signer-uuid",
"role": "signer_1",
"label": "Client",
"name": "John Doe",
"email": "john@acme.com",
"token": "abc123xyz",
"status": "pending",
"link": "https://formalingo.com/d/abc123xyz",
"order": 0,
"createdAt": "2026-02-25T10:00:00.000Z"
}
]
}
}The signing link
Each signer in the response has a link — share it with the signer for them to review and sign the document. Once all signers complete signing, the submission status becomes completed and a completedPdfUrl is available.