Document lifecycle (API)

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

Overview of states

How the states follow one another

1. You create the document via the API — either directly for signing (pending), or as a draft (draft) when you set "state": "draft" in the JSON instructions.
2. For documents with fill-in 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: YOUR_API_KEY" https://api.signi.com/api/v1/contract/DOCUMENT_ID

In the response the state is in the state field:

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

It's 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. See the article Webhooks — automatic notifications of document state changes for details.

Looking up 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: YOUR_API_KEY" \
  "https://api.signi.com/api/v1/contract/id?number=OBJ-2026-001"

[ { "contractId": 1234567 } ]

• An exact match of the number is searched (including letter case) within the workspace of your key; if nothing is found, an empty array [] is returned.
• The number is not unique — if reused, multiple items will be returned. An envelope with attachments also returns the IDs of the attachments.
• It also returns deleted documents — 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 from the beginning of November 2026.

• pending_expiration_date — by 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 can 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 it is null.

What to watch out for

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

Where to go next

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