Document lifecycle (API)

Every document in Signi goes through states. The state tells you what is happening with the document and what you can do with it at that moment.

Overview of states

How states follow each other

1. You create the document via the API — either straight for signing (pending), or as a draft (draft) by setting "state": "draft" in the JSON instructions.
2. For documents with fillable fields, signing may be preceded by the counterparty filling in data (waiting_for_answers).
3. In the pending state the individual parties sign.
4. It ends in one of three states: completed, rejected, or expired.

How to find out the state

By querying the document detail:

curl -H "x-api-key: VAS_API_KLIC" https://api.signi.com/api/v1/contract/ID_DOKUMENTU

In the response the state is in the state field:

{ "contract_id": "1234567", "contract_name": "…", "state": "pending", "creator": { "email": "…" } }

It is more convenient to have changes reported automatically via a webhook — Signi calls your application when a document transitions to the pending, completed, rejected, or expired state. Details in the article Webhooks — automatic notifications of document state changes.

Finding a document by internal number

When you only know your internal document number (the number field used at creation), you can look up the document ID:

curl -H "x-api-key: VAS_API_KLIC" \
  "https://api.signi.com/api/v1/contract/id?number=OBJ-2026-001"

[ { "contractId": 1234567 } ]

• It searches for an exact match of the number (including letter case) within the workspace of your key; if nothing is found, an empty array [] is returned.
• The number is not unique — when reused, multiple items will be returned. An envelope with attachments also returns the attachment IDs.
• It returns deleted documents too — verify the state by querying the detail.
• Encode special characters in the number into the URL (/ → %2F, space → %20).

With the returned contractId you then work as usual: detail, downloading the PDF, etc.

What else the detail returns

ℹ️ New — available in production by the end of October 2026.

• pending_expiration_date — until when the document can be signed (RFC3339 with offset, e.g. 2026-10-02T23:59:59+02:00). Until the document transitions to pending, it returns null.
• is_archived — true = the PDF is in the trusted archive; downloading then returns the archived copy (a ZIP for batch archiving), and you get just the PDF via ?ignoreArchive=true.
• note — the note from the document's Internal settings as Markdown (a custom link is included in it as an MD link); without a note, null.

What to watch out for

• The signed PDF can only be downloaded in the completed state — earlier you will get the document without signatures.
• Deleting documents has restrictions depending on the state — details in the article Cancelling and deleting a document.

Where to go next

• Webhooks — automatic notifications of document state changes
• Who has already signed — the status of individual signers
• Cancelling and deleting a document
• Quickstart — your first document for signing via the API