## List the postal addresses of an address (tenant:masterdata:read)

`GET /api/masterdata/addresses/{id}/postal-addresses`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** Postal addresses (`application/json`)
- **401** Missing, invalid or expired token (empty body)
- **403** The token lacks the permission or carries no tenant (`application/json`)
- **404** Not found in the caller's tenant (or merged, see `code`) (`application/json`)

Fields of the 200 answer:

- `items` (array of PostalAddress, required)
  - `addressLine2` (string): Additional address line (max length 255)
  - `ansNr` (integer): Number within the address; assigned when 0 or omitted
  - `city` (string): City (max length 128)
  - `countryCode` (string): ISO 3166-1 alpha-2 (default `"DE"`)
  - `county` (string): Kreis (Landkreis or kreisfreie Stadt) (max length 128)
  - `customFields` (CustomFields): Values of tenant-defined fields (`/api/masterdata/field-defs`) by key. On write the map is merged into the stored values; `null` removes a key, an omitted map keeps all values. Unknown or archived keys and missing required fields answer `400`.
  - `deliveryNote` (string): Note for deliveries
  - `distanceKm` (number, nullable, read-only): Driving distance in km (0.1 km) from the tenant profile (`TenantProfile`) to this postal address by car, computed asynchronously after geocoding. While `routeStatus` is `PENDING` it is the value from before the last change (being recalculated); absent unless `DONE` or `PENDING`.
  - `district` (string): District (max length 128)
  - `driveMinutes` (integer, nullable, read-only): Driving time in minutes (rounded up), see `distanceKm`
  - `email1` (string (email)): First e-mail address
  - `email2` (string (email)): Second e-mail address
  - `fax` (string): E.164
  - `geocodePrecision` (string, read-only): How exact the coordinates are (house number, street, city or locality, postal code area); set with `DONE`. (one of `HOUSE`, `STREET`, `LOCALITY`, `POSTCODE`)
  - `geocodeStatus` (string, read-only): Geocoding of the postal address, asynchronous after the save (never during a request). `PENDING`: new, or street, postal code, city or country changed; `DONE`: `latitude`/`longitude` set; `FAILED`: no such place, or the geocoder stayed unreachable for five attempts; `SKIPPED`: no postal code, or geocoding is switched off. (one of `PENDING`, `DONE`, `FAILED`, `SKIPPED`)
  - `geocodedAt` (string (date-time), read-only): Time of the last geocoding attempt
  - `gln` (string): Global Location Number with check digit
  - `id` (string (uuid)): Keep the id when replacing the address aggregate
  - `info` (string): Info text
  - `isBlocked` (boolean): Blocked postal address (never a billing or shipping default)
  - `isDefaultBilling` (boolean): Default billing address (at most one)
  - `isDefaultDunning` (boolean): Default dunning address (at most one)
  - `isDefaultInfo` (boolean): Default address for information (at most one)
  - `isDefaultService` (boolean): Default service address (at most one)
  - `isDefaultShipping` (boolean): Default shipping address (at most one)
  - `latitude` (number, nullable, read-only): WGS 84, set by the geocoding of masterdata (self-hosted Photon) after the save; ignored on writes. A change of street, postal code, city or country removes it until the postal address is geocoded again. (max 90)
  - `longitude` (number, nullable, read-only): WGS 84 (max 180)
  - `municipality` (string): Gemeinde (max length 128)
  - `name1` (string): First name line
  - `name2` (string): Second name line
  - `name3` (string): Third name line
  - `phone` (string): E.164
  - `poBox` (string): PO box
  - `poBoxCity` (string): City of the PO box
  - `poBoxPostalCode` (string): Postal code of the PO box
  - `postalCode` (string): Postal code (max length 32)
  - `region` (string): Bundesland: ISO 3166-2 code matching the country
  - `routeApproximate` (boolean, read-only): True when the tenant profile or this postal address is geocoded only to the locality or postal code area
  - `routeStatus` (string, read-only): Routing from the tenant profile, asynchronous (never during a request). `PENDING`: waiting for geocoding or the router (also after a move of this postal address or of the tenant profile); `DONE`: `distanceKm` and `driveMinutes` set; `FAILED`: the router stayed unreachable for five attempts; `SKIPPED`: no coordinates, outside the routable area, or routing is switched off; `NO_ORIGIN`: the tenant profile has no coordinates; `NO_ROUTE`: no road connection. (one of `PENDING`, `DONE`, `FAILED`, `SKIPPED`, `NO_ORIGIN`, `NO_ROUTE`)
  - `routedAt` (string (date-time), read-only): Time of the last routing attempt
  - `street` (string): Street with house number (max length 255)
  - `validationStatus` (string, read-only): OpenPLZ check of postal code, city and street (DE, AT, CH, LI), run on writes that add a postal address or change its postal code, city, street or country; unchanged rows keep their status. An unknown postal code (or one without the format of its country: DE five digits, AT, CH, LI four) answers `400` (`postalCode`: „Unbekannte Postleitzahl.“), a city that does not belong to it `400` (`city`: „Ort passt nicht zur Postleitzahl.“). `VERIFIED`: the street line starts with a street of the postal code (case-insensitive, `ß` = `ss`, `str.` = `straße`; the line keeps the house number). `STREET_UNKNOWN`: postal code and city are known, the street is not (saved). In both cases `municipality`, `county` and `region` are taken from OpenPLZ and are read-only. `NOT_CHECKED`: OpenPLZ unreachable or switched off, or stored before the check, or the checks of the save took longer than 8 s. `NOT_SUPPORTED`: another country. (one of `VERIFIED`, `STREET_UNKNOWN`, `NOT_CHECKED`, `NOT_SUPPORTED`)
  - `vatId` (string): VAT ID of this postal address
  - `version` (integer): Version of this postal address (child updates)
  - `website` (string (uri)): Website

Example 200 answer:

```json
{
  "items": [
    {
      "ansNr": 1,
      "city": "Schönau am Königssee",
      "countryCode": "DE",
      "county": "Berchtesgadener Land",
      "customFields": {},
      "distanceKm": 142.7,
      "driveMinutes": 109,
      "email1": "rezeption@alpenhotel-seeblick.example",
      "geocodePrecision": "HOUSE",
      "geocodeStatus": "DONE",
      "geocodedAt": "2026-03-14T10:02:31Z",
      "id": "2c4e6a8c-0d2f-4b4c-9e6a-8c0e2a4c6e8a",
      "isBlocked": false,
      "isDefaultBilling": true,
      "isDefaultDunning": true,
      "isDefaultInfo": true,
      "isDefaultService": false,
      "isDefaultShipping": true,
      "latitude": 47.5986,
      "longitude": 12.9894,
      "municipality": "Schönau a.Königssee",
      "name1": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "phone": "+49865298760",
      "postalCode": "83471",
      "region": "DE-BY",
      "routeApproximate": false,
      "routeStatus": "DONE",
      "routedAt": "2026-03-14T10:03:05Z",
      "street": "Seestraße 4",
      "validationStatus": "VERIFIED",
      "version": 2
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4/postal-addresses' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
