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.

Main Signi verification scenario: the document counterparty must pass identity verification, otherwise they won't be able to sign at all. 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 a draft

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

Step 2: Attaching verification to the counterparty

You identify the counterparty by the email under which they are listed on the document:

curl -X PUT -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  https://api.signi.com/api/v2/docs/DOCUMENT_UUID/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: if the contact already has an approved and non-expired verification, nothing new is created and "reused": true is returned (without verificationUrl). You 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 document counterparties
curl -H "x-api-key: YOUR_API_KEY" https://api.signi.com/api/v2/docs/DOCUMENT_UUID/verifications
# removing the attachment (while the document is still a draft)
curl -X DELETE -H "x-api-key: YOUR_API_KEY" "https://api.signi.com/api/v2/docs/DOCUMENT_UUID/verifications?email=jan.novak@email.cz"

Warning: attachments can only be added and removed on a draft document. If the same email belongs to multiple document counterparties, the call ends with a 409 error — the email must be unambiguous.

Step 3: Sending the document

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

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

The document moves to the pending state and notifies the counterparties. A counterparty with an attached verification first passes verification — Signi lets them sign only after approval.

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

Where to go next

• Approving and rejecting verification — what happens after the checks are completed
• Verification sheets — record of the verification process