> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # 신분증 인증 API: 문서 OCR 및 진위 확인 > Didit는 220개 이상 국가, 14,000종 이상의 신분증을 인증합니다. 진위 확인, OCR, MRZ, 2초 미만 추론, 사용량 기반 요금, 계약 불필요. ## OpenAPI ````yaml ko/openapi-25.json POST /v3/id-verification/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: 신분증 인증 API입니다. x-api-key 헤더로 인증합니다. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/id-verification/: post: tags: - Standalone APIs summary: 신분증 인증 (문서 OCR + 사기 확인) description: >- 한 번의 호출로 신분증 문서를 OCR하고 문서 사기 검사를 실행합니다. 추출된 소지자 필드, 파싱된 MRZ, `Approved`/`Declined`/`In Review` `status`, 발견된 모든 문제를 설명하는 `warnings` 목록을 반환합니다. 220+개 국가 및 지역의 14,000+개 문서 유형을 지원합니다. **작동 방식.** 문서의 `front_image`(필수)와 양면 문서의 경우 `back_image`를 전송합니다. 문서의 네 모서리가 모두 보이는 자르지 않은 사진을 업로드하세요. 서비스가 문서를 직접 감지하고 정렬한 후 자르므로 미리 자르지 마십시오. 문서는 자동으로 분류되며(국가나 문서 유형을 직접 선언할 필요가 없음), 시각 영역은 OCR로 판독되고, MRZ 및 모든 바코드가 디코딩됩니다. 그런 다음 교차 검증을 통해 날짜, 번호 형식, MRZ 검사 숫자의 유효성을 확인하고 시각 영역과 MRZ를 비교합니다. `perform_document_liveness=true`인 경우 이미지를 추가로 검사하여 화면 재생, 인쇄된 사본, 인물 사진 변조 여부를 확인합니다. **결정 로직.** 적어도 하나의 경고가 거부로 처리되는 경우를 제외하면 `status`는 `Approved`입니다. 사기 및 중대한 실패 위험은 항상 거부됩니다: `DOCUMENT_EXPIRED`, `SCREEN_CAPTURE_DETECTED`, `PRINTED_COPY_DETECTED`, `PORTRAIT_MANIPULATION_DETECTED`, `PUBLIC_DOCUMENT_IMAGE_DETECTED` 및 추출 실패(`NAME_NOT_DETECTED`, `DATE_OF_BIRTH_NOT_DETECTED`, `DOCUMENT_NUMBER_NOT_DETECTED`). (`PORTRAIT_IMAGE_NOT_DETECTED`, `INVALID_DATE`, `MRZ_NOT_DETECTED`는 워크플로 세션에 존재하지만 이 독립 실행형 endpoint에서는 생성되지 않습니다. `COULD_NOT_DETECT_DOCUMENT_TYPE`은 앞면 이미지가 높은 신뢰도로 알려진 공식 문서 디자인과 일치하지 않을 때 여기서 반환되며 요청을 거부합니다.) 세 가지 위험 그룹은 `invalid_mrz_action`, `inconsistent_data_action`, `expiration_date_not_detected_action`을 통해 요청별로 설정할 수 있습니다(`DECLINE` 또는 `NO_ACTION`). 다른 모든 경고(예: `POSSIBLE_DUPLICATED_USER`)는 정보 제공용이며 그 자체로 거부되지 않습니다. `perform_document_liveness=true`(기본값)이고 위조 검사에서 사용 가능한 점수를 반환하지 않는 경우(공급자 실패, 200 외 응답, 또는 `status="ERR"`인 HTTP 200 응답) 호출은 `Approved` 대신 `status: "In Review"` 및 `DOCUMENT_LIVENESS_NOT_COMPUTED` 경고(`log_type: "warning"`)와 함께 `200`을 반환합니다. 실행되지 않은 검사는 문서가 진짜라는 증거가 되지 않기 때문입니다. 이 에스컬레이션은 설정할 수 없으며 `Declined`를 절대 재정의하지 않습니다. `perform_document_liveness=false`인 경우 해당 검사는 건너뛰고 상태는 이전과 같이 나머지 경고를 따릅니다. 전혀 처리할 수 없는 문서는 `{"error": "COULD_NOT_RECOGNIZE_DOCUMENT"}`와 함께 `400`을 반환합니다. 판독할 수 있지만 문제가 있는 문서는 `status: "Declined"`와 함께 `200`을 반환하므로, HTTP 코드뿐만 아니라 항상 `id_verification.status` 및 `id_verification.warnings`를 확인하세요. **결제.** 각 `200` 응답은 신분증 인증 API 크레딧 1개를 소모합니다(요금제 크레딧 또는 충전 잔액에서 차감). 조직의 잔액으로 호출 비용을 충당할 수 없는 경우 endpoint는 이미지 처리가 시작되기 전에 크레딧 부족 오류와 함께 `403`을 반환합니다. **세션 지속성(`save_api_request`, 기본값 `true`).** `true`인 경우 호출은 API 유형 세션으로 유지됩니다. Business Console에 표시되고, 반환된 `request_id`는 `GET /v3/session/{sessionId}/decision/`에 전달할 수 있는 실제 세션 ID이며, 잘라낸 문서/인물 사진 이미지가 저장되어 수명이 짧은 미디어 URL(`https:///ocr/...`)로 반환되고, 설정된 webhook endpoint로 `status.updated` webhook이 전송됩니다. `false`인 경우 아무것도 저장되지 않고, `request_id`는 일회성 연관 UUID이며, `portrait_image`/`front_image`/`back_image`는 base64로 인코딩된 JPEG 문자열로 인라인 반환됩니다. **샌드박스.** 샌드박스 API 키는 모든 처리 및 결제를 건너뜁니다. 요청 검증 후(잘못된 형식의 입력은 여전히 `400` 반환) endpoint는 정적 `Approved` 모의 payload(가상의 "Sandbox User" 미국 신분증)를 반환하며, 세션은 유지되지 않고 크레딧도 소모되지 않습니다. **인증.** 애플리케이션의 API 키를 `x-api-key` 헤더에 담아 전송하세요. 자격 증명이 누락되었거나 유효하지 않은 경우 `403`(`{"detail": "You do not have permission to perform this action."}`)을 반환하며, 이 API는 절대 `401`을 반환하지 않습니다. **속도 제한.** 모든 POST/PATCH/DELETE endpoint에 걸쳐 API 키당 300건/분의 공유 쓰기 예산이 적용되며, 초과 시 `429`가 반환됩니다. operationId: post_v3id-verification parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - front_image properties: front_image: type: string format: binary description: >- 신분증 앞면입니다. 허용되는 확장자: `tiff`, `jpg`, `jpeg`, `png`, `webp`, `pdf`. 최대 업로드 크기: **10 MB**(더 큰 파일은 `400` 오류로 거부됨). PDF는 OCR 전에 이미지로 렌더링되며, 암호화된 PDF는 `front_image_password`가 필요합니다. 이미지는 자동으로 ~0.5 MB로 압축되고 EXIF 방향이 적용됩니다. 문서의 네 모서리가 모두 보이는 잘리지 않은 전체 캡처본을 업로드하세요. front_image_password: type: string description: >- `front_image`가 암호화된 PDF인 경우 복호화하기 위한 비밀번호입니다. 비밀번호 없이(또는 잘못된 비밀번호로) 암호화된 PDF를 전송하면 `400`이 반환됩니다. writeOnly: true back_image: type: string format: binary description: >- 문서의 뒷면입니다. 문서에 뒷면이 있는 경우 항상 전송하십시오(많은 신분증은 뒷면에 MRZ나 바코드가 있습니다. 뒷면을 생략하면 응답에서 MRZ 및 뒷면 필드가 비어 있게 되며, 이 endpoint는 MRZ 누락 경고를 발생시키지 않습니다). `front_image`와 동일한 형식 및 크기 제한이 적용됩니다. 생략된 경우 응답의 `back_image` 및 뒷면 필드는 `null`이 됩니다. back_image_password: type: string description: '`back_image`가 암호화된 PDF인 경우 복호화하기 위한 비밀번호입니다.' writeOnly: true perform_document_liveness: type: boolean default: true description: >- 두 이미지 모두에서 프레젠테이션 부정행위를 스크리닝합니다. 화면 재생(`SCREEN_CAPTURE_DETECTED`), 인쇄된 사본(`PRINTED_COPY_DETECTED`), 인물 사진 조작(`PORTRAIT_MANIPULATION_DETECTED`)을 감지합니다. 이 중 하나라도 해당되면 자동으로 거부됩니다. 기본적으로 활성화되어 있으며, 사기 스크리닝을 건너뛰고 지연 시간을 줄이려면 `false`로 설정하십시오. 활성화된 상태에서 공급자가 사용 가능한 점수를 반환하지 않으면 응답은 `Approved` 대신 `DOCUMENT_LIVENESS_NOT_COMPUTED` 경고와 함께 `In Review`가 됩니다. example: true minimum_age: type: integer nullable: true default: null minimum: 1 maximum: 120 description: >- 허용 및 유효성 검사(1–120)가 수행되지만 이 endpoint에서는 **현재 적용되지 않음** — 이 필드에서는 `MINIMUM_AGE_NOT_MET` 경고가 생성되지 않습니다. 반환된 `date_of_birth`/`age`를 기반으로 연령 규칙을 적용하거나 연령 제한이 있는 인증 세션 워크플로를 사용하십시오. expiration_date_not_detected_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- 만료일을 읽을 수 없을 때(`EXPIRATION_DATE_NOT_DETECTED`) 수행할 작업입니다. 상당수의 신분증에 만료일이 인쇄되어 있지 않으므로 기본값은 `NO_ACTION`입니다. 참고: 이 옵션과 관계없이 *감지되었으나 이미 지난* 만료일은 항상 거부됩니다(`DOCUMENT_EXPIRED`). invalid_mrz_action: type: string enum: - NO_ACTION - DECLINE default: DECLINE description: >- 추출된 MRZ가 체크 디지트 유효성 검사에 실패할 때 수행할 작업입니다 (`MRZ_VALIDATION_FAILED`). MRZ가 누락된 경우 이 endpoint에서는 경고가 발생하지 않습니다. MRZ가 포함된 문서에만 해당합니다. 이 endpoint에서는 `REVIEW`가 지원되지 않으며 `400`을 반환합니다. inconsistent_data_action: type: string enum: - NO_ACTION - DECLINE default: DECLINE description: >- 추출된 데이터 내부에 불일치가 있을 때 수행할 작업입니다: `DATA_INCONSISTENT`, `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME`(시각적 영역과 MRZ 불일치) 또는 `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS`. critical_field_occlusion_action: type: string enum: - NO_ACTION - DECLINE default: DECLINE description: >- 촬영본에서 식별 번호, 이름, 생년월일 또는 만료일과 같은 중요한 인쇄 필드가 물리적으로 가려진 경우(`CRITICAL_FIELD_OCCLUSION_DETECTED`) 수행할 작업입니다. 이 endpoint의 다른 문서 무결성 위험과 마찬가지로 기본적으로 거부됩니다. 보고서 대조에 필요한 번호를 가리는 것은 수정(redact)된 문서의 전형적인 형태이기 때문입니다. 가려진 필드에서 읽은 값은 추출 결과에서 제외되므로, 일반적으로 일치하는 `*_NOT_DETECTED` 경고가 함께 동반됩니다. 이 endpoint에서는 `REVIEW`가 지원되지 않으며 `400`을 반환합니다. document_or_personal_number_format_mismatch_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- 번호가 해당 문서 유형에 대해 발급 기관이 사용하는 형식과 일치하지 않을 때(`DOCUMENT_NUMBER_FORMAT_MISMATCH`, `PERSONAL_NUMBER_FORMAT_MISMATCH`) 수행할 작업입니다. 기본값은 `NO_ACTION`으로, 상태를 변경하지 않고 경고만 보고합니다. 이 endpoint에서는 `REVIEW`가 지원되지 않으며 `400`을 반환합니다. preferred_characters: type: string enum: - latin - non_latin default: latin description: >- 라틴 문자와 비라틴 문자(아랍어, 키릴 자모, CJK 등)가 모두 인쇄된 문서의 성명/주소 필드에 선호하는 문자 체계입니다. `latin`은 음차/라틴 문자로 표기된 값을 반환하고, `non_latin`은 현지 고유 문자 체계를 우선합니다. save_api_request: type: boolean default: true description: >- `true`(기본값)인 경우 호출을 API 유형 세션으로 저장합니다. Business Console에서 확인할 수 있고 반환된 `request_id`를 사용하여 `GET /v3/session/{sessionId}/decision/`을 통해 조회할 수 있으며 `status.updated` webhook을 통해 알림이 전송되고 문서 이미지가 미디어 URL로 반환됩니다. `false`인 경우 아무것도 저장되지 않고 `request_id`는 일시적인 UUID이며 이미지는 base64 JPEG 문자열로 인라인 반환됩니다. example: true vendor_data: type: string description: >- 저장된 세션에 저장되고 응답에 다시 반환되는 선택적 불투명 문자열(내부 사용자 ID, 이메일, UUID 등)입니다. API 호출을 자체 기록과 연관 짓고 나중에 세션을 필터링하는 데 사용합니다. example: user-123 metadata: type: object additionalProperties: true description: >- 세션과 함께 저장되고(`save_api_request=true`인 경우) 응답에 그대로 반환되는 선택적 JSON 객체입니다. multipart 요청에서는 JSON 인코딩된 문자열 필드(예: `metadata={"flow":"onboarding"}`)로 전송하십시오. 객체로 파싱됩니다. example: flow: onboarding example: front_image: (binary JPEG/PNG/PDF of the document front) back_image: (binary JPEG/PNG/PDF of the document back) perform_document_liveness: true save_api_request: true vendor_data: user-123 metadata: flow: onboarding responses: '200': description: >- 문서가 처리되었습니다. `id_verification.status`는 `Approved`, `Declined` 또는 `In Review`입니다. 감지된 모든 문제는 `id_verification.warnings`에 항목별로 나열됩니다. 요청된 문서 라이브니스 검사에서 사용 가능한 결과가 생성되지 않은 경우(`DOCUMENT_LIVENESS_NOT_COMPUTED`) `In Review`가 반환됩니다. 문제가 있는 문서라도 `status: "Declined"`와 함께 `200`을 반환하므로 HTTP 코드뿐만 아니라 본문도 검사해야 합니다. `save_api_request=true`인 경우 `request_id`는 저장된 세션 ID이고 이미지 필드는 수명이 짧은 미디어 URL입니다. `save_api_request=false`인 경우 인라인 base64 JPEG 문자열입니다. content: application/json: examples: Approved: summary: 양면 신분증이 문제없이 판독됨(저장됨 — 이미지는 미디어 URL로 제공) value: request_id: 11d219ed-d59c-4b1d-8d65-9b933f12d5b8 id_verification: status: Approved document_type: Identity Card document_subtype: ID_CARD_GENERIC document_number: CBX164224 personal_number: 20446581H portrait_image: >- https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-portrait_image-8c2f.jpg?signature=... front_image: >- https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-front_image-4a1e.jpg?signature=... back_image: >- https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-back_image-77b0.jpg?signature=... front_image_camera_front: null back_image_camera_front: null front_image_camera_front_face_match_score: null back_image_camera_front_face_match_score: null front_image_quality_score: focus_score: 78 brightness_score: 83.2 brightness_issue: ok is_document_fully_visible: true resolution_score: 40.7 overall_score: 70.2 back_image_quality_score: focus_score: 100 brightness_score: 95.6 brightness_issue: ok is_document_fully_visible: true resolution_score: 43 overall_score: 84.4 date_of_birth: '1980-01-13' age: 46 expiration_date: '2032-03-31' date_of_issue: '2022-03-31' issuing_state: ESP issuing_state_name: Spain first_name: Julio Francisco last_name: Fores Sena full_name: Julio Francisco Fores Sena gender: M address: >- Brda. Urb. El Cardonal 0052 52 Po3 B,Taco,San Cristobal De La Laguna,Santa Cruz De Tenerife formatted_address: >- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain place_of_birth: Valencia, Valencia marital_status: UNKNOWN nationality: ESP extra_fields: first_surname: Fores second_surname: Sena mrz: surname: FORES SENA name: JULIO FRANCISCO country: ESP nationality: ESP birth_date: '800113' expiry_date: '320331' sex: M document_type: ID document_number: CBX164224 optional_data: 20446581H optional_data_2: '' birth_date_hash: '9' expiry_date_hash: '8' document_number_hash: '3' final_hash: '3' personal_number: 20446581H warnings: [] errors: [] mrz_type: TD1 mrz_string: |- IDESPCBX164224320446581H<<<<<< 8001139M3203318ESP<<<<<<<<<<<3 FORES- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain raw_results: address_components: - long_name: b short_name: b types: - subpremise - long_name: '52' short_name: '52' types: - street_number - long_name: Avenida el Cardonal short_name: Av. el Cardonal types: - route - long_name: La Laguna short_name: La Laguna types: - locality - political - long_name: Spain short_name: ES types: - country - political - long_name: '38108' short_name: '38108' types: - postal_code formatted_address: >- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain geometry: location: lat: 28.4501161 lng: -16.3004407 location_type: ROOFTOP types: - street_address - subpremise document_location: latitude: 28.4501161 longitude: -16.3004407 label: Spain Identity Card Address is_verified: true category: Residential warnings: [] barcodes: [] vendor_data: user-123 metadata: flow: onboarding created_at: '2026-06-12T02:21:56.013573+00:00' Declined - expired document: summary: 만료된 신분증의 앞면만 업로드 value: request_id: f61681b8-9422-4378-ac3e-04c6a247fb45 id_verification: status: Declined document_type: Identity Card document_subtype: ID_CARD_GENERIC document_number: BNK123072 personal_number: 21771255F portrait_image: >- https:///ocr/f61681b8-9422-4378-ac3e-04c6a247fb45-portrait_image-1d9a.jpg?signature=... front_image: >- https:///ocr/f61681b8-9422-4378-ac3e-04c6a247fb45-front_image-5c2b.jpg?signature=... back_image: null front_image_camera_front: null back_image_camera_front: null front_image_camera_front_face_match_score: null back_image_camera_front_face_match_score: null front_image_quality_score: focus_score: 100 brightness_score: 95.7 brightness_issue: ok is_document_fully_visible: true resolution_score: 22.2 overall_score: 79.3 back_image_quality_score: null date_of_birth: '1997-01-30' age: 29 expiration_date: '2025-11-26' date_of_issue: null issuing_state: ESP issuing_state_name: Spain first_name: Lucia last_name: Marin Castro full_name: Lucia Marin Castro gender: F address: null formatted_address: null place_of_birth: null marital_status: UNKNOWN nationality: ESP extra_fields: first_surname: Marin second_surname: Castro mrz: {} parsed_address: null warnings: - risk: DOCUMENT_EXPIRED feature: ID_VERIFICATION additional_data: null log_type: error short_description: Document expired long_description: >- The document's expiration date has passed, rendering it no longer valid for use. barcodes: [] vendor_data: user-123 metadata: null created_at: '2026-06-12T02:25:48.117204+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- `save_api_request=true`일 때 유지된 세션 ID(`GET /v3/session/{sessionId}/decision/`와 함께 사용 가능), 그렇지 않으면 임시 상관관계 UUID입니다. id_verification: type: object properties: status: type: string enum: - Approved - Declined - In Review description: >- 어떤 경고도 거부로 이어지지 않고 요청된 문서 라이브니스 검사에서 사용 가능한 결과가 도출된 경우 `Approved`, 해당 요청 검사에서 사용 가능한 결과가 도출되지 않은 경우(`DOCUMENT_LIVENESS_NOT_COMPUTED`) `In Review`, 경고가 거부로 이어지는 경우 `Declined`가 됩니다. `warnings` 목록에 이유가 설명되어 있습니다. document_type: type: string nullable: true description: >- 감지된 문서 유형 표시 이름: `Identity Card`, `Passport`, `Driver's License`, `Residence Permit`, `Health Insurance Card` 또는 `Tax Card`. 문서를 분류할 수 없는 경우 `null`입니다. example: Identity Card document_subtype: type: string nullable: true description: >- 사용 가능한 경우 세부 하위 유형(예: `ID_CARD_GENERIC`, `EPASSPORT`)입니다. example: ID_CARD_GENERIC document_number: type: string nullable: true example: CBX164224 personal_number: type: string nullable: true description: 일부 문서에 인쇄된 보조 개인/국가 식별 번호. example: 20446581H portrait_image: type: string nullable: true description: >- 문서에서 잘라낸 인물 사진입니다. `save_api_request=true`(기본값)인 경우 유효 기간이 짧은 미디어 URL(`https:///ocr/...`)이며, `save_api_request=false`인 경우 인라인 base64 인코딩 JPEG 문자열입니다. 감지된 인물 사진이 없으면 `null`입니다. front_image: type: string nullable: true description: >- 정렬되어 잘라낸 문서 앞면 이미지입니다. 저장된 경우 미디어 URL이며, 그렇지 않은 경우 인라인 base64 JPEG입니다. back_image: type: string nullable: true description: >- 정렬되어 잘라낸 문서 뒷면 이미지입니다. `back_image`가 업로드되지 않은 경우 `null`입니다. front_image_camera_front: type: string nullable: true description: 이 endpoint에서는 항상 `null`입니다(카메라 캡처 인증 세션에서만 채워짐). back_image_camera_front: type: string nullable: true description: 이 endpoint에서는 항상 `null`입니다. front_image_camera_front_face_match_score: type: number nullable: true description: 이 endpoint에서는 항상 `null`입니다. back_image_camera_front_face_match_score: type: number nullable: true description: 이 endpoint에서는 항상 `null`입니다. front_image_quality_score: type: object nullable: true description: >- 업로드된 이미지의 촬영 품질 진단 정보(해당 면이 제공되지 않았거나 점수 산정에 실패한 경우 `null`). 모든 점수는 0–100입니다. properties: focus_score: type: number format: float description: 문서 크롭 영역의 선명도입니다(높을수록 더 선명함). brightness_score: type: number format: float description: 노출 품질(높을수록 좋음). brightness_issue: type: string nullable: true description: >- 노출이 적절한 경우 `ok`이며, 그렇지 않은 경우 감지된 문제(예: 너무 어두움 / 너무 밝음)가 표시됩니다. is_document_fully_visible: type: boolean nullable: true description: 문서의 네 모서리가 모두 프레임 안에 있는지 여부입니다. resolution_score: type: number format: float description: 문서 영역의 유효 해상도입니다. overall_score: type: number format: float description: 종합 품질 점수입니다. back_image_quality_score: type: object nullable: true description: >- 업로드된 이미지의 촬영 품질 진단 정보(해당 면이 제공되지 않았거나 점수 산정에 실패한 경우 `null`). 모든 점수는 0–100입니다. properties: focus_score: type: number format: float description: 문서 크롭 영역의 선명도입니다(높을수록 더 선명함). brightness_score: type: number format: float description: 노출 품질(높을수록 좋음). brightness_issue: type: string nullable: true description: >- 노출이 적절한 경우 `ok`이며, 그렇지 않은 경우 감지된 문제(예: 너무 어두움 / 너무 밝음)가 표시됩니다. is_document_fully_visible: type: boolean nullable: true description: 문서의 네 모서리가 모두 프레임 안에 있는지 여부입니다. resolution_score: type: number format: float description: 문서 영역의 유효 해상도입니다. overall_score: type: number format: float description: 종합 품질 점수입니다. date_of_birth: type: string format: date nullable: true example: '1980-01-13' age: type: integer nullable: true description: '`date_of_birth`를 기준으로 계산된 명의자의 만 나이입니다.' example: 46 expiration_date: type: string format: date nullable: true example: '2032-03-31' date_of_issue: type: string format: date nullable: true example: '2022-03-31' issuing_state: type: string nullable: true description: 발급 국가(ISO 3166-1 alpha-3)입니다. example: ESP issuing_state_name: type: string nullable: true example: Spain first_name: type: string nullable: true example: Julio Francisco last_name: type: string nullable: true example: Fores Sena full_name: type: string nullable: true example: Julio Francisco Fores Sena gender: type: string nullable: true description: 인쇄/감지되지 않은 경우 `M`, `F` 또는 `null`. example: M address: type: string nullable: true description: 문서에 인쇄된 그대로의 주소입니다. formatted_address: type: string nullable: true description: '`address`의 지오코딩되고 정규화된 버전입니다.' place_of_birth: type: string nullable: true example: Valencia, Valencia marital_status: type: string nullable: true description: 문서에 혼인 여부가 인쇄되어 있지 않은 한 `UNKNOWN`입니다. example: UNKNOWN nationality: type: string nullable: true description: 명의자 국적(ISO 3166-1 alpha-3)입니다. example: ESP extra_fields: type: object nullable: true additionalProperties: true description: >- 전용 열이 없는 문서별 추가 항목입니다(예: 스페인 신분증의 `first_surname`/`second_surname`, 운전면허증의 면허 종별). mrz: type: object description: >- 파싱된 기계 판독 영역입니다. 문서에 MRZ가 없거나 읽을 수 없는 경우 **빈 객체**(`{}`)가 반환되며, 이 경우 `warnings` 목록도 확인하십시오. MRZ 내부의 날짜는 원본 `YYMMDD` 형식을 사용합니다. properties: surname: type: string example: FORES SENA name: type: string example: JULIO FRANCISCO country: type: string description: 발급 국가(ISO 3166-1 alpha-3)입니다. example: ESP nationality: type: string description: 명의자 국적(ISO 3166-1 alpha-3)입니다. example: ESP birth_date: type: string description: MRZ의 원시 생년월일(`YYMMDD`)입니다. example: '800113' expiry_date: type: string description: MRZ의 원시 만료일(`YYMMDD`)입니다. example: '320331' sex: type: string example: M document_type: type: string description: 'MRZ 문서 유형 코드(예: `ID`, `P`).' example: ID document_number: type: string example: CBX164224 optional_data: type: string nullable: true example: 20446581H optional_data_2: type: string nullable: true example: '' birth_date_hash: type: string description: 생년월일에 대한 MRZ 체크 디지트. example: '9' expiry_date_hash: type: string description: 만료일에 대한 MRZ 체크 디지트. example: '8' document_number_hash: type: string description: 문서 번호에 대한 MRZ 체크 디지트. example: '3' final_hash: type: string description: 복합 MRZ 체크 디지트입니다. example: '3' personal_number: type: string nullable: true example: 20446581H warnings: type: array items: type: string description: 치명적이지 않은 MRZ 파싱 경고. errors: type: array items: type: string description: >- MRZ 체크 디지트/파싱 오류. 오류가 비어 있지 않으면 `MRZ_VALIDATION_FAILED` 경고로 나타납니다. mrz_type: type: string description: 'MRZ 레이아웃: `TD1`(신분증, 3줄), `TD2` 또는 `TD3`(여권, 2줄).' example: TD1 mrz_string: type: string description: 판독된 원시 MRZ 텍스트이며, 줄은 `\n`으로 구분됩니다. mrz_key: type: string description: 교차 확인에 사용되는 복합 키(문서 번호 + 체크 디지트)입니다. parsed_address: type: object nullable: true description: >- `address`의 구조화된 지오코딩 세부 정보입니다. 문서에 주소가 없거나 파싱할 수 없는 경우 `null`입니다. properties: street_1: type: string nullable: true example: Avenida el Cardonal 52 street_2: type: string nullable: true example: b city: type: string nullable: true example: La Laguna region: type: string nullable: true example: Canarias country: type: string nullable: true description: ISO 3166-1 alpha-2 국가 코드입니다. example: ES postal_code: type: string nullable: true example: '38108' address_type: type: string nullable: true example: Avenida formatted_address: type: string nullable: true description: 표준 지오코딩 주소 문자열입니다. example: >- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain raw_results: type: object additionalProperties: true description: >- 고급 소비자를 위한 원시 지오코딩 payload(`address_components`, `geometry.location`, `place_id`, …)입니다. document_location: type: object nullable: true properties: latitude: type: number longitude: type: number description: 문서 주소의 지오코딩된 좌표입니다. label: type: string nullable: true description: 주소를 읽어온 문서 필드입니다. example: Spain Identity Card Address is_verified: type: boolean description: 지오코딩을 통해 주소가 존재하는 것으로 확인되었는지 여부입니다. category: type: string nullable: true description: '주소 카테고리(예: `Residential`, `Commercial`).' example: Residential warnings: type: array description: >- 문제없이 승인된 경우 비어 있습니다. 각 항목은 감지된 하나의 위험을 설명합니다. `log_type: "error"`인 항목은 `status`를 `Declined`로 설정하고, `DOCUMENT_LIVENESS_NOT_COMPUTED`(`log_type: "warning"`)는 `In Review`로 설정합니다. items: type: object properties: risk: type: string description: >- 기계 판독 가능한 위험 코드입니다. 항상 거부되는 위험: `DOCUMENT_EXPIRED`, `MINIMUM_AGE_NOT_MET`, `PORTRAIT_IMAGE_NOT_DETECTED`, `SCREEN_CAPTURE_DETECTED`, `PRINTED_COPY_DETECTED`, `PORTRAIT_MANIPULATION_DETECTED`, `PUBLIC_DOCUMENT_IMAGE_DETECTED`, `INVALID_DATE`, `COULD_NOT_RECOGNIZE_DOCUMENT`(400 전용, 경고로 처리되지 않음), `DOCUMENT_NUMBER_NOT_DETECTED`, `COULD_NOT_DETECT_DOCUMENT_TYPE`, `NAME_NOT_DETECTED`, `DATE_OF_BIRTH_NOT_DETECTED`. 요청 옵션에 의해 제어됨: `MRZ_NOT_DETECTED` / `MRZ_VALIDATION_FAILED`(`invalid_mrz_action`), `DATA_INCONSISTENT` / `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` / `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS`(`inconsistent_data_action`), `EXPIRATION_DATE_NOT_DETECTED`(`expiration_date_not_detected_action`). 기타 위험(예: `POSSIBLE_DUPLICATED_USER`)은 정보 제공용입니다. `DOCUMENT_LIVENESS_NOT_COMPUTED`는 `perform_document_liveness=true`이지만 위조 확인에서 사용할 수 있는 점수를 반환하지 못했을 때 발생하며, `status`를 `In Review`로 설정합니다. `COULD_NOT_DETECT_DOCUMENT_TYPE`은 문서 앞면이 알려진 공식 문서 디자인과 높은 신뢰도로 일치하지 않을 때도 반환되며, 예를 들어 편집되었거나 컴퓨터로 생성된 문서 또는 아직 지원되지 않는 디자인인 경우가 해당합니다. example: DOCUMENT_EXPIRED feature: type: string enum: - ID_VERIFICATION description: >- 경고를 발생시킨 기능입니다. 이 endpoint에서는 항상 `ID_VERIFICATION`입니다. additional_data: type: object nullable: true additionalProperties: true description: >- 일부 위험에 대한 추가 컨텍스트(예: `POSSIBLE_DUPLICATED_USER`에는 `duplicated_session_id` 포함)이며, 대부분의 경우 `null`입니다. log_type: type: string enum: - error - warning - information description: >- 심각도입니다. `error` 경고는 `status`를 `Declined`로 변경합니다. `warning`(요청된 위변조 검사에서 사용 가능한 점수가 나오지 않았을 때 발생하는 `DOCUMENT_LIVENESS_NOT_COMPUTED`만 해당)은 `status`를 `In Review`로 변경합니다. `information` 항목은 참고용이며 상태를 변경하지 않습니다. short_description: type: string description: 사람이 읽을 수 있는 한 줄의 위험 요약입니다. long_description: type: string description: 위험에 대한 사람이 읽기 쉬운 설명입니다. barcodes: type: array description: >- 문서에서 디코딩된 바코드입니다(PDF417, QR 등). 문서에 바코드가 없거나 읽을 수 없는 경우 비어 있습니다. items: type: object properties: type: type: string description: '바코드 유형입니다(예: `PDF417`, `QR_CODE`, `UNKNOWN`).' position: type: object nullable: true additionalProperties: true description: 이미지 내 바코드 위치(사용 가능한 경우). data: type: string description: 디코딩된 payload입니다. data_raw: type: string description: 다른 경우, 원시(디코딩되지 않은) payload입니다. side: type: string nullable: true description: '`front` 또는 `back`.' vendor_data: type: string nullable: true description: 전송한 `vendor_data`의 에코 값 또는 `null`입니다. metadata: type: object nullable: true additionalProperties: true description: 전송한 `metadata` 객체의 에코 값 또는 `null`입니다. created_at: type: string format: date-time description: 응답이 생성된 시점의 ISO 8601 타임스탬프(UTC)입니다. '400': description: >- 검증 또는 처리 오류입니다. 필드 수준의 문제는 DRF의 표준 엔벨로프(문제가 발생한 필드당 하나의 메시지 배열)를 반환합니다. 암호화된 PDF 문제는 `{"detail": ...}`를 반환합니다. 문서를 전혀 인식할 수 없는 문서 이미지는 `{"error": "COULD_NOT_RECOGNIZE_DOCUMENT"}`를 반환합니다. PDF 업로드는 추가로 "The submitted PDF file is corrupted or invalid." 또는 페이지 없음 오류로 실패할 수 있습니다. content: application/json: examples: Missing front image: summary: 폼 데이터에 `front_image`가 포함되지 않음 value: front_image: - No file was submitted. Unsupported file extension: summary: tiff/jpg/jpeg/png/webp/pdf 이외의 파일 확장자 value: front_image: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp, pdf. File too large: summary: 업로드가 10MB 제한을 초과함 value: front_image: - File size should not exceed 10 MB Invalid option value: summary: 옵션은 DECLINE 또는 NO_ACTION만 허용합니다. value: invalid_mrz_action: - '"REVIEW" is not a valid choice.' Encrypted PDF: summary: 필수 비밀번호 없이 업로드된 PDF입니다. value: detail: >- The PDF is encrypted. Please upload a decrypted PDF or a photo instead. Wrong PDF password: summary: >- `front_image_password` / `back_image_password`로 PDF를 복호화할 수 없음 value: detail: >- The PDF password is incorrect. Please provide the correct password. Document not recognized: summary: 이미지에서 신분증을 감지할 수 없습니다 value: error: COULD_NOT_RECOGNIZE_DOCUMENT PDF conversion failure: summary: 업로드된 PDF를 이미지로 변환할 수 없습니다 value: error: Failed to convert front image PDF. '403': description: >- 권한이 거부되었습니다. `x-api-key` 헤더가 누락되었거나 호출한 조직의 잔액이 호출 비용을 충당할 수 없을 때 반환됩니다. 잘못되었거나 취소되었거나 만료된 키는 `401`을 반환합니다. 키가 누락된 경우 `{"detail": ...}`과 함께 `403`을 반환하고, 잘못되었거나 취소되었거나 만료된 키는 `401`을 반환합니다. 크레딧이 부족한 경우 어떠한 이미지 처리도 진행되기 전에 `{"error": ...}`과 함께 `403`을 반환합니다. content: application/json: examples: Missing or invalid API key: summary: '`x-api-key` 헤더가 없거나, 키가 유효하지 않거나 해지되었습니다' value: detail: You do not have permission to perform this action. Not enough credits: summary: 조직 잔액이 호출 비용을 충당할 수 없습니다 value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- 속도 제한을 초과했습니다. POST/PATCH/DELETE endpoint는 API 키당 분당 300회의 쓰기 요청 한도를 공유합니다(거래 생성 및 이벤트 수집은 별도로 600회 한도 적용). 응답에는 `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `Retry-After` 헤더가 포함됩니다. content: application/json: examples: Write rate limit exceeded: summary: 현재 분 동안 300건을 초과하는 쓰기 요청 발생 value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string '503': $ref: '#/components/responses/DocumentProcessingBusy' security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/id-verification/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'front_image=@./id_front.jpg' \ -F 'back_image=@./id_back.jpg' \ -F 'perform_document_liveness=true' \ -F 'save_api_request=true' \ -F 'vendor_data=user-123' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.id_verification.verify( front_image=open("front_image.jpg", "rb"), back_image=open("back_image.jpg", "rb"), perform_document_liveness=True, save_api_request=True, vendor_data="user-123", metadata={"flow": "onboarding"}, ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.idVerification.verify({ front_image: await fileFromPath("front_image.jpg"), back_image: await fileFromPath("back_image.jpg"), perform_document_liveness: true, save_api_request: true, vendor_data: "user-123", metadata: { flow: "onboarding" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDVerification.Verify(ctx, didit.IDVerificationVerifyParams{\n\tFrontImage: didit.FileFromPath(\"front_image.jpg\"),\n\tBackImage: didit.Some(didit.FileFromPath(\"back_image.jpg\")),\n\tPerformDocumentLiveness: didit.Bool(true),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"onboarding\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import java.util.Map; import me.didit.Didit; import me.didit.types.IdVerificationVerifyParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.idVerification().verify(IdVerificationVerifyParams.builder() .frontImage(Path.of("front_image.jpg")) .backImage(Path.of("back_image.jpg")) .performDocumentLiveness(true) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "onboarding")) .build()); System.out.println(result); - lang: php label: PHP source: |- idVerification->verify([ 'front_image' => File::fromPath('front_image.jpg'), 'back_image' => File::fromPath('back_image.jpg'), 'perform_document_liveness' => true, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'onboarding'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.id_verification.verify( front_image: Pathname("front_image.jpg"), back_image: Pathname("back_image.jpg"), perform_document_liveness: true, save_api_request: true, vendor_data: "user-123", metadata: { flow: "onboarding" } ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.IdVerification.VerifyAsync(new IdVerificationVerifyParams { FrontImage = FileUpload.FromPath("front_image.jpg"), BackImage = FileUpload.FromPath("back_image.jpg"), PerformDocumentLiveness = true, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "onboarding" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: responses: DocumentProcessingBusy: description: >- 현재 너무 많은 문서가 처리 중이므로 이 업로드가 처리되지 않았습니다. 아무것도 저장되지 않았으며 시도 횟수도 사용되지 않았습니다. `Retry-After`의 시간(초)이 지난 후 동일한 파일을 다시 전송하세요. 메시지 텍스트가 아닌 `code`를 기준으로 분기하세요. headers: Retry-After: description: 동일한 요청을 다시 전송하기 전에 대기해야 하는 시간(초)입니다. schema: type: integer example: 10 content: application/json: schema: type: object required: - detail - code properties: detail: type: string code: type: string enum: - document_processing_busy example: detail: We are busy processing documents. Please try again in a moment. code: document_processing_busy securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Business Console의 Developers -> API keys에서 발급받은 귀하 애플리케이션의 API 키입니다. 기본 키는 전체 접근 권한을 갖습니다. 이름이 지정된 키는 리소스별 none, read, write 범위로 권한을 제한할 수 있으며 특정 워크플로나 승인된 세션, IP 주소 목록, 만료일 등으로 제한할 수도 있습니다. 401은 키가 잘못되었거나 폐기되었거나 만료되었음을 의미합니다. 403은 키가 전송되지 않았거나, 키에 해당 리소스나 작업에 대한 접근 권한이 없거나, 요청이 허용된 IP 목록 외부 주소에서 발생했음을 의미합니다. 세션 경로에서의 404는 해당 세션이 키의 허용 워크플로 또는 상태 범위를 벗어났음을 의미합니다. 미디어 접근 권한이 없는 키는 이미지, 비디오, PDF URL을 null로 수신하며, 세션 write 권한이 없는 키는 세션 링크와 token을 null로 수신합니다. https://docs.didit.me/console/api-keys 를 참고하십시오. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.