---
title: "POST /addresses/{id}/validate"
method: POST
path: "/addresses/{id}/validate"
---

# POST /addresses/{id}/validate

`POST /addresses/{id}/validate`

## Request

- Base URL: `https://api.useanima.sh/v1`
- URL: `https://api.useanima.sh/v1/addresses/{id}/validate`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Structural (format-only) address validation: normalizes the country to ISO 3166-1 alpha-2, checks US state codes and ZIP shape, and verifies required fields are present. It does NOT check that the address exists or is deliverable, and `suggestions` is currently always empty (reserved for a future postal-data provider).

## Path parameters

- `id` string, required: Address identity identifier

## Request body

- object: Input for identifying a specific address identity
  - `agentId` union, required: Agent identifier that owns this address
    - string
    - string

## Response `200`

OK

- object: Address validation result. Validation is structural/format-only (provider `anima_lite`): it normalizes the country code and US state, and checks field shapes — it does not verify the address exists or is deliverable.
  - `valid` boolean, required: Whether the address passed structural (format-only) validation: ISO 3166-1 alpha-2 country, US state code + ZIP shape for US addresses, non-empty street/city. This is NOT a deliverability or postal-database check.
  - `standardized` object, required: Standardized version of the address
    - `type` 'BILLING' | 'SHIPPING' | 'MAILING' | 'REGISTERED', required: Address type
    - `label` string, nullable, required: User-defined label
    - `street1` string, required: Primary street address line
    - `street2` string, nullable, required: Secondary street address line
    - `city` string, required: City name
    - `state` string, required: State or province
    - `postalCode` string, required: Postal or ZIP code
    - `country` string, required: 2-character ISO country code
  - `confidence` number, required: Confidence score between 0 and 1
  - `suggestions` object[], required: Reserved: alternative address suggestions. Currently ALWAYS an empty array — the built-in validator is structural only (provider `anima_lite`) and does not generate alternatives. Populated only if/when a postal-data provider is integrated.
    - `street1` string, required: Suggested street address
    - `street2` string, nullable, required: Suggested secondary address
    - `city` string, required: Suggested city
    - `state` string, required: Suggested state
    - `postalCode` string, required: Suggested postal code
    - `country` string, required: Suggested country code

---

[API](https://skmtc.dev/useanima/apis/anima-api.md) · [All operations](https://skmtc.dev/useanima/apis/anima-api/llms.txt) · [OpenAPI document](https://skmtc.dev/useanima/apis/anima-api/revisions/aaa148188980?raw)