> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload User Face

> Attach a trusted imported face image to an existing User profile. Use this after creating or retrieving a User by `vendor_data` and reading its `didit_internal_id`. The uploaded face is stored on the User profile and indexed for duplicate detection and face search. It is not added to a face blocklist.

export const AgentPromptAccordion = ({prompt, title = "AI Agent Integration Prompt"}) => {
  const [copied, setCopied] = React.useState(false);
  const handleCopy = e => {
    e.stopPropagation();
    if (!prompt) return;
    navigator.clipboard.writeText(prompt.trim()).then(() => {
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    });
  };
  const agents = ["Claude Code", "Codex", "Cursor", "Devin", "Windsurf", "GitHub Copilot"];
  return <div className="didit-agent-card">
      {}
      <div className="didit-agent-titlebar">
        <div className="didit-agent-dots" aria-hidden="true">
          <span className="didit-agent-dot didit-agent-dot-red"></span>
          <span className="didit-agent-dot didit-agent-dot-yellow"></span>
          <span className="didit-agent-dot didit-agent-dot-green"></span>
        </div>
        <span className="didit-agent-filename">{title}</span>
        <button type="button" className={`didit-agent-copy ${copied ? "didit-agent-copy-copied" : ""}`} onClick={handleCopy} title="Copy prompt to clipboard" aria-label={copied ? "Copied!" : "Copy prompt to clipboard"}>
          {copied ? <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <path d="M3 8.5l3.5 3.5L13 4" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
              </svg>
              <span>Copied</span>
            </> : <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <rect x="5" y="5" width="9" height="9" rx="1.5" stroke="currentColor" strokeWidth="1.5" />
                <path d="M11 5V3.5A1.5 1.5 0 0 0 9.5 2h-6A1.5 1.5 0 0 0 2 3.5v6A1.5 1.5 0 0 0 3.5 11H5" stroke="currentColor" strokeWidth="1.5" />
              </svg>
              <span>Copy</span>
            </>}
        </button>
      </div>

      {}
      <pre className="didit-agent-body"><code>{prompt.trim()}</code></pre>

      {}
      <div className="didit-agent-footer">
        <span className="didit-agent-footer-label">Paste into</span>
        <div className="didit-agent-chips">
          {agents.map(name => <span key={name} className="didit-agent-chip">{name}</span>)}
        </div>
      </div>
    </div>;
};

<AgentPromptAccordion
  title="Upload User Face Prompt"
  prompt={`Goal: Attach a trusted imported face image to an existing Didit User profile.

Use case: I am migrating users from another provider. I already have a stable vendor_data and a face image I am allowed to process. I want the User profile to carry that face for evidence, duplicate detection, and face search.

Flow:
1. Create or retrieve the User by vendor_data:
POST https://verification.didit.me/v3/users/create/
GET  https://verification.didit.me/v3/users/{vendor_data}/
2. Read didit_internal_id from the User response.
3. Upload the face to:
POST https://verification.didit.me/v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/

Auth: x-api-key for the same application.
Content-Type: application/json

Request body:
- image (string, required) — raw base64-encoded JPG or PNG. Do not include a data URL prefix. Max decoded size: 2 MB.
- comment (string, optional) — operator-visible note, for example "Imported from previous KYC provider".

Response 201:
{
"uuid": "face-upload-uuid",
"image_url": "https://signed-url.example/...",
"comment": "Imported from previous KYC provider",
"uploaded_by": "api",
"created_at": "2026-05-18T12:00:00Z"
}

Limits:
- Max 5 manually uploaded faces per User.
- The image must decode as an image and contain a detectable face.
- This enrolls the face for profile evidence and matching. It does not add the face to a blocklist.

To block a face, use POST /v3/lists/{list_uuid}/entries/face-upload/ with a face-type list instead.`}
/>

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

<Note>
  This is different from [Upload face to list](/management-api/lists/upload-face). 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.
</Note>

## Endpoint

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

## Migration flow

<Steps>
  <Step title="Create or find the User">
    Call [`POST /v3/users/create/`](/management-api/users/create) for a new profile, or [`GET /v3/users/{vendor_data}/`](/management-api/users/get) for an existing one.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Example

```bash theme={null}
# 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

| Field     | Type   | Required | Description                                                                                     |
| --------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `image`   | string | Yes      | Raw base64-encoded JPG or PNG. Do not include `data:image/...;base64,`. Max decoded size: 2 MB. |
| `comment` | string | No       | Operator-visible note shown on the User profile.                                                |

## Response

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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`.

