FaceAuth Common Reference - ARGOS Identity

The FaceAuth API has moved to /v3/face-auth.The response structure, field names, and error format all differ from the previous endpoint /v3/faceauth. To move an existing integration, start with Migrating from the previous API on this page.

This page collects the definitions shared by several endpoints. Each endpoint page references these definitions by name and documents only what differs on that endpoint.

FaceAuthSubmission object — used by the POST creation response, the items[] elements of the list lookup, and the single lookup response.
Error responses — the error format shared by every endpoint.
Migrating from the previous API — what changes when moving a /v3/faceauth integration to /v3/face-auth.

FaceAuthSubmission object

An object holding the information for a single FaceAuth submission: the authentication result, the policy used for the decision, and the decision scores.

Fields are never omitted from responses.Policies that were not applied, results that were not collected, and arrays that do not apply are returned with null instead of having the key removed. The set of keys in a response body is therefore always the same, regardless of submission type or project settings, and can be checked with value === null alone — no 'field' in obj or undefined checks needed.Fields whose type carries nullable are the ones that can be null.

Top-level fields

string

The key of the FaceAuth submission. Store it — it is used by the single lookup, image download, and delete APIs.

string

The authentication result. One of approved or rejected.

string

When the submission was created, in yyyy-MM-dd'T'HH:mm:ss.SSSZ RFC 3339 UTC format. (For example, 2026-08-11T10:09:14.028Z)

string

How the submission was made. form means the Face Auth URL screen, api means POST /v3/face-auth.

string

The ID of the KYC submission used as the comparison reference.

nullable · string

When the deletion completed, in RFC 3339 UTC format. null for submissions that have not been deleted.

object

The policy used for the decision. All six items are always present. See policy items below.

object

The decision results. All six fields are always present. See result fields below.

nullable · object

Supplementary information collected on the Face Auth URL screen. See signals fields below.

nullable · array

An array of rejection reason strings. null for approved submissions.

nullable · array

An array of rejection code strings. null for approved submissions.

The POST /v3/face-auth creation response does not include policy. Every other field is the same.

policy items

A snapshot of the project settings at processing time. Changing the project settings afterwards does not change the values on submissions that already exist. All six items (faceSimilarity, occluded, faceCover, headCover, liveness, activeLiveness) carry the two fields below.

boolean

Whether this policy was turned on when the submission was processed. Determine whether a policy applied from this value, not from threshold.

nullable · number

The numeric criterion used for the decision. null when enabled is false or when the policy does not use a numeric criterion.

Item	Policy	Pass condition
`faceSimilarity`	Face similarity	`result.faceSimilarity` is at or above `threshold`
`occluded`	No face occlusion	The face is not covered. Uses no numeric criterion, so `threshold` is always `null`
`faceCover`	Face protection equipment required	A mask, goggles, or similar is detected with confidence at or above `threshold`
`headCover`	Head protection equipment required	A helmet or similar is detected with confidence at or above `threshold`
`liveness`	Passive Liveness	`result.livenessScore` is at or above `threshold`
`activeLiveness`	Active Liveness	`result.activeLivenessScore` is at or above `threshold`. Runs only on `submitType: form` submissions

occluded and faceCover / headCover have opposite purposes.occluded forbids covering the face, while faceCover and headCover require protective equipment to be worn. The names look similar but the pass conditions are the reverse of each other. The latter two exist for environments such as industrial sites where protective equipment is required.

enabled is a project setting, not an execution result.A policy that is turned on may still not run, depending on the submission method. Whether it actually ran is determined by the corresponding field in result: null means it did not run. Today the only place this difference appears is activeLiveness. A submitType: api submission returns result.activeLivenessScore as null even when enabled is true, and that is expected.

result fields

The result field of a policy that did not run is null. For example, a submission with policy.liveness.enabled set to false has livenessScore as null.

nullable · number

The face similarity score, between 0 and 100 inclusive. May include decimals.

nullable · number

The Passive Liveness score.

nullable · number

The Active Liveness score. Always null for submitType: api submissions.

nullable · object

The face occlusion detection result. value: true means the face was judged covered and the submission was rejected.

Show Properties

nullable · boolean

Whether it was detected.

nullable · number

The decision confidence, between 0 and 100 inclusive.

nullable · object

The face protection equipment detection result. value: false means it was judged not worn and the submission was rejected. Its properties are the same as occluded.

nullable · object

The head protection equipment detection result. value: false means it was judged not worn and the submission was rejected. Its properties are the same as occluded.

occluded, faceCover, and headCover share the same structure. When the check did not run, the whole object is null — it is never returned with only its properties set to null.

signals fields

