> ## 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 endereço: verificar e normalizar

> A Didit confirma que o endereço existe e o retorna normalizado, com coordenadas, via POST /v3/address-validation/. $0.10 por endereço.

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.


## OpenAPI

````yaml pt-br/openapi-25.json POST /v3/address-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/address-validation/:
    post:
      tags:
        - Standalone APIs
      summary: Validar um endereço
      description: >-
        Confirme que um endereço existe e receba-o normalizado: suas linhas de
        entrega, componentes e coordenadas. A validação confirma apenas o
        endereço; ela nunca vincula o endereço a uma pessoa.


        **Requisição.** Envie o endereço em uma única linha (`address`) ou como
        campos estruturados (`address_line_1` e, opcionalmente,
        `address_line_2`, `city`, `region`, `postal_code`), nunca as duas
        formas, e sempre o seu `country` (ISO 3166-1 alfa-2 ou alfa-3).


        **Resultado.** `address_validation.status` é `verified` (confirmado até
        o nível do edifício), `partially_verified` (confirmado apenas até o
        nível da rua ou acima), `not_verified` (apenas a região ou a cidade
        correspondeu, ou nada correspondeu) ou `unavailable` (não foi possível
        executar a validação). O HTTP é `200` para toda requisição concluída,
        incluindo `unavailable`; tente novamente mais tarde quando o resultado
        for `unavailable`.


        **Faturamento.** Uma chamada em produção custa $0.10 por endereço
        validado. Um resultado `unavailable` não é cobrado. Nada é armazenado
        além do registro de uso: nenhuma sessão é criada e o resultado é
        retornado apenas nesta resposta.


        **Sandbox.** Chaves de sandbox validam a requisição e sempre retornam um
        resultado `verified` determinístico que repete o endereço enviado, sem
        consumir créditos.


        **Autenticação.** Envie a chave de API da sua aplicação em `x-api-key`.
        Credenciais ausentes ou inválidas retornam `403`: esta API nunca retorna
        `401`.


        **Limite de requisições.** Cota de escrita compartilhada de 300
        requisições por minuto por chave de API em todos os endpoints
        POST/PATCH/DELETE.
      operationId: post_v3_address_validation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressValidationRequest'
            examples:
              Structured:
                summary: Campos estruturados do endereço
                value:
                  address_line_1: 1600 Amphitheatre Pkwy
                  city: Mountain View
                  region: CA
                  postal_code: '94043'
                  country: US
              One line:
                summary: O endereço completo em uma linha
                value:
                  address: Paseo de la Castellana 259, 28046 Madrid
                  country: ES
      responses:
        '200':
          description: >-
            A validação foi concluída. Leia `address_validation.status`; o HTTP
            é sempre `200` para uma requisição concluída.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressValidationResponse'
              examples:
                Verified:
                  summary: Um endereço real, confirmado até o nível do edifício
                  value:
                    request_id: 6f7d2c1e-1c5a-4a1e-9b8f-2a1f0f4b9c3d
                    address_validation:
                      status: verified
                      verification_level: premise
                      address:
                        address_line_1: 1600 Amphitheatre Pkwy
                        address_line_2: null
                        city: Mountain View
                        region: CA
                        postal_code: 94043-1351
                        country: US
                      formatted_address: 1600 Amphitheatre Pkwy, Mountain View CA 94043-1351
                      latitude: 37.422022
                      longitude: -122.08429
                    created_at: '2026-10-27T11:20:00.000000+00:00'
                Not verified:
                  summary: 'Uma rua inventada: apenas a cidade correspondeu'
                  value:
                    request_id: 0b9e3f4a-6c2d-4e8b-a1f7-5d3c2b1a0e9f
                    address_validation:
                      status: not_verified
                      verification_level: locality
                      address:
                        address_line_1: Calle Inventada Que No Existe 99999 28046
                        address_line_2: null
                        city: Madrid
                        region: Madrid
                        postal_code: null
                        country: ES
                      formatted_address: >-
                        Calle Inventada Que No Existe 99999 28046, Madrid,
                        MADRID, SPAIN
                      latitude: 40.42603054
                      longitude: -3.68645331
                    created_at: '2026-10-27T11:21:00.000000+00:00'
                Unavailable:
                  summary: Não foi possível executar a validação; não cobrado
                  value:
                    request_id: 3c1b2a0f-9e8d-4c7b-b6a5-1f0e9d8c7b6a
                    address_validation:
                      status: unavailable
                      verification_level: null
                      address: null
                      formatted_address: null
                      latitude: null
                      longitude: null
                    created_at: '2026-10-27T11:22:00.000000+00:00'
        '400':
          $ref: '#/components/responses/AddressValidationValidationError'
        '403':
          $ref: '#/components/responses/AddressValidationPermissionDenied'
        '429':
          $ref: '#/components/responses/RateLimitedWrite'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST https://verification.didit.me/v3/address-validation/ \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "address_line_1": "1600 Amphitheatre Pkwy",
                "city": "Mountain View",
                "region": "CA",
                "postal_code": "94043",
                "country": "US"
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.address_validation.validate(
                address_line_1="1600 Amphitheatre Pkwy",
                city="Mountain View",
                region="CA",
                postal_code="94043",
                country="US",
            )
            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.addressValidation.validate({
              address_line_1: "1600 Amphitheatre Pkwy",
              city: "Mountain View",
              region: "CA",
              postal_code: "94043",
              country: "US",
            });
            console.log(result);
        - lang: java
          label: Java
          source: >-
            import me.didit.Didit;

            import me.didit.types.AddressValidationRequest;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.addressValidation().validate(AddressValidationRequest.builder()
                    .addressLine1("1600 Amphitheatre Pkwy")
                    .city("Mountain View")
                    .region("CA")
                    .postalCode("94043")
                    .country("US")
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;

            // Reads DIDIT_API_KEY.
            $didit = new DiditClient();

            $result = $didit->addressValidation->validate([
                'address_line_1' => '1600 Amphitheatre Pkwy',
                'city' => 'Mountain View',
                'region' => 'CA',
                'postal_code' => '94043',
                'country' => 'US',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.address_validation.validate(
              address_line_1: "1600 Amphitheatre Pkwy",
              city: "Mountain View",
              region: "CA",
              postal_code: "94043",
              country: "US"
            )
            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.AddressValidation.ValidateAsync(new
            AddressValidationRequest

            {
                AddressLine1 = "1600 Amphitheatre Pkwy",
                City = "Mountain View",
                Region = "CA",
                PostalCode = "94043",
                Country = "US",
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    AddressValidationRequest:
      type: object
      required:
        - country
      description: >-
        Um endereço: em uma única linha (`address`) ou como campos estruturados
        com pelo menos `address_line_1`, nunca ambos.
      properties:
        address:
          type: string
          maxLength: 500
          description: O endereço completo em uma linha.
          example: Paseo de la Castellana 259, 28046 Madrid
        address_line_1:
          type: string
          maxLength: 255
          description: Logradouro e número.
          example: 1600 Amphitheatre Pkwy
        address_line_2:
          type: string
          maxLength: 255
          description: Apartamento, sala, andar ou edifício.
        city:
          type: string
          maxLength: 128
          description: Cidade ou localidade.
          example: Mountain View
        region:
          type: string
          maxLength: 128
          description: Estado, província ou região.
          example: CA
        postal_code:
          type: string
          maxLength: 32
          example: '94043'
        country:
          type: string
          maxLength: 3
          description: Código ISO 3166-1 alpha-2 ou alpha-3 do país do endereço.
          example: US
    AddressValidationResponse:
      type: object
      required:
        - request_id
        - address_validation
        - created_at
      properties:
        request_id:
          type: string
          format: uuid
          description: >-
            Identificador desta requisição; informe-o ao suporte. Nenhuma sessão
            é criada.
        address_validation:
          $ref: '#/components/schemas/AddressValidationResult'
        created_at:
          type: string
          format: date-time
    AddressValidationResult:
      type: object
      description: >-
        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.
      required:
        - status
        - verification_level
        - address
        - formatted_address
        - latitude
        - longitude
      properties:
        status:
          type: string
          enum:
            - verified
            - partially_verified
            - not_verified
            - unavailable
          description: >-
            `verified`: o endereço foi confirmado até o nível do edifício (ou do
            apartamento ou da caixa postal). `partially_verified`: foi
            confirmado apenas até a rua, ou até o nível mais preciso que os
            dados postais de referência têm para aquele local. `not_verified`:
            apenas a região ou a cidade corresponderam, ou nada correspondeu.
            `unavailable`: a validação não pôde ser executada (por exemplo, o
            serviço de referência não respondeu); ela não é cobrada e nunca
            afeta uma verificação.
        verification_level:
          type: string
          nullable: true
          enum:
            - administrative_area
            - locality
            - thoroughfare
            - premise
            - delivery_point
            - null
          description: >-
            O nível mais preciso em que o endereço foi correspondido. `null`
            quando nada correspondeu ou `status` é `unavailable`.
        address:
          type: object
          nullable: true
          description: O endereço normalizado. `null` quando `status` é `unavailable`.
          properties:
            address_line_1:
              type: string
              nullable: true
              description: Primeira linha de entrega, escrita da forma usada no país.
              example: 1600 Amphitheatre Pkwy
            address_line_2:
              type: string
              nullable: true
              description: >-
                Segunda linha de entrega (apartamento, edifício ou bairro),
                quando o endereço tiver uma.
            city:
              type: string
              nullable: true
              example: Mountain View
            region:
              type: string
              nullable: true
              description: Estado, província ou região.
              example: CA
            postal_code:
              type: string
              nullable: true
              example: 94043-1351
            country:
              type: string
              nullable: true
              description: Código de país ISO 3166-1 alpha-2.
              example: US
        formatted_address:
          type: string
          nullable: true
          description: O endereço normalizado em uma linha.
          example: 1600 Amphitheatre Pkwy, Mountain View CA 94043-1351
        latitude:
          type: number
          nullable: true
          example: 37.422022
        longitude:
          type: number
          nullable: true
          example: -122.08429
  responses:
    AddressValidationValidationError:
      description: >-
        O corpo da requisição é inválido: `country` ausente ou desconhecido,
        nenhum endereço, ou tanto `address` quanto os campos estruturados.
      content:
        application/json:
          examples:
            Unknown country:
              value:
                country:
                  - >-
                    Use an ISO 3166-1 alpha-2 or alpha-3 country code, e.g. 'US'
                    or 'USA'.
            No address:
              value:
                address:
                  - >-
                    Send the address: 'address' on one line, or the structured
                    fields with 'address_line_1'.
            Both shapes:
              value:
                address:
                  - >-
                    Send either 'address' or the structured fields
                    (address_line_1, ...), not both.
    AddressValidationPermissionDenied:
      description: >-
        A chave de API está ausente ou é inválida, uma chave com escopo não tem
        acesso de escrita a `sessions`, ou a organização não consegue cobrir a
        validação. Esta API nunca retorna `401`.
      content:
        application/json:
          examples:
            Missing or invalid API key:
              value:
                detail: You do not have permission to perform this action.
            Not enough credits:
              value:
                detail: >-
                  You don't have enough credits to perform this request. Please
                  top up at https://business.didit.me
                code: insufficient_credits
    RateLimitedWrite:
      description: >-
        O limite compartilhado de escrita de 300 requisições por minuto por
        chave de API foi excedido. Respeite `Retry-After` antes de tentar
        novamente.
      content:
        application/json:
          schema:
            type: object
            required:
              - detail
            properties:
              detail:
                type: string
          example:
            detail: >-
              Write request rate limit exceeded. You can make up to 300 requests
              per minute.
  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.