Post

/v1/sessions/{id}/media

Uploads an image (and specifies the type of the image that is being uploaded) for a specific sessionId = {id}

Only one image file can be uploaded with one request
Veriff supports .jpg, .jpeg, .png, .heif, .heic, .webp and .pdf file formats in uploads
The image file is defined as base64 encoded image string inside a JSON body object
To avoid issues with upload, keep the image 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

Make sure that you upload all the images before setting the status to "submitted" using the PATCH /sessions/{sessionId} endpoint. If you try to upload media after you have submitted the session, you may encounter the 409 - conflict error.

Note: always ensure that you use the correct API URL to send requests. See the API URL section for more info.

Note about different context types

Veriff expects you to define the context of the uploaded media, which should indicate what has been captured on the uploaded image. See the Context types section[↗] for more information about different context types.

Note about PDF support

Veriff supports PDF file uploads for Identity and Document Verification (IDV) documents and Proof of Address (PoA) documents.

Please 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 in 20MB.

Security

API Key: api_key

Header parameter namex-auth-client

Your integration's API key (occasionally referred to the "Token", "API public key" or "Publishable key")

Header parameters

x-hmac-signature

stringRequired

Request body signed with the shared secret key

Path parameters

id

Required

Session id

Body parameters

Expand All

object

image

object (MediaUploadImage) Required

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.

Valid values[ "document-front", "document-back", "document-and-face", "face" ]

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 (Combined ISO 8601 date and time in UTC, YYYY-MM-DDTHH:MM:SS+Timezone Offset)

Timestamp of the upload

Example2020-01-01T00:00:00.000Z

Responses

200

Headers

x-auth-client

string

Your integration's API key. Required to identify the request or response sender. Occasionally referred to as the "API token".

x-hmac-signature

string

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

vrf-auth-client

string

Your integration's API key. Required to identify the request or response sender. Same as x-auth-client.

vrf-hmac-signature

string

Response body signed with the shared secret key. Required to authenticate the response sender. Same as x-hmac-signature.

Expand All

object

status

string

Upload status

Examplesuccess

image

object (VerificationSessionImageUpload)

id

string (uuid)

UUID v4 which identifies the uploaded media

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" ]

Exampledocument-front

context

string

Context type of 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" ]

Exampledocument-front

timestamp

string Deprecated

*Always returns None/null

Examplenull

size

number

Size of the uploaded media, in bytes

Example12345.0

mimetype

string

File type of the uploaded media, one of .jpg, .jpeg, .png, .heif, .heic, .webp or .pdf

Exampleimage/jpeg

url

string

Download URL of the media

Examplehttps://api.veriff.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

object

status

string

Valid values[ "fail" ]

Examplefail

code

string

Example1101

message

string

ExampleValidation failed

401

Unauthorized

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

object

status

string

Valid values[ "fail" ]

Examplefail

code

string

Example1101

message

string

ExampleResource not found

500

Internal server error

object

status

string

Valid values[ "fail" ]

Examplefail

code

string

Example1101

message

string

ExampleSomething went wrong

Document Versioning

Article Versioning

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