Submissions

A submission instantiates a signing workflow — it maps real people to signer roles and generates unique signing links.

Create a submission

The serialized request body is limited to 1,048,576 UTF-8 bytes. Each signer prefill may contain at most 100 fields, 10 levels of nesting, and 65,536 serialized UTF-8 bytes.

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" \
-H "Idempotency-Key: document-create-7f3f" \
-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": {
    "submissionId": "submission-uuid",
    "dispatchId": "dispatch-uuid",
    "dispatchReused": false,
    "linksCreated": true,
    "signers": [
      {
        "id": "signer-uuid",
        "role": "signer_1",
        "label": "Client",
        "name": "John Doe",
        "color": "#13A373",
        "link": "https://www.formalingo.com/d/abc123xyz",
        "order": 0
      }
    ]
  }
}

The first successful request returns 201. Retrying the same normalized request with the same key returns 200 and dispatchReused: true. Reusing a key with a different request returns 409.

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.

The completed submission also records signature evidence used by verification:

• Explicit e-sign consent and signer metadata
• Viewed, consent, field completion, submission, and PDF-generated audit events
• Completed PDF hash for later byte-for-byte comparison
• Cryptographic verification seal over the signer, audit, and document evidence

curl 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.

Verify a completed submission

Use the verification certificate when you need to prove what happened or check whether a PDF still matches the recorded evidence.

• Public certificate: https://www.formalingo.com/verify/{submissionId}
• Public API: GET /api/verify/document/{submissionId}
• Creator API: GET /api/documents/{id}/verify?submissionId={submissionId}

The certificate can show signer status, consent and completion timestamps, the audit event timeline, the PDF hash match result, and the seal verification result. Older submissions generated before sealing may need PDF regeneration before hash and seal verification are available.

Formalingo is designed to support ESIGN/UETA-style electronic signature workflows in the US. It supports standard electronic signature evidence trails internationally, but it is not a qualified trust service provider and does not create eIDAS qualified electronic signatures (QES).