Validate order address

curl --request POST \
  --url https://api.snappy.com/public-api/v2/orders/addresses/validate \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "country": "US",
  "address": {
    "addressLine1": "123 Main St",
    "zipcode": "12345",
    "city": "New York",
    "state": "NY"
  }
}
'

{
  "message": "The address is correct",
  "result": "verified"
}

Orders

Validate order address

Use this endpoint to validate a shipping address before placing an order. Use this when end users are entering shipping addresses in your platform UI - validating up front catches errors early and reduces fulfillment failures.

Required fields

country - country code, 2-3 uppercase letters (ISO 3166-1 alpha-2 or alpha-3)
address - the address object to validate. Contains:
- addressLine1 - street address (validated as required)
- addressLine2 - apartment, suite, floor (optional)
- city - city name (validated as required)
- state - state or province code (2-3 uppercase letters)
- zipcode - postal/ZIP code (alphanumeric, 3-10 characters)

Optional parameters

companyId query parameter - Company identifier, when not inferable from the API key context
Request-Source header - source of the request (api_native, api_zapier, api_salesforce, api_ftp, api_make)

Please note

Successful validation returns one of two result values:
- verified - the address is correct and deliverable
- ambiguous - the address was found but with ambiguity (e.g. multiple matches). Consider surfacing the response message to the end user to confirm before proceeding.
Returns 400 (400_PBLC_003) with a per-field errors array when address validation fails. Each entry includes the offending path, a human-readable message, and the errorCode.
Returns 422 (422_PBLC_001) when the address is well-formed but cannot be found by the validation service.
This endpoint does not place an order - it’s a pre-flight check. Always follow up with the order placement flow once validation succeeds.

Permissions

Requires: orders:read:masked or orders:read:unmasked

POST

orders

addresses

validate

Validate order address

curl --request POST \
  --url https://api.snappy.com/public-api/v2/orders/addresses/validate \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "country": "US",
  "address": {
    "addressLine1": "123 Main St",
    "zipcode": "12345",
    "city": "New York",
    "state": "NY"
  }
}
'

{
  "message": "The address is correct",
  "result": "verified"
}

Authorizations

X-Api-Key

string

header

required

Company Level Authentication

Company level authentication provides access to all resources under your company, including accounts, campaigns, gifts, and recipients.

Getting Your API Key

Create an API Key: Use the POST /v2/authentication/apiKeys endpoint to generate a new API key
Set Expiration: Choose from 30, 60, 90, or 180 days (default: 90 days)
Optional mTLS: Enable mutual TLS for enhanced security
Name Your Key: Provide a descriptive name for easy identification

Using Your API Key

Include your API key in the X-Api-Key header for every request:

X-Api-Key: YOUR_24_CHARACTER_API_KEY

API Key Management

Maximum Keys: Up to 3 active API keys per company
Rotation: Delete old keys before creating new ones when at the limit
Security: Keys are hashed and cannot be retrieved after creation

Enhanced Security (mTLS)

For production environments, enable mutual TLS authentication:

Set enforceMtls: true when creating the API key
Contact support to obtain your client certificates
Use the mTLS endpoint: https://mtls-api.snappy.com/public-api

Headers

Request-Source

enum<string>

Source of the request

Available options:

api_native,

api_zapier,

api_salesforce,

api_ftp,

api_make

Example:

"api_native"

Query Parameters

companyId

string

Company ID

Pattern: ^[A-Za-z0-9]{8,}$

Example:

"12345678"

Body

application/json

Validate order address request body.

country

string

required

Delivery address country a 2-3 letter uppercase country code

Pattern: ^[A-Z]{2,3}$

Example:

"US"

address

object

required

Delivery address details.

Show child attributes

Response

Address validation response.

message

string

required

Validation result message

Example:

"The address is correct"

result

enum<string>

required

The validation result status

Available options:

verified,

ambiguous

Example:

"verified"

Last modified on June 17, 2026

Cancel an order

Autocomplete order address