## Related

* [Create User](/management-api/users/create)
* [Get User](/management-api/users/get)
* [Import and Export Users](/entities/users/import-export)
* [Faces and Biometrics](/entities/users/faces-and-biometrics)
* [Upload face to blocklist](/management-api/lists/upload-face)


## OpenAPI

````yaml POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: Identity verification API. Authenticate with x-api-key header.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/:
    post:
      tags:
        - Users
      summary: Upload user face
      description: >-
        Attach a trusted imported face image to an existing User profile. Use
        this after creating or retrieving a User by `vendor_data` and reading
        its `didit_internal_id`. The uploaded face is stored on the User profile
        and indexed for duplicate detection and face search. It is not added to
        a face blocklist.
      operationId: upload_user_face
      parameters:
        - name: organization_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Organization UUID that owns the application.
        - name: application_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Application UUID that owns the User profile.
        - name: didit_internal_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: >-
            Didit's internal User UUID, returned as `didit_internal_id` by `GET
            /v3/users/{vendor_data}/` and `POST /v3/users/create/`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - image
              properties:
                image:
                  type: string
                  format: byte
                  description: >-
                    Raw base64-encoded JPG or PNG face image. Do not include a
                    `data:image/...;base64,` prefix. Max decoded size: 2 MB.
                comment:
                  type: string
                  description: Optional operator-visible note for the uploaded face.
                  default: ''
            examples:
              Imported face:
                summary: Attach a face imported from a previous provider
                value:
                  image: /9j/4AAQSkZJRgABAQEA...
                  comment: Imported from previous KYC provider
      responses:
        '201':
          description: Face uploaded and attached to the User profile.
          content:
            application/json:
              schema:
                type: object
                required:
                  - uuid
                  - image_url
                  - comment
                  - uploaded_by
                  - created_at
                properties:
                  uuid:
                    type: string
                    format: uuid
                    description: UUID of the uploaded User face record.
                  image_url:
                    type: string
                    format: uri
                    nullable: true
                    description: Signed URL for the uploaded face image.
                  comment:
                    type: string
                    nullable: true
                    description: Comment supplied when the face was uploaded.
                  uploaded_by:
                    type: string
                    nullable: true
                    description: Email or actor identifier of the uploader when available.
                  created_at:
                    type: string
                    format: date-time
                    description: Upload timestamp.
              examples:
                Uploaded:
                  value:
                    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'
        '400':
          description: >-
            Invalid request body or image. Common causes: invalid base64,
            invalid image, no detectable face, image over 2 MB, missing
            embedding, or the User already has 5 uploaded faces.
          content:
            application/json:
              examples:
                No face:
                  value:
                    image: >-
                      No face detected in the image. Please upload a clear photo
                      with a visible face.
                Too many faces:
                  value:
                    detail: Maximum of 5 faces per user reached.
                Too large:
                  value:
                    image: Image exceeds maximum size of 2 MB.
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              examples:
                Missing key:
                  value:
                    detail: Authentication credentials were not provided.
        '403':
          description: >-
            The credential is valid but cannot write User profiles for this
            application.
          content:
            application/json:
              examples:
                Forbidden:
                  value:
                    detail: You do not have permission to perform this action.
        '404':
          description: No User exists for that `didit_internal_id` in the application.
          content:
            application/json:
              examples:
                Not found:
                  value:
                    detail: Not found.
        '429':
          description: Rate limit exceeded; back off and retry.
          content:
            application/json:
              examples:
                Rate limited:
                  value:
                    detail: Request was throttled. Expected available in 30 seconds.
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: >-
            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"}'
        - lang: python
          label: Python
          source: |-
            import requests

            resp = requests.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/',
                headers={'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json'},
                json={
                    'image': '/9j/4AAQSkZJRgABAQEA...',
                    'comment': 'Imported from previous KYC provider',
                },
            )
            resp.raise_for_status()
            face = resp.json()
            print(face['uuid'], face['image_url'])
        - lang: javascript
          label: JavaScript
          source: >-
            const resp = await
            fetch('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/',
            {
              method: 'POST',
              headers: { 'x-api-key': process.env.DIDIT_API_KEY, 'Content-Type': 'application/json' },
              body: JSON.stringify({
                image: '/9j/4AAQSkZJRgABAQEA...',
                comment: 'Imported from previous KYC provider',
              }),
            });

            const face = await resp.json();

            console.log(face.uuid, face.image_url);
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````