The most complex part of the Signi API is the JSON with instructions when creating a document. This article describes all the fields you can include in it — with links to articles with examples.
Basic fields
| Field | Meaning |
|---|---|
file |
Name of the field in which you send the document file (typically uploaded_file_key) — see Quickstart. Not used for a document from a template. |
people |
List of people on the document — see below and Multiple signers. |
state |
pending (default — send out for signing right away) or draft (work in progress, not sent to anyone) — see Document lifecycle. |
contract_name |
Document name. Without it, the file or template name is used. |
number |
Your internal document number (e.g. an order number). |
locale |
Language of the document and emails for unregistered counterparties: cs, sk, en, de, pl, hu, nl, bg, ru, ua, vi. |
url_redirect |
The address to which the signer is redirected after signing — useful for signing within an integrated application. |
waiting_limit |
Number of days after which an unsigned document expires. |
metadata |
Custom data for the document in JSON format (displayed item by item in the app) — see Custom data on a document. |
view_order |
Display order of envelope documents in the Signi app — see Document display order. |
folder_id |
ID of the folder into which the document is placed (a folder = a tag with is_folder) — see Folders and document filing. |
People (people)
Each person in the list can have:
| Field | Meaning |
|---|---|
email |
The signer's email (required). |
is_proposer |
true = proposer (your side), false = counterparty. |
contract_role |
Signing role on the document: sign, approve, stamp, sign_certificate, sign_bank_id_sign, sign_remote_sign, notice — see Signing roles. |
positions |
Where to place the signature — see below and Where to place signatures. |
first_name, last_name |
Name — required for unregistered counterparties. |
person_type |
nature (natural person), legal (legal entity), citizen (citizen). Used with templates. |
phone |
Phone — used for sending PIN codes and SMS messages inviting to sign the document. |
company_name, ic, dic |
Company, business ID and VAT ID (for legal entities). With templates, these are filled into the template header. |
street, city, zip_code |
Address. With templates, filled into the template header. |
organization_position |
Position within the company (e.g. "managing director"). With templates, filled into the template header. |
date_of_birth |
Date of birth. With templates, filled into the template header. |
party_order |
Contracting party number — pairs people with parties in a document from a template. |
locale |
Email language for this person (overrides the document's locale). |
personal_new_notification |
A personal text that only this person receives in the invitation email — see Personal message for the signer. |
signature_footer |
Custom text in the signature footer — the footer must be enabled (showFooter), see Signature header and footer. |
workspace_id |
The person's target workspace — only for registered users from the same account. |
is_visible |
Only for attachments: false hides the attachment from this person — see Hiding an attachment from a signer. |
autosign_place |
Signature location for this proposer's automatic signature (alternative to settings.autosign_proposers) — see Automatic proposer signature. |
one_device |
true = this person signs on a shared device (does not receive their own link) — see Signing on one device. |
Signature positions (positions)
| Field | Meaning |
|---|---|
x, y |
Percentages of the page size (0, 0 = top-left corner, 100, 100 = bottom-right); specifies the top-left corner of the signature rectangle. |
page |
Page number, starting from 0. Negative numbers count from the end — -1 = last page. |
relativeWidth |
Signature width as a percentage of the page width (default 30). |
anchor |
Location of a placeholder field in the document — replaces x/y/page, see Where to place signatures. |
showHeader, showFooter |
Enable the signature header/footer — see Signature header and footer. |
Settings (settings)
| Field | Meaning |
|---|---|
signing_order |
Signing order: all_at_once, proposers_before_counterparties, one_at_a_time — see Signer order. |
autosign_proposers |
Automatic proposer signature — see Automatic proposer signature. |
one_device |
Counterparties sign on the proposer's device — see Signing on one device. |
missing_positions |
What to do with signatures without positions: error (default) or append_to_the_end — not recommended, see Where to place signatures. |
lock_after_seal |
Lock the document after completion — see Document security. |
presume_delivery |
Presumed delivery — see Presumed delivery. |
presumed_delivery_days |
Custom presumed delivery period length (instead of the default 15 days) — see Presumed delivery. |
sms_auth_before_download |
Require SMS code verification before downloading the document (the workspace must have this feature enabled). |
convert_to_pdfa |
Convert the document to PDF/A format. |
archive_expire_years |
Number of years the document is archived (only with archiving active in the workspace, otherwise ignored) — see Document archiving. |
Other sections
| Field | Meaning |
|---|---|
webhooks |
Automatic notifications of state changes: [{ "state": "completed", "url": "…" }] — see Webhooks. |
email_notifications |
Email notifications for signers — see Email notifications. |
template |
Document from a template: { "id": …, "parameters": [...] } — see Document from a template. |
tags |
List of tag IDs — see Tags. |
attachments |
Attachments — each has its own people, file, and optionally number, view_order, template and webhooks — see Document with attachments. |
Example with most fields
A verified example combining basic fields, company details, settings, a webhook and a notification:
{
"contract_name": "Smlouva o dílo",
"number": "OBJ-2026-001",
"locale": "cs",
"state": "pending",
"url_redirect": "https://vase-aplikace.cz/podepsano",
"waiting_limit": 30,
"metadata": "vase-interni-id-123",
"settings": { "signing_order": "all_at_once" },
"people": [
{ "is_proposer": true, "email": "vas@email.cz", "contract_role": "approve" },
{ "is_proposer": false, "email": "protistrana@email.cz", "contract_role": "sign",
"first_name": "Jan", "last_name": "Novák", "person_type": "legal",
"company_name": "Firma s.r.o.", "ic": "12345678", "dic": "CZ12345678",
"street": "Dlouhá 1", "city": "Praha", "zip_code": "11000",
"organization_position": "jednatel", "phone": "+420603123456",
"positions": [ { "x": 50, "y": 80, "page": 0, "relativeWidth": 25 } ] }
],
"webhooks": [ { "state": "completed", "url": "https://vase-aplikace.cz/signi-hotovo" } ],
"email_notifications": [
{ "type": "before_sign_expiration", "recipients": ["vas@email.cz"], "days": 1 }
],
"file": "uploaded_file_key"
}
Where to go next
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article