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.
/api/v1/documents/{id}/submissions/api/v1/documents/{id}/submissionsCreate a submission with signers and pre-fill
/api/v1/documents/{id}/submissions/{sid}Delete a submission
Create a submission
| Name | Type | Description |
|---|---|---|
| signers | SignerInput[] | One entry per signer role. Must cover all required roles. |
| 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 field ID or field label → value. Labels are resolved against fields assigned to this signer's role. If a label matches multiple fields, the request is rejected with disambiguation details. |
| prefillReadonly | boolean | If true, prefilled fields are locked for editing by the signer |
| readonlyFieldIds | string[] | List of field IDs or labels to mark as read-only for this signer. Labels are resolved against fields assigned to this signer's role. |
curl -X POST https://app.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": {
"Full Name": "John Doe",
"Company": "Acme Corp Ltd",
"Date": "2026-03-01"
},
"prefillReadonly": true
}
]
}'{
"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://www.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.
Label-based prefill
Prefill keys can be field UUIDs or field labels. When using labels, the server resolves them against fields assigned to this signer's role:
- If the label matches exactly one field for the role, it resolves to that field's UUID
- If the label matches a field with no assigned role (unassigned), it falls back to that match
- If the label matches multiple fields for the same role, the request is rejected with the matching field IDs so you can disambiguate
- You can mix UUIDs and labels in the same prefill object
The readonlyFieldIds array also accepts labels with the same resolution rules.
Download the signed PDF
Once all signers complete, the submission status becomes completed and the signed PDF is available for download.
/api/v1/documents/{id}/submissions/{sid}/pdfcurl https://app.formalingo.com/api/v1/documents/DOC_ID/submissions/SUB_ID/pdf \
-H "Authorization: Bearer af_live_YOUR_KEY"
# → { "data": { "downloadUrl": "https://...", "expiresIn": 300 } }
# Use the downloadUrl to fetch the PDF file directly{
"success": true,
"data": {
"submissionId": "submission-uuid",
"completedAt": "2026-03-11T14:30:00.000Z",
"downloadUrl": "https://storage.supabase.co/...signed.pdf?token=...",
"expiresIn": 300
}
}The downloadUrl is a presigned URL that expires in 5 minutes. Call the endpoint again to get a fresh URL if needed. Returns 404 if the submission is not yet completed or the PDF is still generating.