Saltar al contenido principal
POST
curl

Descripción general

Usa 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.
Esto es distinto de Subir rostro a una lista. 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/ para un perfil nuevo, o a GET /v3/users/{vendor_data}/ 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

Cuerpo de la solicitud

Respuesta

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 subidos

Listar los rostros del perfil:
Eliminar un rostro del perfil:

Permisos

Usa 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

Autorizaciones

x-api-key
string
header
requerido

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.

Parámetros de ruta

organization_id
string<uuid>
requerido

UUID de la organización propietaria de la aplicación.

application_id
string<uuid>
requerido

UUID de la aplicación a la que pertenece el perfil del usuario.

didit_internal_id
string<uuid>
requerido

UUID interno de usuario de Didit, devuelto como didit_internal_id por GET /v3/users/{vendor_data}/ y POST /v3/users/create/.

Cuerpo

application/json
image
string<byte>
requerido

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
string
predeterminado:""

Nota opcional, visible para los operadores, sobre el rostro subido.

Respuesta

Rostro subido y vinculado al perfil del usuario.

uuid
string<uuid>
requerido

UUID del registro facial de usuario subido.

image_url
string<uri> | null
requerido

URL firmada de la imagen facial subida.

comment
string | null
requerido

Comentario proporcionado al subir el rostro.

uploaded_by
string | null
requerido

Correo electrónico o identificador del actor que subió el archivo, cuando esté disponible.

created_at
string<date-time>
requerido

Marca de tiempo de la subida.

Última modificación el 1 de noviembre de 2026