> ## 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. # Address Validation API: Verify and Normalise Addresses > POST /v3/address-validation/ confirms an address exists and returns it normalised, with coordinates. Structured or one-line input, $0.10 per address. 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. ## OpenAPI ````yaml POST /v3/address-validation/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: Identity verification API. Authenticate with x-api-key header. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/address-validation/: post: tags: - Standalone APIs summary: Validate an address description: >- Confirm that an address exists and get it back normalised: its delivery lines, components and coordinates. It confirms the address only; it never links the address to a person. **Request.** Send the address on one line (`address`) or as structured fields (`address_line_1` and, optionally, `address_line_2`, `city`, `region`, `postal_code`), never both, and always its `country` (ISO 3166-1 alpha-2 or alpha-3). **Result.** `address_validation.status` is `verified` (confirmed to the building), `partially_verified` (confirmed only to the street or above), `not_verified` (only the region or city matched, or nothing did) or `unavailable` (the validation could not run). HTTP is `200` for every completed request, `unavailable` included; retry an `unavailable` result later. **Billing.** A live call costs $0.10 per validated address. An `unavailable` result is not charged. Nothing is stored apart from the usage record: no session is created and the result is returned only in this response. **Sandbox.** Sandbox keys validate the request and always return a deterministic `verified` result that echoes the address sent, without consuming credits. **Authentication.** Send your application's API key in `x-api-key`. Missing or invalid credentials return `403` - this API never returns `401`. **Rate limit.** Shared write budget of 300 requests per minute per API key across all POST/PATCH/DELETE endpoints. operationId: post_v3_address_validation requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AddressValidationRequest' examples: Structured: summary: Structured address fields value: address_line_1: 1600 Amphitheatre Pkwy city: Mountain View region: CA postal_code: '94043' country: US One line: summary: The whole address on one line value: address: Paseo de la Castellana 259, 28046 Madrid country: ES responses: '200': description: >- The validation completed. Read `address_validation.status`; HTTP is always `200` for a completed request. content: application/json: schema: $ref: '#/components/schemas/AddressValidationResponse' examples: Verified: summary: A real address, confirmed to the building 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: 'An invented street: only the city matched' 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: The validation could not run; not charged 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: |- 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"]) - lang: javascript label: JavaScript source: >- 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); components: schemas: AddressValidationRequest: type: object required: - country description: >- One address: on one line (`address`) or as structured fields with at least `address_line_1`, never both. properties: address: type: string maxLength: 500 description: The whole address on one line. example: Paseo de la Castellana 259, 28046 Madrid address_line_1: type: string maxLength: 255 description: Street and number. example: 1600 Amphitheatre Pkwy address_line_2: type: string maxLength: 255 description: Apartment, suite, floor or building. city: type: string maxLength: 128 description: City or locality. example: Mountain View region: type: string maxLength: 128 description: State, province or region. example: CA postal_code: type: string maxLength: 32 example: '94043' country: type: string maxLength: 3 description: ISO 3166-1 alpha-2 or alpha-3 code of the address's country. example: US AddressValidationResponse: type: object required: - request_id - address_validation - created_at properties: request_id: type: string format: uuid description: >- Identifier of this request; quote it to support. No session is created. address_validation: $ref: '#/components/schemas/AddressValidationResult' created_at: type: string format: date-time AddressValidationResult: type: object description: >- 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. required: - status - verification_level - address - formatted_address - latitude - longitude properties: status: type: string enum: - verified - partially_verified - not_verified - unavailable description: >- `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 (for example the reference service did not answer); it is not charged and never affects a verification. verification_level: type: string nullable: true enum: - administrative_area - locality - thoroughfare - premise - delivery_point - null description: >- The most precise level the address was matched to. `null` when nothing matched or `status` is `unavailable`. address: type: object nullable: true description: The normalised address. `null` when `status` is `unavailable`. properties: address_line_1: type: string nullable: true description: First delivery line, written the way the country writes it. example: 1600 Amphitheatre Pkwy address_line_2: type: string nullable: true description: >- Second delivery line (a flat, building or neighbourhood), when the address has one. city: type: string nullable: true example: Mountain View region: type: string nullable: true description: State, province or region. example: CA postal_code: type: string nullable: true example: 94043-1351 country: type: string nullable: true description: ISO 3166-1 alpha-2 country code. example: US formatted_address: type: string nullable: true description: The normalised address on one line. 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: >- The request body is invalid: a missing or unknown `country`, no address, or both `address` and the structured fields. 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: >- The API key is missing or invalid, a scoped key lacks `sessions` write access, or the organization cannot cover the validation. This API never returns `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: >- The shared write limit of 300 requests per minute per API key was exceeded. Honor `Retry-After` before retrying. 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: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.