Address Validation API: Verify and Normalise Addresses

curl

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"
  }'

import os, requests

resp = requests.post(
    "https://verification.didit.me/v3/address-validation/",
    headers={"x-api-key": os.environ["DIDIT_API_KEY"], "Content-Type": "application/json"},
    json={
        "address_line_1": "1600 Amphitheatre Pkwy",
        "city": "Mountain View",
        "region": "CA",
        "postal_code": "94043",
        "country": "US",
    },
    timeout=15,
)
resp.raise_for_status()
result = resp.json()["address_validation"]
print(result["status"], result["formatted_address"])

const res = await fetch('https://verification.didit.me/v3/address-validation/', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ address: 'Paseo de la Castellana 259, 28046 Madrid', country: 'ES' }),
});
const { address_validation } = await res.json();
console.log(address_validation.status, address_validation.formatted_address);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://verification.didit.me/v3/address-validation/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'address_line_1' => '1600 Amphitheatre Pkwy',
    'city' => 'Mountain View',
    'region' => 'CA',
    'postal_code' => '94043',
    'country' => 'US'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://verification.didit.me/v3/address-validation/"

	payload := strings.NewReader("{\n  \"address_line_1\": \"1600 Amphitheatre Pkwy\",\n  \"city\": \"Mountain View\",\n  \"region\": \"CA\",\n  \"postal_code\": \"94043\",\n  \"country\": \"US\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://verification.didit.me/v3/address-validation/")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"address_line_1\": \"1600 Amphitheatre Pkwy\",\n  \"city\": \"Mountain View\",\n  \"region\": \"CA\",\n  \"postal_code\": \"94043\",\n  \"country\": \"US\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://verification.didit.me/v3/address-validation/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"address_line_1\": \"1600 Amphitheatre Pkwy\",\n  \"city\": \"Mountain View\",\n  \"region\": \"CA\",\n  \"postal_code\": \"94043\",\n  \"country\": \"US\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

POST

address-validation

curl

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"
  }'

import os, requests

resp = requests.post(
    "https://verification.didit.me/v3/address-validation/",
    headers={"x-api-key": os.environ["DIDIT_API_KEY"], "Content-Type": "application/json"},
    json={
        "address_line_1": "1600 Amphitheatre Pkwy",
        "city": "Mountain View",
        "region": "CA",
        "postal_code": "94043",
        "country": "US",
    },
    timeout=15,
)
resp.raise_for_status()
result = resp.json()["address_validation"]
print(result["status"], result["formatted_address"])

const res = await fetch('https://verification.didit.me/v3/address-validation/', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ address: 'Paseo de la Castellana 259, 28046 Madrid', country: 'ES' }),
});
const { address_validation } = await res.json();
console.log(address_validation.status, address_validation.formatted_address);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://verification.didit.me/v3/address-validation/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'address_line_1' => '1600 Amphitheatre Pkwy',
    'city' => 'Mountain View',
    'region' => 'CA',
    'postal_code' => '94043',
    'country' => 'US'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://verification.didit.me/v3/address-validation/"

	payload := strings.NewReader("{\n  \"address_line_1\": \"1600 Amphitheatre Pkwy\",\n  \"city\": \"Mountain View\",\n  \"region\": \"CA\",\n  \"postal_code\": \"94043\",\n  \"country\": \"US\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://verification.didit.me/v3/address-validation/")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"address_line_1\": \"1600 Amphitheatre Pkwy\",\n  \"city\": \"Mountain View\",\n  \"region\": \"CA\",\n  \"postal_code\": \"94043\",\n  \"country\": \"US\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://verification.didit.me/v3/address-validation/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"address_line_1\": \"1600 Amphitheatre Pkwy\",\n  \"city\": \"Mountain View\",\n  \"region\": \"CA\",\n  \"postal_code\": \"94043\",\n  \"country\": \"US\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

