> ## 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 Validação de Base de Dados: Documento Nacional > Valide dados de identidade com a API da Didit em 100+ fontes nacionais e globais, com correspondência em cascata 1x1 e 2x2. Pague por chamada. ## Serviços baseados em endereço Para serviços que validam um endereço residencial ou de serviço público, você pode enviar um único `address` e a Didit vai dividi-lo antes de processar a verificação. Para obter a melhor taxa de correspondência, envie diretamente os campos de endereço estruturados da Didit: | Campo | Significado | | - | - | | `address_element_1` | Endereço, incluindo número e tipo de logradouro | | `address_element_2` | Unidade, edifício, andar ou linha adicional de endereço (opcional) | | `address_element_3` | Bairro, distrito, localidade ou vizinhança | | `address_element_4` | Cidade, município, estado, província ou região | | `address_element_5` | CEP ou código postal | Os campos estruturados substituem o valor único de `address`. `postal_code` é aceito como alias de `address_element_5`. ## Consentimento Alguns serviços de banco de dados exigem o consentimento explícito do usuário final antes que o provedor possa ser consultado. O catálogo de serviços marca essas linhas com `requires_consent=true`. Envie `consent=true` quando o consentimento do usuário se aplicar aos serviços selecionados. Se um serviço selecionado exigir consentimento e você não o enviar, a Didit rejeita a requisição antes de qualquer chamada ao provedor ou evento de faturamento. ## Envio de arquivos A validação de banco de dados usa `multipart/form-data`. Os serviços biométricos que exigem `selfie` exibem esse campo de envio de arquivo no playground da API, para que você possa selecionar uma imagem diretamente em vez de colar um caminho ou uma string base64. No código, envie o arquivo com a sintaxe multipart padrão: ```bash theme={null} -F "selfie=@./selfie.jpg" ``` ## Erros de validação A Didit valida os campos obrigatórios, a estrutura do endereço e os formatos específicos de cada serviço antes de chamar o provedor. Por exemplo, serviços de registro da China, como `chn_national_id` e `chn_passport_verification`, esperam `full_name` na escrita chinesa original, e `chn_national_id` também exige um documento nacional de identidade chinês válido, com 15 ou 18 caracteres e dígito verificador correto. Se uma requisição não puder ser executada, a API retorna erros explícitos por campo e nenhum uso é faturado. Se um provedor falhar após a verificação prévia, a resposta inclui `validation_errors`, e as requisições de API salvas armazenam esses erros no resultado de validação no banco de dados. ## Entrada rejeitada e resultados indisponíveis Quando nenhum serviço retornar um resultado utilizável, inspecione cada entrada de `validation_errors` antes de decidir se deve tentar novamente. O status HTTP, por si só, não determina se é adequado tentar novamente. Uma resposta `400` com `code: "provider_rejected_input"` e `retryable: false` significa que todas as tentativas sem resposta recusaram explicitamente a entrada. Corrija os dados fornecidos antes de tentar novamente. Essas tentativas não são faturadas. Uma resposta `502` com `code: "empty_provider_response"` e `retryable: true` significa que o serviço não conseguiu produzir um resultado utilizável por outro motivo. Isso inclui uma entrada recusada seguida de um fallback indisponível ou de um fallback que não fornece nenhuma explicação. Tente novamente mais tarde; a resposta não comprova que a entrada está errada. Se um banco de dados continuar falhando, a Didit envia um e-mail às organizações que o usaram recentemente quando a interrupção se prolonga, e outro quando verificações reais confirmam que ele voltou a responder. Consulte [Notificações de disponibilidade](https://docs.didit.me/pt-br/core-technology/database-validation/overview.md#notificações-de-disponibilidade). Quando apenas alguns dos serviços selecionados falham, a requisição é bem-sucedida: a resposta é `200` e os serviços que falharam são listados em `database_validation.errors[]`, cada um com os mesmos campos `code` e `retryable`. Nesse caso, `database_validation.status` reflete os serviços que responderam e pode ser `Approved`; por isso, inspecione `errors[]` em todas as respostas, e não apenas em respostas `4xx` ou `5xx`. Um serviço listado ali não aparece em `validations` nem em `services_used` e não é faturado; tente novamente apenas esse serviço. Outros erros `502` podem exigir a correção da entrada. Por exemplo, `provider_invalid_input` e `provider_validation_error` descrevem uma entrada que a fonte rejeitou, e você não deve tentar novamente sem alterá-la, mesmo quando a resposta legada omite `retryable`. A orientação sobre tentar novamente para `empty_provider_response` não se aplica a esses códigos. Um resultado conclusivo sem correspondência é uma verificação concluída, não uma falha de disponibilidade. ## OpenAPI ````yaml pt-br/openapi-25.json POST /v3/database-validation/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de verificação de identidade. Autentique-se com o cabeçalho x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/database-validation/: post: tags: - Standalone APIs summary: Validação de banco de dados (avulsa) description: >- Valide os dados de identidade de uma pessoa em fontes oficiais de governos e registros: CPF no Brasil, RENAPER na Argentina, registros de DNI na Espanha e no Peru, INE no México e mais de 100+ outros serviços em 60+ países. **Seleção de serviços.** Cada país oferece um ou mais serviços do catálogo, identificados por um `service_id` (por exemplo, `bra_cpf`, `arg_renaper`, `pan_cedula_sib`). Defina os serviços desejados com o array `services`. Se você omiti-lo, exatamente **um** serviço padrão é executado (o serviço ativo mais antigo do país). Enviar `services` também muda a resposta para o formato estendido, com `services_used` e `match_score`. Descubra os serviços, os campos obrigatórios de cada um e os preços por meio de `GET /v1/organization/database-validation-countries/` (um endpoint de catálogo não documentado nesta especificação) ou do editor de fluxos de verificação (workflow) do Business Console. Alguns serviços estão marcados com `requires_consent=true` no catálogo e exigem `consent=true`; outros exigem onboarding da sua organização antes de poderem ser chamados. **Campos de entrada.** `identification_number` é um campo universal que é mapeado automaticamente para o campo específico do país correto (veja a descrição dele). As regras de formato de cada país são aplicadas antes de qualquer provedor ser chamado (por exemplo, o CPF do BRA deve ter exatamente 11 dígitos), e falhas de formato nunca são cobradas. Serviços biométricos precisam do envio de uma `selfie` (somente multipart); o RENAPER da Argentina também exige `gender`. **Resultados.** Cada serviço retorna um mapa `validation` campo a campo, além de um `outcome_code` independente de fornecedor (`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`). Observe as diferenças: `NO_MATCH` é uma divergência definitiva, `INCONCLUSIVE` significa que o registro não conseguiu confirmar nem negar (revisão, não recusa) e `BIOMETRIC_IMAGE_UNUSABLE` é um problema técnico da selfie (nova captura), ao contrário do definitivo `BIOMETRIC_NO_MATCH`. O `match_type` geral agrega os resultados de todos os serviços (qualquer correspondência completa → `full_match`; caso contrário, qualquer parcial → `partial_match`; caso contrário, `no_match`), e `no_match_action`/`partial_match_action` o convertem no `status` final. `validation_type` é derivado: `two_by_two` quando dois ou mais serviços distintos produziram uma correspondência completa (no número de identificação, no nome completo + data de nascimento em conjunto ou no endereço sem contradições); caso contrário, `one_by_one`. **Persistência.** `save_api_request` tem como padrão **true**: o resultado é armazenado como uma sessão (`request_id` funciona com `GET /v3/session/{sessionId}/decision/`), aparece no console e dispara um webhook `status.updated`. Ele também controla o formato de `validations`: objetos por serviço quando salvo, um mapa `{field: match}` mesclado quando não salvo. **Faturamento.** Por serviço: cada serviço que retorna um resultado faturável é cobrado pelo seu próprio preço de catálogo. Serviços com falha ou ignorados não são cobrados, e requisições rejeitadas com `400` não custam nada. A verificação prévia de saldo cobre a soma dos preços dos serviços selecionados (`403` quando o saldo é insuficiente). **Falhas.** Quando nenhum serviço selecionado retorna um resultado utilizável, a API retorna `400` com `validation_errors` se todas as tentativas sem resposta recusaram explicitamente a entrada (`provider_rejected_input`, `retryable: false`). Corrija a entrada antes de tentar novamente. Caso contrário, ela retorna `502` com `validation_errors` (`empty_provider_response`, `retryable: true`), inclusive quando há rejeição de entrada combinada com tentativas alternativas indisponíveis; nada é cobrado (uma sessão ainda é registrada com status `Not Finished` quando `save_api_request=true`). Quando apenas alguns serviços falham, a resposta `200` traz essas falhas em `database_validation.errors`. **Sandbox.** Chaves de aplicações de sandbox ignoram as chamadas aos registros e o faturamento e retornam uma resposta estática `full_match`. O payload de sandbox sempre inclui `services_used` e `match_score: 100`, independentemente de como `services` foi enviado, portanto não valide nas respostas de sandbox a condição do formato estendido do ambiente de produção nem a fração de `match_score` de 0.0 a 1.0. Envie a requisição como `application/json` ou como `multipart/form-data` ao enviar uma `selfie`. operationId: post_v3database-validation parameters: [] requestBody: required: true content: application/json: schema: type: object required: - issuing_state properties: issuing_state: type: string description: >- Código de país ISO 3166-1 **alpha-3** do registro a ser usado na validação (por exemplo, `BRA`, `ESP`, `COL`). Determina quais serviços estão disponíveis. Códigos não suportados retornam `400` com a lista completa de opções válidas. example: BRA services: type: array items: type: string description: >- `service_id`s do catálogo a executar para este país (por exemplo, `["bra_cpf"]`). Também aceita uma única string ou uma string separada por vírgulas ou codificada em JSON. **Se omitido ou vazio, exatamente um serviço padrão é executado**: o serviço ativo mais antigo do país; serviços mais novos, biométricos e com pagamento por uso devem ser indicados explicitamente. Enviar `services` muda a resposta para o formato estendido (adiciona `services_used` e `match_score`). Todo id deve existir e estar ativo para o `issuing_state`; serviços que exigem onboarding retornam `400` até serem ativados para a sua organização. Descubra os serviços disponíveis por país via `GET /v1/organization/database-validation-countries/` (um endpoint de catálogo não documentado nesta especificação) ou no editor de fluxos do Business Console. example: - bra_cpf validation_type: type: string deprecated: true description: >- OBSOLETO. Aceito por compatibilidade com versões anteriores, mas ignorado: o `validation_type` da resposta agora é derivado de quantos serviços tiveram correspondência total. Use `services` para fixar serviços específicos. consent: type: boolean default: false description: >- Defina como `true` quando o usuário final tiver consentido explicitamente com os serviços de validação selecionados. Obrigatório para serviços marcados com `requires_consent=true` no catálogo; sem isso, esses serviços retornam `400` com `services_requiring_consent`. identification_number: type: string description: >- Número de identificação universal, mapeado automaticamente para o campo específico do país correto, para que você possa usá-lo em vez de `personal_number`/`tax_number`/`document_number`: ARG→document_number (DNI), BOL→document_number (CI), BRA→tax_number (CPF, 11 dígitos), CHL→personal_number (RUT), COL→personal_number (Cédula), CRI→personal_number (Cédula), DOM→personal_number (Cédula, 11 dígitos), ECU→personal_number (Cédula, 10 dígitos), ESP→personal_number (DNI/NIE), GTM→document_number (DPI), HND→document_number (DNI), MEX→personal_number (CURP, 18 caracteres), PAN→personal_number (Cédula), PER→personal_number (DNI, 8 dígitos), PRY→document_number (CI), SLV→document_number (DUI), URY→personal_number (CI), VEN→document_number (Cédula). Ele nunca substitui um campo específico do país informado explicitamente. first_name: type: string description: >- O nome da pessoa física. Obrigatório para alguns serviços/países. example: John last_name: type: string description: >- O sobrenome da pessoa física. Obrigatório para alguns serviços/países. example: Doe middle_name: type: string description: >- Nome do meio, usado por alguns serviços de países (AUS, NZL, …). full_name: type: string description: >- Nome completo. Alguns serviços aceitam este campo no lugar do nome e sobrenome (por exemplo, os serviços CHN, que fazem a correspondência com o nome na escrita nativa). date_of_birth: type: string format: date description: >- Data de nascimento, `YYYY-MM-DD`. Exigida por muitos serviços. example: '1980-01-01' personal_number: type: string description: >- Identificador pessoal único emitido pelo governo. Usado por: CHL (RUT), COL (Cédula), CRI, DOM, ECU, ESP (DNI/NIE), MEX (CURP), PAN (Cédula), PER (DNI), URY. Considere usar `identification_number` em vez disso. tax_number: type: string description: >- Número de identificação fiscal. Usado por: BRA (CPF, 11 dígitos). Considere usar `identification_number`. document_number: type: string description: >- Número do documento. Usado por: ARG (DNI), BOL (CI), GTM (DPI), HND (DNI), PRY (CI), SLV (DUI), VEN (Cédula). Considere usar `identification_number` em vez dele. document_type: type: string enum: - P - DL - ID - RP - SSC - HIC - WP - TC - VISA - PSC - BC - OTHER description: >- Tipo de documento validado: `P` passaporte, `DL` carteira de motorista, `ID` documento nacional de identidade, `RP` autorização de residência (além de `SSC`, `HIC`, `WP`, `TC`, `VISA`, `PSC`, `BC`, `OTHER`). Exigido por alguns serviços (por exemplo, ESP). expiration_date: type: string format: date description: >- Data de validade do documento, `YYYY-MM-DD`. Obrigatória para a validação ESP (Espanha). example: '2030-01-15' date_of_issue: type: string format: date description: >- Data de emissão do documento, `YYYY-MM-DD` (fecha de expedición). Obrigatória para a validação da cédula COL (Colômbia). example: '2015-06-20' nationality: type: string description: >- Nacionalidade no formato ISO 3166-1 alpha-3. Obrigatória para alguns serviços. gender: type: string enum: - M - F - X description: >- Gênero: `M`, `F` ou `X` (outro/desconhecido). Obrigatório para a validação RENAPER da Argentina (`arg_renaper`). address: description: >- Endereço residencial. Prefira o objeto estruturado `{"street_1":"123 Main St","street_2":"Apt 4B","city":"Springfield","region":"IL","postal_code":"62701","country":"US"}`; uma string completa em uma única linha ainda é aceita. Obrigatório para serviços de verificação de endereço; quando um serviço define requisitos de endereço, partes ausentes retornam `400` com `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: Endereço completo em uma única linha (legado). address_element_1: type: string description: >- Endereço incluindo número e tipo de logradouro. Se omitido, é derivado de `address`. address_element_2: type: string description: >- Apartamento, unidade, edifício, andar ou linha adicional do endereço. Envie apenas quando tiver essa informação explicitamente. address_element_3: type: string description: >- Cidade, subúrbio, distrito, localidade ou bairro. Se omitido, é derivado de `address`. address_element_4: type: string description: >- Estado, província, região ou cidade. Se omitido, é derivado de `address`. address_element_5: type: string description: CEP ou código postal. `postal_code` é aceito como alias. postal_code: type: string description: >- Código postal para serviços baseados em endereço (alias de `address_element_5`). driver_license_number: type: string description: >- Número da carteira de motorista para serviços governamentais de verificação de documentos (AUS, NZL, IND). driver_license_card_number: type: string description: >- Número do cartão físico da carteira de motorista, quando exigido separadamente do número da carteira (AUS). driver_license_state: type: string description: Estado ou território emissor da carteira de motorista (AUS). driver_license_version: type: string description: Código de versão da carteira de motorista (NZL). passport_number: type: string description: >- Número do passaporte para serviços governamentais de verificação de passaporte (AUS, NZL, IND, CHN). passport_expiration_date: type: string format: date description: >- Data de validade do passaporte, `YYYY-MM-DD`, para serviços de verificação de passaporte. passport_file_number: type: string description: Número de arquivo do passaporte (IND). passport_issue_country: type: string description: >- País emissor do passaporte (ISO 3166-1 alpha-3) para serviços de verificação de passaporte. medicare_card_number: type: string description: Número do cartão Medicare (AUS). immi_card_number: type: string description: Número do ImmiCard australiano. immi_card_expiry_date: type: string format: date description: Data de validade do ImmiCard australiano. citizenship_certificate_number: type: string description: Número do certificado de cidadania (AUS). birth_registration_number: type: string description: Número de registro da certidão de nascimento (AUS). birth_registration_date: type: string format: date description: Data de registro da certidão de nascimento (AUS). birth_registration_state: type: string description: Estado de registro da certidão de nascimento (AUS). marriage_certificate_number: type: string description: Número da certidão de casamento (AUS). change_of_name_certificate_number: type: string description: Número da certidão de mudança de nome (AUS). first_partner_name: type: string description: Primeiro nome do cônjuge em uma certidão de casamento (AUS). last_partner_name: type: string description: Sobrenome do cônjuge em uma certidão de casamento (AUS). voter_id: type: string description: Número de registro eleitoral (IND EPIC, IRL). epic_card: type: string description: Número do título de eleitor EPIC da Índia. pan: type: string description: PAN (Permanent Account Number) da Índia. national_id: type: string description: >- Número de identidade nacional (CHN, MYS, KEN, KHM, NGA, ZAF, …). cic: type: string description: >- Código de Identificación de Credencial (CIC) do INE/IFE mexicano, 9 dígitos. Usado pelo serviço de validade da credencial INE do México (`mex_ine_vigencia`). identificador_ciudadano: type: string description: >- Identificador del Ciudadano do INE mexicano (9 dígitos). Usado com `cic` para os modelos modernos do INE (E/F/G/H) em `mex_ine_vigencia`. ocr: type: string description: >- Número OCR do INE mexicano (13 dígitos, no verso do cartão). Usado com `cic` para o Modelo D em `mex_ine_vigencia`. voter_number: type: string description: >- Clave de Elector do INE mexicano (18 caracteres). Usada com `emission_number` para os modelos antigos do IFE (A/B/C) em `mex_ine_vigencia`. emission_number: type: string description: >- Número de Emisión do INE mexicano. Usado com `voter_number` para os modelos antigos do IFE (A/B/C) em `mex_ine_vigencia`. bvn: type: string description: Bank Verification Number (BVN) da Nigéria. bank_card_number: type: string description: >- Número do cartão bancário (verificação de cartão bancário da CHN). company_registration_number: type: string description: >- Número de registro da empresa emitido pelo registro de empresas: o CNPJ no Brasil (por exemplo, `11222333000181`), o número de registro na África do Sul (por exemplo, `1936/007721/06`). Obrigatório para os serviços de registro de empresas e de diretores de empresas (`bra_company_registry`, `bra_company_directors`, `zaf_company_registry`, `zaf_company_directors`). company_name: type: string description: >- Razão social registrada, verificada em relação ao registro. Opcional para `zaf_company_registry`. initials: type: string description: >- As iniciais da pessoa conforme impressas no documento. Obrigatório para `zaf_drivers_license`; aceito por `zaf_bank_account_holder`. licence_number: type: string description: >- Número da carteira de motorista conforme impresso no cartão, para `zaf_drivers_license`. Quando omitido, é usado o `document_number`. refugee_file_number: type: string description: >- Número do processo de refugiado emitido pelo Department of Home Affairs da África do Sul. Obrigatório para `zaf_refugee`. bank_name: type: string description: >- Nome do banco que mantém a conta. Obrigatório para `zaf_bank_account_holder`. bank_account_number: type: string description: >- Número da conta bancária. Obrigatório para `zaf_bank_account_holder`; aceito por `zaf_fraud_prevention`. account_type: type: string description: >- Tipo de conta bancária para `zaf_bank_account_holder`: `current`, `savings`, `transmission`, `subscriptionShare` ou `notKnown`, sem diferenciar maiúsculas de minúsculas. Qualquer outro valor retorna `400`. Omita-o quando não souber o tipo: nesse caso, a verificação cruzada do tipo de conta é reportada como não confirmada. phone_number: type: string description: >- Número de celular de contato, para os serviços que verificam a contactabilidade (`zaf_bank_account_holder`, `zaf_fraud_prevention`, `zaf_refugee`). right_thumb: type: string description: >- Impressão digital do polegar direito codificada em Base64 para `zaf_dha_fingerprint_match`, junto com `left_thumb` ou sozinha. left_thumb: type: string description: >- Impressão digital do polegar esquerdo codificada em Base64 para `zaf_dha_fingerprint_match`, junto com `right_thumb` ou sozinha. score_level: type: integer description: >- Nível mínimo de pontuação biométrica para `zaf_criminal_face_screening`. O padrão é `3`. max_matches: type: integer description: >- Número máximo de correspondências candidatas que `zaf_criminal_face_screening` retorna. O padrão é `1`. vehicle_register_number: type: string description: >- Número de registro do veículo. Obrigatório, junto com `vehicle_licence_plate` e `vin`, para `zaf_vehicle_ownership`. vehicle_licence_plate: type: string description: >- Número da placa do veículo. Obrigatório, junto com `vehicle_register_number` e `vin`, para `zaf_vehicle_ownership`. vin: type: string description: >- Número de identificação do veículo (VIN ou número do chassi). Obrigatório, junto com `vehicle_register_number` e `vehicle_licence_plate`, para `zaf_vehicle_ownership`. ssn: type: string description: Número do Seguro Social (Social Security Number, EUA). phone: type: string description: Número de telefone para serviços de verificação de telefone. landline: type: string description: >- Número de telefone fixo para serviços de verificação de telefone. email: type: string format: email description: >- Endereço de e-mail para serviços de verificação de identidade. country_of_residence: type: string description: >- País de residência em ISO 3166-1 alpha-2. Usado por serviços globais de enriquecimento de identidade (por exemplo, `glb_identity_enrichment`) para direcionar a consulta. example: US partial_match_action: type: string enum: - DECLINE - NO_ACTION default: NO_ACTION description: >- O efeito de um `partial_match` em `database_validation.status`. O padrão é `NO_ACTION` (o status permanece `Approved`, com um aviso). no_match_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- O efeito de um `no_match` em `database_validation.status`. O padrão é `DECLINE`. save_api_request: type: boolean default: true description: >- Persiste a validação como uma sessão (visibilidade no console, endpoint de decisão, webhook `status.updated`). Também altera o formato da resposta `validations`: objetos por serviço quando `true` (padrão), um mapa de campos mesclado quando `false`. vendor_data: type: string description: >- Seu identificador para o usuário validado; retornado na resposta e armazenado com a sessão. metadata: type: object nullable: true description: >- JSON livre armazenado com a requisição e retornado na 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: >- Código de país ISO 3166-1 **alpha-3** do registro a ser usado na validação (por exemplo, `BRA`, `ESP`, `COL`). Determina quais serviços estão disponíveis. Códigos não suportados retornam `400` com a lista completa de opções válidas. example: BRA services: type: array items: type: string description: >- `service_id`s do catálogo a executar para este país (por exemplo, `["bra_cpf"]`). Também aceita uma única string ou uma string separada por vírgulas ou codificada em JSON. **Se omitido ou vazio, exatamente um serviço padrão é executado**: o serviço ativo mais antigo do país; serviços mais novos, biométricos e com pagamento por uso devem ser indicados explicitamente. Enviar `services` muda a resposta para o formato estendido (adiciona `services_used` e `match_score`). Todo id deve existir e estar ativo para o `issuing_state`; serviços que exigem onboarding retornam `400` até serem ativados para a sua organização. Descubra os serviços disponíveis por país via `GET /v1/organization/database-validation-countries/` (um endpoint de catálogo não documentado nesta especificação) ou no editor de fluxos do Business Console. example: - bra_cpf validation_type: type: string deprecated: true description: >- OBSOLETO. Aceito por compatibilidade com versões anteriores, mas ignorado: o `validation_type` da resposta agora é derivado de quantos serviços tiveram correspondência total. Use `services` para fixar serviços específicos. consent: type: boolean default: false description: >- Defina como `true` quando o usuário final tiver consentido explicitamente com os serviços de validação selecionados. Obrigatório para serviços marcados com `requires_consent=true` no catálogo; sem isso, esses serviços retornam `400` com `services_requiring_consent`. identification_number: type: string description: >- Número de identificação universal, mapeado automaticamente para o campo específico do país correto, para que você possa usá-lo em vez de `personal_number`/`tax_number`/`document_number`: ARG→document_number (DNI), BOL→document_number (CI), BRA→tax_number (CPF, 11 dígitos), CHL→personal_number (RUT), COL→personal_number (Cédula), CRI→personal_number (Cédula), DOM→personal_number (Cédula, 11 dígitos), ECU→personal_number (Cédula, 10 dígitos), ESP→personal_number (DNI/NIE), GTM→document_number (DPI), HND→document_number (DNI), MEX→personal_number (CURP, 18 caracteres), PAN→personal_number (Cédula), PER→personal_number (DNI, 8 dígitos), PRY→document_number (CI), SLV→document_number (DUI), URY→personal_number (CI), VEN→document_number (Cédula). Ele nunca substitui um campo específico do país informado explicitamente. first_name: type: string description: >- O nome da pessoa física. Obrigatório para alguns serviços/países. example: John last_name: type: string description: >- O sobrenome da pessoa física. Obrigatório para alguns serviços/países. example: Doe middle_name: type: string description: >- Nome do meio, usado por alguns serviços de países (AUS, NZL, …). full_name: type: string description: >- Nome completo. Alguns serviços aceitam este campo no lugar do nome e sobrenome (por exemplo, os serviços CHN, que fazem a correspondência com o nome na escrita nativa). date_of_birth: type: string format: date description: >- Data de nascimento, `YYYY-MM-DD`. Exigida por muitos serviços. example: '1980-01-01' personal_number: type: string description: >- Identificador pessoal único emitido pelo governo. Usado por: CHL (RUT), COL (Cédula), CRI, DOM, ECU, ESP (DNI/NIE), MEX (CURP), PAN (Cédula), PER (DNI), URY. Considere usar `identification_number` em vez disso. tax_number: type: string description: >- Número de identificação fiscal. Usado por: BRA (CPF, 11 dígitos). Considere usar `identification_number`. document_number: type: string description: >- Número do documento. Usado por: ARG (DNI), BOL (CI), GTM (DPI), HND (DNI), PRY (CI), SLV (DUI), VEN (Cédula). Considere usar `identification_number` em vez dele. document_type: type: string enum: - P - DL - ID - RP - SSC - HIC - WP - TC - VISA - PSC - BC - OTHER description: >- Tipo de documento validado: `P` passaporte, `DL` carteira de motorista, `ID` documento nacional de identidade, `RP` autorização de residência (além de `SSC`, `HIC`, `WP`, `TC`, `VISA`, `PSC`, `BC`, `OTHER`). Exigido por alguns serviços (por exemplo, ESP). expiration_date: type: string format: date description: >- Data de validade do documento, `YYYY-MM-DD`. Obrigatória para a validação ESP (Espanha). example: '2030-01-15' date_of_issue: type: string format: date description: >- Data de emissão do documento, `YYYY-MM-DD` (fecha de expedición). Obrigatória para a validação da cédula COL (Colômbia). example: '2015-06-20' nationality: type: string description: >- Nacionalidade no formato ISO 3166-1 alpha-3. Obrigatória para alguns serviços. gender: type: string enum: - M - F - X description: >- Gênero: `M`, `F` ou `X` (outro/desconhecido). Obrigatório para a validação RENAPER da Argentina (`arg_renaper`). address: description: >- Endereço residencial. Prefira o objeto estruturado `{"street_1":"123 Main St","street_2":"Apt 4B","city":"Springfield","region":"IL","postal_code":"62701","country":"US"}`; uma string completa em uma única linha ainda é aceita. Obrigatório para serviços de verificação de endereço; quando um serviço define requisitos de endereço, partes ausentes retornam `400` com `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: Endereço completo em uma única linha (legado). address_element_1: type: string description: >- Endereço incluindo número e tipo de logradouro. Se omitido, é derivado de `address`. address_element_2: type: string description: >- Apartamento, unidade, edifício, andar ou linha adicional do endereço. Envie apenas quando tiver essa informação explicitamente. address_element_3: type: string description: >- Cidade, subúrbio, distrito, localidade ou bairro. Se omitido, é derivado de `address`. address_element_4: type: string description: >- Estado, província, região ou cidade. Se omitido, é derivado de `address`. address_element_5: type: string description: CEP ou código postal. `postal_code` é aceito como alias. postal_code: type: string description: >- Código postal para serviços baseados em endereço (alias de `address_element_5`). driver_license_number: type: string description: >- Número da carteira de motorista para serviços governamentais de verificação de documentos (AUS, NZL, IND). driver_license_card_number: type: string description: >- Número do cartão físico da carteira de motorista, quando exigido separadamente do número da carteira (AUS). driver_license_state: type: string description: Estado ou território emissor da carteira de motorista (AUS). driver_license_version: type: string description: Código de versão da carteira de motorista (NZL). passport_number: type: string description: >- Número do passaporte para serviços governamentais de verificação de passaporte (AUS, NZL, IND, CHN). passport_expiration_date: type: string format: date description: >- Data de validade do passaporte, `YYYY-MM-DD`, para serviços de verificação de passaporte. passport_file_number: type: string description: Número de arquivo do passaporte (IND). passport_issue_country: type: string description: >- País emissor do passaporte (ISO 3166-1 alpha-3) para serviços de verificação de passaporte. medicare_card_number: type: string description: Número do cartão Medicare (AUS). immi_card_number: type: string description: Número do ImmiCard australiano. immi_card_expiry_date: type: string format: date description: Data de validade do ImmiCard australiano. citizenship_certificate_number: type: string description: Número do certificado de cidadania (AUS). birth_registration_number: type: string description: Número de registro da certidão de nascimento (AUS). birth_registration_date: type: string format: date description: Data de registro da certidão de nascimento (AUS). birth_registration_state: type: string description: Estado de registro da certidão de nascimento (AUS). marriage_certificate_number: type: string description: Número da certidão de casamento (AUS). change_of_name_certificate_number: type: string description: Número da certidão de mudança de nome (AUS). first_partner_name: type: string description: Primeiro nome do cônjuge em uma certidão de casamento (AUS). last_partner_name: type: string description: Sobrenome do cônjuge em uma certidão de casamento (AUS). voter_id: type: string description: Número de registro eleitoral (IND EPIC, IRL). epic_card: type: string description: Número do título de eleitor EPIC da Índia. pan: type: string description: PAN (Permanent Account Number) da Índia. national_id: type: string description: >- Número de identidade nacional (CHN, MYS, KEN, KHM, NGA, ZAF, …). cic: type: string description: >- Código de Identificación de Credencial (CIC) do INE/IFE mexicano, 9 dígitos. Usado pelo serviço de validade da credencial INE do México (`mex_ine_vigencia`). identificador_ciudadano: type: string description: >- Identificador del Ciudadano do INE mexicano (9 dígitos). Usado com `cic` para os modelos modernos do INE (E/F/G/H) em `mex_ine_vigencia`. ocr: type: string description: >- Número OCR do INE mexicano (13 dígitos, no verso do cartão). Usado com `cic` para o Modelo D em `mex_ine_vigencia`. voter_number: type: string description: >- Clave de Elector do INE mexicano (18 caracteres). Usada com `emission_number` para os modelos antigos do IFE (A/B/C) em `mex_ine_vigencia`. emission_number: type: string description: >- Número de Emisión do INE mexicano. Usado com `voter_number` para os modelos antigos do IFE (A/B/C) em `mex_ine_vigencia`. bvn: type: string description: Bank Verification Number (BVN) da Nigéria. bank_card_number: type: string description: >- Número do cartão bancário (verificação de cartão bancário da CHN). company_registration_number: type: string description: >- Número de registro da empresa emitido pelo registro de empresas: o CNPJ no Brasil (por exemplo, `11222333000181`), o número de registro na África do Sul (por exemplo, `1936/007721/06`). Obrigatório para os serviços de registro de empresas e de diretores de empresas (`bra_company_registry`, `bra_company_directors`, `zaf_company_registry`, `zaf_company_directors`). company_name: type: string description: >- Razão social registrada, verificada em relação ao registro. Opcional para `zaf_company_registry`. initials: type: string description: >- As iniciais da pessoa conforme impressas no documento. Obrigatório para `zaf_drivers_license`; aceito por `zaf_bank_account_holder`. licence_number: type: string description: >- Número da carteira de motorista conforme impresso no cartão, para `zaf_drivers_license`. Quando omitido, é usado o `document_number`. refugee_file_number: type: string description: >- Número do processo de refugiado emitido pelo Department of Home Affairs da África do Sul. Obrigatório para `zaf_refugee`. bank_name: type: string description: >- Nome do banco que mantém a conta. Obrigatório para `zaf_bank_account_holder`. bank_account_number: type: string description: >- Número da conta bancária. Obrigatório para `zaf_bank_account_holder`; aceito por `zaf_fraud_prevention`. account_type: type: string description: >- Tipo de conta bancária para `zaf_bank_account_holder`: `current`, `savings`, `transmission`, `subscriptionShare` ou `notKnown`, sem diferenciar maiúsculas de minúsculas. Qualquer outro valor retorna `400`. Omita-o quando não souber o tipo: nesse caso, a verificação cruzada do tipo de conta é reportada como não confirmada. phone_number: type: string description: >- Número de celular de contato, para os serviços que verificam a contactabilidade (`zaf_bank_account_holder`, `zaf_fraud_prevention`, `zaf_refugee`). right_thumb: type: string description: >- Impressão digital do polegar direito codificada em Base64 para `zaf_dha_fingerprint_match`, junto com `left_thumb` ou sozinha. left_thumb: type: string description: >- Impressão digital do polegar esquerdo codificada em Base64 para `zaf_dha_fingerprint_match`, junto com `right_thumb` ou sozinha. score_level: type: integer description: >- Nível mínimo de pontuação biométrica para `zaf_criminal_face_screening`. O padrão é `3`. max_matches: type: integer description: >- Número máximo de correspondências candidatas que `zaf_criminal_face_screening` retorna. O padrão é `1`. vehicle_register_number: type: string description: >- Número de registro do veículo. Obrigatório, junto com `vehicle_licence_plate` e `vin`, para `zaf_vehicle_ownership`. vehicle_licence_plate: type: string description: >- Número da placa do veículo. Obrigatório, junto com `vehicle_register_number` e `vin`, para `zaf_vehicle_ownership`. vin: type: string description: >- Número de identificação do veículo (VIN ou número do chassi). Obrigatório, junto com `vehicle_register_number` e `vehicle_licence_plate`, para `zaf_vehicle_ownership`. ssn: type: string description: Número do Seguro Social (Social Security Number, EUA). phone: type: string description: Número de telefone para serviços de verificação de telefone. landline: type: string description: >- Número de telefone fixo para serviços de verificação de telefone. email: type: string format: email description: >- Endereço de e-mail para serviços de verificação de identidade. country_of_residence: type: string description: >- País de residência em ISO 3166-1 alpha-2. Usado por serviços globais de enriquecimento de identidade (por exemplo, `glb_identity_enrichment`) para direcionar a consulta. example: US partial_match_action: type: string enum: - DECLINE - NO_ACTION default: NO_ACTION description: >- O efeito de um `partial_match` em `database_validation.status`. O padrão é `NO_ACTION` (o status permanece `Approved`, com um aviso). no_match_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- O efeito de um `no_match` em `database_validation.status`. O padrão é `DECLINE`. save_api_request: type: boolean default: true description: >- Persiste a validação como uma sessão (visibilidade no console, endpoint de decisão, webhook `status.updated`). Também altera o formato da resposta `validations`: objetos por serviço quando `true` (padrão), um mapa de campos mesclado quando `false`. vendor_data: type: string description: >- Seu identificador para o usuário validado; retornado na resposta e armazenado com a sessão. metadata: type: object nullable: true description: >- JSON livre armazenado com a requisição e retornado na resposta. selfie: type: string format: binary description: >- Imagem da selfie (`jpg`, `jpeg`, `png`, `webp`; máximo de 2 MB, as imagens são comprimidas para cerca de 1,5 MB antes do envio ao registro) para serviços de validação biométrica, por exemplo RENAPER da Argentina (`arg_renaper`) e SIB do Panamá (`pan_cedula_sib`, `pan_cedula_sib_plus`). Obrigatória sempre que um serviço selecionado a listar como campo obrigatório. Disponível somente via `multipart/form-data`. responses: '200': description: >- Validação concluída: pelo menos um serviço selecionado retornou um resultado utilizável. Consulte `database_validation.match_type` para o resultado agregado, `validations` para as comparações de campos por serviço e os `outcome_code`s, e `errors` (quando presente) para os serviços que falharam. content: application/json: schema: type: object properties: request_id: type: string format: uuid description: >- ID da sessão persistida quando `save_api_request=true` (utilizável com `GET /v3/session/{sessionId}/decision/`); caso contrário, um UUID de correlação transitório. database_validation: type: object properties: status: type: string enum: - Approved - Declined - In Review description: >- `Declined` quando o `match_type` geral aciona uma ação `DECLINE` (`no_match_action` tem `DECLINE` como padrão, e `partial_match_action` tem `NO_ACTION`); `In Review` quando nenhum serviço produziu uma comparação utilizável, por exemplo quando o único serviço selecionado retornou `REGISTRY_UNAVAILABLE` ou `INCONCLUSIVE`; `Approved` caso contrário. Uma requisição que selecionou vários serviços pode ficar `Approved` pela correspondência de um serviço enquanto outro estava indisponível, então verifique também `errors` e os `outcome_code`s de cada serviço. issuing_state: type: string description: Eco do país ISO 3166-1 alpha-3 usado na validação. example: BRA validation_type: type: string enum: - one_by_one - two_by_two description: >- Derivado dos resultados: `two_by_two` quando ≥2 serviços distintos produziram uma correspondência completa (no número de identificação, no nome completo + data de nascimento juntos, ou no endereço sem contradições); `one_by_one` caso contrário. (O campo de mesmo nome na requisição está obsoleto e é ignorado.) screened_data: type: object description: >- Eco dos campos de entrada enviados aos serviços selecionados (datas normalizadas para `YYYY-MM-DD`; uma `selfie`, quando enviada, é retornada como URL pré-assinada; `consent_obtained: true` é adicionado quando o consentimento foi dado). match_type: type: string nullable: true enum: - full_match - partial_match - no_match description: >- Resultado geral agregado entre os serviços com comparações em nível de campo: qualquer `full_match` → `full_match`; caso contrário, qualquer `partial_match` → `partial_match`; caso contrário, `no_match`. Serviços que retornam apenas um resultado, como a triagem criminal biométrica, podem retornar `null`; consulte cada item em `validations` para ver o seu `outcome_code`. validations: description: >- O formato depende de `save_api_request`. **`true` (padrão):** um array de objetos por serviço (`service_id`, `service_name`, `validation`, `outcome_code`, `outcome_detail`, `source_data`). **`false`:** um único objeto plano que combina os resultados por campo de todos os serviços (`{"full_name": "full_match", ...}`). oneOf: - type: array items: type: object description: >- Resultado da validação por serviço (retornado quando `save_api_request=true`, o padrão). properties: service_id: type: string description: >- Id de catálogo do serviço que gerou este resultado (por exemplo, `bra_cpf`). example: bra_cpf service_name: type: string description: Nome legível do serviço no catálogo. example: Brazil - CPF status check validation: type: object description: >- Comparação campo a campo entre os seus dados de entrada e o registro oficial. As chaves são nomes canônicos de campo (`full_name`, `date_of_birth`, `identification_number`, `address`, …); os valores são `full_match`, `partial_match` ou `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: >- Resultado da consulta ao registro, independente de fornecedor. `MATCH`/`PARTIAL_MATCH`/`NO_MATCH` descrevem a comparação; `DOCUMENT_NOT_FOUND` significa que o identificador não está no registro; `INCONCLUSIVE` significa que o registro não conseguiu confirmar nem negar (encaminhado para revisão, NÃO é uma não correspondência); `BIOMETRIC_NO_MATCH` é uma divergência facial definitiva, enquanto `BIOMETRIC_IMAGE_UNUSABLE` é um problema técnico de imagem (refaça a selfie); `DECEASED`/`MINOR_BLOCKED` são resultados decorrentes da política do registro; `DOCUMENT_SUPERSEDED` significa que a identidade correspondeu, mas a edição do documento apresentado não é a que consta no registro (uma edição mais recente foi emitida); `INVALID_DOCUMENT_FORMAT`/`INVALID_INPUT` significam que o próprio registro rejeitou os dados enviados; `REGISTRY_UNAVAILABLE`/`REGISTRY_ERROR` indicam falhas no serviço de origem. outcome_detail: type: string nullable: true description: >- Detalhe bruto do status upstream que embasa o código de resultado (por exemplo, um código de status HTTP ou do registro). source_data: type: object nullable: true description: >- Visão limpa e normalizada do registro, com nomes de campo canônicos (`identification_number`, `first_name`, `last_name`, `date_of_birth`, além de indicadores específicos do registro). Os campos de imagem, quando presentes, são retornados como URLs pré-assinadas. - type: object additionalProperties: type: string enum: - full_match - partial_match - no_match description: >- Resultados mesclados no nível do campo (formato sem estado de `save_api_request=false`). warnings: type: array items: type: object properties: feature: type: string description: Recurso que emitiu o aviso. risk: type: string description: Identificador de risco legível por máquina. additional_data: type: object nullable: true description: >- Contexto adicional sobre o aviso, quando disponível. log_type: type: string description: >- `warning`, `information` ou `error`: como o risco afetou o resultado. short_description: type: string description: Resumo legível de uma linha. long_description: type: string description: Explicação completa e legível. description: >- `DATABASE_VALIDATION_NO_MATCH` ou `DATABASE_VALIDATION_PARTIAL_MATCH`, quando aplicável; vazio em uma correspondência total. errors: type: array description: >- Presente somente quando alguns (mas não todos) os serviços selecionados falharam. Cada entrada contém `service_id`, `code`, `message` e `retryable`. Um serviço informado aqui não aparece em `validations` nem em `services_used` e não é cobrado. Este array é o único lugar onde ele aparece, portanto inspecione-o mesmo quando `status` for `Approved`. items: type: object properties: service_id: type: string code: type: string example: empty_provider_response message: type: string retryable: type: boolean description: >- `true` quando o serviço não produziu resposta e tentar novamente mais tarde pode funcionar; `false` quando a fonte rejeitou os dados enviados e a entrada precisa ser corrigida antes. example: true services_used: type: array items: type: string description: >- Ids de catálogo dos serviços que retornaram um resultado faturável. **Presente apenas quando a requisição enviou `services` explicitamente.** match_score: type: number description: >- Fração (0.0–1.0) dos serviços tentados que produziram uma correspondência completa (no número de identificação, no nome completo + data de nascimento em conjunto, ou no endereço sem contradições). **Presente apenas quando a requisição enviou `services` explicitamente.** vendor_data: type: string nullable: true description: Eco dos `vendor_data` que você enviou. metadata: type: object nullable: true description: Eco do `metadata` que você enviou. created_at: type: string format: date-time examples: Full match (Approved): summary: >- Padrão save_api_request=true: objetos `validations` por serviço 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: >- A requisição enviou `services`: a resposta adiciona `services_used` e `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: >- O registro não corresponde — padrão `no_match_action=DECLINE` value: request_id: 0a1b2c3d-4e5f-6789-abcd-ef0123456789 database_validation: status: Declined issuing_state: BRA validation_type: one_by_one screened_data: tax_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' match_type: no_match validations: - validation: full_name: no_match date_of_birth: no_match identification_number: no_match outcome_code: NO_MATCH outcome_detail: '200' service_id: bra_cpf service_name: Brazil - CPF status check source_data: identification_number: '00987654321' first_name: TOTALLY last_name: DIFFERENT NAME date_of_birth: '1999-01-01' lgpd_minor: false minor_under_16: false minor_under_18: false warnings: - feature: DATABASE_VALIDATION risk: DATABASE_VALIDATION_NO_MATCH additional_data: null log_type: error short_description: Database validation no match long_description: >- The system identified a no match in the database validation, requiring further investigation. vendor_data: null metadata: null created_at: '2026-06-11T10:31:00.000000+00:00' Stateless (save_api_request=false): summary: >- `validations` é condensado em um mapa de campos mesclado; nada é armazenado 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: >- Erro de validação: nada é faturado. Os erros de campo da verificação prévia ocorrem antes de qualquer chamada externa. Se todas as tentativas sem resposta recusarem explicitamente a entrada, a resposta passa a incluir `validation_errors` com `code: provider_rejected_input` e `retryable: false`; corrija a entrada antes de tentar novamente. Problemas no nível de campo usam o envelope padrão do DRF. Problemas de catálogo retornam um array `services` (mais `requires_onboarding` ou `services_requiring_consent`, quando relevante). Erros de campo ausente incluem `fields_required_by`, que mapeia cada campo ausente para os serviços que o exigem. Serviços que precisam de pelo menos um identificador extra (por exemplo, `usa_states_credit_bureau`, que não consegue verificar apenas um nome) retornam `any_field_required_by`, que mapeia cada serviço para os campos dos quais pelo menos um deve estar presente. Problemas de formato verificados por serviço retornam `invalid_fields_by_service`. content: application/json: examples: Invalid issuing_state: summary: >- País não suportado — a mensagem lista todos os códigos alpha-3 válidos 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ão dos campos obrigatórios dos serviços selecionados, com a indicação de campo 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ém um id que não está no catálogo' value: services: - 'Unknown service_id(s): [''bogus_service'']' Service not live for country: summary: >- `services` indica um serviço de outro país (ou uma entrada provisória) value: services: - >- Services not currently live for PER: ['bra_cpf']. Available services: ['per_dni', 'per_residential', 'per_tax_registration'] Service requires onboarding: summary: >- O serviço existe, mas ainda não foi ativado para a sua organização 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: >- Um serviço selecionado está marcado com requires_consent=true e `consent` não 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: >- O identificador não atende à regra de formato do país (comprimento/dígitos/regex) value: tax_number: - >- Invalid tax number for BRA: Brazilian CPF (exactly 11 digits). Must be exactly 11 characters long (got 10). Service-specific format violation: summary: >- Um campo não atende aos requisitos de formato do próprio serviço selecionado 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: Corrija a entrada antes de tentar novamente 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: >- Explicação no nível da requisição ou erros de campo da verificação prévia. oneOf: - type: string - type: array items: type: string validation_errors: type: array description: >- Presente quando todas as tentativas sem resposta recusaram a entrada após a pré-verificação. items: type: object properties: service_id: type: string code: type: string message: type: string retryable: type: boolean description: >- Indica se tentar novamente mais tarde pode resolver esta falha do serviço. False significa que é preciso corrigir primeiro a entrada fornecida. '403': description: >- Permissão negada. Retornado quando o cabeçalho `x-api-key` está ausente e também quando o saldo da organização que faz a chamada não cobre a chamada; uma chave incorreta, revogada ou expirada retorna `401`. Uma chave ausente retorna `403` com `{"detail": ...}`; uma chave incorreta, revogada ou expirada retorna `401`. Créditos insuficientes retornam `403` com `{"error": ...}` antes de qualquer análise ou chamada a provedores. content: application/json: examples: Missing or invalid API key: summary: Nenhum cabeçalho `x-api-key`, ou a chave é inválida/revogada value: detail: You do not have permission to perform this action. Not enough credits: summary: O saldo da organização não cobre a chamada value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Limite de requisições excedido. Todos os endpoints POST/PATCH/DELETE compartilham uma cota de 300 requisições de escrita por minuto por chave de API. A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Mais de 300 requisições de escrita no minuto atual 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: >- Nenhum serviço selecionado retornou um resultado utilizável. Inspecione cada entrada de validation_errors antes de tentar novamente; um HTTP 502 por si só não indica uma falha transitória. Uma entrada empty_provider_response com retryable: true indica resultados indisponíveis ou sem explicação, incluindo uma recusa do provedor principal seguida de um fallback indisponível. Já as entradas legadas provider_invalid_input e provider_validation_error exigem a correção da entrada e podem omitir retryable. Nada é cobrado. Quando save_api_request=true, a tentativa com falha é registrada como uma sessão com status Not Finished. Falhas parciais retornam 200 com 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 se tentar novamente mais tarde pode resolver esta falha do serviço. False significa que é preciso corrigir primeiro a entrada fornecida. examples: Provider returned no result: summary: Todos os serviços selecionados falharam 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: >- Chave de API da sua aplicação, em Developers -> API keys no Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter escopo restrito: nenhum acesso, leitura ou escrita por recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está errada, revogada ou expirada; 403 significa que nenhuma chave foi enviada, que a chave não tem acesso a este recurso ou ação, ou que a requisição veio de um endereço fora da sua lista de IPs; 404 em uma rota de sessão significa que a sessão está fora dos fluxos ou status da chave. Uma chave sem acesso a mídia recebe URLs de imagem, vídeo e PDF como null, e uma chave sem permissão de escrita em sessões recebe links e tokens de sessão como null. Consulte https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.