Saltar para o conteúdo principal
POST
curl

Serviços baseados em morada

Para serviços que validam uma morada residencial ou de serviços públicos, pode enviar uma única address e a Didit irá separá-la antes de processar a verificação. Para obter a melhor taxa de correspondência, envie diretamente os campos de morada estruturados da Didit: Os campos estruturados substituem o valor de address. postal_code é aceite como alias de address_element_5.

Consentimento

Alguns serviços de base de dados exigem o consentimento explícito do utilizador final antes de o fornecedor poder ser consultado. O catálogo de serviços assinala estas linhas com requires_consent=true. Envie consent=true quando o consentimento do utilizador se aplicar aos serviços selecionados. A Didit rejeita o pedido antes de qualquer chamada ao fornecedor ou evento de faturação se um serviço selecionado exigir consentimento e não o enviar.

Carregamento de ficheiros

A validação de base de dados usa multipart/form-data. Os serviços biométricos que exigem selfie apresentam-na como um campo de carregamento de ficheiro no ambiente de teste da API, para que possa selecionar uma imagem diretamente, em vez de colar um caminho ou uma string base64. No código, carregue o ficheiro com a sintaxe multipart normal:

Erros de validação

A Didit valida os campos obrigatórios, a estrutura da morada e os formatos específicos de cada serviço antes de chamar o fornecedor. Por exemplo, os serviços de registo chineses, como chn_national_id e chn_passport_verification, esperam full_name no sistema de escrita chinês original, e chn_national_id exige também um número de identificação nacional chinês válido, com 15 ou 18 caracteres e uma soma de verificação correta. Se um pedido não puder ser executado, a API devolve erros explícitos por campo e não é cobrada qualquer utilização. Se um fornecedor falhar após a validação prévia, a resposta inclui validation_errors, e os pedidos de API guardados armazenam esses erros no resultado da validação de base de dados.

Entrada rejeitada e resultados indisponíveis

Quando nenhum serviço devolve um resultado utilizável, analise cada entrada de validation_errors antes de decidir se deve tentar novamente. O estado HTTP, por si só, não determina se uma nova tentativa é adequada. 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 voltar a tentar. Estas 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. Isto inclui uma entrada recusada seguida de um mecanismo alternativo indisponível, ou de um mecanismo alternativo que não fornece qualquer explicação. Tente novamente mais tarde; a resposta não indica que a entrada está errada. Se uma base de dados continuar a falhar, a Didit envia um email às organizações que a utilizaram recentemente, uma vez, quando a interrupção se prolongar, e novamente quando verificações reais confirmarem que está a responder. Consulte Notificações de disponibilidade. Quando apenas alguns dos serviços selecionados falham, o pedido é bem-sucedido: a resposta é 200 e os serviços com falha são listados em database_validation.errors[], cada um com os mesmos campos code e retryable. database_validation.status segue então 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 indicado aí está ausente de validations e de services_used, e não é faturado; volte a tentar apenas esse serviço. Outros erros 502 podem exigir dados corrigidos. Por exemplo, provider_invalid_input e provider_validation_error descrevem dados que a fonte rejeitou e não devem ser repetidos sem alteração, mesmo quando a resposta legada omite retryable. A orientação para novas tentativas de empty_provider_response não se aplica a estes códigos. Um resultado conclusivo sem correspondência é uma verificação concluída, não uma falha de disponibilidade.

Autorizações

x-api-key
string
header
obrigatório

A chave de API da sua aplicação, a partir de Programadores -> Chaves de API na Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter o âmbito definido: nenhum, 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á incorreta, 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 o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs como nulos, e uma chave sem permissão de escrita em sessões recebe ligações de sessão e tokens como nulos. Consulte https://docs.didit.me/console/api-keys.

Corpo

issuing_state
string
obrigatório

Código de país ISO 3166-1 alpha-3 do registo a validar (ex.: BRA, ESP, COL). Determina quais os serviços disponíveis. Códigos não suportados retornam 400 com a lista completa de opções válidas.

Exemplo:

"BRA"

services
string[]