Supplementary information collected on the Face Auth URL screen. Only submitType: form submissions with collected values carry data here; submitType: api submissions and submissions with nothing collected have the whole object as null. It is informational and is not used for the authentication decision.

nullable · string

When the user pressed the start button, in RFC 3339 UTC format.

nullable · array

A record of camera capture segments. When there is no record this is null, not an empty array.

Show Properties

nullable · string

When the capture segment started, in RFC 3339 UTC format.

nullable · string

When the capture segment ended, in RFC 3339 UTC format.

nullable · string

The kind of capture segment, such as faceAuth-passive, faceAuth-active, or faceAuth-auto-capture. The list of values is not fixed and may be extended without notice, so ignore values you do not recognise.

nullable · string

An error that occurred during that segment, or null if there was none. The message is collected from the user’s browser and has no fixed format, so do not branch on it.

rejectComment and failCode

rejectComment is a human-readable explanation; failCode is the code to branch on.

Branch on failCode, not rejectComment. The wording of rejectComment changes without notice, and different causes sometimes share the same wording. Please retry with another face image. is used by both liveness_fail and active_liveness_fail.

The two arrays correspond index by index and always have the same length. The reason for failCode[0] is rejectComment[0].

result.json

{
  "rejectComment": [
    "Protection equipment is not found on Head.",
    "face compare similarity score is lower than threshold"
  ],
  "failCode": ["Head_cover_fail", "face_compare_underscore"]
}

A single submission can fail several policies at once, so check every value in the array. The array order follows the policy evaluation order and is not fixed — do not assume a particular code always comes first. For the list of failCode values, see POST /v3/face-auth — Rejection codes.

Parsing notes

The set of keys in a response is always the same. Missing values come back as null, so undefined checks and key-existence checks are unnecessary.
0 is a valid value for policy.*.threshold. Do not use a falsy check to decide whether a policy is configured — use enabled.
Array fields are null, not an empty array, when there is no value. Default them with ?? [] or check !== null before iterating.
Nested objects (occluded, faceCover, headCover, signals) are null as a whole when they do not apply. Check the parent for null before reading its properties.
When a threshold and a score are equal, the threshold is considered met.
Scores may include decimals rather than being integers. Parse them as numbers, not strings.

Error responses

Errors returned by the ARGOS application use the format below.

error.json

{
  "code": "REQUEST_INVALID",
  "message": "limit must be a decimal integer between 10 and 200."
}

string

The error code. Branch on this value rather than on the HTTP status code.

string

A human-readable description. The wording may change without notice, so never branch on string comparison.

The error object has exactly two fields: code and message.

Authentication layer errors (401, 403)

Requests blocked at the authentication layer do not follow the { code, message } format.API key validation happens at the authentication layer, before the request reaches the ARGOS application. Responses blocked at that stage have no code field.

Situation	HTTP status	Response body
No API key sent	`401`	`{ "message": "Unauthorized" }`
Nonexistent or invalid API key	`403`	`{ "message": "..." }`
Valid API key that is not linked to a FaceAuth project	`403`	`{ "code": "AUTH_FORBIDDEN", "message": "..." }`

Handle 401 and authentication-layer 403 by HTTP status, not by code. Neither response has a code field.
403 has two causes with different response formats. If a code field is present the application returned it; if not, the authentication layer blocked the request.
The message of an authentication-layer error is not generated by ARGOS and may change without notice. Do not parse it.

When reporting a technical question or an incident, include the request time (UTC), the endpoint called, and the first four characters of the API key used.

Error code list

HTTP status	code	Condition	Endpoints
`400`	`REQUEST_INVALID`	The request is invalid. See the error section of each endpoint page.	All
`400`	`FACEAUTH_FACE_NOT_DETECTED`	No comparable face was found in the face image.	POST
`403`	`AUTH_FORBIDDEN`	The API key is valid but is not linked to a FaceAuth project.	All
`404`	`FACEAUTH_SUBMISSION_NOT_FOUND`	The `authId` cannot be found in this project.	Single lookup, image, DELETE
`404`	`SUBMISSION_NOT_FOUND`	The KYC submission does not exist, was deleted, or belongs to another project.	POST
`409`	`SUBMISSION_NOT_APPROVED`	The KYC submission is not approved or has no reference image.	POST
`503`	`UPSTREAM_UNAVAILABLE`	An internal service is temporarily unavailable. Retry the same request shortly.	All
`503`	`UPSTREAM_INVALID_RESPONSE`	The internal lookup result cannot be converted to the public contract.	List and single lookup
`500`	`INTERNAL_UNEXPECTED`	An unexpected server error.	All

Migrating from the previous API

