List attempts IDs

Updated
  • Updated on Apr 24, 2026
  • Published on Mar 8, 2026
Prev Next
Get
/v1/sessions/{id}/attempts

Returns list of verification attempts for a session, including attempt IDs, statuses, user-defined data, and creation timestamps

What is an attempt?

  • In the API requests' context, an "attempt" is one step (uploading required data and getting a decision) inside a verification session, and it can be made several times during one verification session

When to use this endpoint

  • Use this endpoint to retrieve all verification attempts associated with a session

Common use cases include:

  • Tracking multiple verification attempts by an end-user
  • Monitoring custom statuses applied to attempts
  • Investigating verification flows with multiple submissions
  • Analyzing attempt patterns and timing

Response data

The response includes an array of attempt objects, each containing:

  • Unique attempt ID
  • Current attempt status (created, started, submitted, resubmission_requested)
  • User-defined custom statuses with reasons and timestamps (if enabled for your integration)
  • Attempt creation time

User-defined statuses in Veriff Customer Portal

  • Can be used to query the user-defined statuses data if those have been set in the Veriff Customer Portal
  • For more information see the Adding user-defined Statuses to Sessions article in Veriff Knowledge Base (you need an active account with Veriff to access the article)

Implementation notes

  • Multiple attempts can exist for a single session, indicating different actions and "steps" done inside one session
  • User-defined data requires custom status configuration in Veriff Customer Portal
  • Attempts are returned in reverse chronological order (newest first)
  • This endpoint requires session-level HMAC signature authentication
  • Always ensure that you use the correct API URL to send requests. See the API URL section for more info.
  • 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 requirements.
Header parameters
X-AUTH-CLIENT
stringRequired

Your integration's API key (occasionally referred to as the "Token", "API public key" or "Publishable key"). Required for all API requests.

You can find your API key in the Veriff Customer Portal > Settings > API keys.

Exampleyour-api-key
X-HMAC-SIGNATURE
stringRequired

Session ID signed with the shared secret key. Required to authenticate the request sender.

Path parameters
id
string (uuid) Required

Verification session ID.

Examplef04bdb47-d3be-4b28-b028-a652feb060b5
Responses
200

Successfully retrieved session attempts

Headers
Content-Type
string
Response content type.
Exampleapplication/json
X-AUTH-CLIENT
string
API key echoed back in response.
Exampleyour-api-key
X-HMAC-SIGNATURE
string
Response body signed with the shared secret key. Required to authenticate the response sender.
single_attempt_with_custom_status

Single attempt with custom status data

{
  "status": "success",
  "verifications": [
    {
      "id": "a1c68aea-7f4d-478d-80ab-ca9356074f69",
      "status": "approved",
      "userDefinedData": [
        {
          "status": "Custom status for suspicious attempt",
          "statusCode": "custom_status_for_suspicious_attempt",
          "reason": "Looks like velocity abuse",
          "reasonCode": "looks_like_velocity_abuse",
          "createdAt": "2023-09-18T08:41:41.606Z"
        }
      ],
      "createdTime": "2023-09-18T08:33:30.047Z"
    }
  ]
}
multiple_attempts_mixed_statuses

Session with multiple attempts showing mixed statuses and custom status data

{
  "status": "success",
  "verifications": [
    {
      "id": "a1c68aea-7f4d-478d-80ab-ca9356074f69",
      "status": "approved",
      "userDefinedData": [
        {
          "status": "Custom status for suspicious attempt",
          "statusCode": "custom_status_for_suspicious_attempt",
          "reason": "The document used in this attempt is clearly a cut-out",
          "reasonCode": null,
          "createdAt": "2023-09-18T08:41:41.606Z"
        }
      ],
      "createdTime": "2023-09-18T08:33:30.047Z"
    },
    {
      "id": "f2270684-8c51-4d03-88eb-dafd43e8b486",
      "status": "resubmission_requested",
      "userDefinedData": [],
      "createdTime": "2023-09-17T14:22:15.123Z"
    }
  ]
}
attempt_no_custom_status

