List session media metadata

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

Prev Next

Get

/v1/sessions/{id}/media

Returns a list of metadata of a media file associated with a specific verification session

When to use this endpoint

Use this endpoint to retrieve metadata (e.g., file type, size, download URL, context) about a media file uploaded during a verification session
This endpoint returns information about the media file, not the file itself
Common use cases include:
- Checking what media files were uploaded during verification
- Obtaining download URLs for media files
- Identifying media file types and contexts before downloading
- Reviewing media file metadata for quality assessment
- Determining which media files to download for record-keeping

Response data

Returns a list of media objects associated with the specific sessionId. The list contains two arrays:
- images: Array of image metadata objects (document photos, selfies, proof of address)
- videos: Array of video metadata objects (video verification recordings)
Each media object includes:
- Unique identifier (id) and download URL (url)
- File metadata: size (bytes), mimetype, context
- Session relationship (sessionId)
- For videos: duration in seconds
The media objects are sorted based on their accuracy (e.g., does an image match the required image type) and quality. The order is determined by the automation system.
The context field indicates what the media file contains (e.g., document-front, face, address-front). The -pre suffix indicates preliminary/first capture, while no suffix indicates final capture. See the Context types (image, video) documentation for additional info about the values of images.context.

Implementation notes

This endpoint returns metadata about media files, not the media files themselves
Use the id field from the responses (images.id or videos.id) to download actual media files via GET /v1/media/
The request returns media metadata from the most recent attempt only. To get a specific attempt's media metadata:
1. Call GET /v1/sessions//attempts to get the list of attemptId values
2. Use GET /v1/attempts//media to get the metadata of the media in that specific attempt
Empty arrays (images: [] or videos: []) indicate no media of that type was uploaded
The deprecated timestamp field always returns null and should not be used
In test integrations, it is expected behaviour that no video is returned
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.

Examplea1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

Path parameters

string (uuid) Required

Verification session ID.

Exampled69a07cf-4434-4d36-be6c-d22af7dc01fb

Responses

200

Session media metadata retrieved successfully

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

Examplea1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

standard_verification

Standard identity verification with document

{
  "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"
    }
  ],
  "videos": []
}

proof_of_address

Proof of address verification with utility bill

{
  "status": "success",
  "images": [
    {
      "id": "a1b2c3d4-e5f6-4a5b-8c9d-e0f1a2b3c4d5",
      "name": "address-front",
      "context": "address-front",
      "timestamp": null,
      "size": 312456,
      "mimetype": "image/jpeg",
      "url": "https://exampleURL.com/v1/media/a1b2c3d4-e5f6-4a5b-8c9d-e0f1a2b3c4d5",
      "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5"
    }
  ],
  "videos": []
}

video_verification

Video verification with selfie video

{
  "status": "success",
  "videos": [
    {
      "id": "f5g6h7i8-j9k0-4l1m-9n2o-p3q4r5s6t7u8",
      "name": "selfid_video",
      "context": "selfid_video",
      "timestamp": null,
      "size": 4567890,
      "mimetype": "video/mp4",
      "url": "https://exampleURL.com/v1/media/f5g6h7i8-j9k0-4l1m-9n2o-p3q4r5s6t7u8",
      "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",
      "duration": 8
    }
  ]
}

Expand All

object

status

string

API request status

Examplesuccess

images

Array of object (VerificationSessionImageUpload)

Array of image metadata objects. Contains information about the image uploaded to the session, from the most recent attempt.

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 video metadata objects. Contains information about the video uploaded to the session, from the most recent attempt.

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

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.

Examplea1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

{
  "status": "fail",
  "code": "1101",
  "message": "Validation failed"
}

object

status

string

Valid values[ "fail" ]

Examplefail

code

string

Example1101

message

string

ExampleValidation failed

401

Unauthorized

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.

Examplea1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

{
  "status": "fail",
  "code": "1101",
  "message": "Mandatory X-AUTH-CLIENT header containing the API key is missing from the request."
}

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.

Examplea1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

{
  "status": "fail",
  "code": "1101",
  "message": "Resource not found"
}

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.

Examplea1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

{
  "status": "fail",
  "code": "1101",
  "message": "Something went wrong"
}

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
May 2, 2025	`face-cropped` image context type added
Mar 12, 2025	Documentation published

Was this article helpful?