GET/Face-auth (List) - ARGOS Identity

The endpoint has moved to /v3/face-auth.The path, response structure, and field names all differ from the previous endpoint /v3/faceauth. To move an existing integration, see FaceAuth Common Reference — Migrating from the previous API.To look up a single submission, use GET/Face-auth/{authId}. The list lookup and the single lookup are separate endpoints.

Lists FaceAuth submissions in order of most recent creation time. When another page is available, pass the nextCursor from the response to a follow-up request that uses the same conditions.

1. Base URL

GET/Face-auth

GET 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}

This is a separate API key from your Liveform API key. See Add-on Overview — Checking the add-on API key.

3. Request Example

GET/Face-auth

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

You can also query a date range. startDate and endDate must be sent together.

Date range

curl -X GET "https://rest-api.argosidentity.com/v3/face-auth?startDate=2026-08-01T00%3A00%3A00.000Z&endDate=2026-08-31T23%3A59%3A59.999Z&limit=100" \
  -H "x-api-key: {yourAPIKey}"

4. Request Parameters

integer

The maximum number of records to return. The default is 100, the minimum is 10, and the maximum is 200.

string

The nextCursor value from the previous list response. Pass the server-issued value verbatim. It carries a signature, so modifying any part of it returns 400 REQUEST_INVALID. It cannot be assembled by hand or reused with different lookup conditions.

string

The start of the lookup range, in yyyy-MM-dd'T'HH:mm:ss.SSSZ RFC 3339 UTC format. Must be sent together with endDate.

string

The end of the lookup range, in RFC 3339 UTC format. It cannot be earlier than startDate. Both bounds are inclusive.

Sending any query parameter other than the four above returns 400 REQUEST_INVALID. To look up a specific submission, use the single lookup path.
A follow-up request using a cursor must use the same limit, startDate, and endDate as the first request.

5. Response

result.json

{
  "items": [
    {
      "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-active",
            "error": null
          }
        ]
      },
      "rejectComment": null,
      "failCode": null
    },
    {
      "authId": "sampleAuthId2",
      "authStatus": "rejected",
      "createTime": "2026-08-11T09:10:00.000Z",
      "submitType": "api",
      "kycSubmissionId": "sampleKycSubmissionId2",
      "deleteTime": null,
      "policy": {
        "faceSimilarity": { "enabled": true, "threshold": 85 },
        "occluded": { "enabled": true, "threshold": null },
        "faceCover": { "enabled": false, "threshold": null },
        "headCover": { "enabled": false, "threshold": null },
        "liveness": { "enabled": false, "threshold": null },
        "activeLiveness": { "enabled": false, "threshold": null }
      },
      "result": {
        "faceSimilarity": 72.4,
        "livenessScore": null,
        "activeLivenessScore": null,
        "occluded": {
          "value": false,
          "confidence": 99.2
        },
        "faceCover": null,
        "headCover": null
      },
      "signals": null,
      "rejectComment": [
        "face compare similarity score is lower than threshold"
      ],
      "failCode": [
        "face_compare_underscore"
      ]
    }
  ],
  "nextCursor": "v1.eyJ2IjoxLCJjcmVhdGVUaW1l..."
}

5-1. Success

A successful list lookup returns 200 OK with the body below.

array

The array of results. Each element is a FaceAuthSubmission object. It is an empty array when nothing matches.

nullable · string

The value to pass as the cursor parameter of the next page request. null when there is no next page.It is a signed token in the form v1.{payload}.{signature}. The payload holds the position of the last item and the lookup conditions and is base64-encoded, so it can be decoded — but the signature is bound to the lookup conditions, so changing the value or reusing it with different conditions fails validation. Do not depend on its structure; pass back exactly what you received. The format may change without notice.

The response body has exactly two top-level fields: items and nextCursor.
The list can include deleted submissions. A completed deletion has a value in deleteTime.

5-2. Failure

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

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`	An invalid `limit`, date range, or cursor, or an undefined query parameter
`403`	`AUTH_FORBIDDEN`	The API key is valid but is not linked to a FaceAuth 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. Request Parameters

​5. Response

​5-1. Success

​5-2. Failure

​6. Error Responses

1. Base URL

2. Authentication

3. Request Example

4. Request Parameters

5. Response

5-1. Success

5-2. Failure

6. Error Responses