> ## 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.

# Validação de morada API: verificar e normalizar moradas

> Didit: POST /v3/address-validation/ confirma que uma morada existe e devolve-a normalizada com coordenadas. $0.10 por morada.

Didit's Address Validation API confirma que uma morada postal existe e devolve-a normalizada, com as respetivas linhas de entrega, componentes e coordenadas. Use `POST /v3/address-validation/` quando o seu backend tiver uma morada e precisar de saber se ela existe e em que forma normalizada.

A Address Validation API confirma apenas a morada. Nunca associa a morada a uma pessoa: um resultado `verified` significa que o local existe, não que alguém lá viva.

## Envie a morada

Envie-a numa única linha em `address`, ou como campos estruturados: `address_line_1` e, quando os tiver, `address_line_2`, `city`, `region` e `postal_code`.
Nunca envie as duas formas no mesmo pedido.
`country` é sempre obrigatório, como código ISO 3166-1 alpha-2 ou alpha-3.

## Interprete a resposta

* `address_validation.status` é a resposta em que deve basear-se:
  * `verified`: a morada foi confirmada até ao edifício (ou ao apartamento ou à caixa postal).
  * `partially_verified`: foi confirmada apenas até à rua, ou até ao nível mais preciso que os dados de referência postais têm para esse local.
  * `not_verified`: só a região ou a cidade coincidiram, ou nada coincidiu.
  * `unavailable`: a validação não pôde ser executada. Tente novamente mais tarde.
* `address_validation.verification_level` é o nível mais preciso que coincidiu: `administrative_area`, `locality`, `thoroughfare`, `premise` ou `delivery_point`.
* `address_validation.address` e `address_validation.formatted_address` contêm a morada normalizada, escrita da forma como o país a escreve.
* `address_validation.latitude` e `address_validation.longitude` situam a morada encontrada.
* `request_id` identifica o pedido. Não é criada nenhuma sessão e o resultado é devolvido apenas nesta resposta, por isso guarde o que precisar.

O código HTTP é `200` para todos os pedidos concluídos, incluindo `unavailable`.

## Address Validation dentro de um fluxo

A mesma verificação é um complemento dos passos do fluxo de Verificação de identidade e de Comprovativo de morada.
Ative `address_validation_enabled` nas definições do passo, e a morada fornecida pela pessoa (impressa no documento de identidade ou no comprovativo de morada) é validada assim que o carregamento dela for lido.
O resultado é o objeto `address_validation` da entrada desse passo na decisão da sessão (`id_verifications[]` ou `poa_verifications[]`).
Uma morada `partially_verified` ou `not_verified` gera o aviso `ADDRESS_NOT_VERIFIED`, cuja ação é o `address_not_verified_action` do passo (`NO_ACTION` por predefinição, que apenas regista o aviso).
Uma validação `unavailable` nunca gera esse aviso e nunca altera a verificação.

## Comportamento no sandbox

As chaves de sandbox validam o pedido e devolvem sempre um resultado `verified` determinístico que repete a morada que enviou. Não consomem créditos.

## Faturação

Cada chamada à API de Address Validation custa $0.10 por morada validada.
Um resultado `unavailable` não é cobrado.
Num fluxo, o complemento custa $0.10 por cada morada validada num passo.


## OpenAPI