Didit’s Address Validation API confirms that a postal address exists and returns it normalised, with its delivery lines, components and coordinates. Use POST /v3/address-validation/ when your backend has an address and needs to know whether it exists, and in which normalised form. Address Validation confirms the address only. It never links the address to a person: a verified result means the place exists, not that anyone lives there.

Send the address

Send it on one line in address, or as structured fields: address_line_1 and, when you have them, address_line_2, city, region and postal_code. Never send both shapes in one request. country is always required, as an ISO 3166-1 alpha-2 or alpha-3 code.

Interpret the response

address_validation.status is the answer to build on:
- verified: the address was confirmed down to the building (or the flat or PO box).
- partially_verified: it was confirmed only to the street, or to the most precise level the postal reference data holds for that place.
- not_verified: only the region or the city matched, or nothing did.
- unavailable: the validation could not run. Retry later.
address_validation.verification_level is the most precise level matched: administrative_area, locality, thoroughfare, premise or delivery_point.
address_validation.address and address_validation.formatted_address carry the normalised address, written the way the country writes it.
address_validation.latitude and address_validation.longitude place the matched address.
request_id identifies the request. No session is created and the result is returned only in this response, so store what you need.

HTTP is 200 for every completed request, unavailable included.

Address Validation inside a workflow

The same check is an add-on of the ID Verification and Proof of Address workflow steps. Turn on address_validation_enabled in the step’s settings and the address the person supplied (printed on the identity document, or on the proof of address) is validated once their upload is read. The result is the address_validation object of that step’s entry in the session decision (id_verifications[] or poa_verifications[]). An address that is partially_verified or not_verified raises the ADDRESS_NOT_VERIFIED warning, whose action is the step’s address_not_verified_action (NO_ACTION by default, which only records the warning). An unavailable validation never raises it and never changes the verification.

Sandbox behavior

Sandbox keys validate the request and always return a deterministic verified result that echoes the address you sent. They do not consume credits.

Billing

An Address Validation API call costs $0.10 per validated address. An `unavailable` result is not charged. In a workflow, the add-on costs $0.10 per address a step validated.

Authorizations

x-api-key

string

header

required

Your application's API key, from Developers -> API keys in the Business Console. The primary key has full access. A named key can be scoped: none, read or write per resource, limited to some workflows or to approved sessions, to a list of IP addresses, and to an expiry date. 401 means the key is missing, wrong, revoked or expired; 403 means the key has no access to this resource or action, or the request came from an address outside its IP list; 404 on a session route means the session is outside the key's workflows or statuses. A key without media access receives image, video and PDF URLs as null, and a key without sessions write receives session links and tokens as null. See https://docs.didit.me/console/api-keys.

Body

application/json

One address: on one line (address) or as structured fields with at least address_line_1, never both.

country

string

required

ISO 3166-1 alpha-2 or alpha-3 code of the address's country.

Maximum string length: 3

Example:

"US"

address

string

The whole address on one line.

Maximum string length: 500

Example:

"Paseo de la Castellana 259, 28046 Madrid"

address_line_1

string

Street and number.

Maximum string length: 255

Example:

"1600 Amphitheatre Pkwy"

address_line_2

string

Apartment, suite, floor or building.

Maximum string length: 255

city

string

City or locality.

Maximum string length: 128

Example:

"Mountain View"

region

string

State, province or region.

Maximum string length: 128

Example:

"CA"

postal_code

string

Maximum string length: 32

Example:

"94043"

Response

The validation completed. Read address_validation.status; HTTP is always 200 for a completed request.

request_id

string<uuid>

required

Identifier of this request; quote it to support. No session is created.

address_validation

object

required

The result of one Address Validation: whether the address exists, and its normalised form. It confirms the address only; it never links the address to a person.

Show child attributes

created_at

string<date-time>

required

​Send the address

​Interpret the response

​Address Validation inside a workflow

​Sandbox behavior

​Billing

Authorizations

Body

Response

Send the address

Interpret the response

Address Validation inside a workflow

Sandbox behavior

Billing