> ## Documentation Index > Fetch the complete documentation index at: https://devdocs.veriff.com/llms.txt > Use this file to discover all available pages before exploring further. # Create session > ### Creates a verification session with the data specified in the request body #### When to use this endpoint - Use this endpoint to **initiate a new verification session** for an end-user. Every verification flow begins with creating a session. #### Request body content The contents of the request body depends on: - Whether you are using the SDK or API to capture end-user data - The type of verification solution the session is created for Minimum request body: - Empty `verification` object Payload examples: - Click on the **"Show examples" button** in "Request" section to see **request body examples for specific solutions/products**. #### Response data Once you create the verification session, you receive: - Unique session `id` (store this - required for other endpoints) - Unique `sessionToken` (legacy purposes, see [FAQ](https://devdocs.veriff.com/docs/general-faq#what-is-a-sessiontoken)) - Session URL in `verification.url` parameter (required for [SDK integrations](https://devdocs.veriff.com/docs/sdk-guide)) #### Getting session results After the end-user completes the verification: - **Primary:** [webhook](https://devdocs.veriff.com/docs/webhooks-guide) notifications sent to `webhook URL` - **Secondary:** Poll [`GET /v1/sessions/{id}/decision`](https://devdocs.veriff.com/apidocs/v1sessionsiddecision-1) endpoint - **Backup:** Use polling if webhook delivery fails #### Implementation notes - Store the returned session `id` - it is required for all other session-related endpoints - Always ensure that you use the correct API URL to send requests. See the [API URL section](https://devdocs.veriff.com/apidocs/veriff-public-api-guides#api-url) for more info. - See [Javascript sample implementation](https://github.com/Veriff/js-integration-demo) for SDK integration examples - The order of parameters in the real API response can differ from the order you see in this documentation. This is expected and part of the [Backwards compatible changes](https://devdocs.veriff.com/apidocs/veriff-public-api-guides#backwards-compatible-changes) requirements. #### Additional info: end-user flow after session creation 1. Create session → Get `session.verification.url` 2. Redirect end-user to `verification.url` 3. End-user completes verification flow 4. End-user redirected to your callback URL (if configured) 5. Receive webhook notification OR poll for results ## OpenAPI ````json POST /v1/sessions { "openapi": "3.0.0", "info": { "title": "Veriff Public API", "version": "1.0.0" }, "servers": [ { "url": "https://example-base-url" } ], "tags": [ { "name": "Session management", "description": "Create and manage verification sessions" }, { "name": "Data submission", "description": "Upload media and submit verification data during the session" }, { "name": "Session results", "description": "Retrieve verification decisions and results" }, { "name": "Media management", "description": "Access and download verification media files and media file-related data" }, { "name": "Database verification", "description": "Validate identity against national registries and databases" }, { "name": "Certificate management", "description": "Retrieve long-term preservation certificates and their source documents for a verification session" } ], "paths": { "/v1/sessions": { "post": { "summary": "Create session", "description": "### Creates a verification session with the data specified in the request body\n\n#### When to use this endpoint\n\n- Use this endpoint to **initiate a new verification session** for an end-user. Every verification flow begins with creating a session.\n\n#### Request body content\n\nThe contents of the request body depends on:\n- Whether you are using the SDK or API to capture end-user data\n- The type of verification solution the session is created for\n\nMinimum request body:\n- Empty `verification` object\n\nPayload examples:\n- Click on the **\"Show examples\" button** in \"Request\" section to see **request body examples for specific solutions/products**.\n\n#### Response data\n\nOnce you create the verification session, you receive:\n- Unique session `id` (store this - required for other endpoints)\n- Unique `sessionToken` (legacy purposes, see [FAQ](https://devdocs.veriff.com/docs/general-faq#what-is-a-sessiontoken))\n- Session URL in `verification.url` parameter (required for [SDK integrations](https://devdocs.veriff.com/docs/sdk-guide))\n\n#### Getting session results\n\nAfter the end-user completes the verification:\n\n- **Primary:** [webhook](https://devdocs.veriff.com/docs/webhooks-guide) notifications sent to `webhook URL`\n- **Secondary:** Poll [`GET /v1/sessions/{id}/decision`](https://devdocs.veriff.com/apidocs/v1sessionsiddecision-1) endpoint \n- **Backup:** Use polling if webhook delivery fails\n\n#### Implementation notes\n\n- Store the returned session `id` - it is required for all other session-related endpoints\n- Always ensure that you use the correct API URL to send requests. See the [API URL section](https://devdocs.veriff.com/apidocs/veriff-public-api-guides#api-url) for more info.\n- See [Javascript sample implementation](https://github.com/Veriff/js-integration-demo) for SDK integration examples\n- The order of parameters in the real API response can differ from the order you see in this documentation. \n This is expected and part of the [Backwards compatible changes](https://devdocs.veriff.com/apidocs/veriff-public-api-guides#backwards-compatible-changes) requirements. \n\n#### Additional info: end-user flow after session creation\n\n1. Create session → Get `session.verification.url`\n2. Redirect end-user to `verification.url`\n3. End-user completes verification flow\n4. End-user redirected to your callback URL (if configured)\n5. Receive webhook notification OR poll for results\n", "operationId": "createSession", "tags": [ "Session management" ], "parameters": [ { "name": "X-AUTH-CLIENT", "in": "header", "description": "Your integration's API key (occasionally referred to as the \"Token\", \"API public key\" or \"Publishable key\"). Required for all API requests.\n\nYou can find your API key in the Veriff Customer Portal under Settings > API keys.\n", "required": "true", "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "description": "Must be set to application/json", "required": "true", "schema": { "type": "string", "enum": [ "application/json" ] }, "example": "application/json" } ], "requestBody": { "required": "true", "description": "Session initialization data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionRequestBody" }, "examples": { "minimal_payload": { "description": "Empty verification object - minimum required to create a session", "value": { "verification": {} } }, "expanded_payload": { "description": "Session with person data, document details, and end-user ID", "value": { "verification": { "callback": "https://example.com/callback", "person": { "firstName": "John", "lastName": "Smith", "idNumber": "123456789" }, "document": { "number": "B01234567", "type": "PASSPORT", "country": "US" }, "endUserId": "c1de400b-1877-4284-8494-071d37916197" } } }, "expanded_payload_with_hostAppLink": { "description": "Session with person data, document details, end-user ID, and host app link", "value": { "verification": { "callback": "https://example.com/callback", "hostAppLink": "myapp://verification/complete", "person": { "firstName": "John", "lastName": "Smith", "idNumber": "123456789" }, "document": { "number": "B01234567", "type": "PASSPORT", "country": "US" }, "endUserId": "c1de400b-1877-4284-8494-071d37916197" } } }, "session_with_service_coverage": { "description": "Session with service coverage configuration", "value": { "verification": { "serviceCoverage": { "country": "US" } } } }, "session_with_consent": { "description": "Session with person data, document details, end-user ID, and consent array", "value": { "verification": { "person": { "firstName": "John", "lastName": "Smith", "idNumber": "123456789" }, "document": { "number": "B01234567", "type": "PASSPORT", "country": "US" }, "endUserId": "c1de400b-1877-4284-8494-071d37916197", "consents": [ { "type": "ine", "approved": "true", "text": "User agrees to share their INE details", "timestamp": "2026-05-07T08:00:00Z" } ] } } }, "aml_screening_standalone": { "description": "Session for [AML/sanctions screening](https://devdocs.veriff.com/docs/aml-screening-solution) with required person data", "value": { "verification": { "person": { "firstName": "John", "lastName": "Smith", "dateOfBirth": "1990-01-01" } } } }, "br_cadastro_unico_database": { "description": "Session to validate Brazilian users against social benefit registries. See [here](https://devdocs.veriff.com/docs/brazilian-cadastro-unico-database-verification) for full documentation.", "value": { "verification": { "person": { "idNumber": "12345678901", "dateOfBirth": "1990-01-15" } } } }, "br_probet_database": { "description": "Session to validate users against Brazil's betting exclusion registries. See [here](https://devdocs.veriff.com/docs/pro-bet-database-verification) for full documentation.", "value": { "verification": { "person": { "idNumber": "12345678901", "dateOfBirth": "1990-01-15" } } } }, "mx_curp_db_verification": { "description": "Session for [Mexican CURP database verification](https://devdocs.veriff.com/docs/curp-database-verification) using person ID number", "value": { "verification": { "person": { "idNumber": "VISH560427MSRLNL06" } } } }, "mx_ine_db_verification_using_ife": { "description": "Session for [Mexican INE database verification](https://devdocs.veriff.com/docs/ine-database-verification) using CIC and IFE identifier (OCR code) for card type D", "value": { "verification": { "callback": "https://yourwebsite.com/webhook", "document": { "number": "123456789M00000000", "documentNumberIdentifiers": { "mxIfe": "1234567890123" } } } } }, "mx_ine_db_verification_using_ine": { "description": "Session for [Mexican INE database verification](https://devdocs.veriff.com/docs/ine-database-verification) using CIC and INE identifier (Identificador Ciudadano) for card types E, F, G, and H", "value": { "verification": { "callback": "https://yourwebsite.com/webhook", "document": { "number": "123456789M00000000", "documentNumberIdentifiers": { "mxIne": "1234567890123" } } } } }, "proof_of_address_address_matching": { "description": "Proof of Address [address matching](https://devdocs.veriff.com/docs/proof-of-address-verification#address-matching) session to compare addresses from two different sources", "value": { "verification": { "person": { "firstName": "John", "lastName": "Smith" }, "address": { "fullAddress": "123, Main Street, Your County, Anytown 12345" }, "proofOfAddress": { "acceptableTypes": [ { "name": "UTILITY_BILL" }, { "name": "PHONE_BILL" }, { "name": "TAX_DOCUMENT" } ] }, "endUserId": "c1de400b-1877-4284-8494-071d37916197" } } }, "proof_of_address_simple": { "description": "Can be used for [address extraction](https://devdocs.veriff.com/docs/proof-of-address-verification#proof-of-address-extraction) and [address validation](https://devdocs.veriff.com/docs/proof-of-address-verification#address-validation) solutions. See the full Proof of Address documentation [here](https://devdocs.veriff.com/docs/proof-of-address-verification)", "value": { "verification": { "proofOfAddress": { "acceptableTypes": [ { "name": "UTILITY_BILL" }, { "name": "PHONE_BILL" }, { "name": "TAX_DOCUMENT" } ] }, "endUserId": "c1de400b-1877-4284-8494-071d37916197" } } }, "proof_of_address_with_name_match": { "description": "Can be used for [address extraction](https://devdocs.veriff.com/docs/proof-of-address-verification#proof-of-address-extraction) and [address validation](https://devdocs.veriff.com/docs/proof-of-address-verification#address-validation) solutions. See the full Proof of Address documentation [here](https://devdocs.veriff.com/docs/proof-of-address-verification)", "value": { "verification": { "person": { "firstName": "John", "lastName": "Smith" }, "proofOfAddress": { "acceptableTypes": [ { "name": "UTILITY_BILL" }, { "name": "PHONE_BILL" }, { "name": "TAX_DOCUMENT" } ] }, "endUserId": "c1de400b-1877-4284-8494-071d37916197" } } }, "selfie_to_selfie_biometric": { "description": "Session for [Biometric Authentication](https://devdocs.veriff.com/docs/biometric-authentication) to verify identity by comparing two selfie images", "value": { "verification": { "person": { "firstName": "John", "lastName": "Smith" }, "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4", "vendorData": "12345678" } } }, "session_with_tag_parameter": { "description": "Session with custom tag parameter", "value": { "verification": { "vendorData": "12345678", "tag": "your_custom_tag_max_64_characters" } } }, "uk_diatf_m1b": { "description": "Session for UK DIATF M1B verification with full address", "value": { "verification": { "address": { "fullAddress": "123, Main Street, Your County, Anytown 12345" } } } }, "us_light_kyc": { "description": "Session for US Database Verification: [Light KYC verification](https://devdocs.veriff.com/docs/us-database-verification#light-kyc) with person details and address", "value": { "verification": { "person": { "firstName": "John", "lastName": "Smith", "dateOfBirth": "1990-01-01", "phoneNumber": "8888888888" }, "address": { "fullAddress": "123, Main Street, Your County, Anytown 12345" } } } }, "udocs_no_init_data": { "description": "Session for [Unstructured Docs](https://devdocs.veriff.com/docs/unstructured-docs)\nverification without initData — for document extraction only\n(no InitData Matching validation).\n", "value": { "verification": {} } }, "udocs_with_init_data": { "description": "Session for [Unstructured Docs](https://devdocs.veriff.com/docs/unstructured-docs)\nverification with all possible initData fields.\n", "value": { "verification": { "document": { "number": "847293651024738569" }, "person": { "fullName": "JUAN MARTINEZ", "occupation": "Driver" }, "address": { "fullAddress": "AV INSURGENTES SUR 2847 PISO 3 COL DEL VALLE BENITO JUAREZ CIUDAD DE MEXICO MEXICO CP 03100" }, "endUserId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } }, "us_ssn_validation": { "description": "Session for US Database Verification: [SSN check](https://devdocs.veriff.com/docs/us-database-verification#ssn-check) with document number and person data", "value": { "verification": { "person": { "firstName": "John", "lastName": "Smith", "dateOfBirth": "1990-01-01" }, "document": { "number": "123456789" } } } } } } } }, "responses": { "200": { "description": "Created session", "headers": { "Content-Type": { "description": "Response content type.", "schema": { "type": "string", "example": "application/json" } }, "X-AUTH-CLIENT": { "description": "API key echoed back in response.", "schema": { "type": "string" } }, "X-HMAC-SIGNATURE": { "description": "Response body signed with the shared secret key. Required to authenticate the response sender.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionCreatedResponse" } } } }, "400": { "description": "Bad request", "headers": { "Content-Type": { "description": "Response content type.", "schema": { "type": "string", "example": "application/json" } }, "X-AUTH-CLIENT": { "description": "API key echoed back in response.", "schema": { "type": "string" } }, "X-HMAC-SIGNATURE": { "description": "Response body signed with the shared secret key. Required to authenticate the response sender.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestErrorResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "Content-Type": { "description": "Response content type.", "schema": { "type": "string", "example": "application/json" } }, "X-AUTH-CLIENT": { "description": "API key echoed back in response.", "schema": { "type": "string" } }, "X-HMAC-SIGNATURE": { "description": "Response body signed with the shared secret key. Required to authenticate the response sender.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" } } } }, "429": { "description": "Too many requests", "headers": { "Content-Type": { "description": "Response content type.", "schema": { "type": "string", "example": "application/json" } }, "X-AUTH-CLIENT": { "description": "API key echoed back in response.", "schema": { "type": "string" } }, "X-HMAC-SIGNATURE": { "description": "Response body signed with the shared secret key. Required to authenticate the response sender.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsErrorResponse" } } } }, "500": { "description": "Internal server error", "headers": { "Content-Type": { "description": "Response content type.", "schema": { "type": "string", "example": "application/json" } }, "X-AUTH-CLIENT": { "description": "API key echoed back in response.", "schema": { "type": "string" } }, "X-HMAC-SIGNATURE": { "description": "Response body signed with the shared secret key. Required to authenticate the response sender.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } } }, "x-d360-narrative-responses": "