````yaml pt/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 uma morada
      description: >-
        Confirme que uma morada existe e obtenha-a normalizada: as suas linhas
        de entrega, componentes e coordenadas. Confirma apenas a morada; nunca
        associa a morada a uma pessoa.


        **Pedido.** Envie a morada numa única linha (`address`) ou como campos
        estruturados (`address_line_1` e, opcionalmente, `address_line_2`,
        `city`, `region`, `postal_code`), nunca ambos, e sempre o seu `country`
        (ISO 3166-1 alfa-2 ou alfa-3).


        **Resultado.** `address_validation.status` é `verified` (confirmado até
        ao edifício), `partially_verified` (confirmado apenas até à rua ou
        acima), `not_verified` (apenas a região ou cidade coincidiram, ou nada
        coincidiu) ou `unavailable` (não foi possível executar a validação). O
        código HTTP é `200` para todos os pedidos concluídos, incluindo
        `unavailable`; tente novamente um resultado `unavailable` mais tarde.


        **Faturação.** Uma chamada em produção custa $0.10 por morada validada.
        Um resultado `unavailable` não é cobrado. Nada é armazenado além do
        registo de utilização: nenhuma sessão é criada e o resultado é devolvido
        apenas nesta resposta.


        **Sandbox.** As chaves de sandbox validam o pedido e devolvem sempre um
        resultado determinístico `verified` que reflete a morada enviada, sem
        consumir créditos.


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


        **Limite de pedidos.** Orçamento de escrita partilhado de 300 pedidos
        por minuto por chave de API entre endpoints POST/PATCH/DELETE (a criação
        de transações e a ingestão de eventos têm um orçamento separado de 600).
      operationId: post_v3_address_validation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressValidationRequest'
            examples:
              Structured:
                summary: Campos de morada estruturada
                value:
                  address_line_1: 1600 Amphitheatre Pkwy
                  city: Mountain View
                  region: CA
                  postal_code: '94043'
                  country: US
              One line:
                summary: A morada completa numa linha
                value:
                  address: Paseo de la Castellana 259, 28046 Madrid
                  country: ES
      responses:
        '200':
          description: >-
            A validação foi concluída. Consulte `address_validation.status`; o
            HTTP é sempre `200` para um pedido concluído.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressValidationResponse'
              examples:
                Verified:
                  summary: Uma morada real, confirmada até ao 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 é cobrada
                  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: >-
        Uma morada: numa única linha (`address`) ou como campos estruturados com
        pelo menos `address_line_1`, nunca ambos.
      properties:
        address:
          type: string
          maxLength: 500
          description: A morada completa numa linha.
          example: Paseo de la Castellana 259, 28046 Madrid
        address_line_1:
          type: string
          maxLength: 255
          description: Rua e número.
          example: 1600 Amphitheatre Pkwy
        address_line_2:
          type: string
          maxLength: 255
          description: Apartamento, suite, piso 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 alfa-2 ou alfa-3 do país da morada.
          example: US
    AddressValidationResponse:
      type: object
      required:
        - request_id
        - address_validation
        - created_at
      properties:
        request_id:
          type: string
          format: uuid
          description: >-
            Identificador deste pedido; refira-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 a morada existe e a sua forma
        normalizada. Confirma apenas a morada; nunca associa a morada 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`: a morada foi confirmada até ao edifício (ou
            fração/apartamento ou apartado). `partially_verified`: foi
            confirmada apenas até à rua, ou até ao nível mais preciso que os
            dados de referência postal contêm para essa localização.
            `not_verified`: apenas a região ou a cidade corresponderam, ou nada
            correspondeu. `unavailable`: não foi possível executar a validação
            (por exemplo, o serviço de referência não respondeu); 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 com o qual a morada foi correspondida. `null`
            quando nada correspondeu ou `status` for `unavailable`.
        address:
          type: object
          nullable: true
          description: A morada normalizada. `null` quando `status` é `unavailable`.
          properties:
            address_line_1:
              type: string
              nullable: true
              description: >-
                Primeira linha de entrega, escrita da forma como o país a
                escreve.
              example: 1600 Amphitheatre Pkwy
            address_line_2:
              type: string
              nullable: true
              description: >-
                Segunda linha de entrega (um apartamento, edifício ou bairro),
                quando a morada possuir 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: A morada normalizada numa única 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 do pedido é inválido: um `country` em falta ou desconhecido, sem
        morada, ou com `address` e os campos estruturados em simultâneo.
      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á em falta ou é inválida, uma chave com âmbito carece
        de acesso de escrita a `sessions`, ou a organização não pode cobrir a
        validação. Esta API nunca devolve `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 de escrita partilhado de 300 pedidos por minuto por chave de
        API foi excedido. Respeite o `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: >-
        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.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.