Document Verification (API)

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

1. Create the document as a draft ("state": "draft") — verification cannot be attached to a document that has already been sent.
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, in addition to contract_id, you'll 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 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: 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 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: 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"

Note: attachments can only be added and removed while the document is a draft. If the same email belongs to multiple counterparties on the document, the call ends with a 409 error — the email 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 moves to the pending state and is sent to the counterparties. A counterparty with attached verification first passes verification — once the checks are complete, they continue to the signature (approval by the proposer happens independently).

If the document is not yet ready (the PDF is still being processed), /send returns a 409 error 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