# Address Validation

> Country-specific rules for the StreetAddress object used by customer prefill, customer records, and checkout billing addresses.

## Overview

Many Noah API endpoints accept a `StreetAddress` object — for example `PrimaryResidence` on customer prefill and create/update, `RegisteredAddress` on business customers, and billing addresses on checkout sessions.

The OpenAPI schema defines field lengths and which fields are required. Noah also applies additional validation at request time. This page documents those rules so you can validate addresses **before** calling the API.

## Field requirements

| Field      | Required | Length           | Notes                                           |
| ---------- | -------- | ---------------- | ----------------------------------------------- |
| `Street`   | Yes      | 2–200 characters | Primary street line                             |
| `Street2`  | No       | —                | Secondary line (apartment, suite, etc.)         |
| `City`     | Yes      | 1–100 characters | City or town                                    |
| `State`    | Yes      | 1–100 characters | See [State rules](#state-rules) below           |
| `PostCode` | Yes      | 1–20 characters  | See [Postcode rules](#postcode-rules) below     |
| `Country`  | Yes      | —                | ISO 3166-1 alpha-2 code (e.g. `US`, `GB`, `DE`) |

`State` and `PostCode` are **always required**, including for countries that do not use administrative subdivisions or postal codes in everyday addressing. Empty strings and placeholder values are rejected.

## Character set

All `StreetAddress` string fields must be **printable ASCII**. Noah normalises input by removing characters outside the printable ASCII range.

If sanitisation leaves a required field empty (for example, an address written entirely in a non-Latin script with no transliteration), the request fails schema validation. Provide Latin transliterations where your source data uses another script.

## State rules

### United States and Canada

For `Country` `US` or `CA`, `State` must be a valid **ISO 3166-2 subdivision code**:

- **Two uppercase letters** (e.g. `NY`, `TX`, `ON`, `QC`)
- Must match a real subdivision for that country
- Lowercase codes (e.g. `ca`) are rejected

### All other countries

`State` is **free text**. Use the local administrative division name — province, region, county, département, etc. Noah does not validate `State` against ISO 3166-2 outside the US and Canada.

### Countries without states or provinces

If your source data has no subdivision, use the best available real-world value — typically the **city or region name** in `State`. Do not send placeholders such as `NA`, `None`, or `-`.

## Postcode rules

`PostCode` is required for every country. At the `StreetAddress` schema level, Noah checks only that the value is **non-empty** and **at most 20 characters**. There is no per-country postcode format validation on customer or checkout address fields.

Use the postcode format that appears on the customer's official documents or your verified source data.

### Countries without postal codes

If your source system has no postal code for a country, you still must send a non-empty `PostCode`. Use the value your compliance source considers authoritative for that address (for example, a locality code used in that market). **Do not** send generic placeholders such as `00000`, `NA`, `None`, or `Empty`.

:::caution

Sandbox API responses for **bank** addresses (for example virtual account details) may show values such as `00000` in `PostCode`. Those are sandbox artefacts on **response** objects. They are not valid values to send in **request** payloads for customer addresses.

:::

## Payment form addresses

When creating or updating a fiat payment method (for example during a payout), the address fields required by a channel may differ from `StreetAddress`:

- Field names may differ (for example `AccountHolderAddress` with `Address` instead of `Street`)
- A channel's [`FormSchema`](./form-schemas.md) may require a different set of fields
- Additional format rules may apply on top of the base schema

Always retrieve the [`FormSchema`](./form-schemas.md) for the channel you select and validate your payload against that schema before submission.

## Common validation errors

| Symptom                                                                  | Likely cause                                                 |
| ------------------------------------------------------------------------ | ------------------------------------------------------------ |
| `invalid state` on `PrimaryResidence.State` or `RegisteredAddress.State` | Invalid or lowercase ISO 3166-2 code for US/CA               |
| Schema validation on `PostCode` or `State`                               | Empty string, or field became empty after ASCII sanitisation |
| `address could not be converted to ASCII`                                | Required field contained only non-ASCII characters           |

## Related pages

- [Form Schemas](./form-schemas.md) — per-channel payment data requirements
- [Individual Customer Prefill](../recipes/onboarding/individual-customer-prefill.md)
- [Business Customer Prefill](../recipes/onboarding/business-customer-prefill.md)
- [Prefill Customer Details](../../api-reference/prefill-customer-details) — API Reference
- [Create/Update Customer](../../api-reference/create-update-customer) — API Reference