Skip to navigation
Identity verification APIFace Match

Upload a photo for a face comparison

Stores one photo and returns a mediaId to pass to the comparison. Uploading is optional, because the comparison also accepts photos inline. Use it to reuse one photo across several checks or to send bytes too large for base64. An upload that no comparison claims expires after 30 minutes.

Error codes

errorStatusMeaning
upload_failed400The multipart body could not be read, or the file is larger than 25 MB.
file_required400No file field was attached.
unsupported_media_type400The file is not image/jpeg, image/png or image/webp.
secret_key_required403A publishable key was used. This endpoint accepts secret keys only.
environment_mismatch403The key belongs to an environment this deployment does not serve.
ip_not_allowed403The key has an IP allowlist and the calling address is not on it.
organization_suspended403The organisation is suspended. The response carries reason and suspendedAt.
business_not_approved403A live key was used before the business was approved for production.

A missing or unknown key answers 401, where error is a short sentence rather than a code.

Requires a secret (sk_) key. A publishable key receives 403 secret_key_required.

Authentication

AuthorizationBearer
Send the API key as a Bearer token. Each operation states whether a publishable key is enough or a secret key is required.

Request

This endpoint expects a multipart form containing a file.
filefileRequired

The photo, as image/jpeg, image/png or image/webp, up to 25 MB.

Response

The photo was stored.
mediaIdstring

The id to pass as mediaAId or mediaBId on a comparison.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error