eKYC API

인식할 이미지를 업로드하여 진위 검증까지 한 번에 처리합니다.

요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

메서드	URI
POST	/ekyc

요청 헤더

CLOVA eKYC API에서 공통으로 사용하는 헤더에 대한 정보는 CLOVA eKYC 요청 헤더를 참조해 주십시오.

요청 바디

요청 바디에 대한 설명은 Document API 요청 바디를 참조해 주십시오.

요청 예시

요청 예시는 다음과 같습니다.

사업자등록증

curl --location --request POST 'https://{apigwId}.apigw-pub.fin-ntruss.com/ekyc/v1/{domainId}/{signature}/biz-license/ekyc' \
--header 'X-EKYC-SECRET: {secret-key}' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "request-001",
  "timestamp": 1700000000000,
  "images": [
    {
      "name": "business-license",
      "format": "jpg",      
      "data": "{base64-encoded-image}"
    }
  ]
}'

신분증

curl --location --request POST 'https://{apigwId}.apigw-pub.fin-ntruss.com/ekyc/v1/{domainId}/{signature}/id-card/ekyc' \
--header 'X-EKYC-SECRET: {secret-key}' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "request-002",
  "timestamp": 1700000000000,
  "images": [
    {
      "name": "identification-card",
      "format": "jpg",      
      "data": "{base64-encoded-image}"
    }
  ]
}'

응답

응답 형식을 설명합니다.

응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`requestId`	String	-	사용자가 지정한 요청 ID
`uid`	String	-	시스템에서 생성한 고유 ID
`timestamp`	Integer	-	응답 시간 (Unix Timestamp, 밀리초)
`inferType`	String	-	검증 유형 `ID_CARD` \| `BIZ_LICENSE` `ID_CARD`: 신분증 (주민등록증, 운전면허증, 여권, 외국인등록증) `BIZ_LICENSE`: 사업자등록증 (사업자등록증, 사업자등록증명)
`inferDetailType`	String	-	검증 상세 유형 `IC` \| `DL` \| `PP` \| `AC` \| `BL_CORP` \| `BL_SOLE` \| `BL_CERT_CORP` \| `BL_CERT_SOLE` `IC`: 주민등록증 `DL`: 운전면허증 `PP`: 여권 `AC`: 외국인등록증 `BL_CORP`: 법인 사업자등록증 `BL_SOLE`: 개인 사업자등록증 `BL_CERT_CORP`: 법인 사업자등록증명 `BL_CERT_SOLE`: 개인 사업자등록증명
`result`	String	-	검증 결과 `SUCCESS` \| `FAILURE` `SUCCESS`: 검증 성공 `FAILURE`: 검증 실패
`code`	String	-	검증 실패 시 오류 유형을 구분하기 위한 코드
`message`	String	-	검증 결과 메시지 성공할 경우, `Success` 실패할 경우, 진위 검증 기관의 에러 메시지

응답 상태 코드

CLOVA eKYC API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 CLOVA eKYC 응답 상태 코드를 참조해 주십시오.

응답 예시

응답 예시는 다음과 같습니다.

{
    "requestId": "request-001",
    "uid": "a1b2c3d4e5f6g7h8i9j0k1l2m3",
    "timestamp": 1700000000000,
    "inferType": "ID_CARD",
    "inferDetailType": "PP",
    "result": "SUCCESS",
    "message": "Success"
}