List attempt media metadata

Updated on Mar 9, 2026
Published on Mar 8, 2026

Prev Next

Get

/v1/attempts/{id}/media

Returns a list of metadata objects of an attempt-specific media file

When to use this endpoint

Use this endpoint to retrieve metadata about media files captured during a specific attempt inside the verification process.
Common use cases include:
- Accessing attempt-specific media when a session has multiple attempts
- Getting attempt-specific media file's metadata (IDs, URLs, file types)
- Identifying which images and videos are available before downloading them
- Building media lists for internal review systems

Response data

The response includes two arrays containing metadata objects for all media associated with the attempt:
- images array: Contains metadata objects for image files (document photos, selfies, etc.)
- videos array: Contains metadata objects for video files
Each metadata object includes:
- Unique media ID
- Context identifier (what the media shows, e.g., document-front, face)
- File metadata (size in bytes, mimetype)
- Associated session ID
- For videos: duration in seconds
Sorting: The objects in both arrays are sorted by the automation system based on accuracy (does the image match the required type) and quality. Higher quality and more accurate media appears first.
Finding attempt IDs: To find a specific attemptId, call GET /v1/sessions//attempts to get the list of all attempts for a session.
If the attempt has no media, the corresponding array will be empty.

Implementation notes

This endpoint requires session-level HMAC signature authentication
The timestamp field is deprecated and always returns null
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-hmac-signature

stringRequired

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

Example7bb142b882e92642c97d9b23285a35ccd457eb5dab0bedab720b1046795e3f57

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

Path parameters

string (uuid) Required

Verification attempt ID.

Examplea1c68aea-7f4d-478d-80ab-ca9356074f69

Responses

200

Successfully retrieved attempt-specific media's metadata objects

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.

Example9c4fa8c72cdf233df0c7e8e0a1c12e15d4aa5b58f19f35b6e5d64f2e3a1b0c9d

standard_attempt_with_images

Standard attempt with document and face image metadata

Typical response containing metadata for document images and a selfie

{
  "status": "success",
  "images": [
    {
      "id": "d69a07cf-4434-4d36-be6c-d22af7dc01fb",
      "name": "document-front",
      "context": "document-front",
      "timestamp": null,
      "size": 245678,
      "mimetype": "image/jpeg",
      "url": "https://exampleURL.com/v1/media/d69a07cf-4434-4d36-be6c-d22af7dc01fb",
      "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5"
    },
    {
      "id": "e7ab18d1-5545-5e47-af7b-e23gb6247f80",
      "name": "document-back",
      "context": "document-back",
      "timestamp": null,
      "size": 238956,
      "mimetype": "image/jpeg",
      "url": "https://exampleURL.com/v1/media/e7ab18d1-5545-5e47-af7b-e23gb6247f80",
      "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5"
    },
    {
      "id": "a2cd45e3-6656-6f58-bg8c-f34hc7358g91",
      "name": "face",
      "context": "face",
      "timestamp": null,
      "size": 198432,
      "mimetype": "image/jpeg",
      "url": "https://exampleURL.com/v1/media/a2cd45e3-6656-6f58-bg8c-f34hc7358g91",
      "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5"
    }
  ],
  "videos": []
}

attempt_with_video

Response containing metadata of a verification video

{
  "status": "success",
  "videos": [
    {
      "id": "b3de56f4-7767-7g69-ch9d-g45id8469h02",
      "name": "selfid_video",
      "context": "selfid_video",
      "timestamp": null,
      "size": 1456789,
      "mimetype": "video/mp4",
      "url": "https://exampleURL.com/v1/media/b3de56f4-7767-7g69-ch9d-g45id8469h02",
      "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",
      "duration": 8
    }
  ]
}

Expand All

object

status

string

API request status.

Examplesuccess

images

Array of object (VerificationSessionImageUpload)

Array of metadata objects for image files associated with the attempt. Sorted by accuracy and quality.

object

string (uuid)

UUID v4 which identifies the uploaded media.

Exampled69a07cf-4434-4d36-be6c-d22af7dc01fb

