> ## 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.
# API para subir rostro de usuario: perfil de usuario
> Sube una imagen facial en base64 a un perfil de usuario existente de Didit tras crear o importar un usuario con vendor_data.
Prompt para subir el rostro de un usuario
Copiar el prompt al portapapeles
\
\`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.`
\
Pegar en
## Descripción generalUsa este endpoint cuando importes usuarios desde otro proveedor y ya tengas una imagen facial de confianza de cada persona. El usuario sigue estando identificado por tu `vendor_data`, pero este endpoint para adjuntar datos al perfil usa `didit_internal_id` para que no haya ambigüedad sobre el usuario de destino.> [!NOTE]
>
> Esto es distinto de [Subir rostro a una lista](https://docs.didit.me/es/management-api/lists/upload-face.md). La subida al perfil adjunta un rostro a un usuario como evidencia, para la detección de duplicados y la búsqueda facial. La subida a una lista añade un rostro a una lista de bloqueo de tipo rostro para que se puedan rechazar las sesiones futuras que coincidan.## Endpoint**`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`**## Flujo de migración**1. Crea o busca el usuario**Invoca [`POST /v3/users/create/`](https://docs.didit.me/es/management-api/users/create) para un perfil nuevo, o a [`GET /v3/users/{vendor_data}/`](https://docs.didit.me/es/management-api/users/get) para uno existente.**2. Guarda didit\_internal\_id**La respuesta del usuario incluye `didit_internal_id`. Sigue usando `vendor_data` en tu base de datos; usa `didit_internal_id` solo para los endpoints que adjuntan datos al perfil.**3. Sube el rostro**Envía una imagen en base64 sin prefijo en el campo `image`. El backend valida que la imagen se decodifique, su tamaño y la detección del rostro antes de guardarla.## Ejemplo```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": "",
"comment": "Imported from previous KYC provider"
}'
```## Cuerpo de la solicitud| Campo | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| `image` | string | Sí | JPG o PNG codificado en base64 sin prefijo. No incluyas `data:image/...;base64,`. Tamaño máximo decodificado: 2 MB. |
| `comment` | string | No | Nota visible para los operadores que se muestra en el perfil del usuario. |## Respuesta```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"
}
```## Validación y límites- Máximo 5 rostros subidos manualmente por usuario.
- El tamaño máximo de la imagen decodificada es de 2 MB.
- La imagen debe estar en base64 válido y decodificarse como imagen.
- La imagen debe contener un rostro detectable. Usa un recorte frontal del rostro y bien iluminado siempre que sea posible.
- El rostro subido se indexa para la detección de duplicados y la búsqueda facial futuras.
- El rostro subido no se añade automáticamente a una lista de bloqueo.## Listar o eliminar rostros subidosListar los rostros del perfil:```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"
```Eliminar un rostro del perfil:```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"
```## PermisosUsa una clave de API de la misma aplicación. La clave debe pertenecer a una aplicación autorizada para gestionar el perfil del usuario de destino.## Posibles errores- `400`: base64 no válido, imagen no válida, ningún rostro detectable, imagen de más de 2 MB o el usuario ya tiene 5 rostros subidos.
- `401`: credenciales ausentes o no válidas.
- `403`: la clave de API es válida, pero no está autorizada para gestionar el perfil de este usuario.
- `404`: no existe ningún usuario con ese `didit_internal_id` en la aplicación.
- `429`: se superó el límite de solicitudes; espera antes de reintentar según `Retry-After`.## Relacionado- [Crear usuario](https://docs.didit.me/es/management-api/users/create.md)
- [Obtener usuario](https://docs.didit.me/es/management-api/users/get.md)
- [Importar y exportar usuarios](https://docs.didit.me/es/entities/users/import-export.md)
- [Rostros y biometría](https://docs.didit.me/es/entities/users/faces-and-biometrics.md)
- [Subir rostro a una lista de bloqueo](https://docs.didit.me/es/management-api/lists/upload-face.md)
## OpenAPI
````yaml es/openapi-25.json 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: API de verificación de identidad. Autentícate con el encabezado x-api-key.
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: Subir el rostro del usuario
description: >-
Adjunta una imagen facial importada y de confianza a un perfil de User
existente. Úsalo después de crear u obtener un User por `vendor_data` y
leer su `didit_internal_id`. El rostro subido se almacena en el perfil
de User y se indexa para la detección de duplicados y la búsqueda
facial. No se añade a una lista de bloqueo facial.
operationId: upload_user_face
parameters:
- name: organization_id
in: path
required: true
schema:
type: string
format: uuid
description: UUID de la organización propietaria de la aplicación.
- name: application_id
in: path
required: true
schema:
type: string
format: uuid
description: UUID de la aplicación a la que pertenece el perfil del usuario.
- name: didit_internal_id
in: path
required: true
schema:
type: string
format: uuid
description: >-
UUID interno de usuario de Didit, devuelto como `didit_internal_id`
por `GET /v3/users/{vendor_data}/` y `POST /v3/users/create/`.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- image
properties:
image:
type: string
format: byte
description: >-
Imagen facial JPG o PNG sin procesar codificada en base64.
No incluyas un prefijo `data:image/...;base64,`. Tamaño
máximo decodificado: 2 MB.
comment:
type: string
description: >-
Nota opcional, visible para los operadores, sobre el rostro
subido.
default: ''
examples:
Imported face:
summary: Adjuntar un rostro importado de un proveedor anterior
value:
image: /9j/4AAQSkZJRgABAQEA...
comment: Imported from previous KYC provider
responses:
'201':
description: Rostro subido y vinculado al perfil del usuario.
content:
application/json:
schema:
type: object
required:
- uuid
- image_url
- comment
- uploaded_by
- created_at
properties:
uuid:
type: string
format: uuid
description: UUID del registro facial de usuario subido.
image_url:
type: string
format: uri
nullable: true
description: URL firmada de la imagen facial subida.
comment:
type: string
nullable: true
description: Comentario proporcionado al subir el rostro.
uploaded_by:
type: string
nullable: true
description: >-
Correo electrónico o identificador del actor que subió el
archivo, cuando esté disponible.
created_at:
type: string
format: date-time
description: Marca de tiempo de la subida.
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: >-
Cuerpo de la solicitud o imagen no válidos. Causas habituales:
base64 no válido, imagen no válida, ningún rostro detectable, imagen
de más de 2 MB, embedding ausente o el usuario ya tiene 5 rostros
subidos.
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: Clave de API ausente o no válida.
content:
application/json:
examples:
Missing key:
value:
detail: Authentication credentials were not provided.
'403':
description: >-
La credencial es válida, pero no puede escribir perfiles de usuario
para esta aplicación.
content:
application/json:
examples:
Forbidden:
value:
detail: You do not have permission to perform this action.
'404':
description: >-
No existe ningún usuario con ese `didit_internal_id` en la
aplicación.
content:
application/json:
examples:
Not found:
value:
detail: Not found.
'429':
description: Límite de solicitudes superado; espera y reintenta.
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: |-
from didit import Didit
# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
# and DIDIT_APPLICATION_ID.
client = Didit()
result = client.users.upload_face(
"11111111-2222-3333-4444-555555555555",
image="/9j/4AAQSkZJRgABAQEA...",
comment="Imported from previous KYC provider",
)
print(result)
- lang: javascript
label: Node.js
source: >-
import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
// and DIDIT_APPLICATION_ID.
const didit = new Didit();
const result = await
didit.users.uploadFace("11111111-2222-3333-4444-555555555555", {
image: "/9j/4AAQSkZJRgABAQEA...",
comment: "Imported from previous KYC provider",
});
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Users.UploadFace(ctx, \"11111111-2222-3333-4444-555555555555\", didit.UsersUploadFaceParams{\n\tImage: \"/9j/4AAQSkZJRgABAQEA...\",\n\tComment: didit.String(\"Imported from previous KYC provider\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: >-
import me.didit.Didit;
import me.didit.types.UsersUploadFaceParams;
// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
// and DIDIT_APPLICATION_ID.
Didit client = new Didit();
var result =
client.users().uploadFace("11111111-2222-3333-4444-555555555555",
UsersUploadFaceParams.builder()
.image("/9j/4AAQSkZJRgABAQEA...")
.comment("Imported from previous KYC provider")
.build());
System.out.println(result);
- lang: php
label: PHP
source: >-
users->uploadFace('11111111-2222-3333-4444-555555555555', [
'image' => '/9j/4AAQSkZJRgABAQEA...',
'comment' => 'Imported from previous KYC provider',
]);
print_r($result->toArray());
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
# and DIDIT_APPLICATION_ID.
didit = Didit::Client.new
result = didit.users.upload_face(
"11111111-2222-3333-4444-555555555555",
image: "/9j/4AAQSkZJRgABAQEA...",
comment: "Imported from previous KYC provider"
)
puts result.to_h
- lang: csharp
label: .NET
source: >-
using System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
// and DIDIT_APPLICATION_ID.
using var client = new DiditClient();
var result = await
client.Users.UploadFaceAsync("11111111-2222-3333-4444-555555555555",
new UsersUploadFaceParams
{
Image = "/9j/4AAQSkZJRgABAQEA...",
Comment = "Imported from previous KYC provider",
});
Console.WriteLine(JsonSerializer.Serialize(result));
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
La clave de API de tu aplicación, que encontrarás en Developers -> API
keys en la Business Console. La clave principal tiene acceso completo.
Una clave con nombre puede tener un alcance limitado: ninguno, lectura o
escritura por recurso, limitada a algunos flujos o a sesiones aprobadas,
a una lista de direcciones IP y a una fecha de caducidad. 401 significa
que la clave es incorrecta, se revocó o expiró; 403 significa que no se
envió ninguna clave, que la clave no tiene acceso a este recurso o
acción, o que la solicitud provino de una dirección fuera de su lista de
IP; 404 en una ruta de sesión significa que la sesión está fuera de los
flujos o estados de la clave. Una clave sin acceso a contenido
multimedia recibe las URL de imágenes, videos y PDF como null, y una
clave sin permiso de escritura en sesiones recibe los enlaces y tokens
de sesión como null. Consulta https://docs.didit.me/console/api-keys.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.