Postal Code Format Checker
location.validate_postal_code
Overview
You send a postal code and country, and we check the code against the published national format pattern. When the shape matches, we return a normalized form you can store. validationLevel is always FORMAT_ONLY — we never claim the code exists, is assigned, or belongs to a real address. Countries we don't cover or that have no postal system return valid=false with clear findings. Don't use this for delivery-point verification or address lookup.
A postcode that looks right is not a postcode that exists, and a checker that blurs the two sends parcels into the void. This one only ever claims the shape is right, says which rule it used, and hands you a canonical form to store.
Reliability
The rules come from a pinned table we version as dataProfile, reading postal-patterns-v1 today: 66 countries with a format rule plus 5 we record as issuing no postal codes at all (AE, BH, HK, MO, QA), 71 in total. Same code, same country and same table version, same verdict. Countries outside that table come back with valid false and a POSTAL_COUNTRY_UNSUPPORTED warning, which means unchecked rather than wrong — read findings before you reject a customer's address. A failed shape is likewise an ordinary success with valid false, so branch on valid rather than on your error path. COUNTRY_UNRESOLVABLE — trigger: a country designation we cannot map to any ISO country, in the single call or in any one row of a batch, which fails the whole call; retryable: no, the same designation always fails; next: send the alpha-2 code, or run location.normalize_country first to find out which designation is the problem. POSTAL_BATCH_LIMIT_EXCEEDED — trigger: your postalCodes array holds more than 100 entries; retryable: no; next: split the list into chunks of 100 or fewer and merge the results on your side.
Context footprint
Send one postal code or up to 100 pairs in a batch. Each code can be up to 32 characters. A successful call costs 1 execution credit.
When to use it
When a code arrives from a form or an import and you want to catch the structurally impossible ones and tidy the rest before you save them.
When you need to know the address exists, or to derive a city, region or coordinates from the code.
Scope
Non-goals
- No verification that a code exists or is assigned
- No address or city lookup from a postal code
- No geocoding
- No delivery-point or carrier validation
Properties
Capabilities
Cost & billing
Flat rate per invocation
File handling
How we handle your data
What this means
This skill may receive sensitive content, but it does not target sensitive data and returns only a structured non-sensitive result.
Squillify guarantees
- Runs inside Squillify
- This skill runs inside Squillify.
- Payloads are not sent to an external service by this skill.
- Squillify does not permanently store submitted payloads.
- Telemetry records metadata only, not submitted content.
- Submitted payloads are not used for training.
- Submitted payloads are not reviewed by humans.
- This skill does not target sensitive data.
- The response does not contain submitted content.
Your responsibility
Squillify does not determine whether submitted content is sensitive. Your application is responsible for deciding what data it is allowed to submit. Your application is responsible for securing the response.
Input schema
| Field | Type | Required | Description |
|---|---|---|---|
| postalCode | string | No | Postal code exactly as supplied; required unless postalCodes supplies a batch. |
| country | string | No | Country name or ISO designation; required unless postalCodes supplies a batch. |
| postalCodes | array | No | From 1 through 100 closed {postalCode, country} checks in input order; omit it for a single pair. |
| options | object | No | Closed normalizeCase and normalizeSeparators options; omit it to apply both documented defaults. |
Output schema
| Field | Type | Required | Description |
|---|---|---|---|
| valid | boolean | No | Whether the code matches the country's published shape. |
| postalCode | string | No | Canonical postal code; omitted when invalid. |
| inputPostalCode | string | No | Postal code exactly as supplied. |
| country | string | No | Resolved alpha-2 country code; omitted if unresolved. |
| pattern | string | No | Applied postal pattern identifier; omitted when none applied. |
| normalized | boolean | No | Whether normalization changed the supplied code. |
| validationLevel | string | Yes | Always FORMAT_ONLY; this never proves assignment or existence. |
| findings | array | No | From 0 through 1 closed finding objects; empty when valid and actionable otherwise. |
| results | array | No | From 1 through 100 closed postal result objects preserved in caller order. |
| _meta | object | Yes | Closed receipt object containing the pinned dataProfile and countriesSupported properties. |
API contract
POST /v1/executecurl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"location.validate_postal_code","input":{"postalCode":"sw1a 1aa","country":"GB"}}'import { Squillify } from "@squillify/sdk";
const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });
const { output } = await sq.execute("location.validate_postal_code", {"country":"GB","options":{"normalizeSeparators":true,"normalizeCase":true},"postalCode":"sw1a 1aa"});Errors
| Code | HTTP | Retryable | Description |
|---|---|---|---|
| VALIDATION_ERROR | 400 | No | The request payload failed schema validation. |
| UNAUTHORIZED | 401 | No | Missing or invalid API key. |
| SKILL_NOT_ACCESSIBLE | 403 | No | The API key is not granted access to this skill. |
| SKILL_NOT_AVAILABLE_FOR_PLAN | 403 | No | This skill is not included in your current plan. |
| PLAN_ELIGIBILITY_UNAVAILABLE | 503 | Yes | Plan eligibility could not be decided. Retry after backoff. |
| SKILL_NOT_FOUND | 404 | No | The requested skill or version does not exist. |
| TENANT_RATE_LIMITED | 429 | Yes | Request rate limit exceeded. Retry after backoff. |
| QUOTA_EXCEEDED | 429 | Yes | Plan quota exhausted. Retryable once the quota period resets. |
| EXECUTION_TIMEOUT | 504 | Yes | Execution exceeded the allowed time budget. |
| POSTAL_BATCH_LIMIT_EXCEEDED | 429 | No | A size, quota, rate, or time limit was exceeded. |
| COUNTRY_UNRESOLVABLE | 400 | No | The request payload failed this skill's input validation. |
Other limits
| Limit | Value |
|---|---|
| Recommended inline bytes | 32 KiB |
Limitations
- No verification that a code exists or is assigned
- No address or city lookup from a postal code
- No geocoding
- No delivery-point or carrier validation
- Confirming an address really exists at that postcode
- Carrier rate quotes or delivery-time estimates
- Inferring city or region from the code alone
How to call
POST /v1/execute (requires authentication)
{
"skillKey": "location.validate_postal_code",
"input": {
"country": "GB",
"options": {
"normalizeSeparators": true,
"normalizeCase": true
},
"postalCode": "sw1a 1aa"
}
}Examples
UK shipping form — lowercase postcode normalized to the official shape
{
"country": "GB",
"options": {
"normalizeSeparators": true,
"normalizeCase": true
},
"postalCode": "sw1a 1aa"
}{
"normalized": true,
"pattern": "GB-outward-inward",
"findings": [],
"inputPostalCode": "sw1a 1aa",
"country": "GB",
"valid": true,
"postalCode": "SW1A 1AA",
"_meta": {
"countriesSupported": 71,
"dataProfile": "postal-patterns-v1"
},
"validationLevel": "FORMAT_ONLY"
}Obvious typo — shape fails but we still answer in FORMAT_ONLY terms
{
"country": "GB",
"postalCode": "not-a-code"
}{
"findings": [
{
"details": {},
"path": "/postalCode",
"code": "POSTAL_FORMAT_MISMATCH",
"message": "Postal code does not match the published format pattern",
"severity": "error"
}
],
"validationLevel": "FORMAT_ONLY",
"valid": false,
"pattern": "GB-outward-inward",
"inputPostalCode": "not-a-code",
"_meta": {
"countriesSupported": 71,
"dataProfile": "postal-patterns-v1"
},
"country": "GB",
"normalized": true
}Country with no postal system — valid=false with an honest finding
{
"country": "AE",
"postalCode": "00000"
}{
"findings": [
{
"details": {},
"path": "/country",
"code": "POSTAL_COUNTRY_NO_SYSTEM",
"message": "Country has no postal-code system in the pinned table",
"severity": "info"
}
],
"_meta": {
"countriesSupported": 71,
"dataProfile": "postal-patterns-v1"
},
"valid": false,
"normalized": false,
"inputPostalCode": "00000",
"validationLevel": "FORMAT_ONLY",
"country": "AE"
}Two shipping addresses checked in one batch, country given by name
{
"postalCodes": [
{
"country": "Netherlands",
"postalCode": "1012 AB"
},
{
"country": "FR",
"postalCode": "75008"
}
]
}{
"validationLevel": "FORMAT_ONLY",
"results": [
{
"inputPostalCode": "1012 AB",
"validationLevel": "FORMAT_ONLY",
"country": "NL",
"valid": true,
"postalCode": "1012 AB",
"pattern": "NL-nnnn-aa",
"normalized": false,
"findings": [],
"_meta": {
"countriesSupported": 71,
"dataProfile": "postal-patterns-v1"
}
},
{
"inputPostalCode": "75008",
"validationLevel": "FORMAT_ONLY",
"country": "FR",
"valid": true,
"postalCode": "75008",
"pattern": "FR-nnnnn",
"normalized": false,
"findings": [],
"_meta": {
"countriesSupported": 71,
"dataProfile": "postal-patterns-v1"
}
}
],
"_meta": {
"countriesSupported": 71,
"dataProfile": "postal-patterns-v1"
}
}Recommended use cases
- Reject structurally impossible postal codes before you save a form
- Normalize messy user input like sw1a 1aa to the canonical GB form
- Gate imports when the postcode shape is wrong for the stated country
Avoid for
- Confirming an address really exists at that postcode
- Carrier rate quotes or delivery-time estimates
- Inferring city or region from the code alone
Related skills
Composable with
Safety & privacy
- Runs without calling any external service.
- Your payloads are never stored permanently.
- Telemetry captures metadata only — never your payload contents.
- We never train models on your payloads.
- No human reviews your payloads.