Download media or data file

Returns the media (image or video) or data (NFC) file associated with the specified media ID

When to use this endpoint

• Use this endpoint to download specific media or data files captured during verification.

• For the purposes of this endpoint, NFC data files are also considered "media" and can be downloaded using this endpoint by providing the appropriate media ID.

• The media ID must be obtained first from either GET /v1/sessions/{id}/media or GET /v1/attempts/{id}/media endpoints.

• Common use cases include:

  • Downloading document images for archival or compliance purposes
  • Retrieving selfie images for visual verification
  • Accessing video files for review or audit trails
  • Integrating verification media into internal case management systems

Getting media IDs

• To get the media ID of a specific file:

  1. Request a list of media from GET /v1/attempts/{attemptId}/media or GET /v1/sessions/{sessionId}/media
  2. Find the specific media file's ID in the images[].id, videos[].id or nfcDocuments[].id parameter
  3. Use that ID to download the file with this endpoint

Response data

• The endpoint returns a binary file with the appropriate Content-Type header:

  • image/jpeg - JPEG image files
  • image/jpg - JPG image files
  • image/png - PNG image files
  • video/webm - WebM video files
  • application/json - NFC data files (JSON format)

• Image size notes:

  • All images with one edge larger than 1920px are proportionally reduced so the longer edge is maximum 1920px
  • No size limits apply when downloading
  • No resolution limits apply when downloading, except that images larger than 1920px were reduced during capture

Implementation notes

• This endpoint requires session-level HMAC signature authentication
• The media file is returned as binary data in the response body
• NFC data is returned as a JSON file with application/json Content-Type
• Set appropriate Content-Type handling in your HTTP client to receive the data
• Determine the correct file extension by checking the mimetype field from GET /v1/sessions/{id}/media or GET /v1/attempts/{id}/media response (found in images[].mimetype or videos[].mimetype) before downloading
• Media files are available for download as long as the session exists in the system
• 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

How to store response data to file?

• Below are examples of how to download media files and save them to disk using Python.
• In case of video and image files, make sure to use the correct file extension based on the mimetype value from the media list response.

Downloading image files:

import requests

media_url = 'https://example-base-url/v1/media/2b3b3a9f-d73d-445a-aabe-9b41c1c1a2ac'

headers = {
    'X-AUTH-CLIENT': 'your-api-key',
    'X-HMAC-SIGNATURE': '452bfca0e02f8ee0f56d97373cc6971067e43149f1b7e58b681d4e57353a2f6b',
    'Content-Type': 'application/json',
}

response = requests.get(media_url, headers=headers)
with open('image_file_name.jpg', 'wb') as write_file:
    write_file.write(response.content)

Downloading video files:

import requests

media_url = 'https://example-base-url/v1/media/05cfc122-15d8-4838-bbf1-7b26a736b2d2'

headers = {
    'X-AUTH-CLIENT': 'your-api-key',
    'X-HMAC-SIGNATURE': '452bfca0e02f8ee0f56d97373cc6971067e43149f1b7e58b681d4e57353a2f6b',
    'Content-Type': 'application/json',
}

response = requests.get(media_url, headers=headers)

with open('media_filename.webm', 'wb') as media_file:
    for chunk in response.iter_content():
        media_file.write(chunk)

Downloading NFC data:

import requests

media_url = 'https://example-base-url/v1/media/4088480d-d1b2-47e9-aeb8-27c6b73488e2'

headers = {
    'X-AUTH-CLIENT': 'your-api-key',
    'X-HMAC-SIGNATURE': '452bfca0e02f8ee0f56d97373cc6971067e43149f1b7e58b681d4e57353a2f6b',
    'Content-Type': 'application/json',
}

response = requests.get(media_url, headers=headers)
with open('nfc_document.json', 'wb') as write_file:
    write_file.write(response.content)