If you integrate against the previous endpoint /v3/faceauth, review the changes below. The paths, field names, response envelopes, and error format have all changed.

Endpoints

Operation	Previous API	New API
Create a submission	`POST /v3/faceauth`	`POST /v3/face-auth`
List lookup	`GET /v3/faceauth`	`GET /v3/face-auth`
Single lookup	`GET /v3/faceauth?authId=...`	`GET /v3/face-auth/{authId}`
Image download	`GET /v3/faceauth/image?authId=...`	`GET /v3/face-auth/{authId}/image`
Delete a submission	`DELETE /v3/faceauth?authId=...`	`DELETE /v3/face-auth/{authId}`

authId is now a path parameter rather than a query parameter, and the list lookup and single lookup are separate endpoints.

Response envelopes

Case	Previous API	New API
Single lookup	`{ faceAuth_projectId, data: [ {...} ] }`	The submission object at the top level
List lookup	`{ faceAuth_projectId, data: { items, nextPage_key } }`	`{ items, nextCursor }`
Unknown `authId`	`200` with `data: []`	`404 FACEAUTH_SUBMISSION_NOT_FOUND`
Create a submission	`200` with `{ score, authentication_id, ... }`	`201 Created` with the FaceAuthSubmission object
Delete a submission	`{ "result": "success", "statusCode": 200 }`	`{ "authId": "..." }`

faceAuth_projectId and statusCode have been removed from responses.

Field names

Previous API	New API
`auth_id` / `authentication_id` (POST)	`authId`
`auth_status`	`authStatus`
`create_time`	`createTime`
`submit_type`	`submitType`
`kyc_submission_id`	`kycSubmissionId`
`reject_comment` / `rejected_comment` (POST)	`rejectComment`
`fail_code`	`failCode`
`score` (POST, snake_case)	`result` (camelCase, same as lookups)
`delete_check` + `delete_time`	`deleteTime` alone (`null` before deletion)

Structural changes

policy — from flat thresholds to nested objects

The previous API carried thresholds flat, as in faceSimilarity_threshold: 85, and only occluded_threshold was a boolean.The new API gives each item an { enabled, threshold } object. Whether a policy applied is determined by enabled, not by the value of threshold. occluded uses no numeric criterion, so its threshold is always null.

Previous API

{ "faceSimilarity_threshold": 85, "occluded_threshold": true }

New API

{
  "faceSimilarity": { "enabled": true, "threshold": 85 },
  "occluded": { "enabled": true, "threshold": null }
}

result — occluded, faceCover, and headCover are objects

The previous API returned a single value such as occluded: false (boolean) or headCover: 0 (number). In the new API all three are { value, confidence } objects, and the whole object is null when the check did not run.

New API

{ "occluded": { "value": false, "confidence": 99.2 }, "faceCover": null }

Pagination — from a composite key to a single cursor

The previous API returned nextPage_key and expected its authId and createTime back as nextKey_id and nextKey_date, with the page size set by count (1–2,000, default 2,000).The new API returns a single signed string, nextCursor, which you pass back verbatim as cursor, with the page size set by limit (10–200, default 100). A limit outside the range is no longer ignored — it returns 400 REQUEST_INVALID.

Image download — from a binary body to a 302 redirect

The previous API returned the JPEG binary directly in the response body. The new API returns 302 Found with a short-lived download URL in the Location header, so the HTTP client must be configured to follow redirects (curl --location).

Error format — from three formats to one

The previous API mixed { message, errorCode, statusCode }, { traceId, errorCode, message }, and { message, statusCode } across endpoints, and the image endpoint returned every authentication failure as 403.The new API returns all application errors as { code, message }, with authentication-layer errors as the only exception. See Error responses above.

The change to watch most closely

The previous API dropped the keys of unused options from responses; the new API always includes the key and fills the value with null.Code written against the previous API that decides whether a policy was used from key existence — if (result.headCover) or 'headCover' in result — misbehaves against the new API. Use result.headCover !== null (whether it ran) or policy.headCover.enabled (whether it is configured) instead.

​FaceAuthSubmission object

​Top-level fields

​policy items

​result fields

​signals fields

​rejectComment and failCode

​Parsing notes

​Error responses

​Authentication layer errors (401, 403)

​Error code list

​Migrating from the previous API

​Endpoints

​Response envelopes

​Field names

​Structural changes

​The change to watch most closely

FaceAuthSubmission object

Top-level fields

policy items

result fields

signals fields

rejectComment and failCode

Parsing notes

Error responses

Authentication layer errors (401, 403)

Error code list

Migrating from the previous API

Endpoints

Response envelopes

Field names

Structural changes

The change to watch most closely