API docs
Integrate secuveri identity verification: create sessions, verify Swiss companies (KYB), receive signed webhooks and results, and screen sanctions and PEP lists.
Getting started
Verify your first person in a few minutes
Your backend creates a session with an API key, the person verifies on the hosted page, and you learn the outcome from a signed webhook and a signed result.
Base URL
https://api-verify.secuveri.comOne URL for both environments: the key decides.
sk_test_keys run in the sandbox;sk_live_keys run in production. Sandbox scenariosAuthentication
Send an organization API key in the
Settings → API keysx-api-keyheader on every request. Keep keys on your server, never in a browser or app.Webhooks
Each delivery is signed in
Verify signaturessecuveri-signatureast=…,v1=…: HMAC-SHA256 of<t>.<raw body>with your endpoint's signing secret. Check it before you trust the body.Signed results
Results and AML screenings are ES256 JWS, checked with the keys at
Read a result/.well-known/jwks.json.
Create a session
curl -X POST https://api-verify.secuveri.com/v1/sessions \
-H "x-api-key: $SECUVERI_API_KEY" \
-H "content-type: application/json" \
-H "Idempotency-Key: signup-1042-retry-safe" \
-d '{
"workflow_id": "<published workflow id>",
"vendor_data": "customer-1042",
"callback_url": "https://example.com/verified"
}'Response · 200
{
"session_id": "6f1c2e0a-8f43-4f7e-9a51-2b7c1d9e4a10",
"verification_id": "VRF-7KQ2M9XA",
"status": "CREATED",
"created_at": "2026-10-23T09:12:44.120Z",
"session_token": "…",
"url": "https://verify.secuveri.com/verification/VRF-7KQ2M9XA?t=…"
}Guides
- Quick startYour backend creates a session, the person verifies on the hosted page, and you learn the result from a webhook and a signed result.
- SessionsPOST https://api-verify.secuveri.com/v1/sessions with your API key in x-api-key. Every field is optional.
- Liveness modesEach workflow's Liveness Check step runs one of these modes, chosen in the workflow builder. Face checks and re-authentication use Action + Flash.
- WebhooksAdd endpoints in Settings → Webhooks. Each one has its own signing secret (whsec_…) and receives a POST with a JSON body for these events:
- Signed resultsGET https://api-verify.secuveri.com/v1/verifications/{id}/result with your API key, where id is the verification id or the session id, returns { "result"…
- AML screeningPOST https://api-verify.secuveri.com/v1/aml/screen checks one person against the SECO, EU, UN, OFAC and UK sanctions lists and, unless include_peps is false…
- Business verification (KYB)POST https://api-verify.secuveri.com/v1/kyb/cases verifies a Swiss company.
- Standalone APIsEach check also runs on its own, server to server, without a session or the hosted page: you send the images or file, secuveri answers.
- Proof of addressAdd Proof of Address to a workflow to ask for a recent bill or statement (PDF or photo) after the document.
- FINMA online identificationTurn on FINMA online identification (Circular 2016/7) on the Identity Document step for onboarding by Swiss financial intermediaries.
- Content Credentials (C2PA)Turn on Content Credentials (C2PA) under Identity Document in the workflow builder.
- Block and allow listsBlock or allow an email, phone, IP address or CIDR range, device (installation), your user ID (vendor_data) or document country.
- Re-authenticationConfirm that a returning customer is the same person, with only a selfie.
- Reusable verificationA person already verified by secuveri, for any secuveri customer, holds a secuveri ID in the secuveri Wallet.
- Swiss e-ID (swiyu)People in Switzerland may present the state e-ID from the swiyu wallet.
- EmbeddingShow the verification inside your page instead of sending the person away.
- SDKsTwo small open-source packages (MIT, no dependencies) wrap the steps above: @secuveri/web opens the flow in your page, and @secuveri/node creates sessions…
- SandboxA sk_test_ key runs your sandbox workflows.
- Reason codesoutcome_reason in the signed result says why a verification was held, declined by a workflow setting, or could not finish.
- ErrorsErrors are JSON with a message for people and, where you can act on it, a code.
API reference
Open the referenceSessions
Results and keys
AML screening
Business verification (KYB)
- POST
/v1/kyb/casesOpen a business verification (KYB) case - GET
/v1/kyb/cases/{id}Read a business case - GET
/v1/kyb/searchSearch the commercial register by name - POST
/v1/kyb/cases/{id}/persons/{personId}/verificationStart a person's verification - POST
/v1/kyb/cases/{id}/declarationDeclare the beneficial owners - POST
/v1/kyb/cases/{id}/documentsUpload a commercial register extract
Standalone checks
- POST
/v1/face/matchCompare a selfie with a reference portrait - POST
/v1/liveness/checkPassive liveness on one to three selfies - POST
/v1/age/estimateEstimate a person's age from their face - POST
/v1/content-credentials/checkRead an image's Content Credentials (C2PA) - POST
/v1/documents/verifyVerify an identity document - GET
/v1/documents/verify/{id}Read a verify an identity document check - POST
/v1/proof-of-address/readRead a proof of address - GET
/v1/proof-of-address/read/{id}Read a read a proof of address check
Block and allow lists
Webhook events
verification.completedA verification reached a final status without needing a person.verification.review_requiredA verification is waiting for a reviewer.verification.reviewedA reviewer approved or rejected a verification.verification.expiredA session expired before the person finished.kyb_case.completedA business case was approved or declined without a reviewer.kyb_case.review_requiredA business case is waiting for a reviewer.kyb_case.reviewedA reviewer approved or declined a business case.documents.verify.completedA standalone document check ended. data.check_id is the id for GET /v1/documents/verify/{id}; data.status is COMPLETED or FAILED.proof_of_address.read.completedA standalone proof-of-address read ended. data.check_id is the id for GET /v1/proof-of-address/read/{id}.