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.1
Host: api.sznd.app
x-api-key: <your-api-key>
x-timestamp: 2025-01-15T10:30:00Z
x-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
• 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) to validate E.164-style numbers (exact length after country code).

Request:

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

Response:

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

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.