## Replace a postal address (tenant:masterdata:write)

`PUT /api/masterdata/addresses/{id}/postal-addresses/{pid}`

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

The body carries the `version` of the postal address; `ansNr` is kept. The default billing and
shipping address cannot be switched off here (`409`): another postal address takes it over by
setting the flag. Bumps the address version and emits `masterdata.address.updated`.

### Parameters

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

### Request body

`application/json` (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:

```json
{
  "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
}
```

### Responses

- **200** Saved (`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`)
- **404** Not found in the caller's tenant (or merged, see `code`) (`application/json`)
- **409** Stale version or conflict with existing data (`application/json`)

Fields of the 200 answer:

- `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
- `addressVersion` (integer, required): New version of the address

Example 200 answer:

```json
{
  "addressVersion": 8,
  "ansNr": 1,
  "city": "Schönau am Königssee",
  "countryCode": "DE",
  "geocodeStatus": "PENDING",
  "id": "2c4e6a8c-0d2f-4b4c-9e6a-8c0e2a4c6e8a",
  "isDefaultBilling": true,
  "name1": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "postalCode": "83471",
  "routeStatus": "PENDING",
  "street": "Seestraße 4",
  "validationStatus": "VERIFIED",
  "version": 3
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4/postal-addresses/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"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}'
```
