Postal Code

GET/v0/postal-code

Validates a postal code against country-specific format rules. Supports 60+ countries. When the optional country parameter is provided, validation is strict for that country. Without it, the code is matched against all known patterns and the list of matching countries is returned.

Try it

Query Parameters

Parameter	Type	Required	Description
value	string	Yes	The postal code to validate
countryCode	string	No	ISO 3166-1 alpha-2 country code (e.g. `PL`, `US`). When omitted all supported countries are tried.

Example Request — with country

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/postal-code?value=00-950&countryCode=PL"

Response Fields — with country

Field	Type	Description
valid	boolean	Whether the postal code matches the country format
country	string	ISO 3166-1 alpha-2 country code
countryName	string \| null	Full English name of the country
format	string	Human-readable format description (N = digit, A = letter)
location	object \| null	Geographic data from GeoNames, or `null` if not available. See The `location` object below.

The `location` object

Field	Type	Description
city	string	Place name associated with the postal code
region	string \| null	First-level administrative division (e.g. state, voivodeship, province)
subregion	string \| null	Second-level administrative division (e.g. county, district)
lat	number \| null	Latitude in decimal degrees
lon	number \| null	Longitude in decimal degrees

Example Response — valid (PL)

{
  "valid": true,
  "country": "PL",
  "countryName": "Poland",
  "format": "NN-NNN",
  "location": {
    "city": "Warszawa",
    "region": "Masovian Voivodeship",
    "subregion": "Warsaw",
    "lat": 52.23,
    "lon": 21.01
  }
}

Example Request — without country

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/postal-code?value=10115"

Response Fields — without country

Field	Type	Description
valid	boolean	Whether the value matches at least one known postal code format
matchingCountries	array	List of countries whose postal format the value satisfies. See The `matchingCountries` array below.

The `matchingCountries` array

Each element represents one country whose postal code format matches the input.

Field	Type	Description
country	string	ISO 3166-1 alpha-2 country code
countryName	string \| null	Full English name of the country
format	string	Human-readable format description (N = digit, A = letter)

Example Response — valid (no country, 5-digit code)

{
  "valid": true,
  "matchingCountries": [
    { "country": "DE", "countryName": "Germany", "format": "NNNNN" },
    { "country": "EE", "countryName": "Estonia", "format": "NNNNN" },
    { "country": "ES", "countryName": "Spain", "format": "NNNNN" },
    { "country": "FI", "countryName": "Finland", "format": "NNNNN" },
    { "country": "FR", "countryName": "France", "format": "NNNNN" }
  ]
}

Example Response — invalid

{
  "valid": false
}