Verification on a document

ℹ️ The new version of Signi verification (including this API) will be released to production during September 2026. Until then, the calls are not available and the description may change slightly.

The main scenario of Signi verification: the document counterparty must pass identity verification, otherwise they won't even get to sign. The whole flow has three steps:

1. You create the document as a draft ("state": "draft") — verification can no longer be attached to a document that has already been sent.
2. You attach verification to the counterparty.
3. You send the document — the counterparty first passes verification, and only then signs.

Step 1: Document as draft

Create the document as usual, just with "state": "draft". In the response you'll receive, in addition to contract_id, also docsUuid — this is how the document is addressed in all verification calls.

Step 2: Attaching verification to the counterparty

You specify the counterparty by the e-mail under which they appear on the document:

curl -X PUT -H "x-api-key: VAS_API_KLIC" -H "Content-Type: application/json" \
  https://api.signi.com/api/v2/docs/UUID_DOKUMENTU/verifications \
  -d '{
    "email": "jan.novak@email.cz",
    "offeredGroups": ["11111111-2222-3333-4444-555555555555"]
  }'

{
    "uuid": "aaaa1111-bbbb-2222-cccc-333344445555",
    "reused": false,
    "verificationUrl": "https://app.signi.com/…",
    "tokenExpiresAt": "2027-02-01T12:00:00+01:00"
}

Key behavior — valid verifications are recycled: when a contact already has an approved and non-expired verification, nothing new is created and "reused": true is returned (without verificationUrl). You can force a new verification with "forceReverify": true.

• offeredGroups — 1–2 UUIDs of verification groups.
• webhooks — reporting of status changes, see Verification webhooks; they are not registered for a recycled verification.

What else you can do with the attachment:

# overview of verifications of all counterparties of the document
curl -H "x-api-key: VAS_API_KLIC" https://api.signi.com/api/v2/docs/UUID_DOKUMENTU/verifications
# removing the attachment (while the document is a draft)
curl -X DELETE -H "x-api-key: VAS_API_KLIC" "https://api.signi.com/api/v2/docs/UUID_DOKUMENTU/verifications?email=jan.novak@email.cz"

Caution: attachments can only be added and removed on a draft document. When the same e-mail belongs to multiple counterparties of the document, the call ends with a 409 error — the e-mail must be unique.

Step 3: Sending the document

curl -X POST -H "x-api-key: VAS_API_KLIC" https://api.signi.com/api/v2/docs/UUID_DOKUMENTU/send

{ "docsUuid": "…", "state": "pending" }

The document transitions to the pending state and notifies the counterparties. A counterparty with an attached verification first passes verification — once the checks are completed, they proceed to signing (approval by the proposer happens independently).

When the document is not yet ready (the PDF is being processed), /send returns a 409 document_processing error — wait and repeat the call.

Where to go next

• Approval and rejection of verification — what happens after the checks are completed
• Verification sheets — proof of the verification process