Verify API

Document API 응답 결과로 신분증 또는 사업자등록증에 대한 진위를 검증합니다.

요청

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

메서드	URI
POST	/verify/{inferDetailTypeResource}

요청 헤더

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

요청 경로 파라미터

파라미터에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`inferDetailTypeResource`	String	Required	검증하려는 문서 유형 `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`: 개인 사업자등록증명

요청 바디

요청 바디에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`requestId`	String	Required	API 호출 ID Document API 요청 시 사용했던 `requestId`로 10분간 호출 가능
`data`	Array	Required	검증 요청 데이터: data 검증 상세 타입별로 상이 주민등록증 운전면허증 여권 외국인등록증 사업자등록증 기본적으로 문서의 OCR 결과를 API에서 파싱하여 검증에 사용 현재 1개의 데이터만 처리 가능 (추후 개선 예정) 요청값은 Document API 응답과 동일한 필드명 사용

`data`

data에 대한 설명은 다음과 같습니다.

주민등록증

필드	타입	필수 여부	설명
`name`	String	Required	이름
`personalNum`	String	Required	주민등록번호
`issueDate`	String	Required	발급 일자

운전면허증

필드	타입	필수 여부	설명
`name`	String	Required	이름
`personalNum`	String	Required	생년월일 (주민등록번호 앞 6자리)
`num`	String	Required	운전면허번호
`code`	String	Required	암호일련번호 위조 방지를 위한 숫자, 6자리 번호 (숫자와 영문 혼합) 또는 6자리 번호 (숫자 4자리, 영문 2자) Document API 참조
`skipCodeCheck`	Boolean	Optional	암호일련번호 검증 제외 여부 `true` \| `false` (기본값) `true`: 코드값과 관계없이 면허 정보만 검증 `false`: 암호일련번호 검증

여권

필드	타입	필수 여부	설명
`fullNameKor`	String	Required	한글 이름 영문 이름 검증은 현재 지원하지 않음
`num`	String	Required	여권 번호
`birthDate`	String	Required	생년월일
`issueDate`	String	Required	발급 일자
`expireDate`	String	Required	만료 일자

외국인등록증

필드	타입	필수 여부	설명
`alienRegNum`	String	Required	외국인등록번호
`issueDate`	String	Required	발급 일자
`serialNum`	String	Required	일련번호 신분증 후면에 별도 기재되어 인식 불가

사업자등록증

필드	타입	필수 여부	설명
`registerNumber`	String	Required	사업자등록번호 사업자의 진위 검증은 사업자등록번호로만 진행

요청 예시

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

주민등록증

curl --location --request POST 'https://{apigwId}.apigw-pub.fin-ntruss.com/ekyc/v1/{domainId}/{signature}/id-card/verify/ic' \
--header 'X-EKYC-SECRET: {secret-key}' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "request-001",
  "data": [
    {
      "name": "홍길동",    
      "personalNum": "111111-1234567",
      "issueDate": "2012. 6. 1"
    }
  ]
}

운전면허증

curl --location --request POST 'https://{apigwId}.apigw-pub.fin-ntruss.com/ekyc/v1/{domainId}/{signature}/id-card/verify/dl' \
--header 'X-EKYC-SECRET: {secret-key}' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "request-002",
  "data": [
    {
      "name": "홍길동",    
      "personalNum": "111111",
      "num": "11-11-111111-11",  
      "code": "7U86P",
      "skipCodeCheck": true
    }
  ]
}

여권

curl --location --request POST 'https://{apigwId}.apigw-pub.fin-ntruss.com/ekyc/v1/{domainId}/{signature}/id-card/verify/pp' \
--header 'X-EKYC-SECRET: {secret-key}' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "request-003",
  "data": [
    {
      "birthDate": "01 FEB 2022",
      "expireDate": "11 NOV 2031",
      "fullNameKor": "홍길동",
      "issueDate": "11 NOV 2021",
      "num": "M0000000"
    }
  ]
}'

외국인등록증

curl --location --request POST 'https://{apigwId}.apigw-pub.fin-ntruss.com/ekyc/v1/{domainId}/{signature}/id-card/verify/pp' \
--header 'X-EKYC-SECRET: {secret-key}' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "request-004",
  "data": [
    {
      "alienRegNum": "123456-1234567",
      "issueDate": "2021.11.11",
      "serialNum": "01234567890"
    }
  ]
}'

사업자등록증

curl --location --request POST 'https://{apigwId}.apigw-pub.fin-ntruss.com/ekyc/v1/{domainId}/{signature}/biz-license/verify/bl-corp' \
--header 'X-EKYC-SECRET: {secret-key}' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "request-005",
  "data": [
    {
      "registerNumber": "1234567890"
    }
  ]
}'

응답

응답 형식을 설명합니다.

응답 바디

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

필드	타입	필수 여부	설명
`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": "DL",
    "result": "SUCCESS",
    "message": "Success"
}