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

Your application's API key, from Developers -> API keys in the Business Console. The primary key has full access. A named key can be scoped: none, read or write per resource, limited to some workflows or to approved sessions, to a list of IP addresses, and to an expiry date. 401 means the key is wrong, revoked or expired; 403 means no key was sent, the key has no access to this resource or action, or the request came from an address outside its IP list; 404 on a session route means the session is outside the key's workflows or statuses. A key without media access receives image, video and PDF URLs as null, and a key without sessions write receives session links and tokens as null. See https://docs.didit.me/console/api-keys.

Headers

Idempotency-Key
string

Optional retry-safety key you choose for one operation, up to 255 characters (a UUID works). A request repeated with the same key, endpoint, query and body is answered with the first response, same status and same body, and runs and bills nothing a second time. The same key with another endpoint, query or body returns 409 idempotency_key_reused, and while the first request is still running, 409 idempotency_key_in_progress with Retry-After. A failed request (any 4xx or 5xx) is not stored, so you can send it again with the same key. Keys belong to your application, whether you call with an API key or an access token. See Retries and idempotency.

Required string length: 1 - 255

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.

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.

electoral_roll_only
boolean
default:false

Paraguay (pry_cedula) only. Set to true to check the cédula against the TSJE electoral roll alone. The electoral roll lists only citizens aged 18 or over, so a MATCH also confirms that the holder is an adult, and a cédula that is not on the roll returns DOCUMENT_NOT_FOUND. Defaults to false, which also checks the DNIT taxpayer register for wider identity coverage but cannot confirm age. Any other service rejects it with 400.

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

company_registration_number
string

Company registration number as issued by the companies register: the CNPJ in Brazil (e.g. 11222333000181), the registration number in South Africa (e.g. 1936/007721/06). Required by the company registry and company directors services (bra_company_registry, bra_company_directors, zaf_company_registry, zaf_company_directors).

company_name
string

Registered company name, cross-checked against the register entry. Optional for zaf_company_registry.

initials
string

The person's initials as printed on the document. Required by zaf_drivers_license; accepted by zaf_bank_account_holder.

licence_number
string

Driving licence number as printed on the card, for zaf_drivers_license. When omitted, document_number is used.

refugee_file_number
string

Refugee file number issued by South Africa's Department of Home Affairs. Required by zaf_refugee.

bank_name
string

Name of the bank that holds the account. Required by zaf_bank_account_holder.

bank_account_number
string

Bank account number. Required by zaf_bank_account_holder; accepted by zaf_fraud_prevention.

account_type
string

Bank account type for zaf_bank_account_holder: current, savings, transmission, subscriptionShare or notKnown, case-insensitive. Any other value returns 400. Omit it when you do not know the type: the account-type cross-check is then reported as not confirmed.

phone_number
string

Contact mobile number, for the services that cross-check contactability (zaf_bank_account_holder, zaf_fraud_prevention, zaf_refugee).

right_thumb
string

Base64-encoded right thumb fingerprint for zaf_dha_fingerprint_match, with left_thumb or on its own.

left_thumb
string

Base64-encoded left thumb fingerprint for zaf_dha_fingerprint_match, with right_thumb or on its own.

score_level
integer

Minimum biometric score level for zaf_criminal_face_screening. Defaults to 3.

max_matches
integer

Maximum number of candidate matches zaf_criminal_face_screening returns. Defaults to 1.

vehicle_register_number
string

Vehicle register number. Required, with vehicle_licence_plate and vin, by zaf_vehicle_ownership.

vehicle_licence_plate
string

Vehicle licence plate number. Required, with vehicle_register_number and vin, by zaf_vehicle_ownership.

vin
string

Vehicle Identification Number (VIN or chassis number). Required, with vehicle_register_number and vehicle_licence_plate, by zaf_vehicle_ownership.

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. It was used only by the retired global identity-enrichment service (glb_identity_enrichment), which Didit no longer offers.

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>
Last modified on November 1, 2026