Large-recipient postcodes in forms

Some large companies and public authorities have a postcode of their own. Mail to them is sorted straight to the recipient instead of to a postal district. This is called a large-recipient postcode (stormodtagerpostnummer), e.g. 1092 København K for Danske Bank at Holmens Kanal 2. It appears on invoices and letters from such organisations, which is why it turns up in B2B forms, billing addresses and CRM data.

A large-recipient postcode points to an organisation's mail handling. The building still has its normal, geographic postcode: Holmens Kanal 2 is in 1060 København K.

What the API returns#

The API follows DAWA:

Check a postcode#

GET /postnumre/{nr} answers 200 for a known postcode and tells you whether it is a large-recipient postcode:

curl -s "https://api.danadresse.dk/postnumre/1092" \
  -H "X-Api-Key: $DANADRESSE_API_KEY"

{
  "href": "https://api.danadresse.dk/postnumre/1092",
  "nr": "1092",
  "navn": "København K",
  "stormodtageradresser": [
    {
      "href": "https://api.danadresse.dk/adgangsadresser/0a3f507a-8f2e-32b8-e044-0003ba298018",
      "id": "0a3f507a-8f2e-32b8-e044-0003ba298018"
    },
    {
      "href": "https://api.danadresse.dk/adgangsadresser/0a3f507a-8f34-32b8-e044-0003ba298018",
      "id": "0a3f507a-8f34-32b8-e044-0003ba298018"
    }
  ],
  "stormodtager": true,
  "kommuner": [
    {
      "href": "https://api.danadresse.dk/kommuner/0101",
      "kode": "0101",
      "navn": "København"
    }
  ]
}

A 404 means the number is not a postcode in the register. It is typically a typo or a retired number.

How to handle it in the form#

The purpose of the form decides what you do:

Here is a small check in Node that tells "geographic", "large recipient", "unknown" and "invalid format" apart:

async function tjekPostnr(nr) {
  if (!/^\d{4}$/.test(nr))
    return { status: "invalid", text: "The postcode must be four digits" };
  const res = await fetch(`https://api.danadresse.dk/postnumre/${nr}`, {
    headers: { "X-Api-Key": process.env.DANADRESSE_API_KEY },
    signal: AbortSignal.timeout(5000),
  });
  if (res.status === 404)
    return { status: "unknown", text: `${nr} is not a known postcode` };
  if (!res.ok)
    return {
      status: "could not check",
      text: "Could not check the postcode right now",
    };
  const p = await res.json();
  if (p.stormodtager) {
    return {
      status: "large recipient",
      text: `${p.nr} ${p.navn} is a company postcode. Use it for mail, not for delivery.`,
    };
  }
  return { status: "geographic", text: `${p.nr} ${p.navn}` };
}

for (const nr of ["2900", "1092", "9999", "29OO"]) {
  console.log(nr, JSON.stringify(await tjekPostnr(nr)));
}

You can also fetch the full list with GET /postnumre?stormodtagere=true once a day and check locally instead of calling the API on every keystroke. The stormodtager field tells you which numbers are for mail only. See Postcodes and municipalities for dropdowns.

Store the raw input#

When you accept a postcode the API does not know, store it exactly as the customer typed it and flag the row, e.g. with postnr_valideret = false. Then you can find the rows again if you want to check them later. Store a large-recipient postcode on a billing address as it is. Do not overwrite it with the geographic postcode from datavask.

Edge cases#

• Datavask uses the geographic postcode. "Holmens Kanal 2, 1092 København K" gives category C, because the postcode differs from the building's (forskelle.postnr). The candidate is the right building with 1060. The field anvendtstormodtagerpostnummer is null.
• Autocomplete finds the building. The suggestion shows the geographic postcode and carries the large-recipient postcode in data.stormodtagerpostnr. To offer both variants, add stormodtagerpostnumre=true.
• Postcodes with a leading zero. Every geographic postcode has four digits from 1000 upwards. Numbers below 1000, such as 0800 Høje Taastrup and 0999 København C, are large-recipient postcodes. The API always returns postcodes with four digits, so store them as text so the zero does not disappear.
• Municipality from postcode. kommuner on a large-recipient postcode lists the municipalities of its large-recipient addresses. To know the municipality of a specific customer, use the address.

Next steps#

• Postcodes and municipalities for dropdowns
• Validate the address at checkout with datavask