> ## 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. # Database Validation API > Validate a person's identity data against official government and registry sources — CPF in Brazil, RENAPER in Argentina, DNI registries in Spain and Peru, INE in Mexico, and 100+ more services across 60+ countries. **Service selection.** Each country exposes one or more catalog services identified by a `service_id` (e.g. `bra_cpf`, `arg_renaper`, `pan_cedula_sib`). Pin the services you want with the `services` array — if you omit it, exactly **one** default service runs (the longest-established live service for the country). Sending `services` also switches the response to the extended shape with `services_used` and `match_score`. Discover services, their required fields, and prices via `GET /v1/organization/database-validation-countries/` (a catalog endpoint not documented in this spec) or the Business Console workflow editor. Some services are flagged `requires_consent=true` in the catalog and demand `consent=true`; others require onboarding for your organization before they can be called. **Input fields.** `identification_number` is a universal field that maps to the right country-specific field automatically (see its description). Country format rules are enforced before any provider is called (e.g. BRA CPF must be exactly 11 digits) and format failures are never billed. Biometric services need a `selfie` upload (multipart only); Argentina RENAPER additionally requires `gender`. **Results.** Each service returns a field-by-field `validation` map plus a vendor-neutral `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`). Note the distinctions: `NO_MATCH` is a definitive mismatch, `INCONCLUSIVE` means the registry could not confirm either way (review, not decline), and `BIOMETRIC_IMAGE_UNUSABLE` is a technical selfie problem (retake), unlike the definitive `BIOMETRIC_NO_MATCH`. The overall `match_type` aggregates across services (any full → `full_match`, else any partial → `partial_match`, else `no_match`) and `no_match_action`/`partial_match_action` translate it into the final `status`. `validation_type` is derived: `two_by_two` when two or more distinct services produced a full match (on the identification number, on full name + date of birth together, or on the address without contradictions), else `one_by_one`. **Persistence.** `save_api_request` defaults to **true**: the result is stored as a session (`request_id` works with `GET /v3/session/{sessionId}/decision/`), appears in the console, and fires a `status.updated` webhook. It also controls the `validations` shape — per-service objects when saved, a merged `{field: match}` map when not. **Billing.** Per-service: each service that returns a billable result is charged its own catalog price. Failed or skipped services are not billed, and requests rejected with `400` cost nothing. The pre-flight balance check covers the sum of the selected services' prices (`403` when short). **Failures.** When no selected service returns a usable result, the API returns `400` with `validation_errors` if every unanswered attempt explicitly refused the input (`provider_rejected_input`, `retryable: false`). Correct the input before trying again. Otherwise it returns `502` with `validation_errors` (`empty_provider_response`, `retryable: true`), including mixed input rejection and unavailable fallback attempts; nothing is billed (a session is still recorded with status `Not Finished` when `save_api_request=true`). When only some services fail, the `200` response carries their failures in `database_validation.errors`. **Sandbox.** Keys from sandbox applications skip the registry calls and billing and return a static `full_match` response — the sandbox payload always includes `services_used` and `match_score: 100` regardless of how `services` was sent, so don't validate the live extended-shape gating or the 0.0–1.0 `match_score` fraction against sandbox responses. Send the request as `application/json`, or as `multipart/form-data` when uploading a `selfie`. ## Address-based services For services that validate a residential or utility address, you can send a single `address` and Didit will split it before processing the check. For the best match rate, send structured Didit address fields directly: | Field | Meaning | | - | - | | `address_element_1` | Street address, including number and street type | | `address_element_2` | Optional unit, building, floor, or extra address line | | `address_element_3` | Suburb, district, locality, or neighborhood | | `address_element_4` | City, town, state, province, or region | | `address_element_5` | Postcode or postal code | Structured fields override the single `address` value. `postal_code` is accepted as an alias for `address_element_5`. ## Consent Some database services require explicit end-user consent before the provider can be queried. The service catalog marks these rows with `requires_consent=true`. Send `consent=true` when the user consent applies to the selected services. Didit rejects the request before any provider call or billing event if a selected service requires consent and you do not send it. ## File uploads Database validation uses `multipart/form-data`. Biometric services that require `selfie` expose it as a file upload field in the API playground, so you can select an image directly instead of pasting a path or base64 string. In code, upload the file with normal multipart syntax: ```bash theme={null} -F "selfie=@./selfie.jpg" ``` ## Validation errors Didit validates required fields, address structure, and service-specific formats before calling the provider. For example, China registry services such as `chn_national_id` and `chn_passport_verification` expect `full_name` in the original Chinese script, and `chn_national_id` also requires a valid 15- or 18-character Chinese national ID with a correct checksum. If a request cannot run, the API returns explicit field errors and no usage is billed. If a provider fails after preflight, the response includes `validation_errors`, and saved API requests store those errors in the database validation result. ## Rejected input and unavailable results When no service returns a usable result, inspect each `validation_errors` entry before deciding whether to retry. The HTTP status alone does not determine whether retrying is appropriate. A `400` response with `code: "provider_rejected_input"` and `retryable: false` means every unanswered attempt explicitly refused the input. Correct the supplied data before trying again. These attempts are not billed. A `502` response with `code: "empty_provider_response"` and `retryable: true` means the service could not produce a usable result for another reason. This includes a refused input followed by an unavailable fallback or a fallback that provides no explanation. Retry later; the response does not establish that the input is wrong. If a database keeps failing, Didit emails the organizations that recently used it once the interruption is sustained, and again when real checks confirm it is answering — see [Availability notifications](/core-technology/database-validation/overview#availability-notifications). When only some of the selected services fail, the request succeeds instead: the response is `200` and the failed services are listed under `database_validation.errors[]`, each with the same `code` and `retryable` fields. `database_validation.status` then follows the services that did answer and can be `Approved`, so inspect `errors[]` on every response and not only on a `4xx` or `5xx`. A service reported there is absent from `validations` and `services_used`, and is not billed; retry that service on its own. Other `502` errors can require corrected input. For example, `provider_invalid_input` and `provider_validation_error` describe input the source rejected and must not be retried unchanged, even when the legacy response omits `retryable`. The retry guidance for `empty_provider_response` does not apply to these codes. A conclusive no-match result is a completed check, not an availability failure. ## OpenAPI ````yaml POST /v3/database-validation/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: Identity verification API. Authenticate with x-api-key header. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/database-validation/: post: tags: - Standalone APIs summary: Database Validation (standalone) description: >- Validate a person's identity data against official government and registry sources — CPF in Brazil, RENAPER in Argentina, DNI registries in Spain and Peru, INE in Mexico, and 100+ more services across 60+ countries. **Service selection.** Each country exposes one or more catalog services identified by a `service_id` (e.g. `bra_cpf`, `arg_renaper`, `pan_cedula_sib`). Pin the services you want with the `services` array — if you omit it, exactly **one** default service runs (the longest-established live service for the country). Sending `services` also switches the response to the extended shape with `services_used` and `match_score`. Discover services, their required fields, and prices via `GET /v1/organization/database-validation-countries/` (a catalog endpoint not documented in this spec) or the Business Console workflow editor. Some services are flagged `requires_consent=true` in the catalog and demand `consent=true`; others require onboarding for your organization before they can be called. **Input fields.** `identification_number` is a universal field that maps to the right country-specific field automatically (see its description). Country format rules are enforced before any provider is called (e.g. BRA CPF must be exactly 11 digits) and format failures are never billed. Biometric services need a `selfie` upload (multipart only); Argentina RENAPER additionally requires `gender`. **Results.** Each service returns a field-by-field `validation` map plus a vendor-neutral `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`). Note the distinctions: `NO_MATCH` is a definitive mismatch, `INCONCLUSIVE` means the registry could not confirm either way (review, not decline), and `BIOMETRIC_IMAGE_UNUSABLE` is a technical selfie problem (retake), unlike the definitive `BIOMETRIC_NO_MATCH`. The overall `match_type` aggregates across services (any full → `full_match`, else any partial → `partial_match`, else `no_match`) and `no_match_action`/`partial_match_action` translate it into the final `status`. `validation_type` is derived: `two_by_two` when two or more distinct services produced a full match (on the identification number, on full name + date of birth together, or on the address without contradictions), else `one_by_one`. **Persistence.** `save_api_request` defaults to **true**: the result is stored as a session (`request_id` works with `GET /v3/session/{sessionId}/decision/`), appears in the console, and fires a `status.updated` webhook. It also controls the `validations` shape — per-service objects when saved, a merged `{field: match}` map when not. **Billing.** Per-service: each service that returns a billable result is charged its own catalog price. Failed or skipped services are not billed, and requests rejected with `400` cost nothing. The pre-flight balance check covers the sum of the selected services' prices (`403` when short). **Failures.** When no selected service returns a usable result, the API returns `400` with `validation_errors` if every unanswered attempt explicitly refused the input (`provider_rejected_input`, `retryable: false`). Correct the input before trying again. Otherwise it returns `502` with `validation_errors` (`empty_provider_response`, `retryable: true`), including mixed input rejection and unavailable fallback attempts; nothing is billed (a session is still recorded with status `Not Finished` when `save_api_request=true`). When only some services fail, the `200` response carries their failures in `database_validation.errors`. **Sandbox.** Keys from sandbox applications skip the registry calls and billing and return a static `full_match` response — the sandbox payload always includes `services_used` and `match_score: 100` regardless of how `services` was sent, so don't validate the live extended-shape gating or the 0.0–1.0 `match_score` fraction against sandbox responses. Send the request as `application/json`, or as `multipart/form-data` when uploading a `selfie`. 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** country code of the registry to validate against (e.g. `BRA`, `ESP`, `COL`). Determines which services are available. Unsupported codes return `400` with the full list of valid options. example: BRA services: type: array items: type: string description: >- Catalog `service_id`s to run for this country (e.g. `["bra_cpf"]`). Also accepts a single string or a comma-separated/JSON-encoded string. **If omitted or empty, exactly one default service runs** — the longest-established live service for the country; newer, biometric, and pay-as-you-go services must be named explicitly. Sending `services` switches the response to the extended shape (adds `services_used` and `match_score`). Every id must exist and be live for the `issuing_state`; services that require onboarding return `400` until activated for your organization. Discover available services per country via `GET /v1/organization/database-validation-countries/` (a catalog endpoint not documented in this spec) or the Business Console workflow editor. example: - bra_cpf validation_type: type: string deprecated: true description: >- DEPRECATED. Accepted for backward compatibility but ignored — the response `validation_type` is now derived from how many services full-matched. Use `services` to pin specific services. consent: type: boolean default: false description: >- Set to `true` when the end user has explicitly consented to the selected validation services. Required for services flagged `requires_consent=true` in the catalog — without it those services return `400` with `services_requiring_consent`. identification_number: type: string description: >- Universal identification number — automatically mapped to the correct country-specific field, so you can use it instead of `personal_number`/`tax_number`/`document_number`: ARG→document_number (DNI), BOL→document_number (CI), BRA→tax_number (CPF, 11 digits), CHL→personal_number (RUT), COL→personal_number (Cédula), CRI→personal_number (Cédula), DOM→personal_number (Cédula, 11 digits), ECU→personal_number (Cédula, 10 digits), ESP→personal_number (DNI/NIE), GTM→document_number (DPI), HND→document_number (DNI), MEX→personal_number (CURP, 18 chars), PAN→personal_number (Cédula), PER→personal_number (DNI, 8 digits), PRY→document_number (CI), SLV→document_number (DUI), URY→personal_number (CI), VEN→document_number (Cédula). It never overrides an explicitly provided country-specific field. first_name: type: string description: >- The individual's first name. Required by some services/countries. example: John last_name: type: string description: >- The individual's last name. Required by some services/countries. example: Doe middle_name: type: string description: Middle name, used by some country services (AUS, NZL, …). full_name: type: string description: >- Full name — some services accept this in lieu of first/last name (e.g. CHN services, which match the native-script name). date_of_birth: type: string format: date description: Date of birth, `YYYY-MM-DD`. Required by many services. example: '1980-01-01' personal_number: type: string description: >- Government-issued unique personal identifier. Used by: CHL (RUT), COL (Cédula), CRI, DOM, ECU, ESP (DNI/NIE), MEX (CURP), PAN (Cédula), PER (DNI), URY. Consider `identification_number` instead. tax_number: type: string description: >- Tax identification number. Used by: BRA (CPF, 11 digits). Consider `identification_number` instead. document_number: type: string description: >- Document number. Used by: ARG (DNI), BOL (CI), GTM (DPI), HND (DNI), PRY (CI), SLV (DUI), VEN (Cédula). Consider `identification_number` instead. document_type: type: string enum: - P - DL - ID - RP - SSC - HIC - WP - TC - VISA - PSC - BC - OTHER description: >- Type of document being validated: `P` passport, `DL` driver license, `ID` national ID, `RP` residence permit (plus `SSC`, `HIC`, `WP`, `TC`, `VISA`, `PSC`, `BC`, `OTHER`). Required by some services (e.g. ESP). expiration_date: type: string format: date description: >- Document expiration date, `YYYY-MM-DD`. Required for ESP (Spain) validation. example: '2030-01-15' date_of_issue: type: string format: date description: >- Document issue date, `YYYY-MM-DD` (fecha de expedición). Required for COL (Colombia) cédula validation. example: '2015-06-20' nationality: type: string description: >- Nationality as ISO 3166-1 alpha-3. Required by some services. gender: type: string enum: - M - F - X description: >- Gender: `M`, `F`, or `X` (other/unknown). Required for Argentina's RENAPER validation (`arg_renaper`). address: description: >- Residential address. Prefer the structured object `{"street_1":"123 Main St","street_2":"Apt 4B","city":"Springfield","region":"IL","postal_code":"62701","country":"US"}`; a complete single-line string is still accepted. Required by address-verification services; when a service defines address requirements, missing parts return `400` with `address_fields_required_by`. 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: Complete single-line address (legacy). address_element_1: type: string description: >- Street address including street number and type. If omitted, derived from `address`. address_element_2: type: string description: >- Apartment, unit, building, floor, or extra address line. Only send when you have it explicitly. address_element_3: type: string description: >- City, suburb, district, locality, or neighborhood. If omitted, derived from `address`. address_element_4: type: string description: >- State, province, region, or town. If omitted, derived from `address`. address_element_5: type: string description: >- Postcode or postal code. `postal_code` is accepted as an alias. postal_code: type: string description: >- Postal code for address-based services (alias of `address_element_5`). driver_license_number: type: string description: >- Driver licence number for government document-verification services (AUS, NZL, IND). driver_license_card_number: type: string description: >- Physical driver licence card number, where required separately from the licence number (AUS). driver_license_state: type: string description: Driver licence state or territory of issue (AUS). driver_license_version: type: string description: Driver licence version code (NZL). passport_number: type: string description: >- Passport number for government passport-verification services (AUS, NZL, IND, CHN). passport_expiration_date: type: string format: date description: >- Passport expiry date, `YYYY-MM-DD`, for passport-verification services. passport_file_number: type: string description: Passport file number (IND). passport_issue_country: type: string description: >- Issuing country of the passport (ISO 3166-1 alpha-3) for passport-verification services. medicare_card_number: type: string description: Medicare card number (AUS). immi_card_number: type: string description: Australian ImmiCard number. immi_card_expiry_date: type: string format: date description: Australian ImmiCard expiry date. citizenship_certificate_number: type: string description: Citizenship certificate number (AUS). birth_registration_number: type: string description: Birth-certificate registration number (AUS). birth_registration_date: type: string format: date description: Birth-certificate registration date (AUS). birth_registration_state: type: string description: Birth-certificate registration state (AUS). marriage_certificate_number: type: string description: Marriage certificate number (AUS). change_of_name_certificate_number: type: string description: Change-of-name certificate number (AUS). first_partner_name: type: string description: First name of the partner on a marriage certificate (AUS). last_partner_name: type: string description: Last name of the partner on a marriage certificate (AUS). voter_id: type: string description: Voter registration number (IND EPIC, IRL). epic_card: type: string description: India EPIC voter card number. pan: type: string description: India PAN (Permanent Account Number). national_id: type: string description: National ID number (CHN, MYS, KEN, KHM, NGA, ZAF, …). cic: type: string description: >- Mexican INE/IFE Código de Identificación de Credencial (CIC), 9 digits. Used by the MEX INE credential-validity service (`mex_ine_vigencia`). identificador_ciudadano: type: string description: >- Mexican INE Identificador del Ciudadano (9 digits). Used with `cic` for modern INE models (E/F/G/H) in `mex_ine_vigencia`. ocr: type: string description: >- Mexican INE OCR number (13 digits, back of card). Used with `cic` for Model D in `mex_ine_vigencia`. voter_number: type: string description: >- Mexican INE Clave de Elector (18 chars). Used with `emission_number` for legacy IFE models (A/B/C) in `mex_ine_vigencia`. emission_number: type: string description: >- Mexican INE Número de Emisión. Used with `voter_number` for legacy IFE models (A/B/C) in `mex_ine_vigencia`. bvn: type: string description: Nigerian Bank Verification Number. bank_card_number: type: string description: Bank card number (CHN bank-card verification). ssn: type: string description: Social Security Number (USA). phone: type: string description: Phone number for phone-verification services. landline: type: string description: Landline number for phone-verification services. email: type: string format: email description: Email address for identity-verification services. country_of_residence: type: string description: >- ISO 3166-1 alpha-2 country of residence. Used by global identity-enrichment services (e.g. `glb_identity_enrichment`) to focus the lookup. example: US partial_match_action: type: string enum: - DECLINE - NO_ACTION default: NO_ACTION description: >- What a `partial_match` does to `database_validation.status`. Defaults to `NO_ACTION` (status stays `Approved`, with a warning). no_match_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- What a `no_match` does to `database_validation.status`. Defaults to `DECLINE`. save_api_request: type: boolean default: true description: >- Persist the validation as a session (console visibility, decision endpoint, `status.updated` webhook). Also changes the `validations` response shape: per-service objects when `true` (default), a merged field map when `false`. vendor_data: type: string description: >- Your identifier for the validated user; echoed back and stored with the session. metadata: type: object nullable: true description: Free-form JSON stored with the request and echoed back. multipart/form-data: schema: type: object required: - issuing_state properties: issuing_state: type: string description: >- ISO 3166-1 **alpha-3** country code of the registry to validate against (e.g. `BRA`, `ESP`, `COL`). Determines which services are available. Unsupported codes return `400` with the full list of valid options. example: BRA services: type: array items: type: string description: >- Catalog `service_id`s to run for this country (e.g. `["bra_cpf"]`). Also accepts a single string or a comma-separated/JSON-encoded string. **If omitted or empty, exactly one default service runs** — the longest-established live service for the country; newer, biometric, and pay-as-you-go services must be named explicitly. Sending `services` switches the response to the extended shape (adds `services_used` and `match_score`). Every id must exist and be live for the `issuing_state`; services that require onboarding return `400` until activated for your organization. Discover available services per country via `GET /v1/organization/database-validation-countries/` (a catalog endpoint not documented in this spec) or the Business Console workflow editor. example: - bra_cpf validation_type: type: string deprecated: true description: >- DEPRECATED. Accepted for backward compatibility but ignored — the response `validation_type` is now derived from how many services full-matched. Use `services` to pin specific services. consent: type: boolean default: false description: >- Set to `true` when the end user has explicitly consented to the selected validation services. Required for services flagged `requires_consent=true` in the catalog — without it those services return `400` with `services_requiring_consent`. identification_number: type: string description: >- Universal identification number — automatically mapped to the correct country-specific field, so you can use it instead of `personal_number`/`tax_number`/`document_number`: ARG→document_number (DNI), BOL→document_number (CI), BRA→tax_number (CPF, 11 digits), CHL→personal_number (RUT), COL→personal_number (Cédula), CRI→personal_number (Cédula), DOM→personal_number (Cédula, 11 digits), ECU→personal_number (Cédula, 10 digits), ESP→personal_number (DNI/NIE), GTM→document_number (DPI), HND→document_number (DNI), MEX→personal_number (CURP, 18 chars), PAN→personal_number (Cédula), PER→personal_number (DNI, 8 digits), PRY→document_number (CI), SLV→document_number (DUI), URY→personal_number (CI), VEN→document_number (Cédula). It never overrides an explicitly provided country-specific field. first_name: type: string description: >- The individual's first name. Required by some services/countries. example: John last_name: type: string description: >- The individual's last name. Required by some services/countries. example: Doe middle_name: type: string description: Middle name, used by some country services (AUS, NZL, …). full_name: type: string description: >- Full name — some services accept this in lieu of first/last name (e.g. CHN services, which match the native-script name). date_of_birth: type: string format: date description: Date of birth, `YYYY-MM-DD`. Required by many services. example: '1980-01-01' personal_number: type: string description: >- Government-issued unique personal identifier. Used by: CHL (RUT), COL (Cédula), CRI, DOM, ECU, ESP (DNI/NIE), MEX (CURP), PAN (Cédula), PER (DNI), URY. Consider `identification_number` instead. tax_number: type: string description: >- Tax identification number. Used by: BRA (CPF, 11 digits). Consider `identification_number` instead. document_number: type: string description: >- Document number. Used by: ARG (DNI), BOL (CI), GTM (DPI), HND (DNI), PRY (CI), SLV (DUI), VEN (Cédula). Consider `identification_number` instead. document_type: type: string enum: - P - DL - ID - RP - SSC - HIC - WP - TC - VISA - PSC - BC - OTHER description: >- Type of document being validated: `P` passport, `DL` driver license, `ID` national ID, `RP` residence permit (plus `SSC`, `HIC`, `WP`, `TC`, `VISA`, `PSC`, `BC`, `OTHER`). Required by some services (e.g. ESP). expiration_date: type: string format: date description: >- Document expiration date, `YYYY-MM-DD`. Required for ESP (Spain) validation. example: '2030-01-15' date_of_issue: type: string format: date description: >- Document issue date, `YYYY-MM-DD` (fecha de expedición). Required for COL (Colombia) cédula validation. example: '2015-06-20' nationality: type: string description: >- Nationality as ISO 3166-1 alpha-3. Required by some services. gender: type: string enum: - M - F - X description: >- Gender: `M`, `F`, or `X` (other/unknown). Required for Argentina's RENAPER validation (`arg_renaper`). address: description: >- Residential address. Prefer the structured object `{"street_1":"123 Main St","street_2":"Apt 4B","city":"Springfield","region":"IL","postal_code":"62701","country":"US"}`; a complete single-line string is still accepted. Required by address-verification services; when a service defines address requirements, missing parts return `400` with `address_fields_required_by`. 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: Complete single-line address (legacy). address_element_1: type: string description: >- Street address including street number and type. If omitted, derived from `address`. address_element_2: type: string description: >- Apartment, unit, building, floor, or extra address line. Only send when you have it explicitly. address_element_3: type: string description: >- City, suburb, district, locality, or neighborhood. If omitted, derived from `address`. address_element_4: type: string description: >- State, province, region, or town. If omitted, derived from `address`. address_element_5: type: string description: >- Postcode or postal code. `postal_code` is accepted as an alias. postal_code: type: string description: >- Postal code for address-based services (alias of `address_element_5`). driver_license_number: type: string description: >- Driver licence number for government document-verification services (AUS, NZL, IND). driver_license_card_number: type: string description: >- Physical driver licence card number, where required separately from the licence number (AUS). driver_license_state: type: string description: Driver licence state or territory of issue (AUS). driver_license_version: type: string description: Driver licence version code (NZL). passport_number: type: string description: >- Passport number for government passport-verification services (AUS, NZL, IND, CHN). passport_expiration_date: type: string format: date description: >- Passport expiry date, `YYYY-MM-DD`, for passport-verification services. passport_file_number: type: string description: Passport file number (IND). passport_issue_country: type: string description: >- Issuing country of the passport (ISO 3166-1 alpha-3) for passport-verification services. medicare_card_number: type: string description: Medicare card number (AUS). immi_card_number: type: string description: Australian ImmiCard number. immi_card_expiry_date: type: string format: date description: Australian ImmiCard expiry date. citizenship_certificate_number: type: string description: Citizenship certificate number (AUS). birth_registration_number: type: string description: Birth-certificate registration number (AUS). birth_registration_date: type: string format: date description: Birth-certificate registration date (AUS). birth_registration_state: type: string description: Birth-certificate registration state (AUS). marriage_certificate_number: type: string description: Marriage certificate number (AUS). change_of_name_certificate_number: type: string description: Change-of-name certificate number (AUS). first_partner_name: type: string description: First name of the partner on a marriage certificate (AUS). last_partner_name: type: string description: Last name of the partner on a marriage certificate (AUS). voter_id: type: string description: Voter registration number (IND EPIC, IRL). epic_card: type: string description: India EPIC voter card number. pan: type: string description: India PAN (Permanent Account Number). national_id: type: string description: National ID number (CHN, MYS, KEN, KHM, NGA, ZAF, …). cic: type: string description: >- Mexican INE/IFE Código de Identificación de Credencial (CIC), 9 digits. Used by the MEX INE credential-validity service (`mex_ine_vigencia`). identificador_ciudadano: type: string description: >- Mexican INE Identificador del Ciudadano (9 digits). Used with `cic` for modern INE models (E/F/G/H) in `mex_ine_vigencia`. ocr: type: string description: >- Mexican INE OCR number (13 digits, back of card). Used with `cic` for Model D in `mex_ine_vigencia`. voter_number: type: string description: >- Mexican INE Clave de Elector (18 chars). Used with `emission_number` for legacy IFE models (A/B/C) in `mex_ine_vigencia`. emission_number: type: string description: >- Mexican INE Número de Emisión. Used with `voter_number` for legacy IFE models (A/B/C) in `mex_ine_vigencia`. bvn: type: string description: Nigerian Bank Verification Number. bank_card_number: type: string description: Bank card number (CHN bank-card verification). ssn: type: string description: Social Security Number (USA). phone: type: string description: Phone number for phone-verification services. landline: type: string description: Landline number for phone-verification services. email: type: string format: email description: Email address for identity-verification services. country_of_residence: type: string description: >- ISO 3166-1 alpha-2 country of residence. Used by global identity-enrichment services (e.g. `glb_identity_enrichment`) to focus the lookup. example: US partial_match_action: type: string enum: - DECLINE - NO_ACTION default: NO_ACTION description: >- What a `partial_match` does to `database_validation.status`. Defaults to `NO_ACTION` (status stays `Approved`, with a warning). no_match_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- What a `no_match` does to `database_validation.status`. Defaults to `DECLINE`. save_api_request: type: boolean default: true description: >- Persist the validation as a session (console visibility, decision endpoint, `status.updated` webhook). Also changes the `validations` response shape: per-service objects when `true` (default), a merged field map when `false`. vendor_data: type: string description: >- Your identifier for the validated user; echoed back and stored with the session. metadata: type: object nullable: true description: Free-form JSON stored with the request and echoed back. selfie: type: string format: binary description: >- Selfie image (`jpg`, `jpeg`, `png`, `webp`; max 2 MB — images are compressed to ~1.5 MB before upload to the registry) for biometric validation services, e.g. Argentina RENAPER (`arg_renaper`) and Panama SIB (`pan_cedula_sib`, `pan_cedula_sib_plus`). Required whenever a selected service lists it as a required field. Only available via `multipart/form-data`. responses: '200': description: >- Validation completed — at least one selected service returned a usable result. Inspect `database_validation.match_type` for the aggregate outcome, `validations` for the per-service field comparisons and `outcome_code`s, and `errors` (when present) for services that failed. content: application/json: schema: type: object properties: request_id: type: string format: uuid description: >- Persisted session id when `save_api_request=true` (usable with `GET /v3/session/{sessionId}/decision/`); otherwise a transient correlation UUID. database_validation: type: object properties: status: type: string enum: - Approved - Declined - In Review description: >- `Declined` when the overall `match_type` triggers a `DECLINE` action (`no_match_action` defaults to `DECLINE`, `partial_match_action` to `NO_ACTION`); `In Review` when no service produced a usable comparison, for example when the only selected service came back `REGISTRY_UNAVAILABLE` or `INCONCLUSIVE`; `Approved` otherwise. A request that selected several services can be `Approved` on one service's match while another was unavailable, so check `errors` and the per-service `outcome_code`s too. issuing_state: type: string description: >- Echo of the ISO 3166-1 alpha-3 country validated against. example: BRA validation_type: type: string enum: - one_by_one - two_by_two description: >- Derived from the results: `two_by_two` when ≥2 distinct services produced a full match (on the identification number, on full name + date of birth together, or on the address without contradictions); `one_by_one` otherwise. (The request field of the same name is deprecated and ignored.) screened_data: type: object description: >- Echo of the input fields that were sent to the selected services (dates normalized to `YYYY-MM-DD`; a `selfie`, when sent, is returned as a pre-signed URL; `consent_obtained: true` is added when consent was given). match_type: type: string nullable: true enum: - full_match - partial_match - no_match description: >- Overall result aggregated across services with field-level comparisons: any `full_match` → `full_match`; else any `partial_match` → `partial_match`; else `no_match`. Outcome-only services, such as biometric criminal screening, can return `null`; inspect each item in `validations` for its `outcome_code`. validations: description: >- Shape depends on `save_api_request`. **`true` (default):** an array of per-service objects (`service_id`, `service_name`, `validation`, `outcome_code`, `outcome_detail`, `source_data`). **`false`:** a single flat object merging the field-level results of all services (`{"full_name": "full_match", ...}`). oneOf: - type: array items: type: object description: >- Per-service validation result (returned when `save_api_request=true`, the default). properties: service_id: type: string description: >- Catalog id of the service that produced this result (e.g. `bra_cpf`). example: bra_cpf service_name: type: string description: Human-readable catalog name of the service. example: Brazil - CPF status check validation: type: object description: >- Field-by-field comparison between your input and the registry record. Keys are canonical field names (`full_name`, `date_of_birth`, `identification_number`, `address`, …); values are `full_match`, `partial_match`, or `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: >- Vendor-neutral outcome of the registry lookup. `MATCH`/`PARTIAL_MATCH`/`NO_MATCH` describe the comparison; `DOCUMENT_NOT_FOUND` means the identifier is not in the registry; `INCONCLUSIVE` means the registry could not confirm either way (routed to review — NOT a no-match); `BIOMETRIC_NO_MATCH` is a definitive face mismatch while `BIOMETRIC_IMAGE_UNUSABLE` is a technical image problem (retake the selfie); `DECEASED`/`MINOR_BLOCKED` are registry-policy outcomes; `DOCUMENT_SUPERSEDED` means the identity matched but the edition of the document presented is not the one on file (a newer edition has been issued); `INVALID_DOCUMENT_FORMAT`/`INVALID_INPUT` mean the registry itself rejected the data it was sent; `REGISTRY_UNAVAILABLE`/`REGISTRY_ERROR` indicate upstream failures. outcome_detail: type: string nullable: true description: >- Raw upstream status detail backing the outcome code (e.g. an HTTP or registry status code). source_data: type: object nullable: true description: >- Cleaned, normalized view of the registry record using canonical field names (`identification_number`, `first_name`, `last_name`, `date_of_birth`, plus registry-specific flags). Image fields, when present, are returned as pre-signed URLs. - type: object additionalProperties: type: string enum: - full_match - partial_match - no_match description: >- Merged field-level results (stateless `save_api_request=false` shape). warnings: type: array items: type: object properties: feature: type: string description: Feature that raised the warning. risk: type: string description: Machine-readable risk identifier. additional_data: type: object nullable: true description: Extra context for the warning, when available. log_type: type: string description: >- `warning`, `information`, or `error` — how the risk affected the outcome. short_description: type: string description: One-line human-readable summary. long_description: type: string description: Full human-readable explanation. description: >- `DATABASE_VALIDATION_NO_MATCH` or `DATABASE_VALIDATION_PARTIAL_MATCH` when applicable; empty on a full match. errors: type: array description: >- Present only when some (but not all) selected services failed. Each entry carries `service_id`, `code`, `message`, and `retryable`. A service reported here is absent from `validations` and `services_used`, and is not billed. This array is the only place it appears, so inspect it even when `status` is `Approved`. items: type: object properties: service_id: type: string code: type: string example: empty_provider_response message: type: string retryable: type: boolean description: >- `true` when the service produced no answer and retrying it later can succeed; `false` when the source refused the data it was sent and the input must be corrected first. example: true services_used: type: array items: type: string description: >- Catalog ids of the services that returned a billable result. **Only present when the request explicitly sent `services`.** match_score: type: number description: >- Fraction (0.0–1.0) of attempted services that produced a full match (on the identification number, on full name + date of birth together, or on the address without contradictions). **Only present when the request explicitly sent `services`.** vendor_data: type: string nullable: true description: Echo of the `vendor_data` you sent. metadata: type: object nullable: true description: Echo of the `metadata` you sent. created_at: type: string format: date-time examples: Full match (Approved): summary: >- Default save_api_request=true — per-service `validations` objects 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: >- Request sent `services` — response adds `services_used` and `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: >- Registry record does not match — default `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` collapses to a merged field map; nothing is stored 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: >- Validation error - nothing is billed. Preflight field errors occur before any external call. If every unanswered attempt explicitly refuses the input, the response instead includes `validation_errors` with `code: provider_rejected_input` and `retryable: false`; correct the input before retrying. Field-level problems use DRF's standard envelope; catalog problems return a `services` array (plus `requires_onboarding` or `services_requiring_consent` when relevant); missing-field errors include `fields_required_by` mapping each missing field to the services that demand it; services that need at least one extra identifier (e.g. `usa_states_credit_bureau`, which cannot verify a name alone) return `any_field_required_by` mapping each service to the fields of which at least one must be present; format problems checked per service return `invalid_fields_by_service`. content: application/json: examples: Invalid issuing_state: summary: >- Country not supported — message lists every valid alpha-3 code 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: >- Union of required fields across selected services, with the universal-field hint 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` contains an id that is not in the catalog' value: services: - 'Unknown service_id(s): [''bogus_service'']' Service not live for country: summary: >- `services` names a service from another country (or a stub entry) value: services: - >- Services not currently live for PER: ['bra_cpf']. Available services: ['per_dni', 'per_residential', 'per_tax_registration'] Service requires onboarding: summary: >- Service exists but is not activated for your organization yet 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: >- A selected service is flagged requires_consent=true and `consent` was not `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: >- Identifier fails the country's format rule (length/digits/regex) 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: A field fails the selected service's own format requirements 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: Correct the input before retrying 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: Request-level explanation or preflight field errors. oneOf: - type: string - type: array items: type: string validation_errors: type: array description: >- Present when every unanswered attempt refused the input after preflight. items: type: object properties: service_id: type: string code: type: string message: type: string retryable: type: boolean description: >- Whether retrying later can resolve this service failure. False means correct the supplied input first. '403': description: >- Permission denied. Returned when the `x-api-key` header is missing, malformed, revoked, or belongs to another environment — and also when the calling organization's balance cannot cover the call. Authentication failures return `403` with `{"detail": ...}`; this API never returns `401`. Credit shortfalls return `403` with `{"error": ...}` before any screening or provider call happens. content: application/json: examples: Missing or invalid API key: summary: No `x-api-key` header, or the key is invalid/revoked value: detail: You do not have permission to perform this action. Not enough credits: summary: Organization balance cannot cover the call value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Rate limit exceeded. All POST/PATCH/DELETE endpoints share a budget of 300 write requests per minute per API key. The response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, and `Retry-After` headers. content: application/json: examples: Write rate limit exceeded: summary: More than 300 write requests in the current minute 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: >- No selected service returned a usable result. Inspect each validation_errors entry before retrying; HTTP 502 alone does not establish a transient failure. An empty_provider_response with retryable: true indicates unavailable or unexplained results, including a refused primary followed by an unavailable fallback. Legacy provider_invalid_input and provider_validation_error entries instead require corrected input and may omit retryable. Nothing is billed. When save_api_request=true, the failed attempt is recorded as a session with status Not Finished. Partial failures return 200 with database_validation.errors. 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: >- Whether retrying later can resolve this service failure. False means correct the supplied input first. examples: Provider returned no result: summary: Every selected service failed 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: >- import os, requests resp = requests.post( "https://verification.didit.me/v3/database-validation/", headers={"x-api-key": os.environ["DIDIT_API_KEY"]}, json={ "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", }, timeout=45, ) resp.raise_for_status() dv = resp.json()["database_validation"] print(dv["status"], dv["match_type"]) # e.g. Approved full_match # Biometric services need a selfie via multipart/form-data: # requests.post(..., data={"issuing_state": "ARG", "services": '["arg_renaper"]', # "identification_number": "12345678", "gender": "M", ...}, # files={"selfie": open("selfie.jpg", "rb")}) - lang: javascript label: JavaScript source: >- const res = await fetch('https://verification.didit.me/v3/database-validation/', { method: 'POST', headers: { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ 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', }), }); const data = await res.json(); console.log(data.database_validation.status, data.database_validation.match_type); components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.