Payload compression support info

This endpoint accepts compressed request bodies with Content-Encoding: gzip or Content-Encoding: deflate. Note that this endpoint accepts a plain JSON payload, so compression is not always necessary. For typical session initialization payloads, the bandwidth savings are negligible and the extra CPU cost on the client side outweighs the benefit.

Where compression genuinely helps is when the request includes consent records that carry a text field. The consent text typically contains the full, human-readable consent statement that was shown to the end user, and can be several KB or larger (especially for legal or regulatory consents). In those cases, gzip or deflate can shrink the payload by 60–80%, which is worthwhile.

As a rule of thumb:

Request-body compression is a transport optimization, it does not change the signing contract. Your signature is always computed over the uncompressed JSON body. The server decompresses the payload before validating the signature.

No configuration changes are required for the integration to start using this feature. To use compression, include exactly one of these Content-Encoding values in your request:

Combined values such as gzip, deflate or deflate, gzip are not supported. br is not supported on this endpoint.

Operation order

Getting the order right is critical. The signature must cover the uncompressed payload, and the compressed payload must decompress back to the exact bytes that were signed.

  1. Build the JSON payload

  2. Serialize the JSON to bytes

  3. Compute the signature over the serialized bytes ← sign BEFORE compressing

  4. Compress the serialized bytes (gzip or deflate)

  5. Send the compressed bytes with the matching Content-Encoding value

