Form document from PDF with placeholders (API)

ℹ️ New — available in production at the end of October 2026.

A form document — a PDF in which the counterparty fills in fields before signing — can also be created via the API. You upload a PDF with placeholders in the text and Signi turns them into fill-in fields; the same thing in the web app is described in Filling data into a template by the counterparty.

Placeholders in PDF

Insert placeholders {XYZ:field_name} into the PDF text, where the first letter determines who fills in the field (c = counterparty, p = proposer), the second the requirement (r = required, o = optional) and the third the type (t = text, c = checkbox):

How to do it

In settings send "find_placeholders": true:

curl -X POST https://api.signi.com/api/v1/contract/ \
  -H "x-api-key: YOUR_API_KEY" \
  -F "data=@data.json;type=application/json" \
  -F "document=@formular.pdf;type=application/pdf"

data.json:

{
    "contract_name": "Client questionnaire",
    "state": "pending",
    "file": "document",
    "settings": { "find_placeholders": true, "signing_order": "all_at_once" },
    "people": [
        { "is_proposer": true, "email": "your@email.com", "contract_role": "sign" },
        { "email": "counterparty@email.com", "first_name": "Jan", "last_name": "Novák",
          "person_type": "nature", "contract_role": "sign" }
    ]
}

Response (abbreviated):

{
    "contract_id": 1234567,
    "state": "waiting_for_answers",
    "placeholder_detection": "done",
    "document_form_fields": [
        { "id": "jmeno", "name": "jmeno", "value": null, "filled_by": null,
          "assigned_to": { "role": "counterparty", "party_order": 1 } },
        { "id": "cislo_smlouvy", "name": "cislo_smlouvy", "value": null, "filled_by": null,
          "assigned_to": { "role": "proposer", "party_order": null } }
    ]
}

The document moves to the waiting_for_answers state — the counterparty first fills in the fields and only then signs (see Document lifecycle).

When placeholder detection takes longer

If the detection does not finish within 30 seconds, the response returns "state": "draft" and "placeholder_detection": "processing". Then:

1. poll GET /api/v1/contract/DOCUMENT_ID until placeholder_detection is done,
2. send the envelope via POST /api/v2/docs/DOCUMENT_UUID/send.

The values filled in after signing are returned by GET /api/v1/contract/DOCUMENT_ID/fields.

Limitations

• The workspace must have the form document feature enabled.
• find_placeholders cannot be combined with a template or with attachments.
• Max. 50 pages of PDF, max. 20 different placeholders, at least one placeholder in the PDF.

Where to go next

• Filling data into a template by the counterparty — the same thing in the web app
• JSON for creating a document — overview of all items