Document verification (API)

ℹ️ 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 Signi verification scenario: the document counterparty must pass identity verification, otherwise they won't even get to signing. The whole flow has three steps:

1. Create the document as a draft ("state": "draft") — verification can no longer be attached to a sent document.
2. Attach verification to the counterparty.
3. 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 you'll receive, in addition to contract_id, also the docsUuid — which is used to address the document in all verification calls.

Step 2: Attaching verification to the counterparty

You identify the counterparty by the e-mail under which they appear 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 can force a new verification with "forceReverify": true.

• offeredGroups — 1–2 UUIDs of verification groups.
• webhooks — reporting of state 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 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"

Note: attachments can only be added and removed while the document is a draft. If the same e-mail belongs to multiple document counterparties, the call ends with error 409 — the e-mail 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 — once the checks are complete, they continue to signing (approval by the proposer takes place independently).

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

Where to go next

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