If you compress first and then sign the compressed bytes, signature validation will fail.

Request headers

Code examples

The examples below use gzip and include a consent with a long text field, which is the case where compression actually pays off. If you use deflate, keep the same signing flow and set Content-Encoding: deflate with deflate-compressed bytes.

Python

TextText

import gzip\nimport hashlib\nimport hmac\nimport json\nimport requests\nAPI_KEY = \"your-api-key\"\nSHARED_SECRET = \"your-shared-secret\"\nBASE_URL = \"https://stationapi.veriff.com\"\n# A realistic consent text is typically much longer than this snippet.\nCONSENT_TEXT = (\n    \"I consent to Veriff processing my personal data, including biometric data, \"\n    \"for identity verification purposes in accordance with the Privacy Notice. \"\n    # ... full legal text continues, often several KB ...\n)\n# Step 1–2: Build and serialize the JSON payload\npayload = {\n    \"verification\": {\n        \"callback\": \"https://example.com/callback\",\n        \"vendorData\": \"customer-123\",\n        \"consents\": [\n            {\n                \"type\": \"general\",\n                \"approved\": True,\n                \"text\": CONSENT_TEXT,\n                \"timestamp\": \"2026-05-08T10:00:00Z\",\n            }\n        ],\n    }\n}\npayload_bytes = json.dumps(payload, separators=(\",\", \":\")).encode(\"utf-8\")\n# Step 3: Sign the UNCOMPRESSED payload\nsignature = hmac.new(\n    SHARED_SECRET.encode(\"utf-8\"),\n    payload_bytes,\n    hashlib.sha256,\n).hexdigest()\n# Step 4: Compress\ncompressed = gzip.compress(payload_bytes)\n# Step 5: Send with Content-Encoding: gzip\nresponse = requests.post(\n    f\"{BASE_URL}/v1/sessions\",\n    data=compressed,                        # raw bytes, not json=\n    headers={\n        \"X-AUTH-CLIENT\": API_KEY,\n        \"X-HMAC-SIGNATURE\": signature,\n        \"Content-Type\": \"application/json\",\n        \"Content-Encoding\": \"gzip\",\n    },\n)\nprint(response.status_code, response.json())

