Presence Verification

Presence Verification helps confirm that a real, live, single human is present in the verification session and is completing it on their own. It uses a passive selfie video and device signals captured by Veriff's native SDKs to help keep bots, deepfakes, injected media, and sessions guided by a third party out of your sign-up and high-risk flows, without asking the end-user for an identity document.

Presence Verification is available in two tiers:

• Presence Verification: assesses presence, uniqueness, and liveness from the selfie image and the full selfie video, together with device and network integrity signals.

• Presence Verification with Coercion Detection: includes everything above, and also analyses the session audio and video to flag signs that a third party is guiding the end-user during the session.

Presence Verification is available via native SDKs (iOS and Android) and web flow. Because the checks rely on the media and device signals that Veriff's SDK captures, Veriff strongly recommends using the solution via native SDKs.

You need a separate integration for this solution, meaning existing solution's integrations cannot be used. Presence Verification is used as a standalone solution on that integration.

All session-related info is returned via the decision webhook and can be polled from different API endpoints. The results of the verification can also be viewed in the Veriff Customer Portal, on the session's page.

Prerequisites

• You have an integration set up with Veriff

• Presence Verification is configured for that integration by your Solutions Engineer, including which tier you use

• You have configured the decision webhook to get responses from Veriff (see the how-to in webhooks' Set up webhooks section)

• You have integrated a Veriff native SDK (iOS or Android), and your app can request camera access from the end-user, and microphone access if you use Presence Verification with Coercion Detection

• Your backend is ready to create sessions with POST /sessions using the API keys of your Presence Verification integration

• Veriff strongly recommends that you create and send us the endUserId or vendorData

• To use Presence Verification with Coercion Detection, the end-user must be 18 years or older. Presence Verification without Coercion Detection has no age requirement.

→ For more info about how to integrate using Android or iOS SDKs, see the SDK Guides section.

Key terminology

Flow overview

Captured media

During the session, Veriff's SDK accesses the selfie image, the selfie video, device metadata, and sensor data. No identity document is captured.

Use via SDKs

1. Generate a verification session using the API keys and the baseURL of your Presence Verification integration (see the API Documentation and API Reference how to find these)

   • Veriff strongly recommends you create and send the endUserId or vendorData

     
     Session creation bash example

   curl -X POST \
     --url '/v1/sessions/' \
     -H 'X-AUTH-CLIENT: your-api-key' \
     -H 'Content-Type: application/json' \
     -d '{
       "verification": {
         "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
         "vendorData": "12345678"
       }
     }'
   

   Session creation json example

   {
     "verification": {
       "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
       "vendorData": "12345678"
     }
   }
   

2. Capture the end-user's selfie video with Veriff's native SDK

   • Launch the Veriff iOS or Android SDK in your app. You need the session URL generated in step 1 (found in response payload as verification.url).

   • The end-user grants camera access, and microphone access if you use Presence Verification with Coercion Detection

   • The end-user records a short, passive selfie video

3. Session will be submitted automatically once the end-user completes the capture

4. Receive the results from Veriff via the decision webhook or poll them via GET /sessions/{sessionId}/decision endpoint

   • If the decision is resubmission_requested, the end-user sees a retry prompt in the session, records the video again, and Veriff sends a new decision

Session lifecycle flow diagram

sequenceDiagram
    participant EU as End-user
    participant App as Your app
    participant BE as Your backend
    participant API as Veriff API
    participant SDK as Veriff SDK

    BE->>API: POST /v1/sessions (endUserId, vendorData)
    API-->>BE: Session URL (verification.url)
    BE->>App: Session URL
    App->>SDK: Launch SDK with session URL
    SDK->>EU: Request camera and microphone access
    EU->>SDK: Record passive selfie video
    SDK->>API: Submit session automatically
    Note over API: Automated processing
    API-->>BE: Decision webhook
    opt Decision is resubmission_requested
        SDK->>EU: Retry prompt in the session
        EU->>SDK: Record passive selfie video again
        SDK->>API: Submit session automatically
        API-->>BE: Decision webhook
    end
    opt Webhook not received
        BE->>API: GET /v1/sessions/sessionId/decision
        API-->>BE: Decision
    end

