> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Validate an address

> Check that a U.S. postal address is deliverable before quoting mail to it

## Overview

Checks one U.S. address and returns whether it is deliverable, a deliverability code and the standardised address. Free. Changes nothing.

A preview validates both addresses itself and refuses an undeliverable one with `422 address_not_deliverable`. Call this first to catch a bad address before uploading artwork.

## Authentication

`X-Agent-ID` plus a signed `x-agent-proof` with `scope: "write"`, or an access token. See [proof authentication](https://docs.oneshotagent.com/sdk/overview.md#read-authentication). 60 requests a minute per agent.

## Request Body

**name** `string` *required*

Recipient name (1-100 characters)

**address\_line1** `string` *required*

Street address (1-200 characters)

**address\_line2** `string`

Apartment, suite or unit

**address\_city** `string` *required*

City

**address\_state** `string` *required*

Two-letter state code, e.g. `CA`

**address\_zip** `string` *required*

ZIP code, 5 digits or ZIP+4

**address\_country** `string`

Only `US`

## Response

**deliverable** `boolean`

`true` when mail can be delivered to the address

**deliverability** `string`

`deliverable` or `deliverable_unnecessary_unit` when deliverable; otherwise a code saying why not

**address** `object`

The standardised address, in the same shape as the request. The address as sent when it is undeliverable.

```bash cURL theme={null}
curl -X POST https://win.oneshotagent.com/v1/tools/physical-mail/validate-address \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: 0xYourWalletAddress" \
  -H "x-agent-proof: <base64 signed proof, scope=write>" \
  -d '{
    "name": "Jane Doe",
    "address_line1": "185 Berry St",
    "address_line2": "Suite 6100",
    "address_city": "San Francisco",
    "address_state": "CA",
    "address_zip": "94107"
  }'
```

```typescript SDK theme={null}
import { OneShot } from "@oneshot-agent/sdk";

const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });

const result = await agent.physicalMail.validateAddress({
  name: "Jane Doe",
  address_line1: "185 Berry St",
  address_line2: "Suite 6100",
  address_city: "San Francisco",
  address_state: "CA",
  address_zip: "94107",
});
console.log(result.deliverable);
```

```python Python theme={null}
result = client.physical_mail.validate_address({
    "name": "Jane Doe",
    "address_line1": "185 Berry St",
    "address_line2": "Suite 6100",
    "address_city": "San Francisco",
    "address_state": "CA",
    "address_zip": "94107",
})
print(result["deliverable"])
```

```json Response theme={null}
{
  "deliverable": true,
  "deliverability": "deliverable",
  "address": {
    "name": "Jane Doe",
    "address_line1": "185 BERRY ST",
    "address_line2": "STE 6100",
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107",
    "address_country": "US"
  }
}
```

```json Invalid Input (400) theme={null}
{
  "error": "invalid_input",
  "details": [
    { "path": "address_state", "message": "Invalid input" }
  ]
}
```


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