Skip to main content
POST
curl

Overview

Use this endpoint when you import Users from another provider and already have a trusted face image for each person. The User remains keyed by your vendor_data, but this profile attachment endpoint uses didit_internal_id so the target User is unambiguous.
This is different from Upload face to list. Profile upload attaches a face to a User for evidence, duplicate detection, and face search. List upload adds a face to a face-type blocklist so future matching sessions can be rejected.

Endpoint

POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/

Migration flow

1

Create or find the User

Call POST /v3/users/create/ for a new profile, or GET /v3/users/{vendor_data}/ for an existing one.
2

Store didit_internal_id

The User response includes didit_internal_id. Keep using vendor_data in your database; use didit_internal_id only for profile attachment endpoints.
3

Upload the face

Send a raw base64 image in the image field. The backend validates image decoding, image size, and face detection before saving it.

Example

Request body

Response

Validation and limits

  • Max 5 manually uploaded faces per User.
  • Max decoded image size is 2 MB.
  • The image must be valid base64 and decode as an image.
  • The image must contain a detectable face. Use a frontal, well-lit face crop when possible.
  • The uploaded face is indexed for future duplicate detection and face search.
  • The uploaded face is not automatically blocklisted.

List or delete uploaded faces

List profile faces:
Delete one profile face:

Permissions

Use an API key for the same application. The key must belong to an app allowed to manage the target User profile.

Failure modes

  • 400 — invalid base64, invalid image, no detectable face, a detected face that cannot be cropped from the image (code: face_crop_empty), image over 2 MB, or the User already has 5 uploaded faces.
  • 401 — missing or invalid credentials.
  • 403 — API key is valid but not allowed to manage this User profile.
  • 404 — no User exists for that didit_internal_id in the application.
  • 429 — rate-limited; back off using Retry-After.

Authorizations

x-api-key
string
header
required

Your application's API key, from Developers -> API keys in the Business Console. The primary key has full access. A named key can be scoped: none, read or write per resource, limited to some workflows or to approved sessions, to a list of IP addresses, and to an expiry date. 401 means the key is wrong, revoked or expired; 403 means no key was sent, the key has no access to this resource or action, or the request came from an address outside its IP list; 404 on a session route means the session is outside the key's workflows or statuses. A key without media access receives image, video and PDF URLs as null, and a key without sessions write receives session links and tokens as null. See https://docs.didit.me/console/api-keys.

Headers

Idempotency-Key
string

Optional retry-safety key you choose for one operation, up to 255 characters (a UUID works). A request repeated with the same key, endpoint, query and body is answered with the first response, same status and same body, and runs and bills nothing a second time. The same key with another endpoint, query or body returns 409 idempotency_key_reused, and while the first request is still running, 409 idempotency_key_in_progress with Retry-After. A failed request (any 4xx or 5xx) is not stored, so you can send it again with the same key. Keys belong to your application, whether you call with an API key or an access token. See Retries and idempotency.

Required string length: 1 - 255

Path Parameters

organization_id
string<uuid>
required

Organization UUID that owns the application.

application_id
string<uuid>
required

Application UUID that owns the User profile.

didit_internal_id
string<uuid>
required

Didit's internal User UUID, returned as didit_internal_id by GET /v3/users/{vendor_data}/ and POST /v3/users/create/.

Body

application/json
image
string<byte>
required

Raw base64-encoded JPG or PNG face image. Do not include a data:image/...;base64, prefix. Max decoded size: 2 MB.

comment
string
default:""

Optional operator-visible note for the uploaded face.

Response

Face uploaded and attached to the User profile.

uuid
string<uuid>
required

UUID of the uploaded User face record.

image_url
string<uri> | null
required

Signed URL for the uploaded face image.

comment
string | null
required

Comment supplied when the face was uploaded.

uploaded_by
string | null
required

Email or actor identifier of the uploader when available.

created_at
string<date-time>
required

Upload timestamp.

Last modified on November 11, 2026