Form document from PDF with placeholders (API)

ℹ️ New — available from the beginning of November 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 fillable fields; the same thing in the web app is described in Having the counterparty fill in data in a template.

Placeholders in the 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: VAS_API_KLIC" \
  -F "data=@data.json;type=application/json" \
  -F "document=@formular.pdf;type=application/pdf"

data.json:

{
    "contract_name": "Dotazník klienta",
    "state": "pending",
    "file": "document",
    "settings": { "find_placeholders": true, "signing_order": "all_at_once" },
    "people": [
        { "is_proposer": true, "email": "vas@email.cz", "contract_role": "sign" },
        { "email": "protistrana@email.cz", "first_name": "Jan", "last_name": "Novák",
          "person_type": "nature", "contract_role": "sign" }
    ]
}

Response (shortened):

{
    "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

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

1. keep reading GET /api/v1/contract/ID_DOKUMENTU until placeholder_detection is done,
2. send the envelope via POST /api/v2/docs/UUID_DOKUMENTU/send.

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

Limitations

• The workspace must have form documents 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

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