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, 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

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.