POST/Face-auth - ARGOS Identity

El endpoint se ha trasladado a /v3/face-auth.La respuesta ha pasado de { score, authentication_id, ... } al objeto FaceAuthSubmission, y el código de estado de éxito es ahora 201 Created en lugar de 200. Para migrar una integración existente, consulte Referencia común de FaceAuth — Migrar desde la API anterior.

Léalo primero: FaceAuth se ofrece de dos formas.Esta API corresponde al modo en el que usted implementa la UI de cámara y envía la imagen capturada. Este modo no admite Active Liveness, por lo que no puede bloquear intentos de suplantación como reproducir la pantalla de un móvil o mostrar una foto fija. Si necesita verificación de captura real (liveness), use el método Face Auth URL.→ Comparación de ambos métodos y guía del método URL: Comenzar con FaceAuth · Guía de FACE AUTH

Crea un envío de FaceAuth comparando la imagen facial enviada con la imagen de referencia de un envío KYC aprobado. Aunque el resultado sea rejected, la solicitud se procesó correctamente, de modo que la respuesta es 201 Created.

Notas

El resultado de autenticación depende de la configuración de las opciones y de los valores de umbral, y se devuelve como approved o rejected.
Especificación recomendada de faceImage: 960 x 720
Cómo obtener el submissionId: inicie sesión en el panel, haga clic en Configuración > URL de Liveform y complete el proceso de ID Check. Una vez aprobado el ID Check, encontrará el submissionId en Gestión de usuarios > Lista de envíos. El estado final del ID Check debe ser aprobado.
Sobre la clave API: es una clave API distinta de la de Liveform. Consulte Comenzar con complementos.

1. URL base

POST/Face-auth

POST https://rest-api.argosidentity.com/v3/face-auth

2. Autenticación

Incluya la clave API del proyecto FaceAuth en el encabezado x-api-key.

x-api-key

x-api-key: {yourAPIKey}

3. Ejemplo de solicitud

La solicitud usa multipart/form-data.

Deje que su biblioteca cliente HTTP establezca automáticamente el boundary del multipart: no fije usted mismo el encabezado Content-Type.

POST/Face-auth

curl -X POST "https://rest-api.argosidentity.com/v3/face-auth" \
  -H "x-api-key: {yourAPIKey}" \
  -F "submissionId={approvedKycSubmissionId}" \
  -F "faceImage=@./face.jpg" \
  -F "userId={yourUserId}"

4. Cuerpo de la solicitud

string

requerido

ID del envío KYC aprobado que se usa como referencia de comparación. Debe pertenecer al mismo proyecto FaceAuth.

file

requerido

Archivo de imagen facial que se va a comparar. Debe ser un archivo de imagen no vacío. Si usa las opciones de EPP (protección de cabeza, protección facial), todo el equipo de seguridad debe verse con claridad en la imagen para que la detección sea precisa.No se admiten cadenas base64. Envíe la imagen como archivo.

string

Identificador de usuario definido por usted.

string

Valor del campo personalizado 1.

string

Valor del campo personalizado 2.

string

Valor del campo personalizado 3.

No se admiten campos no definidos, copias duplicadas del mismo campo ni la ausencia de faceImage o submissionId.
userId, cf1, cf2 y cf3 se guardan con el envío pero no se incluyen en las respuestas de consulta. Consúltelos en el panel o mediante el webhook de FaceAuth.

5. Respuesta

5-1. Éxito

Una creación correcta devuelve 201 Created con un objeto FaceAuthSubmission. Use su authId como parámetro de ruta en las solicitudes posteriores de consulta individual, descarga de imagen y eliminación.

result.json

{
  "authId": "sampleAuthId1",
  "authStatus": "approved",
  "createTime": "2026-08-12T03:00:00.000Z",
  "submitType": "api",
  "kycSubmissionId": "sampleKycSubmissionId1",
  "deleteTime": null,
  "result": {
    "faceSimilarity": 99.5,
    "livenessScore": null,
    "activeLivenessScore": null,
    "occluded": null,
    "faceCover": null,
    "headCover": null
  },
  "signals": null,
  "rejectComment": null,
  "failCode": null
}

La respuesta de este endpoint no incluye policy. El resto de campos es idéntico al de la referencia común.Si necesita la política usada para la decisión, invoque la consulta individual con el authId de la respuesta de creación. El policy de esa respuesta es una instantánea del momento de creación, así que sigue mostrando los criterios que decidieron el envío aunque después cambie la configuración del proyecto.

El objeto que devuelve este endpoint tiene estos valores fijos.

submitType es siempre api.
deleteTime es siempre null.
signals es siempre null. Esos valores solo se recopilan en la pantalla de Face Auth URL.
result.activeLivenessScore es siempre null. Active Liveness no se ejecuta en el método API.

