--- title: "Biometric Liveness | Veriff.com" slug: "biometric-liveness" description: "Explore Veriff's Biometric Liveness solution, a one-off verification to ensure that the end-user is a live person." tags: ["Biometric Liveness", "Identity Verification"] updated: 2025-07-18T11:28:54Z published: 2025-07-18T11:28:54Z --- > ## 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. # Biometric Liveness Veriff Biometric Liveness solution ensures that the biometric data being captured is from a live person, significantly reducing the risk of fraud. This is a one-off verification, the end-user's data is not stored for re-verification purposes. The system analyses the images, verifies the end-user and returns the decision. It is available via API, web flow, and native SDKs. > [!NOTE] > A **separate integration** is needed to do this verification, please contact your **solutions engineer** for info and configuration. --- ## Prerequisites 1. Your Solutions Engineer has set up a**separate**integration for you 2. You have configured the **decision webhook**to get responses from Veriff (see the [Webhooks](/v1/docs/webhooks-guide) section for info) 3. If using the API, you are ready to send Veriff **additional device/session data**collected about the end-user 4. Veriff strongly recommends that you create and send us the endUserId --- ## Flow overview The flow is a bit different, depending on the method you are using to verify your end-users with Veriff. ### Use via SDKs 1. Generate a verification session using the `API keys` and the `baseURL` of your Biometric Liveness integration (check the [POST /sessions](https://veriff-dev-documentation.document360.io/apidocs/v1sessions)[↗] endpoint in the API reference) 2. Capture end-user’s face images with Veriff’s SDKs 1. Send the end-user through the verification flow to capture the face image (using the preferred [Veriff SDK](/v1/docs/sdk-guide)) 2. You need the session URL generated in step 1 to use the SDKs (found in response payload as `verification.url`) 3. Session will be submitted automatically once the end-user takes and submits necessary images of their face 4. Receive the results from Veriff via [decision webhook](/v1/docs/decision-webhook) ### Use via API 1. Generate an authentication session using the `API keys` and the `baseURL` of your Biometric Liveness integration (check the [POST /sessions](https://veriff-dev-documentation.document360.io/apidocs/v1sessions)[↗] endpoint in the API reference) 1. Veriff strongly recommends you create and send the `endUserId` 2. Upload the device/session data via [POST sessions/{sessionid}/collected-data](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsidcollected-data-1)[↗] 3. Use your face-capturing method, or prepare previously collected end-user face images 4. Upload the end-user's face image via the [POST /sessions/{sessionId}/media](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsidmedia-3)[↗] call 1. Specify `context` parameter as `face` 5. Patch session status to `submitted` status using [PATCH /sessions/{sessionId}](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsid-2)[↗] call 6. 1. Wait for Veriff to verify the end-user 2. Check the decision data and/or session related info from the [decision webhook](/v1/docs/decision-webhook) and/or query the data from the [GET sessions/{sessionId}/decision](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsiddecision-1)[↗] endpoint. --- ## Find decision and session results You can get the data from three sources: - Receive the decision webhook - Query the results via GET sessions/{sessionId}/decision - View the session in Veriff Customer Portal ### Webhook payload > [!NOTE] > Below is an **explanation and a sample of** a decision webhook payload for a **Biometric Liveness session**. The decision webhook is used for many purposes, to find more info about it, see the [decision webhook](/v1/docs/decision-webhook) documentation. #### Sample request ```json {  "status": "success",  "verification":{      "id":"12df6045-3846-3e45-946a-14fa6136d78b",      "attemptId":"c6cab5b0-c506-47a6-922d-6ae3b72ca172",      "vendorData":null,      "endUserId":"a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",      "status":"approved",      "code":9001,      "reason":null,      "reasonCode":null,      "decisionTime":"2025-01-05T12:55:01.232923Z",      "acceptanceTime":"2025-01-05T07:18:36.916Z",      "person":{          "firstName":null,          "lastName":null,          "dateOfBirth":null,                    "gender":null,          "nationality":null,          "idNumber":null,          "yearOfBirth":null,          "placeOfBirth":null,          "pepSanctionMatch":null,          "citizenship":null      },      "document":{          "number":null,          "type":null,          "country":null,          "state":null,          "validUntil":null,          "validFrom":null      },      "additionalVerifiedData":{},      "comments":[],      "riskLabels":[]  },  "technicalData": {      "ip": "186.153.67.122"  } } ``` #### Response properties explained - `status`: `string` Status of the response - `verification`: `object` Verification request decision object. `null` if decision is not available yet - `id`: `string` UUID v4 which identifies the verification session - `attemptId`: `string` UUID v4 of the attempt which received a status (as shown in `verification.status` field) - `vendorData`: `string | null` The unique identifier that you created for your end-user. `null` if not specified - `endUserId`: `string | null` The `UUID` that you created for your end-user. `null` if not specified - `status`: `string` Verification status, one of `approved`, `declined`, `resubmission_requested`, `review`, `expired`,` abandoned` - `code`: `integer` Verification session decision code, one of `9001`, `9102`, `9103`, `9104`, `9121`. For more info, see the [verification session decision codes](/v1/docs/verification-session-decision-codes-table) - `reason`: `string | null` Reason why the verification failed - `reasonCode`: `integer | null` Reason code of the failed verification. For more info, see the [possible codes for a failed verification](/v1/docs/verification-session-decision-codes-table) - `decisionTime`: `string | null` Timestamp of the decision, represented as `UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset` (ISO 8601) - `acceptanceTime`: `string` Timestamp of the session generation, represented as `UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset` (ISO 8601) - **`person`: `object` Data about the verified person** - `firstName`: `string | null` Person's first name as written on the document - `lastName`: `string | null` Person's last name as written on the document - `dateOfBirth`: `string` Date of birth, represented as `YYYY-MM-DD` - `gender`: `string | null` Person’s gender, represented as M or F, or `null` if not present - `nationality`: `string | null` Person’s nationality, represented as `ISO 3166 alpha-2` or `alpha-3 number` - `idNumber`: `string | null` National identification number - `yearOfBirth`: `string | null` Person’s year of birth, represented as `YYYY` - `placeOfBirth`: `string | null` Person’s place of birth - `pepSanctionMatch`: `string | null` *Legacy field, may return incorrect result, should be ignored* - `citizenship`: `null` *Deprecated, always returns null* - **`document`: `object` Verified document** - `number`: `string | null` Document number, `[a-zA-Z0-9]` characters only - `type`: `string | null` Document type, one of `PASSPORT`, `ID_CARD`, `RESIDENCE_PERMIT`, `DRIVERS_LICENSE`, `VISA`, `OTHER`. For more info, see the [Supported document types for IDV](/v1/docs/supported-document-types) article - `country`: `string | null` Document issuing country, represented as ISO 3166 `alpha-2` code - `state`: `string | null` Document issuing state, represented as ISO 3166 `alpha-2` or `alpha-3` code - `additionalVerifiedData`: `object` Data that has been optionally verified for the session. Optional, depending on the integration - `comments`: `array` *(Deprecated) Always returns empty []* - `highRisk`: `boolean` *(Deprecated) Marked if session was considered high risk or not* - `technicalData`: `object` Technical data object - `ip`: `string | null` IP of the device from which the verification was made ### API call You can use the [GET sessions/{sessionId}/decision](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsiddecision-1)[↗] endpoint to get the decision data. > [!NOTE] > Below is an **explanation and a sample of** the API call payload for a **Biometric Liveness session**. This endpoint is used for many purposes, to find more info about it, see the the [GET sessions/{sessionId}/decision](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsiddecision-1)[↗] documentation. #### Sample response ```json {  "status": "success",  "verification":{      "id":"12df6045-3846-3e45-946a-14fa6136d78b",      "attemptId":"c6cab5b0-c506-47a6-922d-6ae3b72ca172",      "vendorData":null,      "endUserId":"a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",      "status":"approved",      "code":9001,      "reason":null,      "reasonCode":null,      "decisionTime":"2025-01-05T12:55:01.232923Z",      "acceptanceTime":"2025-01-05T07:18:36.916Z",      "person":{          "firstName":null,          "lastName":null,          "dateOfBirth":null,                    "gender":null,          "nationality":null,          "idNumber":null,          "yearOfBirth":null,          "placeOfBirth":null,          "pepSanctionMatch":null,          "citizenship":null      },      "document":{          "number":null,          "type":null,          "country":null,          "state":null      },      "additionalVerifiedData":{},      "comments":[],      "riskLabels":[]  },  "technicalData": {      "ip": "186.153.67.122"  } } ``` #### Response properties explained - `status`: `string` Status of the response - `verification`: `object` Verification request decision object. `null` if decision is not available yet - `id`: `string` UUID v4 which identifies the verification session - `attemptId`: `string` UUID v4 of the attempt which received a status (as shown in `verification.status` field) - `vendorData`: `string | null` The unique identifier that you created for your end-user. `null` if not specified - `endUserId`: `string | null` The `UUID` that you created for your end-user. `null` if not specified - `status`: `string` Verification status, one of `approved`, `declined`, `resubmission_requested`, `review`, `expired`,` abandoned` - `code`: `integer` Verification session decision code, one of `9001`, `9102`, `9103`, `9104`, `9121`. For more info, see the [verification session decision codes](/v1/docs/verification-session-decision-codes-table) - `reason`: `string | null` Reason why the verification failed - `reasonCode`: `integer | null` Reason code of the failed verification. For more info, see the [possible codes for a failed verification](/v1/docs/verification-session-decision-codes-table) - `decisionTime`: `string` Timestamp of the decision, represented as `UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset` (ISO 8601) - `acceptanceTime`: `string` Timestamp of the session generation, represented as `UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset` (ISO 8601) - **`person`: `object` Data about the verified person** - `firstName`: `string | null` Person's first name as written on the document - `lastName`: `string | null` Person's last name as written on the document - `dateOfBirth`: `string` Date of birth, represented as `YYYY-MM-DD` - `gender`: `string | null` Person’s gender, represented as M or F, or `null` if not present - `nationality`: `string | null` Person’s nationality, represented as `ISO 3166 alpha-2` or `alpha-3 number` - `idNumber`: `string | null` National identification number - `yearOfBirth`: `string | null` Person’s year of birth, represented as `YYYY` - `placeOfBirth`: `string | null` Person’s place of birth - `pepSanctionMatch`: `string | null` *Legacy field, may return incorrect result, should be ignored* - `citizenship`: `null` *Deprecated, always returns null* - **`document`: `object` Verified document** - `number`: `string | null` Document number, `[a-zA-Z0-9]` characters only - `type`: `string | null` Document type, one of `PASSPORT`, `ID_CARD`, `RESIDENCE_PERMIT`, `DRIVERS_LICENSE`, `VISA`, `OTHER`. For more info, see the [Supported document types for IDV](/v1/docs/supported-document-types) article - `country`: `string | null` Document issuing country, represented as ISO 3166 `alpha-2` code - `state`: `string | null` Document issuing state, represented as ISO 3166 `alpha-2` or `alpha-3` code - `additionalVerifiedData`: `object` Data that has been optionally verified for the session. Optional, depending on the integration - `comments`: `array` *(Deprecated) Always returns empty []* - `highRisk`: `boolean` *(Deprecated) Marked if session was considered high risk or not* - `technicalData`: `object` Technical data object - `ip`: `string | null` IP of the device from which the verification was made ### View in Veriff Customer Portal You can find the verification session related info in the Veriff Customer Portal, under the **Webhooks** tab. → *See*[*Review verification in Veriff Customer Portal*](/v1/docs/how-to-review-verification-in-veriff-customer-portal)*about how to view the session info in the Veriff Customer portal* --- ## Status and reason codes For an `approved` session, see the `verification.code` and `verification.status` parameters. If the session was `declined` or `resubmission_requested`, you can find additional information by checking the `verification.status`, `verification.code`, `verification.reason` and `verification.reasonCode` data objects. Table below lists some reason codes specific to Biometric Liveness sessions. *→ If you are seeing codes not listed in the table below, see the*[*Granular Reason Codes*](/v1/docs/granular-reason-codes)*article* | Code | Description | | --- | --- | | 105 | Declined - Suspicious behaviour | | 106 | Declined - Known fraud | | 201 | Resubmission requested - Video and/or photos missing | | 204 | Resubmission requested - Poor image quality | | 503 | Declined - Attempted deceit | | 515 | Declined - Attempted deceit, device screen used for face image | | 546 | Declined - Face image quality insufficient | | 547 | Declined - Face missing | | 603 | Resubmission requested - Video missing | | 605 | Resubmission requested - Face image missing | | 606 | Resubmission requested - Face is not clearly visible | --- ## FAQ #### Where can I query the media the end-user submitted during verification process? It is possible to query the media the end-user submitted during the verification process via: - [GET /media/{mediaId}](https://devdocs.veriff.com/apidocs/v1mediaid-1) - allows querying the **media file** using the `mediaId` of a specific media file - [GET /sessions/{sessionId}/media](https://devdocs.veriff.com/apidocs/v1sessionsidmedia-2) - allows querying **info about the media** uploaded during the session (using the `sessionId`) - [GET /attempts/{attemptId}/media](https://devdocs.veriff.com/apidocs/v1attemptsidmedia-1) - allows querying **info about the media** uploaded during a certain attempt (using the `attemptId`) Data retention policies may apply. --- ## Changelog | Date | Description | | --- | --- | | Jul 18, 2025 | `decisionTime` field description in webhook parts updated, to indicate that it can also be `null` | | Jun 6, 2025 | Heading “Article versioning” changed to “Changelog” | | Mar 28, 2025 | Broken links fixed | | Mar 12, 2025 | Documentation published | An environment created according to customer's needs to carry out, manage and observe verifications. You can find the list of your integrations in **Veriff Customer Portal**> **All** **Integrations**page (you need to be logged in). A UUID-format unique identifier ([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}) created by you for your end-user to link an end-user to their session(s). Cannot be resolved outside your environment. Veriff stores it only for identity verification and returns it unchanged in webhooks/API responses or as `null` if not provided. Strongly recommended if you already use UUID identifiers. Works as an alternative to `vendorData` in Biometric Authentication solution. A session during which the end-user is verified. It starts when a session is created, it can contain several attempts (i.e. steps of uploading media, sending additional data etc.) and it ends when a conclusive decision (“approved”, “declined”, “expired”/”abandoned”) is granted. Each verification session receives an unique ID, aka the **session ID**, which can be added to the API URL when making API requests. This where the end-user is directed to go through the verification flow, and it is **unique for each verification session**. It is a combination of the `base URL` and the `sessionToken`, created as soon as a verification session is created. You can find its value in the response payload of your POST /sessions call, as `verification.url`. The data that you send when you make an API request, or that you receive when you get a response. Veriff customer back-office, a dashboard where you can see your end-users' verification data. Depending on your setup, you may be required to access the environment via station.veriff.com or hub.veriff.com. Always **check your sign-up email** and make sure that you **log in via correct address**. ## Related - [Getting Started](/getting-started.md) - [Integrations](/how-to-create-an-integration.md) - [Create verification session](/how-to-generate-sessions-manually.md) - [Webhooks Guide](/webhooks-guide.md) - [Codes](/codes.md)