메인 콘텐츠로 건너뛰기
Notes
  • 인증 결과는 옵션 설정과 임계치 값에 따라 결정되며, 승인(approved) 또는 거절(rejected) 상태로 반환됩니다.
  • faceImage 권장 사양: 960 x 720
  • submissionId 확인 방법: 대시보드에 로그인한 후, 설정 > 라이브폼 URL을 클릭하여 ID Check 절차를 진행합니다. ID Check가 승인된 후에는, 대시보드의 사용자 관리 메뉴 > 제출 목록에서 submissionId 데이터를 확인할 수 있습니다. 단, ID Check의 최종 상태가 반드시 승인이어야 합니다.
  • API Key 관련 안내: 기존 liveform API Key와는 다른 별도의 API Key가 필요합니다. Add-on의 시작하기 에서 애드온 API Key 확인하기를 통해 확인할 수 있습니다.

​
1. Base URL

POST/faceauth
https://rest-api.argosidentity.com/v3/faceauth

​
2. 인증

Include the API key in the x-api-key header:
x-api-key
x-api-key: {yourAPIKey}

​
3. 요청 예시

POST/faceauth
curl --location --request POST 'https://rest-api.argosidentity.com/v3/faceauth' \
--header 'x-api-key: {yourAPIKey}' \
--form 'faceImage=@"/C:/Users/face.jpg"' \
--form 'submissionId= "{submissionId}"' \

​
4. 요청 본문

요청 본문은 JSON 형식이어야 합니다. 다음은 필드 설명입니다:
​
submissionId
string
required
KYC 제출 건별 고유 식별자입니다. *faceAuth는 해당 제출건 (submissionId)이 승인(approved)된 경우에만 진행할 수 있습니다.
​
faceImage
file
required
사용자의 셀피 이미지를 파일로 입력합니다. PPE(머리 보호구, 얼굴 보호구) 옵션을 사용할 경우, 정확한 인식을 위해 이미지에 모든 안전장비가 명확하게 포함되어야 합니다.
​
userId
string
고객사에서 정의한 KYC 제출자 고유 식별자
​
cf1
string
사용자 정의 필드 1의 값
​
cf2
string
사용자 정의 필드 2의 값
​
cf3
string
사용자 정의 필드 3의 값

​
5. 응답

​
5-1. 성공 응답

result.json
{
    "authentication_id": "{authentication_id}",
    "auth_status": "approved",
    "create_time": "2023-08-08T07:04:48.633Z",
    "score": {
			"face_similarity_score": 99.5,
      "occluded_score": 99.9
    }
}

​
5-2. 거절 응답

result.json
{
    "authentication_id": "{authentication_id}",
    "auth_status": "rejected",
    "create_time": "2023-08-08T07:04:48.633Z",
    "score": {
        "face_similarity_score": 83.6,
        "occluded_score": 40,
        "face_cover_socre": 93.3,
        "head_cover_socre": 87
    },
    "fail_code": [
        "Face_Occluded_fail",
    ],
    "rejected_comment": [
        "face is occluded and the confidence is higher than threshold.",
    ]
}

​
5-3. 응답 데이터

필드명데이터 타입설명
authentication_idStringfaceAuth 제출 건에 대한 고유한 ID입니다.
auth_statusStringfaceAuth 최종 결과를 나타냅니다. approved(성공) 또는 rejected(실패)를 반환합니다.
scoreObject사용 옵션에 따른 인식 결과의 점수를 포함합니다. 옵션에 따라 face_similarity_score, occluded_score, face_cover_score, head_cover_score 등의 프로퍼티가 포함될 수 있습니다.
create_timeStringfaceAuth제출된 날짜와 시간 (UTC+0)
fail_codeArrayrejected 상태일 경우, 실패 코드를 반환합니다.
rejected_commentArrayrejected 상태일 경우, 실패 원인에 대한 상세 메시지를 반환합니다.

​
6. 오류 코드

​
6-1. 실패 코드

실패 코드거절 코멘트설명
face_compare_underscoreface compare similarity score is lower than threshold얼굴 유사도 점수가 임계치보다 낮음
Face_Occluded_failface is occluded얼굴이 가려져 있음
Face_cover_failProtection equipment is not found on Face안면 보호 장비가 감지되지 않음
Head_cover_failProtection equipment is not found on Head머리 보호 장비가 감지되지 않음

​
6-2. 에러 코드

에러 코드메시지설명
invalid_data_formatData parsing error. Please check input data입력된 데이터 형식이 부적절합니다. 데이터 포맷을 확인하세요.
required_field_missingRequired field is missing필수 입력 값이 누락되었습니다. 필수 파라미터 2가지(submissionId, faceImage)와 API Key를 확인하세요.
Invalid_submissionIdFail to find the submission dataKYC submission이 존재하지 않습니다.
Invalid_projectIdFail to find the project dataFaceAuth 프로젝트가 존재하지 않습니다.
invalid_submission_statusThe submission must be approved to process face authenticationKYC submission의 상태가 approved가 아닙니다.
image_converting_errorImage converting error이미지 포맷이 적절하지 않습니다. 이미지 파일을 form-data 형식으로 제출해야 합니다 (base64 포맷 불가).
image_processing_errorImage processing error이미지 데이터 가공 중 오류가 발생했습니다.
detection_server_errorCannot finish process of detecting face얼굴 이미지 비교 검증 모듈에서 오류가 발생했습니다.
no_faceFace is not detected제출된 faceImage에서 얼굴이 감지되지 않았습니다.
data_processing_errorData processing error데이터 조회 및 저장 중 오류가 발생했습니다.