Node.js

TextText

const crypto = require('crypto');\nconst zlib = require('zlib');\nconst https = require('https');\nconst API_KEY = 'your-api-key';\nconst SHARED_SECRET = 'your-shared-secret';\nconst BASE_URL = 'stationapi.veriff.com';\n// A realistic consent text is typically much longer than this snippet.\nconst CONSENT_TEXT =\n  'I consent to Veriff processing my personal data, including biometric data, ' +\n  'for identity verification purposes in accordance with the Privacy Notice. ' +\n  // ... full legal text continues, often several KB ...\n  '';\n// Step 1–2: Build and serialize the JSON payload\nconst payload = {\n  verification: {\n    callback: 'https://example.com/callback',\n    vendorData: 'customer-123',\n    consents: [\n      {\n        type: 'general',\n        approved: true,\n        text: CONSENT_TEXT,\n        timestamp: '2026-05-08T10:00:00Z',\n      },\n    ],\n  },\n};\nconst payloadBytes = Buffer.from(JSON.stringify(payload));\n// Step 3: Sign the UNCOMPRESSED payload\nconst signature = crypto\n  .createHmac('sha256', SHARED_SECRET)\n  .update(payloadBytes)\n  .digest('hex');\n// Step 4: Compress\nconst compressed = zlib.gzipSync(payloadBytes);\n// Step 5: Send with Content-Encoding: gzip\nconst req = https.request(\n  {\n    hostname: BASE_URL,\n    path: '/v1/sessions',\n    method: 'POST',\n    headers: {\n      'X-AUTH-CLIENT': API_KEY,\n      'X-HMAC-SIGNATURE': signature,\n      'Content-Type': 'application/json',\n      'Content-Encoding': 'gzip',\n      'Content-Length': compressed.length,\n    },\n  },\n  (res) => {\n    let body = '';\n    res.on('data', (chunk) => (body += chunk));\n    res.on('end', () => console.log(res.statusCode, body));\n  }\n);\nreq.write(compressed);\nreq.end();

