> ## Documentation Index
> Fetch the complete documentation index at: https://developers.argosidentity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GET/Face-auth/{authId}

> An API that looks up a single FaceAuth submission by authId. It is available immediately after creation.

<Warning>
  **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](/en/idcheck/add-on/faceauth-reference#migrating-from-the-previous-api).
</Warning>

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

```text GET/Face-auth/{authId} theme={null}
GET https://rest-api.argosidentity.com/v3/face-auth/{authId}
```

## 2. Authentication

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

```text x-api-key theme={null}
x-api-key: {yourAPIKey}
```

## 3. Request Example

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

## 4. Path Parameters

<ResponseField name="authId" type="string" required>
  The key of the FaceAuth submission. Use the `authId` from the [POST creation response](/en/idcheck/add-on/post-faceauth) or the [list response](/en/idcheck/add-on/get-faceauth).
</ResponseField>

## 5. Response

```json result.json theme={null}
{
  "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](/en/idcheck/add-on/faceauth-reference#faceauthsubmission-object). The object sits at the top level as-is.

<Note>
  * 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`.
</Note>

### 5-2. Failure

A failed single lookup returns an HTTP status code with an [error object](/en/idcheck/add-on/faceauth-reference#error-responses).

<Warning>
  **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.
</Warning>

## 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](/en/idcheck/add-on/faceauth-reference#authentication-layer-errors-401-403).

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