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 containing 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 out for signing right away) or draft (work in progress, not sent to anyone) — see Document life cycle. |
contract_name |
The 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, el, pl, hu, nl, bg, ru, ua, vi. |
url_redirect |
The address where the signer will be 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 where the document will be placed (a folder = a tag with is_folder) — see Folders and placing a document. |
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 number — used for sending PIN codes and SMS messages inviting to sign the document. |
company_name, ic, dic |
Company, company ID and VAT ID (for legal entities). For templates these are filled into the template header. |
street, city, zip_code |
Address. For templates it is filled into the template header. |
organization_position |
Position in the company (e.g. "managing director"). For templates it is filled into the template header. |
date_of_birth |
Date of birth. For templates it is filled into the template header. |
party_order |
Contracting party number — pairs people to parties in 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 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 |
Attachments only: false hides the attachment from this person — see Hiding an attachment from a signer. |
autosign_place |
Signature placement for the automatic signing of this proposer (an alternative to settings.autosign_proposers) — see Automatic signing by the proposer. |
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 |
Position 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 signing by the proposer — see Automatic signing by the proposer. |
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 the document is archived (only with archiving active in the workspace, otherwise ignored) — see Document archiving. |
Other sections
| Field | Meaning |
|---|---|
webhooks |
Automatic reporting 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