service_ids do catálogo a executar para este país (por ex., ["bra_cpf"]). Também aceita uma única cadeia de caracteres ou uma cadeia separada por vírgulas/codificada em JSON. Se for omitido ou estiver vazio, é executado exatamente um serviço predefinido — o serviço em produção há mais tempo estabelecido para o país; serviços mais recentes, biométricos e de pagamento conforme a utilização têm de ser indicados explicitamente. Enviar services altera a resposta para o formato alargado (adiciona services_used e match_score). Cada ID tem de existir e estar em produção para o issuing_state; serviços que requerem onboarding devolvem 400 até serem ativados para a sua organização. Descubra os serviços disponíveis por país através de GET /v1/organization/database-validation-countries/ (um endpoint de catálogo não documentado nesta especificação) ou no editor de fluxos da Business Console.

Exemplo:
validation_type
string
obsoleto

OBSOLETO. Aceite para retrocompatibilidade, mas ignorado — o validation_type da resposta é agora derivado do número de serviços com correspondência total. Utilize services para fixar serviços específicos.

Defina como true quando o utilizador final tiver dado consentimento explícito aos serviços de validação selecionados. Obrigatório para serviços assinalados com requires_consent=true no catálogo — sem isso, esses serviços devolvem 400 com services_requiring_consent.

identification_number
string

Número de identificação universal — mapeado automaticamente para o campo específico do país correto, pelo que pode utilizá-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 carateres), 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). Nunca sobrepõe um campo específico do país fornecido explicitamente.

first_name
string

O primeiro nome do indivíduo. Obrigatório para alguns serviços/países.

Exemplo:

"John"

last_name
string

O apelido do indivíduo. Obrigatório para alguns serviços/países.

Exemplo:

"Doe"

middle_name
string

Segundo nome, utilizado por serviços de alguns países (AUS, NZL, …).

full_name
string

Nome completo — alguns serviços aceitam isto em vez de nome próprio/apelido (por exemplo, serviços CHN, que correspondem ao nome no sistema de escrita nativo).

date_of_birth
string<date>

Data de nascimento, YYYY-MM-DD. Obrigatória para muitos serviços.

Exemplo:

"1980-01-01"

personal_number
string

Identificador pessoal único emitido pelo governo. Utilizado por: CHL (RUT), COL (Cédula), CRI, DOM, ECU, ESP (DNI/NIE), MEX (CURP), PAN (Cédula), PER (DNI), URY. Considere utilizar identification_number em alternativa.

tax_number
string

Número de identificação fiscal. Utilizado por: BRA (CPF, 11 dígitos). Considere utilizar identification_number em alternativa.

document_number
string

Número do documento. Utilizado por: ARG (DNI), BOL (CI), GTM (DPI), HND (DNI), PRY (CI), SLV (DUI), VEN (Cédula). Considere utilizar identification_number.

document_type
enum<string>

Tipo de documento a validar: P passaporte, DL carta de condução, ID documento de identificação nacional, RP autorização de residência (mais SSC, HIC, WP, TC, VISA, PSC, BC, OTHER). Obrigatório em alguns serviços (por exemplo, ESP).

Opções disponíveis:
P,
DL,
ID,
RP,
SSC,
HIC,
WP,
TC,
VISA,
PSC,
BC,
OTHER
expiration_date
string<date>

Data de validade do documento, YYYY-MM-DD. Obrigatório para validação ESP (Espanha).

Exemplo:

"2030-01-15"

date_of_issue
string<date>

Data de emissão do documento, YYYY-MM-DD (fecha de expedición). Obrigatório para validação de cédula COL (Colômbia).

Exemplo:

"2015-06-20"

nationality
string

Nacionalidade em formato ISO 3166-1 alpha-3. Obrigatória para alguns serviços.

gender
enum<string>

Género: M, F ou X (outro/desconhecido). Obrigatório para a validação RENAPER da Argentina (arg_renaper).

Opções disponíveis:
M,
F,
X
address

Morada de residência. Dê preferência ao objeto estruturado {"street_1":"123 Main St","street_2":"Apt 4B","city":"Springfield","region":"IL","postal_code":"62701","country":"US"}; uma string completa numa única linha continua a ser aceite. Obrigatório para serviços de verificação de morada; quando um serviço define requisitos de morada, partes em falta devolvem 400 com address_fields_required_by.

