> ## 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: 국가 ID 일치 확인 > Didit 데이터베이스 검증 API. POST /v3/database-validation/로 100+ 국가 및 글로벌 소스에 신원 데이터를 1x1·2x2 waterfall 매칭으로 검증합니다. 호출 건당 과금. ## 주소 기반 서비스 주소 확인(거주지 또는 공과금 주소 검증)을 제공하는 서비스에서는 단일 `address` 값을 보내면 처리 전에 Didit이 이를 나눕니다. 일치율을 가장 높이려면 Didit의 구조화된 주소 필드를 직접 보내십시오. | 필드 | 설명 | | - | - | | `address_element_1` | 번호와 도로 유형을 포함한 도로명 주소 | | `address_element_2` | 선택 사항인 동, 건물, 층 또는 추가 주소 줄 | | `address_element_3` | 구, 지구, 동 또는 행정 지역 | | `address_element_4` | 도시, 시, 주, 도 또는 광역 지역 | | `address_element_5` | 우편번호 | 구조화된 필드는 단일 `address` 값보다 우선합니다. `postal_code`는 `address_element_5`의 별칭으로 허용됩니다. ## 동의 일부 데이터베이스 서비스는 제공자를 조회하기 전에 최종 사용자의 명시적 동의가 필요합니다. 서비스 카탈로그에서는 이러한 항목에 `requires_consent=true`로 표시합니다. 선택한 서비스에 사용자 동의가 적용되는 경우 `consent=true`를 보내십시오. 선택한 서비스에 동의가 필요한데 이를 보내지 않으면, Didit은 제공자 호출이나 과금 이벤트가 발생하기 전에 요청을 거부합니다. ## 파일 업로드 데이터베이스 검증은 `multipart/form-data`를 사용합니다. `selfie`가 필요한 생체 인증 서비스는 API 플레이그라운드에서 이를 파일 업로드 필드로 제공하므로, 경로나 base64 문자열을 붙여넣지 않고 이미지를 직접 선택할 수 있습니다. 코드에서는 일반적인 multipart 문법으로 파일을 업로드하십시오: ```bash theme={null} -F "selfie=@./selfie.jpg" ``` ## 검증 오류 Didit은 제공자를 호출하기 전에 필수 필드, 주소 구조, 서비스별 형식을 검증합니다. 예를 들어 `chn_national_id`, `chn_passport_verification` 같은 중국 등기 서비스는 `full_name`을 원래의 중국어 문자로 입력받으며, `chn_national_id`는 체크섬이 올바른 유효한 15자리 또는 18자리 중국 주민등록번호도 필요합니다. 요청을 실행할 수 없으면 API는 명시적인 필드 오류를 반환하며 사용량은 과금되지 않습니다. 사전 검증 이후 제공자가 실패하면 응답에 `validation_errors`가 포함되고, 저장된 API 요청은 해당 오류를 데이터베이스 검증 결과에 저장합니다. ## 거부된 입력 및 사용할 수 없는 결과 사용할 수 있는 결과를 반환한 서비스가 하나도 없으면, 재시도 여부를 결정하기 전에 각 `validation_errors` 항목을 확인하십시오. HTTP 상태 코드만으로는 재시도가 적절한지 판단할 수 없습니다. `code: "provider_rejected_input"`과 `retryable: false`가 포함된 `400` 응답은 응답되지 않은 모든 시도가 입력을 명시적으로 거부했음을 뜻합니다. 다시 시도하기 전에 제공된 데이터를 수정하십시오. 이러한 시도에는 과금되지 않습니다. `code: "empty_provider_response"`와 `retryable: true`가 포함된 `502` 응답은 다른 이유로 서비스가 사용할 수 있는 결과를 만들지 못했음을 뜻합니다. 여기에는 거부된 입력 뒤에 사용할 수 없는 대체 서비스가 이어진 경우나, 설명을 제공하지 않는 대체 서비스가 이어진 경우도 포함됩니다. 나중에 다시 시도하십시오. 이 응답만으로 입력이 잘못되었다고 판단할 수는 없습니다. 데이터베이스가 계속 실패하면, 중단이 지속될 때 Didit이 최근에 해당 데이터베이스를 사용한 조직에 한 번 이메일을 보내며, 실제 검사에서 서비스가 응답을 다시 시작했음이 확인되면 한 번 더 보냅니다. 자세한 내용은 [가용성 알림](https://docs.didit.me/ko/core-technology/database-validation/overview.md#가용성-알림)을 참조하십시오. 선택한 서비스 중 일부만 실패하면 요청은 대신 성공합니다. 응답은 `200`이며, 실패한 서비스는 `database_validation.errors[]`에 나열되고 각 항목에는 동일한 `code`와 `retryable` 필드가 포함됩니다. 이때 `database_validation.status`는 응답한 서비스를 기준으로 결정되며 `Approved`일 수 있으므로, `4xx` 또는 `5xx` 응답뿐 아니라 모든 응답에서 `errors[]`를 확인하십시오. 여기에 보고된 서비스는 `validations`와 `services_used`에서 제외되며 과금되지 않습니다. 해당 서비스만 따로 다시 시도하십시오. 그 밖의 `502` 오류는 입력을 수정해야 할 수 있습니다. 예를 들어 `provider_invalid_input`과 `provider_validation_error`는 원본 제공자가 거부한 입력을 나타내므로, 레거시 응답에 `retryable`이 없더라도 수정 없이 다시 시도하면 안 됩니다. `empty_provider_response`의 재시도 지침은 이러한 코드에 적용되지 않습니다. 결과가 일치하는 대상이 없다는 확정적 결과라면, 그것은 가용성 실패가 아니라 완료된 검사입니다. ## OpenAPI ````yaml ko/openapi-25.json POST /v3/database-validation/ 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/database-validation/: post: tags: - Standalone APIs summary: 데이터베이스 검증 (단독) description: >- 공식 정부 및 등록부 출처(브라질의 CPF, 아르헨티나의 RENAPER, 스페인 및 페루의 DNI 등록부, 멕시코의 INE 및 60+개국에 걸친 100+개 이상의 서비스)를 대상으로 개인의 신원 데이터를 검증합니다. **서비스 선택.** 각 국가는 `service_id`(예: `bra_cpf`, `arg_renaper`, `pan_cedula_sib`)로 식별되는 하나 이상의 카탈로그 서비스를 제공합니다. `services` 배열로 원하는 서비스를 지정하세요. 이를 생략하면 정확히 **하나**의 기본 서비스(해당 국가에서 가장 오래 운영된 라이브 서비스)가 실행됩니다. 또한 `services`를 전송하면 응답이 `services_used` 및 `match_score`가 포함된 확장된 형식으로 전환됩니다. 서비스, 필수 필드 및 가격은 `GET /v1/organization/database-validation-countries/`(이 사양에 문서화되지 않은 카탈로그 endpoint) 또는 Business Console 워크플로 편집기를 통해 확인할 수 있습니다. 일부 서비스는 카탈로그에서 `requires_consent=true`로 표시되어 `consent=true`를 요구하며, 다른 서비스는 호출하기 전에 조직에 대한 온보딩이 필요합니다. **입력 필드.** `identification_number`는 해당 국가별 필드에 자동으로 매핑되는 범용 필드입니다(설명 참조). 공급자를 호출하기 전에 국가별 형식 규칙이 적용되며(예: 브라질 CPF는 정확히 11자리여야 함), 형식 오류에 대해서는 비용이 청구되지 않습니다. 생체 인식 서비스는 `selfie` 업로드(multipart 전용)가 필요하며, 아르헨티나 RENAPER는 추가로 `gender`를 요구합니다. **결과.** 각 서비스는 필드별 `validation` 맵과 공급자 중립적인 `outcome_code`(`MATCH`, `PARTIAL_MATCH`, `NO_MATCH`, `DOCUMENT_NOT_FOUND`, `INVALID_DOCUMENT_FORMAT`, `INVALID_INPUT`, `MINOR_BLOCKED`, `DECEASED`, `BIOMETRIC_NO_MATCH`, `BIOMETRIC_IMAGE_UNUSABLE`, `INCONCLUSIVE`, `DOCUMENT_SUPERSEDED`, `REGISTRY_UNAVAILABLE`, `REGISTRY_ERROR`)를 반환합니다. 차이점에 유의하세요. `NO_MATCH`는 확정적 불일치이며, `INCONCLUSIVE`는 등록부가 어느 쪽으로도 확인할 수 없음을 의미합니다(거부가 아닌 검토 필요). 또한 `BIOMETRIC_IMAGE_UNUSABLE`은 확정적 `BIOMETRIC_NO_MATCH`와 달리 셀피의 기술적 문제(재촬영)입니다. 전체 `match_type`은 여러 서비스에 걸쳐 집계되며(완전 일치가 하나라도 있으면 → `full_match`, 그렇지 않고 부분 일치가 하나라도 있으면 → `partial_match`, 그 외에는 `no_match`), `no_match_action`/`partial_match_action`이 이를 최종 `status`로 변환합니다. `validation_type`은 도출된 값입니다. 두 개 이상의 서로 다른 서비스에서 완전 일치(식별 번호 일치, 성명 + 생년월일 동시 일치, 또는 모순 없는 주소 일치)를 생성한 경우 `two_by_two`가 되며, 그렇지 않으면 `one_by_one`이 됩니다. **영속성.** `save_api_request`의 기본값은 **true**입니다. 결과는 세션으로 저장되고(`request_id`는 `GET /v3/session/{sessionId}/decision/`에서 작동함), 콘솔에 표시되며, `status.updated` webhook을 트리거합니다. 또한 `validations`의 형식을 제어합니다. 저장된 경우에는 서비스별 객체로, 저장되지 않은 경우에는 병합된 `{field: match}` 맵으로 제공됩니다. **결제.** 서비스별: 청구 가능한 결과를 반환하는 각 서비스에 고유한 카탈로그 가격이 청구됩니다. 실패하거나 건너뛴 서비스에는 비용이 청구되지 않으며, `400`으로 거부된 요청에는 비용이 발생하지 않습니다. 사전 잔액 확인은 선택한 서비스 가격의 합계를 대상으로 수행됩니다(잔액 부족 시 `403`). **실패.** 선택한 서비스 중 사용할 수 있는 결과를 반환한 서비스가 없을 때, 사용 가능한 결과를 반환하지 않은 모든 시도가 입력을 명시적으로 거부한 경우(`provider_rejected_input`, `retryable: false`), API는 `validation_errors`와 함께 `400`을 반환합니다. 입력을 수정한 후 다시 시도하세요. 그렇지 않은 경우(입력 거부와 사용 불가능한 대체 시도가 혼합된 경우 포함), `validation_errors`(`empty_provider_response`, `retryable: true`)와 함께 `502`를 반환합니다. 비용은 청구되지 않습니다(`save_api_request=true`인 경우 상태가 `Not Finished`인 세션이 계속 기록됨). 일부 서비스만 실패한 경우, `200` 응답의 `database_validation.errors`에 해당 실패 내용이 포함됩니다. **샌드박스.** 샌드박스 애플리케이션의 키는 등록부 호출 및 결제를 건너뛰고 정적 `full_match` 응답을 반환합니다. 샌드박스 payload에는 `services` 전송 방식과 관계없이 항상 `services_used` 및 `match_score: 100`이 포함되므로, 샌드박스 응답을 기준으로 프로덕션의 확장된 형식 전환 조건이나 0.0–1.0 범위의 `match_score` 소수값을 검증하지 마세요. `application/json`으로 요청을 전송하거나, `selfie`를 업로드할 때는 `multipart/form-data`로 전송하세요. operationId: post_v3database-validation parameters: [] requestBody: required: true content: application/json: schema: type: object required: - issuing_state properties: issuing_state: type: string description: >- 유효성을 검증할 등기부의 ISO 3166-1 **alpha-3** 국가 코드(예: `BRA`, `ESP`, `COL`)입니다. 사용 가능한 서비스를 결정합니다. 지원되지 않는 코드는 유효한 옵션의 전체 목록과 함께 `400`을 반환합니다. example: BRA services: type: array items: type: string description: >- 해당 국가에 대해 실행할 카탈로그 `service_id` 목록(예: `["bra_cpf"]`). 단일 문자열이나 쉼표로 구분된/JSON으로 인코딩된 문자열도 허용합니다. **생략되거나 비어 있는 경우 정확히 하나의 기본 서비스가 실행됩니다** — 해당 국가에서 가장 오래 운영된 라이브 서비스입니다. 최신 서비스, 생체 인식 서비스 및 종량제 서비스는 명시적으로 지정해야 합니다. `services`를 전송하면 응답이 확장된 형태(`services_used` 및 `match_score` 추가)로 전환됩니다. 모든 id는 `issuing_state`에 존재하고 활성 상태여야 합니다. 온보딩이 필요한 서비스는 조직에 활성화될 때까지 `400`을 반환합니다. 국가별 사용 가능한 서비스는 `GET /v1/organization/database-validation-countries/`(이 사양에 문서화되지 않은 카탈로그 endpoint) 또는 Business Console 워크플로 편집기를 통해 확인할 수 있습니다. example: - bra_cpf validation_type: type: string deprecated: true description: >- 지원 중단됨. 이전 버전과의 호환성을 위해 허용되지만 무시됩니다. 이제 응답의 `validation_type`은 완전히 일치한 서비스 수에서 파생됩니다. 특정 서비스를 고정하려면 `services`를 사용하세요. consent: type: boolean default: false description: >- 최종 사용자가 선택한 검증 서비스에 명시적으로 동의한 경우 `true`로 설정합니다. 카탈로그에서 `requires_consent=true`로 표시된 서비스의 경우 필수입니다. 동의하지 않으면 해당 서비스는 `services_requiring_consent`와 함께 `400`을 반환합니다. identification_number: type: string description: >- 범용 식별 번호 — 해당 국가별 필드에 자동으로 매핑되므로 `personal_number`/`tax_number`/`document_number` 대신 사용할 수 있습니다: ARG→document_number (DNI), BOL→document_number (CI), BRA→tax_number (CPF, 11자리), CHL→personal_number (RUT), COL→personal_number (Cédula), CRI→personal_number (Cédula), DOM→personal_number (Cédula, 11자리), ECU→personal_number (Cédula, 10자리), ESP→personal_number (DNI/NIE), GTM→document_number (DPI), HND→document_number (DNI), MEX→personal_number (CURP, 18자), PAN→personal_number (Cédula), PER→personal_number (DNI, 8자리), PRY→document_number (CI), SLV→document_number (DUI), URY→personal_number (CI), VEN→document_number (Cédula). 명시적으로 제공된 국가별 필드를 절대 덮어쓰지 않습니다. first_name: type: string description: 개인의 이름입니다. 일부 서비스/국가에서 필수입니다. example: John last_name: type: string description: 개인의 성입니다. 일부 서비스/국가에서 필수입니다. example: Doe middle_name: type: string description: 일부 국가 서비스(AUS, NZL 등)에서 사용되는 중간 이름입니다. full_name: type: string description: >- 성명 — 일부 서비스에서는 이름/성 대신 이를 허용합니다(예: 고유 문자 체계 이름을 일치시키는 CHN 서비스). date_of_birth: type: string format: date description: 생년월일, `YYYY-MM-DD`입니다. 많은 서비스에서 필수 항목입니다. example: '1980-01-01' personal_number: type: string description: >- 정부 발급 고유 개인 식별자입니다. 다음 국가에서 사용됩니다: CHL(RUT), COL(Cédula), CRI, DOM, ECU, ESP(DNI/NIE), MEX(CURP), PAN(Cédula), PER(DNI), URY. 대신 `identification_number`를 사용하는 것을 고려하십시오. tax_number: type: string description: >- 납세자 번호입니다. 사용 국가: BRA(CPF, 11자리). 대신 `identification_number` 사용을 고려하십시오. document_number: type: string description: >- 문서 번호입니다. 다음 국가에서 사용됩니다: ARG (DNI), BOL (CI), GTM (DPI), HND (DNI), PRY (CI), SLV (DUI), VEN (Cédula). 대신 `identification_number` 사용을 고려하세요. document_type: type: string enum: - P - DL - ID - RP - SSC - HIC - WP - TC - VISA - PSC - BC - OTHER description: >- 검증 중인 문서 유형: `P`(여권), `DL`(운전면허증), `ID`(국가 신분증), `RP`(거주 허가증)(추가로 `SSC`, `HIC`, `WP`, `TC`, `VISA`, `PSC`, `BC`, `OTHER`). 일부 서비스(예: ESP)에서 필수입니다. expiration_date: type: string format: date description: 문서 만료일(`YYYY-MM-DD`)입니다. ESP(스페인) 검증에 필요합니다. example: '2030-01-15' date_of_issue: type: string format: date description: >- 문서 발급일, `YYYY-MM-DD`(fecha de expedición)입니다. COL(콜롬비아) cédula 검증에 필요합니다. example: '2015-06-20' nationality: type: string description: ISO 3166-1 alpha-3 형식의 국적입니다. 일부 서비스에서 필수입니다. gender: type: string enum: - M - F - X description: >- 성별: `M`, `F` 또는 `X`(기타/알 수 없음). 아르헨티나 RENAPER 검증(`arg_renaper`) 시 필수입니다. address: description: >- 거주지 주소입니다. 구조화된 객체 `{"street_1":"123 Main St","street_2":"Apt 4B","city":"Springfield","region":"IL","postal_code":"62701","country":"US"}` 형식을 권장하지만, 완전한 단일 라인 문자열도 허용됩니다. 주소 검증 서비스에 필수입니다. 서비스에 주소 요구사항이 정의되어 있는 경우 누락된 구성 요소가 있으면 `address_fields_required_by`와 함께 `400`이 반환됩니다. oneOf: - type: object properties: street_1: type: string street_2: type: string city: type: string region: type: string postal_code: type: string country: type: string - type: string description: 한 줄로 작성된 전체 주소(레거시)입니다. address_element_1: type: string description: 도로명 번호 및 유형을 포함한 도로명 주소입니다. 생략 시 `address`에서 파생됩니다. address_element_2: type: string description: 아파트, 동/호수, 건물, 층 또는 추가 주소 라인입니다. 명시적으로 보유한 경우에만 전송하십시오. address_element_3: type: string description: 시, 교외, 구, 지역 또는 동입니다. 생략된 경우 `address`에서 파생됩니다. address_element_4: type: string description: 주, 도, 지역 또는 시/군/구입니다. 생략된 경우 `address`에서 파생됩니다. address_element_5: type: string description: 우편번호입니다. `postal_code`도 별칭으로 허용됩니다. postal_code: type: string description: 주소 기반 서비스를 위한 우편번호(`address_element_5`의 별칭)입니다. driver_license_number: type: string description: 정부 문서 검증 서비스(AUS, NZL, IND)용 운전면허증 번호입니다. driver_license_card_number: type: string description: 면허증 번호와 별도로 요구되는 경우 실물 운전면허증 카드 번호(AUS). driver_license_state: type: string description: 운전면허증 발급 주 또는 테리토리(AUS)입니다. driver_license_version: type: string description: 운전면허증 버전 코드(NZL)입니다. passport_number: type: string description: 정부 여권 검증 서비스(AUS, NZL, IND, CHN)용 여권 번호입니다. passport_expiration_date: type: string format: date description: 여권 검증 서비스를 위한 여권 만료일(`YYYY-MM-DD`)입니다. passport_file_number: type: string description: 여권 파일 번호(IND)입니다. passport_issue_country: type: string description: 여권 인증 서비스용 여권 발급 국가(ISO 3166-1 alpha-3)입니다. medicare_card_number: type: string description: Medicare 카드 번호(AUS). immi_card_number: type: string description: 호주 ImmiCard 번호입니다. immi_card_expiry_date: type: string format: date description: 호주 ImmiCard 만료일입니다. citizenship_certificate_number: type: string description: 시민권 증명서 번호(AUS)입니다. birth_registration_number: type: string description: 출생증명서 등록번호(호주). birth_registration_date: type: string format: date description: 출생증명서 등록일(호주). birth_registration_state: type: string description: 출생증명서 등록 주/지역(호주). marriage_certificate_number: type: string description: 혼인 증명서 번호(AUS). change_of_name_certificate_number: type: string description: 개명 증명서 번호(호주). first_partner_name: type: string description: 결혼 증명서상의 배우자 이름(호주)입니다. last_partner_name: type: string description: 결혼 증명서(AUS)에 기재된 배우자의 성입니다. voter_id: type: string description: 유권자 등록번호(IND EPIC, IRL)입니다. epic_card: type: string description: 인도 EPIC 유권자 카드 번호. pan: type: string description: 인도 PAN(영구 계좌 번호). national_id: type: string description: 국가 신분증 번호(CHN, MYS, KEN, KHM, NGA, ZAF, …). cic: type: string description: >- 멕시코 INE/IFE 신분증 식별 코드(CIC, 9자리)입니다. 멕시코 INE 신분증 유효성 서비스(`mex_ine_vigencia`)에서 사용됩니다. identificador_ciudadano: type: string description: >- 멕시코 INE 시민 식별자(Identificador del Ciudadano, 9자리)입니다. `mex_ine_vigencia`에서 최신 INE 모델(E/F/G/H)의 `cic`와 함께 사용됩니다. ocr: type: string description: >- 멕시코 INE OCR 번호(13자리, 카드 뒷면)입니다. `mex_ine_vigencia`에서 모델 D의 `cic`와 함께 사용됩니다. voter_number: type: string description: >- 멕시코 INE 유권자 식별 번호(Clave de Elector, 18자)입니다. `mex_ine_vigencia`에서 기존 IFE 모델(A/B/C)의 `emission_number`와 함께 사용됩니다. emission_number: type: string description: >- 멕시코 INE 발급 번호(Número de Emisión)입니다. `mex_ine_vigencia`에서 기존 IFE 모델(A/B/C)의 `voter_number`와 함께 사용됩니다. bvn: type: string description: 나이지리아 은행 검증 번호입니다. bank_card_number: type: string description: 은행 카드 번호입니다(중국 은행 카드 인증). company_registration_number: type: string description: >- 법인 등기부에서 발급한 기업 등록번호입니다. 예를 들어 브라질의 CNPJ(예: `11222333000181`), 남아프리카공화국의 등록번호(예: `1936/007721/06`) 등이 있습니다. 법인 등기부 및 기업 이사 조회 서비스(`bra_company_registry`, `bra_company_directors`, `zaf_company_registry`, `zaf_company_directors`)에서 필수입니다. company_name: type: string description: >- 등록부 항목과 대조 확인된 등록 회사명입니다. `zaf_company_registry`의 경우 선택 사항입니다. initials: type: string description: >- 문서에 인쇄된 해당 인물의 이니셜입니다. `zaf_drivers_license`에는 필수이며, `zaf_bank_account_holder`에서는 허용됩니다. licence_number: type: string description: >- `zaf_drivers_license`의 카드에 인쇄된 운전면허증 번호입니다. 생략 시 `document_number`가 사용됩니다. refugee_file_number: type: string description: 남아프리카공화국 내무부에서 발급한 난민 파일 번호입니다. `zaf_refugee`에 필수입니다. bank_name: type: string description: 계좌를 보유한 은행의 이름입니다. `zaf_bank_account_holder`에 필수입니다. bank_account_number: type: string description: >- 은행 계좌번호입니다. `zaf_bank_account_holder`에 필수이며, `zaf_fraud_prevention`에서 허용됩니다. account_type: type: string description: >- `zaf_bank_account_holder`의 은행 계좌 유형: `current`, `savings`, `transmission`, `subscriptionShare` 또는 `notKnown`(대소문자 구분 없음). 다른 모든 값은 `400`을 반환합니다. 유형을 모르는 경우 생략하십시오. 이 경우 계좌 유형 교차 검증은 확인되지 않음으로 보고됩니다. phone_number: type: string description: >- 연락 가능 여부를 교차 확인하는 서비스(`zaf_bank_account_holder`, `zaf_fraud_prevention`, `zaf_refugee`)를 위한 연락처 휴대폰 번호입니다. right_thumb: type: string description: >- `zaf_dha_fingerprint_match`를 위한 Base64 인코딩된 오른손 엄지 지문으로, `left_thumb`와 함께 전송하거나 단독으로 전송합니다. left_thumb: type: string description: >- `zaf_dha_fingerprint_match`를 위한 Base64 인코딩된 왼손 엄지 지문으로, `right_thumb`와 함께 전송하거나 단독으로 전송합니다. score_level: type: integer description: >- `zaf_criminal_face_screening`의 최소 생체 인식 점수 등급입니다. 기본값은 `3`입니다. max_matches: type: integer description: >- `zaf_criminal_face_screening`이 반환하는 최대 후보 일치 항목 수입니다. 기본값은 `1`입니다. vehicle_register_number: type: string description: >- 차량 등록번호. `zaf_vehicle_ownership`에서 `vehicle_licence_plate` 및 `vin`과 함께 필수입니다. vehicle_licence_plate: type: string description: >- 차량 번호판 번호. `zaf_vehicle_ownership`에서 `vehicle_register_number` 및 `vin`과 함께 필수입니다. vin: type: string description: >- 차대번호(VIN 또는 섀시 번호). `zaf_vehicle_ownership`에서 `vehicle_register_number` 및 `vehicle_licence_plate`와 함께 필수입니다. ssn: type: string description: 사회보장번호(미국). phone: type: string description: 전화번호 인증 서비스를 위한 전화번호입니다. landline: type: string description: 전화번호 인증 서비스용 유선 전화번호입니다. email: type: string format: email description: 신원 인증 서비스에 사용할 이메일 주소입니다. country_of_residence: type: string description: >- 거주 국가의 ISO 3166-1 alpha-2 코드입니다. 글로벌 신원 보강 서비스(예: `glb_identity_enrichment`)에서 조회를 세부 조정하는 데 사용됩니다. example: US partial_match_action: type: string enum: - DECLINE - NO_ACTION default: NO_ACTION description: >- `partial_match`가 `database_validation.status`에 적용하는 영향입니다. 기본값은 `NO_ACTION`입니다(상태는 경고와 함께 `Approved`로 유지됨). no_match_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- `no_match`가 `database_validation.status`에 적용하는 영향입니다. 기본값은 `DECLINE`입니다. save_api_request: type: boolean default: true description: >- 검증을 세션으로 유지합니다(콘솔 표시, 결정 endpoint, `status.updated` webhook). 또한 `validations` 응답 형태를 변경합니다: `true`(기본값)인 경우 서비스별 객체, `false`인 경우 병합된 필드 맵. vendor_data: type: string description: 검증 대상 사용자에 대한 귀하의 식별자입니다. 세션에 저장되며 그대로 다시 반환됩니다. metadata: type: object nullable: true description: 요청과 함께 저장되고 그대로 반환되는 자유 형식 JSON입니다. example: issuing_state: BRA services: - bra_cpf identification_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' vendor_data: user-1234 multipart/form-data: schema: type: object required: - issuing_state properties: issuing_state: type: string description: >- 유효성을 검증할 등기부의 ISO 3166-1 **alpha-3** 국가 코드(예: `BRA`, `ESP`, `COL`)입니다. 사용 가능한 서비스를 결정합니다. 지원되지 않는 코드는 유효한 옵션의 전체 목록과 함께 `400`을 반환합니다. example: BRA services: type: array items: type: string description: >- 해당 국가에 대해 실행할 카탈로그 `service_id` 목록(예: `["bra_cpf"]`). 단일 문자열이나 쉼표로 구분된/JSON으로 인코딩된 문자열도 허용합니다. **생략되거나 비어 있는 경우 정확히 하나의 기본 서비스가 실행됩니다** — 해당 국가에서 가장 오래 운영된 라이브 서비스입니다. 최신 서비스, 생체 인식 서비스 및 종량제 서비스는 명시적으로 지정해야 합니다. `services`를 전송하면 응답이 확장된 형태(`services_used` 및 `match_score` 추가)로 전환됩니다. 모든 id는 `issuing_state`에 존재하고 활성 상태여야 합니다. 온보딩이 필요한 서비스는 조직에 활성화될 때까지 `400`을 반환합니다. 국가별 사용 가능한 서비스는 `GET /v1/organization/database-validation-countries/`(이 사양에 문서화되지 않은 카탈로그 endpoint) 또는 Business Console 워크플로 편집기를 통해 확인할 수 있습니다. example: - bra_cpf validation_type: type: string deprecated: true description: >- 지원 중단됨. 이전 버전과의 호환성을 위해 허용되지만 무시됩니다. 이제 응답의 `validation_type`은 완전히 일치한 서비스 수에서 파생됩니다. 특정 서비스를 고정하려면 `services`를 사용하세요. consent: type: boolean default: false description: >- 최종 사용자가 선택한 검증 서비스에 명시적으로 동의한 경우 `true`로 설정합니다. 카탈로그에서 `requires_consent=true`로 표시된 서비스의 경우 필수입니다. 동의하지 않으면 해당 서비스는 `services_requiring_consent`와 함께 `400`을 반환합니다. identification_number: type: string description: >- 범용 식별 번호 — 해당 국가별 필드에 자동으로 매핑되므로 `personal_number`/`tax_number`/`document_number` 대신 사용할 수 있습니다: ARG→document_number (DNI), BOL→document_number (CI), BRA→tax_number (CPF, 11자리), CHL→personal_number (RUT), COL→personal_number (Cédula), CRI→personal_number (Cédula), DOM→personal_number (Cédula, 11자리), ECU→personal_number (Cédula, 10자리), ESP→personal_number (DNI/NIE), GTM→document_number (DPI), HND→document_number (DNI), MEX→personal_number (CURP, 18자), PAN→personal_number (Cédula), PER→personal_number (DNI, 8자리), PRY→document_number (CI), SLV→document_number (DUI), URY→personal_number (CI), VEN→document_number (Cédula). 명시적으로 제공된 국가별 필드를 절대 덮어쓰지 않습니다. first_name: type: string description: 개인의 이름입니다. 일부 서비스/국가에서 필수입니다. example: John last_name: type: string description: 개인의 성입니다. 일부 서비스/국가에서 필수입니다. example: Doe middle_name: type: string description: 일부 국가 서비스(AUS, NZL 등)에서 사용되는 중간 이름입니다. full_name: type: string description: >- 성명 — 일부 서비스에서는 이름/성 대신 이를 허용합니다(예: 고유 문자 체계 이름을 일치시키는 CHN 서비스). date_of_birth: type: string format: date description: 생년월일, `YYYY-MM-DD`입니다. 많은 서비스에서 필수 항목입니다. example: '1980-01-01' personal_number: type: string description: >- 정부 발급 고유 개인 식별자입니다. 다음 국가에서 사용됩니다: CHL(RUT), COL(Cédula), CRI, DOM, ECU, ESP(DNI/NIE), MEX(CURP), PAN(Cédula), PER(DNI), URY. 대신 `identification_number`를 사용하는 것을 고려하십시오. tax_number: type: string description: >- 납세자 번호입니다. 사용 국가: BRA(CPF, 11자리). 대신 `identification_number` 사용을 고려하십시오. document_number: type: string description: >- 문서 번호입니다. 다음 국가에서 사용됩니다: ARG (DNI), BOL (CI), GTM (DPI), HND (DNI), PRY (CI), SLV (DUI), VEN (Cédula). 대신 `identification_number` 사용을 고려하세요. document_type: type: string enum: - P - DL - ID - RP - SSC - HIC - WP - TC - VISA - PSC - BC - OTHER description: >- 검증 중인 문서 유형: `P`(여권), `DL`(운전면허증), `ID`(국가 신분증), `RP`(거주 허가증)(추가로 `SSC`, `HIC`, `WP`, `TC`, `VISA`, `PSC`, `BC`, `OTHER`). 일부 서비스(예: ESP)에서 필수입니다. expiration_date: type: string format: date description: 문서 만료일(`YYYY-MM-DD`)입니다. ESP(스페인) 검증에 필요합니다. example: '2030-01-15' date_of_issue: type: string format: date description: >- 문서 발급일, `YYYY-MM-DD`(fecha de expedición)입니다. COL(콜롬비아) cédula 검증에 필요합니다. example: '2015-06-20' nationality: type: string description: ISO 3166-1 alpha-3 형식의 국적입니다. 일부 서비스에서 필수입니다. gender: type: string enum: - M - F - X description: >- 성별: `M`, `F` 또는 `X`(기타/알 수 없음). 아르헨티나 RENAPER 검증(`arg_renaper`) 시 필수입니다. address: description: >- 거주지 주소입니다. 구조화된 객체 `{"street_1":"123 Main St","street_2":"Apt 4B","city":"Springfield","region":"IL","postal_code":"62701","country":"US"}` 형식을 권장하지만, 완전한 단일 라인 문자열도 허용됩니다. 주소 검증 서비스에 필수입니다. 서비스에 주소 요구사항이 정의되어 있는 경우 누락된 구성 요소가 있으면 `address_fields_required_by`와 함께 `400`이 반환됩니다. oneOf: - type: object properties: street_1: type: string street_2: type: string city: type: string region: type: string postal_code: type: string country: type: string - type: string description: 한 줄로 작성된 전체 주소(레거시)입니다. address_element_1: type: string description: 도로명 번호 및 유형을 포함한 도로명 주소입니다. 생략 시 `address`에서 파생됩니다. address_element_2: type: string description: 아파트, 동/호수, 건물, 층 또는 추가 주소 라인입니다. 명시적으로 보유한 경우에만 전송하십시오. address_element_3: type: string description: 시, 교외, 구, 지역 또는 동입니다. 생략된 경우 `address`에서 파생됩니다. address_element_4: type: string description: 주, 도, 지역 또는 시/군/구입니다. 생략된 경우 `address`에서 파생됩니다. address_element_5: type: string description: 우편번호입니다. `postal_code`도 별칭으로 허용됩니다. postal_code: type: string description: 주소 기반 서비스를 위한 우편번호(`address_element_5`의 별칭)입니다. driver_license_number: type: string description: 정부 문서 검증 서비스(AUS, NZL, IND)용 운전면허증 번호입니다. driver_license_card_number: type: string description: 면허증 번호와 별도로 요구되는 경우 실물 운전면허증 카드 번호(AUS). driver_license_state: type: string description: 운전면허증 발급 주 또는 테리토리(AUS)입니다. driver_license_version: type: string description: 운전면허증 버전 코드(NZL)입니다. passport_number: type: string description: 정부 여권 검증 서비스(AUS, NZL, IND, CHN)용 여권 번호입니다. passport_expiration_date: type: string format: date description: 여권 검증 서비스를 위한 여권 만료일(`YYYY-MM-DD`)입니다. passport_file_number: type: string description: 여권 파일 번호(IND)입니다. passport_issue_country: type: string description: 여권 인증 서비스용 여권 발급 국가(ISO 3166-1 alpha-3)입니다. medicare_card_number: type: string description: Medicare 카드 번호(AUS). immi_card_number: type: string description: 호주 ImmiCard 번호입니다. immi_card_expiry_date: type: string format: date description: 호주 ImmiCard 만료일입니다. citizenship_certificate_number: type: string description: 시민권 증명서 번호(AUS)입니다. birth_registration_number: type: string description: 출생증명서 등록번호(호주). birth_registration_date: type: string format: date description: 출생증명서 등록일(호주). birth_registration_state: type: string description: 출생증명서 등록 주/지역(호주). marriage_certificate_number: type: string description: 혼인 증명서 번호(AUS). change_of_name_certificate_number: type: string description: 개명 증명서 번호(호주). first_partner_name: type: string description: 결혼 증명서상의 배우자 이름(호주)입니다. last_partner_name: type: string description: 결혼 증명서(AUS)에 기재된 배우자의 성입니다. voter_id: type: string description: 유권자 등록번호(IND EPIC, IRL)입니다. epic_card: type: string description: 인도 EPIC 유권자 카드 번호. pan: type: string description: 인도 PAN(영구 계좌 번호). national_id: type: string description: 국가 신분증 번호(CHN, MYS, KEN, KHM, NGA, ZAF, …). cic: type: string description: >- 멕시코 INE/IFE 신분증 식별 코드(CIC, 9자리)입니다. 멕시코 INE 신분증 유효성 서비스(`mex_ine_vigencia`)에서 사용됩니다. identificador_ciudadano: type: string description: >- 멕시코 INE 시민 식별자(Identificador del Ciudadano, 9자리)입니다. `mex_ine_vigencia`에서 최신 INE 모델(E/F/G/H)의 `cic`와 함께 사용됩니다. ocr: type: string description: >- 멕시코 INE OCR 번호(13자리, 카드 뒷면)입니다. `mex_ine_vigencia`에서 모델 D의 `cic`와 함께 사용됩니다. voter_number: type: string description: >- 멕시코 INE 유권자 식별 번호(Clave de Elector, 18자)입니다. `mex_ine_vigencia`에서 기존 IFE 모델(A/B/C)의 `emission_number`와 함께 사용됩니다. emission_number: type: string description: >- 멕시코 INE 발급 번호(Número de Emisión)입니다. `mex_ine_vigencia`에서 기존 IFE 모델(A/B/C)의 `voter_number`와 함께 사용됩니다. bvn: type: string description: 나이지리아 은행 검증 번호입니다. bank_card_number: type: string description: 은행 카드 번호입니다(중국 은행 카드 인증). company_registration_number: type: string description: >- 법인 등기부에서 발급한 기업 등록번호입니다. 예를 들어 브라질의 CNPJ(예: `11222333000181`), 남아프리카공화국의 등록번호(예: `1936/007721/06`) 등이 있습니다. 법인 등기부 및 기업 이사 조회 서비스(`bra_company_registry`, `bra_company_directors`, `zaf_company_registry`, `zaf_company_directors`)에서 필수입니다. company_name: type: string description: >- 등록부 항목과 대조 확인된 등록 회사명입니다. `zaf_company_registry`의 경우 선택 사항입니다. initials: type: string description: >- 문서에 인쇄된 해당 인물의 이니셜입니다. `zaf_drivers_license`에는 필수이며, `zaf_bank_account_holder`에서는 허용됩니다. licence_number: type: string description: >- `zaf_drivers_license`의 카드에 인쇄된 운전면허증 번호입니다. 생략 시 `document_number`가 사용됩니다. refugee_file_number: type: string description: 남아프리카공화국 내무부에서 발급한 난민 파일 번호입니다. `zaf_refugee`에 필수입니다. bank_name: type: string description: 계좌를 보유한 은행의 이름입니다. `zaf_bank_account_holder`에 필수입니다. bank_account_number: type: string description: >- 은행 계좌번호입니다. `zaf_bank_account_holder`에 필수이며, `zaf_fraud_prevention`에서 허용됩니다. account_type: type: string description: >- `zaf_bank_account_holder`의 은행 계좌 유형: `current`, `savings`, `transmission`, `subscriptionShare` 또는 `notKnown`(대소문자 구분 없음). 다른 모든 값은 `400`을 반환합니다. 유형을 모르는 경우 생략하십시오. 이 경우 계좌 유형 교차 검증은 확인되지 않음으로 보고됩니다. phone_number: type: string description: >- 연락 가능 여부를 교차 확인하는 서비스(`zaf_bank_account_holder`, `zaf_fraud_prevention`, `zaf_refugee`)를 위한 연락처 휴대폰 번호입니다. right_thumb: type: string description: >- `zaf_dha_fingerprint_match`를 위한 Base64 인코딩된 오른손 엄지 지문으로, `left_thumb`와 함께 전송하거나 단독으로 전송합니다. left_thumb: type: string description: >- `zaf_dha_fingerprint_match`를 위한 Base64 인코딩된 왼손 엄지 지문으로, `right_thumb`와 함께 전송하거나 단독으로 전송합니다. score_level: type: integer description: >- `zaf_criminal_face_screening`의 최소 생체 인식 점수 등급입니다. 기본값은 `3`입니다. max_matches: type: integer description: >- `zaf_criminal_face_screening`이 반환하는 최대 후보 일치 항목 수입니다. 기본값은 `1`입니다. vehicle_register_number: type: string description: >- 차량 등록번호. `zaf_vehicle_ownership`에서 `vehicle_licence_plate` 및 `vin`과 함께 필수입니다. vehicle_licence_plate: type: string description: >- 차량 번호판 번호. `zaf_vehicle_ownership`에서 `vehicle_register_number` 및 `vin`과 함께 필수입니다. vin: type: string description: >- 차대번호(VIN 또는 섀시 번호). `zaf_vehicle_ownership`에서 `vehicle_register_number` 및 `vehicle_licence_plate`와 함께 필수입니다. ssn: type: string description: 사회보장번호(미국). phone: type: string description: 전화번호 인증 서비스를 위한 전화번호입니다. landline: type: string description: 전화번호 인증 서비스용 유선 전화번호입니다. email: type: string format: email description: 신원 인증 서비스에 사용할 이메일 주소입니다. country_of_residence: type: string description: >- 거주 국가의 ISO 3166-1 alpha-2 코드입니다. 글로벌 신원 보강 서비스(예: `glb_identity_enrichment`)에서 조회를 세부 조정하는 데 사용됩니다. example: US partial_match_action: type: string enum: - DECLINE - NO_ACTION default: NO_ACTION description: >- `partial_match`가 `database_validation.status`에 적용하는 영향입니다. 기본값은 `NO_ACTION`입니다(상태는 경고와 함께 `Approved`로 유지됨). no_match_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- `no_match`가 `database_validation.status`에 적용하는 영향입니다. 기본값은 `DECLINE`입니다. save_api_request: type: boolean default: true description: >- 검증을 세션으로 유지합니다(콘솔 표시, 결정 endpoint, `status.updated` webhook). 또한 `validations` 응답 형태를 변경합니다: `true`(기본값)인 경우 서비스별 객체, `false`인 경우 병합된 필드 맵. vendor_data: type: string description: 검증 대상 사용자에 대한 귀하의 식별자입니다. 세션에 저장되며 그대로 다시 반환됩니다. metadata: type: object nullable: true description: 요청과 함께 저장되고 그대로 반환되는 자유 형식 JSON입니다. selfie: type: string format: binary description: >- 아르헨티나 RENAPER(`arg_renaper`) 및 파나마 SIB(`pan_cedula_sib`, `pan_cedula_sib_plus`) 등 생체 검증 서비스용 셀피 이미지(`jpg`, `jpeg`, `png`, `webp`, 최대 2MB — 이미지는 등기부 업로드 전 약 1.5MB로 압축됨)입니다. 선택한 서비스에서 필수 필드로 나열된 경우 항상 필요합니다. `multipart/form-data`를 통해서만 사용할 수 있습니다. responses: '200': description: >- 검증 완료 — 선택한 서비스 중 최소 하나가 사용 가능한 결과를 반환했습니다. 종합 결과는 `database_validation.match_type`, 서비스별 필드 비교 및 `outcome_code`s는 `validations`, 실패한 서비스는 `errors`(있는 경우)를 확인하십시오. content: application/json: schema: type: object properties: request_id: type: string format: uuid description: >- `save_api_request=true`일 때 유지된 세션 ID(`GET /v3/session/{sessionId}/decision/`와 함께 사용 가능), 그렇지 않으면 임시 상관관계 UUID입니다. database_validation: type: object properties: status: type: string enum: - Approved - Declined - In Review description: >- 전체 `match_type`이 `DECLINE` 작업을 트리거하는 경우 `Declined`(`no_match_action`의 기본값은 `DECLINE`, `partial_match_action`의 기본값은 `NO_ACTION`), 유효한 비교를 생성한 서비스가 없는 경우(예: 선택된 유일한 서비스가 `REGISTRY_UNAVAILABLE` 또는 `INCONCLUSIVE`를 반환한 경우) `In Review`, 그렇지 않은 경우 `Approved`. 여러 서비스를 선택한 요청은 한 서비스에서 일치하여 `Approved`되는 동시에 다른 서비스를 사용할 수 없었을 수 있으므로 `errors` 및 서비스별 `outcome_code`도 확인하십시오. issuing_state: type: string description: 검증 기준이 된 ISO 3166-1 alpha-3 국가의 에코 값입니다. example: BRA validation_type: type: string enum: - one_by_one - two_by_two description: >- 결과에서 도출됨: 2개 이상의 서로 다른 서비스에서 완전 일치(식별 번호 일치, 성명과 생년월일 동시 일치, 또는 모순 없는 주소 일치)를 생성한 경우 `two_by_two`, 그렇지 않은 경우 `one_by_one`입니다. (동일한 이름의 요청 필드는 지원 중단되었으며 무시됩니다.) screened_data: type: object description: >- 선택한 서비스로 전송된 입력 필드의 에코 값입니다(날짜는 `YYYY-MM-DD` 형식으로 정규화되며, `selfie`는 전송된 경우 사전 서명된 URL로 반환되고, 동의를 받은 경우 `consent_obtained: true`가 추가됨). match_type: type: string nullable: true enum: - full_match - partial_match - no_match description: >- 필드 수준 비교를 통해 서비스 전반에서 집계된 전체 결과: `full_match`가 하나라도 있으면 → `full_match`, 그렇지 않고 `partial_match`가 하나라도 있으면 → `partial_match`, 그 외에는 `no_match`입니다. 생체 범죄 스크리닝과 같은 결과 전용 서비스는 `null`을 반환할 수 있으므로, 각 `validations` 항목의 `outcome_code`를 확인하십시오. validations: description: >- 형태는 `save_api_request`에 따라 달라집니다. **`true`(기본값):** 서비스별 객체 배열(`service_id`, `service_name`, `validation`, `outcome_code`, `outcome_detail`, `source_data`)입니다. **`false`:** 모든 서비스의 필드 수준 결과를 병합한 단일 플랫 객체(`{"full_name": "full_match", ...}`)입니다. oneOf: - type: array items: type: object description: >- 서비스별 검증 결과입니다(`save_api_request=true`일 때 반환되며 기본값임). properties: service_id: type: string description: '이 결과를 생성한 서비스의 카탈로그 id(예: `bra_cpf`).' example: bra_cpf service_name: type: string description: 서비스의 사람이 읽기 쉬운 카탈로그 이름입니다. example: Brazil - CPF status check validation: type: object description: >- 입력값과 등기부 기록 간의 필드별 비교입니다. 키는 표준 필드 이름(`full_name`, `date_of_birth`, `identification_number`, `address`, …)이며, 값은 `full_match`, `partial_match` 또는 `no_match`입니다. additionalProperties: type: string enum: - full_match - partial_match - no_match outcome_code: type: string enum: - MATCH - PARTIAL_MATCH - NO_MATCH - DOCUMENT_NOT_FOUND - INVALID_DOCUMENT_FORMAT - INVALID_INPUT - MINOR_BLOCKED - DECEASED - BIOMETRIC_NO_MATCH - BIOMETRIC_IMAGE_UNUSABLE - INCONCLUSIVE - DOCUMENT_SUPERSEDED - REGISTRY_UNAVAILABLE - REGISTRY_ERROR description: >- 등록부 조회의 벤더 중립적 결과입니다. `MATCH`/`PARTIAL_MATCH`/`NO_MATCH`는 비교 결과를 나타냅니다. `DOCUMENT_NOT_FOUND`는 식별자가 등록부에 없음을 의미합니다. `INCONCLUSIVE`는 등록소에서 어느 쪽으로도 확인할 수 없음을 의미합니다(검토로 라우팅됨 — 불일치가 아님). `BIOMETRIC_NO_MATCH`는 명확한 얼굴 불일치인 반면 `BIOMETRIC_IMAGE_UNUSABLE`은 기술적인 이미지 문제입니다(셀피 재촬영 필요). `DECEASED`/`MINOR_BLOCKED`는 등록소 정책에 따른 결과입니다. `DOCUMENT_SUPERSEDED`는 신원은 일치하지만 제출된 문서의 판본이 기록과 일치하지 않음(더 최신 판본이 발급됨)을 의미합니다. `INVALID_DOCUMENT_FORMAT`/`INVALID_INPUT`은 등록소 자체가 전송된 데이터를 거부했음을 의미합니다. `REGISTRY_UNAVAILABLE`/`REGISTRY_ERROR`는 상위 시스템 오류를 나타냅니다. outcome_detail: type: string nullable: true description: >- 결과 코드를 뒷받침하는 원시 업스트림 상태 세부 정보(예: HTTP 또는 등기부 상태 코드)입니다. source_data: type: object nullable: true description: >- 표준 필드 이름(`identification_number`, `first_name`, `last_name`, `date_of_birth` 및 등기부 고유 플래그)을 사용하여 정제 및 정규화된 등기부 기록 보기입니다. 이미지 필드가 있는 경우 사전 서명된 URL로 반환됩니다. - type: object additionalProperties: type: string enum: - full_match - partial_match - no_match description: 병합된 필드 수준 결과(무상태 `save_api_request=false` 형태)입니다. warnings: type: array items: type: object properties: feature: type: string description: 경고를 발생시킨 기능입니다. risk: type: string description: 기계 판독 가능한 위험 식별자입니다. additional_data: type: object nullable: true description: 가능한 경우 제공되는 경고의 추가 컨텍스트입니다. log_type: type: string description: >- `warning`, `information` 또는 `error` — 위험이 결과에 미친 영향입니다. short_description: type: string description: 사람이 읽을 수 있는 한 줄 요약입니다. long_description: type: string description: 사람이 읽을 수 있는 전체 설명입니다. description: >- 해당하는 경우 `DATABASE_VALIDATION_NO_MATCH` 또는 `DATABASE_VALIDATION_PARTIAL_MATCH`, 완전히 일치하는 경우 비어 있음. errors: type: array description: >- 선택한 서비스 중 일부(전체는 아님)가 실패한 경우에만 표시됩니다. 각 항목에는 `service_id`, `code`, `message`, `retryable`이 포함됩니다. 여기에 보고된 서비스는 `validations` 및 `services_used`에서 제외되며 결제되지 않습니다. 이 배열이 해당 서비스가 표시되는 유일한 위치이므로 `status`가 `Approved`인 경우에도 확인하십시오. items: type: object properties: service_id: type: string code: type: string example: empty_provider_response message: type: string retryable: type: boolean description: >- 서비스에서 응답을 생성하지 못하여 나중에 재시도하면 성공할 수 있는 경우 `true`입니다. 소스가 전송받은 데이터를 거부하여 입력을 먼저 수정해야 하는 경우에는 `false`입니다. example: true services_used: type: array items: type: string description: >- 청구 가능한 결과를 반환한 서비스의 카탈로그 id 목록. **요청에서 `services`를 명시적으로 보낸 경우에만 표시됩니다.** match_score: type: number description: >- 전체 일치(식별 번호, 성명 + 생년월일 조합 또는 모순 없는 주소 기준)를 생성한 시도된 서비스의 비율(0.0–1.0)입니다. **요청 시 `services`를 명시적으로 전송한 경우에만 표시됩니다.** vendor_data: type: string nullable: true description: 전송한 `vendor_data`의 에코 값입니다. metadata: type: object nullable: true description: 전송한 `metadata`의 에코 값입니다. created_at: type: string format: date-time examples: Full match (Approved): summary: 기본값 save_api_request=true — 서비스별 `validations` 객체 value: request_id: 7f9a1c0e-1f2b-4f6e-9d3a-2b1c0e7f9a1c database_validation: status: Approved issuing_state: BRA validation_type: one_by_one screened_data: tax_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' match_type: full_match validations: - validation: full_name: full_match date_of_birth: full_match identification_number: full_match outcome_code: MATCH outcome_detail: '200' service_id: bra_cpf service_name: Brazil - CPF status check source_data: identification_number: '12345678900' first_name: JOHN last_name: DOE date_of_birth: '1980-01-01' lgpd_minor: false minor_under_16: false minor_under_18: false warnings: [] vendor_data: user-1234 metadata: null created_at: '2026-06-11T10:30:00.000000+00:00' Explicit services (extended shape): summary: >- 요청에서 `services` 전송됨 — 응답에 `services_used` 및 `match_score` 추가됨 value: request_id: b3e7c1a2-9d4f-4f0b-8a6c-5e2d1f0a9b3e database_validation: status: Approved issuing_state: BRA validation_type: one_by_one screened_data: tax_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' match_type: full_match validations: - validation: full_name: full_match date_of_birth: full_match identification_number: full_match outcome_code: MATCH outcome_detail: '200' service_id: bra_cpf service_name: Brazil - CPF status check source_data: identification_number: '12345678900' first_name: JOHN last_name: DOE date_of_birth: '1980-01-01' lgpd_minor: false minor_under_16: false minor_under_18: false warnings: [] services_used: - bra_cpf match_score: 1 vendor_data: user-1234 metadata: null created_at: '2026-06-11T10:30:00.000000+00:00' No match (Declined): summary: 법인 등기부 기록이 일치하지 않음 — 기본값 `no_match_action=DECLINE` value: request_id: 0a1b2c3d-4e5f-6789-abcd-ef0123456789 database_validation: status: Declined issuing_state: BRA validation_type: one_by_one screened_data: tax_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' match_type: no_match validations: - validation: full_name: no_match date_of_birth: no_match identification_number: no_match outcome_code: NO_MATCH outcome_detail: '200' service_id: bra_cpf service_name: Brazil - CPF status check source_data: identification_number: '00987654321' first_name: TOTALLY last_name: DIFFERENT NAME date_of_birth: '1999-01-01' lgpd_minor: false minor_under_16: false minor_under_18: false warnings: - feature: DATABASE_VALIDATION risk: DATABASE_VALIDATION_NO_MATCH additional_data: null log_type: error short_description: Database validation no match long_description: >- The system identified a no match in the database validation, requiring further investigation. vendor_data: null metadata: null created_at: '2026-06-11T10:31:00.000000+00:00' Stateless (save_api_request=false): summary: '`validations`는 병합된 필드 맵으로 압축되며, 아무것도 저장되지 않습니다.' value: request_id: c4d5e6f7-8901-2345-6789-abcdef012345 database_validation: status: Approved issuing_state: BRA validation_type: one_by_one screened_data: tax_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' match_type: full_match validations: full_name: full_match date_of_birth: full_match identification_number: full_match warnings: [] vendor_data: null metadata: null created_at: '2026-06-11T10:32:00.000000+00:00' '400': description: >- 검증 오류 - 결제되지 않습니다. 외부 호출이 발생하기 전에 사전 점검(preflight) 필드 오류가 발생합니다. 응답하지 않은 모든 시도에서 입력을 명시적으로 거부하는 경우, 응답에는 대신 `code: provider_rejected_input` 및 `retryable: false`가 포함된 `validation_errors`가 포함됩니다. 다시 시도하기 전에 입력을 수정하십시오. 필드 수준 문제는 DRF의 표준 엔벨로프를 사용합니다. 카탈로그 문제는 `services` 배열(해당하는 경우 `requires_onboarding` 또는 `services_requiring_consent` 추가)을 반환합니다. 누락된 필드 오류에는 누락된 각 필드를 이를 요구하는 서비스에 매핑하는 `fields_required_by`가 포함됩니다. 하나 이상의 추가 식별자가 필요한 서비스(예: 이름만으로는 검증할 수 없는 `usa_states_credit_bureau`)는 각 서비스를 최소 하나 이상 존재해야 하는 필드에 매핑하는 `any_field_required_by`를 반환합니다. 서비스별로 확인된 형식 문제는 `invalid_fields_by_service`를 반환합니다. content: application/json: examples: Invalid issuing_state: summary: 지원되지 않는 국가 — 메시지에 모든 유효한 alpha-3 코드가 나열됩니다 value: error: - >- Invalid issuing state. Valid options are: ARE, ARG, AUS, AUT, BEL, BGD, BOL, BRA, CAN, CHE, CHL, CHN, CIV, COL, CRI, CZE, DEU, DNK, DOM, ECU, ESP, FIN, FRA, GBR, GHA, GLB, GRC, GTM, HKG, HND, IDN, IND, IRL, ITA, KEN, KHM, MAR, MEX, MYS, NGA, NLD, NOR, NZL, OMN, PAN, PER, PHL, POL, PRT, PRY, QAT, SGP, SLV, SVK, SWE, THA, UGA, URY, USA, VEN, ZAF, ZMB, ZWE Missing required fields: summary: 선택한 서비스 전반의 필수 필드 합집합(범용 필드 힌트 포함) value: error: - >- Missing required fields: tax_number (or use 'identification_number' which maps to 'tax_number' for BRA) fields_required_by: tax_number: - bra_cpf Unknown service id: summary: '`services`에 카탈로그에 없는 ID가 포함되어 있음' value: services: - 'Unknown service_id(s): [''bogus_service'']' Service not live for country: summary: '`services`에 다른 국가의 서비스(또는 스텁 항목)가 지정되어 있음' value: services: - >- Services not currently live for PER: ['bra_cpf']. Available services: ['per_dni', 'per_residential', 'per_tax_registration'] Service requires onboarding: summary: 서비스가 존재하지만 조직에 아직 활성화되지 않았습니다 value: services: - >- Services require onboarding before they can be enabled for AUS: ['aus_australia_driver_licence']. Contact Didit support to activate them. requires_onboarding: - aus_australia_driver_licence Consent missing: summary: >- 선택한 서비스에 requires_consent=true 플래그가 지정되어 있으나 `consent`가 `true`가 아닙니다. value: consent: - >- Explicit end-user consent is required for these database validation services: ['chn_national_id']. Send `consent=true`. services_requiring_consent: - chn_national_id Country format rule violation: summary: 식별자가 해당 국가의 형식 규칙(길이/숫자/정규식)을 충족하지 못함 value: tax_number: - >- Invalid tax number for BRA: Brazilian CPF (exactly 11 digits). Must be exactly 11 characters long (got 10). Service-specific format violation: summary: 필드가 선택한 서비스 자체의 형식 요구사항을 충족하지 않습니다 value: error: - >- One or more fields do not match the format required by the selected service. invalid_fields_by_service: chn_national_id: - national_id_format Input refused by every attempt: summary: 재시도하기 전에 입력을 수정하세요 value: error: >- The source refused to run this query with the supplied input. validation_errors: - service_id: bra_cpf code: provider_rejected_input message: >- The source refused to run this query with the supplied input. retryable: false schema: type: object additionalProperties: true properties: error: description: 요청 수준의 설명 또는 사전 점검 필드 오류입니다. oneOf: - type: string - type: array items: type: string validation_errors: type: array description: 응답되지 않은 모든 시도가 사전 검사 후 입력을 거부했을 때 표시됩니다. items: type: object properties: service_id: type: string code: type: string message: type: string retryable: type: boolean description: >- 나중에 재시도하여 이 서비스 장애를 해결할 수 있는지 여부입니다. False는 제공된 입력을 먼저 수정해야 함을 의미합니다. '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 '502': description: >- 선택한 서비스 중 사용 가능한 결과를 반환한 서비스가 없습니다. 재시도하기 전에 각 validation_errors 항목을 확인하십시오. HTTP 502만으로는 일시적 장애 여부를 판단할 수 없습니다. retryable: true인 empty_provider_response는 기본 제공자 거부 후 대체 제공자 사용 불가 등 사용 불가하거나 설명되지 않은 결과를 나타냅니다. 레거시 provider_invalid_input 및 provider_validation_error 항목은 대신 수정된 입력이 필요하며 retryable이 생략될 수 있습니다. 청구되는 금액은 없습니다. save_api_request=true인 경우, 실패한 시도는 상태가 Not Finished인 세션으로 기록됩니다. 부분 실패는 database_validation.errors와 함께 200을 반환합니다. content: application/json: schema: type: object properties: error: type: string validation_errors: type: array items: type: object properties: service_id: type: string code: type: string message: type: string retryable: type: boolean description: >- 나중에 재시도하여 이 서비스 장애를 해결할 수 있는지 여부입니다. False는 제공된 입력을 먼저 수정해야 함을 의미합니다. examples: Provider returned no result: summary: 선택한 모든 서비스 실패 value: error: >- Database validation could not be performed. The external validation service did not return a result. Please try again later. validation_errors: - service_id: bra_cpf code: empty_provider_response message: >- The provider did not return a database validation result. retryable: true security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST https://verification.didit.me/v3/database-validation/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "issuing_state": "BRA", "services": ["bra_cpf"], "identification_number": "12345678900", "first_name": "John", "last_name": "Doe", "date_of_birth": "1980-01-01", "vendor_data": "user-1234" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.database_validation.validate( issuing_state="BRA", services=["bra_cpf"], identification_number="12345678900", first_name="John", last_name="Doe", date_of_birth="1980-01-01", vendor_data="user-1234", ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.databaseValidation.validate({ issuing_state: "BRA", services: ["bra_cpf"], identification_number: "12345678900", first_name: "John", last_name: "Doe", date_of_birth: "1980-01-01", vendor_data: "user-1234", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.DatabaseValidation.Validate(ctx, didit.DatabaseValidationValidateParams{\n\tIssuingState: \"BRA\",\n\tServices: didit.Some([]string{\"bra_cpf\"}),\n\tIdentificationNumber: didit.String(\"12345678900\"),\n\tFirstName: didit.String(\"John\"),\n\tLastName: didit.String(\"Doe\"),\n\tDateOfBirth: didit.String(\"1980-01-01\"),\n\tVendorData: didit.String(\"user-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.time.LocalDate; import java.util.List; import me.didit.Didit; import me.didit.types.DatabaseValidationValidateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.databaseValidation().validate(DatabaseValidationValidateParams.builder() .issuingState("BRA") .services(List.of("bra_cpf")) .identificationNumber("12345678900") .firstName("John") .lastName("Doe") .dateOfBirth(LocalDate.parse("1980-01-01")) .vendorData("user-1234") .build()); System.out.println(result); - lang: php label: PHP source: |- databaseValidation->validate([ 'issuing_state' => 'BRA', 'services' => ['bra_cpf'], 'identification_number' => '12345678900', 'first_name' => 'John', 'last_name' => 'Doe', 'date_of_birth' => '1980-01-01', 'vendor_data' => 'user-1234', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.database_validation.validate( issuing_state: "BRA", services: ["bra_cpf"], identification_number: "12345678900", first_name: "John", last_name: "Doe", date_of_birth: "1980-01-01", vendor_data: "user-1234" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.DatabaseValidation.ValidateAsync(new DatabaseValidationValidateParams { IssuingState = "BRA", Services = new string[] { "bra_cpf" }, IdentificationNumber = "12345678900", FirstName = "John", LastName = "Doe", DateOfBirth = "1980-01-01", VendorData = "user-1234", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: 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.