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 |
The 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 straight away for signing) or draft (work in progress, sent to no one) — see Document lifecycle. |
contract_name |
Document name. Without it, the file or template name is used. |
number |
Your internal document number (e.g. order number). The document can later be located by this number. |
locale |
Language of the document and emails for unregistered counterparties: cs, sk, en, de, el, pl, hu, nl, bg, ru, ua, vi. |
url_redirect |
Address where the signer will be redirected after signing — useful for signing in an integrated application. |
waiting_limit |
Number of days after which an unsigned document expires. |
metadata |
Custom data for the document in JSON format (displayed in the app as individual items) — 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 in which the document is placed (a folder = a tag with is_folder) — see Folders and filing a document. |
People (people)
Each person in the list can have:
| Field | Meaning |
|---|---|
email |
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 for templates. |
phone |
Phone — used for sending PIN codes and SMS messages prompting the signing of the document. |
sms_before_view |
SMS verification before viewing the document — true/false overrides the workspace default, null inherits. Counterparties only; applies to the person's entire envelope. Available from early November 2026. |
sms_before_sign |
SMS verification before signing (incl. attachments) — true requires it (the workspace must have SMS sending enabled, otherwise 403), false disables it, null keeps the document scenario. Counterparties only; set on the people of the main document. Available from early November 2026. |
company_name, ic, dic |
Company, Company ID and VAT ID (for legal entities). For templates they are propagated into the template header. |
street, city, zip_code |
Address. For templates it is propagated into the template header. |
organization_position |
Position in the company (e.g. "managing director"). For templates it is propagated into the template header. |
date_of_birth |
Date of birth. For templates it is propagated into the template header. |
party_order |
Contracting party number — pairs people to parties for a document from a template. |
locale |
Email language for this person (overrides the document's locale). |
personal_new_notification |
Personal text received only by this person 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 |
For attachments only: false hides the attachment from this person — see Hiding an attachment from a signer. |
autosign_place |
Signing position for the automatic signature of this proposer (an 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); defines 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 the 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 signing 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 length of the presumed delivery period (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 the feature enabled). |
convert_to_pdfa |
Convert the document to PDF/A format. |
archive_expire_years |
Number of years to archive the document (only with active archiving in the workspace, otherwise ignored) — see Document archiving. |
Other blocks
| Field | Meaning |
|---|---|
webhooks |
Automatic reports of state changes: [{ "state": "completed", "url": "…" }] — see Webhooks. |
email_notifications |
Email notifications to 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