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 (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. an order number). The document can later be found by this number. |
locale |
Language of the document and of emails for unregistered counterparties: cs, sk, en, de, el, pl, hu, nl, bg, ru, ua, vi. |
url_redirect |
The address the signer will be redirected to 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 in the app as individual items) — see Custom data on a document. |
view_order |
Display order of the envelope's documents in the Signi app — see Document display order. |
folder_id |
ID of the folder to which the document is assigned (a folder = a tag with is_folder) — see Folders and document assignment. |
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 prompting the document to be signed. |
company_name, ic, dic |
Company, company ID and VAT ID (for legal entities). With templates they are filled into the template header. |
street, city, zip_code |
Address. With templates it is filled into the template header. |
organization_position |
Position in the company (e.g. “managing director”). With templates it is filled into the template header. |
date_of_birth |
Date of birth. With templates it is filled into the template header. |
party_order |
Contracting party number — pairs people to parties for a document from a template. |
locale |
Language of emails for this person (overrides the document's locale). |
personal_new_notification |
Personal text that only this person receives in the prompt 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 |
Attachments only: false hides the attachment from this person — see Hiding an attachment from a signer. |
autosign_place |
Signing location 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 a single 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 |
Placeholder field location 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 a single 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 |
Deemed delivery — see Deemed delivery. |
presumed_delivery_days |
Custom length of the deemed delivery period (instead of the default 15 days) — see Deemed delivery. |
sms_auth_before_download |
Require verification via SMS code 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 the document is archived (only with active archiving in the workspace, otherwise ignored) — see Document archiving. |
Other sections
| Field | Meaning |
|---|---|
webhooks |
Automatic reports 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