address_element_1
string

Morada de rua, incluindo o número e o tipo de rua. Se omitida, é obtida a partir de address.

address_element_2
string

Apartamento, fração, edifício, piso ou linha de morada adicional. Envie-a apenas quando a tiver explicitamente.

address_element_3
string

Cidade, subúrbio, distrito, localidade ou bairro. Se omitido, é derivado de address.

address_element_4
string

Estado, província, região ou localidade. Se omitido, é derivado de address.

address_element_5
string

Código postal. postal_code é aceite como alias.

postal_code
string

Código postal para serviços baseados na morada (alias de address_element_5).

driver_license_number
string

Número da carta de condução para serviços de verificação de documentos governamentais (AUS, NZL, IND).

driver_license_card_number
string

Número do cartão físico da carta de condução, quando exigido separadamente do número da carta de condução (AUS).

driver_license_state
string

Estado ou território de emissão da carta de condução (AUS).

driver_license_version
string

Código da versão da carta de condução (NZL).

passport_number
string

Número do passaporte para serviços governamentais de verificação de passaportes (AUS, NZL, IND, CHN).

passport_expiration_date
string<date>

Data de validade do passaporte, YYYY-MM-DD, para serviços de verificação de passaportes.

passport_file_number
string

Número de ficheiro do passaporte (IND).

passport_issue_country
string

País emissor do passaporte (ISO 3166-1 alfa-3) para serviços de verificação de passaporte.

medicare_card_number
string

Número do cartão Medicare (AUS).

immi_card_number
string

Número do ImmiCard australiano.

immi_card_expiry_date
string<date>

Data de validade do ImmiCard australiano.

citizenship_certificate_number
string

Número do certificado de cidadania (AUS).

birth_registration_number
string

Número de registo da certidão de nascimento (AUS).

birth_registration_date
string<date>

Data de registo da certidão de nascimento (AUS).

birth_registration_state
string

Estado de registo da certidão de nascimento (AUS).

marriage_certificate_number
string

Número da certidão de casamento (AUS).

change_of_name_certificate_number
string

Número da certidão de alteração de nome (AUS).

first_partner_name
string

Primeiro nome do parceiro numa certidão de casamento (AUS).

last_partner_name
string

Apelido do cônjuge numa certidão de casamento (AUS).

voter_id
string

Número de recenseamento eleitoral (IND EPIC, IRL).

epic_card
string

Número do cartão de eleitor EPIC da Índia.

pan
string

PAN (Permanent Account Number) da Índia.

national_id
string

Número de identificação nacional (CHN, MYS, KEN, KHM, NGA, ZAF, …).

cic
string

Código de Identificación de Credencial (CIC) do INE/IFE mexicano, 9 dígitos. Utilizado pelo serviço de validade de credenciais do INE do México (mex_ine_vigencia).

identificador_ciudadano
string

Identificador del Ciudadano do INE mexicano (9 dígitos). Utilizado com cic para modelos INE modernos (E/F/G/H) em mex_ine_vigencia.

ocr
string

Número OCR do INE mexicano (13 dígitos, verso do cartão). Utilizado com cic para o Modelo D em mex_ine_vigencia.

voter_number
string

Clave de Elector do INE mexicano (18 carateres). Utilizado com emission_number para modelos IFE legados (A/B/C) em mex_ine_vigencia.

emission_number
string

Número de Emisión do INE mexicano. Utilizado com voter_number para modelos IFE legados (A/B/C) em mex_ine_vigencia.

bvn
string

Número de Verificação Bancária da Nigéria.

bank_card_number
string

Número do cartão bancário (verificação de cartões bancários CHN).

company_registration_number
string

Número de registo da empresa conforme emitido pelo registo de empresas: o CNPJ no Brasil (ex.: 11222333000181), o número de registo na África do Sul (ex.: 1936/007721/06). Obrigatório para os serviços de registo de empresas e de administradores da empresa (bra_company_registry, bra_company_directors, zaf_company_registry, zaf_company_directors).

company_name
string

Nome registado da empresa, comparado com a entrada no registo. Opcional para zaf_company_registry.

