Upload media

Updated

Published on Mar 8, 2026

Prev Next

Post

/v1/sessions/{id}/media

Uploads an image file (and specifies the filetype of the upload) for a specific session ID

When to use this endpoint

Use this endpoint to programmatically upload images to a verification session when using the API-based integration (not SDK)
If using the Veriff SDK, media upload is handled automatically within the SDK flow and this endpoint is not needed.

Common scenarios include:

Uploading document photos captured via your own interface
Submitting selfie images for face verification
Providing proof of address document images
Uploading generic documents for verification

Request body content

The image file is defined as base64 encoded image string inside a JSON body object
To avoid issues with upload, keep the file smaller than:
- Image files: 24MB in base64 encoding (approx 17MB in image files format)
- PDFs: 20 MB in pdf format
- Make sure the longer side of the uploaded image is max 1920px

The request must include an image object containing:

context: what type of image is being uploaded (e.g., document-front, document-back, selfie). See Context types article for more info.
content: base64-encoded image data with data URI scheme
timestamp: when the image was captured (optional)

Supported image formats:

.jpg
.jpeg
.png
.heif
.heic
.webp
.pdf

Response data

Successful uploads return metadata about the uploaded media including:
- Unique media ID for reference
- Media type and context
- File size and mimetype (format of the media file, see here for more info)
- Download URL for accessing the uploaded image
- sessionId the media belongs to
The timestamp field in the response is deprecated and always returns null.

Implementation notes

Only one image file can be uploaded with one request
Make sure that you upload all the images before setting the status to "submitted" using the PATCH /sessions/ endpoint. If you try to upload media after you have submitted the session, you may encounter the 409 - conflict error.
The same context can be uploaded multiple times (e.g., for retries)
This endpoint requires session-level HMAC signature authentication
Base64 content should include the data URI scheme prefix (e.g., data:image/jpeg;base64,)
Maximum file size limits may apply depending on integration configuration
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.

Additional info

Improved fraud detection

Veriff strongly recommends you upload several images per context (e.g. face, document-front, document-back), to indicate liveness and improve fraud detection
Each image must be uploaded using a separate request

PDF support is not enabled by default

Veriff supports PDF file uploads for Identity and Document Verification (IDV) documents and Proof of Address (PoA) documents
Contact your Solutions Engineer before starting to upload PDF files

Identity and Document Verification feature

In IDV, document images can be uploaded in following configurations:
- Two PDF files, where one file contains document front image and the other file contains document back image
- Single PDF file, which has both document sides on different pages
- Single PDF file, which has both document sides on single page
- Veriff processes first 5 pages of uploaded PDF file. System removes empty pages from the PDF.

Proof of Address Verification

The file that is uploaded for Proof of Address flow must contain only one PoA document
Max document size is 20MB

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

Request body signed with the shared secret key. Required to authenticate the request sender.

Examplea1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

Content-Type

stringRequired

Content type of the request body

Valid values[ "application/json" ]

Exampleapplication/json

Path parameters

string (uuid) Required

Verification session ID.

Examplef04bdb47-d3be-4b28-b028-a652feb060b5

Body parameters

document_front

Standard document front side upload with base64-encoded JPEG image

{
  "image": {
    "context": "document-front",
    "content": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAX/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwA/AAAA",
    "timestamp": "2025-01-01T10:00:00Z"
  }
}

document_back

Document back side upload with base64-encoded PNG format

{
  "image": {
    "context": "document-back",
    "content": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
    "timestamp": "2025-01-01T10:00:15Z"
  }
}

selfie_face

Face verification selfie upload, base64-encoded JPEG file

{
  "image": {
    "context": "face",
    "content": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAX/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwA/AAAA",
    "timestamp": "2025-01-01T10:01:00Z"
  }
}

proof_of_address

Proof of address document upload (utility bill, bank statement, etc.), base64-encoded JPEG file

{
  "image": {
    "context": "address-front",
    "content": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAX/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwA/AAAA",
    "timestamp": "2025-01-01T10:05:00Z"
  }
}

