Pular para o conteúdo principal
POST
curl
A API de Address Validation da Didit confirma que um endereço postal existe e o retorna normalizado, com as linhas de endereço para entrega, os componentes e as coordenadas. Use POST /v3/address-validation/ quando o seu backend tiver um endereço e precisar saber se ele existe e qual é a sua forma normalizada. A validação de endereço confirma apenas o endereço. Ela nunca vincula o endereço a uma pessoa: um resultado verified significa que o local existe, não que alguém mora lá.

Envie o endereço

Envie-o em uma única linha no campo address ou como campos estruturados: address_line_1 e, quando disponíveis, address_line_2, city, region e postal_code. Nunca envie os dois formatos na mesma requisição. country é sempre obrigatório, na forma de um código ISO 3166-1 alfa-2 ou alfa-3.

Interprete a resposta

  • address_validation.status é a resposta em que você deve se basear:
    • verified: o endereço foi confirmado até o nível do edifício (ou do apartamento ou da caixa postal).
    • partially_verified: ele foi confirmado apenas até a rua, ou até o nível mais preciso que os dados de referência postal têm para aquele local.
    • not_verified: apenas a região ou a cidade teve correspondência, ou nada correspondeu.
    • unavailable: não foi possível executar a validação. Tente novamente mais tarde.
  • address_validation.verification_level é o nível mais preciso com correspondência: administrative_area, locality, thoroughfare, premise ou delivery_point.
  • address_validation.address e address_validation.formatted_address trazem o endereço normalizado, escrito da forma como o país o escreve.
  • address_validation.latitude e address_validation.longitude indicam a localização do endereço correspondente.
  • request_id identifica a requisição. Nenhuma sessão é criada e o resultado é retornado apenas nesta resposta, então armazene o que você precisar.
O status HTTP é 200 para toda requisição concluída, incluindo unavailable.

Validação de endereço dentro de um fluxo de verificação (workflow)

A mesma verificação é um complemento das etapas de Verificação de identidade e de Comprovante de endereço do fluxo. Ative address_validation_enabled nas configurações da etapa e o endereço informado pela pessoa (impresso no documento de identidade ou no comprovante de endereço) será validado assim que o upload dela for lido. O resultado é o objeto address_validation da entrada dessa etapa na decisão da sessão (id_verifications[] ou poa_verifications[]). Um endereço partially_verified ou not_verified gera o aviso ADDRESS_NOT_VERIFIED, cuja ação é o address_not_verified_action da etapa (NO_ACTION por padrão, que apenas registra o aviso). Uma validação unavailable nunca gera esse aviso e nunca altera a verificação.

Comportamento no sandbox

As chaves de sandbox validam a requisição e sempre retornam um resultado verified determinístico que repete o endereço que você enviou. Elas não consomem créditos.

Faturamento

Uma chamada à Address Validation API custa $0.10 por endereço validado. Um resultado `unavailable` não é cobrado. Em um fluxo, o complemento custa $0.10 por endereço validado por uma etapa.

Autorizações

x-api-key
string
header
obrigatório

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.

Corpo

application/json

Um endereço: em uma única linha (address) ou como campos estruturados com pelo menos address_line_1, nunca ambos.

country
string
obrigatório

Código ISO 3166-1 alpha-2 ou alpha-3 do país do endereço.

Maximum string length: 3
Exemplo:

"US"

address
string

O endereço completo em uma linha.

Maximum string length: 500
Exemplo:

"Paseo de la Castellana 259, 28046 Madrid"

address_line_1
string

Logradouro e número.

Maximum string length: 255
Exemplo:

"1600 Amphitheatre Pkwy"

address_line_2
string

Apartamento, sala, andar ou edifício.

Maximum string length: 255
city
string

Cidade ou localidade.

Maximum string length: 128
Exemplo:

"Mountain View"

region
string

Estado, província ou região.

Maximum string length: 128
Exemplo:

"CA"

postal_code
string
Maximum string length: 32
Exemplo:

"94043"

Resposta

A validação foi concluída. Leia address_validation.status; o HTTP é sempre 200 para uma requisição concluída.

request_id
string<uuid>
obrigatório

Identificador desta requisição; informe-o ao suporte. Nenhuma sessão é criada.

address_validation
object
obrigatório

O resultado de uma Address Validation: se o endereço existe e sua forma normalizada. Ela confirma apenas o endereço; nunca vincula o endereço a uma pessoa.

created_at
string<date-time>
obrigatório
Última modificação em 1 de novembro de 2026