sequenceDiagram
    participant EU as End-user
    participant App as Your app
    participant BE as Your backend
    participant API as Veriff API
    participant SDK as Veriff SDK

    BE->>API: POST /v1/sessions (endUserId, vendorData)
    API-->>BE: Session URL (verification.url)
    BE->>App: Session URL
    App->>SDK: Launch SDK with session URL
    SDK->>EU: Request camera and microphone access
    EU->>SDK: Record passive selfie video
    SDK->>API: Submit session automatically
    Note over API: Automated processing
    API-->>BE: Decision webhook
    opt Decision is resubmission_requested
        SDK->>EU: Retry prompt in the session
        EU->>SDK: Record passive selfie video again
        SDK->>API: Submit session automatically
        API-->>BE: Decision webhook
    end
    opt Webhook not received
        BE->>API: GET /v1/sessions/sessionId/decision
        API-->>BE: Decision
    end

Find decision and/or session related info

You can get the data from three sources:

• Receive the decision webhook (full example with placeholder values below)

• Query the results via GET /sessions/{sessionId}/decision (payload is identical to the webhook)

• View the session in the Veriff Customer Portal

Solution-specific parameters

Presence Verification does not add a solution-specific object to the payload. The result is returned in the standard decision fields: verification.status and verification.code show the outcome, and for sessions that are not approved, verification.reason and verification.reasonCode show why.

Which reason codes you can receive depends on your configuration, for example whether you use Presence Verification with Coercion Detection and whether bot and velocity protection is enabled. See Status and reason codes below.

Note about object and field visibility

All objects and fields listed in the payload examples below are mandatory and always present.

• verification.person and verification.document are always returned, but every field in them is null, because Presence Verification does not use an identity document

• verification.additionalVerifiedData is returned as an empty object {}

• verification.reason and verification.reasonCode are null when the session is approved

• verification.vendorData and verification.endUserId are null if you did not send them

• technicalData.ip can be null

Note on session outcomes

An approved session is identified by a verification.status of approved. It means the selfie and video appear genuine, a live end-user was present, and no signs of manipulation, non-uniqueness, or, on Presence Verification with Coercion Detection, third-party guidance were detected.

A session can also end as:

• declined: the inputs appear not genuine, the end-user does not appear to be present, a second person or third-party guidance was detected, or other fraudulent behaviour was detected

• resubmission_requested: expected input is missing or of poor quality, for example the face is missing or not clearly visible, or the video is missing. The third-party guidance check never leads to resubmission_requested.

• expired or abandoned: standard meanings, as for any other session

Note on the decision fields

For an approved session:

• verification.status is approved,

• verification.code is 9001, and

• verification.reason and verification.reasonCode are null.

For a declined Presence Verification with Coercion Detection session, for example:

• verification.status is declined,

• verification.code is 9102,

• verification.reason is "Signs of third-party guidance during the session", and

• verification.reasonCode is 589.

Webhook payload

Sample request

Approved session

{
  "status": "success",
  "verification": {
    "id": "12df6045-3846-3e45-946a-14fa6136d78b",
    "attemptId": "00bca969-b53a-4fad-b065-874d41a7b2b8",
    "vendorData": "12345678",
    "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
    "status": "approved",
    "code": 9001,
    "reason": null,
    "reasonCode": null,
    "decisionTime": "2026-10-05T12:55:01.232Z",
    "acceptanceTime": "2026-10-05T12:53:36.916Z",
    "submissionTime": "2026-10-05T12:54:15.736755Z",
    "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,
      "validFrom": null,
      "validUntil": null
    },
    "additionalVerifiedData": {},
    "comments": []
  },
  "technicalData": {
    "ip": "192.0.2.10"
  }
}

Declined session

{
  "status": "success",
  "verification": {
    "id": "33bb5a12-7c84-4e2a-9f3d-2b1c6a9d4e57",
    "attemptId": "5fa21d88-6e32-4f71-9ac4-8d3b7c5e2f10",
    "vendorData": "87654321",
    "endUserId": null,
    "status": "declined",
    "code": 9102,
    "reason": "Signs of third-party guidance during the session",
    "reasonCode": 589,
    "decisionTime": "2026-10-05T09:12:44.512Z",
    "acceptanceTime": "2026-10-05T09:10:03.118Z",
    "submissionTime": "2026-10-05T09:11:57.402551Z",
    "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,
      "validFrom": null,
      "validUntil": null
    },
    "additionalVerifiedData": {},
    "comments": []
  },
  "technicalData": {
    "ip": "192.0.2.11"
  }
}

