## Look up the places of a postal code (tenant:masterdata:read)

`GET /api/masterdata/postal-lookup/localities`

Module: Master data · operationId: `listPostalLocalities` · Tag: Postal addresses · Auth: access token (`Authorization: Bearer <accessToken>`)

Places of a postal code from OpenPLZ (Germany, Austria, Switzerland, Liechtenstein; cached for 24 hours)
with municipality (Gemeinde), county (Kreis/Bezirk) and federal state (Bundesland/Kanton, `region` as
ISO 3166-2). An unknown postal code answers an empty list, one without the format of its country (DE five
digits, AT, CH, LI four) `400`. Other countries answer `400` (`country_not_supported`); when the lookup is switched off or OpenPLZ is unreachable `503`
(`unavailable`) – enter the place by hand then.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `country` | query | string |  | ISO 3166-1 alpha-2: DE, AT, CH or LI (default `"DE"`) |
| `postalCode` | query | string | yes | (max length 32) |

### Responses

- **200** Places of the postal code (`application/json`)
- **400** Malformed body or query parameter (`application/json`)
- **401** Missing, invalid or expired token (empty body)
- **403** The token lacks the permission or carries no tenant (`application/json`)
- **503** The postal code lookup is switched off or OpenPLZ is unreachable; enter the place by hand (`application/json`)

Fields of the 200 answer:

- `items` (array of PostalLocality, required)
  - `county` (string, required): Kreis (DE) or Bezirk (AT, CH); empty for LI
  - `federalState` (string, required): Bundesland or Kanton; empty for LI
  - `municipality` (string, required): Gemeinde
  - `name` (string, required): Place (Ort)
  - `postalCode` (string, required): Postal code
  - `region` (string, required): ISO 3166-2 code of the federal state, as stored in PostalAddress.region; empty for LI

Example 200 answer:

```json
{
  "items": [
    {
      "county": "Berchtesgadener Land",
      "federalState": "Bayern",
      "municipality": "Schönau a.Königssee",
      "name": "Schönau a.Königssee",
      "postalCode": "83471",
      "region": "DE-BY"
    },
    {
      "county": "Berchtesgadener Land",
      "federalState": "Bayern",
      "municipality": "Berchtesgaden",
      "name": "Berchtesgaden",
      "postalCode": "83471",
      "region": "DE-BY"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/masterdata/postal-lookup/localities?postalCode=80331' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
