POST/Face-auth - ARGOS Identity

The endpoint has moved to /v3/face-auth.The response has changed from { score, authentication_id, ... } to the FaceAuthSubmission object, and the success status code is now 201 Created instead of 200. To move an existing integration, see FaceAuth Common Reference — Migrating from the previous API.

Read this first — FaceAuth comes in two forms.This API is the form where you implement the camera UI yourself and send the captured image. It does not support Active Liveness, so it cannot block spoofing attempts such as replaying a phone screen or holding up a still photo. If you need real-capture (liveness) verification, use the Face Auth URL method.→ Comparison of both methods and the URL guide: FaceAuth Overview · FACE AUTH Guide

Creates a FaceAuth submission by comparing the face image you send against the reference image of an approved KYC submission. Even when the result is rejected, the request itself was processed normally, so the response is 201 Created.

Notes

The authentication result depends on the option settings and threshold values, and is returned as either approved or rejected.
Recommended faceImage specification: 960 x 720
How to find submissionId: sign in to the dashboard, click Settings > Liveform URL, and complete the ID Check flow. Once the ID Check is approved, you can find the submissionId under User Management > Submissions. The final ID Check status must be approved.
About the API key: this is a separate API key from your Liveform API key. See Add-on Overview — Checking the add-on API key.

1. Base URL

POST/Face-auth

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

2. Authentication

Include the FaceAuth project API key in the x-api-key header.

x-api-key

x-api-key: {yourAPIKey}

3. Request Example

The request uses multipart/form-data.

Let your HTTP client library set the multipart boundary automatically — do not set the Content-Type header yourself.

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. Request Body

string

required

The ID of the approved KYC submission used as the comparison reference. It must belong to the same FaceAuth project.

file

required

The face image file to compare. It must be a non-empty image file. When PPE options (head cover, face cover) are in use, all safety equipment must be clearly visible in the image for accurate detection.base64 strings are not supported. Send the image as a file.

string

Your own user identifier.

string

The value of custom field 1.

string

The value of custom field 2.

string

The value of custom field 3.

Undefined fields, duplicate copies of the same field, and a missing faceImage or submissionId are not allowed.
userId, cf1, cf2, and cf3 are stored with the submission but are not included in lookup responses. Check them in the dashboard or via the FaceAuth webhook.

5. Response

5-1. Success

A successful creation returns 201 Created with a FaceAuthSubmission object. Use its authId as the path parameter of subsequent single lookup, image download, and delete requests.

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
}

This endpoint’s response does not include policy. Every other field is the same as the common reference.If you need the policy used for the decision, call the single lookup with the authId from the creation response. The policy in that response is a snapshot taken at creation time, so it still shows the criteria that decided the submission even after the project settings change.

The object returned by this endpoint has these fixed values.

submitType is always api.
deleteTime is always null.
signals is always null. Those values are collected only on the Face Auth URL screen.
result.activeLivenessScore is always null. Active Liveness does not run in the API method.

The POST response and a later single lookup of the same authId are the same object. If you need Active Liveness, use the Face Auth URL flow.

5-2. Rejection

A failed decision is not an HTTP error — it returns 201 Created with authStatus: "rejected". Determine success or rejection from authStatus. HTTP 4xx/5xx means the request itself was not processed.

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. Rejection codes (failCode)

failCode values mix upper and lower case, so compare the strings exactly as they are. Do not normalise them.

failCode	Rejection reason	Corresponding policy
`face_compare_underscore`	The face similarity is below the threshold.	`faceSimilarity`
`Face_Occluded_fail`	The face was detected as covered.	`occluded`
`Face_cover_fail`	Face protection equipment was not confirmed — either none was detected or the detection confidence is below the threshold.	`faceCover`
`Head_cover_fail`	Head protection equipment was not confirmed — either none was detected or the detection confidence is below the threshold.	`headCover`
`liveness_fail`	The Passive Liveness score is below the threshold.	`liveness`
`active_liveness_fail`	The Active Liveness score is below the threshold. This does not occur in the API method.	`activeLiveness`

Face_Occluded_fail and Face_cover_fail look alike but have opposite causes. The first means the submission was rejected because the face was covered; the second means it was rejected because protective equipment was not worn. Turning both policies on can put them in conflict, so use only the one that fits your case.Getting Face_cover_fail or Head_cover_fail for a bare face is expected behaviour: it means a policy requiring protective equipment is turned on. If you do not need that policy, turn it off in the project settings.

For how the rejection arrays correspond and how to parse them, see FaceAuth Common Reference — rejectComment and failCode.

6. Error Responses

Errors returned by the ARGOS application use the { code, message } format. 401 and some 403 responses are blocked at the authentication layer and do not follow that format — see FaceAuth Common Reference — Authentication layer errors.

HTTP status	code	Condition
`400`	`REQUEST_INVALID`	The multipart format, boundary, required fields, or duplicate/undefined fields are incorrect. This also covers a `faceImage` that is empty or cannot be processed as an image
`400`	`FACEAUTH_FACE_NOT_DETECTED`	No comparable face was found in the face image
`403`	`AUTH_FORBIDDEN`	The API key is valid but is not linked to a FaceAuth project
`404`	`SUBMISSION_NOT_FOUND`	The KYC submission does not exist, was deleted, or belongs to another project
`409`	`SUBMISSION_NOT_APPROVED`	The KYC submission is not approved or has no reference image
`503`	`UPSTREAM_UNAVAILABLE`	An internal service required for face analysis is temporarily unavailable. Retry the same request shortly
`500`	`INTERNAL_UNEXPECTED`	An unexpected server error

The table above covers the codes returned by the POST /v3/face-auth API method. For the error codes of the Face Auth URL method (PV-40015, SE-50010–SE-50014, and others) and the wording users actually see, refer to Face Auth URL Validation and Error Handling.

​1. Base URL

​2. Authentication

​3. Request Example

​4. Request Body

​5. Response

​5-1. Success

​5-2. Rejection

​5-3. Rejection codes (failCode)

​6. Error Responses

1. Base URL

2. Authentication

3. Request Example

4. Request Body

5. Response

5-1. Success

5-2. Rejection

5-3. Rejection codes (failCode)

6. Error Responses