# secuveri API

> Integrate secuveri identity verification: create sessions, verify Swiss companies (KYB), receive signed webhooks and results, and screen sanctions and PEP lists.

Base URL: https://api-verify.secuveri.com. Authenticate every request with an organization API key in the `x-api-key` header; `sk_test_` keys run in the sandbox, `sk_live_` keys in production. Keep keys on your server.

Flow: POST /v1/sessions returns a hosted verification `url`; the person verifies there; you receive a signed webhook (`secuveri-signature`: HMAC-SHA256 of `<t>.<raw body>`) and read the signed result (ES256 JWS, keys at /.well-known/jwks.json) from GET /v1/verifications/{id}/result.

Every page below is Markdown; the full docs are in one file at /docs/llms-full.txt and the OpenAPI 3.1 spec is at /openapi.json.

## Docs
- [Getting started](https://app.secuveri.com/docs/index.md): base URL, authentication, webhooks and signed results in brief
- [Quick start](https://app.secuveri.com/docs/quick-start.md): Your backend creates a session, the person verifies on the hosted page, and you learn the result from a webhook and a signed result.
- [Sessions](https://app.secuveri.com/docs/sessions.md): POST https://api-verify.secuveri.com/v1/sessions with your API key in x-api-key. Every field is optional.
- [Liveness modes](https://app.secuveri.com/docs/liveness.md): Each workflow's Liveness Check step runs one of these modes, chosen in the workflow builder. Face checks and re-authentication use Action + Flash.
- [Webhooks](https://app.secuveri.com/docs/webhooks.md): Add endpoints in Settings → Webhooks. Each one has its own signing secret (whsec_…) and receives a POST with a JSON body for these events:
- [Signed results](https://app.secuveri.com/docs/results.md): GET 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 screening](https://app.secuveri.com/docs/aml.md): POST 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)](https://app.secuveri.com/docs/kyb.md): POST https://api-verify.secuveri.com/v1/kyb/cases verifies a Swiss company.
- [Standalone APIs](https://app.secuveri.com/docs/standalone.md): Each 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 address](https://app.secuveri.com/docs/proof-of-address.md): Add Proof of Address to a workflow to ask for a recent bill or statement (PDF or photo) after the document.
- [FINMA online identification](https://app.secuveri.com/docs/finma-online-identification.md): Turn on FINMA online identification (Circular 2016/7) on the Identity Document step for onboarding by Swiss financial intermediaries.
- [Content Credentials (C2PA)](https://app.secuveri.com/docs/content-credentials.md): Turn on Content Credentials (C2PA) under Identity Document in the workflow builder.
- [Block and allow lists](https://app.secuveri.com/docs/lists.md): Block or allow an email, phone, IP address or CIDR range, device (installation), your user ID (vendor_data) or document country.
- [Re-authentication](https://app.secuveri.com/docs/reauth.md): Confirm that a returning customer is the same person, with only a selfie.
- [Reusable verification](https://app.secuveri.com/docs/reusable.md): A person already verified by secuveri, for any secuveri customer, holds a secuveri ID in the secuveri Wallet.
- [Swiss e-ID (swiyu)](https://app.secuveri.com/docs/swiss-e-id.md): People in Switzerland may present the state e-ID from the swiyu wallet.
- [Embedding](https://app.secuveri.com/docs/embedding.md): Show the verification inside your page instead of sending the person away.
- [SDKs](https://app.secuveri.com/docs/sdks.md): Two small open-source packages (MIT, no dependencies) wrap the steps above: @secuveri/web opens the flow in your page, and @secuveri/node creates sessions…
- [Sandbox](https://app.secuveri.com/docs/sandbox.md): A sk_test_ key runs your sandbox workflows.
- [Reason codes](https://app.secuveri.com/docs/reason-codes.md): outcome_reason in the signed result says why a verification was held, declined by a workflow setting, or could not finish.
- [Errors](https://app.secuveri.com/docs/errors.md): Errors are JSON with a message for people and, where you can act on it, a code.

## API reference: Sessions
- [POST /v1/sessions](https://app.secuveri.com/docs/api/create-session.md): Create a verification session. params: workflow_id, vendor_data, metadata, callback_url, language, contact, reusable, type, send_link, sandbox_scenario, expected_details; responses: 200, 401, 402, 403, 404, 409, 422, 429

## API reference: Results and keys
- [GET /v1/verifications/{id}/result](https://app.secuveri.com/docs/api/get-result.md): Read the signed result of a finished verification. params: id*; responses: 200, 401, 403, 404, 409, 503
- [GET /v1/verifications/{id}/finma-record](https://app.secuveri.com/docs/api/get-finma-record.md): Read the FINMA identification record of a finished verification. params: id*; responses: 200, 401, 403, 404, 409
- [GET /.well-known/jwks.json](https://app.secuveri.com/docs/api/get-jwks.md): Public keys for signed results, AML screenings and webhook JWS. responses: 200

## API reference: AML screening
- [POST /v1/aml/screen](https://app.secuveri.com/docs/api/screen-person.md): Screen one person against sanctions and PEP lists. params: name, names, date_of_birth, nationality, document_number, include_peps, reference; responses: 200, 400, 401, 402, 403, 409, 410, 429, 503

## API reference: Business verification (KYB)
- [POST /v1/kyb/cases](https://app.secuveri.com/docs/api/open-kyb-case.md): Open a business verification (KYB) case. params: uid, name, workflow_id*, reference, persons, language; responses: 200, 201, 400, 401, 402, 403, 404, 409, 422, 429, 503
- [GET /v1/kyb/cases/{id}](https://app.secuveri.com/docs/api/get-kyb-case.md): Read a business case. params: id*; responses: 200, 401, 403, 404
- [GET /v1/kyb/search](https://app.secuveri.com/docs/api/search-companies.md): Search the commercial register by name. params: name*; responses: 200, 422, 503
- [POST /v1/kyb/cases/{id}/persons/{personId}/verification](https://app.secuveri.com/docs/api/request-kyb-person-verification.md): Start a person's verification. params: id*, personId*, email, phone, send_link; responses: 201, 404, 409, 422
- [POST /v1/kyb/cases/{id}/declaration](https://app.secuveri.com/docs/api/submit-kyb-declaration.md): Declare the beneficial owners. params: id*, kind*, persons*, signer*, confirmed*; responses: 201, 400, 404, 409
- [POST /v1/kyb/cases/{id}/documents](https://app.secuveri.com/docs/api/upload-kyb-document.md): Upload a commercial register extract. params: id*; responses: 201, 413, 422

## API reference: Standalone checks
- [POST /v1/face/match](https://app.secuveri.com/docs/api/match-faces.md): Compare a selfie with a reference portrait. params: threshold, reference_id, sandbox_outcome, selfie*, reference*; responses: 200, 400, 401, 402, 403, 409, 413, 415, 422, 429, 503
- [POST /v1/liveness/check](https://app.secuveri.com/docs/api/check-liveness.md): Passive liveness on one to three selfies. params: deepfake, reference_id, sandbox_outcome, images*; responses: 200, 400, 401, 402, 403, 409, 413, 415, 422, 429, 503
- [POST /v1/age/estimate](https://app.secuveri.com/docs/api/estimate-age.md): Estimate a person's age from their face. params: threshold, buffer_years, reference_id, sandbox_outcome, images*; responses: 200, 400, 401, 402, 403, 409, 413, 415, 422, 429, 503
- [POST /v1/content-credentials/check](https://app.secuveri.com/docs/api/check-content-credentials.md): Read an image's Content Credentials (C2PA). params: reference_id, sandbox_outcome, file*; responses: 200, 400, 401, 402, 403, 409, 413, 415, 422, 429, 503
- [POST /v1/documents/verify](https://app.secuveri.com/docs/api/start-document-verification.md): Verify an identity document. params: country*, document_type*, reference_id, sandbox_outcome, front*, back; responses: 202, 400, 401, 402, 403, 409, 413, 415, 429, 503
- [GET /v1/documents/verify/{id}](https://app.secuveri.com/docs/api/get-document-verification.md): Read a verify an identity document check. params: id*; responses: 200, 401, 403, 404
- [POST /v1/proof-of-address/read](https://app.secuveri.com/docs/api/start-proof-of-address-read.md): Read a proof of address. params: given_names*, surname*, country, postcode, max_age_days, reference_id, sandbox_outcome, file*; responses: 202, 400, 401, 402, 403, 409, 413, 415, 429, 503
- [GET /v1/proof-of-address/read/{id}](https://app.secuveri.com/docs/api/get-proof-of-address-read.md): Read a read a proof of address check. params: id*; responses: 200, 401, 403, 404

## API reference: Block and allow lists
- [GET /v1/lists](https://app.secuveri.com/docs/api/list-entries.md): Read your block and allow list entries. params: kind, type, limit, offset; responses: 200, 400, 401, 403, 429
- [POST /v1/lists](https://app.secuveri.com/docs/api/add-list-entry.md): Block or allow one value. params: kind*, type*, value*, reason, expires_at; responses: 200, 201, 400, 401, 403, 429, 503
- [POST /v1/lists/bulk](https://app.secuveri.com/docs/api/add-list-entries.md): Block or allow up to 1000 values at once. params: entries*; responses: 200, 400, 401, 403, 429, 503
- [DELETE /v1/lists/{id}](https://app.secuveri.com/docs/api/remove-list-entry.md): Remove one entry. params: id*; responses: 200, 401, 403, 404, 429

## Webhook events
- [verification.completed](https://app.secuveri.com/docs/api/webhook-verification-completed.md): A verification reached a final status without needing a person.
- [verification.review_required](https://app.secuveri.com/docs/api/webhook-verification-review-required.md): A verification is waiting for a reviewer.
- [verification.reviewed](https://app.secuveri.com/docs/api/webhook-verification-reviewed.md): A reviewer approved or rejected a verification.
- [verification.expired](https://app.secuveri.com/docs/api/webhook-verification-expired.md): A session expired before the person finished.
- [kyb_case.completed](https://app.secuveri.com/docs/api/webhook-kyb-case-completed.md): A business case was approved or declined without a reviewer.
- [kyb_case.review_required](https://app.secuveri.com/docs/api/webhook-kyb-case-review-required.md): A business case is waiting for a reviewer.
- [kyb_case.reviewed](https://app.secuveri.com/docs/api/webhook-kyb-case-reviewed.md): A reviewer approved or declined a business case.
- [documents.verify.completed](https://app.secuveri.com/docs/api/webhook-documents-verify-completed.md): A 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.completed](https://app.secuveri.com/docs/api/webhook-proof-of-address-read-completed.md): A standalone proof-of-address read ended. data.check_id is the id for GET /v1/proof-of-address/read/{id}.

## Machine-readable
- [OpenAPI 3.1 (JSON)](https://app.secuveri.com/openapi.json): the public spec: every endpoint, schema and webhook
- [OpenAPI 3.1 (YAML)](https://app.secuveri.com/openapi.yaml): the same spec as YAML
- [Sitemap](https://app.secuveri.com/docs/sitemap.xml): every docs page

## Optional
- [Full docs](https://app.secuveri.com/docs/llms-full.txt): every guide and the whole API reference in one file