Import images in bulk for asynchronous processing
Import one or more face images in bulk. Processing happens asynchronously — the API returns immediately with a 202 status, and images are processed in the background.
Cap on image uploads per request
Maximum 10 images per request
Each request can include a maximum of 10 face images. This is a hard limit enforced by the API. If you attempt to submit more than 10 images in a single request, the request will fail with a validation error.
When you need to import more than 10 images:
Make multiple requests, each with up to 10 images
Each image submitted counts toward your quota
- This quota is fixed according to your service plan
- Info about remaining quota is available in the API response in
availableQuotaparameter - Contact your Solutions Engineer or Veriff Customer Support if you need to increase your quota
All images can be of the same person or different persons
Example:
- To import 25 images: Make 3 requests (10 + 10 + 5 images)
When to use this endpoint
- Use this endpoint to import face images in bulk for fraud detection and identity verification
- Process multiple images per person in a single request (up to 10 per call)
- Leverage asynchronous processing for high-throughput scenarios
Image name uniqueness
Each image name can only be submitted once every 5 minutes. If you submit an image with the same name multiple times within 5 minutes, only the first submission will be processed.
Recommended naming strategies:
- Include timestamps:
profile_2026-02-17_14-30-00.jpg - Use UUIDs:
profile_a7f8d3e1-4c2b-9f8e-b1d2-c3e4f5a6b7c8.jpg - Use your internal IDs:
profile_user_12345_session_67890.jpg - Combine multiple identifiers:
profile_john_doe_20260217_143000.jpg
For retries
If you need to re-submit an image:
- Option 1: Wait at least 5 minutes before using the same image name again
- Option 2: Use a different image name (recommended for immediate retry)
Implementation notes
- This endpoint requires session-level HMAC signature authentication
- Processing is asynchronous — results are not returned in the response
- 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.
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 under Settings > API keys.
Request body signed with the shared secret key. Required to authenticate the request sender.
Signature Formula:
sourceString = "/v1/faces/import" + "\n" + JSON.stringify(requestBody)
signature = HmacSHA256.sign(sourceString, sharedSecret)
The request body must be serialized consistently (sorted keys, no extra spaces).
Must be set to application/json
Face import request containing face images
Import single face image
{
"images": [
{
"name": "profile_2026-02-17_14-30-00.jpg",
"content": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAA+.../9fgAEAKcxisFjVfn0AAAAASUVORK5CYII="
}
]
}Import 3 face images
{
"images": [
{
"name": "profile_2026-02-17_14-30-00.jpg",
"content": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAA+.../9fgAEAKcxisFjVfn0AAAAASUVORK5CYII="
},
{
"name": "id_card_front_2026-02-17_14-30-00.jpg",
"content": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAA+.../9fgAEAKcxisFjVfn0AAAAASUVORK5CYII="
},
{
"name": "id_card_back_2026-02-17_14-30-00.jpg",
"content": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAA+.../9fgAEAKcxisFjVfn0AAAAASUVORK5CYII="
}
]
}Request model for importing images in bulk.
⚠️ Hard Limit: Maximum 10 images per request Each request can include 1 to 10 face images. Requests with more than 10 images will be rejected with a validation error.
Array of image objects containing face data.
Important: Exactly 1 to 10 images maximum per request. Each image beyond 10 will cause validation to fail.
Model for image data with name and base64 content.
Unique name/identifier for this image within the request.
Allowed characters: letters, digits, ., _, -. Max 120 characters. Must not be empty and must not contain ...
Names that break these rules don't 422 the whole batch — they land in the response's failedImages with reason "Invalid image name." while the rest of the batch proceeds.
Cannot be submitted again from the same account within 5 minutes — use timestamps or UUIDs to ensure uniqueness across requests.
Base64-encoded image data. Supported formats: JPEG, PNG, GIF, BMP, WEBP.
Max decoded size: 2 MB per image. Can include a data URI prefix (e.g., data:image/jpeg;base64,) or be raw base64.
Invalid / unsupported / oversized content doesn't 422 the whole batch — it lands in the response's failedImages with reason "Invalid image content." while the rest of the batch proceeds.
Accepted — Images will be processed asynchronously.
The request has been accepted for processing. Images are now queued for asynchronous processing.
Successful import of 3 images
{
"message": "3 images queued for asynchronous face import.",
"availableQuota": 997,
"failedImages": []
}Partial success — 2 of 3 images accepted
{
"message": "2 of 3 images queued for face import. 1 could not be accepted — see `failedImages` for details and resubmit those.",
"availableQuota": 998,
"failedImages": [
{
"name": "profile_2026-02-17_14-30-02.jpg",
"reason": "The image could not be processed. Please retry."
}
]
}Response model for image import operation.
Confirmation message indicating images are queued for processing.
On full success: " images queued for asynchronous face import."
On partial success: " of images queued for face import. could not be accepted — see failedImages for details and resubmit those."
Remaining quota after this operation. Only successful images debit quota, so resubmitting a failure does not double-charge.
Images that could not be accepted. Empty array on full success.
Inspect this list to identify which specific images to resubmit. When retrying within 5 minutes, use a different name — the 5-minute uniqueness rule applies to retries as well.
Quota exhaustion is NOT reported here — it returns a 402 response before any image is attempted.
An image the API could not accept.
The image name as submitted in the request.
Why the image was not accepted and what to do next:
- "Invalid image name." — the
namecontained characters outside the allowed set (only letters, digits,.,_,-), was empty, contained.., or exceeded 120 characters. Rename and resubmit. - "Invalid image content." —
contentwas not valid base64, did not decode to a supported image format (JPEG, PNG, GIF, BMP, WEBP), was larger than 2 MB, or was too small to be a real image. Fix the image and resubmit. - "The image could not be processed. Please retry." — transient server-side issue. Retry after a short delay; contact support if it persists.
Bad Request — the request could not be processed.
Truncated / malformed JSON body
{
"status": "fail",
"code": "1101",
"message": "Invalid JSON in request body."
}Unauthorized — Authentication failed.
Missing X-AUTH-CLIENT header
{
"status": "fail",
"code": "1801",
"message": "Mandatory X-AUTH-CLIENT header containing the API key is missing from the request."
}API key not recognised
{
"status": "fail",
"code": "1803",
"message": "Integration with the API key \"00000000-0000-0000-0000-000000000000\" was not found."
}HMAC signature mismatch or otherwise unverifiable
{
"status": "fail",
"code": "1815",
"message": "Could not authenticate request."
}Provided signature does not match the HMAC-SHA256 of body + secret
{
"status": "fail",
"code": "1819",
"message": "Signature \"\" does not match the HMAC-SHA256 of request body and integration API secret."
} Payment Required — Insufficient quota available.
Your account has reached its faceblock import quota limit.
Insufficient quota
{
"detail": {
"error": "insufficient_quota",
"message": "Insufficient quota. Available: 1, Required: 3",
"available_quota": 1,
"required": 3
}
}402 response body returned when a faceblock import request exceeds the integration's remaining quota.
Quota remaining at the moment the request was evaluated.
Number of images the request was attempting to import.
Validation Error — The body is valid JSON but fails schema validation
(wrong types, empty images, more than 10 items, missing required
fields, or content exceeding the raw-size cap).
Use 400 handling for unparseable / truncated JSON bodies; 422
only fires once the JSON has been parsed successfully and schema
validation runs. Per-image validation failures (invalid name
characters, bad base64, unsupported image format, decoded payload
over 2 MB) are NOT reported here — those return 202 and land in
the response's failedImages list alongside the successes.
Empty images array (minimum 1 required)
{
"detail": [
{
"type": "too_short",
"loc": [
"body",
"images"
],
"msg": "List should have at least 1 item after validation, not 0",
"input": []
}
]
}Too many images (maximum 10)
{
"detail": [
{
"type": "too_long",
"loc": [
"body",
"images"
],
"msg": "List should have at most 10 items after validation, not 11",
"input": []
}
]
}Missing required field (name or content)
{
"detail": [
{
"type": "missing",
"loc": [
"body",
"images",
0,
"content"
],
"msg": "Field required",
"input": {
"name": "only-name.jpg"
}
}
]
}Content string too large (OOM protection)
{
"detail": [
{
"type": "string_too_long",
"loc": [
"body",
"images",
0,
"content"
],
"msg": "String should have at most 2796268 characters",
"input": "<>"
}
]
} Wrong type (for example images sent as a string)
{
"detail": [
{
"type": "list_type",
"loc": [
"body",
"images"
],
"msg": "Input should be a valid list",
"input": "not-an-array"
}
]
}Validation error response model with detailed error locations and messages.
Array of validation error details with field locations and error messages
Internal server error. Something went wrong on our side while processing the request; retry after a short delay and contact support if it persists.
Internal server error
{
"status": "fail",
"code": "1101",
"message": "Something went wrong"
}