---
title: "List attempts IDs"
slug: "v1sessionsidattempts-1"
updated: 2026-04-24T06:36:37Z
published: 2026-04-24T06:36:37Z
---
> ## 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.
# List attempts IDs
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](https://help.veriff.com/en/articles/8480053-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](https://devdocs.veriff.com/docs/hmac-authentication-and-endpoint-security#public-api-v1) authentication
- 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.
- 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.
Header parametersX-AUTH-CLIENTstringRequired
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-SIGNATUREstringRequired
Session ID signed with the shared secret key. Required to authenticate the request sender.
Path parametersidstring (uuid) Required
Verification session ID.
Examplef04bdb47-d3be-4b28-b028-a652feb060b5
Responses200
Successfully retrieved session attempts
HeadersContent-TypestringResponse content type.Exampleapplication/json
X-AUTH-CLIENTstringAPI key echoed back in response.Exampleyour-api-key
X-HMAC-SIGNATUREstringResponse body signed with the shared secret key. Required to authenticate the response sender.
single_attempt_with_custom_status
Single attempt with custom status data
```json
{
"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
```json
{
"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
```json
{
"status": "success",
"verifications": [
{
"id": "b3d79efa-6c2a-4b8e-92cd-da8467185c7a",
"status": "submitted",
"userDefinedData": [],
"createdTime": "2023-09-18T10:15:42.789Z"
}
]
}
```
Expand Allobject statusstring
API request status.
Examplesuccess
verifications Array of object (SessionAttemptsResponseVerification)
List of data identifying the attempts in the verification session
object idstring
Unique identifier (ID) of the attempt.
Example123e4567-e89b-12d3-a456-426614174000
statusstring
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 statusstring
Name of the custom end-user defined status as set in the Veriff Customer Portal.
ExampleApproved
statusCodestring
Autogenerated code for the custom end-user defined status.
Exampleapproved
reasonstring | 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
reasonCodestring | 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
createdAtstring (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
createdTimestring (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
HeadersContent-TypestringResponse content type.Exampleapplication/json
X-AUTH-CLIENTstringAPI key echoed back in response.Exampleyour-api-public-key
X-HMAC-SIGNATUREstringResponse body signed with the shared secret key.
object statusstring Valid values[
"fail"
]Examplefail
codestring Example1101
messagestring ExampleValidation failed
401
Unauthorized - Invalid or missing authentication credentials
HeadersContent-TypestringResponse content type.Exampleapplication/json
X-AUTH-CLIENTstringAPI key echoed back in response.Exampleyour-api-public-key
object statusstring Valid values[
"fail"
]Examplefail
codestring Example1101
messagestring ExampleMandatory X-AUTH-CLIENT header containing the API key is missing from the request.
404
Session not found
HeadersContent-TypestringResponse content type.Exampleapplication/json
X-AUTH-CLIENTstringAPI key echoed back in response.Exampleyour-api-key
X-HMAC-SIGNATUREstringResponse body signed with the shared secret key.
object statusstring Valid values[
"fail"
]Examplefail
codestring Example1101
messagestring ExampleResource not found
500
Internal server error
HeadersContent-TypestringResponse content type.Exampleapplication/json
X-AUTH-CLIENTstringAPI key echoed back in response.Exampleyour-api-key
X-HMAC-SIGNATUREstringResponse body signed with the shared secret key.
object statusstring Valid values[
"fail"
]Examplefail
codestring Example1101
messagestring 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 |