initials
string

As iniciais da pessoa conforme impressas no documento. Obrigatórias para zaf_drivers_license; aceites por zaf_bank_account_holder.

licence_number
string

Número da carta de condução tal como impresso no cartão, para zaf_drivers_license. Quando omitido, é utilizado document_number.

refugee_file_number
string

Número de processo de refugiado emitido pelo Department of Home Affairs da África do Sul. Obrigatório para zaf_refugee.

bank_name
string

Nome do banco detentor da conta. Obrigatório para zaf_bank_account_holder.

bank_account_number
string

Número de conta bancária. Obrigatório por zaf_bank_account_holder; aceite por zaf_fraud_prevention.

account_type
string

Tipo de conta bancária para zaf_bank_account_holder: current, savings, transmission, subscriptionShare ou notKnown, não sensível a maiúsculas/minúsculas. Qualquer outro valor devolve 400. Omita-o quando não souber o tipo: a verificação cruzada do tipo de conta é então reportada como não confirmada.

phone_number
string

Número de telemóvel de contacto, para os serviços que cruzam a contactabilidade (zaf_bank_account_holder, zaf_fraud_prevention, zaf_refugee).

right_thumb
string

Impressão digital do polegar direito codificada em base64 para zaf_dha_fingerprint_match, com left_thumb ou isoladamente.

left_thumb
string

Impressão digital do polegar esquerdo codificada em base64 para zaf_dha_fingerprint_match, com right_thumb ou isoladamente.

score_level
integer

Nível mínimo de pontuação biométrica para zaf_criminal_face_screening. O valor predefinido é 3.

max_matches
integer

Número máximo de correspondências candidatas devolvidas por zaf_criminal_face_screening. Assume por predefinição 1.

vehicle_register_number
string

Número de registo do veículo. Obrigatório, juntamente com vehicle_licence_plate e vin, para zaf_vehicle_ownership.

vehicle_licence_plate
string

Matrícula do veículo. Obrigatório, juntamente com vehicle_register_number e vin, para zaf_vehicle_ownership.

vin
string

Número de Identificação do Veículo (VIN ou número de chassis). Obrigatório, juntamente com vehicle_register_number e vehicle_licence_plate, para zaf_vehicle_ownership.

ssn
string

Número de Segurança Social (EUA).

phone
string

Número de telefone para serviços de verificação de telefone.

landline
string

Número de telefone fixo para serviços de verificação de telefone.

email
string<email>

Endereço de e-mail para serviços de verificação de identidade.

country_of_residence
string

País de residência ISO 3166-1 alfa-2. Utilizado por serviços globais de enriquecimento de identidade (por exemplo, glb_identity_enrichment) para direcionar a consulta.

Exemplo:

"US"

partial_match_action
enum<string>
padrão:NO_ACTION

O impacto que um partial_match tem em database_validation.status. A predefinição é NO_ACTION (o estado permanece Approved, com um aviso).

Opções disponíveis:
DECLINE,
NO_ACTION
no_match_action
enum<string>
padrão:DECLINE

O impacto que um no_match tem em database_validation.status. A predefinição é DECLINE.

Opções disponíveis:
DECLINE,
NO_ACTION
save_api_request
boolean
padrão:true

Persistir a validação como uma sessão (visibilidade na consola, endpoint de decisão, webhook status.updated). Também altera a estrutura da resposta de validations: objetos por serviço quando true (predefinição), um mapa de campos unificado quando false.

vendor_data
string

O seu identificador para o utilizador validado; devolvido e armazenado com a sessão.

metadata
object | null

JSON de formato livre armazenado com o pedido e devolvido na resposta.

Resposta

Validação concluída — pelo menos um serviço selecionado devolveu um resultado utilizável. Inspecione database_validation.match_type para o resultado agregado, validations para as comparações de campos por serviço e outcome_codes, e errors (quando presentes) para serviços que falharam.

request_id
string<uuid>

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
object
vendor_data
string | null

Eco do vendor_data que enviou.

metadata
object | null

Eco do objeto metadata que enviou.

created_at
string<date-time>
Última modificação em 7 de novembro de 2026