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 the placeholder search takes longer

If the search doesn't finish within 30 seconds, the response returns "state": "draft" and "placeholder_detection": "processing". Then:

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

The filled-in values after signing are returned by GET /api/v1/contract/ID_DOKUMENTU/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.

The same fields can also be placed manually in the app — see Form PDF — fillable fields in a document.

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

Related terms: fillable PDF · fillable fields · form PDF