Skip to main content
POST
curl

​
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: Structured fields override the single address value. postal_code is accepted as an alias for address_element_5. 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:

​
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. 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.

Authorizations

​
x-api-key
string
header
required

Body

​
issuing_state
string
required

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
string[]

Catalog service_ids 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:
​
validation_type
string
deprecated

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
boolean
default:false

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
string

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
string

The individual's first name. Required by some services/countries.

Example:

"John"

​
last_name
string

The individual's last name. Required by some services/countries.

Example:

"Doe"

​
middle_name
string

Middle name, used by some country services (AUS, NZL, …).

​
full_name
string

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
string<date>

Date of birth, YYYY-MM-DD. Required by many services.

Example:

"1980-01-01"

​
personal_number
string

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
string

Tax identification number. Used by: BRA (CPF, 11 digits). Consider identification_number instead.

​
document_number
string

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
enum<string>

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).

Available options:
P,
DL,
ID,
RP,
SSC,
HIC,
WP,
TC,
VISA,
PSC,
BC,
OTHER
​
expiration_date
string<date>

Document expiration date, YYYY-MM-DD. Required for ESP (Spain) validation.

Example:

"2030-01-15"

​
date_of_issue
string<date>

Document issue date, YYYY-MM-DD (fecha de expedición). Required for COL (Colombia) cédula validation.

Example:

"2015-06-20"

​
nationality
string

Nationality as ISO 3166-1 alpha-3. Required by some services.

​
gender
enum<string>

Gender: M, F, or X (other/unknown). Required for Argentina's RENAPER validation (arg_renaper).

Available options:
M,
F,
X
​
address

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.

​
address_element_1
string

Street address including street number and type. If omitted, derived from address.

​
address_element_2
string

Apartment, unit, building, floor, or extra address line. Only send when you have it explicitly.

​
address_element_3
string

City, suburb, district, locality, or neighborhood. If omitted, derived from address.

​
address_element_4
string

State, province, region, or town. If omitted, derived from address.

​
address_element_5
string

Postcode or postal code. postal_code is accepted as an alias.

​
postal_code
string

Postal code for address-based services (alias of address_element_5).

​
driver_license_number
string

Driver licence number for government document-verification services (AUS, NZL, IND).

​
driver_license_card_number
string

Physical driver licence card number, where required separately from the licence number (AUS).

​
driver_license_state
string

Driver licence state or territory of issue (AUS).

​
driver_license_version
string

Driver licence version code (NZL).

​
passport_number
string

Passport number for government passport-verification services (AUS, NZL, IND, CHN).

​
passport_expiration_date
string<date>

Passport expiry date, YYYY-MM-DD, for passport-verification services.

​
passport_file_number
string

Passport file number (IND).

​
passport_issue_country
string

Issuing country of the passport (ISO 3166-1 alpha-3) for passport-verification services.

​
medicare_card_number
string

Medicare card number (AUS).

​
immi_card_number
string

Australian ImmiCard number.

​
immi_card_expiry_date
string<date>

Australian ImmiCard expiry date.

​
citizenship_certificate_number
string

Citizenship certificate number (AUS).

​
birth_registration_number
string

Birth-certificate registration number (AUS).

​
birth_registration_date
string<date>

Birth-certificate registration date (AUS).

​
birth_registration_state
string

Birth-certificate registration state (AUS).

​
marriage_certificate_number
string

Marriage certificate number (AUS).

​
change_of_name_certificate_number
string

Change-of-name certificate number (AUS).

​
first_partner_name
string

First name of the partner on a marriage certificate (AUS).

​
last_partner_name
string

Last name of the partner on a marriage certificate (AUS).

​
voter_id
string

Voter registration number (IND EPIC, IRL).

​
epic_card
string

India EPIC voter card number.

​
pan
string

India PAN (Permanent Account Number).

​
national_id
string

National ID number (CHN, MYS, KEN, KHM, NGA, ZAF, …).

​
cic
string

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
string

Mexican INE Identificador del Ciudadano (9 digits). Used with cic for modern INE models (E/F/G/H) in mex_ine_vigencia.

​
ocr
string

Mexican INE OCR number (13 digits, back of card). Used with cic for Model D in mex_ine_vigencia.

​
voter_number
string

Mexican INE Clave de Elector (18 chars). Used with emission_number for legacy IFE models (A/B/C) in mex_ine_vigencia.

​
emission_number
string

Mexican INE Número de Emisión. Used with voter_number for legacy IFE models (A/B/C) in mex_ine_vigencia.

​
bvn
string

Nigerian Bank Verification Number.

​
bank_card_number
string

Bank card number (CHN bank-card verification).

​
ssn
string

Social Security Number (USA).

​
phone
string

Phone number for phone-verification services.

​
landline
string

Landline number for phone-verification services.

​
email
string<email>

Email address for identity-verification services.

​
country_of_residence
string

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
enum<string>
default:NO_ACTION

What a partial_match does to database_validation.status. Defaults to NO_ACTION (status stays Approved, with a warning).

Available options:
DECLINE,
NO_ACTION
​
no_match_action
enum<string>
default:DECLINE

What a no_match does to database_validation.status. Defaults to DECLINE.

Available options:
DECLINE,
NO_ACTION
​
save_api_request
boolean
default:true

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
string

Your identifier for the validated user; echoed back and stored with the session.

​
metadata
object | null

Free-form JSON stored with the request and echoed back.

Response

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_codes, and errors (when present) for services that failed.

​
request_id
string<uuid>

Persisted session id when save_api_request=true (usable with GET /v3/session/{sessionId}/decision/); otherwise a transient correlation UUID.

​
database_validation
object
​
vendor_data
string | null

Echo of the vendor_data you sent.

​
metadata
object | null

Echo of the metadata you sent.

​
created_at
string<date-time>