name

string

Name which identifies the uploaded media.

Valid values[ "address-front", "document-and-face", "document-and-face-pre", "document-back", "document-back-barcode", "document-back-barcode-pre", "document-back-pre", "document-back-qrcode", "document-back-qrcode-pre", "document-front", "document-front-face-cropped", "document-front-pre", "document-front-qrcode", "document-front-qrcode-pre", "face", "face-cropped", "face-nfc", "face-pre", "face-reference", "registry-face" ]

Exampledocument-front

context

string

Context type of the uploaded media.

See Context types article for more info.

Exampledocument-front

timestamp

string Deprecated

Always returns None/null.

Example

size

number

Size of the uploaded media, in bytes.

Example12345.0

mimetype

string

File type of the uploaded media.

See Media file mimetypes article for more info.

Valid values[ "image/jpeg", "image/jpg", "image/png", "image/heif", "image/heic", "image/webp", "application/pdf" ]

Exampleimage/jpeg

url

string

Download URL of the media.

Examplehttps://exmpleURL.com/v1/media/d69a07cf-4434-4d36-be6c-d22af7dc01fb

sessionId

string

UUID v4 of the verification session the uploaded media belongs to.

Exampled69a07cf-4434-4d36-be6c-d22af7dc01fb

videos

Array of object (VerificationSessionVideoUpload)

Array of metadata objects for video files associated with the attempt. Sorted by accuracy and quality.

object

Metadata object describing a video file uploaded during verification.

string (uuid)

UUID v4 which identifies the uploaded media.

Use with GET /v1/media/ to download the actual file.

Exampled69a07cf-4434-4d36-be6c-d22af7dc01fb

name

string

Name which identifies the uploaded media.

Valid values[ "document-and-face", "document-and-face-pre", "document-back", "document-back-pre", "document-front", "document-front-pre", "document-front-with-signature", "document-front-with-signature-pre", "face", "face-pre", "face-nfc", "face-reference", "face-cropped", "address-front", "document-front-face-cropped", "registry-face", "generic-document-back", "generic-document-front" ]

Exampleselfid_video

context

string

Context type of the uploaded media.

See Context types article for more info.

Exampleselfid_video

timestamp

string Deprecated

Always returns null.

Example

size

number

Size of the uploaded media, in bytes.

Example12345.0

mimetype

string

File type of the uploaded media.

Examplevideo/mp4

url

string

Download URL for the actual media file.

Examplehttps://exampleURL.com/v1/media/d69a07cf-4434-4d36-be6c-d22af7dc01fb

sessionId

string

UUID v4 of the verification session the uploaded media belongs to.

Exampled69a07cf-4434-4d36-be6c-d22af7dc01fb

duration

number (integer)

Duration of the uploaded media, in seconds.

Example12345.0

400

Bad request

Headers

Content-Type

string

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.

Example9c4fa8c72cdf233df0c7e8e0a1c12e15d4aa5b58f19f35b6e5d64f2e3a1b0c9d

object

status

string

Valid values[ "fail" ]

Examplefail

code

string

Example1101

message

string

ExampleValidation failed

401

Unauthorized - Invalid or missing authentication

Headers

Content-Type

string

Exampleapplication/json

x-auth-client

string

API key echoed back in response.

Exampleyour-api-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

Attempt not found

Headers

Content-Type

string

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.

Example9c4fa8c72cdf233df0c7e8e0a1c12e15d4aa5b58f19f35b6e5d64f2e3a1b0c9d

object

status

string

Valid values[ "fail" ]

Examplefail

code

string

Example1101

message

string

ExampleResource not found

500

Internal server error

Headers

Content-Type

string

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.

Example9c4fa8c72cdf233df0c7e8e0a1c12e15d4aa5b58f19f35b6e5d64f2e3a1b0c9d

object

status

string

Valid values[ "fail" ]

Examplefail

code

string

Example1101

message

string

ExampleSomething went wrong

Document Versioning

Changelog

Date	Description
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

Was this article helpful?