Skip to main content
POST
/
v3
/
organization
/
{organization_id}
/
application
/
{application_id}
/
vendor-users
/
by-id
/
{didit_internal_id}
/
faces
/
upload
curl
curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/vendor-users/by-id/f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418/faces/upload/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"image": "/9j/4AAQSkZJRgABAQEA...", "comment": "Imported from previous KYC provider"}'
{
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "image_url": "https://signed-url.example/face.jpg",
  "comment": "Imported from previous KYC provider",
  "uploaded_by": "api",
  "created_at": "2026-05-18T12:00:00Z"
}

​
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

# 1. Create the User keyed by your external id
curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "previous_provider": "legacy-kyc-vendor" }
  }'

# 2. Upload an imported face to the returned didit_internal_id
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpg-or-png>",
    "comment": "Imported from previous KYC provider"
  }'

​
Request body

FieldTypeRequiredDescription
imagestringYesRaw base64-encoded JPG or PNG. Do not include data:image/...;base64,. Max decoded size: 2 MB.
commentstringNoOperator-visible note shown on the User profile.

​
Response

{
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "image_url": "https://signed-url.example/face.jpg",
  "comment": "Imported from previous KYC provider",
  "uploaded_by": "api",
  "created_at": "2026-05-18T12:00:00Z"
}

​
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: 
curl https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/ \
  -H "x-api-key: YOUR_API_KEY"
Delete one profile face: 
curl -X DELETE https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/$FACE_UUID/ \
  -H "x-api-key: YOUR_API_KEY"

​
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.