> ## 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/Faceauth

> An API to retrieve specific submissions or the entire submission list using filters such as authId, startDate, and endDate for efficient data retrieval.

## 1. Base URL

```text GET/FaceAuth theme={null}
https://rest-api.argosidentity.com/v3/faceauth
```

## 2. Authentication

Include the API key in the x-api-key header:

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

## 3. Request Example

```curl GET/FaceAuth theme={null}
curl -X GET "https://rest-api.argosidentity.com/v3/faceauth" \
-H "x-api-key: {yourAPIKey}" \
```

## 4. Request Parameters

Example with Parameters

```curl GET/FaceAuth theme={null}
curl -X GET "https://rest-api.argosidentity.com/v3/faceauth?auth_id={auth_id}&startDate={startDate}" \
-H "x-api-key: {yourAPIKey}" \
```

<ResponseField name="authId" type="string">
  Used for retrieving a specific submission. If `authId` is provided, only the corresponding submission is returned; otherwise, the full list is retrieved.
</ResponseField>

<ResponseField name="startDate" type="string">
  Start date of the query (`yyyy-mm-dd` format). To filter data within a specific period, both `startDate` and `endDate` must be provided.
</ResponseField>

<ResponseField name="endDate" type="string">
  End date of the query (`yyyy-mm-dd` format).
</ResponseField>

<ResponseField name="nextKey_id" type="string">
  The `authId` value from the `nextPage_key` object in the response of the previous request.
</ResponseField>

<ResponseField name="nextKey_date" type="string">
  The `createTime` value from the `nextPage_key` object in the response of the previous request.
</ResponseField>

<ResponseField name="count" type="string">
  Specifies the number of data entries to retrieve (minimum 1, maximum 2,000). If not provided, the default value is 2,000.
</ResponseField>

<Note>
  * **Maximum retrieval limit**: A single request can retrieve up to 2,000 entries.
  * **Fetching additional data**: If more data is available, the response includes the `nextPage_key` object.
    To continue retrieving data, use `nextPage_key`'s `authId` as `nextKey_id` and `createTime` as `nextKey_date` in the next request.
</Note>

## 5. Response

### 5-1. Response (delete\_check:false)

```json result.json theme={null}
[
  {
    "faceAuth_projectId": "sampleProjectId1",
    "data": [
      {
        "policy": {
          "faceSimilarity_threshold": 85,
          "occluded_threshold": false,
          "faceCover_threshold": 0,
          "headCover_threshold": 0,
          "liveness_threshold": 0,
          "activeLiveness_threshold": 0
        },
        "auth_id": "sampleId1",
        "auth_status": "rejected",
        "create_time": "2025-10-02T02:15:17.554Z",
        "submit_type": "form",
        "kyc_submission_id": "sampleKycId1",
        "delete_check": false,
        "result": {
          "active_liveness_score": 97.78668212890625,
          "face_similarity": 100,
          "detectOccluded": true
        },
        "reject_comment": [
          "face is occluded and the confidence is higher than threshold."
        ],
        "fail_code": [
          "Face_Occluded_fail"
        ],
        "signals": {
          "cameraProcessInfo": [
            {
              "processStartTime": "YYYY-MM-DD-HH-MM-SS-ZZZ",
              "processEndTime": "YYYY-MM-DD-HH-MM-SS-ZZZ",
              "type": "faceAuth-active",
              "error": null
            }
          ],
          "startButtonClickTime": "YYYY-MM-DD-HH-MM-SS-ZZZ"
        }        
      },
      {
        "policy": {
          "faceSimilarity_threshold": 85,
          "occluded_threshold": false,
          "faceCover_threshold": 0,
          "headCover_threshold": 0,
          "liveness_threshold": 0,
          "activeLiveness_threshold": 0
        },
        "auth_id": "sampleId2",
        "auth_status": "rejected",
        "create_time": "2025-10-02T02:15:17.554Z",
        "submit_type": "form",
        "kyc_submission_id": "sampleKycId1",
        "delete_check": true,
        "delete_time": "2025-10-09T03:18:18.046Z"
        "result": {
          "active_liveness_score": 97.78668212890625,
          "face_similarity": 100,
          "detectOccluded": true
        },
        "reject_comment": [
          "face is occluded and the confidence is higher than threshold."
        ],
        "fail_code": [
          "Face_Occluded_fail"
        ],
        "signals": {
          "cameraProcessInfo": [
            {
              "processStartTime": "YYYY-MM-DD-HH-MM-SS-ZZZ",
              "processEndTime": "YYYY-MM-DD-HH-MM-SS-ZZZ",
              "type": "faceAuth-active",
              "error": null
            }
          ],
          "startButtonClickTime": "YYYY-MM-DD-HH-MM-SS-ZZZ"
        }        
      }
    ],
    "nextPage_key": {
        "authId": "sampleId2",
        "createTime": "2025-10-02T02:15:17.554Z"
      }
  }
]
```

### 5-2. Response (delete\_check:true)