Attempt without custom user-defined data

{
  "status": "success",
  "verifications": [
    {
      "id": "b3d79efa-6c2a-4b8e-92cd-da8467185c7a",
      "status": "submitted",
      "userDefinedData": [],
      "createdTime": "2023-09-18T10:15:42.789Z"
    }
  ]
}
Expand All
object
status
string

API request status.

Examplesuccess
verifications
Array of object (SessionAttemptsResponseVerification)

List of data identifying the attempts in the verification session

object
id
string

Unique identifier (ID) of the attempt.

Example123e4567-e89b-12d3-a456-426614174000
status
string

Verification session status.

Valid values[ "created", "started", "submitted", "resubmission_requested" ]
Examplecreated
userDefinedData
Array of object (UserStatus)

Array of objects describing the custom statuses defined by the user in Veriff Customer Portal.

object
status
string

Name of the custom end-user defined status as set in the Veriff Customer Portal.

ExampleApproved
statusCode
string

Autogenerated code for the custom end-user defined status.

Exampleapproved
reason
string | null

Name of the custom end-user defined reason as set in the Veriff Customer Portal. If the user has selected the "Custom" reason for the status and typed an explanation to the text box, then the explanation is sent in this field.

ExampleApproved by user
reasonCode
string | null

Autogenerated code for the custom end-user defined reason. It is null when the user has selected the "Custom" reason for the status and typed an explanation to the text box. This explanation is sent in the reason parameter.

Exampleapproved_by_user
createdAt
string (date-time)

Creation time of the user-defined status for the verification attempt.

As combined ISO 8601 date and time in UTC. Format: YYYY-MM-DDTHH:MM:SS.sssZ.

Example2020-01-01T14:35:22.456Z
createdTime
string (date-time)

Timestamp of when the attempt was created.

As combined ISO 8601 date and time in UTC. Format: YYYY-MM-DDTHH:MM:SS.sssZ.

Example2025-01-01T09:23:47.123Z
400

Bad request

Headers
Content-Type
string
Response content type.
Exampleapplication/json
X-AUTH-CLIENT
string
API key echoed back in response.
Exampleyour-api-public-key
X-HMAC-SIGNATURE
string
Response body signed with the shared secret key.
object
status
string
Valid values[ "fail" ]
Examplefail
code
string
Example1101
message
string
ExampleValidation failed
401

Unauthorized - Invalid or missing authentication credentials

Headers
Content-Type
string
Response content type.
Exampleapplication/json
X-AUTH-CLIENT
string
API key echoed back in response.
Exampleyour-api-public-key
object
status
string
Valid values[ "fail" ]
Examplefail
code
string
Example1101
message
string
ExampleMandatory X-AUTH-CLIENT header containing the API key is missing from the request.
404

Session not found

Headers
Content-Type
string
Response content type.
Exampleapplication/json
X-AUTH-CLIENT
string
API key echoed back in response.
Exampleyour-api-key
X-HMAC-SIGNATURE
string
Response body signed with the shared secret key.
object
status
string
Valid values[ "fail" ]
Examplefail
code
string
Example1101
message
string
ExampleResource not found
500

Internal server error

Headers
Content-Type
string
Response content type.
Exampleapplication/json
X-AUTH-CLIENT
string
API key echoed back in response.
Exampleyour-api-key
X-HMAC-SIGNATURE
string
Response body signed with the shared secret key.
object
status
string
Valid values[ "fail" ]
Examplefail
code
string
Example1101
message
string
ExampleSomething went wrong



Document Versioning

Changelog

Date

Description

Apr 24, 2026

createdTime and createdAt description and examples standardized to UTC Z-only format and updated

Mar 9, 2026

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

Oct 2, 2025

vrf- headers removed from response headers

Aug 6, 2025

Response headers added

Mar 12, 2025

Documentation published