POST/FaceAuth

faceAuth 에 제출한 faceImage와 앞서 진행한 KYC Submission 의 selfie 이미지 또는 idCard 이미지(selfie option 미 사용시)를 비교합니다.

• 옵션 사용 여부 및 임계치에 따라 인증 결과(approved <> rejected) 를 반환합니다.

• faceAuth 를 진행하기 위해선 KYC submission 의 ‘approved’ 가 반드시 전제되어야 합니다.

• faceAuth submission 은 기존 KYC Project 하위의 FaceAuth Project 에 종속됩니다.

• 반드시 faceAuth 전용 API Key 를 사용하여 요청을 보내야 합니다.

• 옵션 사용여부 및 각 임계치(Threshold)는 대시보드 내 faceAuth project 상세 화면에서 설정 및 변경할 수 있습니다.

• 제출된 KYC 데이터(submission)의 상세 정보는 대시보드(https://admin.argoskyc.com)에서 확인 할 수 있습니다.

• face auth 는 Body /form-data 형식으로 제출하는 것을 권장합니다.

• faceImage의 표준 권장 사양은 960 x 720 입니다.

Input data

Face Auth 를 제출하기 위해 필요한 매개변수들에 대해 설명 합니다.

• submissionId, faceImage 는 필수로 입력해야 하는 매개변수 입니다.

• userId, cf1, cf2, cf3 는 선택적 매개변수 입니다. (Liveform을 이용할 경우 Query String 양식에 맞추어서 입력해주세요.)

Parameter	Format	requirement	Description
submissionId	string	*required	KYC Submission Id 를 입력합니다. face auth 는 KYC 결과가 approved 인 경우에만 진행 가능합니다.
faceImage	file	*required	사용자의 셀피 이미지를 파일로 입력합니다. 만일 PPE(head cover, face cover) 옵션을 이용한다면 사용자가 안전장비가 이미지에 모두 담겨야 정확한 인식이 가능합니다.
userId	string	optional	필요 시, 회사 내부에서 자체적으로 사용하는 사용자 ID를 입력합니다.
cf1	string	optional
cf2	string	optional
cf3	string	optional

Output Data

Face Auth 제출 완료 시 조회 되는 데이터 목록입니다.

Property	Format	Description
authentication_id	string	face auth 제출건에 대한 각각의 고유한 ID 입니다.
auth_status	string	face auth 최종 결과입니다. approved(성공) 또는 rejected(실패) 를 반환합니다.
score	object	사용 옵션에 따른 인식 결과의 score 를 반환합니다. 옵션에 따라 "face_similarity_score", "occluded_score", "face_cover_socre", "head_cover_socre" 프로퍼티를 포함할 수 있습니다.
create_time	string	face auth를 제출한 시각입니다.
fail_code	Array	rejected 시, 실패 코드를 반환합니다.
rejected_comment	Array	rejected 시, 실패 원인에 대한 상세 메세지를 반환합니다.

Fail Codes (200 Rejected)

fail_code	rejected_comment	description
face_compare_underscore	face compare similarity score is lower than threshold	얼굴 유사도 점수가 임계치 보다 낮을 경우
Face_Occluded_fail	face is occluded	얼굴이 가려져있는 경우
Face_cover_fail	Protection equipment is not found on Face	안면에 보호구가 인식되지 않은 경우
Head_cover_fail	Protection equipment is not found on Head	머리에 보호구가 인식되지 않은 경우

Error Codes (400 error)

Face Auth 에서 제출에 실패가 되면 실패한 이유에 대한 에러 코드와 함께 메세지가 제공됩니다.

error_code	Message	description
invalid_data_format	data parsing error. please check input data	input parameter 형식이 부적절한 경우. 데이터 포맷을 확인해주세요
required_field_missing	required field is missing	required parameter 가 누락된 경우. 필수 파라미터 2가지와 api key를 확인해주세요.
Invalid_submissionId	Fail to find the submission data	kyc submission 이 존재하지 않는 경우
Invalid_projectId	Fail to find the project data	faceAuth project 가 존재하지 않는 경우
invalid_submission_status	The submission must be approved to process face authentication	kyc submission 의 인증 상태가 ‘approved’ 가 아닌 경우
image_converting_error	image converting error	이미지 포맷이 적절하지 않은 경우. 이미지 파일을 form-data 로 제출 (base64 포맷)
image_processing_error	image processing error	이미지 데이터 가공 중 에러가 발생한 경우
detection_server_error	cannot finished process of detecting face	얼굴 이미지 비교 검증 모듈에 에러가 발생한 경우
no_face	face is not detected	제출한 faceImage 에서 얼굴이 인식되지 않은 경우
data_processing_error	data processing error	데이터 조회 및 저장 중 에러가 발생한 경우

Request URL

Face Auth를 제출하는 방법에 대해 설명 합니다.

• URL과 x-api-key를 반드시 입력해 주어야 합니다.

curl -X POST "https://rest-api.argoskyc.com/v3/faceauth" \
-H "x-api-key: {yourAPIKey}" \

Sample Request

KYC 진행 후 KYC 데이터의 고유 식별 ID(submissionId)를 반드시 입력해야 하며, 해당 KYC submission는 반드시 ‘approved’ 상태여야 합니다.

• submissionId, faceImage 입력 데이터를 필수로 요구합니다.

• 입력 데이터는 포맷에 맞춰 입력 되어야 합니다.

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

Sample Response - Approved

{
    "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
    }
}

Sample Response - Rejected

{
    "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.",
    ]
}