Skip to main content

Address Validation

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.

tip

Field names and types are defined on the StreetAddress schema in the API Reference. This page explains how those fields are validated in practice.

Field requirements​

FieldRequiredLengthNotes
StreetYes2–200 charactersPrimary street line
Street2No—Secondary line (apartment, suite, etc.)
CityYes1–100 charactersCity or town
StateYes1–100 charactersSee State rules below
PostCodeYes1–20 charactersSee Postcode rules below
CountryYes—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, CA, 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 may require a different set of fields
  • Additional format rules may apply on top of the base schema

Always retrieve the FormSchema for the channel you select and validate your payload against that schema before submission.

Common validation errors​

SymptomLikely cause
invalid state on PrimaryResidence.State or RegisteredAddress.StateInvalid or lowercase ISO 3166-2 code for US/CA
Schema validation on PostCode or StateEmpty string, or field became empty after ASCII sanitisation
address could not be converted to ASCIIRequired field contained only non-ASCII characters