Request 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, expired, abandoned

  • code: integer Verification session decision code, one of 9001, 9102, 9103, 9104. For more info, see the 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 Granular reason 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)

  • submissionTime: string Timestamp of when the session was submitted, represented as UTC YYYY-MM-DDTHH:MM:SS.SSSSSS+Timezone Offset (ISO 8601)

  • person: object Data about the verified person. For Presence Verification, every field in this object is null.

    • 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 | null Person's date of birth, represented as YYYY-MM-DD

    • gender: string | null Person's gender, represented as M, F or X, 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. For Presence Verification, every field in this object is null.

    • 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

    • 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

    • validFrom: string | null Document is valid from date

    • validUntil: string | null Document is valid until date

  • additionalVerifiedData: object Data that has been optionally verified for the session. Empty {} for Presence Verification.

  • comments: array (Deprecated) Always returns empty []

• technicalData: object Technical data object

  • ip: string | null IP of the device from which the verification was made

API call

{
  "status": "success",
  "verification": {
    "id": "12df6045-3846-3e45-946a-14fa6136d78b",
    "attemptId": "00bca969-b53a-4fad-b065-874d41a7b2b8",
    "vendorData": "12345678",
    "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
    "status": "approved",
    "code": 9001,
    "reason": null,
    "reasonCode": null,
    "decisionTime": "2026-10-05T12:55:01.232Z",
    "acceptanceTime": "2026-10-05T12:53:36.916Z",
    "submissionTime": "2026-10-05T12:54:15.736755Z",
    "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,
      "validFrom": null,
      "validUntil": null
    },
    "additionalVerifiedData": {},
    "comments": []
  },
  "technicalData": {
    "ip": "192.0.2.10"
  }
}

{
  "status": "success",
  "verification": {
    "id": "33bb5a12-7c84-4e2a-9f3d-2b1c6a9d4e57",
    "attemptId": "5fa21d88-6e32-4f71-9ac4-8d3b7c5e2f10",
    "vendorData": "87654321",
    "endUserId": null,
    "status": "declined",
    "code": 9102,
    "reason": "Signs of third-party guidance during the session",
    "reasonCode": 589,
    "decisionTime": "2026-10-05T09:12:44.512Z",
    "acceptanceTime": "2026-10-05T09:10:03.118Z",
    "submissionTime": "2026-10-05T09:11:57.402551Z",
    "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,
      "validFrom": null,
      "validUntil": null
    },
    "additionalVerifiedData": {},
    "comments": []
  },
  "technicalData": {
    "ip": "192.0.2.11"
  }
}

Veriff Customer Portal

You can find the verification session related info, including the decision, in the Veriff Customer Portal, under the session's Webhooks tab.

Status and reason codes

For an approved session, see:

• verification.code about verification session decision code, one of 9001, 9102, 9103, 9104

• verification.status about verification status, one of approved, declined, resubmission_requested, expired, abandoned

If the Presence Verification session was declined or resubmission_requested, you can find additional information by checking:

• verification.reason for the reason why the verification failed

• verification.reasonCode for reason code of the failed verification and cross-reference it with Granular reason codes (table)

Depending on your configuration, you may also see other existing codes, for example 108 (duplicated end-user), 110 (duplicated ID), or 539 (resubmission limit exceeded).

The table above aims to list the most common reasons why you may see the decline reason for a Presence Verification session. However, the session may be declined due to a reason that is not inherently Presence Verification related. In that case, to find info about the codes you are seeing, refer to:

• Verification session status codes (table)

• Verification session decision codes (table)

• Granular reason codes (table)

Additional information

Best practices

Use a native SDK: Veriff strongly recommends the iOS and Android SDKs over the web flow, because the checks rely on the media and device signals the SDK captures. The API alone cannot run this solution; it only creates the session.

Camera and microphone access: Make sure the end-user can grant camera access, and microphone access if you use Presence Verification with Coercion Detection, and explain in your app why they are needed. Without audio, the third-party guidance assessment cannot run. Adding Coercion Detection to an existing integration introduces a new runtime permission prompt and may require updating your app's privacy disclosures to cover audio capture.

Selfie image quality: ensure that end-user's selfie image is of good quality. This will reduce the possibility of session going to resubmission_requested.

Send an endUserId or vendorData: Create and send an endUserId or vendorData for every session.

Decision logic: Drive your logic from verification.code and verification.status. Treat verification.reasonCode as an open set that can gain new values, and handle unknown codes gracefully.

Third-party guidance declines: Treat 589 like other fraud-related declines in your risk handling.

Webhook first, polling as backup: Use the decision webhook as the primary channel, and GET /sessions/{sessionId}/decision as a fallback.

Error handling: Implement proper error handling for all possible validation results.

Webhook security: Secure your webhook endpoint and verify request signatures

User experience: Provide clear feedback to end-users about validation results

Ensure Backwards compatible changes for webhooks and API connections

FAQ

Changelog