{ "openapi": "3.1.0", "info": { "title": "secuveri API", "version": "1", "description": "Create verification sessions, read signed results, verify Swiss companies (KYB), run single checks on their own (face match, passive liveness, age estimation, document verification, proof of address, Content Credentials, AML screening), manage your block and allow lists, and receive webhooks. Authenticate with an organization API key in the x-api-key header: sk_test_ keys work in the sandbox, sk_live_ keys in production." }, "servers": [ { "url": "https://api-verify.secuveri.com" } ], "security": [ { "apiKey": [] } ], "paths": { "/v1/sessions": { "post": { "operationId": "createSession", "summary": "Create a verification session", "description": "Returns a hosted link to send the person to. With workflow_id the session runs that published workflow of your organization; without it, the full verification.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "1 to 255 visible ASCII characters. Retrying with the same key and body within 24 hours returns the first response instead of creating a second session.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSession" } } } }, "responses": { "200": { "description": "The session. A replayed response carries the header idempotent-replayed: true; a returned open session carries secuveri-session-reused: true.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "401": { "description": "Missing, unknown or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The balance does not cover the verification (code insufficient_balance or payment_hold).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope this call needs, or its IP allowlist refuses the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "workflow_id does not name a workflow of your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The workflow is not published, a request with this Idempotency-Key is still running, or (type reauth) no stored face remains (code no_reference).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A field is invalid, the Idempotency-Key was used with a different body, or sandbox_scenario was sent with a live key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/verifications/{id}/result": { "get": { "operationId": "getResult", "summary": "Read the signed result of a finished verification", "description": "The result is a compact ES256 JWS. Check it with the keys from /.well-known/jwks.json; aud is your organization id. A key reads only results of its own environment.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The verification id (VRF-…) or the session id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The signed result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "type": "string", "description": "Compact JWS; payload is ResultPayload." } } } } } }, "401": { "description": "Missing, unknown or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope this call needs, or its IP allowlist refuses the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such verification for this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The verification has not finished yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Result signing is not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/verifications/{id}/finma-record": { "get": { "operationId": "getFinmaRecord", "summary": "Read the FINMA identification record of a finished verification", "description": "For workflows with the FINMA online identification profile (Circular 2016/7). Lists each requirement with its margin number (Rz), the evidence secuveri recorded and an outcome, the randomly selected security features with their seed and results, the beneficial owner declaration, timestamps and reviewer actions. `signature` is a compact ES256 JWS over the same record (check it with /.well-known/jwks.json) so an archived copy can be verified. Needs the results:read scope. Archive it yourself: secuveri deletes personal data and media on its retention clocks.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The verification id (VRF-…) or the session id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The record.", "content": { "application/json": { "schema": { "type": "object", "required": [ "record" ], "properties": { "record": { "$ref": "#/components/schemas/FinmaRecord" }, "signature": { "type": [ "string", "null" ], "description": "Compact JWS; payload is { iss, aud, record }." } } } } } }, "401": { "description": "Missing, unknown or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope this call needs, or its IP allowlist refuses the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such verification for this key, or it did not use the FINMA profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The verification has not finished yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/jwks.json": { "get": { "operationId": "getJwks", "summary": "Public keys for signed results, AML screenings and webhook JWS", "security": [], "responses": { "200": { "description": "A JSON Web Key Set. During a key rotation it holds the old and the new key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Jwks" } } } } } } }, "/v1/aml/screen": { "post": { "operationId": "screenPerson", "summary": "Screen one person against sanctions and PEP lists", "description": "Uses the same lists and scoring as the AML workflow step. Send Idempotency-Key to reuse a saved response and billing ID on retries, scoped to organization and environment. Encrypted responses are replayable for 24 hours from the first attempt; expired keys return 410 and cannot charge again. Without the header, every request is independent. At most 120 calls per minute per organization, including replays. Raw subject input is not stored.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "A unique identifier for this intended screening. Reuse on retries; printable non-space ASCII. Changed request details conflict. Generate a new key only for a new intended screening." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmlScreenRequest" } } } }, "responses": { "200": { "description": "The screening.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmlScreening" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The balance does not cover the screening.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope this call needs, or its IP allowlist refuses the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The same key is in progress (idempotency_in_progress, Retry-After: 1), conflicts with different request details, or its reservation was refunded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "The saved-response window expired; this key cannot create another charge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 screenings in a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A source list or matching capacity/worker is unavailable. Capacity errors return Retry-After: 1. Retry with the same Idempotency-Key; no charge is started for rejected matching work.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/kyb/cases": { "post": { "operationId": "openKybCase", "summary": "Open a business verification (KYB) case", "description": "Looks the company up in the Swiss commercial register (Zefix and the UID register) by UID, or by name when exactly one company has that name, lists its registered persons with their roles and signing authority, derives beneficial owner candidates (GmbH partners holding 25% or more), and screens the company and its persons against the sanctions and PEP lists. workflow_id names a published workflow with the Business Verification step; its other steps are what each person's verification runs. Charged once per case when the register found the company (pricing: business-verification). Needs kyb:write. Send Idempotency-Key to get the same case back on retries for 24 hours.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybOpenCase" } } } }, "responses": { "200": { "description": "The case opened earlier with this Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybCase" } } } }, "201": { "description": "The case, plus declaration_url (the applicant's declaration link, shown once).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybCase" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The balance does not cover the company check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the kyb:write scope, or its IP allowlist refuses the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such workflow in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Several companies have this name (ambiguous_company, with candidates), or the Idempotency-Key is in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid UID, or the workflow has no Business Verification step.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 60 business verification calls in a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The commercial register is unavailable (registry_unavailable); nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/kyb/cases/{id}": { "get": { "operationId": "getKybCase", "summary": "Read a business case", "description": "Refreshes the persons' verification states first. A decided case carries signed_result, an ES256 JWS (typ kyb_case) with identifiers and outcome only. Needs kyb:read.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The case.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybCase" } } } }, "401": { "description": "Missing, unknown or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the kyb:read scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such case in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/kyb/search": { "get": { "operationId": "searchCompanies", "summary": "Search the commercial register by name", "description": "Free. At most 25 companies, with UID, name, seat and status. Needs kyb:read.", "parameters": [ { "name": "name", "in": "query", "required": true, "schema": { "type": "string", "minLength": 3 } } ], "responses": { "200": { "description": "Matching companies.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object" } } } } } } }, "422": { "description": "The name is shorter than 3 characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The commercial register is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/kyb/cases/{id}/persons/{personId}/verification": { "post": { "operationId": "requestKybPersonVerification", "summary": "Start a person's verification", "description": "Creates a verification session of the case's workflow for one person (a signatory or beneficial owner) and returns its url; with send_link the link goes out by email or SMS. Charged as a normal verification. At most 20 per case. Needs kyb:write.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "personId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "email": { "type": "string" }, "phone": { "type": "string", "description": "E.164, e.g. +41791234567" }, "send_link": { "enum": [ "email", "sms" ] } } } } } }, "responses": { "201": { "description": "The verification: person_id, verification_id, url, link_sent." }, "404": { "description": "No such case or person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The person already has a verification, the case is closed, or the case reached 20 verifications.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A legal person cannot verify itself, or send_link lacks its contact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/kyb/cases/{id}/declaration": { "post": { "operationId": "submitKybDeclaration", "summary": "Declare the beneficial owners", "description": "Beneficial owners (ownership of 25% or more, or other control) or, where none can be identified, the controlling persons (management). Declared owners with an email or phone get a verification link when the workflow verifies beneficial owners. The applicant can also use the case's declaration_url. Needs kyb:write.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KybDeclaration" } } } }, "responses": { "201": { "description": "Received: declaration_id and the invitations sent." }, "400": { "description": "Invalid declaration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such case.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The case is closed or its company was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/kyb/cases/{id}/documents": { "post": { "operationId": "uploadKybDocument", "summary": "Upload a commercial register extract", "description": "multipart/form-data with field \"file\" (PDF, JPEG or PNG, at most 10 MB) and optional \"kind\" (register_extract or other). Stored encrypted for your reviewers. Needs kyb:write.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Stored: id, kind, size, sha256." }, "413": { "description": "Larger than 10 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Not a PDF, JPEG or PNG.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/lists": { "get": { "operationId": "listEntries", "summary": "Read your block and allow list entries", "description": "Newest first. Contacts, devices and vendor_data are stored only as a keyed fingerprint, so an entry shows a masked hint, never the value. Needs the lists:read scope. At most 300 list calls per minute per organization.", "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "block", "allow" ] } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "email", "phone", "ip", "installation", "vendor_data", "country" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "One page of entries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/ListEntry" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } }, "400": { "description": "Invalid filter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope this call needs, or its IP allowlist refuses the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 300 list calls in a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "addListEntry", "summary": "Block or allow one value", "description": "A blocked value declines a verification that presents it (LIST_BLOCK; a workflow can send it to review instead). An allowed value skips the velocity, IP-country and risky-contact holds. The value is normalized first (emails lower-cased, phones as E.164, IPs and CIDR ranges, two-letter countries); adding an active value returns the existing entry with 200. An expired matching entry is reactivated with the requested expiry and returned with 200. Needs the lists:write scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewListEntry" } } } }, "responses": { "200": { "description": "Already listed; the existing entry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEntryResult" } } } }, "201": { "description": "Added.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEntryResult" } } } }, "400": { "description": "Invalid value, or an expiry that is not in the future.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope this call needs, or its IP allowlist refuses the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 300 list calls in a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Lists are not available right now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/lists/bulk": { "post": { "operationId": "addListEntries", "summary": "Block or allow up to 1000 values at once", "description": "Each entry is checked like a single add. Invalid entries and repeats within the request are reported per entry and not stored; new entries are added and expired matches are reactivated with the requested expiry. Active matches remain unchanged. Counts and per-entry statuses distinguish created, reactivated and existing entries. Changes and their audit record are saved atomically. Needs the lists:write scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entries" ], "additionalProperties": false, "properties": { "entries": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "$ref": "#/components/schemas/NewListEntry" } } } } } } }, "responses": { "200": { "description": "What happened to each entry, by its position in the request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "integer" }, "reactivated": { "type": "integer" }, "existing": { "type": "integer" }, "invalid": { "type": "integer", "description": "Invalid entries and repeats." }, "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "status": { "type": "string", "enum": [ "created", "reactivated", "exists", "duplicate", "invalid" ] }, "error": { "type": "string" }, "entry": { "$ref": "#/components/schemas/ListEntry" } } } } } } } } }, "400": { "description": "The body is not an object with 1 to 1000 entries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope this call needs, or its IP allowlist refuses the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 300 list calls in a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Lists are not available right now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/lists/{id}": { "delete": { "operationId": "removeListEntry", "summary": "Remove one entry", "description": "Needs the lists:write scope.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "const": true } } } } } }, "401": { "description": "Missing, unknown or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope this call needs, or its IP allowlist refuses the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such entry in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 300 list calls in a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/face/match": { "post": { "operationId": "matchFaces", "summary": "Compare a selfie with a reference portrait", "description": "The hosted face match on two images you send. MATCH when the score reaches `threshold` (default 0.50; 0.50–0.75). CHF 0.30 per answered call, including NO_FACE answers; refunded when it could not run. Needs the face:match scope. Images are not stored.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Reuse on retries (printable non-space ASCII). For 24 hours the same key and the same request return the saved answer and check id without a second charge; a different request under the key returns 409." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "selfie", "reference" ], "properties": { "threshold": { "type": "number", "minimum": 0.5, "maximum": 0.75, "default": 0.5 }, "reference_id": { "type": "string", "maxLength": 128, "description": "Your own id, echoed in the answer." }, "sandbox_outcome": { "type": "string", "enum": [ "match", "no_match", "no_face" ], "description": "Sandbox keys only: which test answer to return. No model runs and nothing is charged." }, "selfie": { "type": "string", "format": "binary", "description": "JPEG, PNG or WebP, at most 10 MB." }, "reference": { "type": "string", "format": "binary", "description": "The trusted portrait (document photo or chip image)." } } } }, "application/json": { "schema": { "type": "object", "required": [ "selfie", "reference" ], "properties": { "threshold": { "type": "number", "minimum": 0.5, "maximum": 0.75, "default": 0.5 }, "reference_id": { "type": "string", "maxLength": 128, "description": "Your own id, echoed in the answer." }, "sandbox_outcome": { "type": "string", "enum": [ "match", "no_match", "no_face" ], "description": "Sandbox keys only: which test answer to return. No model runs and nothing is charged." }, "selfie": { "type": "string", "description": "JPEG, PNG or WebP, at most 10 MB." }, "reference": { "type": "string", "description": "The trusted portrait (document photo or chip image)." } } } } } }, "responses": { "200": { "description": "The answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaceMatch" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The balance does not cover the check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the product's scope, its IP allowlist refuses the caller, or (code production_not_allowed) the organization may not use production yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The Idempotency-Key is in progress (Retry-After: 1) or was used with a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "A file or the body is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A file is not of an accepted type (checked by its bytes, not its name), or the body is neither multipart nor JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "An image could not be decoded. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 calls in a minute for this product.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The check could not run on our side. Nothing was charged; retry later with the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/liveness/check": { "post": { "operationId": "checkLiveness", "summary": "Passive liveness on one to three selfies", "description": "Passive presentation-attack detection: the hosted flow's two PAD models and its deepfake model on the images you send. Weaker than the hosted active liveness (no challenge, no screen flash, no capture binding): it catches printed photos, screens and masks the models know, not a replayed or injected stream. CHF 0.60 per answered call; refunded when it could not run. Needs the liveness:check scope.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Reuse on retries (printable non-space ASCII). For 24 hours the same key and the same request return the saved answer and check id without a second charge; a different request under the key returns 409." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "images" ], "properties": { "deepfake": { "type": "boolean", "default": true }, "reference_id": { "type": "string", "maxLength": 128, "description": "Your own id, echoed in the answer." }, "sandbox_outcome": { "type": "string", "enum": [ "live", "spoof", "review", "no_face" ], "description": "Sandbox keys only: which test answer to return. No model runs and nothing is charged." }, "images": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "One to three images of one person (or a single `image` field)." } } } }, "application/json": { "schema": { "type": "object", "required": [ "images" ], "properties": { "deepfake": { "type": "boolean", "default": true }, "reference_id": { "type": "string", "maxLength": 128, "description": "Your own id, echoed in the answer." }, "sandbox_outcome": { "type": "string", "enum": [ "live", "spoof", "review", "no_face" ], "description": "Sandbox keys only: which test answer to return. No model runs and nothing is charged." }, "images": { "type": "array", "items": { "type": "string", "description": "In JSON: the file as base64 (a data: URL is accepted)." }, "description": "One to three images of one person (or a single `image` field)." } } } } } }, "responses": { "200": { "description": "The answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LivenessCheck" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The balance does not cover the check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the product's scope, its IP allowlist refuses the caller, or (code production_not_allowed) the organization may not use production yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The Idempotency-Key is in progress (Retry-After: 1) or was used with a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "A file or the body is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A file is not of an accepted type (checked by its bytes, not its name), or the body is neither multipart nor JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "An image could not be decoded. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 calls in a minute for this product.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The check could not run on our side. Nothing was charged; retry later with the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/age/estimate": { "post": { "operationId": "estimateAge", "summary": "Estimate a person's age from their face", "description": "The hosted age gate's estimator. OVER_THRESHOLD when the estimate reaches `threshold` + `buffer_years` (default 18 + 7 = 25, as the hosted gate); the estimate has no calibrated error bound, so decide with the buffer, not the raw age. CHF 0.30 per answered call. Needs the age:estimate scope.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Reuse on retries (printable non-space ASCII). For 24 hours the same key and the same request return the saved answer and check id without a second charge; a different request under the key returns 409." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "images" ], "properties": { "threshold": { "type": "integer", "minimum": 12, "maximum": 30, "default": 18 }, "buffer_years": { "type": "integer", "minimum": 0, "maximum": 15, "default": 7 }, "reference_id": { "type": "string", "maxLength": 128, "description": "Your own id, echoed in the answer." }, "sandbox_outcome": { "type": "string", "enum": [ "over", "under", "no_face" ], "description": "Sandbox keys only: which test answer to return. No model runs and nothing is charged." }, "images": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "One to three images of one person (or a single `image` field)." } } } }, "application/json": { "schema": { "type": "object", "required": [ "images" ], "properties": { "threshold": { "type": "integer", "minimum": 12, "maximum": 30, "default": 18 }, "buffer_years": { "type": "integer", "minimum": 0, "maximum": 15, "default": 7 }, "reference_id": { "type": "string", "maxLength": 128, "description": "Your own id, echoed in the answer." }, "sandbox_outcome": { "type": "string", "enum": [ "over", "under", "no_face" ], "description": "Sandbox keys only: which test answer to return. No model runs and nothing is charged." }, "images": { "type": "array", "items": { "type": "string", "description": "In JSON: the file as base64 (a data: URL is accepted)." }, "description": "One to three images of one person (or a single `image` field)." } } } } } }, "responses": { "200": { "description": "The answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgeEstimate" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The balance does not cover the check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the product's scope, its IP allowlist refuses the caller, or (code production_not_allowed) the organization may not use production yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The Idempotency-Key is in progress (Retry-After: 1) or was used with a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "A file or the body is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A file is not of an accepted type (checked by its bytes, not its name), or the body is neither multipart nor JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "An image could not be decoded. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 calls in a minute for this product.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The check could not run on our side. Nothing was charged; retry later with the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/content-credentials/check": { "post": { "operationId": "checkContentCredentials", "summary": "Read an image's Content Credentials (C2PA)", "description": "The same validator and summary as the workflow's Content Credentials check: verdict, signer, generator, AI-generated and edited flags. CHF 0.05 per checked file; a format the validator cannot read is answered NOT_APPLICABLE and not charged. Needs the c2pa:check scope.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Reuse on retries (printable non-space ASCII). For 24 hours the same key and the same request return the saved answer and check id without a second charge; a different request under the key returns 409." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "reference_id": { "type": "string", "maxLength": 128, "description": "Your own id, echoed in the answer." }, "sandbox_outcome": { "type": "string", "enum": [ "trusted", "no_manifest", "ai_generated", "invalid" ], "description": "Sandbox keys only: which test answer to return. No model runs and nothing is charged." }, "file": { "type": "string", "format": "binary", "description": "JPEG, PNG, WebP, HEIC, HEIF or AVIF, at most 20 MB." } } } }, "application/json": { "schema": { "type": "object", "required": [ "file" ], "properties": { "reference_id": { "type": "string", "maxLength": 128, "description": "Your own id, echoed in the answer." }, "sandbox_outcome": { "type": "string", "enum": [ "trusted", "no_manifest", "ai_generated", "invalid" ], "description": "Sandbox keys only: which test answer to return. No model runs and nothing is charged." }, "file": { "type": "string", "description": "JPEG, PNG, WebP, HEIC, HEIF or AVIF, at most 20 MB." } } } } } }, "responses": { "200": { "description": "The answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentCredentialsCheck" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The balance does not cover the check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the product's scope, its IP allowlist refuses the caller, or (code production_not_allowed) the organization may not use production yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The Idempotency-Key is in progress (Retry-After: 1) or was used with a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "A file or the body is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A file is not of an accepted type (checked by its bytes, not its name), or the body is neither multipart nor JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "An image could not be decoded. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 300 calls in a minute for this product.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The check could not run on our side. Nothing was charged; retry later with the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/documents/verify": { "post": { "operationId": "startDocumentVerification", "summary": "Verify an identity document", "description": "The hosted document pipeline on photos you send: document type and country, MRZ and visual-zone fields, MRZ check digits, consistency and authenticity checks. No chip read, morph or face checks. Send each side flat and cropped to the document. Asynchronous: answers 202, then documents.verify.completed. CHF 1.20 when it reached a document outcome; refunded on a processing error or timeout. Needs the documents:verify scope. Photos are erased when the check ends.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Reuse on retries (printable non-space ASCII). For 24 hours the same key and the same request return the saved answer and check id without a second charge; a different request under the key returns 409." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "front", "country", "document_type" ], "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2 or alpha-3." }, "document_type": { "type": "string", "enum": [ "PASSPORT", "NATIONAL_ID", "DRIVER_LICENSE", "RESIDENCE_PERMIT" ] }, "reference_id": { "type": "string", "maxLength": 128, "description": "Your own id, echoed in the answer." }, "sandbox_outcome": { "type": "string", "enum": [ "pass", "fail", "review" ], "description": "Sandbox keys only: which test answer to return. No model runs and nothing is charged." }, "front": { "type": "string", "format": "binary", "description": "JPEG, PNG or WebP, at most 12 MB." }, "back": { "type": "string", "format": "binary", "description": "Optional." } } } }, "application/json": { "schema": { "type": "object", "required": [ "front", "country", "document_type" ], "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2 or alpha-3." }, "document_type": { "type": "string", "enum": [ "PASSPORT", "NATIONAL_ID", "DRIVER_LICENSE", "RESIDENCE_PERMIT" ] }, "reference_id": { "type": "string", "maxLength": 128, "description": "Your own id, echoed in the answer." }, "sandbox_outcome": { "type": "string", "enum": [ "pass", "fail", "review" ], "description": "Sandbox keys only: which test answer to return. No model runs and nothing is charged." }, "front": { "type": "string", "description": "JPEG, PNG or WebP, at most 12 MB." }, "back": { "type": "string", "description": "Optional." } } } } } }, "responses": { "202": { "description": "Accepted. Poll the check or wait for its webhook.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentVerification" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The balance does not cover the check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the product's scope, its IP allowlist refuses the caller, or (code production_not_allowed) the organization may not use production yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The Idempotency-Key is in progress (Retry-After: 1) or was used with a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "A file or the body is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A file is not of an accepted type (checked by its bytes, not its name), or the body is neither multipart nor JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 60 calls in a minute for this product.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The check could not run on our side. Nothing was charged; retry later with the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/documents/verify/{id}": { "get": { "operationId": "getDocumentVerification", "summary": "Read a verify an identity document check", "description": "For the organization and environment that started it, for 24 hours.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentVerification" } } } }, "401": { "description": "Missing, unknown or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the product's scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such check for this organization and environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/proof-of-address/read": { "post": { "operationId": "startProofOfAddressRead", "summary": "Read a proof of address", "description": "The proof-of-address reader on a bill or statement: name match against the name you send, address, issue date and age, issuer, document type, QR-bill and PDF forensics. It assists and never approves. Asynchronous: answers 202, then proof_of_address.read.completed. CHF 0.25 when the reader read the file; refunded when it could not. Needs the poa:read scope. The file is not stored.", "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Reuse on retries (printable non-space ASCII). For 24 hours the same key and the same request return the saved answer and check id without a second charge; a different request under the key returns 409." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "given_names", "surname" ], "properties": { "given_names": { "type": "string" }, "surname": { "type": "string" }, "country": { "type": "string", "description": "Expected country of the address, ISO 3166-1." }, "postcode": { "type": "string", "description": "Expected postcode; answered as postcode_match." }, "max_age_days": { "type": "integer", "enum": [ 30, 60, 90, 180 ], "default": 90 }, "reference_id": { "type": "string", "maxLength": 128, "description": "Your own id, echoed in the answer." }, "sandbox_outcome": { "type": "string", "enum": [ "pass", "review", "unreadable" ], "description": "Sandbox keys only: which test answer to return. No model runs and nothing is charged." }, "file": { "type": "string", "format": "binary", "description": "PDF, JPEG, PNG, WebP, HEIC or AVIF, at most 10 MB." } } } }, "application/json": { "schema": { "type": "object", "required": [ "file", "given_names", "surname" ], "properties": { "given_names": { "type": "string" }, "surname": { "type": "string" }, "country": { "type": "string", "description": "Expected country of the address, ISO 3166-1." }, "postcode": { "type": "string", "description": "Expected postcode; answered as postcode_match." }, "max_age_days": { "type": "integer", "enum": [ 30, 60, 90, 180 ], "default": 90 }, "reference_id": { "type": "string", "maxLength": 128, "description": "Your own id, echoed in the answer." }, "sandbox_outcome": { "type": "string", "enum": [ "pass", "review", "unreadable" ], "description": "Sandbox keys only: which test answer to return. No model runs and nothing is charged." }, "file": { "type": "string", "description": "PDF, JPEG, PNG, WebP, HEIC or AVIF, at most 10 MB." } } } } } }, "responses": { "202": { "description": "Accepted. Poll the check or wait for its webhook.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProofOfAddressRead" } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The balance does not cover the check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the product's scope, its IP allowlist refuses the caller, or (code production_not_allowed) the organization may not use production yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The Idempotency-Key is in progress (Retry-After: 1) or was used with a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "A file or the body is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A file is not of an accepted type (checked by its bytes, not its name), or the body is neither multipart nor JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 60 calls in a minute for this product.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The check could not run on our side. Nothing was charged; retry later with the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/proof-of-address/read/{id}": { "get": { "operationId": "getProofOfAddressRead", "summary": "Read a read a proof of address check", "description": "For the organization and environment that started it, for 24 hours.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProofOfAddressRead" } } } }, "401": { "description": "Missing, unknown or expired API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the product's scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such check for this organization and environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "verification.completed": { "post": { "summary": "verification.completed", "description": "A verification reached a final status without needing a person. Signed with the secuveri-signature header (HMAC-SHA256 of \".\" with your endpoint's signing secret) and, when result signing is configured, a detached ES256 JWS in secuveri-jws.", "parameters": [ { "name": "secuveri-signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "secuveri-jws", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "secuveri-event-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "secuveri-event-type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Any other answer, a redirect or a timeout after 10 s is retried." } } } }, "verification.review_required": { "post": { "summary": "verification.review_required", "description": "A verification is waiting for a reviewer. Signed with the secuveri-signature header (HMAC-SHA256 of \".\" with your endpoint's signing secret) and, when result signing is configured, a detached ES256 JWS in secuveri-jws.", "parameters": [ { "name": "secuveri-signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "secuveri-jws", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "secuveri-event-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "secuveri-event-type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Any other answer, a redirect or a timeout after 10 s is retried." } } } }, "verification.reviewed": { "post": { "summary": "verification.reviewed", "description": "A reviewer approved or rejected a verification. Signed with the secuveri-signature header (HMAC-SHA256 of \".\" with your endpoint's signing secret) and, when result signing is configured, a detached ES256 JWS in secuveri-jws.", "parameters": [ { "name": "secuveri-signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "secuveri-jws", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "secuveri-event-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "secuveri-event-type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Any other answer, a redirect or a timeout after 10 s is retried." } } } }, "verification.expired": { "post": { "summary": "verification.expired", "description": "A session expired before the person finished. Signed with the secuveri-signature header (HMAC-SHA256 of \".\" with your endpoint's signing secret) and, when result signing is configured, a detached ES256 JWS in secuveri-jws.", "parameters": [ { "name": "secuveri-signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "secuveri-jws", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "secuveri-event-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "secuveri-event-type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Any other answer, a redirect or a timeout after 10 s is retried." } } } }, "kyb_case.completed": { "post": { "summary": "kyb_case.completed", "description": "A business case was approved or declined without a reviewer. Signed with the secuveri-signature header (HMAC-SHA256 of \".\" with your endpoint's signing secret) and, when result signing is configured, a detached ES256 JWS in secuveri-jws.", "parameters": [ { "name": "secuveri-signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "secuveri-jws", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "secuveri-event-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "secuveri-event-type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Any other answer, a redirect or a timeout after 10 s is retried." } } } }, "kyb_case.review_required": { "post": { "summary": "kyb_case.review_required", "description": "A business case is waiting for a reviewer. Signed with the secuveri-signature header (HMAC-SHA256 of \".\" with your endpoint's signing secret) and, when result signing is configured, a detached ES256 JWS in secuveri-jws.", "parameters": [ { "name": "secuveri-signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "secuveri-jws", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "secuveri-event-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "secuveri-event-type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Any other answer, a redirect or a timeout after 10 s is retried." } } } }, "kyb_case.reviewed": { "post": { "summary": "kyb_case.reviewed", "description": "A reviewer approved or declined a business case. Signed with the secuveri-signature header (HMAC-SHA256 of \".\" with your endpoint's signing secret) and, when result signing is configured, a detached ES256 JWS in secuveri-jws.", "parameters": [ { "name": "secuveri-signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "secuveri-jws", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "secuveri-event-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "secuveri-event-type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Any other answer, a redirect or a timeout after 10 s is retried." } } } }, "documents.verify.completed": { "post": { "summary": "documents.verify.completed", "description": "A standalone document check ended. `data.check_id` is the id for GET /v1/documents/verify/{id}; `data.status` is COMPLETED or FAILED. Signed with the secuveri-signature header (HMAC-SHA256 of \".\" with your endpoint's signing secret) and, when result signing is configured, a detached ES256 JWS in secuveri-jws.", "parameters": [ { "name": "secuveri-signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "secuveri-jws", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "secuveri-event-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "secuveri-event-type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Any other answer, a redirect or a timeout after 10 s is retried." } } } }, "proof_of_address.read.completed": { "post": { "summary": "proof_of_address.read.completed", "description": "A standalone proof-of-address read ended. `data.check_id` is the id for GET /v1/proof-of-address/read/{id}. Signed with the secuveri-signature header (HMAC-SHA256 of \".\" with your endpoint's signing secret) and, when result signing is configured, a detached ES256 JWS in secuveri-jws.", "parameters": [ { "name": "secuveri-signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "secuveri-jws", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "secuveri-event-id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "secuveri-event-type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Any other answer, a redirect or a timeout after 10 s is retried." } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "schemas": { "FaceMatch": { "type": "object", "properties": { "check_id": { "type": "string", "format": "uuid" }, "product": { "type": "string" }, "environment": { "type": [ "string", "null" ] }, "sandbox": { "type": "boolean" }, "checked_at": { "type": "string", "format": "date-time" }, "reference_id": { "type": "string" }, "signed_result": { "type": "string", "description": "The same answer as an ES256 JWS, verifiable with /.well-known/jwks.json." }, "decision": { "type": "string", "enum": [ "MATCH", "NO_MATCH", "NO_FACE_IN_SELFIE", "NO_FACE_IN_REFERENCE" ] }, "match": { "type": "boolean" }, "score": { "type": [ "number", "null" ], "description": "Similarity score, about 0 for different people." }, "threshold": { "type": "number" } } }, "LivenessCheck": { "type": "object", "properties": { "check_id": { "type": "string", "format": "uuid" }, "product": { "type": "string" }, "environment": { "type": [ "string", "null" ] }, "sandbox": { "type": "boolean" }, "checked_at": { "type": "string", "format": "date-time" }, "reference_id": { "type": "string" }, "signed_result": { "type": "string", "description": "The same answer as an ES256 JWS, verifiable with /.well-known/jwks.json." }, "decision": { "type": "string", "enum": [ "LIVE", "SPOOF", "REVIEW", "NO_FACE" ] }, "live": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "passive" ] }, "frames": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "face_found": { "type": "boolean" }, "presentation_attack": { "type": [ "string", "null" ], "enum": [ "PASS", "REVIEW", "FAIL", null ] }, "spoof_score": { "type": [ "number", "null" ], "description": "Higher is more likely an attack." }, "deepfake": { "type": [ "string", "null" ], "enum": [ "PASS", "REVIEW", null ] }, "deepfake_score": { "type": [ "number", "null" ] } } } } } }, "AgeEstimate": { "type": "object", "properties": { "check_id": { "type": "string", "format": "uuid" }, "product": { "type": "string" }, "environment": { "type": [ "string", "null" ] }, "sandbox": { "type": "boolean" }, "checked_at": { "type": "string", "format": "date-time" }, "reference_id": { "type": "string" }, "signed_result": { "type": "string", "description": "The same answer as an ES256 JWS, verifiable with /.well-known/jwks.json." }, "decision": { "type": "string", "enum": [ "OVER_THRESHOLD", "NOT_CONFIRMED", "NO_FACE" ] }, "over_threshold": { "type": "boolean" }, "estimated_age": { "type": [ "number", "null" ] }, "threshold": { "type": "integer" }, "pass_age": { "type": "integer" }, "uncertainty": { "type": "object", "properties": { "buffer_years": { "type": "integer" }, "frames_used": { "type": "integer" }, "spread_years": { "type": [ "number", "null" ], "description": "How far estimates over several images differ; not an error bound." } } } } }, "ContentCredentialsCheck": { "type": "object", "properties": { "check_id": { "type": "string", "format": "uuid" }, "product": { "type": "string" }, "environment": { "type": [ "string", "null" ] }, "sandbox": { "type": "boolean" }, "checked_at": { "type": "string", "format": "date-time" }, "reference_id": { "type": "string" }, "signed_result": { "type": "string", "description": "The same answer as an ES256 JWS, verifiable with /.well-known/jwks.json." }, "state": { "type": "string", "enum": [ "CHECKED", "NOT_APPLICABLE" ] }, "reason": { "type": [ "string", "null" ] }, "verdict": { "type": [ "string", "null" ], "enum": [ "trusted", "valid_untrusted", "invalid", "no_manifest", null ] }, "signer": { "type": [ "string", "null" ] }, "issuer": { "type": [ "string", "null" ] }, "claim_generator": { "type": [ "string", "null" ] }, "signed_at": { "type": [ "string", "null" ] }, "digital_source_type": { "type": [ "string", "null" ] }, "actions": { "type": "array", "items": { "type": "string" } }, "ai_generated": { "type": "boolean" }, "edited": { "type": "boolean" }, "camera_capture": { "type": "boolean" }, "failure_codes": { "type": "array", "items": { "type": "string" } } } }, "DocumentVerification": { "type": "object", "required": [ "check_id", "status" ], "properties": { "check_id": { "type": "string", "format": "uuid" }, "product": { "type": "string" }, "environment": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "PROCESSING", "COMPLETED", "FAILED" ] }, "sandbox": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "reference_id": { "type": "string" }, "poll_url": { "type": "string" }, "result": { "type": "object", "properties": { "check_id": { "type": "string", "format": "uuid" }, "product": { "type": "string" }, "environment": { "type": [ "string", "null" ] }, "sandbox": { "type": "boolean" }, "checked_at": { "type": "string", "format": "date-time" }, "reference_id": { "type": "string" }, "signed_result": { "type": "string", "description": "The same answer as an ES256 JWS, verifiable with /.well-known/jwks.json." }, "decision": { "type": "string", "enum": [ "PASS", "FAIL", "REVIEW" ] }, "outcome": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "document": { "type": "object" }, "fields": { "type": "object", "description": "given_names, surname, document_number, date_of_birth, expiration_date, nationality, sex, issuing_country." }, "mrz": { "type": [ "object", "null" ], "description": "The MRZ fields and their check-digit results." }, "fraud": { "type": "object" }, "authenticity": { "type": [ "object", "null" ] }, "checks_not_run": { "type": "array", "items": { "type": "string" } } } }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "ProofOfAddressRead": { "type": "object", "required": [ "check_id", "status" ], "properties": { "check_id": { "type": "string", "format": "uuid" }, "product": { "type": "string" }, "environment": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "PROCESSING", "COMPLETED", "FAILED" ] }, "sandbox": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "reference_id": { "type": "string" }, "poll_url": { "type": "string" }, "result": { "type": "object", "properties": { "check_id": { "type": "string", "format": "uuid" }, "product": { "type": "string" }, "environment": { "type": [ "string", "null" ] }, "sandbox": { "type": "boolean" }, "checked_at": { "type": "string", "format": "date-time" }, "reference_id": { "type": "string" }, "signed_result": { "type": "string", "description": "The same answer as an ES256 JWS, verifiable with /.well-known/jwks.json." }, "state": { "type": "string", "enum": [ "PASS", "REVIEW", "ERROR" ] }, "read": { "type": "boolean", "description": "Whether the reader read the file (what is charged)." }, "consistent": { "type": "boolean" }, "findings": { "type": "array", "items": { "type": "string" } }, "document_type": { "type": [ "string", "null" ] }, "issuer": { "type": [ "string", "null" ] }, "issued_on": { "type": [ "string", "null" ] }, "age_days": { "type": [ "integer", "null" ] }, "name_score": { "type": [ "number", "null" ] }, "address": { "type": [ "object", "null" ] }, "postcode_match": { "type": [ "boolean", "null" ] }, "qr_bill": { "type": [ "object", "null" ] }, "pdf": { "type": [ "object", "null" ] } } }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "Error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" } } }, "CreateSession": { "type": "object", "additionalProperties": false, "properties": { "workflow_id": { "type": [ "string", "null" ], "description": "A published workflow of your organization." }, "vendor_data": { "type": [ "string", "null" ], "maxLength": 256, "description": "Your id for the person. Returned in webhooks and results. While a session for the same vendor_data and workflow_id is unfinished, creating again returns it." }, "metadata": { "type": [ "object", "null" ], "description": "Your JSON, up to 16 KB. Returned in webhooks and results. Stored as plain JSON: do not put sensitive personal data here." }, "callback_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "description": "https URL the person is sent back to at the end." }, "language": { "type": [ "string", "null" ], "enum": [ "en", "de", "fr", "it", null ] }, "contact": { "type": [ "object", "null" ], "properties": { "email": { "type": [ "string", "null" ], "maxLength": 254 }, "phone": { "type": [ "string", "null" ], "maxLength": 32, "description": "E.164, e.g. +41791234567." } }, "description": "Prefills the email and phone steps of the workflow." }, "reusable": { "type": [ "boolean", "null" ], "description": "The person may present their secuveri ID (secuveri Wallet) instead of capturing a document; a new liveness selfie is matched against its portrait. Needs Liveness Check and Face Match in the workflow; not with AML screening, proof of address or age estimation (422). 503 when reusable verification is not available." }, "type": { "type": [ "string", "null" ], "enum": [ "verification", "reauth", null ], "description": "reauth: a selfie with liveness matched against the face of the customer's last approved verification (needs vendor_data). 409 no_reference when no stored face remains." }, "send_link": { "type": [ "string", "null" ], "enum": [ "email", "sms", null ], "description": "Also send the hosted link to contact.email or contact.phone, in the session's language. Organization keys only." }, "sandbox_scenario": { "type": [ "string", "null" ], "enum": [ "approved", "declined_tampered", "declined_expired", "declined_unreadable", "declined_face_mismatch", "review_liveness", "review_aml", "review_document", "check_error", null ], "description": "sk_test_ keys only. The session finishes at once with this outcome, with the usual webhook and signed result. Free; nothing is captured." }, "expected_details": { "type": [ "object", "null" ], "additionalProperties": false, "properties": { "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "date_of_birth": { "type": [ "string", "null" ] }, "nationality": { "type": [ "string", "null" ] }, "document_country": { "type": [ "string", "null" ] }, "document_number": { "type": [ "string", "null" ] }, "address_country": { "type": [ "string", "null" ] }, "address_postal_code": { "type": [ "string", "null" ] }, "address_locality": { "type": [ "string", "null" ] } }, "description": "Who you expect. A field that disagrees with the document sends the verification to review (EXPECTED_DETAILS_REVIEW). Dates as YYYY-MM-DD, countries as ISO alpha-3. The address fields are not on identity documents and are never compared with them: the FINMA profile uses them for its digital address evidence (country against the IP country; Swiss postal code and locality against the official directory) when no proof of address was read." } } }, "Session": { "type": "object", "required": [ "session_id", "verification_id", "status", "created_at", "session_token" ], "properties": { "session_id": { "type": "string", "format": "uuid" }, "verification_id": { "type": "string" }, "status": { "type": "string", "enum": [ "CREATED", "DOC_PROCESSING", "MRZ_FOUND", "NFC_PROCESSING", "DOC_DONE", "SELFIE_PROCESSING", "SELFIE_DONE", "COMPLETE", "FAILED", "REVIEW_REQUIRED", "CHECK_ERROR", "EXPIRED" ] }, "created_at": { "type": "string", "format": "date-time" }, "session_token": { "type": "string", "description": "Grants the person's browser access to this session." }, "url": { "type": [ "string", "null" ], "description": "The hosted verification link." }, "sandbox_scenario": { "type": "string", "description": "Echoed when the session was finished by a scenario." }, "link_sent": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "email", "sms" ] }, "status": { "type": "string", "enum": [ "queued", "cooldown", "sent", "failed", "unavailable" ] } }, "description": "Present when send_link was requested, including on reused sessions. queued means durably accepted for background delivery, not sent or delivered; cooldown means a pending job, the 30-second resend interval, or the five-per-hour limit prevents another send." }, "reference": { "type": "object", "properties": { "verification_id": { "type": "string" }, "source": { "type": "string", "enum": [ "stored_chip", "stored_selfie", "stored_document" ] } }, "description": "type reauth: whose stored face is the reference." }, "reused": { "type": "boolean", "description": "true when an unfinished session for the same vendor_data and workflow_id was returned instead of a new one." } } }, "ResultPayload": { "type": "object", "properties": { "iss": { "type": "string" }, "aud": { "type": "string", "description": "Your organization id." }, "sub": { "type": "string", "description": "The verification id." }, "iat": { "type": "integer" }, "jti": { "type": "string" }, "verification": { "type": "object", "properties": { "verification_id": { "type": "string" }, "session_id": { "type": "string" }, "workflow_id": { "type": [ "string", "null" ] }, "vendor_data": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ] }, "status": { "type": "string", "enum": [ "COMPLETE", "FAILED", "REVIEW_REQUIRED", "CHECK_ERROR", "EXPIRED" ] }, "verdict": { "type": [ "string", "null" ], "enum": [ "APPROVED", "REJECTED", null ] }, "trust_level": { "type": [ "string", "null" ], "enum": [ "NONE", "BASIC", "STANDARD", "HIGH", null ] }, "outcome_reason": { "type": [ "string", "null" ], "enum": [ "CAPTURE_ATTEMPTS_EXHAUSTED", "CAPTURE_ENVIRONMENT_REVIEW", "DOCUMENT_AUTHENTICITY_REVIEW", "FACE_REGISTRY_REVIEW", "INSTALLATION_VELOCITY_REVIEW", "EXPECTED_DETAILS_REVIEW", "DOCUMENT_REGISTRY_REVIEW", "CONTACT_RISK_REVIEW", "AML_REVIEW", "IP_COUNTRY_RESTRICTED", "IP_COUNTRY_DIFFERS", "FACE_MATCH_REVIEW", "STATUS_RULE", "AGE_ESTIMATION_REVIEW", "LIST_BLOCK", "CAMERA_INJECTION", "FLASH_REFLECTION_REVIEW", "PROOF_OF_ADDRESS_REVIEW", "PROOF_OF_ADDRESS_OUTDATED", "PROOF_OF_ADDRESS_NO_NAME_OR_ADDRESS", "PROOF_OF_ADDRESS_WRONG_DOCUMENT", "PROOF_OF_ADDRESS_EDITED", "CONTENT_CREDENTIALS_AI_GENERATED", "CONTENT_CREDENTIALS_INVALID", "CONTENT_CREDENTIALS_EDITED", "NFC_REQUIRED_REVIEW", "FINMA_CHIP_NOT_VERIFIED", "FINMA_PORTRAIT_MISMATCH", "SECURITY_FEATURES_INSUFFICIENT", "SECURITY_FEATURE_FAILED", "FINMA_MRZ_NOT_CROSSCHECKED", "FINMA_ADDRESS_UNVERIFIED", "FINMA_HIGHER_RISK", "FINMA_EID_NOT_VERIFIED", "FINMA_EID_BETA_CREDENTIAL", "BENEFICIAL_OWNER_NOT_CONFIRMED", "BENEFICIAL_OWNER_THIRD_PARTY", "MORPH_REVIEW", "MORPH_ERROR", "MORPH_SKIPPED", "LIVENESS_REVIEW", "DEEPFAKE_REVIEW", "REQUIRED_SELFIE_CHECK_ERROR", "WORKER_RETRIES_EXHAUSTED", "ORCHESTRATION_RETRIES_EXHAUSTED", "SELFIE_QUEUE_UNAVAILABLE", "SWISS_EID_PORTRAIT_MISMATCH", "SWISS_EID_AGE_NOT_MET", "DOCUMENT_IMAGE_UNAVAILABLE", "DOCUMENT_PROCESSING_ERROR", "DOCUMENT_OCR_ERROR", "DOCUMENT_QUEUE_UNAVAILABLE", "FRAUD_IMAGE_UNAVAILABLE", "FRAUD_DOCUMENT_CROP_UNAVAILABLE", "FRAUD_EVIDENCE_UNAVAILABLE", "FRAUD_TAMPER_ERROR", "FRAUD_IDENTITY_ERROR", "FRAUD_QUEUE_UNAVAILABLE", "CATALOG_REVISION_UNAVAILABLE", null ], "description": "Why the verification was held, rejected by a workflow setting, or could not finish." }, "identification_method": { "type": [ "string", "null" ], "enum": [ "swiss_eid", "swiss_eid_age", "reusable_credential", "face_check", "nfc", "document", null ], "description": "How the person was identified. swiss_eid: the Swiss e-ID from the swiyu wallet replaced the document and a liveness selfie was matched against its portrait. swiss_eid_age: only the e-ID's age attribute was disclosed; nobody is identified." }, "swiss_eid": { "type": "object", "description": "Present when the Swiss e-ID was presented. Provenance only: the disclosed attributes stay in the full report.", "properties": { "state": { "type": "string", "enum": [ "PENDING", "VERIFIED", "FAILED" ] }, "mode": { "type": "string", "enum": [ "identity", "age" ] }, "environment": { "type": [ "string", "null" ], "enum": [ "beta", "production", null ] }, "beta": { "type": "boolean", "description": "A swiyu public-beta credential, which is not a proof of identity." }, "notice": { "type": "string", "description": "\"Beta credential — not a proof of identity\" when beta." }, "issuer": { "type": [ "string", "null" ] }, "trust_source": { "type": [ "string", "null" ], "enum": [ "registry", "static", null ] }, "credential_type": { "type": [ "string", "null" ] }, "credential_status": { "type": [ "string", "null" ] }, "holder_binding": { "type": "boolean" }, "disclosed": { "type": "array", "items": { "type": "string" } }, "failure_reasons": { "type": "array", "items": { "type": "string", "enum": [ "SWISS_EID_CREDENTIAL_INVALID", "SWISS_EID_EXPIRED", "SWISS_EID_REVOKED", "SWISS_EID_UNTRUSTED_ISSUER", "SWISS_EID_HOLDER_BINDING_FAILED", "SWISS_EID_MISSING_ATTRIBUTES", "SWISS_EID_AGE_NOT_MET", "SWISS_EID_PORTRAIT_MISMATCH", "SWISS_EID_TRUST_UNAVAILABLE", "SWISS_EID_DECLINED", "SWISS_EID_REQUEST_EXPIRED" ] }, "description": "Why earlier presentations in this verification were refused." } } }, "expected_details": { "type": [ "object", "null" ], "description": "Per field: match, mismatch or unavailable." }, "document": { "type": "object", "properties": { "type": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "chip_verified": { "type": "boolean" }, "outcome": { "type": [ "string", "null" ], "enum": [ "UNSUPPORTED_DOCUMENT", "UNREADABLE_DOCUMENT", "TAMPERED", "IDENTITY_MISMATCH", "SPECIMEN_DOCUMENT", "DOCUMENT_EXPIRED", "WRONG_DOCUMENT_TYPE", "WRONG_COUNTRY", "AGE_REQUIREMENT_NOT_MET", null ], "description": "Why the document was rejected; null otherwise." } } }, "checks": { "type": "object", "properties": { "document": { "type": [ "string", "null" ], "enum": [ "DISABLED", "NOT_APPLICABLE", "PENDING", "NOT_RUN", "PASS", "FAIL", "ERROR", "REVIEW", null ] }, "morph": { "type": [ "string", "null" ], "enum": [ "DISABLED", "NOT_APPLICABLE", "PENDING", "NOT_RUN", "PASS", "FAIL", "ERROR", "REVIEW", null ] }, "liveness": { "type": [ "string", "null" ], "enum": [ "DISABLED", "NOT_APPLICABLE", "PENDING", "NOT_RUN", "PASS", "FAIL", "ERROR", "REVIEW", null ] }, "face-match": { "type": [ "string", "null" ], "enum": [ "DISABLED", "NOT_APPLICABLE", "PENDING", "NOT_RUN", "PASS", "FAIL", "ERROR", "REVIEW", null ] }, "deepfake": { "type": [ "string", "null" ], "enum": [ "DISABLED", "NOT_APPLICABLE", "PENDING", "NOT_RUN", "PASS", "FAIL", "ERROR", "REVIEW", null ] } } }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "content_credentials": { "type": "object", "description": "Present when the workflow checks Content Credentials (C2PA) (identity-document option, or the proof-of-address option of older workflows). One entry per checked image: the document photos and the uploaded proof of address.", "properties": { "images": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "document_front", "document_back", "proof_of_address" ], "description": "Which image: the document's front or back photo, or the uploaded proof of address." }, "state": { "type": "string", "enum": [ "CHECKED", "NOT_APPLICABLE", "NOT_CHECKED" ], "description": "NOT_APPLICABLE: the file cannot carry credentials here (a PDF). NOT_CHECKED: the check could not run; never held against the verification." }, "verdict": { "type": [ "string", "null" ], "enum": [ "trusted", "valid_untrusted", "invalid", "no_manifest", null ], "description": "trusted: unchanged and signed by a C2PA Trust List signer. valid_untrusted: unchanged, unknown signer. invalid: changed after signing or a broken signature. no_manifest: no credentials (common, not negative)." }, "ai_generated": { "type": "boolean", "description": "The credentials say the image was generated or composed with AI." }, "edited": { "type": "boolean", "description": "The credentials record content edits or a composite." }, "camera_capture": { "type": "boolean", "description": "Signed as a camera capture. A positive signal only." }, "digital_source_type": { "type": [ "string", "null" ], "description": "IPTC digital source type, e.g. digitalCapture or trainedAlgorithmicMedia." }, "signer": { "type": [ "string", "null" ], "description": "Organization of the signing certificate." }, "claim_generator": { "type": [ "string", "null" ], "description": "Software that wrote the credentials." }, "failure_codes": { "type": "array", "items": { "type": "string" }, "description": "C2PA validation failure codes." } } } } } }, "beneficial_owner": { "type": "object", "description": "Present when the workflow has the beneficial owner declaration step (FINMA Circular 2016/7 Rz 48). The beneficial owner's own details are in the FINMA record and the dashboard, not here.", "properties": { "state": { "type": "string", "enum": [ "PENDING_CONFIRMATION", "CONFIRMED" ] }, "is_beneficial_owner": { "type": [ "boolean", "null" ], "description": "false: the person declared someone else." }, "confirmed_at": { "type": [ "string", "null" ], "format": "date-time" }, "confirmation_method": { "type": [ "string", "null" ], "enum": [ "one_time_code", null ] }, "confirmation_channel": { "type": [ "string", "null" ], "enum": [ "email", "phone", null ] } } }, "finma": { "type": "object", "description": "Present for workflows with the FINMA online identification profile.", "properties": { "profile": { "type": "string", "enum": [ "finma-2016-7" ] }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "The profile's holds (also listed under outcome_reason codes)." }, "security_features": { "type": [ "object", "null" ], "properties": { "state": { "type": "string", "enum": [ "PASS", "FAIL", "INSUFFICIENT" ] }, "seed": { "type": [ "string", "null" ], "description": "The session's 128-bit selection seed (hex)." }, "selected": { "type": "array", "items": { "type": "object" } }, "available": { "type": "array", "items": { "type": "string" } } } }, "address_method": { "type": [ "string", "null" ], "enum": [ "proof_of_address", "digital_evidence", null ] }, "second_reviewer_required": { "type": "boolean" } } }, "proof_of_address": { "type": "object", "description": "Present when the workflow asks for a proof of address: what the reader concluded, without the name, address or issuer it read (those are in the dashboard). The reader never approves a document on its own.", "properties": { "state": { "type": [ "string", "null" ], "enum": [ "UPLOADED", "PROCESSING", "PASS", "REVIEW", "ERROR", null ], "description": "PASS: read and consistent. REVIEW: read, with findings. ERROR: could not be read (a review, never a decline). PROCESSING: the reader did not answer in time." }, "consistent": { "type": "boolean", "description": "The name matches the ID, the date is recent, issuer and address were read, no edit signs." }, "findings": { "type": "array", "items": { "type": "string" }, "description": "Reader findings, e.g. DOCUMENT_TOO_OLD, DATE_IN_FUTURE, NO_NAME_OR_ADDRESS, NOT_PROOF_OF_ADDRESS, EDIT_EVIDENCE (these decline by default), NAME_MISMATCH, NAME_NOT_FOUND, DATE_NOT_FOUND, ISSUER_UNKNOWN, ADDRESS_NOT_FOUND, ADDRESS_COUNTRY_DIFFERS, LOW_TEXT_QUALITY, ENCRYPTED_PDF, READ_TIMEOUT." }, "document_type": { "type": [ "string", "null" ], "enum": [ "utility", "telecom", "bank", "insurance", "tax", "government", "lease", "identity_document", "other", null ] }, "issued_on": { "type": [ "string", "null" ], "format": "date" }, "age_days": { "type": [ "integer", "null" ] }, "max_age_days": { "type": [ "integer", "null" ], "enum": [ 30, 60, 90, 180, null ] }, "name_score": { "type": [ "number", "null" ], "description": "Match of the name on the document with the ID, 0 to 1." }, "address_country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country of the address." } } }, "sandbox_scenario": { "type": "string", "enum": [ "approved", "declined_tampered", "declined_expired", "declined_unreadable", "declined_face_mismatch", "review_liveness", "review_aml", "review_document", "check_error" ], "description": "Present only when a sandbox scenario produced this result." } } } } }, "Jwks": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "kty": { "const": "EC" }, "crv": { "const": "P-256" }, "x": { "type": "string" }, "y": { "type": "string" }, "kid": { "type": "string" }, "use": { "const": "sig" }, "alg": { "const": "ES256" } } } } } }, "AmlScreenRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 200 }, "names": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 200 }, "maxItems": 5, "description": "Further spellings: aliases, maiden name." }, "date_of_birth": { "type": "string", "description": "YYYY-MM-DD." }, "nationality": { "type": "string", "pattern": "^[A-Za-z]{3}$", "description": "ISO alpha-3." }, "document_number": { "type": "string", "minLength": 5, "maxLength": 64 }, "include_peps": { "type": "boolean", "default": true }, "reference": { "type": "string", "maxLength": 128, "description": "Your id; echoed back and included in the encrypted saved response when Idempotency-Key is used." } }, "description": "name or names is required." }, "FinmaRecord": { "type": "object", "description": "services/shared/finma-record.ts. Outcomes: MET, NOT_MET, REVIEW, NOT_APPLICABLE, NOT_SUPPORTED, INFORMATION.", "properties": { "record_version": { "type": "integer", "enum": [ 1 ] }, "kind": { "type": "string", "enum": [ "finma-2016-7-identification-record" ] }, "generated_at": { "type": "string", "format": "date-time" }, "verification_id": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "requirements": { "type": "array", "items": { "type": "object", "properties": { "rz": { "type": "string" }, "requirement": { "type": "string" }, "evidence": { "type": "string" }, "outcome": { "type": "string", "enum": [ "MET", "NOT_MET", "REVIEW", "NOT_APPLICABLE", "NOT_SUPPORTED", "INFORMATION" ] } } } }, "security_feature_selection": { "type": [ "object", "null" ] }, "reviewer_actions": { "type": "array", "items": { "type": "object" } }, "limitations": { "type": "array", "items": { "type": "string" } } } }, "AmlScreening": { "type": "object", "properties": { "screening_id": { "type": "string" }, "state": { "type": "string", "enum": [ "CLEAR", "POSSIBLE_MATCH" ] }, "hits": { "type": "array", "items": { "type": "object", "properties": { "list": { "type": "string", "enum": [ "seco", "eu", "un", "ofac", "uk", "pep" ] }, "entry_id": { "type": "string" }, "kind": { "type": "string" }, "matched_name": { "type": "string" }, "score": { "type": "number" }, "breakdown": { "type": "object" }, "programs": { "type": "array", "items": { "type": "string" } }, "listed_on": { "type": [ "string", "null" ] } } } }, "lists": { "type": "array", "items": { "type": "object" }, "description": "The list versions used." }, "include_peps": { "type": "boolean" }, "screened_at": { "type": "string", "format": "date-time" }, "reference": { "type": "string" }, "signed_result": { "type": "string", "description": "The same answer as an ES256 JWS (typ aml_screening)." } } }, "NewListEntry": { "type": "object", "required": [ "kind", "type", "value" ], "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "block", "allow" ] }, "type": { "type": "string", "enum": [ "email", "phone", "ip", "installation", "vendor_data", "country" ], "description": "installation is the device id from a verification report; vendor_data is your id for the person; country is the document's issuing country (ISO alpha-2)." }, "value": { "type": "string", "minLength": 1, "maxLength": 320, "description": "For ip, an address or a CIDR range." }, "reason": { "type": "string", "maxLength": 1000 }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Must be in the future." } } }, "ListEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "block", "allow" ] }, "entry_type": { "type": "string", "enum": [ "email", "phone", "ip", "installation", "vendor_data", "country" ] }, "hint": { "type": "string", "description": "A masked hint for emails, phones, devices and vendor_data; the address or range for ip, the code for country." }, "reason": { "type": "string" }, "source_verification_id": { "type": [ "string", "null" ], "description": "Set when blocked from a verification." }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ListEntryResult": { "type": "object", "properties": { "entry": { "oneOf": [ { "$ref": "#/components/schemas/ListEntry" }, { "type": "null" } ] }, "created": { "type": "boolean" } } }, "KybOpenCase": { "type": "object", "additionalProperties": false, "required": [ "workflow_id" ], "properties": { "uid": { "type": "string", "description": "Swiss UID, CHE-123.456.789 or CHE123456789." }, "name": { "type": "string", "description": "Company name; with a UID it is compared with the registered name (KYB_NAME_MISMATCH)." }, "workflow_id": { "type": "string", "format": "uuid" }, "reference": { "type": "string", "maxLength": 128, "description": "Your id for the company; echoed back." }, "persons": { "type": "array", "maxItems": 20, "items": { "type": "object", "properties": { "registry_person_id": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "send_link": { "enum": [ "email", "sms" ] } } } }, "language": { "enum": [ "de", "fr", "it", "en" ], "description": "Language of legal form labels." } } }, "KybDeclaration": { "type": "object", "additionalProperties": false, "required": [ "kind", "persons", "signer", "confirmed" ], "properties": { "kind": { "enum": [ "beneficial_owners", "controlling_persons" ] }, "persons": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "type": "object", "required": [ "name", "control" ], "properties": { "name": { "type": "string" }, "date_of_birth": { "type": "string", "format": "date" }, "nationality": { "type": "string", "description": "ISO 3166-1 alpha-3" }, "address": { "type": "string" }, "ownership_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "control": { "enum": [ "ownership", "other_control", "management" ] }, "email": { "type": "string" }, "phone": { "type": "string" } } } }, "signer": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "function": { "type": "string" } } }, "confirmed": { "const": true } } }, "KybCase": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "const": "kyb_case" }, "status": { "enum": [ "open", "review_required", "approved", "declined" ] }, "reasons": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "action": { "enum": [ "review", "decline" ] } } } }, "outstanding": { "type": "array", "items": { "enum": [ "KYB_DECLARATION_MISSING", "KYB_REGISTER_EXTRACT_MISSING", "PERSON_VERIFICATION_PENDING", "SIGNATORY_SELECTION_REQUIRED" ] }, "description": "What an open case waits for." }, "company": { "type": [ "object", "null" ], "description": "Register data: uid, name, legalForm, seat, canton, address, status, purpose, capital, publications." }, "ubo": { "type": [ "object", "null" ], "description": "status identified | partial | none_identified | not_public, threshold_pct, declaration_required." }, "signing_rules": { "type": "array", "items": { "type": "object" } }, "persons": { "type": "array", "items": { "type": "object" }, "description": "Registered and declared persons with roles, signing_mode, is_signatory, is_ubo, ownership_pct, verification (status, verification_id) and screening." }, "company_screening": { "type": [ "object", "null" ] }, "declaration": { "type": [ "object", "null" ] }, "documents": { "type": "array", "items": { "type": "object" } }, "declaration_url": { "type": [ "string", "null" ] }, "signed_result": { "type": "string", "description": "Decided cases only, when result signing is configured." } } }, "WebhookEvent": { "type": "object", "required": [ "id", "type", "created_at", "organization_id", "data" ], "properties": { "id": { "type": "string", "description": "Stable across retries; use it to drop duplicates." }, "type": { "type": "string", "enum": [ "verification.completed", "verification.review_required", "verification.reviewed", "verification.expired", "kyb_case.completed", "kyb_case.review_required", "kyb_case.reviewed", "documents.verify.completed", "proof_of_address.read.completed", "webhook.test" ] }, "created_at": { "type": "string", "format": "date-time" }, "organization_id": { "type": "string" }, "data": { "type": "object", "properties": { "verification_id": { "type": [ "string", "null" ] }, "session_id": { "type": [ "string", "null" ] }, "workflow_id": { "type": [ "string", "null" ] }, "vendor_data": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ] }, "status": { "type": [ "string", "null" ] }, "verdict": { "type": [ "string", "null" ] }, "decision": { "type": [ "string", "null" ], "enum": [ "APPROVE", "REJECT", null ], "description": "verification.reviewed and kyb_case.reviewed only." }, "manual_override": { "type": "boolean" }, "identification_method": { "type": [ "string", "null" ], "enum": [ "swiss_eid", "swiss_eid_age", "reusable_credential", "face_check", "nfc", "document", null ], "description": "How the person was identified, once the verification has a report." }, "swiss_eid_beta": { "type": "boolean", "description": "true when the result rests on a swiyu beta credential, which is not a proof of identity." }, "test": { "type": "boolean" }, "kyb_case_id": { "type": "string", "description": "kyb_case.* events only; verification_id and session_id are null." }, "check_id": { "type": "string", "description": "Standalone check events only." }, "product": { "type": "string", "description": "Standalone check events only." } } } } } } }, "externalDocs": { "description": "secuveri API docs", "url": "https://app.secuveri.com/docs" } }