GET/Face-auth/{authId} - ARGOS Identity

The single lookup is now a separate endpoint from the list lookup.What used to be GET /v3/faceauth?authId=... is now GET /v3/face-auth/{authId}, with authId as a path parameter. To move an existing integration, see FaceAuth Common Reference — Migrating from the previous API.

Looks up a single FaceAuth submission. It can be retrieved by authId immediately after creation, with no need to wait for indexing.

1. Base URL

GET/Face-auth/{authId}

GET https://rest-api.argosidentity.com/v3/face-auth/{authId}

2. Authentication

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

x-api-key

x-api-key: {yourAPIKey}

3. Request Example

GET/Face-auth/{authId}

curl -X GET "https://rest-api.argosidentity.com/v3/face-auth/{authId}" \
  -H "x-api-key: {yourAPIKey}"

4. Path Parameters

string

required

The key of the FaceAuth submission. Use the authId from the POST creation response or the list response.

5. Response

result.json

{
  "authId": "sampleAuthId1",
  "authStatus": "approved",
  "createTime": "2026-08-11T10:09:14.028Z",
  "submitType": "form",
  "kycSubmissionId": "sampleKycSubmissionId1",
  "deleteTime": null,
  "policy": {
    "faceSimilarity": { "enabled": true, "threshold": 85 },
    "occluded": { "enabled": false, "threshold": null },
    "faceCover": { "enabled": false, "threshold": null },
    "headCover": { "enabled": false, "threshold": null },
    "liveness": { "enabled": false, "threshold": null },
    "activeLiveness": { "enabled": true, "threshold": 75 }
  },
  "result": {
    "faceSimilarity": 100,
    "livenessScore": null,
    "activeLivenessScore": 90.60411071777344,
    "occluded": null,
    "faceCover": null,
    "headCover": null
  },
  "signals": {
    "startButtonClickTime": "2026-08-11T10:08:54.742Z",
    "cameraProcessInfo": [
      {
        "processStartTime": "2026-08-11T10:08:57.300Z",
        "processEndTime": "2026-08-11T10:09:12.278Z",
        "type": "faceAuth-passive",
        "error": null
      }
    ]
  },
  "rejectComment": null,
  "failCode": null
}

5-1. Success

A successful single lookup returns 200 OK with a FaceAuthSubmission object. The object sits at the top level as-is.

An items[] element from the list lookup and a single lookup response are the same object. Looking up the same authId through either path returns the same set of fields.
A deleted submission is returned with a value in deleteTime.

5-2. Failure

A failed single lookup returns an HTTP status code with an error object.

A submission belonging to another FaceAuth project returns 404, exactly as a nonexistent authId does. The response cannot be used to tell the two cases apart.

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 `authId` path parameter is invalid
`403`	`AUTH_FORBIDDEN`	The API key is valid but is not linked to a FaceAuth project
`404`	`FACEAUTH_SUBMISSION_NOT_FOUND`	The `authId` cannot be found in this project
`503`	`UPSTREAM_UNAVAILABLE`	An internal service required for the lookup is temporarily unavailable. Retry the same request shortly
`503`	`UPSTREAM_INVALID_RESPONSE`	The internal lookup result cannot be converted to the public contract
`500`	`INTERNAL_UNEXPECTED`	An unexpected server error

​1. Base URL

​2. Authentication

​3. Request Example

​4. Path Parameters

​5. Response

​5-1. Success

​5-2. Failure

​6. Error Responses

1. Base URL

2. Authentication

3. Request Example

4. Path Parameters

5. Response

5-1. Success

5-2. Failure

6. Error Responses