Regions & Validation API

The Regions API exposes country-level metadata used for validating addresses and phone numbers.
It powers strict checks in onboarding and beneficiary creation flows.

Use these endpoints to validate address and phone data before calling onboarding or beneficiary creation, so only region-valid data is sent to the API.

Authentication

This endpoint requires HMAC authentication (Business API Key). Include your API key and signature in the request headers:

x-api-key: <your-api-key>x-timestamp: <RFC3339-timestamp>x-signature: <HMAC-signature>

Note: For HMAC authentication details, see the Authentication guide.

Endpoints

Get subdivisions for a country

GET /api/v1/client/regions/{country_code}/subdivisions

Returns:

• country_code, country_name
• subdivisions (list of {code, name})

Example:

GET /api/v1/client/regions/US/subdivisions HTTP/1.1Host: api.sznd.appx-api-key: <your-api-key>x-timestamp: 2025-01-15T10:30:00Zx-signature: <hmac-hex>

Get subdivisions with code formats

GET /api/v1/client/regions/{country_code}/subdivisions-with-code-formats

Returns:

• country_code, country_name
• phone_code, phone_format, phone_length_after_code
• phone_length_after_code_min, phone_length_after_code_max (range after the country calling code; both equal phone_length_after_code for fixed-length countries)
• postal_code_format
• subdivisions (list of {code, name})

Get postal code format

GET /api/v1/client/regions/{country_code}/postal-code-format

Returns:

{  "country_code": "US",  "postal_code_format": "^([0-9]{5})(?:[ \\-]([0-9]{4}))?$"}

Validation helpers

Validate address and phone data before calling onboarding or beneficiary APIs.

Validate postal code

POST /api/v1/client/regions/validate/postal-code

Request:

{  "country_code": "US",  "postal_code": "10001"}

Response:

{  "country_code": "US",  "postal_code": "10001",  "valid": true}

Validate region/state code or name

POST /api/v1/client/regions/validate/region

Accepts subdivision code (e.g. CA, NY) or name (e.g. California, New York). Matching is case-insensitive.

• Onboarding (register, full customer registration): code or name is accepted; code is advised.
• Beneficiary creation: only subdivision code is accepted by the API—names are rejected. Use this endpoint with the code (e.g. LA) when building beneficiary address payloads.

Request:

{  "country_code": "US",  "region_code": "CA"}

Or with subdivision name: "region_code": "New York".

Response:

{  "country_code": "US",  "region_code": "CA",  "valid": true}

Validate phone number

POST /api/v1/client/regions/validate/phone

Uses the country’s phone metadata (phone_code, phone_length_after_code_min, phone_length_after_code_max) to validate E.164-style numbers. Length after the country code must fall in that range (exact when min equals max).

Request:

{  "country_code": "US",  "phone_number": "+14165550123"}

Response:

{  "country_code": "US",  "phone_number": "+14165550123",  "valid": true,  "error": null}

Supported subdivisions: United Kingdom (GB)

The UK's state/region field accepts either the subdivision code or name (case-insensitive) for onboarding, and code only for beneficiary creation — same rules as any other country (see Validate region/state code or name above).

This list includes standard unitary authorities, London boroughs, and Scottish/Welsh/Northern Irish council areas, as well as the six historic metropolitan counties (West Midlands, Greater Manchester, Merseyside, South Yorkshire, Tyne and Wear, West Yorkshire) that are still commonly used in real-world UK addresses even though each is also broken down into individual boroughs (e.g. "West Midlands" and "Birmingham" are both valid, independent values — pick whichever matches your customer's address).

This table is generated from the live GET /api/v1/client/regions/GB/subdivisions-with-code-formats data (see Get subdivisions with code formats above). If you're building an integration, prefer calling that endpoint directly rather than hardcoding this list, so you always get the current supported set.

Usage in client flows

• Customer full registration:
  Validate address and phone before calling
  POST /api/v1/client/customers/full
  so address (street_1, city, state, postal_code, country_code) and phone_number match region rules.

• Beneficiary creation:
  Validate address (and optionally phone) before
  POST /api/v1/client/beneficiaries
  when address is required or provided. State must be a subdivision code only (e.g. NY, LA), not the full name.

This keeps client-side errors tight and ensures only region-valid data reaches onboarding and payout rails.