Common mistakes

Compressing payloads that don't need it. For small session-creation payloads without a long consent text, the compression overhead is rarely worth it. Reach for compression when consent text or other large string fields push the body well beyond a few KB.

Signing the compressed bytes. The most common integration error. If you compress first and then compute the HMAC over the compressed output, the server will reject the request with a 401. Always sign the uncompressed JSON body.

Encoding/header mismatch. If you send Content-Encoding: gzip or Content-Encoding: deflate but the body is not encoded accordingly, the request fails with a 400. If you are not compressing, omit the Content-Encoding header.

Using json= in your HTTP library with compressed bytes. When sending compressed data, pass compressed bytes as a raw body (data= in Python requests, content= in httpx), not as a JSON parameter. Setting json= causes the HTTP library to re-serialize the payload, which defeats compression and breaks the signature.

Double compression. Do not set Content-Encoding if your HTTP client or proxy is already compressing the request transparently. If in doubt, check the outbound request body and Content-Encoding header.

Using unsupported or combined encodings. Supported values are exactly gzip or deflate. Combined values (for example, gzip, deflate) and other encodings (for example, br) fail with a 415 http error.




Changelog

Date

Description

Sep 3, 2026

address object updated:

  • buildingName and subDistrict strings added

  • neighbourhood string removed

person.gender now also accepts male and female

June 15, 2026

hostAppLink parameter added to the request body

June 3, 2026

serviceCoverage parameter added to the request body

May 19, 2026

\"Payload compression\" info added

consent object updated:

  • text string added

  • timestamp string added

Apr 24, 2026

Headers capitalization harmonized

Apr 17, 2026

Typo fixes

Apr 13, 2026

New parameters added to support the Metadata Database Verification solution session generation: to person object: fullName, landLinePhoneNumber, partnerLastName, partnerFirstName, marriageDateOfEvent, middleName, secondLastName; to document object: validFrom, validUntil, version, cardType, cardNumber, stateOfIssue, referenceNumber, registrationNumber; to address object: street, houseNumber, postcode, city, state, unit, neighbourhood. Also, new consent types dvs and general to consent.type.

Mar 18, 2026

tag parameter info and payload example added

Mar 9, 2026

Documentation updated: parent categories rearranged, intro section expanded, request and response examples added

Jan 6, 2026

New parameter occupation added to person object

Nov 6, 2025

\"Article Versoning\" renamed to \"Changelog\"
Changelog updated

Oct 30, 2025

documentNumberIdentifiers object added

Sep 16, 2025

vrf-integration-id header removed

Aug 6, 2025

Response headers added

Jul 11, 2025

Improved the note in the intro section about session creation, and about finding request parameters from Product Guides

Apr 30, 2025

- New parameters added to request's verification.person object: email, maritalStatus and isDeceased for registry checks

- New header vrf-integration-id added to support the new Flexible API keys solution

Apr 22, 2025

proofOfAddress object added to support sending proof of address data over API. This parameter is solution-specific, it is not commonly needed.

Mar 12, 2025

Documentation published

