> ## 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 de validació en bases de dades: coincidència ID > Valida dades d'identitat amb Didit contra 100+ fonts nacionals i globals (coincidència 1x1 i 2x2). POST /v3/database-validation/. Preu per crida. ## Serveis basats en adreces Per als serveis que validen una adreça de residència o de subministrament, pots enviar una sola `address` i Didit la dividirà abans de processar la comprovació. Per obtenir la millor taxa de coincidència, envia directament els camps d'adreça estructurats de Didit: | Camp | Significat | | - | - | | `address_element_1` | Adreça del carrer, inclosos el número i el tipus de via | | `address_element_2` | Unitat, edifici, planta o línia addicional d'adreça (opcional) | | `address_element_3` | Barri, districte, localitat o veïnat | | `address_element_4` | Ciutat, població, estat, província o regió | | `address_element_5` | Codi postal | Els camps estructurats substitueixen el valor únic de `address`. `postal_code` s'accepta com a àlies de `address_element_5`. ## Consentiment Alguns serveis de bases de dades requereixen el consentiment explícit de l'usuari final abans que el proveïdor es pugui consultar. El catàleg de serveis marca aquestes files amb `requires_consent=true`. Envia `consent=true` quan el consentiment de l'usuari s'aplica als serveis seleccionats. Didit rebutja la sol·licitud abans de cap crida al proveïdor o cap esdeveniment de facturació si algun servei seleccionat requereix consentiment i no l'envies. ## Càrrega de fitxers La validació de bases de dades utilitza `multipart/form-data`. Els serveis biomètrics que requereixen `selfie` mostren aquest camp com a càrrega de fitxer a l'entorn de proves de l'API, de manera que pots seleccionar una imatge directament en lloc d'enganxar una ruta o una cadena en base64. Al codi, puja el fitxer amb la sintaxi multipart habitual: ```bash theme={null} -F "selfie=@./selfie.jpg" ``` ## Errors de validació Didit valida els camps obligatoris, l'estructura de l'adreça i els formats específics de cada servei abans de cridar el proveïdor. Per exemple, els serveis de registres xinesos com `chn_national_id` i `chn_passport_verification` esperen `full_name` en l'escriptura xinesa original, i `chn_national_id` també requereix un número d'identitat nacional xinès vàlid de 15 o 18 caràcters amb una suma de control correcta. Si una sol·licitud no es pot executar, l'API retorna errors explícits per camp i no es factura cap ús. Si un proveïdor falla després de la validació prèvia, la resposta inclou `validation_errors`, i les sol·licituds d'API desades emmagatzemen aquests errors al resultat de la validació de bases de dades. ## Entrada rebutjada i resultats no disponibles Quan cap servei no retorna un resultat utilitzable, revisa cada entrada de `validation_errors` abans de decidir si cal reintentar. L'estat HTTP per si sol no determina si és adequat reintentar. Una resposta `400` amb `code: "provider_rejected_input"` i `retryable: false` significa que cada intent sense resposta ha rebutjat explícitament l'entrada. Corregeix les dades subministrades abans de tornar-ho a provar. Aquests intents no es facturen. Una resposta `502` amb `code: "empty_provider_response"` i `retryable: true` significa que el servei no ha pogut produir un resultat utilitzable per un altre motiu. Això inclou una entrada rebutjada seguida d'una alternativa no disponible o d'una alternativa que no ofereix cap explicació. Torna-ho a intentar més tard; la resposta no demostra que l'entrada sigui incorrecta. Si una base de dades continua fallant, Didit envia un correu electrònic a les organitzacions que l'han utilitzat recentment quan la interrupció es prolonga, i de nou quan les comprovacions reals confirmen que torna a respondre; consulta [Notificacions de disponibilitat](https://docs.didit.me/ca/core-technology/database-validation/overview.md#notificacions-de-disponibilitat). Quan només fallen alguns dels serveis seleccionats, la sol·licitud es completa igualment: la resposta és `200` i els serveis que han fallat es mostren a `database_validation.errors[]`, cadascun amb els mateixos camps `code` i `retryable`. `database_validation.status` aleshores segueix els serveis que sí han respost i pot ser `Approved`, així que revisa `errors[]` en cada resposta i no només en una resposta `4xx` o `5xx`. Un servei que apareix allà no apareix a `validations` ni a `services_used`, i no es factura; torna a intentar aquest servei per separat. Altres errors `502` poden requerir dades corregides. Per exemple, `provider_invalid_input` i `provider_validation_error` descriuen una entrada que la font ha rebutjat i que no s'ha de reintentar sense canvis, fins i tot quan la resposta heretada no inclou `retryable`. La guia de reintent per a `empty_provider_response` no s'aplica a aquests codis. Un resultat concloent de no coincidència és una comprovació completada, no un error de disponibilitat. ## OpenAPI ````yaml ca/openapi-25.json POST /v3/database-validation/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de verificació d'identitat. Autentica't amb la capçalera x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/database-validation/: post: tags: - Standalone APIs summary: Validació en bases de dades (independent) description: >- Valida les dades d'identitat d'una persona amb fonts oficials del govern i dels registres: CPF al Brasil, RENAPER a l'Argentina, registres de DNI a Espanya i el Perú, INE a Mèxic i 100+ serveis addicionals en 60+ països. **Selecció de serveis.** Cada país exposa un o més serveis del catàleg identificats per un `service_id` (p. ex. `bra_cpf`, `arg_renaper`, `pan_cedula_sib`). Fixa els serveis que vulguis amb l'array `services`: si l'omets, s'executa exactament **un** servei per defecte (el servei en producció més consolidat per al país). Enviar `services` també canvia la resposta a l'estructura ampliada amb `services_used` i `match_score`. Descobreix serveis, els seus camps obligatoris i preus mitjançant `GET /v1/organization/database-validation-countries/` (un endpoint de catàleg no documentat en aquesta especificació) o l'editor de fluxos de treball de la Business Console. Alguns serveis tenen la marca `requires_consent=true` al catàleg i exigeixen `consent=true`; d'altres requereixen alta per a la teva organització abans de poder-los cridar. **Camps d'entrada.** `identification_number` és un camp universal que s'assigna automàticament al camp específic del país correcte (consulta'n la descripció). Les regles de format del país s'apliquen abans de cridar cap proveïdor (p. ex., el CPF de BRA ha de tenir exactament 11 xifres) i els errors de format no es facturen mai. Els serveis biomètrics necessiten la càrrega d'una `selfie` (només multipart); el RENAPER de l'Argentina requereix addicionalment `gender`. **Resultats.** Cada servei retorna un mapa de `validation` camp per camp més un `outcome_code` neutre respecte al proveïdor (`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`). Tingues en compte les distincions: `NO_MATCH` és una no coincidència definitiva, `INCONCLUSIVE` significa que el registre no ha pogut confirmar cap de les dues opcions (revisar, no rebutjar) i `BIOMETRIC_IMAGE_UNUSABLE` és un problema tècnic amb la selfie (cal repetir-la), a diferència del definitiu `BIOMETRIC_NO_MATCH`. El `match_type` global s'agrega entre serveis (qualsevol coincidència total → `full_match`, altrament qualsevol coincidència parcial → `partial_match`, altrament `no_match`) i `no_match_action`/`partial_match_action` el tradueixen a l'estat final (`status`). El `validation_type` és derivat: `two_by_two` quan dos o més serveis diferents han produït una coincidència total (sobre el número d'identificació, sobre el nom complet + data de naixement plegats, o sobre l'adreça sense contradiccions), altrament `one_by_one`. **Persistència.** `save_api_request` per defecte és **true**: el resultat s'emmagatzema com a sessió (`request_id` funciona amb `GET /v3/session/{sessionId}/decision/`), apareix a la consola i dispara un webhook `status.updated`. També controla l'estructura de `validations`: objectes per servei quan es desa, un mapa fusionat `{field: match}` quan no. **Facturació.** Per servei: a cada servei que retorna un resultat facturable se li cobra el seu propi preu de catàleg. Els serveis fallits o omesos no es facturen, i les sol·licituds rebutjades amb `400` no costen res. La comprovació prèvia de saldo cobreix la suma dels preus dels serveis seleccionats (`403` si és insuficient). **Errors.** Quan cap dels serveis seleccionats retorna un resultat utilitzable, l'API retorna `400` amb `validation_errors` si tots els intents sense resposta han rebutjat explícitament les dades d'entrada (`provider_rejected_input`, `retryable: false`). Corregeix les dades d'entrada abans de tornar-ho a provar. En cas contrari, retorna `502` amb `validation_errors` (`empty_provider_response`, `retryable: true`), inclosos els casos de rebuig d'entrades mixtes i intents de reserva no disponibles; no es factura res (es continua registrant una sessió amb estat `Not Finished` quan `save_api_request=true`). Quan només fallen alguns serveis, la resposta `200` inclou les seves fallades a `database_validation.errors`. **Sandbox.** Les claus d'aplicacions de sandbox ometen les crides als registres i la facturació, i retornen una resposta estàtica `full_match`; el payload de sandbox sempre inclou `services_used` i `match_score: 100` independentment de com s'hagi enviat `services`, de manera que no validis el condicionament de l'estructura ampliada en producció ni la fracció de 0.0–1.0 de `match_score` amb respostes del sandbox. Envia la sol·licitud com a `application/json`, o com a `multipart/form-data` quan pugis una `selfie`. operationId: post_v3database-validation parameters: [] requestBody: required: true content: application/json: schema: type: object required: - issuing_state properties: issuing_state: type: string description: >- Codi de país ISO 3166-1 **alfa-3** del registre contra el qual s'ha de validar (p. ex. `BRA`, `ESP`, `COL`). Determina quins serveis estan disponibles. Els codis no admesos retornen `400` amb la llista completa d'opcions vàlides. example: BRA services: type: array items: type: string description: >- `service_id`s de catàleg que s'han d'executar per a aquest país (p. ex., `["bra_cpf"]`). També accepta una sola cadena o una cadena separada per comes / codificada en JSON. **Si s'omet o és buit, s'executa exactament un servei per defecte** —el servei en producció més consolidat per al país; els serveis més nous, biomètrics i de pagament per ús s'han d'especificar explícitament. Enviar `services` canvia la resposta a l'estructura ampliada (afegeix `services_used` i `match_score`). Cada id ha d'existir i estar actiu per a l'`issuing_state`; els serveis que requereixen alta retornen `400` fins que s'activin per a la teva organització. Descobreix els serveis disponibles per país mitjançant `GET /v1/organization/database-validation-countries/` (un endpoint de catàleg no documentat en aquesta especificació) o l'editor de fluxos de treball de la Business Console. example: - bra_cpf validation_type: type: string deprecated: true description: >- OBSOLET. S'accepta per compatibilitat amb versions anteriors però s'ignora: el `validation_type` de la resposta ara es deriva de quants serveis han coincidit completament. Utilitza `services` per fixar serveis específics. consent: type: boolean default: false description: >- Estableix-ho a `true` quan l'usuari final hagi donat el consentiment explícit als serveis de validació seleccionats. Requerit per als serveis marcats amb `requires_consent=true` al catàleg — sense ell, aquests serveis retornen `400` amb `services_requiring_consent`. identification_number: type: string description: >- Número d'identificació universal — s'assigna automàticament al camp correcte específic de cada país, de manera que pots utilitzar-lo en lloc de `personal_number`/`tax_number`/`document_number`: ARG→document_number (DNI), BOL→document_number (CI), BRA→tax_number (CPF, 11 dígits), CHL→personal_number (RUT), COL→personal_number (Cédula), CRI→personal_number (Cédula), DOM→personal_number (Cédula, 11 dígits), ECU→personal_number (Cédula, 10 dígits), ESP→personal_number (DNI/NIE), GTM→document_number (DPI), HND→document_number (DNI), MEX→personal_number (CURP, 18 caràcters), PAN→personal_number (Cédula), PER→personal_number (DNI, 8 dígits), PRY→document_number (CI), SLV→document_number (DUI), URY→personal_number (CI), VEN→document_number (Cédula). Mai no sobreescriu un camp específic del país proporcionat de manera explícita. first_name: type: string description: >- El nom de la persona física. Requerit per alguns serveis/països. example: John last_name: type: string description: >- Els cognoms de la persona física. Requerits per alguns serveis/països. example: Doe middle_name: type: string description: >- Segon nom, utilitzat per serveis d'alguns països (AUS, NZL, …). full_name: type: string description: >- Nom complet — alguns serveis l'accepten en lloc del nom/cognoms (p. ex., serveis de CHN, que fan coincidir el nom en el sistema d'escriptura natiu). date_of_birth: type: string format: date description: >- Data de naixement, `YYYY-MM-DD`. Requerida per molts serveis. example: '1980-01-01' personal_number: type: string description: >- Identificador personal únic emès pel govern. Fes servir: CHL (RUT), COL (Cédula), CRI, DOM, ECU, ESP (DNI/NIE), MEX (CURP), PAN (Cédula), PER (DNI), URY. Considera fer servir `identification_number` en el seu lloc. tax_number: type: string description: >- Identificador fiscal. Utilitzat per: BRA (CPF, 11 dígits). Considera utilitzar `identification_number` en el seu lloc. document_number: type: string description: >- Número de document. Utilitzat per: ARG (DNI), BOL (CI), GTM (DPI), HND (DNI), PRY (CI), SLV (DUI), VEN (Cédula). Considera utilitzar `identification_number` en el seu lloc. document_type: type: string enum: - P - DL - ID - RP - SSC - HIC - WP - TC - VISA - PSC - BC - OTHER description: >- Tipus de document que s'està validant: `P` passaport, `DL` permís de conduir, `ID` document nacional d'identitat, `RP` permís de residència (a més de `SSC`, `HIC`, `WP`, `TC`, `VISA`, `PSC`, `BC`, `OTHER`). Requerit per alguns serveis (p. ex., ESP). expiration_date: type: string format: date description: >- Data de caducitat del document, `YYYY-MM-DD`. Obligatòria per a la validació d'ESP (Espanya). example: '2030-01-15' date_of_issue: type: string format: date description: >- Data d'emissió del document, `YYYY-MM-DD` (fecha de expedición). Obligatòria per a la validació de la cèdula de COL (Colòmbia). example: '2015-06-20' nationality: type: string description: >- Nacionalitat en format ISO 3166-1 alpha-3. Requerida per alguns serveis. gender: type: string enum: - M - F - X description: >- Gènere: `M`, `F` o `X` (altre/desconegut). Obligatori per a la validació de RENAPER de l'Argentina (`arg_renaper`). address: description: >- Adreça de residència. Es recomana l'objecte estructurat `{"street_1":"123 Main St","street_2":"Apt 4B","city":"Springfield","region":"IL","postal_code":"62701","country":"US"}`; encara s'accepta una cadena completa d'una sola línia. Obligatori per als serveis de verificació d'adreça; quan un servei defineix requisits d'adreça, les parts que faltin retornen `400` amb `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: Adreça completa en una sola línia (llegat). address_element_1: type: string description: >- Adreça que inclou el carrer, el número i el tipus de via. Si s'omet, es dedueix de `address`. address_element_2: type: string description: >- Apartament, unitat, edifici, planta o línia d'adreça addicional. Envia-ho només quan ho tinguis explícitament. address_element_3: type: string description: >- Ciutat, suburbi, districte, localitat o barri. Si s'omet, es deriva d'`address`. address_element_4: type: string description: >- Estat, província, regió o població. Si s'omet, es deriva d'`address`. address_element_5: type: string description: Codi postal. S'accepta `postal_code` com a àlies. postal_code: type: string description: >- Codi postal per a serveis basats en adreça (àlies de `address_element_5`). driver_license_number: type: string description: >- Número del permís de conduir per a serveis governamentals de verificació de documents (AUS, NZL, IND). driver_license_card_number: type: string description: >- Número de la targeta física del permís de conduir, quan es requereix per separat del número de permís (AUS). driver_license_state: type: string description: Estat o territori d'emissió del permís de conduir (AUS). driver_license_version: type: string description: Codi de versió del permís de conduir (NZL). passport_number: type: string description: >- Número de passaport per als serveis governamentals de verificació de passaports (AUS, NZL, IND, CHN). passport_expiration_date: type: string format: date description: >- Data de caducitat del passaport, `YYYY-MM-DD`, per als serveis de verificació de passaports. passport_file_number: type: string description: Número de fitxer del passaport (IND). passport_issue_country: type: string description: >- País emissor del passaport (ISO 3166-1 alfa-3) per a serveis de verificació de passaport. medicare_card_number: type: string description: Número de targeta Medicare (AUS). immi_card_number: type: string description: Número de la ImmiCard australiana. immi_card_expiry_date: type: string format: date description: Data de caducitat de la ImmiCard australiana. citizenship_certificate_number: type: string description: Número de certificat de ciutadania (AUS). birth_registration_number: type: string description: Número de registre del certificat de naixement (AUS). birth_registration_date: type: string format: date description: Data de registre del certificat de naixement (AUS). birth_registration_state: type: string description: Estat de registre del certificat de naixement (AUS). marriage_certificate_number: type: string description: Número del certificat de matrimoni (AUS). change_of_name_certificate_number: type: string description: Número del certificat de canvi de nom (AUS). first_partner_name: type: string description: Nom de pila del cònjuge en un certificat de matrimoni (AUS). last_partner_name: type: string description: Cognom del cònjuge en un certificat de matrimoni (AUS). voter_id: type: string description: Número d'inscripció electoral (IND EPIC, IRL). epic_card: type: string description: Número de la targeta d'elector EPIC de l'Índia. pan: type: string description: PAN (Permanent Account Number) de l'Índia. national_id: type: string description: >- Número d'identificació nacional (CHN, MYS, KEN, KHM, NGA, ZAF, …). cic: type: string description: >- Codi d'identificació de credencial (CIC) de l'INE/IFE mexicà, 9 dígits. S'utilitza pel servei de validesa de credencials MEX INE (`mex_ine_vigencia`). identificador_ciudadano: type: string description: >- Identificador de ciutadà de l'INE mexicà (9 dígits). S'utilitza amb `cic` per a models moderns de l'INE (E/F/G/H) a `mex_ine_vigencia`. ocr: type: string description: >- Número OCR de l'INE mexicà (13 dígits, dors de la targeta). S'utilitza amb `cic` per al Model D a `mex_ine_vigencia`. voter_number: type: string description: >- Clau d'elector de l'INE mexicà (18 caràcters). S'utilitza amb `emission_number` per a models antics de l'IFE (A/B/C) a `mex_ine_vigencia`. emission_number: type: string description: >- Número d'emissió de l'INE mexicà. S'utilitza amb `voter_number` per a models antics de l'IFE (A/B/C) a `mex_ine_vigencia`. bvn: type: string description: Número de verificació bancària de Nigèria. bank_card_number: type: string description: >- Número de targeta bancària (verificació de targeta bancària CHN). company_registration_number: type: string description: >- Número de registre de l'empresa tal com l'emet el registre mercantil: el CNPJ al Brasil (p. ex., `11222333000181`), el número de registre a Sud-àfrica (p. ex., `1936/007721/06`). Requerit pels serveis de registre mercantil i administradors d'empreses (`bra_company_registry`, `bra_company_directors`, `zaf_company_registry`, `zaf_company_directors`). company_name: type: string description: >- Nom de l'empresa registrada, confrontat amb l'entrada del registre. Opcional per a `zaf_company_registry`. initials: type: string description: >- Les inicials de la persona tal com apareixen impreses al document. Requerides per `zaf_drivers_license`; acceptades per `zaf_bank_account_holder`. licence_number: type: string description: >- Número del permís de conduir tal com apareix imprès a la targeta, per a `zaf_drivers_license`. Quan s'omet, s'utilitza `document_number`. refugee_file_number: type: string description: >- Número d'expedient de refugiat emès pel Department of Home Affairs de Sud-àfrica. Requerit per a `zaf_refugee`. bank_name: type: string description: >- Nom del banc titular del compte. Requerit per `zaf_bank_account_holder`. bank_account_number: type: string description: >- Número de compte bancari. Obligatori per a `zaf_bank_account_holder`; admès per `zaf_fraud_prevention`. account_type: type: string description: >- Tipus de compte bancari per a `zaf_bank_account_holder`: `current`, `savings`, `transmission`, `subscriptionShare` o `notKnown`, sense distingir majúscules i minúscules. Qualsevol altre valor retorna `400`. Omet-lo si no en saps el tipus: la comprovació creuada del tipus de compte s'informa llavors com a no confirmada. phone_number: type: string description: >- Número de telèfon mòbil de contacte, per als serveis que verifiquen de forma creuada la contactabilitat (`zaf_bank_account_holder`, `zaf_fraud_prevention`, `zaf_refugee`). right_thumb: type: string description: >- Empremta dactilar del polze dret codificada en base64 per a `zaf_dha_fingerprint_match`, juntament amb `left_thumb` o sola. left_thumb: type: string description: >- Empremta dactilar del polze esquerre codificada en base64 per a `zaf_dha_fingerprint_match`, juntament amb `right_thumb` o sola. score_level: type: integer description: >- Nivell mínim de puntuació biomètrica per a `zaf_criminal_face_screening`. Per defecte és `3`. max_matches: type: integer description: >- Nombre màxim de coincidències candidates que retorna `zaf_criminal_face_screening`. Per defecte és `1`. vehicle_register_number: type: string description: >- Número de registre del vehicle. Obligatori, juntament amb `vehicle_licence_plate` i `vin`, per a `zaf_vehicle_ownership`. vehicle_licence_plate: type: string description: >- Número de matrícula del vehicle. Obligatori, juntament amb `vehicle_register_number` i `vin`, per a `zaf_vehicle_ownership`. vin: type: string description: >- Número d'identificació del vehicle (VIN o número de bastidor). Obligatori, juntament amb `vehicle_register_number` i `vehicle_licence_plate`, per a `zaf_vehicle_ownership`. ssn: type: string description: Número de la Seguretat Social (EUA). phone: type: string description: Número de telèfon per als serveis de verificació de telèfon. landline: type: string description: >- Número de telèfon fix per als serveis de verificació de telèfon. email: type: string format: email description: >- Adreça de correu electrònic per als serveis de verificació d'identitat. country_of_residence: type: string description: >- País de residència ISO 3166-1 alpha-2. Utilitzat pels serveis globals d'enriquiment d'identitat (p. ex., `glb_identity_enrichment`) per centrar la cerca. example: US partial_match_action: type: string enum: - DECLINE - NO_ACTION default: NO_ACTION description: >- Quin efecte té un `partial_match` en `database_validation.status`. Per defecte és `NO_ACTION` (l'estat es manté en `Approved`, amb una advertència). no_match_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Quin efecte té un `no_match` en `database_validation.status`. Per defecte és `DECLINE`. save_api_request: type: boolean default: true description: >- Persisteix la validació com una sessió (visibilitat a la consola, endpoint de decisió, webhook `status.updated`). També canvia l'estructura de resposta de `validations`: objectes per servei quan és `true` (per defecte), un mapa de camps fusionat quan és `false`. vendor_data: type: string description: >- El teu identificador per a l'usuari validat; es retorna tal com s'ha enviat i s'emmagatzema amb la sessió. metadata: type: object nullable: true description: >- JSON de format lliure emmagatzemat amb la sol·licitud i retornat com a resposta. 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: >- Codi de país ISO 3166-1 **alfa-3** del registre contra el qual s'ha de validar (p. ex. `BRA`, `ESP`, `COL`). Determina quins serveis estan disponibles. Els codis no admesos retornen `400` amb la llista completa d'opcions vàlides. example: BRA services: type: array items: type: string description: >- `service_id`s de catàleg que s'han d'executar per a aquest país (p. ex., `["bra_cpf"]`). També accepta una sola cadena o una cadena separada per comes / codificada en JSON. **Si s'omet o és buit, s'executa exactament un servei per defecte** —el servei en producció més consolidat per al país; els serveis més nous, biomètrics i de pagament per ús s'han d'especificar explícitament. Enviar `services` canvia la resposta a l'estructura ampliada (afegeix `services_used` i `match_score`). Cada id ha d'existir i estar actiu per a l'`issuing_state`; els serveis que requereixen alta retornen `400` fins que s'activin per a la teva organització. Descobreix els serveis disponibles per país mitjançant `GET /v1/organization/database-validation-countries/` (un endpoint de catàleg no documentat en aquesta especificació) o l'editor de fluxos de treball de la Business Console. example: - bra_cpf validation_type: type: string deprecated: true description: >- OBSOLET. S'accepta per compatibilitat amb versions anteriors però s'ignora: el `validation_type` de la resposta ara es deriva de quants serveis han coincidit completament. Utilitza `services` per fixar serveis específics. consent: type: boolean default: false description: >- Estableix-ho a `true` quan l'usuari final hagi donat el consentiment explícit als serveis de validació seleccionats. Requerit per als serveis marcats amb `requires_consent=true` al catàleg — sense ell, aquests serveis retornen `400` amb `services_requiring_consent`. identification_number: type: string description: >- Número d'identificació universal — s'assigna automàticament al camp correcte específic de cada país, de manera que pots utilitzar-lo en lloc de `personal_number`/`tax_number`/`document_number`: ARG→document_number (DNI), BOL→document_number (CI), BRA→tax_number (CPF, 11 dígits), CHL→personal_number (RUT), COL→personal_number (Cédula), CRI→personal_number (Cédula), DOM→personal_number (Cédula, 11 dígits), ECU→personal_number (Cédula, 10 dígits), ESP→personal_number (DNI/NIE), GTM→document_number (DPI), HND→document_number (DNI), MEX→personal_number (CURP, 18 caràcters), PAN→personal_number (Cédula), PER→personal_number (DNI, 8 dígits), PRY→document_number (CI), SLV→document_number (DUI), URY→personal_number (CI), VEN→document_number (Cédula). Mai no sobreescriu un camp específic del país proporcionat de manera explícita. first_name: type: string description: >- El nom de la persona física. Requerit per alguns serveis/països. example: John last_name: type: string description: >- Els cognoms de la persona física. Requerits per alguns serveis/països. example: Doe middle_name: type: string description: >- Segon nom, utilitzat per serveis d'alguns països (AUS, NZL, …). full_name: type: string description: >- Nom complet — alguns serveis l'accepten en lloc del nom/cognoms (p. ex., serveis de CHN, que fan coincidir el nom en el sistema d'escriptura natiu). date_of_birth: type: string format: date description: >- Data de naixement, `YYYY-MM-DD`. Requerida per molts serveis. example: '1980-01-01' personal_number: type: string description: >- Identificador personal únic emès pel govern. Fes servir: CHL (RUT), COL (Cédula), CRI, DOM, ECU, ESP (DNI/NIE), MEX (CURP), PAN (Cédula), PER (DNI), URY. Considera fer servir `identification_number` en el seu lloc. tax_number: type: string description: >- Identificador fiscal. Utilitzat per: BRA (CPF, 11 dígits). Considera utilitzar `identification_number` en el seu lloc. document_number: type: string description: >- Número de document. Utilitzat per: ARG (DNI), BOL (CI), GTM (DPI), HND (DNI), PRY (CI), SLV (DUI), VEN (Cédula). Considera utilitzar `identification_number` en el seu lloc. document_type: type: string enum: - P - DL - ID - RP - SSC - HIC - WP - TC - VISA - PSC - BC - OTHER description: >- Tipus de document que s'està validant: `P` passaport, `DL` permís de conduir, `ID` document nacional d'identitat, `RP` permís de residència (a més de `SSC`, `HIC`, `WP`, `TC`, `VISA`, `PSC`, `BC`, `OTHER`). Requerit per alguns serveis (p. ex., ESP). expiration_date: type: string format: date description: >- Data de caducitat del document, `YYYY-MM-DD`. Obligatòria per a la validació d'ESP (Espanya). example: '2030-01-15' date_of_issue: type: string format: date description: >- Data d'emissió del document, `YYYY-MM-DD` (fecha de expedición). Obligatòria per a la validació de la cèdula de COL (Colòmbia). example: '2015-06-20' nationality: type: string description: >- Nacionalitat en format ISO 3166-1 alpha-3. Requerida per alguns serveis. gender: type: string enum: - M - F - X description: >- Gènere: `M`, `F` o `X` (altre/desconegut). Obligatori per a la validació de RENAPER de l'Argentina (`arg_renaper`). address: description: >- Adreça de residència. Es recomana l'objecte estructurat `{"street_1":"123 Main St","street_2":"Apt 4B","city":"Springfield","region":"IL","postal_code":"62701","country":"US"}`; encara s'accepta una cadena completa d'una sola línia. Obligatori per als serveis de verificació d'adreça; quan un servei defineix requisits d'adreça, les parts que faltin retornen `400` amb `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: Adreça completa en una sola línia (llegat). address_element_1: type: string description: >- Adreça que inclou el carrer, el número i el tipus de via. Si s'omet, es dedueix de `address`. address_element_2: type: string description: >- Apartament, unitat, edifici, planta o línia d'adreça addicional. Envia-ho només quan ho tinguis explícitament. address_element_3: type: string description: >- Ciutat, suburbi, districte, localitat o barri. Si s'omet, es deriva d'`address`. address_element_4: type: string description: >- Estat, província, regió o població. Si s'omet, es deriva d'`address`. address_element_5: type: string description: Codi postal. S'accepta `postal_code` com a àlies. postal_code: type: string description: >- Codi postal per a serveis basats en adreça (àlies de `address_element_5`). driver_license_number: type: string description: >- Número del permís de conduir per a serveis governamentals de verificació de documents (AUS, NZL, IND). driver_license_card_number: type: string description: >- Número de la targeta física del permís de conduir, quan es requereix per separat del número de permís (AUS). driver_license_state: type: string description: Estat o territori d'emissió del permís de conduir (AUS). driver_license_version: type: string description: Codi de versió del permís de conduir (NZL). passport_number: type: string description: >- Número de passaport per als serveis governamentals de verificació de passaports (AUS, NZL, IND, CHN). passport_expiration_date: type: string format: date description: >- Data de caducitat del passaport, `YYYY-MM-DD`, per als serveis de verificació de passaports. passport_file_number: type: string description: Número de fitxer del passaport (IND). passport_issue_country: type: string description: >- País emissor del passaport (ISO 3166-1 alfa-3) per a serveis de verificació de passaport. medicare_card_number: type: string description: Número de targeta Medicare (AUS). immi_card_number: type: string description: Número de la ImmiCard australiana. immi_card_expiry_date: type: string format: date description: Data de caducitat de la ImmiCard australiana. citizenship_certificate_number: type: string description: Número de certificat de ciutadania (AUS). birth_registration_number: type: string description: Número de registre del certificat de naixement (AUS). birth_registration_date: type: string format: date description: Data de registre del certificat de naixement (AUS). birth_registration_state: type: string description: Estat de registre del certificat de naixement (AUS). marriage_certificate_number: type: string description: Número del certificat de matrimoni (AUS). change_of_name_certificate_number: type: string description: Número del certificat de canvi de nom (AUS). first_partner_name: type: string description: Nom de pila del cònjuge en un certificat de matrimoni (AUS). last_partner_name: type: string description: Cognom del cònjuge en un certificat de matrimoni (AUS). voter_id: type: string description: Número d'inscripció electoral (IND EPIC, IRL). epic_card: type: string description: Número de la targeta d'elector EPIC de l'Índia. pan: type: string description: PAN (Permanent Account Number) de l'Índia. national_id: type: string description: >- Número d'identificació nacional (CHN, MYS, KEN, KHM, NGA, ZAF, …). cic: type: string description: >- Codi d'identificació de credencial (CIC) de l'INE/IFE mexicà, 9 dígits. S'utilitza pel servei de validesa de credencials MEX INE (`mex_ine_vigencia`). identificador_ciudadano: type: string description: >- Identificador de ciutadà de l'INE mexicà (9 dígits). S'utilitza amb `cic` per a models moderns de l'INE (E/F/G/H) a `mex_ine_vigencia`. ocr: type: string description: >- Número OCR de l'INE mexicà (13 dígits, dors de la targeta). S'utilitza amb `cic` per al Model D a `mex_ine_vigencia`. voter_number: type: string description: >- Clau d'elector de l'INE mexicà (18 caràcters). S'utilitza amb `emission_number` per a models antics de l'IFE (A/B/C) a `mex_ine_vigencia`. emission_number: type: string description: >- Número d'emissió de l'INE mexicà. S'utilitza amb `voter_number` per a models antics de l'IFE (A/B/C) a `mex_ine_vigencia`. bvn: type: string description: Número de verificació bancària de Nigèria. bank_card_number: type: string description: >- Número de targeta bancària (verificació de targeta bancària CHN). company_registration_number: type: string description: >- Número de registre de l'empresa tal com l'emet el registre mercantil: el CNPJ al Brasil (p. ex., `11222333000181`), el número de registre a Sud-àfrica (p. ex., `1936/007721/06`). Requerit pels serveis de registre mercantil i administradors d'empreses (`bra_company_registry`, `bra_company_directors`, `zaf_company_registry`, `zaf_company_directors`). company_name: type: string description: >- Nom de l'empresa registrada, confrontat amb l'entrada del registre. Opcional per a `zaf_company_registry`. initials: type: string description: >- Les inicials de la persona tal com apareixen impreses al document. Requerides per `zaf_drivers_license`; acceptades per `zaf_bank_account_holder`. licence_number: type: string description: >- Número del permís de conduir tal com apareix imprès a la targeta, per a `zaf_drivers_license`. Quan s'omet, s'utilitza `document_number`. refugee_file_number: type: string description: >- Número d'expedient de refugiat emès pel Department of Home Affairs de Sud-àfrica. Requerit per a `zaf_refugee`. bank_name: type: string description: >- Nom del banc titular del compte. Requerit per `zaf_bank_account_holder`. bank_account_number: type: string description: >- Número de compte bancari. Obligatori per a `zaf_bank_account_holder`; admès per `zaf_fraud_prevention`. account_type: type: string description: >- Tipus de compte bancari per a `zaf_bank_account_holder`: `current`, `savings`, `transmission`, `subscriptionShare` o `notKnown`, sense distingir majúscules i minúscules. Qualsevol altre valor retorna `400`. Omet-lo si no en saps el tipus: la comprovació creuada del tipus de compte s'informa llavors com a no confirmada. phone_number: type: string description: >- Número de telèfon mòbil de contacte, per als serveis que verifiquen de forma creuada la contactabilitat (`zaf_bank_account_holder`, `zaf_fraud_prevention`, `zaf_refugee`). right_thumb: type: string description: >- Empremta dactilar del polze dret codificada en base64 per a `zaf_dha_fingerprint_match`, juntament amb `left_thumb` o sola. left_thumb: type: string description: >- Empremta dactilar del polze esquerre codificada en base64 per a `zaf_dha_fingerprint_match`, juntament amb `right_thumb` o sola. score_level: type: integer description: >- Nivell mínim de puntuació biomètrica per a `zaf_criminal_face_screening`. Per defecte és `3`. max_matches: type: integer description: >- Nombre màxim de coincidències candidates que retorna `zaf_criminal_face_screening`. Per defecte és `1`. vehicle_register_number: type: string description: >- Número de registre del vehicle. Obligatori, juntament amb `vehicle_licence_plate` i `vin`, per a `zaf_vehicle_ownership`. vehicle_licence_plate: type: string description: >- Número de matrícula del vehicle. Obligatori, juntament amb `vehicle_register_number` i `vin`, per a `zaf_vehicle_ownership`. vin: type: string description: >- Número d'identificació del vehicle (VIN o número de bastidor). Obligatori, juntament amb `vehicle_register_number` i `vehicle_licence_plate`, per a `zaf_vehicle_ownership`. ssn: type: string description: Número de la Seguretat Social (EUA). phone: type: string description: Número de telèfon per als serveis de verificació de telèfon. landline: type: string description: >- Número de telèfon fix per als serveis de verificació de telèfon. email: type: string format: email description: >- Adreça de correu electrònic per als serveis de verificació d'identitat. country_of_residence: type: string description: >- País de residència ISO 3166-1 alpha-2. Utilitzat pels serveis globals d'enriquiment d'identitat (p. ex., `glb_identity_enrichment`) per centrar la cerca. example: US partial_match_action: type: string enum: - DECLINE - NO_ACTION default: NO_ACTION description: >- Quin efecte té un `partial_match` en `database_validation.status`. Per defecte és `NO_ACTION` (l'estat es manté en `Approved`, amb una advertència). no_match_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Quin efecte té un `no_match` en `database_validation.status`. Per defecte és `DECLINE`. save_api_request: type: boolean default: true description: >- Persisteix la validació com una sessió (visibilitat a la consola, endpoint de decisió, webhook `status.updated`). També canvia l'estructura de resposta de `validations`: objectes per servei quan és `true` (per defecte), un mapa de camps fusionat quan és `false`. vendor_data: type: string description: >- El teu identificador per a l'usuari validat; es retorna tal com s'ha enviat i s'emmagatzema amb la sessió. metadata: type: object nullable: true description: >- JSON de format lliure emmagatzemat amb la sol·licitud i retornat com a resposta. selfie: type: string format: binary description: >- Imatge de la selfie (`jpg`, `jpeg`, `png`, `webp`; màx. 2 MB — les imatges es comprimeixen a ~1.5 MB abans de pujar-se al registre) per a serveis de validació biomètrica, p. ex. RENAPER de l'Argentina (`arg_renaper`) i SIB de Panamà (`pan_cedula_sib`, `pan_cedula_sib_plus`). Obligatòria sempre que un servei seleccionat la llisti com a camp obligatori. Només disponible mitjançant `multipart/form-data`. responses: '200': description: >- Validació completada — almenys un dels serveis seleccionats ha retornat un resultat utilitzable. Inspecciona `database_validation.match_type` per al resultat agregat, `validations` per a les comparacions de camps per servei i els `outcome_code`s, i `errors` (quan n'hi hagi) per als serveis que hagin fallat. content: application/json: schema: type: object properties: request_id: type: string format: uuid description: >- ID de sessió persistida quan `save_api_request=true` (utilitzable amb `GET /v3/session/{sessionId}/decision/`); en cas contrari, un UUID de correlació transitori. database_validation: type: object properties: status: type: string enum: - Approved - Declined - In Review description: >- `Declined` quan el `match_type` global activa una acció `DECLINE` (`no_match_action` té per defecte `DECLINE`, i `partial_match_action` té per defecte `NO_ACTION`); `In Review` quan cap servei ha produït una comparació utilitzable, per exemple quan l'únic servei seleccionat ha retornat `REGISTRY_UNAVAILABLE` o `INCONCLUSIVE`; `Approved` en cas contrari. Una sol·licitud que ha seleccionat diversos serveis pot resultar `Approved` per la coincidència d'un servei mentre un altre no estava disponible, de manera que cal comprovar també `errors` i els `outcome_code` de cada servei. issuing_state: type: string description: >- Ressò del país ISO 3166-1 alpha-3 contra el qual s'ha validat. example: BRA validation_type: type: string enum: - one_by_one - two_by_two description: >- Deduït a partir dels resultats: `two_by_two` quan ≥2 serveis diferents han produït una coincidència completa (en el número d'identificació, en el nom complet + data de naixement plegats, o en l'adreça sense contradiccions); `one_by_one` en cas contrari. (El camp de la sol·licitud amb el mateix nom està obsolet i s'ignora.) screened_data: type: object description: >- Ressò dels camps d'entrada enviats als serveis seleccionats (dates normalitzades a `YYYY-MM-DD`; si s'envia una `selfie`, es retorna com a URL presignada; s'afegeix `consent_obtained: true` quan s'ha obtingut el consentiment). match_type: type: string nullable: true enum: - full_match - partial_match - no_match description: >- Resultat global agregat entre serveis amb comparacions a nivell de camp: qualsevol `full_match` → `full_match`; altrament, qualsevol `partial_match` → `partial_match`; altrament, `no_match`. Els serveis només de resultat, com ara el cribratge penal biomètric, poden retornar `null`; inspecciona cada element a `validations` per veure el seu `outcome_code`. validations: description: >- L'estructura depèn de `save_api_request`. **`true` (per defecte):** una matriu d'objectes per servei (`service_id`, `service_name`, `validation`, `outcome_code`, `outcome_detail`, `source_data`). **`false`:** un únic objecte pla que fusiona els resultats a nivell de camp de tots els serveis (`{"full_name": "full_match", ...}`). oneOf: - type: array items: type: object description: >- Resultat de validació per servei (es retorna quan `save_api_request=true`, el valor per defecte). properties: service_id: type: string description: >- Identificador de catàleg del servei que ha generat aquest resultat (p. ex., `bra_cpf`). example: bra_cpf service_name: type: string description: Nom de catàleg del servei fàcil de llegir. example: Brazil - CPF status check validation: type: object description: >- Comparació camp per camp entre les teves dades d'entrada i el registre oficial. Les claus són noms canònics de camp (`full_name`, `date_of_birth`, `identification_number`, `address`, …); els valors són `full_match`, `partial_match` o `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: >- Resultat independent del proveïdor de la consulta al registre. `MATCH`/`PARTIAL_MATCH`/`NO_MATCH` descriuen la comparació; `DOCUMENT_NOT_FOUND` significa que l'identificador no és al registre; `INCONCLUSIVE` significa que el registre no ha pogut confirmar cap de les dues opcions (s'envia a revisió manual, NO és una no coincidència); `BIOMETRIC_NO_MATCH` és una no coincidència facial definitiva, mentre que `BIOMETRIC_IMAGE_UNUSABLE` és un problema tècnic de la imatge (torna a fer la selfie); `DECEASED`/`MINOR_BLOCKED` són resultats per polítiques del registre; `DOCUMENT_SUPERSEDED` significa que la identitat coincideix però l'edició del document presentat no és la que figura en els arxius (s'ha emès una edició més nova); `INVALID_DOCUMENT_FORMAT`/`INVALID_INPUT` signifiquen que el registre mateix ha rebutjat les dades enviades; `REGISTRY_UNAVAILABLE`/`REGISTRY_ERROR` indiquen fallades dels sistemes anteriors. outcome_detail: type: string nullable: true description: >- Detall de l'estat d'origen en brut que fonamenta el codi de resultat (p. ex., un codi d'estat HTTP o del registre). source_data: type: object nullable: true description: >- Vista neta i normalitzada del registre mitjançant noms de camp canònics (`identification_number`, `first_name`, `last_name`, `date_of_birth`, a més d'indicadors específics del registre). Els camps d'imatge, quan estan presents, es retornen com a URL signades prèviament. - type: object additionalProperties: type: string enum: - full_match - partial_match - no_match description: >- Resultats fusionats a nivell de camp (format sense estat `save_api_request=false`). warnings: type: array items: type: object properties: feature: type: string description: Funcionalitat que ha generat l'advertència. risk: type: string description: Identificador de risc llegible per màquina. additional_data: type: object nullable: true description: >- Context addicional per a l'advertència, quan estigui disponible. log_type: type: string description: >- `warning`, `information` o `error` — com ha afectat el risc el resultat. short_description: type: string description: Resum d'una línia llegible per humans. long_description: type: string description: Explicació completa comprensible per a persones. description: >- `DATABASE_VALIDATION_NO_MATCH` o `DATABASE_VALIDATION_PARTIAL_MATCH` quan correspongui; buit en cas de coincidència total. errors: type: array description: >- Present només quan alguns serveis seleccionats (però no tots) han fallat. Cada entrada conté `service_id`, `code`, `message` i `retryable`. Un servei informat aquí no apareix a `validations` ni a `services_used`, i no es factura. Aquesta matriu és l'únic lloc on apareix, de manera que revisa-la fins i tot quan `status` sigui `Approved`. items: type: object properties: service_id: type: string code: type: string example: empty_provider_response message: type: string retryable: type: boolean description: >- `true` quan el servei no ha donat cap resposta i reintentar-ho més tard pot ser satisfactori; `false` quan la font ha rebutjat les dades que se li han enviat i cal corregir l'entrada primer. example: true services_used: type: array items: type: string description: >- Identificadors de catàleg dels serveis que han retornat un resultat facturable. **Només present quan la sol·licitud ha enviat explícitament `services`.** match_score: type: number description: >- Fracció (0.0–1.0) de serveis intentats que han produït una coincidència total (en el número d'identificació, en el nom complet + data de naixement plegats, o en l'adreça sense contradiccions). **Només present quan la sol·licitud ha enviat explícitament `services`.** vendor_data: type: string nullable: true description: Ressò del `vendor_data` que has enviat. metadata: type: object nullable: true description: Ressò de les `metadata` que has enviat. created_at: type: string format: date-time examples: Full match (Approved): summary: >- Per defecte save_api_request=true: objectes `validations` per servei 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: >- S'ha enviat la sol·licitud amb `services` — la resposta afegeix `services_used` i `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: >- El registre no coincideix — `no_match_action=DECLINE` per defecte 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` es redueix a un mapa de camps fusionat; no s'emmagatzema res 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: >- Error de validació - no es factura res. Els errors de camp de prevalidació es produeixen abans de qualsevol crida externa. Si cada intent sense resposta rebutja explícitament l'entrada, la resposta inclou en el seu lloc `validation_errors` amb `code: provider_rejected_input` i `retryable: false`; corregeix l'entrada abans de reintentar. Els problemes a nivell de camp utilitzen l'embolcall estàndard de DRF; els problemes de catàleg retornen una matriu `services` (més `requires_onboarding` o `services_requiring_consent` quan sigui rellevant); els errors de camps que falten inclouen `fields_required_by`, que assigna cada camp que falta als serveis que el requereixen; els serveis que necessiten almenys un identificador addicional (p. ex., `usa_states_credit_bureau`, que no pot verificar un nom tot sol) retornen `any_field_required_by`, que assigna cada servei als camps dels quals almenys un ha d'estar present; els problemes de format comprovats per servei retornen `invalid_fields_by_service`. content: application/json: examples: Invalid issuing_state: summary: >- País no admès — el missatge llista tots els codis alpha-3 vàlids 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: >- Unió de camps obligatoris entre els serveis seleccionats, amb la indicació del camp universal 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` conté un id que no és al catàleg' value: services: - 'Unknown service_id(s): [''bogus_service'']' Service not live for country: summary: >- `services` indica un servei d'un altre país (o una entrada fictícia) value: services: - >- Services not currently live for PER: ['bra_cpf']. Available services: ['per_dni', 'per_residential', 'per_tax_registration'] Service requires onboarding: summary: >- El servei existeix però encara no està activat per a la teva organització 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: >- Un servei seleccionat té la marca requires_consent=true i `consent` no era `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: >- L'identificador no compleix la regla de format del país (longitud/dígits/expressió regular) 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: >- Un camp no compleix els requisits de format propis del servei seleccionat 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: Corregeix les dades d'entrada abans de reintentar 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: >- Explicació a nivell de sol·licitud o errors de camp de comprovació prèvia. oneOf: - type: string - type: array items: type: string validation_errors: type: array description: >- Present quan tots els intents sense resposta han rebutjat les dades després de la comprovació prèvia. items: type: object properties: service_id: type: string code: type: string message: type: string retryable: type: boolean description: >- Indica si reintentar més tard pot resoldre aquest error del servei. False significa que primer cal corregir les dades d'entrada proporcionades. '403': description: >- Permís denegat. Es retorna quan falta la capçalera `x-api-key`, i també quan el saldo de l'organització que fa la crida no pot cobrir la crida; una clau incorrecta, revocada o caducada retorna `401`. Si falta la clau es retorna `403` amb `{"detail": ...}`; una clau incorrecta, revocada o caducada retorna `401`. La manca de crèdit retorna `403` amb `{"error": ...}` abans que es produeixi cap cribratge o crida al proveïdor. content: application/json: examples: Missing or invalid API key: summary: >- Sense capçalera `x-api-key`, o la clau no és vàlida/s'ha revocat value: detail: You do not have permission to perform this action. Not enough credits: summary: El saldo de l'organització no pot cobrir la crida value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- S'ha superat el límit de freqüència. Els endpoints POST/PATCH/DELETE comparteixen un pressupost de 300 sol·licituds d'escriptura per minut per clau d'API (la creació de transaccions i la ingesta d'esdeveniments tenen un pressupost independent de 600). La resposta inclou les capçaleres `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` i `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Més de 300 sol·licituds d'escriptura en el minut actual 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: >- Cap servei seleccionat ha retornat un resultat utilitzable. Inspecciona cada entrada de validation_errors abans de reintentar; HTTP 502 per si sol no determina una fallada transitòria. Un empty_provider_response amb retryable: true indica resultats no disponibles o inexplicats, incloent-hi un proveïdor principal rebutjat seguit d'una alternativa no disponible. En canvi, les entrades heretades provider_invalid_input i provider_validation_error requereixen dades d'entrada corregides i poden ometre retryable. No es factura res. Quan save_api_request=true, l'intent fallit es registra com una sessió amb estat Not Finished. Les fallades parcials retornen 200 amb 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: >- Indica si reintentar més tard pot resoldre aquest error del servei. False significa que primer cal corregir les dades d'entrada proporcionades. examples: Provider returned no result: summary: Tots els serveis seleccionats han fallat 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: >- La clau d'API de la teva aplicació, des de Developers -> API keys a la Business Console. La clau primària té accés complet. Una clau amb nom pot tenir l'abast limitat: cap, lectura o escriptura per recurs, limitada a determinats fluxos de treball o a sessions aprovades, a una llista d'adreces IP i a una data de caducitat. 401 significa que la clau és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap clau, que la clau no té accés a aquest recurs o acció, o que la sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una ruta de sessió significa que la sessió està fora dels fluxos de treball o estats de la clau. Una clau sense accés a fitxers multimèdia rep els URL d'imatge, vídeo i PDF com a null, i una clau sense permís d'escriptura de sessions rep els enllaços de sessió i els tokens com a null. Consulta https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.