List session media and NFC data metadata

Updated on Apr 24, 2026
Published on Mar 8, 2026

Prev Next

Get

/v1/sessions/{id}/media

Returns a list of metadata of a media file or a NFC data 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 or a NFC data file uploaded during a verification session
This endpoint returns information about the media/data file, not the file itself
Common use cases include:
- Checking what media/data files were uploaded during verification
- Obtaining download URLs for media/data files
- Identifying media/data file types and contexts before downloading
- Reviewing media/data file metadata for quality assessment
- Determining which media/data files to download for record-keeping

Response data

Returns a list of media/data objects associated with the specific sessionId. The list can contain the following arrays:
- images: Array of image metadata objects (document photos, selfies, proof of address)
- videos: Array of video metadata objects (video verification recordings)
- nfcDocuments: Array of NFC document metadata objects
Each object includes:
- Unique identifier (id) and download URL (url)
- File metadata: size (bytes), mimetype, context
- Session relationship (sessionId)
- For videos: duration in seconds
The image and video 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.
Sorting does not apply to NFC data files as there is usually one upload per attempt.
For media files, 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.
For NFC data files, the context field is always document-nfc, added by Veriff's system.

Implementation notes

This endpoint returns metadata about media/data files, not the media/data files themselves
Use the id field from the responses (images.id, videos.id or nfcDocuments.id) to download actual media files via GET /v1/media/
The request returns media/data file's metadata from the most recent attempt only. To get a specific attempt's media/data file's 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/data file in that specific attempt
Empty arrays (images: [] or videos: [] or nfcDocuments: []) indicate no media/data 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/data 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
    }
  ]
}

nfcDocuments_verification

Verification with NFC data

{
  "status": "success",
  "nfcDocuments": [
    {
      "id": "908d041f-e66e-47de-9664-0950a201fd85",
      "name": "document-nfc",
      "context": "document-nfc",
      "timestamp": null,
      "size": 29584,
      "mimetype": "application/octet-stream",
      "url": "https://exampleURL.com/v1/media/908d041f-e66e-47de-9664-0950a201fd85",
      "sessionId": "86c71df5-c163-4022-9c94-1fb6dc903a98"
    }
  ]
}

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 | null Deprecated

Always returns null.

Example

size

integer

Size of the uploaded media, in bytes.

Example12345

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-front-pre-video", "document-back-pre-video", "document-and-face-pre-video", "documet-back-barcode-pre-video", "face-pre-video", "selfid_video" ]

Exampleselfid_video

context

string

Context type of the uploaded media.

See Context types article for more info.

Valid values[ "document-front-pre-video", "document-back-pre-video", "document-and-face-pre-video", "documet-back-barcode-pre-video", "face-pre-video", "selfid_video" ]

Exampleselfid_video

timestamp

string | null Deprecated

Always returns null.

Example

size

integer

Size of the uploaded media, in bytes.

Example12345

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

integer

Duration of the uploaded media, in seconds.

Example12345

nfcDocuments

Array of object (NfcDocumentsMediaObject) | null

Array of NFC document metadata objects. Present only when NFC data was uploaded during the verification session. Each object contains metadata about the raw NFC data file, not the NFC data itself.

object

string (uuid)

Unique identifier of the NFC data file.

Example908d041f-e66e-47de-9664-0950a201fd85

name

string

Name of the NFC data file.

Exampledocument-nfc

context

string

Context type of the NFC data file. Always document-nfc for NFC captures.

Exampledocument-nfc

timestamp

string | null Deprecated

Always returns null.

Example

size

integer

Size of the NFC data file, in bytes.

Example29584

mimetype

string

File type of the NFC data file. NFC data is returned as application/octet-stream.

Exampleapplication/octet-stream

sessionId

string (uuid)

UUID of the verification session this NFC data file belongs to.

Example86c71df5-c163-4022-9c94-1fb6dc903a98

url

string

Download URL of the NFC data file.

Examplehttps://exampleURL.com/v1/media/908d041f-e66e-47de-9664-0950a201fd85

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
Apr 24, 2026	Media metadata schema type alignment: `size` as integer and `duration` as integer
Apr 17, 2026	Typo fixed
Apr 10, 2026	Video `context` types updated
Mar 20, 2026	NFC data upload info and examples added
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?