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

# Address requirements

> Look up which address fields are required, optional, or ignored for each country.

## Overview

Different countries have different address formats and requirements. The address requirements endpoint lets you look up the minimum address fields needed for a given country before submitting addresses for tax calculations or transactions.

Use this endpoint to:

* **Validate addresses client-side** before calling `/calculate` or `/transactions`, reducing failed requests.
* **Build dynamic address forms** that adapt to each country's requirements.
* **Check postal code formats** using the provided regex pattern.
* **Restrict state/province inputs** to valid codes for the country.

## Field requirement levels

Each address field returns one of three requirement levels:

| Level      | Meaning                                                                   |
| ---------- | ------------------------------------------------------------------------- |
| `REQUIRED` | The field must be provided. Omitting it may cause tax calculation errors. |
| `OPTIONAL` | The field is accepted but not mandatory. Providing it improves accuracy.  |
| `IGNORED`  | The field is not used for this country and can be omitted.                |

## How address requirements are used

The `/calculate` and `/transactions` endpoints only require `country` at the schema level for all addresses. All other field requirements — including `postal_code` and `state` — are determined per-country using the rules returned by this endpoint. If a field marked as `REQUIRED` for a country is missing or incorrectly formatted, the API returns a `400` error with details about the validation failure. Querying address requirements ahead of time lets you catch these issues before submitting a request.

## Regional differences

Address requirements vary by country and region. Here are some key differences to be aware of:

* **United States (US):** `address_line_1`, `city`, `state`, and `postal_code` are all `REQUIRED`. State codes must be valid 2-letter US state abbreviations (e.g., `CA`, `NY`).
* **EU countries (e.g., DE, FR):** `address_line_1`, `city`, and `postal_code` are `REQUIRED`, while `state` is `OPTIONAL`. Postal codes are validated against the country's regex pattern.
* **United Kingdom (GB):** `address_line_1`, `city`, and `postal_code` are `REQUIRED`, while `state` is `OPTIONAL`. Postal codes must match the UK format (e.g., `SW1A 1AA`).
* **Canada (CA):** `address_line_1` and `city` are `REQUIRED`. `state` and `postal_code` requirements follow Canadian postal standards. When provided, state codes must be valid 2-letter province/territory abbreviations (e.g., `ON`, `BC`).

<Note>
  Even when a field is `OPTIONAL`, providing it improves tax calculation accuracy. For example, including a state code for EU or GB addresses helps resolve the correct tax jurisdiction.
</Note>

## Postal code validation

When `postal_code_regex` is present in the response, you can use it to validate postal codes before submission. For example, the US pattern `^\d{5}(-\d{4})?$` accepts both 5-digit and 9-digit ZIP codes.

<Note>
  The `postal_code` field is **required** for the US, EU countries (such as DE and FR), and GB. For CA, `postal_code` is optional. When a postal code is provided, it is validated against the country's regex pattern.
</Note>

## Valid state codes

For countries with defined state or province subdivisions (e.g., US, CA), the `valid_state_codes` array lists all accepted codes. Use this to populate dropdowns or validate state input in your address forms.