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

> 특정 제출 건 또는 전체 제출 목록을 조회하는 API로, authId, startDate, endDate 등의 필터를 활용하여 필요한 데이터를 효과적으로 조회할 수 있습니다.

## 1. Base URL

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

## 2. 인증

x-api-key 헤더에 API 키를 포함시켜야 합니다:

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

## 3. 요청 예시

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

## 4. 요청 파라미터

<ResponseField name="authId" type="string">
  특정 제출 건(단 건) 조회 시 사용. 해당 authId를 제출하면 단일 데이터를 조회하며, 미제출 시 전체 리스트가 조회됨
</ResponseField>

<ResponseField name="startDate" type="string">
  조회 시작 일자 (`yyyy-mm-dd` or ISO string 형식) 특정 기간 내 데이터를 조회하려면 startDate와 endDate를 함께 제출해야 함
</ResponseField>

<ResponseField name="endDate" type="string">
  조회 종료 일자 (`yyyy-mm-dd` or ISO string 형식).
</ResponseField>

<ResponseField name="nextKey_id" type="string">
  이전 요청의 Response에서 반환된 `nextPage_key` 객체의 `authId` 값.
</ResponseField>

<ResponseField name="nextKey_date" type="string">
  이전 요청의 Response에서 반환된 `nextPage_key` 객체의 `createTime` 값.
</ResponseField>

<ResponseField name="count" type="string">
  조회할 데이터 개수 지정 (최소 1 \~ 최대 2,000). 미제출 시 기본값은 2,000건.
</ResponseField>

## 4.1 요청 파라미터들을 url에 추가한 예시

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

<Note>
  * 최대 조회 가능 개수: 한 번의 요청에서 최대 2,000건을 조회할 수 있습니다.
  * 추가 데이터 조회: 조회할 데이터가 더 있는 경우, 응답(Response)에 `nextPage_key` 객체가 포함됩니다.
    이후 데이터를 조회할 때는 `nextPage_key` 객체의 `authId` 값을 `nextKey_id`로, `createTime` 값을 `nextKey_date`로 전달하여 요청해야 합니다.
</Note>

## 5. 응답

### 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. 응답 예시

<ResponseField name="faceAuth_projectId" type="string">
  faceAuth 프로젝트 ID
</ResponseField>

<ResponseField name="data" type="array">
  조회된 제출 건들의 배열

  <Expandable title="Properties">
    <ResponseField name="[i]" type="object" required="false">
      개별 제출 건 객체

      <Expandable title="Properties">
        <ResponseField name="policy" type="string">
          인증에 적용된 임계값 정책 객체

          <Expandable title="Properties">
            <ResponseField name="faceSimilarity_threshold" type="string">
              얼굴 유사도 임계값
            </ResponseField>

            <ResponseField name="faceCover_threshold" type="string">
              얼굴 가림 감지 (고글, 마스크, 보호구 착용) 임계값
            </ResponseField>

            <ResponseField name="headCover_threshold" type="string">
              머리 보호 장비 감지 임계값
            </ResponseField>

            <ResponseField name="occluded_threshold" type="boolean">
              손이나 특정 물체로 얼굴을 가렸는지 여부
            </ResponseField>

            <ResponseField name="liveness_threshold" type="boolean">
              패시브 라이브니스 임계값
            </ResponseField>

            <ResponseField name="activeLiveness_threshold" type="boolean">
              액티브 라이브니스 임계값
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="auth_id" type="string">
          각 제출 건의 고유 인증 ID
        </ResponseField>

        <ResponseField name="auth_status" type="string">
          인증 결과 (예: approved, rejected)
        </ResponseField>

        <ResponseField name="create_time" type="string">
          제출된 날짜와 시간 (UTC+0)
        </ResponseField>

        <ResponseField name="submit_type" type="string">
          제출 방식
        </ResponseField>

        <ResponseField name="kyc_submission_id" type="string">
          faceAuth가 수행된 KYC 제출 건의 ID
        </ResponseField>

        <ResponseField name="delete_check" type="boolean">
          삭제된 데이터인지 여부
        </ResponseField>

        <ResponseField name="delete_time" type="string">
          삭제된 날짜와 시간 (UTC+0)
        </ResponseField>

        <ResponseField name="result" type="object">
          인증 결과 데이터 객체

          <Expandable title="Properties">
            <ResponseField name="faceSimilarity" type="number">
              얼굴 유사도 결과 값
            </ResponseField>

            <ResponseField name="occluded" type="boolean">
              손이나 특정 물체로 얼굴을 가렸는지 결과 값
            </ResponseField>

            <ResponseField name="headCover" type="number">
              얼굴 가림 감지 (고글, 마스크, 보호구 착용) 결과 값
            </ResponseField>

            <ResponseField name="faceCover" type="number">
              머리 보호 장비 감지 결과 값
            </ResponseField>

            <ResponseField name="livenessScore" type="number">
              패시브 라이브니스 결과 값
            </ResponseField>

            <ResponseField name="activeLivenessScore" type="number">
              액티브 라이브니스 결과 값
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="rejectComment" type="array">
          거절 사유
        </ResponseField>

        <ResponseField name="failCode" type="array">
          실패 코드
        </ResponseField>

        <ResponseField name="signals" type="object">
          프로세스 과정에서 생성된 부가 데이터 객체

          <Expandable title="Properties">
            <ResponseField name="startButtonClickTime" type="string">
              사용자가 시작 버튼을 클릭한 시각 (ISO 8601 형식)
            </ResponseField>

            <ResponseField name="cameraProcessInfo" type="array">
              카메라 동작 데이터 배열

              <Expandable title="Properties">
                <ResponseField name="[i].type" type="string">
                  프로세스 타입 (예: `faceAuth-passive`, `faceAuth-active`)
                </ResponseField>

                <ResponseField name="[i].processStartTime" type="string">
                  해당 프로세스가 시작된 시각 (ISO 8601 형식)
                </ResponseField>

                <ResponseField name="[i].processEndTime" type="string">
                  해당 프로세스가 종료된 시각 (ISO 8601 형식)
                </ResponseField>

                <ResponseField name="[i].error" type="string">
                  해당 프로세스 중 발생한 에러 (`null`이면 에러 없음)
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="nextPage_key" type="object">
  다음 페이지 조회를 위한 키 객체

  <Expandable title="Properties">
    <ResponseField name="create_time" type="string">
      다음 페이지 조회를 위한 키의 create\_time
    </ResponseField>

    <ResponseField name="authId" type="string">
      다음 페이지 조회를 위한 키의 authId
    </ResponseField>
  </Expandable>
</ResponseField>

### 5-3. 에러 코드

오류가 발생하면 400 상태 코드와 함께 응답 본문에 세부 정보가 포함됩니다:

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

| 에러 코드                        | 설명                                                                        |
| ---------------------------- | ------------------------------------------------------------------------- |
| `faceAuth_project not found` | 제출한 API-Key에 해당하는 유효한 프로젝트가 없을 경우 발생하는 오류입니다.입력한 API-Key가 올바른지 다시 확인해주세요. |