" } } }, "components": { "schemas": { "CreateSessionRequestBody": { "type": "object", "properties": { "verification": { "description": "Verification object", "allOf": [ { "$ref": "#/components/schemas/CreateSessionVerification" } ] } }, "required": [ "verification" ] }, "SessionCreatedResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "API request status.", "example": "success" }, "verification": { "description": "Verification object.", "allOf": [ { "$ref": "#/components/schemas/SessionCreatedVerification" } ] } }, "required": [ "status", "verification" ] }, "BadRequestErrorResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail" ], "example": "fail" }, "code": { "type": "string", "example": "1101" }, "message": { "type": "string", "example": "Validation failed" } }, "required": [ "status", "code", "message" ] }, "UnauthorizedErrorResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail" ], "example": "fail" }, "code": { "type": "string", "example": "1101" }, "message": { "type": "string", "example": "Mandatory X-AUTH-CLIENT header containing the API key is missing from the request." } }, "required": [ "status", "code", "message" ] }, "TooManyRequestsErrorResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail" ], "example": "fail" }, "code": { "type": "string", "example": "1004" }, "message": { "type": "string", "example": "Too many requests." } }, "required": [ "status", "code", "message" ] }, "InternalServerErrorResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail" ], "example": "fail" }, "code": { "type": "string", "example": "1101" }, "message": { "type": "string", "example": "Something went wrong" } }, "required": [ "status", "code", "message" ] }, "CreateSessionVerification": { "type": "object", "properties": { "callback": { "type": "string", "description": "The callback URL to where the end-user is redirected after the \nverification session is completed. \n\n\nDefault is visible in the Veriff \nCustomer Portal -> Settings. Changing the value in this request body \nwill overwrite the default callback URL, but it will not change the \ncallback URL that is visible in the Customer Portal.\n", "example": "https://example.com/callback" }, "person": { "description": "Data about the person being verified.", "allOf": [ { "$ref": "#/components/schemas/CreateSessionPerson" } ] }, "document": { "description": "Data about the document of the person being verified.", "allOf": [ { "$ref": "#/components/schemas/CreateSessionDocument" } ] }, "address": { "description": "Data about the address of the person being verified.", "allOf": [ { "$ref": "#/components/schemas/CreateSessionAddress" } ] }, "proofOfAddress": { "description": "Data about the PoA document of the person being verified.\n\nOptional, should be only used in [Proof of Address](https://devdocs.veriff.com/docs/proof-of-address-verification)\nintegrations.\n", "allOf": [ { "$ref": "#/components/schemas/CreateSessionProofOfAddress" } ] }, "serviceCoverage": { "description": "Object for specifying which country's verification services\nshould be offered to the end-user.\n", "allOf": [ { "$ref": "#/components/schemas/CreateSessionServiceCoverage" } ], "nullable": "true" }, "vendorData": { "type": "string", "description": "The unique identifier that you created for your end-user. It can be \nmax 1,000 characters long and contain only non-semantic data that can \nnot be resolved or used outside your systems or environments. \n\nVeriff returns it unmodified in webhooks and API response payloads, or as \n`null` if not provided.\n", "example": "1234567890" }, "endUserId": { "type": "string", "description": "The `UUID` that you created for your end-user, that can not be \nresolved or used outside your systems or environments. \n\nVeriff returns it unmodified in webhooks and API response payloads, or as `null` if \nnot provided.\n", "format": "uuid", "example": "c1de400b-1877-4284-8494-071d37916197" }, "consents": { "description": "Array of objects listing the type of consent given. \n\nOptional, should be only included for solutions/products that require consent (e.g., [MX INE Biometric Database](https://devdocs.veriff.com/docs/ine-biometric-database-verification) or\n[Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification)).\n", "type": "array", "items": { "$ref": "#/components/schemas/CreateSessionConsent" } }, "tag": { "description": "Custom marker for the session that you create, max length 64 characters. \nCan be sent only if enabled for your integration.\n\nContact your Solutions Engineer or Veriff Customer Support for info and configuration.\n", "type": "string", "example": "your_custom_tag_max_64_characters" }, "hostAppLink": { "type": "string", "nullable": "true", "description": "Optional link used to return the end-user to the host application during an external provider flow, which typically takes place in a browser.\nSend this field only if you have built your integration to return the end-user to the host app.\n", "pattern": "^[a-zA-Z][a-zA-Z0-9+.\\-]*://", "example": "myapp://verification/complete" } } }, "SessionCreatedVerification": { "type": "object", "properties": { "status": { "type": "string", "description": "Verification session status.", "example": "created" }, "id": { "type": "string", "format": "uuid", "description": "UUID v4 which identifies the verification session.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "url": { "type": "string", "description": "URL of the verification session. The end-user is redirected here to \ngo through the flow. It is a combination of the `baseUrl` and the \n`sessionToken`.\n", "example": "https://exampleURL.com/v/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "sessionToken": { "type": "string", "description": "Session-specific token of the verification.", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "host": { "type": "string", "description": "The base url the `sessionToken` can be used for.", "example": "https://exampleURL.com" }, "endUserId": { "type": "string", "description": "The `UUID` that you created for your end-user, that can not be \nresolved or used outside your systems or environments.\nVeriff returns it unmodified in webhooks and API response payloads, or as `null` if \nnot provided.\n", "format": "uuid", "example": "c1de400b-1877-4284-8494-071d37916197", "nullable": "true" }, "vendorData": { "type": "string", "description": "The unique identifier that you created for your end-user. It can be \nmax 1,000 characters long and contain only non-semantic data that can \nnot be resolved or used outside your systems or environments. \nVeriff returns it unmodified in webhooks and API response payloads, or as \n`null` if not provided.\n", "example": "1234567890", "nullable": "true" } }, "required": [ "status", "id", "url", "sessionToken", "host", "endUserId", "vendorData" ] }, "CreateSessionPerson": { "type": "object", "properties": { "firstName": { "type": "string", "description": "Person's first name.", "example": "John" }, "lastName": { "type": "string", "description": "Person's last name.", "example": "Smith" }, "idNumber": { "type": "string", "description": "Person's national identification number.", "example": "123456789" }, "phoneNumber": { "type": "string", "description": "Person's phone number.", "example": "8888888888" }, "gender": { "type": "string", "enum": [ "M", "MALE", "F", "FEMALE" ], "description": "Person's gender.", "example": "M" }, "dateOfBirth": { "type": "string", "description": "Person's date of birth. \n\nFormat: YYYY-MM-DD.\n", "example": "1990-01-01", "format": "date" }, "email": { "type": "string", "description": "Person's email address.", "example": "john.smith@example.com" }, "maritalStatus": { "type": "string", "description": "Person's marital status (mandatory only for some registry checks).\n", "enum": [ "single", "married", "divorced", "widowed" ], "example": "single" }, "isDeceased": { "type": "boolean", "description": "Person's deceased status (mandatory only for some registry checks).\n", "enum": [ "true", "false" ], "example": "false" }, "fullName": { "type": "string", "description": "Person's full name.\n\nOptional. Used as initData for\n[Unstructured Docs](https://devdocs.veriff.com/docs/unstructured-docs)\nInitData Matching validation or in [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "example": "JUAN MARTINEZ" }, "occupation": { "type": "string", "description": "Person's occupation.\n\nOptional. Used as initData for\n[Unstructured Docs](https://devdocs.veriff.com/docs/unstructured-docs)\nInitData Matching validation.\n", "example": "Driver" }, "landLinePhoneNumber": { "type": "string", "description": "Person's landline phone number.\n\nOptional, used in some registry checks, for example [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "example": "+1234567890" }, "partnerFirstName": { "type": "string", "description": "Person's partner's first name.\n\nOptional, used in some registry checks, for example [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "example": "Emily" }, "partnerLastName": { "type": "string", "description": "Person's partner's last name.\n\nOptional, used in some registry checks, for example [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "example": "Johnson" }, "marriageDateOfEvent": { "type": "string", "description": "Person's marriage date. Format: YYYY-MM-DD.\n\nOptional, used in some registry checks, for example [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "example": "2015-06-30", "format": "date" }, "middleName": { "type": "string", "description": "Person's middle name.\n\nOptional, used in some registry checks, for example [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "example": "William" }, "secondLastName": { "type": "string", "description": "Person's second last name (if applicable).\n\nOptional, used in some registry checks, for example [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "example": "Garcia" } } }, "CreateSessionDocument": { "type": "object", "properties": { "number": { "type": "string", "description": "Document number, [a-zA-Z0-9] characters only.", "example": "B01234567" }, "country": { "type": "string", "description": "Document issuing country, in capital letters.", "example": "US", "format": "ISO 3166-1 Alpha-2" }, "type": { "type": "string", "enum": [ "ID_CARD", "PASSPORT", "DRIVERS_LICENSE", "RESIDENCE_PERMIT" ], "description": "Document type for [Document + Selfie verification](https://devdocs.veriff.com/docs/document-selfie-idv)\nor [Document-only verification](https://devdocs.veriff.com/docs/document-only-idv)\n", "example": "PASSPORT" }, "firstIssue": { "type": "string", "description": "Date of the document's first issue. Format: YYYY-MM-DD.\n", "example": "2022-01-01", "format": "date" }, "idCardType": { "type": "string", "description": "Document type for the ID card, [a-zA-Z] characters only.\n\nOptional, only required for Colombia identity verification.\n", "enum": [ "CE", "CC", "TI" ], "example": "CC" }, "documentNumberIdentifiers": { "description": "Specific document number identifiers. \n\nOptional, currently used only for the Official Database Verification step \nfor INE database verification solution.\n", "allOf": [ { "$ref": "#/components/schemas/DocumentNumberIdentifiers" } ] }, "validFrom": { "type": "string", "description": "Document issue date or valid-from date. Format: YYYY-MM-DD.\n\nOptional, used in some registry checks, for example [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "example": "2020-01-01", "format": "date" }, "validUntil": { "type": "string", "description": "Document expiry date. Format: YYYY-MM-DD.\n\nOptional, used in some registry checks, for example [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "example": "2030-01-01", "format": "date" }, "version": { "type": "string", "description": "The version or revision number of the document. \n\nOptional, used in some registry checks, for example [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "example": "001" }, "cardType": { "type": "string", "description": "The specific type or category of the document. \n\nOptional, used in some registry checks, for example [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "enum": [ "SSS", "TIN", "GSIS" ], "example": "TIN" }, "cardNumber": { "type": "string", "description": "The document's unique identification number. \n\nOptional, used in some registry checks, for example [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "example": "123456" }, "stateOfIssue": { "type": "string", "description": "The state or region where the document was issued. \n\nOptional, used in some registry checks, for example [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "example": "AL" }, "referenceNumber": { "type": "string", "description": "The reference number of the document. \n\nOptional, used in some registry checks, for example [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "example": "123456" }, "registrationNumber": { "type": "string", "description": "A registration identifier assigned to the document by the issuing authority. \n\nOptional, used in some registry checks, for example [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "example": "BOAB123456" } } }, "CreateSessionAddress": { "type": "object", "properties": { "fullAddress": { "type": "string", "description": "Full address.", "example": "123, Main Street, Your County, Anytown 12345" }, "street": { "type": "string", "description": "Street name.\n\nOptional, used in some registry checks, for example [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "example": "Main Street" }, "houseNumber": { "type": "string", "description": "House number.\n\nOptional, used in some registry checks, for example [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "example": "123" }, "postcode": { "type": "string", "description": "Postal code.\n\nOptional, used in some registry checks, for example [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "example": "12345" }, "city": { "type": "string", "description": "Any human settlement, including cities, towns, villages, hamlets, localities, etc.\n\nOptional, used in some registry checks, for example [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "example": "Anytown" }, "state": { "type": "string", "description": "Any administrative division, such as a state, province, or region.\n\nOptional, used in some registry checks, for example [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "example": "Your County" }, "unit": { "type": "string", "description": "Apartment, suite, or unit number.\n\nOptional, used in some registry checks, for example [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "example": "4B" }, "suburb": { "type": "string", "nullable": "true", "description": "A specific named area or district within a city or a town.\n\nOptional, used in some registry checks, for example [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "example": "Westmere" }, "subDistrict": { "type": "string", "nullable": "true", "description": "An entity at a lower level compared to district, often used to refer to names of places or neighborhoods within a city or town.\n\nOptional, used in some registry checks, for example [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "example": "Juniper Row" }, "buildingName": { "type": "string", "nullable": "true", "description": "A specific name give to a building or property.\n\nOptional, used in some registry checks, for example [Metadata Database Verification](https://devdocs.veriff.com/docs/metadata-database-verification).\n", "example": "The Alden House" } } }, "CreateSessionProofOfAddress": { "type": "object", "properties": { "acceptableTypes": { "description": "Accepted types for proof of address document. \n\nThis parameter should be sent only when using the proof of address solution and after the\n[Acceptable document types](https://devdocs.veriff.com/docs/proof-of-address-verification#define-acceptable-document-types-optional) feature\nhas been configured for your integration.\n", "type": "array", "items": { "$ref": "#/components/schemas/ProofOfAddressAcceptableTypes" } } } }, "CreateSessionServiceCoverage": { "type": "object", "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code indicating which country's verification\nservices should be offered to the end user. Not available by default.\n", "pattern": "^[A-Z]{2}$", "example": "US", "nullable": "true" } } }, "CreateSessionConsent": { "type": "object", "properties": { "type": { "type": "string", "description": "Indicates the feature for which the consent is given.\n\nMandatory field for MX INE Biometric Database Verification and some registries in Metadata Database Verification.\n", "enum": [ "ine", "bipa", "aadhaar", "general", "dvs", "eid" ], "example": "ine" }, "approved": { "type": "boolean", "description": "If true, indicates that the consent has been given.\n\nMX INE Biometric Database Verification requires that `approved=true` is sent. If `false` or missing, \nthe session is not created. \n\nA mandatory field for some registries in Metadata Database Verification.\n", "example": "true" }, "text": { "type": "string", "description": "Consent text exactly (same language) as shown to the end-user.\n\nMandatory when `type=eid` and `approved=true`. Optional in all other cases.\n", "example": "User agrees to share their INE details" }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp recording when the consent was given by the end-user, as combined ISO 8601 date and time in UTC.\nAlways optional.\n\nFormat: YYYY-MM-DDTHH:MM:SS.sssZ.\n", "example": "2026-05-07T08:00:00Z" } } }, "DocumentNumberIdentifiers": { "type": "object", "properties": { "mxIne": { "type": "string", "description": "Field representing the last 9 digits of the first line of the MRZ of \nan INE card. Also known as \"Identificador del ciudadano\".\n", "example": "158912347" }, "mxIfe": { "type": "string", "description": "Field representing the last 13 digits of the first line of the MRZ of \nan IFE card. Also known as \"ocr\".\n", "example": "1234567890123" } } }, "ProofOfAddressAcceptableTypes": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the accepted proof of address document type.", "example": "UTILITY_BILL" } }, "required": [ "name" ] } } } } ````