without_timestamp

Media upload without optional timestamp field

{
  "image": {
    "context": "document-front",
    "content": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAX/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwA/AAAA"
  }
}

Expand All

object

image

object (MediaUploadImage)

context

string Required

Context of the uploaded media, i.e., what the uploaded image was taken of.

Veriff captures multiple images, therefore the image with the -pre suffix is the first one, and the one without is the second image.

See Context types article for more info.

Exampledocument-front

content

string (base64) Required

The media file to be uploaded, as base64 encoded image (.jpg, .jpeg, .png, .heif, .heic, .webp and .pdf formats are supported).

Exampledata:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+.../9fgAEAKcxisFjVfn0AAAAASUVORK5CYII=

timestamp

string (YYYY-MM-DDTHH:MM:SS+Z)

Timestamp of the upload as combined ISO 8601 date and time in UTC, YYYY-MM-DDTHH:MM:SS+Timezone Offset.

Example2020-01-01T00:00:00.000Z

Responses

200

Media uploaded successfully.

Headers

Content-Type

string

Response content type.

Valid values[ "application/json" ]

x-auth-client

string

API key echoed back in response.

x-hmac-signature

string

Response body signed with the shared secret key. Required to authenticate the response sender.

document_front_success

Document front uploaded successfully

{
  "status": "success",
  "image": {
    "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"
  }
}

face_upload_success

Selfie uploaded successfully

{
  "status": "success",
  "image": {
    "id": "a1b2c3d4-e5f6-4g7h-8i9j-0k1l2m3n4o5p",
    "name": "face",
    "context": "face",
    "timestamp": null,
    "size": 189234,
    "mimetype": "image/jpeg",
    "url": "https://exampleURL.com/v1/media/a1b2c3d4-e5f6-4g7h-8i9j-0k1l2m3n4o5p",
    "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5"
  }
}

proof_of_address_success

Proof of Address document uploaded successfully

{
  "status": "success",
  "image": {
    "id": "6q7r8s9t-0u1v-4w3x-4y5z-6a1b2c3d4e5f",
    "name": "address-front",
    "context": "address-front",
    "timestamp": null,
    "size": 512890,
    "mimetype": "image/jpeg",
    "url": "https://exampleURL.com/v1/media/6q7r8s9t-0u1v-4w3x-4y5z-6a1b2c3d4e5f",
    "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5"
  }
}

Expand All

object

status

string

Upload status.

Examplesuccess

image

object (VerificationSessionImageUpload)

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

400

Bad request

Headers

Content-Type

string

Response content type.

Valid values[ "application/json" ]

x-auth-client

string

API key echoed back in response.

x-hmac-signature

string

Response body signed with the shared secret key. Required to authenticate the response sender.

bad_request

Request failed

{
  "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.

Valid values[ "application/json" ]

x-auth-client

string

API key echoed back in response.

missing_api_key

Missing API key

Request failed because x-auth-client header is missing

{
  "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.

Valid values[ "application/json" ]

x-auth-client

string

API key echoed back in response.

x-hmac-signature

string

Response body signed with the shared secret key. Required to authenticate the response sender.

session_not_found

Request failed because session does not exist

{
  "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.

Valid values[ "application/json" ]

x-auth-client

string

API key echoed back in response.

x-hmac-signature

string

Response body signed with the shared secret key. Required to authenticate the response sender.

server_error

Internal server error

Request failed due to an internal server error

{
  "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
Nov 26, 2025	Added the "Note about improved fraud detection" section
Oct 2, 2025	`vrf-` headers removed from response headers
Aug 6, 2025	Response headers added
May 2, 2025	Updated the info about PDF files support for Proof of Address Verification flow to match the logic of Proof of Address Verification solution Note about multiple PDF uploads for PoA solution moved to the legacy Proof of Address Extraction documentation as it is only applicable for that flow.
Apr 21, 2025	Added a note about the max length of the longer side of an image
Mar 12, 2025	Documentation published

Was this article helpful?