Address Validation

Validate customer addresses and normalize postal codes for accurate tax jurisdiction resolution.

Validate Address

POST /v1/addresses/validate

curl -X POST https://api.shipvat.com/v1/addresses/validate \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "country": "US",
    "region": "CA",
    "postal_code": "90210",
    "city": "Beverly Hills",
    "line1": "123 Main Street"
  }'

Response (Valid)

{
  "valid": true,
  "normalized": {
    "country": "US",
    "country_name": "United States",
    "region": "CA",
    "region_name": "California",
    "postal_code": "90210",
    "city": "Beverly Hills",
    "line1": "123 Main Street",
    "line2": null
  },
  "jurisdiction_id": "US-CA",
  "issues": [],
  "suggestions": []
}

Response (With Issues)

{
  "valid": false,
  "normalized": {
    "country": "US",
    "country_name": "United States",
    "region": "XX",
    "region_name": null,
    "postal_code": "9021",
    "city": "Beverly Hills",
    "line1": "123 Main Street",
    "line2": null
  },
  "jurisdiction_id": "US",
  "issues": [
    {
      "field": "region",
      "code": "INVALID_REGION",
      "message": "State code \"XX\" is not a valid US state"
    },
    {
      "field": "postal_code",
      "code": "INVALID_POSTAL_CODE",
      "message": "Postal code \"9021\" does not match expected format for US"
    }
  ],
  "suggestions": [
    "US states should be 2-letter codes like CA, NY, TX",
    "Expected format: #####(-####) (e.g., 90210 or 90210-1234)"
  ]
}

List Supported Countries

GET /v1/addresses/countries

curl https://api.shipvat.com/v1/addresses/countries \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "countries": [
    {
      "code": "US",
      "name": "United States",
      "requires_region": true
    },
    {
      "code": "CA",
      "name": "Canada",
      "requires_region": true
    },
    {
      "code": "DE",
      "name": "Germany",
      "requires_region": false
    },
    {
      "code": "GB",
      "name": "United Kingdom",
      "requires_region": false
    }
  ],
  "total": 50
}

Get Regions

Get states/provinces for countries that require a region.

GET /v1/addresses/regions/:country

curl https://api.shipvat.com/v1/addresses/regions/US \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "country": "US",
  "regions": [
    { "code": "AL", "name": "Alabama" },
    { "code": "AK", "name": "Alaska" },
    { "code": "AZ", "name": "Arizona" },
    { "code": "CA", "name": "California" },
    { "code": "NY", "name": "New York" },
    { "code": "TX", "name": "Texas" }
  ],
  "total": 54
}

Postal Code Formats

Country	Format	Example
US	##### or #####-####	90210, 90210-1234
CA	A#A #A#	K1A 0B1
GB	XX# #XX	SW1A 1AA
DE	#####	10115
FR	#####	75001
NL	#### XX	1012 AB
BE	####	1000
AT	####	1010
CH	####	8001
AU	####	2000
JP	###-####	100-0001
BR	#####-###	01310-100

Postal Code Normalization

The API normalizes postal codes to their standard format:

Input	Country	Output
`K1A0B1`	CA	`K1A 0B1`
`SW1A1AA`	GB	`SW1A 1AA`
`1012AB`	NL	`1012 AB`
`1000001`	JP	`100-0001`

Issue Codes

Code	Description
`INVALID_COUNTRY`	Country code not recognized
`INVALID_REGION`	Region/state code not valid for country
`REGION_REQUIRED`	Region is required for this country
`INVALID_POSTAL_CODE`	Postal code format invalid

Integration Example

Use address validation before calculating tax:

import { ShipVAT } from '@shipvat/sdk';

const client = new ShipVAT({ apiKey: 'sk_live_...' });

// 1. Validate the address
const validation = await client.validateAddress({
  country: 'US',
  region: 'CA',
  postal_code: '90210'
});

if (!validation.valid) {
  console.log('Address issues:', validation.issues);
  console.log('Suggestions:', validation.suggestions);
  return;
}

// 2. Use normalized address for tax calculation
const tax = await client.calculate({
  line_items: [{ amount: 9999, product_type: 'saas', quantity: 1 }],
  customer: {
    address: {
      country: validation.normalized.country,
      region: validation.normalized.region,
      postal_code: validation.normalized.postal_code
    }
  },
  seller: { registered_in: ['US-CA'] },
  currency: 'USD'
});

console.log(`Tax jurisdiction: ${validation.jurisdiction_id}`);
console.log(`Tax amount: $${(tax.tax_amount / 100).toFixed(2)}`);