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 https://rest-api.argosidentity.com/v3/face-auth/{authId}

GET https://kr.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

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

curl -X GET "https://kr.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

FaceAuth Getting Started

FaceAuth further verifies identity by comparing the selfie of a user approved in the ID check process with the selfie captured during FaceAuth. This page covers the two delivery methods (URL / API), the FaceAuth URL query string structure, and the request parameter definitions.

FaceAuth Result

After faceAuth verification is completed, the final result (approved or rejected) is automatically sent to the Webhook URL registered in the existing ID check project, providing real-time notifications.

​1. Base URL

​2. Authentication

​3. Request Example

​4. Path Parameters

​5. Response

​5-1. Success

​5-2. Failure

​6. Error Responses

​Related documents

FaceAuth Getting Started

FaceAuth Result

1. Base URL

2. Authentication

3. Request Example

4. Path Parameters

5. Response

5-1. Success

5-2. Failure

6. Error Responses

Related documents