La respuesta de POST y una consulta individual posterior del mismo authId son el mismo objeto. Si necesita Active Liveness, use el flujo de Face Auth URL.

5-2. Rechazo

Una decisión negativa no es un error HTTP: devuelve 201 Created con authStatus: "rejected". Determine el éxito o el rechazo a partir de authStatus. Un HTTP 4xx/5xx significa que la solicitud no llegó a procesarse.

result.json

{
  "authId": "sampleAuthId2",
  "authStatus": "rejected",
  "createTime": "2026-08-12T03:00:00.000Z",
  "submitType": "api",
  "kycSubmissionId": "sampleKycSubmissionId1",
  "deleteTime": null,
  "result": {
    "faceSimilarity": 72.4,
    "livenessScore": null,
    "activeLivenessScore": null,
    "occluded": null,
    "faceCover": null,
    "headCover": null
  },
  "signals": null,
  "rejectComment": [
    "face compare similarity score is lower than threshold"
  ],
  "failCode": [
    "face_compare_underscore"
  ]
}

5-3. Códigos de rechazo (failCode)

Los valores de failCode mezclan mayúsculas y minúsculas, así que compare las cadenas exactamente como son. No las normalice.

failCode	Motivo del rechazo	Política correspondiente
`face_compare_underscore`	La similitud facial está por debajo del umbral.	`faceSimilarity`
`Face_Occluded_fail`	Se detectó que el rostro estaba cubierto.	`occluded`
`Face_cover_fail`	No se confirmó el equipo de protección facial: no se detectó ninguno o la confianza de la detección está por debajo del umbral.	`faceCover`
`Head_cover_fail`	No se confirmó el equipo de protección de cabeza: no se detectó ninguno o la confianza de la detección está por debajo del umbral.	`headCover`
`liveness_fail`	La puntuación de Passive Liveness está por debajo del umbral.	`liveness`
`active_liveness_fail`	La puntuación de Active Liveness está por debajo del umbral. No se produce en el método API.	`activeLiveness`

Face_Occluded_fail y Face_cover_fail se parecen, pero sus causas son opuestas. El primero significa que el envío se rechazó porque el rostro estaba cubierto; el segundo, que se rechazó porque no se llevaba equipo de protección. Activar ambas políticas a la vez puede provocar conflictos, así que use solo la que corresponda a su caso.Obtener Face_cover_fail o Head_cover_fail con el rostro descubierto es el comportamiento esperado: significa que hay activada una política que exige equipo de protección. Si no la necesita, desactívela en la configuración del proyecto.

Para saber cómo se corresponden los arreglos de rechazo y cómo procesarlos, consulte Referencia común de FaceAuth — rejectComment y failCode.

6. Respuestas de error

Los errores que devuelve la aplicación de ARGOS usan el formato { code, message }. El 401 y algunos 403 se bloquean en la capa de autenticación y no siguen ese formato: consulte Referencia común de FaceAuth — Respuestas de error.

Estado HTTP	code	Condición
`400`	`REQUEST_INVALID`	El formato multipart, el boundary, los campos obligatorios o los campos duplicados o no definidos son incorrectos. También cubre un `faceImage` vacío o que no puede procesarse como imagen
`400`	`FACEAUTH_FACE_NOT_DETECTED`	No se encontró un rostro comparable en la imagen facial
`403`	`AUTH_FORBIDDEN`	La clave API es válida pero no está vinculada a un proyecto FaceAuth
`404`	`SUBMISSION_NOT_FOUND`	El envío KYC no existe, se eliminó o pertenece a otro proyecto
`409`	`SUBMISSION_NOT_APPROVED`	El envío KYC no está aprobado o no tiene imagen de referencia
`503`	`UPSTREAM_UNAVAILABLE`	Un servicio interno necesario para el análisis facial no está disponible temporalmente. Reintente la misma solicitud en unos instantes
`500`	`INTERNAL_UNEXPECTED`	Error inesperado del servidor

La tabla anterior recoge los códigos que devuelve el método API POST /v3/face-auth. Para los códigos de error del método Face Auth URL (PV-40015, SE-50010–SE-50014, entre otros) y los textos que ven los usuarios, consulte Validación y manejo de errores de Face Auth URL.

​1. URL base

​2. Autenticación

​3. Ejemplo de solicitud

​4. Cuerpo de la solicitud

​5. Respuesta

​5-1. Éxito

​5-2. Rechazo

​5-3. Códigos de rechazo (failCode)

​6. Respuestas de error

1. URL base

2. Autenticación

3. Ejemplo de solicitud

4. Cuerpo de la solicitud

5. Respuesta

5-1. Éxito

5-2. Rechazo

5-3. Códigos de rechazo (failCode)

6. Respuestas de error