Postal codes

The postal_code of a contact is validated against the country's published postal format and stored in that country's canonical notation. Validation runs when the contact is written — with POST /v1/contacts, or with the contact_create and contact_create_bulk job commands — so a postal code a registry would refuse fails immediately, with the field named, instead of failing at the registry after the contact has been stored.

Validated countries

An invalid postal code is refused for these countries:

Contacts in any other country accept whatever you submit. One rule applies everywhere: a postal code containing non-ASCII characters is rejected for every country, because it cannot be transmitted to a registry.

Rejected postal codes

An invalid postal code returns 422 with a request-validation-failed problem that names the field, so it can be mapped back to a form field:

{
  "type": "request-validation-failed",
  "title": "Request validation error.",
  "status": 422,
  "errors": [
    {
      "type": "invalid_postal_code",
      "loc": ["body", "postal_code"],
      "msg": "'93053' is not a valid postal code for country 'NL', expected a format like '1234 AB'",
      "input": "93053",
      "ctx": {
        "message": "'93053' is not a valid postal code for country 'NL', expected a format like '1234 AB'"
      }
    }
  ]
}

type is invalid_postal_code — a stable key for this rejection — and msg quotes the value you submitted together with an example of the expected format.

What gets stored

Postal codes are canonicalized on write, so the stored value can differ from what you submitted:

• Dutch postal codes are stored in the official national notation — four digits, a space, two upper-case letters. Both 1234AB and 1234 ab are accepted.
• The cross-border country prefix (D-, NL-, F-, …) is not part of a postal code and is stripped. It is only stripped when it matches the contact's own country: F-26133 on a DE contact keeps the F- and is rejected as an invalid German postal code.
• US ZIP+4 is stored in the hyphenated form.
• Where a space is part of the national format, as in CZ and GB, it is kept.

Registry-specific formats

Some registries require a different form than the national notation — SIDN, for example, requires a .nl postal code without the space. OpusDNS applies those rules when it builds the registry request. Store and submit the national format and never pre-format a postal code for a registry; the value you read back from the API is always the canonical national form.

Imported contacts

Contacts mirrored from another registrar or registry — domain import, transfer-in, and registrar sync — are canonicalized where possible but are never rejected for their postal code format, so an off-format value held at the losing registrar cannot fail an import.

Registry rejections

A registry can still refuse an address for its own reasons. Where the registry reports which field was at fault, that text is included in the detail of the resulting problem, after the generic result code:

2308: Validation of the transaction failed. Contact address group: A postcode has to be four numbers and two letters.

Errors

Related API Reference

• POST /v1/contacts
• GET /v1/contacts
• GET /v1/contacts/{contact_id}