```json result.json theme={null}
[     
  { 
    "auth_id" : "sampleId1", 
		"aurh_status" : "approved",
		"create_time" : "2023-08-18T15:00:00.000Z",
		"submit_type" : "sampleType",
		"kyc_submission_id" : "sampleKycId1",
		"policy" : {
			"faceSimilarity_threshold" : 70,
			"occluded_threshold" : false, 
			"faceCover_threshold" : 0,
			"headCover_threshold" : 50
		},
    "delete_check": true,
    "delete_time": "2023-09-04T02:19:01.399Z",
    "result": {
      "active_liveness_score": 97.78668212890625,
      "face_similarity": 100,
      "detectOccluded": true
    },
  }
]
```

### 5-2. Response Example

<ResponseField name="faceAuth_projectId" type="string">
  FaceAuth project ID
</ResponseField>

<ResponseField name="data" type="array">
  Array of retrieved submissions

  <Expandable title="Properties">
    <ResponseField name="[i]" type="object" required="false">
      Individual submission object

      <Expandable title="Properties">
        <ResponseField name="policy" type="string">
          Threshold policy object applied for authentication

          <Expandable title="Properties">
            <ResponseField name="faceSimilarity_threshold" type="string">
              Face similarity threshold
            </ResponseField>

            <ResponseField name="faceCover_threshold" type="string">
              Face occlusion detection threshold (goggles, masks, protective equipment)
            </ResponseField>

            <ResponseField name="headCover_threshold" type="string">
              Head protection equipment detection threshold
            </ResponseField>

            <ResponseField name="occluded_threshold" type="boolean">
              Whether the face is obscured by hands or other objects
            </ResponseField>

            <ResponseField name="liveness_threshold" type="boolean">
              Passive liveness threshold
            </ResponseField>

            <ResponseField name="activeLiveness_threshold" type="boolean">
              Active liveness threshold
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="auth_id" type="string">
          Unique authentication ID for each submission
        </ResponseField>

        <ResponseField name="auth_status" type="string">
          Authentication result (e.g., approved, rejected)
        </ResponseField>

        <ResponseField name="create_time" type="string">
          Submission date and time (UTC+0)
        </ResponseField>

        <ResponseField name="submit_type" type="string">
          Submission method
        </ResponseField>

        <ResponseField name="kyc_submission_id" type="string">
          ID of the KYC submission where FaceAuth was performed
        </ResponseField>

        <ResponseField name="delete_check" type="boolean">
          Whether the data has been deleted
        </ResponseField>

        <ResponseField name="delete_time" type="string">
          Deletion date and time (UTC+0)
        </ResponseField>

        <ResponseField name="result" type="object">
          Authentication result data object

          <Expandable title="Properties">
            <ResponseField name="faceSimilarity" type="number">
              Face similarity result value
            </ResponseField>

            <ResponseField name="occluded" type="boolean">
              Result value indicating whether the face is covered by hands or specific objects
            </ResponseField>

            <ResponseField name="headCover" type="number">
              Face occlusion detection result value (goggles, masks, protective equipment)
            </ResponseField>

            <ResponseField name="faceCover" type="number">
              Head protection equipment detection result value
            </ResponseField>

            <ResponseField name="livenessScore" type="number">
              Passive liveness result value
            </ResponseField>

            <ResponseField name="activeLivenessScore" type="number">
              Active liveness result value
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="rejectComment" type="array">
          Rejection reason
        </ResponseField>

        <ResponseField name="failCode" type="array">
          Failure code
        </ResponseField>

        <ResponseField name="signals" type="object">
          Additional data object generated during the process

          <Expandable title="Properties">
            <ResponseField name="startButtonClickTime" type="string">
              Timestamp when the user clicked the start button (ISO 8601 format)
            </ResponseField>

            <ResponseField name="cameraProcessInfo" type="array">
              Array of camera operation data

              <Expandable title="Properties">
                <ResponseField name="[i].type" type="string">
                  Process type (e.g., `faceAuth-passive` or `faceAuth-active`.)
                </ResponseField>

                <ResponseField name="[i].processStartTime" type="string">
                  Timestamp when the process started (ISO 8601 format)
                </ResponseField>

                <ResponseField name="[i].processEndTime" type="string">
                  Timestamp when the process ended (ISO 8601 format)
                </ResponseField>

                <ResponseField name="[i].error" type="string">
                  Error that occurred during the process (`null` if no error)
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="nextPage_key" type="object">
  Key object for retrieving the next page

  <Expandable title="Properties">
    <ResponseField name="create_time" type="string">
      create\_time of the key for retrieving the next page
    </ResponseField>

    <ResponseField name="authId" type="string">
      authId of the key for retrieving the next page
    </ResponseField>
  </Expandable>
</ResponseField>

### 5-3. Error Codes

If an error occurs, a 400 status code is returned along with details in the response body:

```json error.json theme={null}
{
  traceId: '0199cb93-bdf1-77ef-8cd4-3d38dec61830',
  errorCode: 'NOT_FOUND',
  message: 'faceAuth_project not found'
}
```

| Error Code                   | Description                                                                                                                       |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `faceAuth_project not found` | This error occurs when there is no valid project corresponding to the submitted API-Key. Please check if your API-Key is correct. |