# ConnectCloud Master data API (v1.0.0)

Addresses (customers, suppliers) with contacts and postal addresses, articles, product groups, lookup tables, number ranges and the tenant profile.

Base URLs:

- Production: `https://api.mbcom.cloud`
- Staging: `https://api.mbcom.cloud`
- Sandbox: `https://developers.mbcom.cloud/sandbox/masterdata`

Masterdata holds the business partners and articles of a tenant: the **addresses**
(customers, suppliers, prospects, partners, with their postal addresses, contact persons,
bank accounts and SEPA mandates), the **articles** with their sales price and suppliers,
the **product groups**, the tenant's parameter tables ("lookups"), number ranges and the
tenant's own company profile. CRM, trade (invoice matching, ITSP) and desk (requester matching)
read these records; masterdata is their source of truth.

The paths of this document are absolute: the tenant API lives under `/api/masterdata`
(no version segment) and the service-to-service API under `/internal`.

## Model
- **Addresses** (`/api/masterdata/addresses`) follow the structure of the microtech ERP
  address (`tblAddresses`): a party (`partyType` `COMPANY` needs `companyName`, `PERSON` needs
  `lastName`) with a tenant-unique address number `adrNr` (assigned from the `ADDRESS` number
  range when empty), CRM fields (roles, hierarchy via `parentAddressId`, tags, external ids),
  tax and e-invoicing data (VAT ID, Leitweg-ID, Peppol ID, GLN), payment, pricing, delivery and
  GDPR fields, tenant-defined `customFields`, and the child collections `postalAddresses`
  (Anschriften, `ansNr`), `contactPersons` (Ansprechpartner, `aspNr`), `bankAccounts` and
  `sepaMandates`. A `PUT` replaces the whole aggregate; the child endpoints edit one contact
  person or postal address without sending the rest.
- **Duplicates and merging:** `POST /api/masterdata/addresses:duplicates` scores an address
  (nothing is stored) against the existing ones (VAT ID, IBAN, email and its domain, phone,
  name similarity with postal code); `POST /api/masterdata/addresses/{id}/merge` merges another
  address into the given one. A merged address answers `404` with `code: merged` and
  `details.mergedInto`.
- **VAT ID checks** query the official German BZSt eVatR service (simple or qualified with name
  and main postal address) and keep every result as a protocol entry (§18e UStG evidence).
- **Distributor IDs** map the supplier IDs of IT distributors (`source` such as `egis` or
  `ingram`) to the supplier address they stand for; one distributor ID maps to exactly one
  address.
- **Articles** (`/api/masterdata/products`) follow the microtech article (`tblProducts`):
  article number `articleNumber` (assigned from the `PRODUCT` number range when empty), type
  (`GOODS`, `SERVICE`, `SUBSCRIPTION`, `TEXT`, `FEE`), one net sales price (`salesPrice`, with
  minimum and special price), suppliers with one purchase price each (the default supplier gives
  `purchasePrice`), logistics and subscription fields. Articles belong to an optional
  **product group** (Warengruppe, hierarchical).
- **Lookups** are tenant parameter tables (`address-statuses`, `salutations`, `payment-terms`,
  `payment-methods`, `shipping-types`, `units`, `tax-keys`, `currencies`,
  `industries`). Every tenant is seeded with German defaults on its first request. Address
  and article fields such as `statusCode`, `paymentTermCode` or `unitCode` refer to their codes.
- **Field definitions** describe tenant-defined fields of addresses (`ADDRESS`), contact persons
  (`CONTACT`) and postal addresses (`POSTAL`); their values live in `customFields`.
- **AI drafts** (`:draft`) turn pasted text, an image (business card, letterhead) or a website
  into a pre-filled address, contact person or postal address. Nothing is stored; save the
  checked draft with the normal create endpoint.
- `syncStatus` is reserved for an ERP synchronisation and read-only; records created through
  this API are `STANDALONE`.

## Authentication
Send an access token as `Authorization: Bearer <accessToken>`. Get it by exchanging an API key at
`POST https://api.mbcom.cloud/api/hr/v1/auth/token`; it lives 15 minutes and carries the key's permissions.
The tenant is always the one of the token. Guide: https://developers.mbcom.cloud/guides/authentication

## Permissions
| Permission | Grants |
|---|---|
| `tenant:masterdata:read` | read addresses, contact persons, postal addresses, VAT check history, distributor IDs, articles, product groups, lookups, number ranges, the company profile and field definitions; duplicate check and imprint lookup |
| `tenant:masterdata:write` | create, change, delete and merge addresses and their children, run VAT checks, assign distributor IDs, maintain articles and product groups, AI drafts |
| `tenant:settings:write` | edit lookups, number ranges, the company profile and field definitions |

## Conventions
- Addresses and articles page by cursor (below); the VAT checks of an address with `limit`
  (1–200, default 50) and `offset`, answering `{items, total}`. A `limit` or `offset` outside its
  range is `400 invalid`, never adjusted. Other lists answer `{items}` with all entries.
- Updates use optimistic locking: send the `version` you read; a stale version returns `409`
  with `code: version_conflict`. Every write to a contact person or postal address also bumps
  the version of its address and returns it as `addressVersion`.
- Creates are not idempotent (no idempotency key); `PUT` on lookups and distributor IDs
  creates or replaces the entry.
- Errors have the shared shape `{error, code, field?, details?}`; `error` is a German message
  for end users, `code` the stable reason to branch on. Invalid input – a malformed body or query as
  well as a value a rule refuses – is `400 invalid`: `field` names the first invalid field,
  `details.fields` lists `{field, message}` per invalid input (nested fields like
  `postalAddresses[0].postalCode`). `401`: missing or invalid token (no body); `403`: missing
  permission (`forbidden`) or no tenant in the token (`tenant_required`); unexpected errors are
  `500 internal`.
- The address and article lists page by cursor: `limit` (1–200, default 50) and `cursor` (the
  `nextCursor` of the previous page; keep `sort` and the filters unchanged). They answer
  `{items, total, nextCursor}`; a cursor of another sort or an altered one is `400 invalid`
  (`field: cursor`).
- Custom methods use a colon: `addresses:duplicates`, `addresses:batchUpdate`, `addresses:draft`, `imprint:lookup`.
- Dates are `YYYY-MM-DD`, times of day `HH:MM`, timestamps RFC 3339. Identifiers (VAT ID,
  IBAN, BIC, codes) are trimmed and upper-cased on write.
- Request bodies are limited to 2 MiB (4 MiB for `:draft`).

## Events
Changes are published through the transactional outbox, which other ConnectCloud services read
: `masterdata.address.created|updated|deleted|merged|vat_checked`,
`masterdata.distributor_id.assigned|removed`, `masterdata.product.created|updated|deleted`,
`masterdata.product_group.created|updated|deleted`, `masterdata.lookup.updated` and
`masterdata.tenant_profile.updated`.

# Addresses

## List addresses (tenant:masterdata:read)

`GET /api/masterdata/addresses`

Module: Master data · operationId: `listAddresses` · Tag: Addresses · Auth: access token (`Authorization: Bearer <accessToken>`)

Returns one page of compact address rows. `q` searches address number, customer and supplier
number, search term, company name, first and last name, email, VAT ID (spaces ignored) and the
postcode and city of every postal address (case-insensitive substring); a query of phone
characters only (digits, spaces, `+ - / ( ) .`) also matches the digits of `phone` and `mobile`,
typed nationally or internationally. The address columns
`street`, `postalCode`, `city` and `countryCode` come from the default billing postal
address (else the lowest `ansNr`). Filter by tenant-defined fields with `cf.<key>=<value>`
(at most 10; multiselect fields match one option, bool and number fields are parsed).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `q` | query | string |  | Search text |
| `search` | query | string |  | Alias of `q` (used when `q` is empty) |
| `status` | query | string |  | Comma-separated address status codes |
| `partyType` | query | string |  | (one of `COMPANY`, `PERSON`) |
| `adrNr` | query | string |  | The address with exactly this address number (`adrNr`, case-sensitive; at most one) |
| `blocked` | query | string |  | `true` only blocked, `false` only unblocked addresses; other values do not filter (one of `true`, `false`) |
| `tag` | query | string |  | Addresses carrying this tag (exact) |
| `role` | query | string |  | Comma-separated roles; matches addresses with any of them |
| `parentId` | query | string (uuid) |  | Subsidiaries of this address |
| `sort` | query | string |  | Sort key, prefix `-` for descending. `name` sorts by the shown name (`displayName`, the company name or first and last name of a person, case-insensitive). Unknown keys sort by name. (one of `adrNr`, `-adrNr`, `name`, `-name`, `city`, `-city`, `updatedAt`, `-updatedAt`, `createdAt`, `-createdAt`, `quality`, `-quality`; default `"name"`) |
| `limit` | query | integer |  | Page size 1–200; any other value is `400 invalid` (default `50`; max 200) |
| `cursor` | query | string |  | `nextCursor` of the previous page; leave out for the first page. Keep `sort` and the filters unchanged while paging: a cursor of another sort or an altered one is `400 invalid` (`field: cursor`). (max length 1024) |
| `cf.{key}` | query | string |  | Filter by the tenant-defined address field `key`, e.g. `cf.branche=it`. |

### Responses

- **200** One page of addresses (`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`)

Fields of the 200 answer:

- `items` (array of AddressListItem, required): One page of addresses
  - `adrNr` (string, required): Address number
  - `displayName` (string, required): Company name, else first and last name
  - `id` (string (uuid), required): Id of the address
  - `isBlocked` (boolean, required): General block
  - `partyType` (string, required): Company or person (one of `COMPANY`, `PERSON`)
  - `roles` (array of string, required): Roles derived from the status
  - `searchTerm` (string, required): Search term
  - `tags` (array of string, required): Tags
  - `updatedAt` (string (date-time), required): Time of the last change
  - `version` (integer, required): Optimistic locking version
  - `blockReason` (string): Reason of the general block (left out unless `isBlocked`)
  - `city` (string): City, see `street`
  - `companyName` (string): Company name
  - `countryCode` (string): Country (ISO 3166-1 alpha-2), see `street`
  - `customFields` (CustomFields): Tenant-defined values (left out when none are set)
  - `customerNumber` (string): Customer number
  - `dataQualityScore` (integer): Completeness score 0–100
  - `email` (string): Main e-mail address
  - `firstName` (string): First name
  - `lastName` (string): Last name
  - `phone` (string): Phone (E.164)
  - `postalCode` (string): Postal code, see `street`
  - `statusCode` (string): Code of `address-statuses`
  - `street` (string): Street of the default billing postal address (else the lowest `ansNr`)
  - `supplierNumber` (string): Supplier number
  - `vatCheckStatus` (VatCheckStatus): Result of the latest VAT check (absent when never checked) (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`, `NOT_CHECKED`)
  - `vatId` (string): VAT ID
- `total` (integer, required): Number of matching addresses
- `nextCursor` (string): Cursor of the next page (pass it as `cursor`); missing on the last page

Example 200 answer:

```json
{
  "items": [
    {
      "adrNr": "10001",
      "city": "Schönau am Königssee",
      "companyName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "countryCode": "DE",
      "customFields": {
        "branche": "hotel"
      },
      "customerNumber": "10001",
      "dataQualityScore": 90,
      "displayName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "email": "rezeption@alpenhotel-seeblick.example",
      "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
      "isBlocked": false,
      "partyType": "COMPANY",
      "phone": "+49865298760",
      "postalCode": "83471",
      "roles": [
        "CUSTOMER"
      ],
      "searchTerm": "ALPENHOTEL SEEBLICK",
      "statusCode": "KUNDE",
      "street": "Seestraße 4",
      "tags": [
        "Wartungsvertrag"
      ],
      "updatedAt": "2026-11-03T09:14:22Z",
      "vatCheckStatus": "OFFICIALLY_CONFIRMED",
      "vatId": "DE811234567",
      "version": 7
    }
  ],
  "total": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/masterdata/addresses' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create an address (tenant:masterdata:write)

`POST /api/masterdata/addresses`

Module: Master data · operationId: `createAddress` · Tag: Addresses · Auth: access token (`Authorization: Bearer <accessToken>`)

Stores a new address with its child collections. An empty `adrNr` is assigned from the
`ADDRESS` number range, an empty `searchTerm` is derived from the name. The first postal
address becomes the default billing and shipping address, the first bank account the
default account. Omitted `purchaseOrderRequired` is `true`. A `customerNumber` or `supplierNumber`
another live address of the tenant has answers `409` `customer_number_taken` / `supplier_number_taken`
(`field` and `details.fields` name the field). Emits `masterdata.address.created`.

### Request body

`application/json` (required)

- `statusCode` (string, required): Code of `address-statuses` (required). Its flags decide the `roles`
- `version` (integer, required): Optimistic locking version; send the version you read (ignored on create)
- `accountOwner` (string): Account owner (responsible person) in CRM (max length 255)
- `accountType` (string): Individual or collective account (one of `INDIVIDUAL`, `COLLECTIVE`; default `"INDIVIDUAL"`)
- `additionalName` (string): Name addition (second name line) (max length 255)
- `adrNr` (string): Address number, unique per tenant; assigned from the ADDRESS range when empty (max length 32)
- `annualRevenue` (number, nullable): Annual revenue
- `bankAccounts` (array of BankAccount): Bank accounts
  - `iban` (string, required): Unique per address
  - `accountHolder` (string): Account holder (max length 255)
  - `bankName` (string): Name of the bank (max length 128)
  - `bic` (string): BIC
  - `id` (string (uuid)): Id of the bank account
  - `isDefault` (boolean): At most one; the first account is the default when none is set
- `blockReason` (string): Cleared when `isBlocked` is false (max length 255)
- `blockedAt` (string (date-time), read-only): Time of the general block
- `blockedBy` (string, read-only): Actor of the general block
- `commercialRegister` (string): Commercial register number (Handelsregister) (max length 128)
- `companyName` (string): Company name (required for `partyType` COMPANY) (max length 255)
- `contactPersons` (array of ContactPerson): Contact persons (Ansprechpartner)
  - `aspNr` (integer): Number within the address; assigned
  - `availableFrom1` (string, nullable): Reachable from (HH:MM)
  - `availableFrom2` (string, nullable): Second time window: reachable from (HH:MM)
  - `availableTo1` (string, nullable): After `availableFrom1`
  - `availableTo2` (string, nullable): After `availableFrom2`
  - `birthday` (string (date), nullable): Birthday (YYYY-MM-DD)
  - `blockReason` (string, read-only): Reason of the block
  - `blockedAt` (string (date-time), read-only): Time of the block
  - `blockedBy` (string, read-only): Actor of the block
  - `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`.
  - `department` (string): Department
  - `doNotCall` (boolean): Do not call
  - `email1` (string (email)): First e-mail address
  - `email2` (string (email)): Second e-mail address
  - `emailOptOut` (boolean): No marketing e-mails
  - `fax` (string): E.164
  - `firstName` (string): First name (max length 128)
  - `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
  - `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
  - `id` (string (uuid)): Id of the contact person
  - `info` (string): Info text
  - `isActive` (boolean): False when `leftAt` is set (default `true`)
  - `isBlocked` (boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set with `POST /addresses/{id}/contacts/{cid}/block`
  - `isDefault` (boolean): Default contact of the address (at most one)
  - `languageCode` (string): Language (ISO 639-1)
  - `lastName` (string): Last name (max length 128)
  - `leftAt` (string (date), nullable): Date the person left the company; sets `isActive` false
  - `letterSalutation` (string): Salutation line of letters
  - `linkedinUrl` (string (uri)): LinkedIn profile (max length 255)
  - `mobile` (string): E.164
  - `namePrefix` (string): Name prefix
  - `nameSuffix` (string): Name suffix
  - `phone1` (string): E.164
  - `phone2` (string): E.164
  - `portalUserId` (string): Linked desk portal user (max length 255)
  - `position` (string): Position
  - `postalAddressAnsNr` (integer, nullable): `ansNr` of a postal address of the same address
  - `preferredChannel` (string): Preferred contact channel (one of `EMAIL`, `PHONE`, `MOBILE`, `LETTER`, `PORTAL`)
  - `reportsToAspNr` (integer, nullable): `aspNr` of the manager within the same address (no cycles)
  - `roles` (array of string): Roles in the buying centre or for ticket routing
  - `salutationCode` (string): Code of `salutations`
  - `timezone` (string): IANA time zone
  - `title` (string): Title
  - `version` (integer): Version of this contact (child updates)
- `createdAt` (string (date-time), read-only): Creation time
- `createdBy` (string, read-only): Who created the address (subject of the token)
- `creditLimit` (number, nullable): Credit limit
- `creditorAccountNo` (string): Creditor account. With `glAccountLength` g it must lie in [7*10^g, 10^(g+1)-1] (g=4: 70000-99999); checked only when the value changes, else 400 (max length 32)
- `currencyCode` (string): ISO 4217
- `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`.
- `customerNo` (string, read-only): Tenant customer number (from the token)
- `customerNumber` (string): Customer number (Kundennummer), unique among the live addresses of the tenant (`409` `customer_number_taken`). Empty on an address with the role CUSTOMER: the address number (adrNr) is used while no other address has it as customer number, except in the platform operator tenant (max length 64)
- `customerSince` (string (date), nullable): Customer since (YYYY-MM-DD)
- `dataQualityScore` (integer, read-only): Completeness score computed on save (max 100)
- `deletionBlockedUntil` (string (date), nullable): Deleting the address or merging it away (as source) through this date (inclusive) answers 409 (Löschsperre bis TT.MM.JJJJ); a merge keeps the later date of both addresses
- `deliveryBlockReason` (string, read-only): Reason of the delivery block
- `deliveryBlocked` (boolean, read-only): Delivery block (set with `POST /addresses/{id}/blocks`; a PUT keeps it)
- `deliveryBlockedAt` (string (date-time), read-only): Time of the delivery block
- `deliveryBlockedBy` (string, read-only): Actor of the delivery block
- `deliveryCondition` (string): Delivery condition (free text) (max length 255)
- `discountRate` (number, nullable): Discount in percent (max 100)
- `displayName` (string, read-only): Company name, else first and last name
- `distributorIds` (array of DistributorID, read-only): Maintained via /api/masterdata/distributor-ids
  - `addressId` (string (uuid), required): Supplier address the distributor ID maps to
  - `addressName` (string, required): Display name of that address
  - `adrNr` (string, required): Address number of that address
  - `distributorId` (string, required): The distributor's own ID
  - `source` (string, required): Distributor (lower case, e.g. egis, ingram)
  - `updatedAt` (string (date-time), required): Time of the last change
  - `distributorName` (string): Name of the distributor
- `dunningBlocked` (boolean): Dunning block (also set with `POST /addresses/{id}/blocks`, type DUNNING)
- `dunningBlockedAt` (string (date-time), read-only): Time of the dunning block
- `dunningBlockedBy` (string, read-only): Actor of the dunning block
- `eInvoiceBuyerRef` (string): Leitweg-ID (XRechnung buyer reference)
- `eInvoiceFormat` (string): Preferred e-invoice format (one of `XRECHNUNG`, `ZUGFERD`, `PEPPOL`, `PDF`)
- `email` (string (email)): Main e-mail address (max length 255)
- `employeeCount` (integer, nullable): Number of employees
- `enrichedAt` (string (date-time), read-only): Time of the last enrichment
- `enrichmentData` (any): Free JSON of an enrichment
- `enrichmentStatus` (string): State of the data enrichment (one of `NOT_ENRICHED`, `PENDING`, `ENRICHED`, `FAILED`; default `"NOT_ENRICHED"`)
- `externalIds` (object): Keys of other systems, at most 20; key `^[a-z0-9_-]{1,64}$`, value max. 255 characters
- `fax` (string): E.164 (max length 64)
- `firstName` (string): First name (of a person) (max length 128)
- `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
- `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
- `gdprDataOrigin` (string): GDPR: where the data came from (max length 255)
- `gdprPurpose` (string): GDPR: purpose of the processing (max length 255)
- `gln` (string): Global Location Number with check digit
- `id` (string (uuid), read-only): Id of the address
- `industryCode` (string): Code of `industries`
- `info` (string): Info text
- `invoiceEmail` (string (email)): E-mail address for invoices (max length 255)
- `isBlocked` (boolean): General block of the address
- `isDiscountEligible` (boolean): Discounts may be granted
- `isEuForeign` (boolean, read-only): Derived like `isForeign` (both countries in the EU)
- `isForeign` (boolean, read-only): Derived on every write from the billing country (default billing postal address, else the first one) and the tenant country; ignored on write
- `isOneTime` (boolean): One-time account (Diverse)
- `isTaxInclusive` (boolean): Prices are gross (tax inclusive)
- `languageCode` (string): ISO 639-1, optionally with region
- `lastName` (string): Last name (required for `partyType` PERSON) (max length 128)
- `legalForm` (string): Legal form (max length 64)
- `marketingObjection` (boolean): Objection to advertising
- `marketingObjectionAt` (string (date-time), nullable, read-only): Set by the server when `marketingObjection` turns true
- `memo` (string): Internal memo
- `mergedIntoId` (string (uuid), read-only): Set when the address was merged into another one
- `mobile` (string): E.164 (max length 64)
- `netDays` (integer, nullable): Payment term in days (net)
- `ourCustomerNumber` (string): Our customer number at this party (max length 64)
- `parentAddressId` (string (uuid)): Parent company (another address of the tenant; no cycles)
- `parentName` (string, read-only): Display name of the parent address (set on read)
- `partyType` (string): COMPANY needs `companyName`, PERSON needs `lastName` (one of `COMPANY`, `PERSON`; default `"COMPANY"`)
- `paymentBlockReason` (string, read-only): Reason of the payment block
- `paymentBlocked` (boolean, read-only): Payment block (set with `POST /addresses/{id}/blocks`; a PUT keeps it)
- `paymentBlockedAt` (string (date-time), read-only): Time of the payment block
- `paymentBlockedBy` (string, read-only): Actor of the payment block
- `paymentMethodCode` (string): Code of `payment-methods`
- `paymentTermCode` (string): Code of `payment-terms`
- `peppolId` (string): Peppol participant ID `scheme:id`
- `phone` (string): E.164 (+4989123456). Input is normalised with the country of the default billing postal address, else of the tenant profile, else DE; extensions are dropped; a changed value that cannot be parsed answers 400 (a value equal to the stored one is kept) (max length 64)
- `postalAddresses` (array of PostalAddress): Postal addresses (Anschriften)
  - `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
- `postingAccountNo` (string): Debtor account (Debitorenkonto). With the tenant's `glAccountLength` g it must lie in [10^g, 7*10^g-1] (g=4: 10000-69999); checked only when the value changes, else 400 (max length 32)
- `purchaseOrderEmail` (string (email)): Mail address that receives the purchase orders sent to this supplier; empty falls back to `email` (max length 254)
- `purchaseOrderRequired` (boolean, nullable): Invoices of this supplier need a purchase order. Omitted: `true` on create, unchanged on update
- `registerCourt` (string): Register court (max length 128)
- `reverseCharge` (boolean): Reverse charge (§13b UStG)
- `roles` (array of string, read-only): Derived from the flags of the status (`isCustomer` CUSTOMER, `isVendor` SUPPLIER, `isLead` PROSPECT, `isPartner` PARTNER); a value in the request is ignored
- `salesRepCommissionRate` (number, nullable): Commission of the sales representative in percent (max 100)
- `salesRepNo` (string): Number of the sales representative (max length 32)
- `salutationCode` (string): Code of `salutations`
- `searchTerm` (string): Search term (Suchbegriff); derived from the name when empty (max length 255)
- `sepaMandates` (array of SepaMandate): SEPA direct debit mandates
  - `bankAccountIban` (string, required): IBAN of a bank account of this address
  - `signedAt` (string (date), required): Date of signature (YYYY-MM-DD)
  - `bankAccountId` (string (uuid), read-only): Id of the linked bank account
  - `creditorId` (string): Creditor identifier (max length 35)
  - `id` (string (uuid)): Id of the mandate
  - `lastUsedAt` (string (date), nullable): Set when a collection uses the mandate. A mandate with lastUsedAt cannot be deleted, also not together with its bank account: a PUT that omits it answers 409; revoke it with status REVOKED instead
  - `mandateReference` (string): Assigned from the MANDATE range when empty
  - `mandateType` (string): CORE or B2B direct debit (one of `CORE`, `B2B`; default `"CORE"`)
  - `revokedAt` (string (date), nullable): Set by the server for status REVOKED (the first stamp stays; a client value is ignored)
  - `sequenceType` (string): Sequence type of the next collection (one of `FRST`, `RCUR`, `OOFF`, `FNAL`; default `"FRST"`)
  - `status` (string): State of the mandate (one of `ACTIVE`, `REVOKED`, `EXPIRED`; default `"ACTIVE"`)
  - `validFrom` (string (date), nullable): Valid from (YYYY-MM-DD)
- `shippingTypeCode` (string): Code of `shipping-types`
- `skontoDays1` (integer, nullable): Days for the first cash discount
- `skontoDays2` (integer, nullable): Days for the second cash discount
- `skontoRate1` (number, nullable): First cash discount in percent (max 100)
- `skontoRate2` (number, nullable): Second cash discount in percent (max 100)
- `smallBusiness` (boolean): Small business (§19 UStG)
- `source` (string): Where the address came from (lead source) (max length 64)
- `supplierNumber` (string): Supplier number (Lieferantennummer), unique among the live addresses of the tenant (`409` `supplier_number_taken`). Empty on an address with the role SUPPLIER: the address number (adrNr) is used while no other address has it as supplier number (max length 64)
- `syncStatus` (string, read-only): Reserved for an ERP synchronisation; STANDALONE for records of this API (one of `STANDALONE`, `PENDING_CREATION`, `PENDING_UPDATE`, `SYNCED`, `CONFLICT`, `ERROR`)
- `tags` (array of string): Duplicates (case-insensitive) are removed
- `taxNumber` (string): Tax number (Steuernummer) (max length 64)
- `taxZone` (string, read-only): Derived on every write: DOMESTIC (billing country = tenant country), EU_VATID (EU with `vatId`), EU_PRIVATE (EU without `vatId`), THIRD_COUNTRY; empty without a postal address. Ignored on write. `vatCategory` stays for compatibility (one of `DOMESTIC`, `EU_VATID`, `EU_PRIVATE`, `THIRD_COUNTRY`)
- `tenantName` (string, read-only): Tenant name (from the token)
- `title` (string): Title of the party (e.g. Dr.) (max length 64)
- `updatedAt` (string (date-time), read-only): Time of the last change
- `updatedBy` (string, read-only): Who changed the address last (subject of the token)
- `valutaDays` (integer, nullable): Value date days
- `vatCategory` (integer): VAT category (microtech) (max 9)
- `vatCheckStatus` (VatCheckStatus, read-only): Result of the latest official VAT check (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`, `NOT_CHECKED`)
- `vatCheckedAt` (string (date-time), read-only): Time of the latest official VAT check
- `vatId` (string): VAT ID (USt-IdNr.)
- `website` (string (uri)): Website (max length 255)

Example:

```json
{
  "bankAccounts": [
    {
      "bankName": "Deutsche Kreditbank",
      "bic": "BYLADEM1001",
      "iban": "DE02120300000000202051",
      "isDefault": true
    }
  ],
  "companyName": "Muster GmbH",
  "contactPersons": [
    {
      "email1": "erika.musterfrau@muster.de",
      "firstName": "Erika",
      "isDefault": true,
      "lastName": "Musterfrau",
      "position": "Leitung Einkauf",
      "roles": [
        "PURCHASING"
      ],
      "salutationCode": "FRAU"
    }
  ],
  "customerNumber": "10023",
  "email": "info@muster.de",
  "legalForm": "GmbH",
  "partyType": "COMPANY",
  "paymentTermCode": "NETTO30",
  "phone": "+49 30 1234567",
  "postalAddresses": [
    {
      "city": "Berlin",
      "countryCode": "DE",
      "isDefaultBilling": true,
      "isDefaultShipping": true,
      "postalCode": "10115",
      "street": "Hauptstraße 1"
    }
  ],
  "statusCode": "KUNDE",
  "tags": [
    "Stammkunde"
  ],
  "vatId": "DE123456789",
  "website": "https://www.muster.de"
}
```

### Responses

- **201** Created (`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`)
- **409** Stale version or conflict with existing data (`application/json`)
- **413** The body is over the limit (2 MiB; AI drafts 4 MiB) (`application/json`)

Fields of the 201 answer:

- `statusCode` (string, required): Code of `address-statuses` (required). Its flags decide the `roles`
- `version` (integer, required): Optimistic locking version; send the version you read (ignored on create)
- `accountOwner` (string): Account owner (responsible person) in CRM (max length 255)
- `accountType` (string): Individual or collective account (one of `INDIVIDUAL`, `COLLECTIVE`; default `"INDIVIDUAL"`)
- `additionalName` (string): Name addition (second name line) (max length 255)
- `adrNr` (string): Address number, unique per tenant; assigned from the ADDRESS range when empty (max length 32)
- `annualRevenue` (number, nullable): Annual revenue
- `bankAccounts` (array of BankAccount): Bank accounts
  - `iban` (string, required): Unique per address
  - `accountHolder` (string): Account holder (max length 255)
  - `bankName` (string): Name of the bank (max length 128)
  - `bic` (string): BIC
  - `id` (string (uuid)): Id of the bank account
  - `isDefault` (boolean): At most one; the first account is the default when none is set
- `blockReason` (string): Cleared when `isBlocked` is false (max length 255)
- `blockedAt` (string (date-time), read-only): Time of the general block
- `blockedBy` (string, read-only): Actor of the general block
- `commercialRegister` (string): Commercial register number (Handelsregister) (max length 128)
- `companyName` (string): Company name (required for `partyType` COMPANY) (max length 255)
- `contactPersons` (array of ContactPerson): Contact persons (Ansprechpartner)
  - `aspNr` (integer): Number within the address; assigned
  - `availableFrom1` (string, nullable): Reachable from (HH:MM)
  - `availableFrom2` (string, nullable): Second time window: reachable from (HH:MM)
  - `availableTo1` (string, nullable): After `availableFrom1`
  - `availableTo2` (string, nullable): After `availableFrom2`
  - `birthday` (string (date), nullable): Birthday (YYYY-MM-DD)
  - `blockReason` (string, read-only): Reason of the block
  - `blockedAt` (string (date-time), read-only): Time of the block
  - `blockedBy` (string, read-only): Actor of the block
  - `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`.
  - `department` (string): Department
  - `doNotCall` (boolean): Do not call
  - `email1` (string (email)): First e-mail address
  - `email2` (string (email)): Second e-mail address
  - `emailOptOut` (boolean): No marketing e-mails
  - `fax` (string): E.164
  - `firstName` (string): First name (max length 128)
  - `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
  - `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
  - `id` (string (uuid)): Id of the contact person
  - `info` (string): Info text
  - `isActive` (boolean): False when `leftAt` is set (default `true`)
  - `isBlocked` (boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set with `POST /addresses/{id}/contacts/{cid}/block`
  - `isDefault` (boolean): Default contact of the address (at most one)
  - `languageCode` (string): Language (ISO 639-1)
  - `lastName` (string): Last name (max length 128)
  - `leftAt` (string (date), nullable): Date the person left the company; sets `isActive` false
  - `letterSalutation` (string): Salutation line of letters
  - `linkedinUrl` (string (uri)): LinkedIn profile (max length 255)
  - `mobile` (string): E.164
  - `namePrefix` (string): Name prefix
  - `nameSuffix` (string): Name suffix
  - `phone1` (string): E.164
  - `phone2` (string): E.164
  - `portalUserId` (string): Linked desk portal user (max length 255)
  - `position` (string): Position
  - `postalAddressAnsNr` (integer, nullable): `ansNr` of a postal address of the same address
  - `preferredChannel` (string): Preferred contact channel (one of `EMAIL`, `PHONE`, `MOBILE`, `LETTER`, `PORTAL`)
  - `reportsToAspNr` (integer, nullable): `aspNr` of the manager within the same address (no cycles)
  - `roles` (array of string): Roles in the buying centre or for ticket routing
  - `salutationCode` (string): Code of `salutations`
  - `timezone` (string): IANA time zone
  - `title` (string): Title
  - `version` (integer): Version of this contact (child updates)
- `createdAt` (string (date-time), read-only): Creation time
- `createdBy` (string, read-only): Who created the address (subject of the token)
- `creditLimit` (number, nullable): Credit limit
- `creditorAccountNo` (string): Creditor account. With `glAccountLength` g it must lie in [7*10^g, 10^(g+1)-1] (g=4: 70000-99999); checked only when the value changes, else 400 (max length 32)
- `currencyCode` (string): ISO 4217
- `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`.
- `customerNo` (string, read-only): Tenant customer number (from the token)
- `customerNumber` (string): Customer number (Kundennummer), unique among the live addresses of the tenant (`409` `customer_number_taken`). Empty on an address with the role CUSTOMER: the address number (adrNr) is used while no other address has it as customer number, except in the platform operator tenant (max length 64)
- `customerSince` (string (date), nullable): Customer since (YYYY-MM-DD)
- `dataQualityScore` (integer, read-only): Completeness score computed on save (max 100)
- `deletionBlockedUntil` (string (date), nullable): Deleting the address or merging it away (as source) through this date (inclusive) answers 409 (Löschsperre bis TT.MM.JJJJ); a merge keeps the later date of both addresses
- `deliveryBlockReason` (string, read-only): Reason of the delivery block
- `deliveryBlocked` (boolean, read-only): Delivery block (set with `POST /addresses/{id}/blocks`; a PUT keeps it)
- `deliveryBlockedAt` (string (date-time), read-only): Time of the delivery block
- `deliveryBlockedBy` (string, read-only): Actor of the delivery block
- `deliveryCondition` (string): Delivery condition (free text) (max length 255)
- `discountRate` (number, nullable): Discount in percent (max 100)
- `displayName` (string, read-only): Company name, else first and last name
- `distributorIds` (array of DistributorID, read-only): Maintained via /api/masterdata/distributor-ids
  - `addressId` (string (uuid), required): Supplier address the distributor ID maps to
  - `addressName` (string, required): Display name of that address
  - `adrNr` (string, required): Address number of that address
  - `distributorId` (string, required): The distributor's own ID
  - `source` (string, required): Distributor (lower case, e.g. egis, ingram)
  - `updatedAt` (string (date-time), required): Time of the last change
  - `distributorName` (string): Name of the distributor
- `dunningBlocked` (boolean): Dunning block (also set with `POST /addresses/{id}/blocks`, type DUNNING)
- `dunningBlockedAt` (string (date-time), read-only): Time of the dunning block
- `dunningBlockedBy` (string, read-only): Actor of the dunning block
- `eInvoiceBuyerRef` (string): Leitweg-ID (XRechnung buyer reference)
- `eInvoiceFormat` (string): Preferred e-invoice format (one of `XRECHNUNG`, `ZUGFERD`, `PEPPOL`, `PDF`)
- `email` (string (email)): Main e-mail address (max length 255)
- `employeeCount` (integer, nullable): Number of employees
- `enrichedAt` (string (date-time), read-only): Time of the last enrichment
- `enrichmentData` (any): Free JSON of an enrichment
- `enrichmentStatus` (string): State of the data enrichment (one of `NOT_ENRICHED`, `PENDING`, `ENRICHED`, `FAILED`; default `"NOT_ENRICHED"`)
- `externalIds` (object): Keys of other systems, at most 20; key `^[a-z0-9_-]{1,64}$`, value max. 255 characters
- `fax` (string): E.164 (max length 64)
- `firstName` (string): First name (of a person) (max length 128)
- `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
- `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
- `gdprDataOrigin` (string): GDPR: where the data came from (max length 255)
- `gdprPurpose` (string): GDPR: purpose of the processing (max length 255)
- `gln` (string): Global Location Number with check digit
- `id` (string (uuid), read-only): Id of the address
- `industryCode` (string): Code of `industries`
- `info` (string): Info text
- `invoiceEmail` (string (email)): E-mail address for invoices (max length 255)
- `isBlocked` (boolean): General block of the address
- `isDiscountEligible` (boolean): Discounts may be granted
- `isEuForeign` (boolean, read-only): Derived like `isForeign` (both countries in the EU)
- `isForeign` (boolean, read-only): Derived on every write from the billing country (default billing postal address, else the first one) and the tenant country; ignored on write
- `isOneTime` (boolean): One-time account (Diverse)
- `isTaxInclusive` (boolean): Prices are gross (tax inclusive)
- `languageCode` (string): ISO 639-1, optionally with region
- `lastName` (string): Last name (required for `partyType` PERSON) (max length 128)
- `legalForm` (string): Legal form (max length 64)
- `marketingObjection` (boolean): Objection to advertising
- `marketingObjectionAt` (string (date-time), nullable, read-only): Set by the server when `marketingObjection` turns true
- `memo` (string): Internal memo
- `mergedIntoId` (string (uuid), read-only): Set when the address was merged into another one
- `mobile` (string): E.164 (max length 64)
- `netDays` (integer, nullable): Payment term in days (net)
- `ourCustomerNumber` (string): Our customer number at this party (max length 64)
- `parentAddressId` (string (uuid)): Parent company (another address of the tenant; no cycles)
- `parentName` (string, read-only): Display name of the parent address (set on read)
- `partyType` (string): COMPANY needs `companyName`, PERSON needs `lastName` (one of `COMPANY`, `PERSON`; default `"COMPANY"`)
- `paymentBlockReason` (string, read-only): Reason of the payment block
- `paymentBlocked` (boolean, read-only): Payment block (set with `POST /addresses/{id}/blocks`; a PUT keeps it)
- `paymentBlockedAt` (string (date-time), read-only): Time of the payment block
- `paymentBlockedBy` (string, read-only): Actor of the payment block
- `paymentMethodCode` (string): Code of `payment-methods`
- `paymentTermCode` (string): Code of `payment-terms`
- `peppolId` (string): Peppol participant ID `scheme:id`
- `phone` (string): E.164 (+4989123456). Input is normalised with the country of the default billing postal address, else of the tenant profile, else DE; extensions are dropped; a changed value that cannot be parsed answers 400 (a value equal to the stored one is kept) (max length 64)
- `postalAddresses` (array of PostalAddress): Postal addresses (Anschriften)
  - `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
- `postingAccountNo` (string): Debtor account (Debitorenkonto). With the tenant's `glAccountLength` g it must lie in [10^g, 7*10^g-1] (g=4: 10000-69999); checked only when the value changes, else 400 (max length 32)
- `purchaseOrderEmail` (string (email)): Mail address that receives the purchase orders sent to this supplier; empty falls back to `email` (max length 254)
- `purchaseOrderRequired` (boolean, nullable): Invoices of this supplier need a purchase order. Omitted: `true` on create, unchanged on update
- `registerCourt` (string): Register court (max length 128)
- `reverseCharge` (boolean): Reverse charge (§13b UStG)
- `roles` (array of string, read-only): Derived from the flags of the status (`isCustomer` CUSTOMER, `isVendor` SUPPLIER, `isLead` PROSPECT, `isPartner` PARTNER); a value in the request is ignored
- `salesRepCommissionRate` (number, nullable): Commission of the sales representative in percent (max 100)
- `salesRepNo` (string): Number of the sales representative (max length 32)
- `salutationCode` (string): Code of `salutations`
- `searchTerm` (string): Search term (Suchbegriff); derived from the name when empty (max length 255)
- `sepaMandates` (array of SepaMandate): SEPA direct debit mandates
  - `bankAccountIban` (string, required): IBAN of a bank account of this address
  - `signedAt` (string (date), required): Date of signature (YYYY-MM-DD)
  - `bankAccountId` (string (uuid), read-only): Id of the linked bank account
  - `creditorId` (string): Creditor identifier (max length 35)
  - `id` (string (uuid)): Id of the mandate
  - `lastUsedAt` (string (date), nullable): Set when a collection uses the mandate. A mandate with lastUsedAt cannot be deleted, also not together with its bank account: a PUT that omits it answers 409; revoke it with status REVOKED instead
  - `mandateReference` (string): Assigned from the MANDATE range when empty
  - `mandateType` (string): CORE or B2B direct debit (one of `CORE`, `B2B`; default `"CORE"`)
  - `revokedAt` (string (date), nullable): Set by the server for status REVOKED (the first stamp stays; a client value is ignored)
  - `sequenceType` (string): Sequence type of the next collection (one of `FRST`, `RCUR`, `OOFF`, `FNAL`; default `"FRST"`)
  - `status` (string): State of the mandate (one of `ACTIVE`, `REVOKED`, `EXPIRED`; default `"ACTIVE"`)
  - `validFrom` (string (date), nullable): Valid from (YYYY-MM-DD)
- `shippingTypeCode` (string): Code of `shipping-types`
- `skontoDays1` (integer, nullable): Days for the first cash discount
- `skontoDays2` (integer, nullable): Days for the second cash discount
- `skontoRate1` (number, nullable): First cash discount in percent (max 100)
- `skontoRate2` (number, nullable): Second cash discount in percent (max 100)
- `smallBusiness` (boolean): Small business (§19 UStG)
- `source` (string): Where the address came from (lead source) (max length 64)
- `supplierNumber` (string): Supplier number (Lieferantennummer), unique among the live addresses of the tenant (`409` `supplier_number_taken`). Empty on an address with the role SUPPLIER: the address number (adrNr) is used while no other address has it as supplier number (max length 64)
- `syncStatus` (string, read-only): Reserved for an ERP synchronisation; STANDALONE for records of this API (one of `STANDALONE`, `PENDING_CREATION`, `PENDING_UPDATE`, `SYNCED`, `CONFLICT`, `ERROR`)
- `tags` (array of string): Duplicates (case-insensitive) are removed
- `taxNumber` (string): Tax number (Steuernummer) (max length 64)
- `taxZone` (string, read-only): Derived on every write: DOMESTIC (billing country = tenant country), EU_VATID (EU with `vatId`), EU_PRIVATE (EU without `vatId`), THIRD_COUNTRY; empty without a postal address. Ignored on write. `vatCategory` stays for compatibility (one of `DOMESTIC`, `EU_VATID`, `EU_PRIVATE`, `THIRD_COUNTRY`)
- `tenantName` (string, read-only): Tenant name (from the token)
- `title` (string): Title of the party (e.g. Dr.) (max length 64)
- `updatedAt` (string (date-time), read-only): Time of the last change
- `updatedBy` (string, read-only): Who changed the address last (subject of the token)
- `valutaDays` (integer, nullable): Value date days
- `vatCategory` (integer): VAT category (microtech) (max 9)
- `vatCheckStatus` (VatCheckStatus, read-only): Result of the latest official VAT check (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`, `NOT_CHECKED`)
- `vatCheckedAt` (string (date-time), read-only): Time of the latest official VAT check
- `vatId` (string): VAT ID (USt-IdNr.)
- `website` (string (uri)): Website (max length 255)

Example 201 answer:

```json
{
  "accountOwner": "Lena Vogel",
  "accountType": "INDIVIDUAL",
  "adrNr": "10001",
  "bankAccounts": [
    {
      "accountHolder": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "bankName": "Commerzbank",
      "bic": "COBADEFFXXX",
      "iban": "DE89370400440532013000",
      "id": "4e6a8c0e-2a4b-4d6f-8a0c-2e4a6b8d0f2a",
      "isDefault": true
    }
  ],
  "commercialRegister": "HRA 4711",
  "companyName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "contactPersons": [
    {
      "aspNr": 1,
      "email1": "georg.moser@alpenhotel-seeblick.example",
      "firstName": "Georg",
      "gdprConsent": "UNKNOWN",
      "id": "6a8c0e2a-4b6d-4f8a-9c0e-2a4b6d8f0a2c",
      "isActive": true,
      "isDefault": true,
      "lastName": "Moser",
      "letterSalutation": "Sehr geehrter Herr Moser",
      "phone1": "+49865298760",
      "position": "Geschäftsführer",
      "postalAddressAnsNr": 1,
      "roles": [
        "DECISION_MAKER"
      ],
      "salutationCode": "HERR",
      "version": 1
    },
    {
      "aspNr": 2,
      "availableFrom1": "08:00",
      "availableTo1": "16:00",
      "customFields": {},
      "doNotCall": false,
      "email1": "katrin.stadler@alpenhotel-seeblick.example",
      "emailOptOut": false,
      "firstName": "Katrin",
      "gdprConsent": "UNKNOWN",
      "id": "8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a",
      "isActive": true,
      "isBlocked": false,
      "isDefault": false,
      "languageCode": "de",
      "lastName": "Stadler",
      "letterSalutation": "Sehr geehrte Frau Stadler",
      "phone1": "+498652987612",
      "position": "Empfangsleitung und IT",
      "postalAddressAnsNr": 1,
      "preferredChannel": "PHONE",
      "roles": [
        "TECHNICAL",
        "SUPPORT"
      ],
      "salutationCode": "FRAU",
      "timezone": "Europe/Berlin",
      "version": 3
    }
  ],
  "createdAt": "2026-01-02T08:00:00Z",
  "createdBy": "laura.kaestner@muster-it.example",
  "currencyCode": "EUR",
  "customFields": {
    "branche": "hotel"
  },
  "customerNo": "99999",
  "customerNumber": "10001",
  "customerSince": "2019-04-01",
  "dataQualityScore": 90,
  "deliveryBlocked": false,
  "displayName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "distributorIds": [
    {
      "addressId": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
      "addressName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "adrNr": "10001",
      "distributorId": "700123",
      "distributorName": "EGIS Computer Service-Center GmbH",
      "source": "egis",
      "updatedAt": "2026-05-20T11:40:00Z"
    }
  ],
  "dunningBlocked": false,
  "eInvoiceFormat": "ZUGFERD",
  "email": "rezeption@alpenhotel-seeblick.example",
  "employeeCount": 38,
  "enrichmentStatus": "NOT_ENRICHED",
  "gdprConsent": "UNKNOWN",
  "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
  "invoiceEmail": "buchhaltung@alpenhotel-seeblick.example",
  "isBlocked": false,
  "isDiscountEligible": true,
  "isEuForeign": false,
  "isForeign": false,
  "isOneTime": false,
  "isTaxInclusive": false,
  "languageCode": "de",
  "legalForm": "GmbH \u0026 Co. KG",
  "marketingObjection": false,
  "netDays": 30,
  "partyType": "COMPANY",
  "paymentBlocked": false,
  "paymentMethodCode": "UEBERWEISUNG",
  "paymentTermCode": "NETTO30",
  "phone": "+49865298760",
  "postalAddresses": [
    {
      "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
    }
  ],
  "postingAccountNo": "10001",
  "registerCourt": "Amtsgericht Traunstein",
  "reverseCharge": false,
  "roles": [
    "CUSTOMER"
  ],
  "searchTerm": "ALPENHOTEL SEEBLICK",
  "sepaMandates": [],
  "smallBusiness": false,
  "statusCode": "KUNDE",
  "syncStatus": "STANDALONE",
  "tags": [
    "Wartungsvertrag"
  ],
  "taxZone": "DOMESTIC",
  "tenantName": "DEMO",
  "updatedAt": "2026-11-03T09:14:22Z",
  "updatedBy": "christina.adler@muster-it.example",
  "vatCheckStatus": "OFFICIALLY_CONFIRMED",
  "vatCheckedAt": "2026-11-03T09:14:22Z",
  "vatId": "DE811234567",
  "version": 7,
  "website": "https://www.alpenhotel-seeblick.example"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/masterdata/addresses' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"bankAccounts":[{"bankName":"Deutsche Kreditbank","bic":"BYLADEM1001","iban":"DE02120300000000202051","isDefault":true}],"companyName":"Muster GmbH","contactPersons":[{"email1":"erika.musterfrau@muster.de","firstName":"Erika","isDefault":true,"lastName":"Musterfrau","position":"Leitung Einkauf","roles":["PURCHASING"],"salutationCode":"FRAU"}],"customerNumber":"10023","email":"info@muster.de","legalForm":"GmbH","partyType":"COMPANY","paymentTermCode":"NETTO30","phone":"+49 30 1234567","postalAddresses":[{"city":"Berlin","countryCode":"DE","isDefaultBilling":true,"isDefaultShipping":true,"postalCode":"10115","street":"Hauptstraße 1"}],"statusCode":"KUNDE","tags":["Stammkunde"],"vatId":"DE123456789","website":"https://www.muster.de"}'
```

## Get an address with all children (tenant:masterdata:read)

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

Module: Master data · operationId: `getAddress` · Tag: Addresses · Auth: access token (`Authorization: Bearer <accessToken>`)

A merged address answers `404` with `code` `merged` and `details.mergedInto` (the id of the kept address).

### Parameters

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

### Responses

- **200** The address aggregate (`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:

- `statusCode` (string, required): Code of `address-statuses` (required). Its flags decide the `roles`
- `version` (integer, required): Optimistic locking version; send the version you read (ignored on create)
- `accountOwner` (string): Account owner (responsible person) in CRM (max length 255)
- `accountType` (string): Individual or collective account (one of `INDIVIDUAL`, `COLLECTIVE`; default `"INDIVIDUAL"`)
- `additionalName` (string): Name addition (second name line) (max length 255)
- `adrNr` (string): Address number, unique per tenant; assigned from the ADDRESS range when empty (max length 32)
- `annualRevenue` (number, nullable): Annual revenue
- `bankAccounts` (array of BankAccount): Bank accounts
  - `iban` (string, required): Unique per address
  - `accountHolder` (string): Account holder (max length 255)
  - `bankName` (string): Name of the bank (max length 128)
  - `bic` (string): BIC
  - `id` (string (uuid)): Id of the bank account
  - `isDefault` (boolean): At most one; the first account is the default when none is set
- `blockReason` (string): Cleared when `isBlocked` is false (max length 255)
- `blockedAt` (string (date-time), read-only): Time of the general block
- `blockedBy` (string, read-only): Actor of the general block
- `commercialRegister` (string): Commercial register number (Handelsregister) (max length 128)
- `companyName` (string): Company name (required for `partyType` COMPANY) (max length 255)
- `contactPersons` (array of ContactPerson): Contact persons (Ansprechpartner)
  - `aspNr` (integer): Number within the address; assigned
  - `availableFrom1` (string, nullable): Reachable from (HH:MM)
  - `availableFrom2` (string, nullable): Second time window: reachable from (HH:MM)
  - `availableTo1` (string, nullable): After `availableFrom1`
  - `availableTo2` (string, nullable): After `availableFrom2`
  - `birthday` (string (date), nullable): Birthday (YYYY-MM-DD)
  - `blockReason` (string, read-only): Reason of the block
  - `blockedAt` (string (date-time), read-only): Time of the block
  - `blockedBy` (string, read-only): Actor of the block
  - `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`.
  - `department` (string): Department
  - `doNotCall` (boolean): Do not call
  - `email1` (string (email)): First e-mail address
  - `email2` (string (email)): Second e-mail address
  - `emailOptOut` (boolean): No marketing e-mails
  - `fax` (string): E.164
  - `firstName` (string): First name (max length 128)
  - `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
  - `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
  - `id` (string (uuid)): Id of the contact person
  - `info` (string): Info text
  - `isActive` (boolean): False when `leftAt` is set (default `true`)
  - `isBlocked` (boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set with `POST /addresses/{id}/contacts/{cid}/block`
  - `isDefault` (boolean): Default contact of the address (at most one)
  - `languageCode` (string): Language (ISO 639-1)
  - `lastName` (string): Last name (max length 128)
  - `leftAt` (string (date), nullable): Date the person left the company; sets `isActive` false
  - `letterSalutation` (string): Salutation line of letters
  - `linkedinUrl` (string (uri)): LinkedIn profile (max length 255)
  - `mobile` (string): E.164
  - `namePrefix` (string): Name prefix
  - `nameSuffix` (string): Name suffix
  - `phone1` (string): E.164
  - `phone2` (string): E.164
  - `portalUserId` (string): Linked desk portal user (max length 255)
  - `position` (string): Position
  - `postalAddressAnsNr` (integer, nullable): `ansNr` of a postal address of the same address
  - `preferredChannel` (string): Preferred contact channel (one of `EMAIL`, `PHONE`, `MOBILE`, `LETTER`, `PORTAL`)
  - `reportsToAspNr` (integer, nullable): `aspNr` of the manager within the same address (no cycles)
  - `roles` (array of string): Roles in the buying centre or for ticket routing
  - `salutationCode` (string): Code of `salutations`
  - `timezone` (string): IANA time zone
  - `title` (string): Title
  - `version` (integer): Version of this contact (child updates)
- `createdAt` (string (date-time), read-only): Creation time
- `createdBy` (string, read-only): Who created the address (subject of the token)
- `creditLimit` (number, nullable): Credit limit
- `creditorAccountNo` (string): Creditor account. With `glAccountLength` g it must lie in [7*10^g, 10^(g+1)-1] (g=4: 70000-99999); checked only when the value changes, else 400 (max length 32)
- `currencyCode` (string): ISO 4217
- `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`.
- `customerNo` (string, read-only): Tenant customer number (from the token)
- `customerNumber` (string): Customer number (Kundennummer), unique among the live addresses of the tenant (`409` `customer_number_taken`). Empty on an address with the role CUSTOMER: the address number (adrNr) is used while no other address has it as customer number, except in the platform operator tenant (max length 64)
- `customerSince` (string (date), nullable): Customer since (YYYY-MM-DD)
- `dataQualityScore` (integer, read-only): Completeness score computed on save (max 100)
- `deletionBlockedUntil` (string (date), nullable): Deleting the address or merging it away (as source) through this date (inclusive) answers 409 (Löschsperre bis TT.MM.JJJJ); a merge keeps the later date of both addresses
- `deliveryBlockReason` (string, read-only): Reason of the delivery block
- `deliveryBlocked` (boolean, read-only): Delivery block (set with `POST /addresses/{id}/blocks`; a PUT keeps it)
- `deliveryBlockedAt` (string (date-time), read-only): Time of the delivery block
- `deliveryBlockedBy` (string, read-only): Actor of the delivery block
- `deliveryCondition` (string): Delivery condition (free text) (max length 255)
- `discountRate` (number, nullable): Discount in percent (max 100)
- `displayName` (string, read-only): Company name, else first and last name
- `distributorIds` (array of DistributorID, read-only): Maintained via /api/masterdata/distributor-ids
  - `addressId` (string (uuid), required): Supplier address the distributor ID maps to
  - `addressName` (string, required): Display name of that address
  - `adrNr` (string, required): Address number of that address
  - `distributorId` (string, required): The distributor's own ID
  - `source` (string, required): Distributor (lower case, e.g. egis, ingram)
  - `updatedAt` (string (date-time), required): Time of the last change
  - `distributorName` (string): Name of the distributor
- `dunningBlocked` (boolean): Dunning block (also set with `POST /addresses/{id}/blocks`, type DUNNING)
- `dunningBlockedAt` (string (date-time), read-only): Time of the dunning block
- `dunningBlockedBy` (string, read-only): Actor of the dunning block
- `eInvoiceBuyerRef` (string): Leitweg-ID (XRechnung buyer reference)
- `eInvoiceFormat` (string): Preferred e-invoice format (one of `XRECHNUNG`, `ZUGFERD`, `PEPPOL`, `PDF`)
- `email` (string (email)): Main e-mail address (max length 255)
- `employeeCount` (integer, nullable): Number of employees
- `enrichedAt` (string (date-time), read-only): Time of the last enrichment
- `enrichmentData` (any): Free JSON of an enrichment
- `enrichmentStatus` (string): State of the data enrichment (one of `NOT_ENRICHED`, `PENDING`, `ENRICHED`, `FAILED`; default `"NOT_ENRICHED"`)
- `externalIds` (object): Keys of other systems, at most 20; key `^[a-z0-9_-]{1,64}$`, value max. 255 characters
- `fax` (string): E.164 (max length 64)
- `firstName` (string): First name (of a person) (max length 128)
- `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
- `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
- `gdprDataOrigin` (string): GDPR: where the data came from (max length 255)
- `gdprPurpose` (string): GDPR: purpose of the processing (max length 255)
- `gln` (string): Global Location Number with check digit
- `id` (string (uuid), read-only): Id of the address
- `industryCode` (string): Code of `industries`
- `info` (string): Info text
- `invoiceEmail` (string (email)): E-mail address for invoices (max length 255)
- `isBlocked` (boolean): General block of the address
- `isDiscountEligible` (boolean): Discounts may be granted
- `isEuForeign` (boolean, read-only): Derived like `isForeign` (both countries in the EU)
- `isForeign` (boolean, read-only): Derived on every write from the billing country (default billing postal address, else the first one) and the tenant country; ignored on write
- `isOneTime` (boolean): One-time account (Diverse)
- `isTaxInclusive` (boolean): Prices are gross (tax inclusive)
- `languageCode` (string): ISO 639-1, optionally with region
- `lastName` (string): Last name (required for `partyType` PERSON) (max length 128)
- `legalForm` (string): Legal form (max length 64)
- `marketingObjection` (boolean): Objection to advertising
- `marketingObjectionAt` (string (date-time), nullable, read-only): Set by the server when `marketingObjection` turns true
- `memo` (string): Internal memo
- `mergedIntoId` (string (uuid), read-only): Set when the address was merged into another one
- `mobile` (string): E.164 (max length 64)
- `netDays` (integer, nullable): Payment term in days (net)
- `ourCustomerNumber` (string): Our customer number at this party (max length 64)
- `parentAddressId` (string (uuid)): Parent company (another address of the tenant; no cycles)
- `parentName` (string, read-only): Display name of the parent address (set on read)
- `partyType` (string): COMPANY needs `companyName`, PERSON needs `lastName` (one of `COMPANY`, `PERSON`; default `"COMPANY"`)
- `paymentBlockReason` (string, read-only): Reason of the payment block
- `paymentBlocked` (boolean, read-only): Payment block (set with `POST /addresses/{id}/blocks`; a PUT keeps it)
- `paymentBlockedAt` (string (date-time), read-only): Time of the payment block
- `paymentBlockedBy` (string, read-only): Actor of the payment block
- `paymentMethodCode` (string): Code of `payment-methods`
- `paymentTermCode` (string): Code of `payment-terms`
- `peppolId` (string): Peppol participant ID `scheme:id`
- `phone` (string): E.164 (+4989123456). Input is normalised with the country of the default billing postal address, else of the tenant profile, else DE; extensions are dropped; a changed value that cannot be parsed answers 400 (a value equal to the stored one is kept) (max length 64)
- `postalAddresses` (array of PostalAddress): Postal addresses (Anschriften)
  - `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
- `postingAccountNo` (string): Debtor account (Debitorenkonto). With the tenant's `glAccountLength` g it must lie in [10^g, 7*10^g-1] (g=4: 10000-69999); checked only when the value changes, else 400 (max length 32)
- `purchaseOrderEmail` (string (email)): Mail address that receives the purchase orders sent to this supplier; empty falls back to `email` (max length 254)
- `purchaseOrderRequired` (boolean, nullable): Invoices of this supplier need a purchase order. Omitted: `true` on create, unchanged on update
- `registerCourt` (string): Register court (max length 128)
- `reverseCharge` (boolean): Reverse charge (§13b UStG)
- `roles` (array of string, read-only): Derived from the flags of the status (`isCustomer` CUSTOMER, `isVendor` SUPPLIER, `isLead` PROSPECT, `isPartner` PARTNER); a value in the request is ignored
- `salesRepCommissionRate` (number, nullable): Commission of the sales representative in percent (max 100)
- `salesRepNo` (string): Number of the sales representative (max length 32)
- `salutationCode` (string): Code of `salutations`
- `searchTerm` (string): Search term (Suchbegriff); derived from the name when empty (max length 255)
- `sepaMandates` (array of SepaMandate): SEPA direct debit mandates
  - `bankAccountIban` (string, required): IBAN of a bank account of this address
  - `signedAt` (string (date), required): Date of signature (YYYY-MM-DD)
  - `bankAccountId` (string (uuid), read-only): Id of the linked bank account
  - `creditorId` (string): Creditor identifier (max length 35)
  - `id` (string (uuid)): Id of the mandate
  - `lastUsedAt` (string (date), nullable): Set when a collection uses the mandate. A mandate with lastUsedAt cannot be deleted, also not together with its bank account: a PUT that omits it answers 409; revoke it with status REVOKED instead
  - `mandateReference` (string): Assigned from the MANDATE range when empty
  - `mandateType` (string): CORE or B2B direct debit (one of `CORE`, `B2B`; default `"CORE"`)
  - `revokedAt` (string (date), nullable): Set by the server for status REVOKED (the first stamp stays; a client value is ignored)
  - `sequenceType` (string): Sequence type of the next collection (one of `FRST`, `RCUR`, `OOFF`, `FNAL`; default `"FRST"`)
  - `status` (string): State of the mandate (one of `ACTIVE`, `REVOKED`, `EXPIRED`; default `"ACTIVE"`)
  - `validFrom` (string (date), nullable): Valid from (YYYY-MM-DD)
- `shippingTypeCode` (string): Code of `shipping-types`
- `skontoDays1` (integer, nullable): Days for the first cash discount
- `skontoDays2` (integer, nullable): Days for the second cash discount
- `skontoRate1` (number, nullable): First cash discount in percent (max 100)
- `skontoRate2` (number, nullable): Second cash discount in percent (max 100)
- `smallBusiness` (boolean): Small business (§19 UStG)
- `source` (string): Where the address came from (lead source) (max length 64)
- `supplierNumber` (string): Supplier number (Lieferantennummer), unique among the live addresses of the tenant (`409` `supplier_number_taken`). Empty on an address with the role SUPPLIER: the address number (adrNr) is used while no other address has it as supplier number (max length 64)
- `syncStatus` (string, read-only): Reserved for an ERP synchronisation; STANDALONE for records of this API (one of `STANDALONE`, `PENDING_CREATION`, `PENDING_UPDATE`, `SYNCED`, `CONFLICT`, `ERROR`)
- `tags` (array of string): Duplicates (case-insensitive) are removed
- `taxNumber` (string): Tax number (Steuernummer) (max length 64)
- `taxZone` (string, read-only): Derived on every write: DOMESTIC (billing country = tenant country), EU_VATID (EU with `vatId`), EU_PRIVATE (EU without `vatId`), THIRD_COUNTRY; empty without a postal address. Ignored on write. `vatCategory` stays for compatibility (one of `DOMESTIC`, `EU_VATID`, `EU_PRIVATE`, `THIRD_COUNTRY`)
- `tenantName` (string, read-only): Tenant name (from the token)
- `title` (string): Title of the party (e.g. Dr.) (max length 64)
- `updatedAt` (string (date-time), read-only): Time of the last change
- `updatedBy` (string, read-only): Who changed the address last (subject of the token)
- `valutaDays` (integer, nullable): Value date days
- `vatCategory` (integer): VAT category (microtech) (max 9)
- `vatCheckStatus` (VatCheckStatus, read-only): Result of the latest official VAT check (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`, `NOT_CHECKED`)
- `vatCheckedAt` (string (date-time), read-only): Time of the latest official VAT check
- `vatId` (string): VAT ID (USt-IdNr.)
- `website` (string (uri)): Website (max length 255)

Example 200 answer:

```json
{
  "accountOwner": "Lena Vogel",
  "accountType": "INDIVIDUAL",
  "adrNr": "10001",
  "bankAccounts": [
    {
      "accountHolder": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "bankName": "Commerzbank",
      "bic": "COBADEFFXXX",
      "iban": "DE89370400440532013000",
      "id": "4e6a8c0e-2a4b-4d6f-8a0c-2e4a6b8d0f2a",
      "isDefault": true
    }
  ],
  "commercialRegister": "HRA 4711",
  "companyName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "contactPersons": [
    {
      "aspNr": 1,
      "email1": "georg.moser@alpenhotel-seeblick.example",
      "firstName": "Georg",
      "gdprConsent": "UNKNOWN",
      "id": "6a8c0e2a-4b6d-4f8a-9c0e-2a4b6d8f0a2c",
      "isActive": true,
      "isDefault": true,
      "lastName": "Moser",
      "letterSalutation": "Sehr geehrter Herr Moser",
      "phone1": "+49865298760",
      "position": "Geschäftsführer",
      "postalAddressAnsNr": 1,
      "roles": [
        "DECISION_MAKER"
      ],
      "salutationCode": "HERR",
      "version": 1
    },
    {
      "aspNr": 2,
      "availableFrom1": "08:00",
      "availableTo1": "16:00",
      "customFields": {},
      "doNotCall": false,
      "email1": "katrin.stadler@alpenhotel-seeblick.example",
      "emailOptOut": false,
      "firstName": "Katrin",
      "gdprConsent": "UNKNOWN",
      "id": "8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a",
      "isActive": true,
      "isBlocked": false,
      "isDefault": false,
      "languageCode": "de",
      "lastName": "Stadler",
      "letterSalutation": "Sehr geehrte Frau Stadler",
      "phone1": "+498652987612",
      "position": "Empfangsleitung und IT",
      "postalAddressAnsNr": 1,
      "preferredChannel": "PHONE",
      "roles": [
        "TECHNICAL",
        "SUPPORT"
      ],
      "salutationCode": "FRAU",
      "timezone": "Europe/Berlin",
      "version": 3
    }
  ],
  "createdAt": "2026-01-02T08:00:00Z",
  "createdBy": "laura.kaestner@muster-it.example",
  "currencyCode": "EUR",
  "customFields": {
    "branche": "hotel"
  },
  "customerNo": "99999",
  "customerNumber": "10001",
  "customerSince": "2019-04-01",
  "dataQualityScore": 90,
  "deliveryBlocked": false,
  "displayName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "distributorIds": [
    {
      "addressId": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
      "addressName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "adrNr": "10001",
      "distributorId": "700123",
      "distributorName": "EGIS Computer Service-Center GmbH",
      "source": "egis",
      "updatedAt": "2026-05-20T11:40:00Z"
    }
  ],
  "dunningBlocked": false,
  "eInvoiceFormat": "ZUGFERD",
  "email": "rezeption@alpenhotel-seeblick.example",
  "employeeCount": 38,
  "enrichmentStatus": "NOT_ENRICHED",
  "gdprConsent": "UNKNOWN",
  "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
  "invoiceEmail": "buchhaltung@alpenhotel-seeblick.example",
  "isBlocked": false,
  "isDiscountEligible": true,
  "isEuForeign": false,
  "isForeign": false,
  "isOneTime": false,
  "isTaxInclusive": false,
  "languageCode": "de",
  "legalForm": "GmbH \u0026 Co. KG",
  "marketingObjection": false,
  "netDays": 30,
  "partyType": "COMPANY",
  "paymentBlocked": false,
  "paymentMethodCode": "UEBERWEISUNG",
  "paymentTermCode": "NETTO30",
  "phone": "+49865298760",
  "postalAddresses": [
    {
      "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
    }
  ],
  "postingAccountNo": "10001",
  "registerCourt": "Amtsgericht Traunstein",
  "reverseCharge": false,
  "roles": [
    "CUSTOMER"
  ],
  "searchTerm": "ALPENHOTEL SEEBLICK",
  "sepaMandates": [],
  "smallBusiness": false,
  "statusCode": "KUNDE",
  "syncStatus": "STANDALONE",
  "tags": [
    "Wartungsvertrag"
  ],
  "taxZone": "DOMESTIC",
  "tenantName": "DEMO",
  "updatedAt": "2026-11-03T09:14:22Z",
  "updatedBy": "christina.adler@muster-it.example",
  "vatCheckStatus": "OFFICIALLY_CONFIRMED",
  "vatCheckedAt": "2026-11-03T09:14:22Z",
  "vatId": "DE811234567",
  "version": 7,
  "website": "https://www.alpenhotel-seeblick.example"
}
```

### Example request

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

## Replace an address (tenant:masterdata:write)

`PUT /api/masterdata/addresses/{id}`

Module: Master data · operationId: `updateAddress` · Tag: Addresses · Auth: access token (`Authorization: Bearer <accessToken>`)

Replaces the aggregate, including `postalAddresses`, `contactPersons`, `bankAccounts` and
`sepaMandates` (send them all; children with a known `id` keep it). `version` must match the
stored version. An empty `adrNr` keeps the current number; omitted `customFields` keep the
stored values, a `null` value removes a key; omitted `purchaseOrderRequired` keeps the stored
value. A taken `customerNumber` or `supplierNumber` answers `409` as on create. Emits `masterdata.address.updated`.

### Parameters

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

### Request body

`application/json` (required)

- `statusCode` (string, required): Code of `address-statuses` (required). Its flags decide the `roles`
- `version` (integer, required): Optimistic locking version; send the version you read (ignored on create)
- `accountOwner` (string): Account owner (responsible person) in CRM (max length 255)
- `accountType` (string): Individual or collective account (one of `INDIVIDUAL`, `COLLECTIVE`; default `"INDIVIDUAL"`)
- `additionalName` (string): Name addition (second name line) (max length 255)
- `adrNr` (string): Address number, unique per tenant; assigned from the ADDRESS range when empty (max length 32)
- `annualRevenue` (number, nullable): Annual revenue
- `bankAccounts` (array of BankAccount): Bank accounts
  - `iban` (string, required): Unique per address
  - `accountHolder` (string): Account holder (max length 255)
  - `bankName` (string): Name of the bank (max length 128)
  - `bic` (string): BIC
  - `id` (string (uuid)): Id of the bank account
  - `isDefault` (boolean): At most one; the first account is the default when none is set
- `blockReason` (string): Cleared when `isBlocked` is false (max length 255)
- `blockedAt` (string (date-time), read-only): Time of the general block
- `blockedBy` (string, read-only): Actor of the general block
- `commercialRegister` (string): Commercial register number (Handelsregister) (max length 128)
- `companyName` (string): Company name (required for `partyType` COMPANY) (max length 255)
- `contactPersons` (array of ContactPerson): Contact persons (Ansprechpartner)
  - `aspNr` (integer): Number within the address; assigned
  - `availableFrom1` (string, nullable): Reachable from (HH:MM)
  - `availableFrom2` (string, nullable): Second time window: reachable from (HH:MM)
  - `availableTo1` (string, nullable): After `availableFrom1`
  - `availableTo2` (string, nullable): After `availableFrom2`
  - `birthday` (string (date), nullable): Birthday (YYYY-MM-DD)
  - `blockReason` (string, read-only): Reason of the block
  - `blockedAt` (string (date-time), read-only): Time of the block
  - `blockedBy` (string, read-only): Actor of the block
  - `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`.
  - `department` (string): Department
  - `doNotCall` (boolean): Do not call
  - `email1` (string (email)): First e-mail address
  - `email2` (string (email)): Second e-mail address
  - `emailOptOut` (boolean): No marketing e-mails
  - `fax` (string): E.164
  - `firstName` (string): First name (max length 128)
  - `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
  - `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
  - `id` (string (uuid)): Id of the contact person
  - `info` (string): Info text
  - `isActive` (boolean): False when `leftAt` is set (default `true`)
  - `isBlocked` (boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set with `POST /addresses/{id}/contacts/{cid}/block`
  - `isDefault` (boolean): Default contact of the address (at most one)
  - `languageCode` (string): Language (ISO 639-1)
  - `lastName` (string): Last name (max length 128)
  - `leftAt` (string (date), nullable): Date the person left the company; sets `isActive` false
  - `letterSalutation` (string): Salutation line of letters
  - `linkedinUrl` (string (uri)): LinkedIn profile (max length 255)
  - `mobile` (string): E.164
  - `namePrefix` (string): Name prefix
  - `nameSuffix` (string): Name suffix
  - `phone1` (string): E.164
  - `phone2` (string): E.164
  - `portalUserId` (string): Linked desk portal user (max length 255)
  - `position` (string): Position
  - `postalAddressAnsNr` (integer, nullable): `ansNr` of a postal address of the same address
  - `preferredChannel` (string): Preferred contact channel (one of `EMAIL`, `PHONE`, `MOBILE`, `LETTER`, `PORTAL`)
  - `reportsToAspNr` (integer, nullable): `aspNr` of the manager within the same address (no cycles)
  - `roles` (array of string): Roles in the buying centre or for ticket routing
  - `salutationCode` (string): Code of `salutations`
  - `timezone` (string): IANA time zone
  - `title` (string): Title
  - `version` (integer): Version of this contact (child updates)
- `createdAt` (string (date-time), read-only): Creation time
- `createdBy` (string, read-only): Who created the address (subject of the token)
- `creditLimit` (number, nullable): Credit limit
- `creditorAccountNo` (string): Creditor account. With `glAccountLength` g it must lie in [7*10^g, 10^(g+1)-1] (g=4: 70000-99999); checked only when the value changes, else 400 (max length 32)
- `currencyCode` (string): ISO 4217
- `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`.
- `customerNo` (string, read-only): Tenant customer number (from the token)
- `customerNumber` (string): Customer number (Kundennummer), unique among the live addresses of the tenant (`409` `customer_number_taken`). Empty on an address with the role CUSTOMER: the address number (adrNr) is used while no other address has it as customer number, except in the platform operator tenant (max length 64)
- `customerSince` (string (date), nullable): Customer since (YYYY-MM-DD)
- `dataQualityScore` (integer, read-only): Completeness score computed on save (max 100)
- `deletionBlockedUntil` (string (date), nullable): Deleting the address or merging it away (as source) through this date (inclusive) answers 409 (Löschsperre bis TT.MM.JJJJ); a merge keeps the later date of both addresses
- `deliveryBlockReason` (string, read-only): Reason of the delivery block
- `deliveryBlocked` (boolean, read-only): Delivery block (set with `POST /addresses/{id}/blocks`; a PUT keeps it)
- `deliveryBlockedAt` (string (date-time), read-only): Time of the delivery block
- `deliveryBlockedBy` (string, read-only): Actor of the delivery block
- `deliveryCondition` (string): Delivery condition (free text) (max length 255)
- `discountRate` (number, nullable): Discount in percent (max 100)
- `displayName` (string, read-only): Company name, else first and last name
- `distributorIds` (array of DistributorID, read-only): Maintained via /api/masterdata/distributor-ids
  - `addressId` (string (uuid), required): Supplier address the distributor ID maps to
  - `addressName` (string, required): Display name of that address
  - `adrNr` (string, required): Address number of that address
  - `distributorId` (string, required): The distributor's own ID
  - `source` (string, required): Distributor (lower case, e.g. egis, ingram)
  - `updatedAt` (string (date-time), required): Time of the last change
  - `distributorName` (string): Name of the distributor
- `dunningBlocked` (boolean): Dunning block (also set with `POST /addresses/{id}/blocks`, type DUNNING)
- `dunningBlockedAt` (string (date-time), read-only): Time of the dunning block
- `dunningBlockedBy` (string, read-only): Actor of the dunning block
- `eInvoiceBuyerRef` (string): Leitweg-ID (XRechnung buyer reference)
- `eInvoiceFormat` (string): Preferred e-invoice format (one of `XRECHNUNG`, `ZUGFERD`, `PEPPOL`, `PDF`)
- `email` (string (email)): Main e-mail address (max length 255)
- `employeeCount` (integer, nullable): Number of employees
- `enrichedAt` (string (date-time), read-only): Time of the last enrichment
- `enrichmentData` (any): Free JSON of an enrichment
- `enrichmentStatus` (string): State of the data enrichment (one of `NOT_ENRICHED`, `PENDING`, `ENRICHED`, `FAILED`; default `"NOT_ENRICHED"`)
- `externalIds` (object): Keys of other systems, at most 20; key `^[a-z0-9_-]{1,64}$`, value max. 255 characters
- `fax` (string): E.164 (max length 64)
- `firstName` (string): First name (of a person) (max length 128)
- `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
- `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
- `gdprDataOrigin` (string): GDPR: where the data came from (max length 255)
- `gdprPurpose` (string): GDPR: purpose of the processing (max length 255)
- `gln` (string): Global Location Number with check digit
- `id` (string (uuid), read-only): Id of the address
- `industryCode` (string): Code of `industries`
- `info` (string): Info text
- `invoiceEmail` (string (email)): E-mail address for invoices (max length 255)
- `isBlocked` (boolean): General block of the address
- `isDiscountEligible` (boolean): Discounts may be granted
- `isEuForeign` (boolean, read-only): Derived like `isForeign` (both countries in the EU)
- `isForeign` (boolean, read-only): Derived on every write from the billing country (default billing postal address, else the first one) and the tenant country; ignored on write
- `isOneTime` (boolean): One-time account (Diverse)
- `isTaxInclusive` (boolean): Prices are gross (tax inclusive)
- `languageCode` (string): ISO 639-1, optionally with region
- `lastName` (string): Last name (required for `partyType` PERSON) (max length 128)
- `legalForm` (string): Legal form (max length 64)
- `marketingObjection` (boolean): Objection to advertising
- `marketingObjectionAt` (string (date-time), nullable, read-only): Set by the server when `marketingObjection` turns true
- `memo` (string): Internal memo
- `mergedIntoId` (string (uuid), read-only): Set when the address was merged into another one
- `mobile` (string): E.164 (max length 64)
- `netDays` (integer, nullable): Payment term in days (net)
- `ourCustomerNumber` (string): Our customer number at this party (max length 64)
- `parentAddressId` (string (uuid)): Parent company (another address of the tenant; no cycles)
- `parentName` (string, read-only): Display name of the parent address (set on read)
- `partyType` (string): COMPANY needs `companyName`, PERSON needs `lastName` (one of `COMPANY`, `PERSON`; default `"COMPANY"`)
- `paymentBlockReason` (string, read-only): Reason of the payment block
- `paymentBlocked` (boolean, read-only): Payment block (set with `POST /addresses/{id}/blocks`; a PUT keeps it)
- `paymentBlockedAt` (string (date-time), read-only): Time of the payment block
- `paymentBlockedBy` (string, read-only): Actor of the payment block
- `paymentMethodCode` (string): Code of `payment-methods`
- `paymentTermCode` (string): Code of `payment-terms`
- `peppolId` (string): Peppol participant ID `scheme:id`
- `phone` (string): E.164 (+4989123456). Input is normalised with the country of the default billing postal address, else of the tenant profile, else DE; extensions are dropped; a changed value that cannot be parsed answers 400 (a value equal to the stored one is kept) (max length 64)
- `postalAddresses` (array of PostalAddress): Postal addresses (Anschriften)
  - `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
- `postingAccountNo` (string): Debtor account (Debitorenkonto). With the tenant's `glAccountLength` g it must lie in [10^g, 7*10^g-1] (g=4: 10000-69999); checked only when the value changes, else 400 (max length 32)
- `purchaseOrderEmail` (string (email)): Mail address that receives the purchase orders sent to this supplier; empty falls back to `email` (max length 254)
- `purchaseOrderRequired` (boolean, nullable): Invoices of this supplier need a purchase order. Omitted: `true` on create, unchanged on update
- `registerCourt` (string): Register court (max length 128)
- `reverseCharge` (boolean): Reverse charge (§13b UStG)
- `roles` (array of string, read-only): Derived from the flags of the status (`isCustomer` CUSTOMER, `isVendor` SUPPLIER, `isLead` PROSPECT, `isPartner` PARTNER); a value in the request is ignored
- `salesRepCommissionRate` (number, nullable): Commission of the sales representative in percent (max 100)
- `salesRepNo` (string): Number of the sales representative (max length 32)
- `salutationCode` (string): Code of `salutations`
- `searchTerm` (string): Search term (Suchbegriff); derived from the name when empty (max length 255)
- `sepaMandates` (array of SepaMandate): SEPA direct debit mandates
  - `bankAccountIban` (string, required): IBAN of a bank account of this address
  - `signedAt` (string (date), required): Date of signature (YYYY-MM-DD)
  - `bankAccountId` (string (uuid), read-only): Id of the linked bank account
  - `creditorId` (string): Creditor identifier (max length 35)
  - `id` (string (uuid)): Id of the mandate
  - `lastUsedAt` (string (date), nullable): Set when a collection uses the mandate. A mandate with lastUsedAt cannot be deleted, also not together with its bank account: a PUT that omits it answers 409; revoke it with status REVOKED instead
  - `mandateReference` (string): Assigned from the MANDATE range when empty
  - `mandateType` (string): CORE or B2B direct debit (one of `CORE`, `B2B`; default `"CORE"`)
  - `revokedAt` (string (date), nullable): Set by the server for status REVOKED (the first stamp stays; a client value is ignored)
  - `sequenceType` (string): Sequence type of the next collection (one of `FRST`, `RCUR`, `OOFF`, `FNAL`; default `"FRST"`)
  - `status` (string): State of the mandate (one of `ACTIVE`, `REVOKED`, `EXPIRED`; default `"ACTIVE"`)
  - `validFrom` (string (date), nullable): Valid from (YYYY-MM-DD)
- `shippingTypeCode` (string): Code of `shipping-types`
- `skontoDays1` (integer, nullable): Days for the first cash discount
- `skontoDays2` (integer, nullable): Days for the second cash discount
- `skontoRate1` (number, nullable): First cash discount in percent (max 100)
- `skontoRate2` (number, nullable): Second cash discount in percent (max 100)
- `smallBusiness` (boolean): Small business (§19 UStG)
- `source` (string): Where the address came from (lead source) (max length 64)
- `supplierNumber` (string): Supplier number (Lieferantennummer), unique among the live addresses of the tenant (`409` `supplier_number_taken`). Empty on an address with the role SUPPLIER: the address number (adrNr) is used while no other address has it as supplier number (max length 64)
- `syncStatus` (string, read-only): Reserved for an ERP synchronisation; STANDALONE for records of this API (one of `STANDALONE`, `PENDING_CREATION`, `PENDING_UPDATE`, `SYNCED`, `CONFLICT`, `ERROR`)
- `tags` (array of string): Duplicates (case-insensitive) are removed
- `taxNumber` (string): Tax number (Steuernummer) (max length 64)
- `taxZone` (string, read-only): Derived on every write: DOMESTIC (billing country = tenant country), EU_VATID (EU with `vatId`), EU_PRIVATE (EU without `vatId`), THIRD_COUNTRY; empty without a postal address. Ignored on write. `vatCategory` stays for compatibility (one of `DOMESTIC`, `EU_VATID`, `EU_PRIVATE`, `THIRD_COUNTRY`)
- `tenantName` (string, read-only): Tenant name (from the token)
- `title` (string): Title of the party (e.g. Dr.) (max length 64)
- `updatedAt` (string (date-time), read-only): Time of the last change
- `updatedBy` (string, read-only): Who changed the address last (subject of the token)
- `valutaDays` (integer, nullable): Value date days
- `vatCategory` (integer): VAT category (microtech) (max 9)
- `vatCheckStatus` (VatCheckStatus, read-only): Result of the latest official VAT check (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`, `NOT_CHECKED`)
- `vatCheckedAt` (string (date-time), read-only): Time of the latest official VAT check
- `vatId` (string): VAT ID (USt-IdNr.)
- `website` (string (uri)): Website (max length 255)

Example:

```json
{
  "accountOwner": "Lena Vogel",
  "accountType": "INDIVIDUAL",
  "adrNr": "10001",
  "bankAccounts": [
    {
      "accountHolder": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "bankName": "Commerzbank",
      "bic": "COBADEFFXXX",
      "iban": "DE89370400440532013000",
      "id": "4e6a8c0e-2a4b-4d6f-8a0c-2e4a6b8d0f2a",
      "isDefault": true
    }
  ],
  "commercialRegister": "HRA 4711",
  "companyName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "contactPersons": [
    {
      "aspNr": 1,
      "email1": "georg.moser@alpenhotel-seeblick.example",
      "firstName": "Georg",
      "gdprConsent": "UNKNOWN",
      "id": "6a8c0e2a-4b6d-4f8a-9c0e-2a4b6d8f0a2c",
      "isActive": true,
      "isDefault": true,
      "lastName": "Moser",
      "letterSalutation": "Sehr geehrter Herr Moser",
      "phone1": "+49865298760",
      "position": "Geschäftsführer",
      "postalAddressAnsNr": 1,
      "roles": [
        "DECISION_MAKER"
      ],
      "salutationCode": "HERR",
      "version": 1
    },
    {
      "aspNr": 2,
      "availableFrom1": "08:00",
      "availableTo1": "16:00",
      "customFields": {},
      "doNotCall": false,
      "email1": "katrin.stadler@alpenhotel-seeblick.example",
      "emailOptOut": false,
      "firstName": "Katrin",
      "gdprConsent": "UNKNOWN",
      "id": "8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a",
      "isActive": true,
      "isBlocked": false,
      "isDefault": false,
      "languageCode": "de",
      "lastName": "Stadler",
      "letterSalutation": "Sehr geehrte Frau Stadler",
      "phone1": "+498652987612",
      "position": "Empfangsleitung und IT",
      "postalAddressAnsNr": 1,
      "preferredChannel": "PHONE",
      "roles": [
        "TECHNICAL",
        "SUPPORT"
      ],
      "salutationCode": "FRAU",
      "timezone": "Europe/Berlin",
      "version": 3
    }
  ],
  "createdAt": "2026-01-02T08:00:00Z",
  "createdBy": "laura.kaestner@muster-it.example",
  "currencyCode": "EUR",
  "customFields": {
    "branche": "hotel"
  },
  "customerNo": "99999",
  "customerNumber": "10001",
  "customerSince": "2019-04-01",
  "dataQualityScore": 90,
  "deliveryBlocked": false,
  "displayName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "distributorIds": [
    {
      "addressId": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
      "addressName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "adrNr": "10001",
      "distributorId": "700123",
      "distributorName": "EGIS Computer Service-Center GmbH",
      "source": "egis",
      "updatedAt": "2026-05-20T11:40:00Z"
    }
  ],
  "dunningBlocked": false,
  "eInvoiceFormat": "ZUGFERD",
  "email": "rezeption@alpenhotel-seeblick.example",
  "employeeCount": 38,
  "enrichmentStatus": "NOT_ENRICHED",
  "gdprConsent": "UNKNOWN",
  "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
  "invoiceEmail": "buchhaltung@alpenhotel-seeblick.example",
  "isBlocked": false,
  "isDiscountEligible": true,
  "isEuForeign": false,
  "isForeign": false,
  "isOneTime": false,
  "isTaxInclusive": false,
  "languageCode": "de",
  "legalForm": "GmbH \u0026 Co. KG",
  "marketingObjection": false,
  "netDays": 30,
  "partyType": "COMPANY",
  "paymentBlocked": false,
  "paymentMethodCode": "UEBERWEISUNG",
  "paymentTermCode": "NETTO30",
  "phone": "+49865298760",
  "postalAddresses": [
    {
      "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
    }
  ],
  "postingAccountNo": "10001",
  "registerCourt": "Amtsgericht Traunstein",
  "reverseCharge": false,
  "roles": [
    "CUSTOMER"
  ],
  "searchTerm": "ALPENHOTEL SEEBLICK",
  "sepaMandates": [],
  "smallBusiness": false,
  "statusCode": "KUNDE",
  "syncStatus": "STANDALONE",
  "tags": [
    "Wartungsvertrag"
  ],
  "taxZone": "DOMESTIC",
  "tenantName": "DEMO",
  "updatedAt": "2026-11-03T09:14:22Z",
  "updatedBy": "christina.adler@muster-it.example",
  "vatCheckStatus": "OFFICIALLY_CONFIRMED",
  "vatCheckedAt": "2026-11-03T09:14:22Z",
  "vatId": "DE811234567",
  "version": 7,
  "website": "https://www.alpenhotel-seeblick.example"
}
```

### 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:

- `statusCode` (string, required): Code of `address-statuses` (required). Its flags decide the `roles`
- `version` (integer, required): Optimistic locking version; send the version you read (ignored on create)
- `accountOwner` (string): Account owner (responsible person) in CRM (max length 255)
- `accountType` (string): Individual or collective account (one of `INDIVIDUAL`, `COLLECTIVE`; default `"INDIVIDUAL"`)
- `additionalName` (string): Name addition (second name line) (max length 255)
- `adrNr` (string): Address number, unique per tenant; assigned from the ADDRESS range when empty (max length 32)
- `annualRevenue` (number, nullable): Annual revenue
- `bankAccounts` (array of BankAccount): Bank accounts
  - `iban` (string, required): Unique per address
  - `accountHolder` (string): Account holder (max length 255)
  - `bankName` (string): Name of the bank (max length 128)
  - `bic` (string): BIC
  - `id` (string (uuid)): Id of the bank account
  - `isDefault` (boolean): At most one; the first account is the default when none is set
- `blockReason` (string): Cleared when `isBlocked` is false (max length 255)
- `blockedAt` (string (date-time), read-only): Time of the general block
- `blockedBy` (string, read-only): Actor of the general block
- `commercialRegister` (string): Commercial register number (Handelsregister) (max length 128)
- `companyName` (string): Company name (required for `partyType` COMPANY) (max length 255)
- `contactPersons` (array of ContactPerson): Contact persons (Ansprechpartner)
  - `aspNr` (integer): Number within the address; assigned
  - `availableFrom1` (string, nullable): Reachable from (HH:MM)
  - `availableFrom2` (string, nullable): Second time window: reachable from (HH:MM)
  - `availableTo1` (string, nullable): After `availableFrom1`
  - `availableTo2` (string, nullable): After `availableFrom2`
  - `birthday` (string (date), nullable): Birthday (YYYY-MM-DD)
  - `blockReason` (string, read-only): Reason of the block
  - `blockedAt` (string (date-time), read-only): Time of the block
  - `blockedBy` (string, read-only): Actor of the block
  - `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`.
  - `department` (string): Department
  - `doNotCall` (boolean): Do not call
  - `email1` (string (email)): First e-mail address
  - `email2` (string (email)): Second e-mail address
  - `emailOptOut` (boolean): No marketing e-mails
  - `fax` (string): E.164
  - `firstName` (string): First name (max length 128)
  - `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
  - `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
  - `id` (string (uuid)): Id of the contact person
  - `info` (string): Info text
  - `isActive` (boolean): False when `leftAt` is set (default `true`)
  - `isBlocked` (boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set with `POST /addresses/{id}/contacts/{cid}/block`
  - `isDefault` (boolean): Default contact of the address (at most one)
  - `languageCode` (string): Language (ISO 639-1)
  - `lastName` (string): Last name (max length 128)
  - `leftAt` (string (date), nullable): Date the person left the company; sets `isActive` false
  - `letterSalutation` (string): Salutation line of letters
  - `linkedinUrl` (string (uri)): LinkedIn profile (max length 255)
  - `mobile` (string): E.164
  - `namePrefix` (string): Name prefix
  - `nameSuffix` (string): Name suffix
  - `phone1` (string): E.164
  - `phone2` (string): E.164
  - `portalUserId` (string): Linked desk portal user (max length 255)
  - `position` (string): Position
  - `postalAddressAnsNr` (integer, nullable): `ansNr` of a postal address of the same address
  - `preferredChannel` (string): Preferred contact channel (one of `EMAIL`, `PHONE`, `MOBILE`, `LETTER`, `PORTAL`)
  - `reportsToAspNr` (integer, nullable): `aspNr` of the manager within the same address (no cycles)
  - `roles` (array of string): Roles in the buying centre or for ticket routing
  - `salutationCode` (string): Code of `salutations`
  - `timezone` (string): IANA time zone
  - `title` (string): Title
  - `version` (integer): Version of this contact (child updates)
- `createdAt` (string (date-time), read-only): Creation time
- `createdBy` (string, read-only): Who created the address (subject of the token)
- `creditLimit` (number, nullable): Credit limit
- `creditorAccountNo` (string): Creditor account. With `glAccountLength` g it must lie in [7*10^g, 10^(g+1)-1] (g=4: 70000-99999); checked only when the value changes, else 400 (max length 32)
- `currencyCode` (string): ISO 4217
- `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`.
- `customerNo` (string, read-only): Tenant customer number (from the token)
- `customerNumber` (string): Customer number (Kundennummer), unique among the live addresses of the tenant (`409` `customer_number_taken`). Empty on an address with the role CUSTOMER: the address number (adrNr) is used while no other address has it as customer number, except in the platform operator tenant (max length 64)
- `customerSince` (string (date), nullable): Customer since (YYYY-MM-DD)
- `dataQualityScore` (integer, read-only): Completeness score computed on save (max 100)
- `deletionBlockedUntil` (string (date), nullable): Deleting the address or merging it away (as source) through this date (inclusive) answers 409 (Löschsperre bis TT.MM.JJJJ); a merge keeps the later date of both addresses
- `deliveryBlockReason` (string, read-only): Reason of the delivery block
- `deliveryBlocked` (boolean, read-only): Delivery block (set with `POST /addresses/{id}/blocks`; a PUT keeps it)
- `deliveryBlockedAt` (string (date-time), read-only): Time of the delivery block
- `deliveryBlockedBy` (string, read-only): Actor of the delivery block
- `deliveryCondition` (string): Delivery condition (free text) (max length 255)
- `discountRate` (number, nullable): Discount in percent (max 100)
- `displayName` (string, read-only): Company name, else first and last name
- `distributorIds` (array of DistributorID, read-only): Maintained via /api/masterdata/distributor-ids
  - `addressId` (string (uuid), required): Supplier address the distributor ID maps to
  - `addressName` (string, required): Display name of that address
  - `adrNr` (string, required): Address number of that address
  - `distributorId` (string, required): The distributor's own ID
  - `source` (string, required): Distributor (lower case, e.g. egis, ingram)
  - `updatedAt` (string (date-time), required): Time of the last change
  - `distributorName` (string): Name of the distributor
- `dunningBlocked` (boolean): Dunning block (also set with `POST /addresses/{id}/blocks`, type DUNNING)
- `dunningBlockedAt` (string (date-time), read-only): Time of the dunning block
- `dunningBlockedBy` (string, read-only): Actor of the dunning block
- `eInvoiceBuyerRef` (string): Leitweg-ID (XRechnung buyer reference)
- `eInvoiceFormat` (string): Preferred e-invoice format (one of `XRECHNUNG`, `ZUGFERD`, `PEPPOL`, `PDF`)
- `email` (string (email)): Main e-mail address (max length 255)
- `employeeCount` (integer, nullable): Number of employees
- `enrichedAt` (string (date-time), read-only): Time of the last enrichment
- `enrichmentData` (any): Free JSON of an enrichment
- `enrichmentStatus` (string): State of the data enrichment (one of `NOT_ENRICHED`, `PENDING`, `ENRICHED`, `FAILED`; default `"NOT_ENRICHED"`)
- `externalIds` (object): Keys of other systems, at most 20; key `^[a-z0-9_-]{1,64}$`, value max. 255 characters
- `fax` (string): E.164 (max length 64)
- `firstName` (string): First name (of a person) (max length 128)
- `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
- `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
- `gdprDataOrigin` (string): GDPR: where the data came from (max length 255)
- `gdprPurpose` (string): GDPR: purpose of the processing (max length 255)
- `gln` (string): Global Location Number with check digit
- `id` (string (uuid), read-only): Id of the address
- `industryCode` (string): Code of `industries`
- `info` (string): Info text
- `invoiceEmail` (string (email)): E-mail address for invoices (max length 255)
- `isBlocked` (boolean): General block of the address
- `isDiscountEligible` (boolean): Discounts may be granted
- `isEuForeign` (boolean, read-only): Derived like `isForeign` (both countries in the EU)
- `isForeign` (boolean, read-only): Derived on every write from the billing country (default billing postal address, else the first one) and the tenant country; ignored on write
- `isOneTime` (boolean): One-time account (Diverse)
- `isTaxInclusive` (boolean): Prices are gross (tax inclusive)
- `languageCode` (string): ISO 639-1, optionally with region
- `lastName` (string): Last name (required for `partyType` PERSON) (max length 128)
- `legalForm` (string): Legal form (max length 64)
- `marketingObjection` (boolean): Objection to advertising
- `marketingObjectionAt` (string (date-time), nullable, read-only): Set by the server when `marketingObjection` turns true
- `memo` (string): Internal memo
- `mergedIntoId` (string (uuid), read-only): Set when the address was merged into another one
- `mobile` (string): E.164 (max length 64)
- `netDays` (integer, nullable): Payment term in days (net)
- `ourCustomerNumber` (string): Our customer number at this party (max length 64)
- `parentAddressId` (string (uuid)): Parent company (another address of the tenant; no cycles)
- `parentName` (string, read-only): Display name of the parent address (set on read)
- `partyType` (string): COMPANY needs `companyName`, PERSON needs `lastName` (one of `COMPANY`, `PERSON`; default `"COMPANY"`)
- `paymentBlockReason` (string, read-only): Reason of the payment block
- `paymentBlocked` (boolean, read-only): Payment block (set with `POST /addresses/{id}/blocks`; a PUT keeps it)
- `paymentBlockedAt` (string (date-time), read-only): Time of the payment block
- `paymentBlockedBy` (string, read-only): Actor of the payment block
- `paymentMethodCode` (string): Code of `payment-methods`
- `paymentTermCode` (string): Code of `payment-terms`
- `peppolId` (string): Peppol participant ID `scheme:id`
- `phone` (string): E.164 (+4989123456). Input is normalised with the country of the default billing postal address, else of the tenant profile, else DE; extensions are dropped; a changed value that cannot be parsed answers 400 (a value equal to the stored one is kept) (max length 64)
- `postalAddresses` (array of PostalAddress): Postal addresses (Anschriften)
  - `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
- `postingAccountNo` (string): Debtor account (Debitorenkonto). With the tenant's `glAccountLength` g it must lie in [10^g, 7*10^g-1] (g=4: 10000-69999); checked only when the value changes, else 400 (max length 32)
- `purchaseOrderEmail` (string (email)): Mail address that receives the purchase orders sent to this supplier; empty falls back to `email` (max length 254)
- `purchaseOrderRequired` (boolean, nullable): Invoices of this supplier need a purchase order. Omitted: `true` on create, unchanged on update
- `registerCourt` (string): Register court (max length 128)
- `reverseCharge` (boolean): Reverse charge (§13b UStG)
- `roles` (array of string, read-only): Derived from the flags of the status (`isCustomer` CUSTOMER, `isVendor` SUPPLIER, `isLead` PROSPECT, `isPartner` PARTNER); a value in the request is ignored
- `salesRepCommissionRate` (number, nullable): Commission of the sales representative in percent (max 100)
- `salesRepNo` (string): Number of the sales representative (max length 32)
- `salutationCode` (string): Code of `salutations`
- `searchTerm` (string): Search term (Suchbegriff); derived from the name when empty (max length 255)
- `sepaMandates` (array of SepaMandate): SEPA direct debit mandates
  - `bankAccountIban` (string, required): IBAN of a bank account of this address
  - `signedAt` (string (date), required): Date of signature (YYYY-MM-DD)
  - `bankAccountId` (string (uuid), read-only): Id of the linked bank account
  - `creditorId` (string): Creditor identifier (max length 35)
  - `id` (string (uuid)): Id of the mandate
  - `lastUsedAt` (string (date), nullable): Set when a collection uses the mandate. A mandate with lastUsedAt cannot be deleted, also not together with its bank account: a PUT that omits it answers 409; revoke it with status REVOKED instead
  - `mandateReference` (string): Assigned from the MANDATE range when empty
  - `mandateType` (string): CORE or B2B direct debit (one of `CORE`, `B2B`; default `"CORE"`)
  - `revokedAt` (string (date), nullable): Set by the server for status REVOKED (the first stamp stays; a client value is ignored)
  - `sequenceType` (string): Sequence type of the next collection (one of `FRST`, `RCUR`, `OOFF`, `FNAL`; default `"FRST"`)
  - `status` (string): State of the mandate (one of `ACTIVE`, `REVOKED`, `EXPIRED`; default `"ACTIVE"`)
  - `validFrom` (string (date), nullable): Valid from (YYYY-MM-DD)
- `shippingTypeCode` (string): Code of `shipping-types`
- `skontoDays1` (integer, nullable): Days for the first cash discount
- `skontoDays2` (integer, nullable): Days for the second cash discount
- `skontoRate1` (number, nullable): First cash discount in percent (max 100)
- `skontoRate2` (number, nullable): Second cash discount in percent (max 100)
- `smallBusiness` (boolean): Small business (§19 UStG)
- `source` (string): Where the address came from (lead source) (max length 64)
- `supplierNumber` (string): Supplier number (Lieferantennummer), unique among the live addresses of the tenant (`409` `supplier_number_taken`). Empty on an address with the role SUPPLIER: the address number (adrNr) is used while no other address has it as supplier number (max length 64)
- `syncStatus` (string, read-only): Reserved for an ERP synchronisation; STANDALONE for records of this API (one of `STANDALONE`, `PENDING_CREATION`, `PENDING_UPDATE`, `SYNCED`, `CONFLICT`, `ERROR`)
- `tags` (array of string): Duplicates (case-insensitive) are removed
- `taxNumber` (string): Tax number (Steuernummer) (max length 64)
- `taxZone` (string, read-only): Derived on every write: DOMESTIC (billing country = tenant country), EU_VATID (EU with `vatId`), EU_PRIVATE (EU without `vatId`), THIRD_COUNTRY; empty without a postal address. Ignored on write. `vatCategory` stays for compatibility (one of `DOMESTIC`, `EU_VATID`, `EU_PRIVATE`, `THIRD_COUNTRY`)
- `tenantName` (string, read-only): Tenant name (from the token)
- `title` (string): Title of the party (e.g. Dr.) (max length 64)
- `updatedAt` (string (date-time), read-only): Time of the last change
- `updatedBy` (string, read-only): Who changed the address last (subject of the token)
- `valutaDays` (integer, nullable): Value date days
- `vatCategory` (integer): VAT category (microtech) (max 9)
- `vatCheckStatus` (VatCheckStatus, read-only): Result of the latest official VAT check (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`, `NOT_CHECKED`)
- `vatCheckedAt` (string (date-time), read-only): Time of the latest official VAT check
- `vatId` (string): VAT ID (USt-IdNr.)
- `website` (string (uri)): Website (max length 255)

Example 200 answer:

```json
{
  "accountOwner": "Lena Vogel",
  "accountType": "INDIVIDUAL",
  "adrNr": "10001",
  "bankAccounts": [
    {
      "accountHolder": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "bankName": "Commerzbank",
      "bic": "COBADEFFXXX",
      "iban": "DE89370400440532013000",
      "id": "4e6a8c0e-2a4b-4d6f-8a0c-2e4a6b8d0f2a",
      "isDefault": true
    }
  ],
  "commercialRegister": "HRA 4711",
  "companyName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "contactPersons": [
    {
      "aspNr": 1,
      "email1": "georg.moser@alpenhotel-seeblick.example",
      "firstName": "Georg",
      "gdprConsent": "UNKNOWN",
      "id": "6a8c0e2a-4b6d-4f8a-9c0e-2a4b6d8f0a2c",
      "isActive": true,
      "isDefault": true,
      "lastName": "Moser",
      "letterSalutation": "Sehr geehrter Herr Moser",
      "phone1": "+49865298760",
      "position": "Geschäftsführer",
      "postalAddressAnsNr": 1,
      "roles": [
        "DECISION_MAKER"
      ],
      "salutationCode": "HERR",
      "version": 1
    },
    {
      "aspNr": 2,
      "availableFrom1": "08:00",
      "availableTo1": "16:00",
      "customFields": {},
      "doNotCall": false,
      "email1": "katrin.stadler@alpenhotel-seeblick.example",
      "emailOptOut": false,
      "firstName": "Katrin",
      "gdprConsent": "UNKNOWN",
      "id": "8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a",
      "isActive": true,
      "isBlocked": false,
      "isDefault": false,
      "languageCode": "de",
      "lastName": "Stadler",
      "letterSalutation": "Sehr geehrte Frau Stadler",
      "phone1": "+498652987612",
      "position": "Empfangsleitung und IT",
      "postalAddressAnsNr": 1,
      "preferredChannel": "PHONE",
      "roles": [
        "TECHNICAL",
        "SUPPORT"
      ],
      "salutationCode": "FRAU",
      "timezone": "Europe/Berlin",
      "version": 3
    }
  ],
  "createdAt": "2026-01-02T08:00:00Z",
  "createdBy": "laura.kaestner@muster-it.example",
  "currencyCode": "EUR",
  "customFields": {
    "branche": "hotel"
  },
  "customerNo": "99999",
  "customerNumber": "10001",
  "customerSince": "2019-04-01",
  "dataQualityScore": 90,
  "deliveryBlocked": false,
  "displayName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "distributorIds": [
    {
      "addressId": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
      "addressName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "adrNr": "10001",
      "distributorId": "700123",
      "distributorName": "EGIS Computer Service-Center GmbH",
      "source": "egis",
      "updatedAt": "2026-05-20T11:40:00Z"
    }
  ],
  "dunningBlocked": false,
  "eInvoiceFormat": "ZUGFERD",
  "email": "rezeption@alpenhotel-seeblick.example",
  "employeeCount": 38,
  "enrichmentStatus": "NOT_ENRICHED",
  "gdprConsent": "UNKNOWN",
  "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
  "invoiceEmail": "buchhaltung@alpenhotel-seeblick.example",
  "isBlocked": false,
  "isDiscountEligible": true,
  "isEuForeign": false,
  "isForeign": false,
  "isOneTime": false,
  "isTaxInclusive": false,
  "languageCode": "de",
  "legalForm": "GmbH \u0026 Co. KG",
  "marketingObjection": false,
  "netDays": 30,
  "partyType": "COMPANY",
  "paymentBlocked": false,
  "paymentMethodCode": "UEBERWEISUNG",
  "paymentTermCode": "NETTO30",
  "phone": "+49865298760",
  "postalAddresses": [
    {
      "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
    }
  ],
  "postingAccountNo": "10001",
  "registerCourt": "Amtsgericht Traunstein",
  "reverseCharge": false,
  "roles": [
    "CUSTOMER"
  ],
  "searchTerm": "ALPENHOTEL SEEBLICK",
  "sepaMandates": [],
  "smallBusiness": false,
  "statusCode": "KUNDE",
  "syncStatus": "STANDALONE",
  "tags": [
    "Wartungsvertrag"
  ],
  "taxZone": "DOMESTIC",
  "tenantName": "DEMO",
  "updatedAt": "2026-11-03T09:14:22Z",
  "updatedBy": "christina.adler@muster-it.example",
  "vatCheckStatus": "OFFICIALLY_CONFIRMED",
  "vatCheckedAt": "2026-11-03T09:14:22Z",
  "vatId": "DE811234567",
  "version": 7,
  "website": "https://www.alpenhotel-seeblick.example"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"accountOwner":"Lena Vogel","accountType":"INDIVIDUAL","adrNr":"10001","bankAccounts":[{"accountHolder":"Alpenhotel Seeblick GmbH \u0026 Co. KG","bankName":"Commerzbank","bic":"COBADEFFXXX","iban":"DE89370400440532013000","id":"4e6a8c0e-2a4b-4d6f-8a0c-2e4a6b8d0f2a","isDefault":true}],"commercialRegister":"HRA 4711","companyName":"Alpenhotel Seeblick GmbH \u0026 Co. KG","contactPersons":[{"aspNr":1,"email1":"georg.moser@alpenhotel-seeblick.example","firstName":"Georg","gdprConsent":"UNKNOWN","id":"6a8c0e2a-4b6d-4f8a-9c0e-2a4b6d8f0a2c","isActive":true,"isDefault":true,"lastName":"Moser","letterSalutation":"Sehr geehrter Herr Moser","phone1":"+49865298760","position":"Geschäftsführer","postalAddressAnsNr":1,"roles":["DECISION_MAKER"],"salutationCode":"HERR","version":1},{"aspNr":2,"availableFrom1":"08:00","availableTo1":"16:00","customFields":{},"doNotCall":false,"email1":"katrin.stadler@alpenhotel-seeblick.example","emailOptOut":false,"firstName":"Katrin","gdprConsent":"UNKNOWN","id":"8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a","isActive":true,"isBlocked":false,"isDefault":false,"languageCode":"de","lastName":"Stadler","letterSalutation":"Sehr geehrte Frau Stadler","phone1":"+498652987612","position":"Empfangsleitung und IT","postalAddressAnsNr":1,"preferredChannel":"PHONE","roles":["TECHNICAL","SUPPORT"],"salutationCode":"FRAU","timezone":"Europe/Berlin","version":3}],"createdAt":"2026-01-02T08:00:00Z","createdBy":"laura.kaestner@muster-it.example","currencyCode":"EUR","customFields":{"branche":"hotel"},"customerNo":"99999","customerNumber":"10001","customerSince":"2019-04-01","dataQualityScore":90,"deliveryBlocked":false,"displayName":"Alpenhotel Seeblick GmbH \u0026 Co. KG","distributorIds":[{"addressId":"3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e","addressName":"Alpenhotel Seeblick GmbH \u0026 Co. KG","adrNr":"10001","distributorId":"700123","distributorName":"EGIS Computer Service-Center GmbH","source":"egis","updatedAt":"2026-05-20T11:40:00Z"}],"dunningBlocked":false,"eInvoiceFormat":"ZUGFERD","email":"rezeption@alpenhotel-seeblick.example","employeeCount":38,"enrichmentStatus":"NOT_ENRICHED","gdprConsent":"UNKNOWN","id":"3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e","invoiceEmail":"buchhaltung@alpenhotel-seeblick.example","isBlocked":false,"isDiscountEligible":true,"isEuForeign":false,"isForeign":false,"isOneTime":false,"isTaxInclusive":false,"languageCode":"de","legalForm":"GmbH \u0026 Co. KG","marketingObjection":false,"netDays":30,"partyType":"COMPANY","paymentBlocked":false,"paymentMethodCode":"UEBERWEISUNG","paymentTermCode":"NETTO30","phone":"+49865298760","postalAddresses":[{"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}],"postingAccountNo":"10001","registerCourt":"Amtsgericht Traunstein","reverseCharge":false,"roles":["CUSTOMER"],"searchTerm":"ALPENHOTEL SEEBLICK","sepaMandates":[],"smallBusiness":false,"statusCode":"KUNDE","syncStatus":"STANDALONE","tags":["Wartungsvertrag"],"taxZone":"DOMESTIC","tenantName":"DEMO","updatedAt":"2026-11-03T09:14:22Z","updatedBy":"christina.adler@muster-it.example","vatCheckStatus":"OFFICIALLY_CONFIRMED","vatCheckedAt":"2026-11-03T09:14:22Z","vatId":"DE811234567","version":7,"website":"https://www.alpenhotel-seeblick.example"}'
```

## Delete an address (tenant:masterdata:write)

`DELETE /api/masterdata/addresses/{id}`

Module: Master data · operationId: `deleteAddress` · Tag: Addresses · Auth: access token (`Authorization: Bearer <accessToken>`)

Soft-deletes the address and removes its distributor IDs. An address that is still the
supplier or manufacturer of an article answers `409`. An address whose `deletionBlockedUntil` has not passed (inclusive) answers `409` ("Löschsperre bis TT.MM.JJJJ"). Emits `masterdata.address.deleted`.
The personal data of a deleted address is removed once its grace period has passed (GDPR; 90 days by default,
not while `deletionBlockedUntil` has not passed): names, contact data, notes, tags, custom fields, contact persons,
postal addresses and bank accounts go – a bank account under a SEPA mandate stays without its holder until 14
months after the mandate's last use. Address number, customer and supplier number, a company's name and VAT ID and
the VAT ID check protocol stay. `masterdata.address.deleted` is emitted again with `anonymized: true`.

### Parameters

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

### Responses

- **204** Deleted
- **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`)

### Example request

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

## Find possible duplicates of an address (tenant:masterdata:read)

`POST /api/masterdata/addresses:duplicates`

Module: Master data · operationId: `findAddressDuplicates` · Tag: Addresses · Auth: access token (`Authorization: Bearer <accessToken>`)

Checks an address (body as for `POST /api/masterdata/addresses`; nothing is stored) against
the tenant's addresses and returns up to 10 candidates with a score of at least 40 (0–100),
best first. Strong identifiers (VAT ID, IBAN, customer and supplier number, email) count most; a
similar name counts more with the same postal code.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `excludeId` | query | string (uuid) |  | Skip this address (the one being edited) |

### Request body

`application/json` (required)

- `statusCode` (string, required): Code of `address-statuses` (required). Its flags decide the `roles`
- `version` (integer, required): Optimistic locking version; send the version you read (ignored on create)
- `accountOwner` (string): Account owner (responsible person) in CRM (max length 255)
- `accountType` (string): Individual or collective account (one of `INDIVIDUAL`, `COLLECTIVE`; default `"INDIVIDUAL"`)
- `additionalName` (string): Name addition (second name line) (max length 255)
- `adrNr` (string): Address number, unique per tenant; assigned from the ADDRESS range when empty (max length 32)
- `annualRevenue` (number, nullable): Annual revenue
- `bankAccounts` (array of BankAccount): Bank accounts
  - `iban` (string, required): Unique per address
  - `accountHolder` (string): Account holder (max length 255)
  - `bankName` (string): Name of the bank (max length 128)
  - `bic` (string): BIC
  - `id` (string (uuid)): Id of the bank account
  - `isDefault` (boolean): At most one; the first account is the default when none is set
- `blockReason` (string): Cleared when `isBlocked` is false (max length 255)
- `blockedAt` (string (date-time), read-only): Time of the general block
- `blockedBy` (string, read-only): Actor of the general block
- `commercialRegister` (string): Commercial register number (Handelsregister) (max length 128)
- `companyName` (string): Company name (required for `partyType` COMPANY) (max length 255)
- `contactPersons` (array of ContactPerson): Contact persons (Ansprechpartner)
  - `aspNr` (integer): Number within the address; assigned
  - `availableFrom1` (string, nullable): Reachable from (HH:MM)
  - `availableFrom2` (string, nullable): Second time window: reachable from (HH:MM)
  - `availableTo1` (string, nullable): After `availableFrom1`
  - `availableTo2` (string, nullable): After `availableFrom2`
  - `birthday` (string (date), nullable): Birthday (YYYY-MM-DD)
  - `blockReason` (string, read-only): Reason of the block
  - `blockedAt` (string (date-time), read-only): Time of the block
  - `blockedBy` (string, read-only): Actor of the block
  - `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`.
  - `department` (string): Department
  - `doNotCall` (boolean): Do not call
  - `email1` (string (email)): First e-mail address
  - `email2` (string (email)): Second e-mail address
  - `emailOptOut` (boolean): No marketing e-mails
  - `fax` (string): E.164
  - `firstName` (string): First name (max length 128)
  - `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
  - `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
  - `id` (string (uuid)): Id of the contact person
  - `info` (string): Info text
  - `isActive` (boolean): False when `leftAt` is set (default `true`)
  - `isBlocked` (boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set with `POST /addresses/{id}/contacts/{cid}/block`
  - `isDefault` (boolean): Default contact of the address (at most one)
  - `languageCode` (string): Language (ISO 639-1)
  - `lastName` (string): Last name (max length 128)
  - `leftAt` (string (date), nullable): Date the person left the company; sets `isActive` false
  - `letterSalutation` (string): Salutation line of letters
  - `linkedinUrl` (string (uri)): LinkedIn profile (max length 255)
  - `mobile` (string): E.164
  - `namePrefix` (string): Name prefix
  - `nameSuffix` (string): Name suffix
  - `phone1` (string): E.164
  - `phone2` (string): E.164
  - `portalUserId` (string): Linked desk portal user (max length 255)
  - `position` (string): Position
  - `postalAddressAnsNr` (integer, nullable): `ansNr` of a postal address of the same address
  - `preferredChannel` (string): Preferred contact channel (one of `EMAIL`, `PHONE`, `MOBILE`, `LETTER`, `PORTAL`)
  - `reportsToAspNr` (integer, nullable): `aspNr` of the manager within the same address (no cycles)
  - `roles` (array of string): Roles in the buying centre or for ticket routing
  - `salutationCode` (string): Code of `salutations`
  - `timezone` (string): IANA time zone
  - `title` (string): Title
  - `version` (integer): Version of this contact (child updates)
- `createdAt` (string (date-time), read-only): Creation time
- `createdBy` (string, read-only): Who created the address (subject of the token)
- `creditLimit` (number, nullable): Credit limit
- `creditorAccountNo` (string): Creditor account. With `glAccountLength` g it must lie in [7*10^g, 10^(g+1)-1] (g=4: 70000-99999); checked only when the value changes, else 400 (max length 32)
- `currencyCode` (string): ISO 4217
- `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`.
- `customerNo` (string, read-only): Tenant customer number (from the token)
- `customerNumber` (string): Customer number (Kundennummer), unique among the live addresses of the tenant (`409` `customer_number_taken`). Empty on an address with the role CUSTOMER: the address number (adrNr) is used while no other address has it as customer number, except in the platform operator tenant (max length 64)
- `customerSince` (string (date), nullable): Customer since (YYYY-MM-DD)
- `dataQualityScore` (integer, read-only): Completeness score computed on save (max 100)
- `deletionBlockedUntil` (string (date), nullable): Deleting the address or merging it away (as source) through this date (inclusive) answers 409 (Löschsperre bis TT.MM.JJJJ); a merge keeps the later date of both addresses
- `deliveryBlockReason` (string, read-only): Reason of the delivery block
- `deliveryBlocked` (boolean, read-only): Delivery block (set with `POST /addresses/{id}/blocks`; a PUT keeps it)
- `deliveryBlockedAt` (string (date-time), read-only): Time of the delivery block
- `deliveryBlockedBy` (string, read-only): Actor of the delivery block
- `deliveryCondition` (string): Delivery condition (free text) (max length 255)
- `discountRate` (number, nullable): Discount in percent (max 100)
- `displayName` (string, read-only): Company name, else first and last name
- `distributorIds` (array of DistributorID, read-only): Maintained via /api/masterdata/distributor-ids
  - `addressId` (string (uuid), required): Supplier address the distributor ID maps to
  - `addressName` (string, required): Display name of that address
  - `adrNr` (string, required): Address number of that address
  - `distributorId` (string, required): The distributor's own ID
  - `source` (string, required): Distributor (lower case, e.g. egis, ingram)
  - `updatedAt` (string (date-time), required): Time of the last change
  - `distributorName` (string): Name of the distributor
- `dunningBlocked` (boolean): Dunning block (also set with `POST /addresses/{id}/blocks`, type DUNNING)
- `dunningBlockedAt` (string (date-time), read-only): Time of the dunning block
- `dunningBlockedBy` (string, read-only): Actor of the dunning block
- `eInvoiceBuyerRef` (string): Leitweg-ID (XRechnung buyer reference)
- `eInvoiceFormat` (string): Preferred e-invoice format (one of `XRECHNUNG`, `ZUGFERD`, `PEPPOL`, `PDF`)
- `email` (string (email)): Main e-mail address (max length 255)
- `employeeCount` (integer, nullable): Number of employees
- `enrichedAt` (string (date-time), read-only): Time of the last enrichment
- `enrichmentData` (any): Free JSON of an enrichment
- `enrichmentStatus` (string): State of the data enrichment (one of `NOT_ENRICHED`, `PENDING`, `ENRICHED`, `FAILED`; default `"NOT_ENRICHED"`)
- `externalIds` (object): Keys of other systems, at most 20; key `^[a-z0-9_-]{1,64}$`, value max. 255 characters
- `fax` (string): E.164 (max length 64)
- `firstName` (string): First name (of a person) (max length 128)
- `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
- `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
- `gdprDataOrigin` (string): GDPR: where the data came from (max length 255)
- `gdprPurpose` (string): GDPR: purpose of the processing (max length 255)
- `gln` (string): Global Location Number with check digit
- `id` (string (uuid), read-only): Id of the address
- `industryCode` (string): Code of `industries`
- `info` (string): Info text
- `invoiceEmail` (string (email)): E-mail address for invoices (max length 255)
- `isBlocked` (boolean): General block of the address
- `isDiscountEligible` (boolean): Discounts may be granted
- `isEuForeign` (boolean, read-only): Derived like `isForeign` (both countries in the EU)
- `isForeign` (boolean, read-only): Derived on every write from the billing country (default billing postal address, else the first one) and the tenant country; ignored on write
- `isOneTime` (boolean): One-time account (Diverse)
- `isTaxInclusive` (boolean): Prices are gross (tax inclusive)
- `languageCode` (string): ISO 639-1, optionally with region
- `lastName` (string): Last name (required for `partyType` PERSON) (max length 128)
- `legalForm` (string): Legal form (max length 64)
- `marketingObjection` (boolean): Objection to advertising
- `marketingObjectionAt` (string (date-time), nullable, read-only): Set by the server when `marketingObjection` turns true
- `memo` (string): Internal memo
- `mergedIntoId` (string (uuid), read-only): Set when the address was merged into another one
- `mobile` (string): E.164 (max length 64)
- `netDays` (integer, nullable): Payment term in days (net)
- `ourCustomerNumber` (string): Our customer number at this party (max length 64)
- `parentAddressId` (string (uuid)): Parent company (another address of the tenant; no cycles)
- `parentName` (string, read-only): Display name of the parent address (set on read)
- `partyType` (string): COMPANY needs `companyName`, PERSON needs `lastName` (one of `COMPANY`, `PERSON`; default `"COMPANY"`)
- `paymentBlockReason` (string, read-only): Reason of the payment block
- `paymentBlocked` (boolean, read-only): Payment block (set with `POST /addresses/{id}/blocks`; a PUT keeps it)
- `paymentBlockedAt` (string (date-time), read-only): Time of the payment block
- `paymentBlockedBy` (string, read-only): Actor of the payment block
- `paymentMethodCode` (string): Code of `payment-methods`
- `paymentTermCode` (string): Code of `payment-terms`
- `peppolId` (string): Peppol participant ID `scheme:id`
- `phone` (string): E.164 (+4989123456). Input is normalised with the country of the default billing postal address, else of the tenant profile, else DE; extensions are dropped; a changed value that cannot be parsed answers 400 (a value equal to the stored one is kept) (max length 64)
- `postalAddresses` (array of PostalAddress): Postal addresses (Anschriften)
  - `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
- `postingAccountNo` (string): Debtor account (Debitorenkonto). With the tenant's `glAccountLength` g it must lie in [10^g, 7*10^g-1] (g=4: 10000-69999); checked only when the value changes, else 400 (max length 32)
- `purchaseOrderEmail` (string (email)): Mail address that receives the purchase orders sent to this supplier; empty falls back to `email` (max length 254)
- `purchaseOrderRequired` (boolean, nullable): Invoices of this supplier need a purchase order. Omitted: `true` on create, unchanged on update
- `registerCourt` (string): Register court (max length 128)
- `reverseCharge` (boolean): Reverse charge (§13b UStG)
- `roles` (array of string, read-only): Derived from the flags of the status (`isCustomer` CUSTOMER, `isVendor` SUPPLIER, `isLead` PROSPECT, `isPartner` PARTNER); a value in the request is ignored
- `salesRepCommissionRate` (number, nullable): Commission of the sales representative in percent (max 100)
- `salesRepNo` (string): Number of the sales representative (max length 32)
- `salutationCode` (string): Code of `salutations`
- `searchTerm` (string): Search term (Suchbegriff); derived from the name when empty (max length 255)
- `sepaMandates` (array of SepaMandate): SEPA direct debit mandates
  - `bankAccountIban` (string, required): IBAN of a bank account of this address
  - `signedAt` (string (date), required): Date of signature (YYYY-MM-DD)
  - `bankAccountId` (string (uuid), read-only): Id of the linked bank account
  - `creditorId` (string): Creditor identifier (max length 35)
  - `id` (string (uuid)): Id of the mandate
  - `lastUsedAt` (string (date), nullable): Set when a collection uses the mandate. A mandate with lastUsedAt cannot be deleted, also not together with its bank account: a PUT that omits it answers 409; revoke it with status REVOKED instead
  - `mandateReference` (string): Assigned from the MANDATE range when empty
  - `mandateType` (string): CORE or B2B direct debit (one of `CORE`, `B2B`; default `"CORE"`)
  - `revokedAt` (string (date), nullable): Set by the server for status REVOKED (the first stamp stays; a client value is ignored)
  - `sequenceType` (string): Sequence type of the next collection (one of `FRST`, `RCUR`, `OOFF`, `FNAL`; default `"FRST"`)
  - `status` (string): State of the mandate (one of `ACTIVE`, `REVOKED`, `EXPIRED`; default `"ACTIVE"`)
  - `validFrom` (string (date), nullable): Valid from (YYYY-MM-DD)
- `shippingTypeCode` (string): Code of `shipping-types`
- `skontoDays1` (integer, nullable): Days for the first cash discount
- `skontoDays2` (integer, nullable): Days for the second cash discount
- `skontoRate1` (number, nullable): First cash discount in percent (max 100)
- `skontoRate2` (number, nullable): Second cash discount in percent (max 100)
- `smallBusiness` (boolean): Small business (§19 UStG)
- `source` (string): Where the address came from (lead source) (max length 64)
- `supplierNumber` (string): Supplier number (Lieferantennummer), unique among the live addresses of the tenant (`409` `supplier_number_taken`). Empty on an address with the role SUPPLIER: the address number (adrNr) is used while no other address has it as supplier number (max length 64)
- `syncStatus` (string, read-only): Reserved for an ERP synchronisation; STANDALONE for records of this API (one of `STANDALONE`, `PENDING_CREATION`, `PENDING_UPDATE`, `SYNCED`, `CONFLICT`, `ERROR`)
- `tags` (array of string): Duplicates (case-insensitive) are removed
- `taxNumber` (string): Tax number (Steuernummer) (max length 64)
- `taxZone` (string, read-only): Derived on every write: DOMESTIC (billing country = tenant country), EU_VATID (EU with `vatId`), EU_PRIVATE (EU without `vatId`), THIRD_COUNTRY; empty without a postal address. Ignored on write. `vatCategory` stays for compatibility (one of `DOMESTIC`, `EU_VATID`, `EU_PRIVATE`, `THIRD_COUNTRY`)
- `tenantName` (string, read-only): Tenant name (from the token)
- `title` (string): Title of the party (e.g. Dr.) (max length 64)
- `updatedAt` (string (date-time), read-only): Time of the last change
- `updatedBy` (string, read-only): Who changed the address last (subject of the token)
- `valutaDays` (integer, nullable): Value date days
- `vatCategory` (integer): VAT category (microtech) (max 9)
- `vatCheckStatus` (VatCheckStatus, read-only): Result of the latest official VAT check (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`, `NOT_CHECKED`)
- `vatCheckedAt` (string (date-time), read-only): Time of the latest official VAT check
- `vatId` (string): VAT ID (USt-IdNr.)
- `website` (string (uri)): Website (max length 255)

Example:

```json
{
  "bankAccounts": [
    {
      "bankName": "Deutsche Kreditbank",
      "bic": "BYLADEM1001",
      "iban": "DE02120300000000202051",
      "isDefault": true
    }
  ],
  "companyName": "Muster GmbH",
  "contactPersons": [
    {
      "email1": "erika.musterfrau@muster.de",
      "firstName": "Erika",
      "isDefault": true,
      "lastName": "Musterfrau",
      "position": "Leitung Einkauf",
      "roles": [
        "PURCHASING"
      ],
      "salutationCode": "FRAU"
    }
  ],
  "customerNumber": "10023",
  "email": "info@muster.de",
  "legalForm": "GmbH",
  "partyType": "COMPANY",
  "paymentTermCode": "NETTO30",
  "phone": "+49 30 1234567",
  "postalAddresses": [
    {
      "city": "Berlin",
      "countryCode": "DE",
      "isDefaultBilling": true,
      "isDefaultShipping": true,
      "postalCode": "10115",
      "street": "Hauptstraße 1"
    }
  ],
  "statusCode": "KUNDE",
  "tags": [
    "Stammkunde"
  ],
  "vatId": "DE123456789",
  "website": "https://www.muster.de"
}
```

### Responses

- **200** Candidates (`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`)

Fields of the 200 answer:

- `candidates` (array of DuplicateCandidate, required): Up to 10 candidates, best first
  - `adrNr` (string, required): Address number
  - `displayName` (string, required): Display name
  - `id` (string (uuid), required): Id of the existing address
  - `reasons` (array of string, required): Why it may be the same
  - `score` (integer, required): Similarity score (at least 40) (max 100)
  - `city` (string): City of the default billing postal address (else the lowest `ansNr`)

Example 200 answer:

```json
{
  "candidates": [
    {
      "adrNr": "10001",
      "city": "Schönau am Königssee",
      "displayName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
      "reasons": [
        "VAT_ID",
        "EMAIL_DOMAIN",
        "NAME"
      ],
      "score": 95
    }
  ]
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/masterdata/addresses:duplicates' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"bankAccounts":[{"bankName":"Deutsche Kreditbank","bic":"BYLADEM1001","iban":"DE02120300000000202051","isDefault":true}],"companyName":"Muster GmbH","contactPersons":[{"email1":"erika.musterfrau@muster.de","firstName":"Erika","isDefault":true,"lastName":"Musterfrau","position":"Leitung Einkauf","roles":["PURCHASING"],"salutationCode":"FRAU"}],"customerNumber":"10023","email":"info@muster.de","legalForm":"GmbH","partyType":"COMPANY","paymentTermCode":"NETTO30","phone":"+49 30 1234567","postalAddresses":[{"city":"Berlin","countryCode":"DE","isDefaultBilling":true,"isDefaultShipping":true,"postalCode":"10115","street":"Hauptstraße 1"}],"statusCode":"KUNDE","tags":["Stammkunde"],"vatId":"DE123456789","website":"https://www.muster.de"}'
```

## Change status and tags of several addresses (tenant:masterdata:write)

`POST /api/masterdata/addresses:batchUpdate`

Module: Master data · operationId: `batchUpdateAddresses` · Tag: Addresses · Auth: access token (`Authorization: Bearer <accessToken>`)

Sets `statusCode` and/or adds and removes tags on up to 200 addresses. Every id is updated on
its own, exactly like a single `PUT` (status validation, the platform guard that answers `409`
for a customer with active tenants, events and version bump), so one failing id does not stop
the others. The answer is always `200` with one result per id, in request order; a failed id
carries `error.status` (`404` for unknown ids and ids of other tenants, `409`, `400`) and a
German `error.message`.

### Request body

`application/json` (required)

- `ids` (array of string (uuid), required): Addresses to change (each updated on its own)
- `addTags` (array of string): Tags to add
- `removeTags` (array of string): Tags to remove
- `statusCode` (string): New status (lookup `address-statuses`); the roles follow from it

Example:

```json
{
  "addTags": [
    "Messe 2026"
  ],
  "ids": [
    "0b6f6c1e-7d2a-4f0e-9a58-3c1f2b7d9e10"
  ],
  "removeTags": [],
  "statusCode": "INTERESSENT"
}
```

### Responses

- **200** One result per id (`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`)

Fields of the 200 answer:

- `results` (array of object, required): One result per id, in request order
  - `id` (string, required): The id of the request
  - `ok` (boolean, required): The update of this id succeeded
  - `error` (object): Why the update of this id failed (absent when `ok`)
    - `message` (string, required): German message
    - `status` (integer, required): HTTP status the single update would have answered (400, 404, 409)
    - `code` (string): Error code the single update would have answered (`invalid`, `not_found`, `version_conflict`, …)

Example 200 answer:

```json
{
  "results": [
    {
      "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
      "ok": true
    },
    {
      "error": {
        "code": "not_found",
        "message": "Adresse nicht gefunden.",
        "status": 404
      },
      "id": "0b6f6c1e-7d2a-4f0e-9a58-3c1f2b7d9e10",
      "ok": false
    }
  ]
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/masterdata/addresses:batchUpdate' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"addTags":["Messe 2026"],"ids":["0b6f6c1e-7d2a-4f0e-9a58-3c1f2b7d9e10"],"removeTags":[],"statusCode":"INTERESSENT"}'
```

## Merge another address into this one (tenant:masterdata:write)

`POST /api/masterdata/addresses/{id}/merge`

Module: Master data · operationId: `mergeAddress` · Tag: Addresses · Auth: access token (`Authorization: Bearer <accessToken>`)

Moves postal addresses, contact persons, bank accounts, SEPA mandates and article
references of `sourceId` into the address `{id}` (which is kept), fills its empty fields
from the source and replaces the fields listed in `takeFields` with the source values. The
source is soft-deleted and afterwards answers `404` with `code: merged`. Both versions must
match. Emits `masterdata.address.merged`, `masterdata.address.updated` and
`masterdata.address.deleted`. A source whose `deletionBlockedUntil` has not passed (inclusive) answers `409`; a
`customerNumber` or `supplierNumber` the kept address would get that a third live address has answers `409`
`customer_number_taken` / `supplier_number_taken` as on create. The target takes over `marketingObjection` (OR, earliest `marketingObjectionAt`) and the later `deletionBlockedUntil`.

### Parameters

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

### Request body

`application/json` (required)

- `sourceId` (string (uuid), required): The address that is merged and removed
- `sourceVersion` (integer): Version of the source address
- `takeFields` (array of string): Address fields (JSON names) whose source value replaces the target value; empty target fields are always filled
- `targetVersion` (integer): Version of the kept address `{id}`

Example:

```json
{
  "sourceId": "9b2d6e10-5c3a-4f7e-8a1b-0c4d2e6f8a90",
  "sourceVersion": 1,
  "takeFields": [
    "phone"
  ],
  "targetVersion": 3
}
```

### Responses

- **200** The kept address (`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:

- `statusCode` (string, required): Code of `address-statuses` (required). Its flags decide the `roles`
- `version` (integer, required): Optimistic locking version; send the version you read (ignored on create)
- `accountOwner` (string): Account owner (responsible person) in CRM (max length 255)
- `accountType` (string): Individual or collective account (one of `INDIVIDUAL`, `COLLECTIVE`; default `"INDIVIDUAL"`)
- `additionalName` (string): Name addition (second name line) (max length 255)
- `adrNr` (string): Address number, unique per tenant; assigned from the ADDRESS range when empty (max length 32)
- `annualRevenue` (number, nullable): Annual revenue
- `bankAccounts` (array of BankAccount): Bank accounts
  - `iban` (string, required): Unique per address
  - `accountHolder` (string): Account holder (max length 255)
  - `bankName` (string): Name of the bank (max length 128)
  - `bic` (string): BIC
  - `id` (string (uuid)): Id of the bank account
  - `isDefault` (boolean): At most one; the first account is the default when none is set
- `blockReason` (string): Cleared when `isBlocked` is false (max length 255)
- `blockedAt` (string (date-time), read-only): Time of the general block
- `blockedBy` (string, read-only): Actor of the general block
- `commercialRegister` (string): Commercial register number (Handelsregister) (max length 128)
- `companyName` (string): Company name (required for `partyType` COMPANY) (max length 255)
- `contactPersons` (array of ContactPerson): Contact persons (Ansprechpartner)
  - `aspNr` (integer): Number within the address; assigned
  - `availableFrom1` (string, nullable): Reachable from (HH:MM)
  - `availableFrom2` (string, nullable): Second time window: reachable from (HH:MM)
  - `availableTo1` (string, nullable): After `availableFrom1`
  - `availableTo2` (string, nullable): After `availableFrom2`
  - `birthday` (string (date), nullable): Birthday (YYYY-MM-DD)
  - `blockReason` (string, read-only): Reason of the block
  - `blockedAt` (string (date-time), read-only): Time of the block
  - `blockedBy` (string, read-only): Actor of the block
  - `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`.
  - `department` (string): Department
  - `doNotCall` (boolean): Do not call
  - `email1` (string (email)): First e-mail address
  - `email2` (string (email)): Second e-mail address
  - `emailOptOut` (boolean): No marketing e-mails
  - `fax` (string): E.164
  - `firstName` (string): First name (max length 128)
  - `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
  - `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
  - `id` (string (uuid)): Id of the contact person
  - `info` (string): Info text
  - `isActive` (boolean): False when `leftAt` is set (default `true`)
  - `isBlocked` (boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set with `POST /addresses/{id}/contacts/{cid}/block`
  - `isDefault` (boolean): Default contact of the address (at most one)
  - `languageCode` (string): Language (ISO 639-1)
  - `lastName` (string): Last name (max length 128)
  - `leftAt` (string (date), nullable): Date the person left the company; sets `isActive` false
  - `letterSalutation` (string): Salutation line of letters
  - `linkedinUrl` (string (uri)): LinkedIn profile (max length 255)
  - `mobile` (string): E.164
  - `namePrefix` (string): Name prefix
  - `nameSuffix` (string): Name suffix
  - `phone1` (string): E.164
  - `phone2` (string): E.164
  - `portalUserId` (string): Linked desk portal user (max length 255)
  - `position` (string): Position
  - `postalAddressAnsNr` (integer, nullable): `ansNr` of a postal address of the same address
  - `preferredChannel` (string): Preferred contact channel (one of `EMAIL`, `PHONE`, `MOBILE`, `LETTER`, `PORTAL`)
  - `reportsToAspNr` (integer, nullable): `aspNr` of the manager within the same address (no cycles)
  - `roles` (array of string): Roles in the buying centre or for ticket routing
  - `salutationCode` (string): Code of `salutations`
  - `timezone` (string): IANA time zone
  - `title` (string): Title
  - `version` (integer): Version of this contact (child updates)
- `createdAt` (string (date-time), read-only): Creation time
- `createdBy` (string, read-only): Who created the address (subject of the token)
- `creditLimit` (number, nullable): Credit limit
- `creditorAccountNo` (string): Creditor account. With `glAccountLength` g it must lie in [7*10^g, 10^(g+1)-1] (g=4: 70000-99999); checked only when the value changes, else 400 (max length 32)
- `currencyCode` (string): ISO 4217
- `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`.
- `customerNo` (string, read-only): Tenant customer number (from the token)
- `customerNumber` (string): Customer number (Kundennummer), unique among the live addresses of the tenant (`409` `customer_number_taken`). Empty on an address with the role CUSTOMER: the address number (adrNr) is used while no other address has it as customer number, except in the platform operator tenant (max length 64)
- `customerSince` (string (date), nullable): Customer since (YYYY-MM-DD)
- `dataQualityScore` (integer, read-only): Completeness score computed on save (max 100)
- `deletionBlockedUntil` (string (date), nullable): Deleting the address or merging it away (as source) through this date (inclusive) answers 409 (Löschsperre bis TT.MM.JJJJ); a merge keeps the later date of both addresses
- `deliveryBlockReason` (string, read-only): Reason of the delivery block
- `deliveryBlocked` (boolean, read-only): Delivery block (set with `POST /addresses/{id}/blocks`; a PUT keeps it)
- `deliveryBlockedAt` (string (date-time), read-only): Time of the delivery block
- `deliveryBlockedBy` (string, read-only): Actor of the delivery block
- `deliveryCondition` (string): Delivery condition (free text) (max length 255)
- `discountRate` (number, nullable): Discount in percent (max 100)
- `displayName` (string, read-only): Company name, else first and last name
- `distributorIds` (array of DistributorID, read-only): Maintained via /api/masterdata/distributor-ids
  - `addressId` (string (uuid), required): Supplier address the distributor ID maps to
  - `addressName` (string, required): Display name of that address
  - `adrNr` (string, required): Address number of that address
  - `distributorId` (string, required): The distributor's own ID
  - `source` (string, required): Distributor (lower case, e.g. egis, ingram)
  - `updatedAt` (string (date-time), required): Time of the last change
  - `distributorName` (string): Name of the distributor
- `dunningBlocked` (boolean): Dunning block (also set with `POST /addresses/{id}/blocks`, type DUNNING)
- `dunningBlockedAt` (string (date-time), read-only): Time of the dunning block
- `dunningBlockedBy` (string, read-only): Actor of the dunning block
- `eInvoiceBuyerRef` (string): Leitweg-ID (XRechnung buyer reference)
- `eInvoiceFormat` (string): Preferred e-invoice format (one of `XRECHNUNG`, `ZUGFERD`, `PEPPOL`, `PDF`)
- `email` (string (email)): Main e-mail address (max length 255)
- `employeeCount` (integer, nullable): Number of employees
- `enrichedAt` (string (date-time), read-only): Time of the last enrichment
- `enrichmentData` (any): Free JSON of an enrichment
- `enrichmentStatus` (string): State of the data enrichment (one of `NOT_ENRICHED`, `PENDING`, `ENRICHED`, `FAILED`; default `"NOT_ENRICHED"`)
- `externalIds` (object): Keys of other systems, at most 20; key `^[a-z0-9_-]{1,64}$`, value max. 255 characters
- `fax` (string): E.164 (max length 64)
- `firstName` (string): First name (of a person) (max length 128)
- `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
- `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
- `gdprDataOrigin` (string): GDPR: where the data came from (max length 255)
- `gdprPurpose` (string): GDPR: purpose of the processing (max length 255)
- `gln` (string): Global Location Number with check digit
- `id` (string (uuid), read-only): Id of the address
- `industryCode` (string): Code of `industries`
- `info` (string): Info text
- `invoiceEmail` (string (email)): E-mail address for invoices (max length 255)
- `isBlocked` (boolean): General block of the address
- `isDiscountEligible` (boolean): Discounts may be granted
- `isEuForeign` (boolean, read-only): Derived like `isForeign` (both countries in the EU)
- `isForeign` (boolean, read-only): Derived on every write from the billing country (default billing postal address, else the first one) and the tenant country; ignored on write
- `isOneTime` (boolean): One-time account (Diverse)
- `isTaxInclusive` (boolean): Prices are gross (tax inclusive)
- `languageCode` (string): ISO 639-1, optionally with region
- `lastName` (string): Last name (required for `partyType` PERSON) (max length 128)
- `legalForm` (string): Legal form (max length 64)
- `marketingObjection` (boolean): Objection to advertising
- `marketingObjectionAt` (string (date-time), nullable, read-only): Set by the server when `marketingObjection` turns true
- `memo` (string): Internal memo
- `mergedIntoId` (string (uuid), read-only): Set when the address was merged into another one
- `mobile` (string): E.164 (max length 64)
- `netDays` (integer, nullable): Payment term in days (net)
- `ourCustomerNumber` (string): Our customer number at this party (max length 64)
- `parentAddressId` (string (uuid)): Parent company (another address of the tenant; no cycles)
- `parentName` (string, read-only): Display name of the parent address (set on read)
- `partyType` (string): COMPANY needs `companyName`, PERSON needs `lastName` (one of `COMPANY`, `PERSON`; default `"COMPANY"`)
- `paymentBlockReason` (string, read-only): Reason of the payment block
- `paymentBlocked` (boolean, read-only): Payment block (set with `POST /addresses/{id}/blocks`; a PUT keeps it)
- `paymentBlockedAt` (string (date-time), read-only): Time of the payment block
- `paymentBlockedBy` (string, read-only): Actor of the payment block
- `paymentMethodCode` (string): Code of `payment-methods`
- `paymentTermCode` (string): Code of `payment-terms`
- `peppolId` (string): Peppol participant ID `scheme:id`
- `phone` (string): E.164 (+4989123456). Input is normalised with the country of the default billing postal address, else of the tenant profile, else DE; extensions are dropped; a changed value that cannot be parsed answers 400 (a value equal to the stored one is kept) (max length 64)
- `postalAddresses` (array of PostalAddress): Postal addresses (Anschriften)
  - `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
- `postingAccountNo` (string): Debtor account (Debitorenkonto). With the tenant's `glAccountLength` g it must lie in [10^g, 7*10^g-1] (g=4: 10000-69999); checked only when the value changes, else 400 (max length 32)
- `purchaseOrderEmail` (string (email)): Mail address that receives the purchase orders sent to this supplier; empty falls back to `email` (max length 254)
- `purchaseOrderRequired` (boolean, nullable): Invoices of this supplier need a purchase order. Omitted: `true` on create, unchanged on update
- `registerCourt` (string): Register court (max length 128)
- `reverseCharge` (boolean): Reverse charge (§13b UStG)
- `roles` (array of string, read-only): Derived from the flags of the status (`isCustomer` CUSTOMER, `isVendor` SUPPLIER, `isLead` PROSPECT, `isPartner` PARTNER); a value in the request is ignored
- `salesRepCommissionRate` (number, nullable): Commission of the sales representative in percent (max 100)
- `salesRepNo` (string): Number of the sales representative (max length 32)
- `salutationCode` (string): Code of `salutations`
- `searchTerm` (string): Search term (Suchbegriff); derived from the name when empty (max length 255)
- `sepaMandates` (array of SepaMandate): SEPA direct debit mandates
  - `bankAccountIban` (string, required): IBAN of a bank account of this address
  - `signedAt` (string (date), required): Date of signature (YYYY-MM-DD)
  - `bankAccountId` (string (uuid), read-only): Id of the linked bank account
  - `creditorId` (string): Creditor identifier (max length 35)
  - `id` (string (uuid)): Id of the mandate
  - `lastUsedAt` (string (date), nullable): Set when a collection uses the mandate. A mandate with lastUsedAt cannot be deleted, also not together with its bank account: a PUT that omits it answers 409; revoke it with status REVOKED instead
  - `mandateReference` (string): Assigned from the MANDATE range when empty
  - `mandateType` (string): CORE or B2B direct debit (one of `CORE`, `B2B`; default `"CORE"`)
  - `revokedAt` (string (date), nullable): Set by the server for status REVOKED (the first stamp stays; a client value is ignored)
  - `sequenceType` (string): Sequence type of the next collection (one of `FRST`, `RCUR`, `OOFF`, `FNAL`; default `"FRST"`)
  - `status` (string): State of the mandate (one of `ACTIVE`, `REVOKED`, `EXPIRED`; default `"ACTIVE"`)
  - `validFrom` (string (date), nullable): Valid from (YYYY-MM-DD)
- `shippingTypeCode` (string): Code of `shipping-types`
- `skontoDays1` (integer, nullable): Days for the first cash discount
- `skontoDays2` (integer, nullable): Days for the second cash discount
- `skontoRate1` (number, nullable): First cash discount in percent (max 100)
- `skontoRate2` (number, nullable): Second cash discount in percent (max 100)
- `smallBusiness` (boolean): Small business (§19 UStG)
- `source` (string): Where the address came from (lead source) (max length 64)
- `supplierNumber` (string): Supplier number (Lieferantennummer), unique among the live addresses of the tenant (`409` `supplier_number_taken`). Empty on an address with the role SUPPLIER: the address number (adrNr) is used while no other address has it as supplier number (max length 64)
- `syncStatus` (string, read-only): Reserved for an ERP synchronisation; STANDALONE for records of this API (one of `STANDALONE`, `PENDING_CREATION`, `PENDING_UPDATE`, `SYNCED`, `CONFLICT`, `ERROR`)
- `tags` (array of string): Duplicates (case-insensitive) are removed
- `taxNumber` (string): Tax number (Steuernummer) (max length 64)
- `taxZone` (string, read-only): Derived on every write: DOMESTIC (billing country = tenant country), EU_VATID (EU with `vatId`), EU_PRIVATE (EU without `vatId`), THIRD_COUNTRY; empty without a postal address. Ignored on write. `vatCategory` stays for compatibility (one of `DOMESTIC`, `EU_VATID`, `EU_PRIVATE`, `THIRD_COUNTRY`)
- `tenantName` (string, read-only): Tenant name (from the token)
- `title` (string): Title of the party (e.g. Dr.) (max length 64)
- `updatedAt` (string (date-time), read-only): Time of the last change
- `updatedBy` (string, read-only): Who changed the address last (subject of the token)
- `valutaDays` (integer, nullable): Value date days
- `vatCategory` (integer): VAT category (microtech) (max 9)
- `vatCheckStatus` (VatCheckStatus, read-only): Result of the latest official VAT check (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`, `NOT_CHECKED`)
- `vatCheckedAt` (string (date-time), read-only): Time of the latest official VAT check
- `vatId` (string): VAT ID (USt-IdNr.)
- `website` (string (uri)): Website (max length 255)

Example 200 answer:

```json
{
  "accountOwner": "Lena Vogel",
  "accountType": "INDIVIDUAL",
  "adrNr": "10001",
  "bankAccounts": [
    {
      "accountHolder": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "bankName": "Commerzbank",
      "bic": "COBADEFFXXX",
      "iban": "DE89370400440532013000",
      "id": "4e6a8c0e-2a4b-4d6f-8a0c-2e4a6b8d0f2a",
      "isDefault": true
    }
  ],
  "commercialRegister": "HRA 4711",
  "companyName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "contactPersons": [
    {
      "aspNr": 1,
      "email1": "georg.moser@alpenhotel-seeblick.example",
      "firstName": "Georg",
      "gdprConsent": "UNKNOWN",
      "id": "6a8c0e2a-4b6d-4f8a-9c0e-2a4b6d8f0a2c",
      "isActive": true,
      "isDefault": true,
      "lastName": "Moser",
      "letterSalutation": "Sehr geehrter Herr Moser",
      "phone1": "+49865298760",
      "position": "Geschäftsführer",
      "postalAddressAnsNr": 1,
      "roles": [
        "DECISION_MAKER"
      ],
      "salutationCode": "HERR",
      "version": 1
    },
    {
      "aspNr": 2,
      "availableFrom1": "08:00",
      "availableTo1": "16:00",
      "customFields": {},
      "doNotCall": false,
      "email1": "katrin.stadler@alpenhotel-seeblick.example",
      "emailOptOut": false,
      "firstName": "Katrin",
      "gdprConsent": "UNKNOWN",
      "id": "8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a",
      "isActive": true,
      "isBlocked": false,
      "isDefault": false,
      "languageCode": "de",
      "lastName": "Stadler",
      "letterSalutation": "Sehr geehrte Frau Stadler",
      "phone1": "+498652987612",
      "position": "Empfangsleitung und IT",
      "postalAddressAnsNr": 1,
      "preferredChannel": "PHONE",
      "roles": [
        "TECHNICAL",
        "SUPPORT"
      ],
      "salutationCode": "FRAU",
      "timezone": "Europe/Berlin",
      "version": 3
    }
  ],
  "createdAt": "2026-01-02T08:00:00Z",
  "createdBy": "laura.kaestner@muster-it.example",
  "currencyCode": "EUR",
  "customFields": {
    "branche": "hotel"
  },
  "customerNo": "99999",
  "customerNumber": "10001",
  "customerSince": "2019-04-01",
  "dataQualityScore": 90,
  "deliveryBlocked": false,
  "displayName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "distributorIds": [
    {
      "addressId": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
      "addressName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "adrNr": "10001",
      "distributorId": "700123",
      "distributorName": "EGIS Computer Service-Center GmbH",
      "source": "egis",
      "updatedAt": "2026-05-20T11:40:00Z"
    }
  ],
  "dunningBlocked": false,
  "eInvoiceFormat": "ZUGFERD",
  "email": "rezeption@alpenhotel-seeblick.example",
  "employeeCount": 38,
  "enrichmentStatus": "NOT_ENRICHED",
  "gdprConsent": "UNKNOWN",
  "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
  "invoiceEmail": "buchhaltung@alpenhotel-seeblick.example",
  "isBlocked": false,
  "isDiscountEligible": true,
  "isEuForeign": false,
  "isForeign": false,
  "isOneTime": false,
  "isTaxInclusive": false,
  "languageCode": "de",
  "legalForm": "GmbH \u0026 Co. KG",
  "marketingObjection": false,
  "netDays": 30,
  "partyType": "COMPANY",
  "paymentBlocked": false,
  "paymentMethodCode": "UEBERWEISUNG",
  "paymentTermCode": "NETTO30",
  "phone": "+49865298760",
  "postalAddresses": [
    {
      "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
    }
  ],
  "postingAccountNo": "10001",
  "registerCourt": "Amtsgericht Traunstein",
  "reverseCharge": false,
  "roles": [
    "CUSTOMER"
  ],
  "searchTerm": "ALPENHOTEL SEEBLICK",
  "sepaMandates": [],
  "smallBusiness": false,
  "statusCode": "KUNDE",
  "syncStatus": "STANDALONE",
  "tags": [
    "Wartungsvertrag"
  ],
  "taxZone": "DOMESTIC",
  "tenantName": "DEMO",
  "updatedAt": "2026-11-03T09:14:22Z",
  "updatedBy": "christina.adler@muster-it.example",
  "vatCheckStatus": "OFFICIALLY_CONFIRMED",
  "vatCheckedAt": "2026-11-03T09:14:22Z",
  "vatId": "DE811234567",
  "version": 7,
  "website": "https://www.alpenhotel-seeblick.example"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4/merge' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"sourceId":"9b2d6e10-5c3a-4f7e-8a1b-0c4d2e6f8a90","sourceVersion":1,"takeFields":["phone"],"targetVersion":3}'
```

## Block an address (tenant:masterdata:write)

`POST /api/masterdata/addresses/{id}/blocks`

Module: Master data · operationId: `blockAddress` · Tag: Addresses · Auth: access token (`Authorization: Bearer <accessToken>`)

Sets one block: `GENERAL` (`isBlocked`), `PAYMENT`, `DELIVERY` or `DUNNING` (`dunningBlocked`). The reason is required (`400` "Bitte einen Grund angeben.") except for `DUNNING`. Time and actor of an existing block stay, its reason is replaced. Like any change it bumps the version and emits `masterdata.address.updated`. Returns the address.

### Parameters

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

### Request body

`application/json` (required)

- `reason` (string): Required except for `DUNNING` (max length 255)
- `type` (string): Block type of an address (not used for contact persons) (one of `GENERAL`, `PAYMENT`, `DELIVERY`, `DUNNING`)

Example:

```json
{
  "reason": "Zwei Rechnungen über 60 Tage offen",
  "type": "PAYMENT"
}
```

### Responses

- **200** Blocked (`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`)

Fields of the 200 answer:

- `statusCode` (string, required): Code of `address-statuses` (required). Its flags decide the `roles`
- `version` (integer, required): Optimistic locking version; send the version you read (ignored on create)
- `accountOwner` (string): Account owner (responsible person) in CRM (max length 255)
- `accountType` (string): Individual or collective account (one of `INDIVIDUAL`, `COLLECTIVE`; default `"INDIVIDUAL"`)
- `additionalName` (string): Name addition (second name line) (max length 255)
- `adrNr` (string): Address number, unique per tenant; assigned from the ADDRESS range when empty (max length 32)
- `annualRevenue` (number, nullable): Annual revenue
- `bankAccounts` (array of BankAccount): Bank accounts
  - `iban` (string, required): Unique per address
  - `accountHolder` (string): Account holder (max length 255)
  - `bankName` (string): Name of the bank (max length 128)
  - `bic` (string): BIC
  - `id` (string (uuid)): Id of the bank account
  - `isDefault` (boolean): At most one; the first account is the default when none is set
- `blockReason` (string): Cleared when `isBlocked` is false (max length 255)
- `blockedAt` (string (date-time), read-only): Time of the general block
- `blockedBy` (string, read-only): Actor of the general block
- `commercialRegister` (string): Commercial register number (Handelsregister) (max length 128)
- `companyName` (string): Company name (required for `partyType` COMPANY) (max length 255)
- `contactPersons` (array of ContactPerson): Contact persons (Ansprechpartner)
  - `aspNr` (integer): Number within the address; assigned
  - `availableFrom1` (string, nullable): Reachable from (HH:MM)
  - `availableFrom2` (string, nullable): Second time window: reachable from (HH:MM)
  - `availableTo1` (string, nullable): After `availableFrom1`
  - `availableTo2` (string, nullable): After `availableFrom2`
  - `birthday` (string (date), nullable): Birthday (YYYY-MM-DD)
  - `blockReason` (string, read-only): Reason of the block
  - `blockedAt` (string (date-time), read-only): Time of the block
  - `blockedBy` (string, read-only): Actor of the block
  - `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`.
  - `department` (string): Department
  - `doNotCall` (boolean): Do not call
  - `email1` (string (email)): First e-mail address
  - `email2` (string (email)): Second e-mail address
  - `emailOptOut` (boolean): No marketing e-mails
  - `fax` (string): E.164
  - `firstName` (string): First name (max length 128)
  - `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
  - `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
  - `id` (string (uuid)): Id of the contact person
  - `info` (string): Info text
  - `isActive` (boolean): False when `leftAt` is set (default `true`)
  - `isBlocked` (boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set with `POST /addresses/{id}/contacts/{cid}/block`
  - `isDefault` (boolean): Default contact of the address (at most one)
  - `languageCode` (string): Language (ISO 639-1)
  - `lastName` (string): Last name (max length 128)
  - `leftAt` (string (date), nullable): Date the person left the company; sets `isActive` false
  - `letterSalutation` (string): Salutation line of letters
  - `linkedinUrl` (string (uri)): LinkedIn profile (max length 255)
  - `mobile` (string): E.164
  - `namePrefix` (string): Name prefix
  - `nameSuffix` (string): Name suffix
  - `phone1` (string): E.164
  - `phone2` (string): E.164
  - `portalUserId` (string): Linked desk portal user (max length 255)
  - `position` (string): Position
  - `postalAddressAnsNr` (integer, nullable): `ansNr` of a postal address of the same address
  - `preferredChannel` (string): Preferred contact channel (one of `EMAIL`, `PHONE`, `MOBILE`, `LETTER`, `PORTAL`)
  - `reportsToAspNr` (integer, nullable): `aspNr` of the manager within the same address (no cycles)
  - `roles` (array of string): Roles in the buying centre or for ticket routing
  - `salutationCode` (string): Code of `salutations`
  - `timezone` (string): IANA time zone
  - `title` (string): Title
  - `version` (integer): Version of this contact (child updates)
- `createdAt` (string (date-time), read-only): Creation time
- `createdBy` (string, read-only): Who created the address (subject of the token)
- `creditLimit` (number, nullable): Credit limit
- `creditorAccountNo` (string): Creditor account. With `glAccountLength` g it must lie in [7*10^g, 10^(g+1)-1] (g=4: 70000-99999); checked only when the value changes, else 400 (max length 32)
- `currencyCode` (string): ISO 4217
- `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`.
- `customerNo` (string, read-only): Tenant customer number (from the token)
- `customerNumber` (string): Customer number (Kundennummer), unique among the live addresses of the tenant (`409` `customer_number_taken`). Empty on an address with the role CUSTOMER: the address number (adrNr) is used while no other address has it as customer number, except in the platform operator tenant (max length 64)
- `customerSince` (string (date), nullable): Customer since (YYYY-MM-DD)
- `dataQualityScore` (integer, read-only): Completeness score computed on save (max 100)
- `deletionBlockedUntil` (string (date), nullable): Deleting the address or merging it away (as source) through this date (inclusive) answers 409 (Löschsperre bis TT.MM.JJJJ); a merge keeps the later date of both addresses
- `deliveryBlockReason` (string, read-only): Reason of the delivery block
- `deliveryBlocked` (boolean, read-only): Delivery block (set with `POST /addresses/{id}/blocks`; a PUT keeps it)
- `deliveryBlockedAt` (string (date-time), read-only): Time of the delivery block
- `deliveryBlockedBy` (string, read-only): Actor of the delivery block
- `deliveryCondition` (string): Delivery condition (free text) (max length 255)
- `discountRate` (number, nullable): Discount in percent (max 100)
- `displayName` (string, read-only): Company name, else first and last name
- `distributorIds` (array of DistributorID, read-only): Maintained via /api/masterdata/distributor-ids
  - `addressId` (string (uuid), required): Supplier address the distributor ID maps to
  - `addressName` (string, required): Display name of that address
  - `adrNr` (string, required): Address number of that address
  - `distributorId` (string, required): The distributor's own ID
  - `source` (string, required): Distributor (lower case, e.g. egis, ingram)
  - `updatedAt` (string (date-time), required): Time of the last change
  - `distributorName` (string): Name of the distributor
- `dunningBlocked` (boolean): Dunning block (also set with `POST /addresses/{id}/blocks`, type DUNNING)
- `dunningBlockedAt` (string (date-time), read-only): Time of the dunning block
- `dunningBlockedBy` (string, read-only): Actor of the dunning block
- `eInvoiceBuyerRef` (string): Leitweg-ID (XRechnung buyer reference)
- `eInvoiceFormat` (string): Preferred e-invoice format (one of `XRECHNUNG`, `ZUGFERD`, `PEPPOL`, `PDF`)
- `email` (string (email)): Main e-mail address (max length 255)
- `employeeCount` (integer, nullable): Number of employees
- `enrichedAt` (string (date-time), read-only): Time of the last enrichment
- `enrichmentData` (any): Free JSON of an enrichment
- `enrichmentStatus` (string): State of the data enrichment (one of `NOT_ENRICHED`, `PENDING`, `ENRICHED`, `FAILED`; default `"NOT_ENRICHED"`)
- `externalIds` (object): Keys of other systems, at most 20; key `^[a-z0-9_-]{1,64}$`, value max. 255 characters
- `fax` (string): E.164 (max length 64)
- `firstName` (string): First name (of a person) (max length 128)
- `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
- `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
- `gdprDataOrigin` (string): GDPR: where the data came from (max length 255)
- `gdprPurpose` (string): GDPR: purpose of the processing (max length 255)
- `gln` (string): Global Location Number with check digit
- `id` (string (uuid), read-only): Id of the address
- `industryCode` (string): Code of `industries`
- `info` (string): Info text
- `invoiceEmail` (string (email)): E-mail address for invoices (max length 255)
- `isBlocked` (boolean): General block of the address
- `isDiscountEligible` (boolean): Discounts may be granted
- `isEuForeign` (boolean, read-only): Derived like `isForeign` (both countries in the EU)
- `isForeign` (boolean, read-only): Derived on every write from the billing country (default billing postal address, else the first one) and the tenant country; ignored on write
- `isOneTime` (boolean): One-time account (Diverse)
- `isTaxInclusive` (boolean): Prices are gross (tax inclusive)
- `languageCode` (string): ISO 639-1, optionally with region
- `lastName` (string): Last name (required for `partyType` PERSON) (max length 128)
- `legalForm` (string): Legal form (max length 64)
- `marketingObjection` (boolean): Objection to advertising
- `marketingObjectionAt` (string (date-time), nullable, read-only): Set by the server when `marketingObjection` turns true
- `memo` (string): Internal memo
- `mergedIntoId` (string (uuid), read-only): Set when the address was merged into another one
- `mobile` (string): E.164 (max length 64)
- `netDays` (integer, nullable): Payment term in days (net)
- `ourCustomerNumber` (string): Our customer number at this party (max length 64)
- `parentAddressId` (string (uuid)): Parent company (another address of the tenant; no cycles)
- `parentName` (string, read-only): Display name of the parent address (set on read)
- `partyType` (string): COMPANY needs `companyName`, PERSON needs `lastName` (one of `COMPANY`, `PERSON`; default `"COMPANY"`)
- `paymentBlockReason` (string, read-only): Reason of the payment block
- `paymentBlocked` (boolean, read-only): Payment block (set with `POST /addresses/{id}/blocks`; a PUT keeps it)
- `paymentBlockedAt` (string (date-time), read-only): Time of the payment block
- `paymentBlockedBy` (string, read-only): Actor of the payment block
- `paymentMethodCode` (string): Code of `payment-methods`
- `paymentTermCode` (string): Code of `payment-terms`
- `peppolId` (string): Peppol participant ID `scheme:id`
- `phone` (string): E.164 (+4989123456). Input is normalised with the country of the default billing postal address, else of the tenant profile, else DE; extensions are dropped; a changed value that cannot be parsed answers 400 (a value equal to the stored one is kept) (max length 64)
- `postalAddresses` (array of PostalAddress): Postal addresses (Anschriften)
  - `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
- `postingAccountNo` (string): Debtor account (Debitorenkonto). With the tenant's `glAccountLength` g it must lie in [10^g, 7*10^g-1] (g=4: 10000-69999); checked only when the value changes, else 400 (max length 32)
- `purchaseOrderEmail` (string (email)): Mail address that receives the purchase orders sent to this supplier; empty falls back to `email` (max length 254)
- `purchaseOrderRequired` (boolean, nullable): Invoices of this supplier need a purchase order. Omitted: `true` on create, unchanged on update
- `registerCourt` (string): Register court (max length 128)
- `reverseCharge` (boolean): Reverse charge (§13b UStG)
- `roles` (array of string, read-only): Derived from the flags of the status (`isCustomer` CUSTOMER, `isVendor` SUPPLIER, `isLead` PROSPECT, `isPartner` PARTNER); a value in the request is ignored
- `salesRepCommissionRate` (number, nullable): Commission of the sales representative in percent (max 100)
- `salesRepNo` (string): Number of the sales representative (max length 32)
- `salutationCode` (string): Code of `salutations`
- `searchTerm` (string): Search term (Suchbegriff); derived from the name when empty (max length 255)
- `sepaMandates` (array of SepaMandate): SEPA direct debit mandates
  - `bankAccountIban` (string, required): IBAN of a bank account of this address
  - `signedAt` (string (date), required): Date of signature (YYYY-MM-DD)
  - `bankAccountId` (string (uuid), read-only): Id of the linked bank account
  - `creditorId` (string): Creditor identifier (max length 35)
  - `id` (string (uuid)): Id of the mandate
  - `lastUsedAt` (string (date), nullable): Set when a collection uses the mandate. A mandate with lastUsedAt cannot be deleted, also not together with its bank account: a PUT that omits it answers 409; revoke it with status REVOKED instead
  - `mandateReference` (string): Assigned from the MANDATE range when empty
  - `mandateType` (string): CORE or B2B direct debit (one of `CORE`, `B2B`; default `"CORE"`)
  - `revokedAt` (string (date), nullable): Set by the server for status REVOKED (the first stamp stays; a client value is ignored)
  - `sequenceType` (string): Sequence type of the next collection (one of `FRST`, `RCUR`, `OOFF`, `FNAL`; default `"FRST"`)
  - `status` (string): State of the mandate (one of `ACTIVE`, `REVOKED`, `EXPIRED`; default `"ACTIVE"`)
  - `validFrom` (string (date), nullable): Valid from (YYYY-MM-DD)
- `shippingTypeCode` (string): Code of `shipping-types`
- `skontoDays1` (integer, nullable): Days for the first cash discount
- `skontoDays2` (integer, nullable): Days for the second cash discount
- `skontoRate1` (number, nullable): First cash discount in percent (max 100)
- `skontoRate2` (number, nullable): Second cash discount in percent (max 100)
- `smallBusiness` (boolean): Small business (§19 UStG)
- `source` (string): Where the address came from (lead source) (max length 64)
- `supplierNumber` (string): Supplier number (Lieferantennummer), unique among the live addresses of the tenant (`409` `supplier_number_taken`). Empty on an address with the role SUPPLIER: the address number (adrNr) is used while no other address has it as supplier number (max length 64)
- `syncStatus` (string, read-only): Reserved for an ERP synchronisation; STANDALONE for records of this API (one of `STANDALONE`, `PENDING_CREATION`, `PENDING_UPDATE`, `SYNCED`, `CONFLICT`, `ERROR`)
- `tags` (array of string): Duplicates (case-insensitive) are removed
- `taxNumber` (string): Tax number (Steuernummer) (max length 64)
- `taxZone` (string, read-only): Derived on every write: DOMESTIC (billing country = tenant country), EU_VATID (EU with `vatId`), EU_PRIVATE (EU without `vatId`), THIRD_COUNTRY; empty without a postal address. Ignored on write. `vatCategory` stays for compatibility (one of `DOMESTIC`, `EU_VATID`, `EU_PRIVATE`, `THIRD_COUNTRY`)
- `tenantName` (string, read-only): Tenant name (from the token)
- `title` (string): Title of the party (e.g. Dr.) (max length 64)
- `updatedAt` (string (date-time), read-only): Time of the last change
- `updatedBy` (string, read-only): Who changed the address last (subject of the token)
- `valutaDays` (integer, nullable): Value date days
- `vatCategory` (integer): VAT category (microtech) (max 9)
- `vatCheckStatus` (VatCheckStatus, read-only): Result of the latest official VAT check (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`, `NOT_CHECKED`)
- `vatCheckedAt` (string (date-time), read-only): Time of the latest official VAT check
- `vatId` (string): VAT ID (USt-IdNr.)
- `website` (string (uri)): Website (max length 255)

Example 200 answer:

```json
{
  "accountOwner": "Lena Vogel",
  "accountType": "INDIVIDUAL",
  "adrNr": "10001",
  "bankAccounts": [
    {
      "accountHolder": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "bankName": "Commerzbank",
      "bic": "COBADEFFXXX",
      "iban": "DE89370400440532013000",
      "id": "4e6a8c0e-2a4b-4d6f-8a0c-2e4a6b8d0f2a",
      "isDefault": true
    }
  ],
  "commercialRegister": "HRA 4711",
  "companyName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "contactPersons": [
    {
      "aspNr": 1,
      "email1": "georg.moser@alpenhotel-seeblick.example",
      "firstName": "Georg",
      "gdprConsent": "UNKNOWN",
      "id": "6a8c0e2a-4b6d-4f8a-9c0e-2a4b6d8f0a2c",
      "isActive": true,
      "isDefault": true,
      "lastName": "Moser",
      "letterSalutation": "Sehr geehrter Herr Moser",
      "phone1": "+49865298760",
      "position": "Geschäftsführer",
      "postalAddressAnsNr": 1,
      "roles": [
        "DECISION_MAKER"
      ],
      "salutationCode": "HERR",
      "version": 1
    },
    {
      "aspNr": 2,
      "availableFrom1": "08:00",
      "availableTo1": "16:00",
      "customFields": {},
      "doNotCall": false,
      "email1": "katrin.stadler@alpenhotel-seeblick.example",
      "emailOptOut": false,
      "firstName": "Katrin",
      "gdprConsent": "UNKNOWN",
      "id": "8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a",
      "isActive": true,
      "isBlocked": false,
      "isDefault": false,
      "languageCode": "de",
      "lastName": "Stadler",
      "letterSalutation": "Sehr geehrte Frau Stadler",
      "phone1": "+498652987612",
      "position": "Empfangsleitung und IT",
      "postalAddressAnsNr": 1,
      "preferredChannel": "PHONE",
      "roles": [
        "TECHNICAL",
        "SUPPORT"
      ],
      "salutationCode": "FRAU",
      "timezone": "Europe/Berlin",
      "version": 3
    }
  ],
  "createdAt": "2026-01-02T08:00:00Z",
  "createdBy": "laura.kaestner@muster-it.example",
  "currencyCode": "EUR",
  "customFields": {
    "branche": "hotel"
  },
  "customerNo": "99999",
  "customerNumber": "10001",
  "customerSince": "2019-04-01",
  "dataQualityScore": 90,
  "deliveryBlocked": false,
  "displayName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "distributorIds": [
    {
      "addressId": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
      "addressName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "adrNr": "10001",
      "distributorId": "700123",
      "distributorName": "EGIS Computer Service-Center GmbH",
      "source": "egis",
      "updatedAt": "2026-05-20T11:40:00Z"
    }
  ],
  "dunningBlocked": false,
  "eInvoiceFormat": "ZUGFERD",
  "email": "rezeption@alpenhotel-seeblick.example",
  "employeeCount": 38,
  "enrichmentStatus": "NOT_ENRICHED",
  "gdprConsent": "UNKNOWN",
  "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
  "invoiceEmail": "buchhaltung@alpenhotel-seeblick.example",
  "isBlocked": false,
  "isDiscountEligible": true,
  "isEuForeign": false,
  "isForeign": false,
  "isOneTime": false,
  "isTaxInclusive": false,
  "languageCode": "de",
  "legalForm": "GmbH \u0026 Co. KG",
  "marketingObjection": false,
  "netDays": 30,
  "partyType": "COMPANY",
  "paymentBlocked": false,
  "paymentMethodCode": "UEBERWEISUNG",
  "paymentTermCode": "NETTO30",
  "phone": "+49865298760",
  "postalAddresses": [
    {
      "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
    }
  ],
  "postingAccountNo": "10001",
  "registerCourt": "Amtsgericht Traunstein",
  "reverseCharge": false,
  "roles": [
    "CUSTOMER"
  ],
  "searchTerm": "ALPENHOTEL SEEBLICK",
  "sepaMandates": [],
  "smallBusiness": false,
  "statusCode": "KUNDE",
  "syncStatus": "STANDALONE",
  "tags": [
    "Wartungsvertrag"
  ],
  "taxZone": "DOMESTIC",
  "tenantName": "DEMO",
  "updatedAt": "2026-11-03T09:14:22Z",
  "updatedBy": "christina.adler@muster-it.example",
  "vatCheckStatus": "OFFICIALLY_CONFIRMED",
  "vatCheckedAt": "2026-11-03T09:14:22Z",
  "vatId": "DE811234567",
  "version": 7,
  "website": "https://www.alpenhotel-seeblick.example"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4/blocks' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"reason":"Zwei Rechnungen über 60 Tage offen","type":"PAYMENT"}'
```

## Lift a block of an address (tenant:masterdata:write)

`DELETE /api/masterdata/addresses/{id}/blocks/{type}`

Module: Master data · operationId: `unblockAddress` · Tag: Addresses · Auth: access token (`Authorization: Bearer <accessToken>`)

Clears the flag, reason, time and actor of the block, bumps the version and emits `masterdata.address.updated`. Returns the address.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `type` | path | string | yes | Block type (one of `GENERAL`, `PAYMENT`, `DELIVERY`, `DUNNING`) |

### Responses

- **200** Unblocked (`application/json`)
- **400** Invalid input (`invalid`); `field` names the first, `details.fields` each invalid field (`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:

- `statusCode` (string, required): Code of `address-statuses` (required). Its flags decide the `roles`
- `version` (integer, required): Optimistic locking version; send the version you read (ignored on create)
- `accountOwner` (string): Account owner (responsible person) in CRM (max length 255)
- `accountType` (string): Individual or collective account (one of `INDIVIDUAL`, `COLLECTIVE`; default `"INDIVIDUAL"`)
- `additionalName` (string): Name addition (second name line) (max length 255)
- `adrNr` (string): Address number, unique per tenant; assigned from the ADDRESS range when empty (max length 32)
- `annualRevenue` (number, nullable): Annual revenue
- `bankAccounts` (array of BankAccount): Bank accounts
  - `iban` (string, required): Unique per address
  - `accountHolder` (string): Account holder (max length 255)
  - `bankName` (string): Name of the bank (max length 128)
  - `bic` (string): BIC
  - `id` (string (uuid)): Id of the bank account
  - `isDefault` (boolean): At most one; the first account is the default when none is set
- `blockReason` (string): Cleared when `isBlocked` is false (max length 255)
- `blockedAt` (string (date-time), read-only): Time of the general block
- `blockedBy` (string, read-only): Actor of the general block
- `commercialRegister` (string): Commercial register number (Handelsregister) (max length 128)
- `companyName` (string): Company name (required for `partyType` COMPANY) (max length 255)
- `contactPersons` (array of ContactPerson): Contact persons (Ansprechpartner)
  - `aspNr` (integer): Number within the address; assigned
  - `availableFrom1` (string, nullable): Reachable from (HH:MM)
  - `availableFrom2` (string, nullable): Second time window: reachable from (HH:MM)
  - `availableTo1` (string, nullable): After `availableFrom1`
  - `availableTo2` (string, nullable): After `availableFrom2`
  - `birthday` (string (date), nullable): Birthday (YYYY-MM-DD)
  - `blockReason` (string, read-only): Reason of the block
  - `blockedAt` (string (date-time), read-only): Time of the block
  - `blockedBy` (string, read-only): Actor of the block
  - `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`.
  - `department` (string): Department
  - `doNotCall` (boolean): Do not call
  - `email1` (string (email)): First e-mail address
  - `email2` (string (email)): Second e-mail address
  - `emailOptOut` (boolean): No marketing e-mails
  - `fax` (string): E.164
  - `firstName` (string): First name (max length 128)
  - `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
  - `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
  - `id` (string (uuid)): Id of the contact person
  - `info` (string): Info text
  - `isActive` (boolean): False when `leftAt` is set (default `true`)
  - `isBlocked` (boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set with `POST /addresses/{id}/contacts/{cid}/block`
  - `isDefault` (boolean): Default contact of the address (at most one)
  - `languageCode` (string): Language (ISO 639-1)
  - `lastName` (string): Last name (max length 128)
  - `leftAt` (string (date), nullable): Date the person left the company; sets `isActive` false
  - `letterSalutation` (string): Salutation line of letters
  - `linkedinUrl` (string (uri)): LinkedIn profile (max length 255)
  - `mobile` (string): E.164
  - `namePrefix` (string): Name prefix
  - `nameSuffix` (string): Name suffix
  - `phone1` (string): E.164
  - `phone2` (string): E.164
  - `portalUserId` (string): Linked desk portal user (max length 255)
  - `position` (string): Position
  - `postalAddressAnsNr` (integer, nullable): `ansNr` of a postal address of the same address
  - `preferredChannel` (string): Preferred contact channel (one of `EMAIL`, `PHONE`, `MOBILE`, `LETTER`, `PORTAL`)
  - `reportsToAspNr` (integer, nullable): `aspNr` of the manager within the same address (no cycles)
  - `roles` (array of string): Roles in the buying centre or for ticket routing
  - `salutationCode` (string): Code of `salutations`
  - `timezone` (string): IANA time zone
  - `title` (string): Title
  - `version` (integer): Version of this contact (child updates)
- `createdAt` (string (date-time), read-only): Creation time
- `createdBy` (string, read-only): Who created the address (subject of the token)
- `creditLimit` (number, nullable): Credit limit
- `creditorAccountNo` (string): Creditor account. With `glAccountLength` g it must lie in [7*10^g, 10^(g+1)-1] (g=4: 70000-99999); checked only when the value changes, else 400 (max length 32)
- `currencyCode` (string): ISO 4217
- `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`.
- `customerNo` (string, read-only): Tenant customer number (from the token)
- `customerNumber` (string): Customer number (Kundennummer), unique among the live addresses of the tenant (`409` `customer_number_taken`). Empty on an address with the role CUSTOMER: the address number (adrNr) is used while no other address has it as customer number, except in the platform operator tenant (max length 64)
- `customerSince` (string (date), nullable): Customer since (YYYY-MM-DD)
- `dataQualityScore` (integer, read-only): Completeness score computed on save (max 100)
- `deletionBlockedUntil` (string (date), nullable): Deleting the address or merging it away (as source) through this date (inclusive) answers 409 (Löschsperre bis TT.MM.JJJJ); a merge keeps the later date of both addresses
- `deliveryBlockReason` (string, read-only): Reason of the delivery block
- `deliveryBlocked` (boolean, read-only): Delivery block (set with `POST /addresses/{id}/blocks`; a PUT keeps it)
- `deliveryBlockedAt` (string (date-time), read-only): Time of the delivery block
- `deliveryBlockedBy` (string, read-only): Actor of the delivery block
- `deliveryCondition` (string): Delivery condition (free text) (max length 255)
- `discountRate` (number, nullable): Discount in percent (max 100)
- `displayName` (string, read-only): Company name, else first and last name
- `distributorIds` (array of DistributorID, read-only): Maintained via /api/masterdata/distributor-ids
  - `addressId` (string (uuid), required): Supplier address the distributor ID maps to
  - `addressName` (string, required): Display name of that address
  - `adrNr` (string, required): Address number of that address
  - `distributorId` (string, required): The distributor's own ID
  - `source` (string, required): Distributor (lower case, e.g. egis, ingram)
  - `updatedAt` (string (date-time), required): Time of the last change
  - `distributorName` (string): Name of the distributor
- `dunningBlocked` (boolean): Dunning block (also set with `POST /addresses/{id}/blocks`, type DUNNING)
- `dunningBlockedAt` (string (date-time), read-only): Time of the dunning block
- `dunningBlockedBy` (string, read-only): Actor of the dunning block
- `eInvoiceBuyerRef` (string): Leitweg-ID (XRechnung buyer reference)
- `eInvoiceFormat` (string): Preferred e-invoice format (one of `XRECHNUNG`, `ZUGFERD`, `PEPPOL`, `PDF`)
- `email` (string (email)): Main e-mail address (max length 255)
- `employeeCount` (integer, nullable): Number of employees
- `enrichedAt` (string (date-time), read-only): Time of the last enrichment
- `enrichmentData` (any): Free JSON of an enrichment
- `enrichmentStatus` (string): State of the data enrichment (one of `NOT_ENRICHED`, `PENDING`, `ENRICHED`, `FAILED`; default `"NOT_ENRICHED"`)
- `externalIds` (object): Keys of other systems, at most 20; key `^[a-z0-9_-]{1,64}$`, value max. 255 characters
- `fax` (string): E.164 (max length 64)
- `firstName` (string): First name (of a person) (max length 128)
- `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
- `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
- `gdprDataOrigin` (string): GDPR: where the data came from (max length 255)
- `gdprPurpose` (string): GDPR: purpose of the processing (max length 255)
- `gln` (string): Global Location Number with check digit
- `id` (string (uuid), read-only): Id of the address
- `industryCode` (string): Code of `industries`
- `info` (string): Info text
- `invoiceEmail` (string (email)): E-mail address for invoices (max length 255)
- `isBlocked` (boolean): General block of the address
- `isDiscountEligible` (boolean): Discounts may be granted
- `isEuForeign` (boolean, read-only): Derived like `isForeign` (both countries in the EU)
- `isForeign` (boolean, read-only): Derived on every write from the billing country (default billing postal address, else the first one) and the tenant country; ignored on write
- `isOneTime` (boolean): One-time account (Diverse)
- `isTaxInclusive` (boolean): Prices are gross (tax inclusive)
- `languageCode` (string): ISO 639-1, optionally with region
- `lastName` (string): Last name (required for `partyType` PERSON) (max length 128)
- `legalForm` (string): Legal form (max length 64)
- `marketingObjection` (boolean): Objection to advertising
- `marketingObjectionAt` (string (date-time), nullable, read-only): Set by the server when `marketingObjection` turns true
- `memo` (string): Internal memo
- `mergedIntoId` (string (uuid), read-only): Set when the address was merged into another one
- `mobile` (string): E.164 (max length 64)
- `netDays` (integer, nullable): Payment term in days (net)
- `ourCustomerNumber` (string): Our customer number at this party (max length 64)
- `parentAddressId` (string (uuid)): Parent company (another address of the tenant; no cycles)
- `parentName` (string, read-only): Display name of the parent address (set on read)
- `partyType` (string): COMPANY needs `companyName`, PERSON needs `lastName` (one of `COMPANY`, `PERSON`; default `"COMPANY"`)
- `paymentBlockReason` (string, read-only): Reason of the payment block
- `paymentBlocked` (boolean, read-only): Payment block (set with `POST /addresses/{id}/blocks`; a PUT keeps it)
- `paymentBlockedAt` (string (date-time), read-only): Time of the payment block
- `paymentBlockedBy` (string, read-only): Actor of the payment block
- `paymentMethodCode` (string): Code of `payment-methods`
- `paymentTermCode` (string): Code of `payment-terms`
- `peppolId` (string): Peppol participant ID `scheme:id`
- `phone` (string): E.164 (+4989123456). Input is normalised with the country of the default billing postal address, else of the tenant profile, else DE; extensions are dropped; a changed value that cannot be parsed answers 400 (a value equal to the stored one is kept) (max length 64)
- `postalAddresses` (array of PostalAddress): Postal addresses (Anschriften)
  - `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
- `postingAccountNo` (string): Debtor account (Debitorenkonto). With the tenant's `glAccountLength` g it must lie in [10^g, 7*10^g-1] (g=4: 10000-69999); checked only when the value changes, else 400 (max length 32)
- `purchaseOrderEmail` (string (email)): Mail address that receives the purchase orders sent to this supplier; empty falls back to `email` (max length 254)
- `purchaseOrderRequired` (boolean, nullable): Invoices of this supplier need a purchase order. Omitted: `true` on create, unchanged on update
- `registerCourt` (string): Register court (max length 128)
- `reverseCharge` (boolean): Reverse charge (§13b UStG)
- `roles` (array of string, read-only): Derived from the flags of the status (`isCustomer` CUSTOMER, `isVendor` SUPPLIER, `isLead` PROSPECT, `isPartner` PARTNER); a value in the request is ignored
- `salesRepCommissionRate` (number, nullable): Commission of the sales representative in percent (max 100)
- `salesRepNo` (string): Number of the sales representative (max length 32)
- `salutationCode` (string): Code of `salutations`
- `searchTerm` (string): Search term (Suchbegriff); derived from the name when empty (max length 255)
- `sepaMandates` (array of SepaMandate): SEPA direct debit mandates
  - `bankAccountIban` (string, required): IBAN of a bank account of this address
  - `signedAt` (string (date), required): Date of signature (YYYY-MM-DD)
  - `bankAccountId` (string (uuid), read-only): Id of the linked bank account
  - `creditorId` (string): Creditor identifier (max length 35)
  - `id` (string (uuid)): Id of the mandate
  - `lastUsedAt` (string (date), nullable): Set when a collection uses the mandate. A mandate with lastUsedAt cannot be deleted, also not together with its bank account: a PUT that omits it answers 409; revoke it with status REVOKED instead
  - `mandateReference` (string): Assigned from the MANDATE range when empty
  - `mandateType` (string): CORE or B2B direct debit (one of `CORE`, `B2B`; default `"CORE"`)
  - `revokedAt` (string (date), nullable): Set by the server for status REVOKED (the first stamp stays; a client value is ignored)
  - `sequenceType` (string): Sequence type of the next collection (one of `FRST`, `RCUR`, `OOFF`, `FNAL`; default `"FRST"`)
  - `status` (string): State of the mandate (one of `ACTIVE`, `REVOKED`, `EXPIRED`; default `"ACTIVE"`)
  - `validFrom` (string (date), nullable): Valid from (YYYY-MM-DD)
- `shippingTypeCode` (string): Code of `shipping-types`
- `skontoDays1` (integer, nullable): Days for the first cash discount
- `skontoDays2` (integer, nullable): Days for the second cash discount
- `skontoRate1` (number, nullable): First cash discount in percent (max 100)
- `skontoRate2` (number, nullable): Second cash discount in percent (max 100)
- `smallBusiness` (boolean): Small business (§19 UStG)
- `source` (string): Where the address came from (lead source) (max length 64)
- `supplierNumber` (string): Supplier number (Lieferantennummer), unique among the live addresses of the tenant (`409` `supplier_number_taken`). Empty on an address with the role SUPPLIER: the address number (adrNr) is used while no other address has it as supplier number (max length 64)
- `syncStatus` (string, read-only): Reserved for an ERP synchronisation; STANDALONE for records of this API (one of `STANDALONE`, `PENDING_CREATION`, `PENDING_UPDATE`, `SYNCED`, `CONFLICT`, `ERROR`)
- `tags` (array of string): Duplicates (case-insensitive) are removed
- `taxNumber` (string): Tax number (Steuernummer) (max length 64)
- `taxZone` (string, read-only): Derived on every write: DOMESTIC (billing country = tenant country), EU_VATID (EU with `vatId`), EU_PRIVATE (EU without `vatId`), THIRD_COUNTRY; empty without a postal address. Ignored on write. `vatCategory` stays for compatibility (one of `DOMESTIC`, `EU_VATID`, `EU_PRIVATE`, `THIRD_COUNTRY`)
- `tenantName` (string, read-only): Tenant name (from the token)
- `title` (string): Title of the party (e.g. Dr.) (max length 64)
- `updatedAt` (string (date-time), read-only): Time of the last change
- `updatedBy` (string, read-only): Who changed the address last (subject of the token)
- `valutaDays` (integer, nullable): Value date days
- `vatCategory` (integer): VAT category (microtech) (max 9)
- `vatCheckStatus` (VatCheckStatus, read-only): Result of the latest official VAT check (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`, `NOT_CHECKED`)
- `vatCheckedAt` (string (date-time), read-only): Time of the latest official VAT check
- `vatId` (string): VAT ID (USt-IdNr.)
- `website` (string (uri)): Website (max length 255)

Example 200 answer:

```json
{
  "accountOwner": "Lena Vogel",
  "accountType": "INDIVIDUAL",
  "adrNr": "10001",
  "bankAccounts": [
    {
      "accountHolder": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "bankName": "Commerzbank",
      "bic": "COBADEFFXXX",
      "iban": "DE89370400440532013000",
      "id": "4e6a8c0e-2a4b-4d6f-8a0c-2e4a6b8d0f2a",
      "isDefault": true
    }
  ],
  "commercialRegister": "HRA 4711",
  "companyName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "contactPersons": [
    {
      "aspNr": 1,
      "email1": "georg.moser@alpenhotel-seeblick.example",
      "firstName": "Georg",
      "gdprConsent": "UNKNOWN",
      "id": "6a8c0e2a-4b6d-4f8a-9c0e-2a4b6d8f0a2c",
      "isActive": true,
      "isDefault": true,
      "lastName": "Moser",
      "letterSalutation": "Sehr geehrter Herr Moser",
      "phone1": "+49865298760",
      "position": "Geschäftsführer",
      "postalAddressAnsNr": 1,
      "roles": [
        "DECISION_MAKER"
      ],
      "salutationCode": "HERR",
      "version": 1
    },
    {
      "aspNr": 2,
      "availableFrom1": "08:00",
      "availableTo1": "16:00",
      "customFields": {},
      "doNotCall": false,
      "email1": "katrin.stadler@alpenhotel-seeblick.example",
      "emailOptOut": false,
      "firstName": "Katrin",
      "gdprConsent": "UNKNOWN",
      "id": "8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a",
      "isActive": true,
      "isBlocked": false,
      "isDefault": false,
      "languageCode": "de",
      "lastName": "Stadler",
      "letterSalutation": "Sehr geehrte Frau Stadler",
      "phone1": "+498652987612",
      "position": "Empfangsleitung und IT",
      "postalAddressAnsNr": 1,
      "preferredChannel": "PHONE",
      "roles": [
        "TECHNICAL",
        "SUPPORT"
      ],
      "salutationCode": "FRAU",
      "timezone": "Europe/Berlin",
      "version": 3
    }
  ],
  "createdAt": "2026-01-02T08:00:00Z",
  "createdBy": "laura.kaestner@muster-it.example",
  "currencyCode": "EUR",
  "customFields": {
    "branche": "hotel"
  },
  "customerNo": "99999",
  "customerNumber": "10001",
  "customerSince": "2019-04-01",
  "dataQualityScore": 90,
  "deliveryBlocked": false,
  "displayName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "distributorIds": [
    {
      "addressId": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
      "addressName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "adrNr": "10001",
      "distributorId": "700123",
      "distributorName": "EGIS Computer Service-Center GmbH",
      "source": "egis",
      "updatedAt": "2026-05-20T11:40:00Z"
    }
  ],
  "dunningBlocked": false,
  "eInvoiceFormat": "ZUGFERD",
  "email": "rezeption@alpenhotel-seeblick.example",
  "employeeCount": 38,
  "enrichmentStatus": "NOT_ENRICHED",
  "gdprConsent": "UNKNOWN",
  "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
  "invoiceEmail": "buchhaltung@alpenhotel-seeblick.example",
  "isBlocked": false,
  "isDiscountEligible": true,
  "isEuForeign": false,
  "isForeign": false,
  "isOneTime": false,
  "isTaxInclusive": false,
  "languageCode": "de",
  "legalForm": "GmbH \u0026 Co. KG",
  "marketingObjection": false,
  "netDays": 30,
  "partyType": "COMPANY",
  "paymentBlocked": false,
  "paymentMethodCode": "UEBERWEISUNG",
  "paymentTermCode": "NETTO30",
  "phone": "+49865298760",
  "postalAddresses": [
    {
      "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
    }
  ],
  "postingAccountNo": "10001",
  "registerCourt": "Amtsgericht Traunstein",
  "reverseCharge": false,
  "roles": [
    "CUSTOMER"
  ],
  "searchTerm": "ALPENHOTEL SEEBLICK",
  "sepaMandates": [],
  "smallBusiness": false,
  "statusCode": "KUNDE",
  "syncStatus": "STANDALONE",
  "tags": [
    "Wartungsvertrag"
  ],
  "taxZone": "DOMESTIC",
  "tenantName": "DEMO",
  "updatedAt": "2026-11-03T09:14:22Z",
  "updatedBy": "christina.adler@muster-it.example",
  "vatCheckStatus": "OFFICIALLY_CONFIRMED",
  "vatCheckedAt": "2026-11-03T09:14:22Z",
  "vatId": "DE811234567",
  "version": 7,
  "website": "https://www.alpenhotel-seeblick.example"
}
```

### Example request

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

# Contact persons

## Block a contact person (tenant:masterdata:write)

`POST /api/masterdata/addresses/{id}/contacts/{cid}/block`

Module: Master data · operationId: `blockContactPerson` · Tag: Contact persons · Auth: access token (`Authorization: Bearer <accessToken>`)

The reason is required (`400` "Bitte einen Grund angeben."). A blocked contact is left out of the phone contacts and the platform notification list. Bumps the address version and emits `masterdata.address.updated`.

### Parameters

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

### Request body

`application/json` (required)

- `reason` (string): Required except for `DUNNING` (max length 255)
- `type` (string): Block type of an address (not used for contact persons) (one of `GENERAL`, `PAYMENT`, `DELIVERY`, `DUNNING`)

Example:

```json
{
  "reason": "Zwei Rechnungen über 60 Tage offen",
  "type": "PAYMENT"
}
```

### Responses

- **200** Blocked (`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`)

Fields of the 200 answer:

- `aspNr` (integer): Number within the address; assigned
- `availableFrom1` (string, nullable): Reachable from (HH:MM)
- `availableFrom2` (string, nullable): Second time window: reachable from (HH:MM)
- `availableTo1` (string, nullable): After `availableFrom1`
- `availableTo2` (string, nullable): After `availableFrom2`
- `birthday` (string (date), nullable): Birthday (YYYY-MM-DD)
- `blockReason` (string, read-only): Reason of the block
- `blockedAt` (string (date-time), read-only): Time of the block
- `blockedBy` (string, read-only): Actor of the block
- `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`.
- `department` (string): Department
- `doNotCall` (boolean): Do not call
- `email1` (string (email)): First e-mail address
- `email2` (string (email)): Second e-mail address
- `emailOptOut` (boolean): No marketing e-mails
- `fax` (string): E.164
- `firstName` (string): First name (max length 128)
- `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
- `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
- `id` (string (uuid)): Id of the contact person
- `info` (string): Info text
- `isActive` (boolean): False when `leftAt` is set (default `true`)
- `isBlocked` (boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set with `POST /addresses/{id}/contacts/{cid}/block`
- `isDefault` (boolean): Default contact of the address (at most one)
- `languageCode` (string): Language (ISO 639-1)
- `lastName` (string): Last name (max length 128)
- `leftAt` (string (date), nullable): Date the person left the company; sets `isActive` false
- `letterSalutation` (string): Salutation line of letters
- `linkedinUrl` (string (uri)): LinkedIn profile (max length 255)
- `mobile` (string): E.164
- `namePrefix` (string): Name prefix
- `nameSuffix` (string): Name suffix
- `phone1` (string): E.164
- `phone2` (string): E.164
- `portalUserId` (string): Linked desk portal user (max length 255)
- `position` (string): Position
- `postalAddressAnsNr` (integer, nullable): `ansNr` of a postal address of the same address
- `preferredChannel` (string): Preferred contact channel (one of `EMAIL`, `PHONE`, `MOBILE`, `LETTER`, `PORTAL`)
- `reportsToAspNr` (integer, nullable): `aspNr` of the manager within the same address (no cycles)
- `roles` (array of string): Roles in the buying centre or for ticket routing
- `salutationCode` (string): Code of `salutations`
- `timezone` (string): IANA time zone
- `title` (string): Title
- `version` (integer): Version of this contact (child updates)
- `addressVersion` (integer, required): New version of the address

Example 200 answer:

```json
{
  "addressVersion": 8,
  "aspNr": 2,
  "email1": "katrin.stadler@alpenhotel-seeblick.example",
  "firstName": "Katrin",
  "gdprConsent": "UNKNOWN",
  "id": "8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a",
  "isActive": true,
  "isBlocked": false,
  "isDefault": false,
  "lastName": "Stadler",
  "letterSalutation": "Sehr geehrte Frau Stadler",
  "phone1": "+498652987612",
  "position": "Empfangsleitung und IT",
  "postalAddressAnsNr": 1,
  "roles": [
    "TECHNICAL",
    "SUPPORT"
  ],
  "salutationCode": "FRAU",
  "version": 3
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4/contacts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/block' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"reason":"Zwei Rechnungen über 60 Tage offen","type":"PAYMENT"}'
```

## Lift the block of a contact person (tenant:masterdata:write)

`DELETE /api/masterdata/addresses/{id}/contacts/{cid}/block`

Module: Master data · operationId: `unblockContactPerson` · Tag: Contact persons · Auth: access token (`Authorization: Bearer <accessToken>`)

Bumps the address version and emits `masterdata.address.updated`.

### Parameters

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

### Responses

- **200** Unblocked (`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:

- `aspNr` (integer): Number within the address; assigned
- `availableFrom1` (string, nullable): Reachable from (HH:MM)
- `availableFrom2` (string, nullable): Second time window: reachable from (HH:MM)
- `availableTo1` (string, nullable): After `availableFrom1`
- `availableTo2` (string, nullable): After `availableFrom2`
- `birthday` (string (date), nullable): Birthday (YYYY-MM-DD)
- `blockReason` (string, read-only): Reason of the block
- `blockedAt` (string (date-time), read-only): Time of the block
- `blockedBy` (string, read-only): Actor of the block
- `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`.
- `department` (string): Department
- `doNotCall` (boolean): Do not call
- `email1` (string (email)): First e-mail address
- `email2` (string (email)): Second e-mail address
- `emailOptOut` (boolean): No marketing e-mails
- `fax` (string): E.164
- `firstName` (string): First name (max length 128)
- `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
- `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
- `id` (string (uuid)): Id of the contact person
- `info` (string): Info text
- `isActive` (boolean): False when `leftAt` is set (default `true`)
- `isBlocked` (boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set with `POST /addresses/{id}/contacts/{cid}/block`
- `isDefault` (boolean): Default contact of the address (at most one)
- `languageCode` (string): Language (ISO 639-1)
- `lastName` (string): Last name (max length 128)
- `leftAt` (string (date), nullable): Date the person left the company; sets `isActive` false
- `letterSalutation` (string): Salutation line of letters
- `linkedinUrl` (string (uri)): LinkedIn profile (max length 255)
- `mobile` (string): E.164
- `namePrefix` (string): Name prefix
- `nameSuffix` (string): Name suffix
- `phone1` (string): E.164
- `phone2` (string): E.164
- `portalUserId` (string): Linked desk portal user (max length 255)
- `position` (string): Position
- `postalAddressAnsNr` (integer, nullable): `ansNr` of a postal address of the same address
- `preferredChannel` (string): Preferred contact channel (one of `EMAIL`, `PHONE`, `MOBILE`, `LETTER`, `PORTAL`)
- `reportsToAspNr` (integer, nullable): `aspNr` of the manager within the same address (no cycles)
- `roles` (array of string): Roles in the buying centre or for ticket routing
- `salutationCode` (string): Code of `salutations`
- `timezone` (string): IANA time zone
- `title` (string): Title
- `version` (integer): Version of this contact (child updates)
- `addressVersion` (integer, required): New version of the address

Example 200 answer:

```json
{
  "addressVersion": 8,
  "aspNr": 2,
  "email1": "katrin.stadler@alpenhotel-seeblick.example",
  "firstName": "Katrin",
  "gdprConsent": "UNKNOWN",
  "id": "8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a",
  "isActive": true,
  "isBlocked": false,
  "isDefault": false,
  "lastName": "Stadler",
  "letterSalutation": "Sehr geehrte Frau Stadler",
  "phone1": "+498652987612",
  "position": "Empfangsleitung und IT",
  "postalAddressAnsNr": 1,
  "roles": [
    "TECHNICAL",
    "SUPPORT"
  ],
  "salutationCode": "FRAU",
  "version": 3
}
```

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4/contacts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/block' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List the contact persons of an address (tenant:masterdata:read)

`GET /api/masterdata/addresses/{id}/contacts`

Module: Master data · operationId: `listContactPersons` · Tag: Contact persons · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

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

### Responses

- **200** Contact persons (`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 ContactPerson, required)
  - `aspNr` (integer): Number within the address; assigned
  - `availableFrom1` (string, nullable): Reachable from (HH:MM)
  - `availableFrom2` (string, nullable): Second time window: reachable from (HH:MM)
  - `availableTo1` (string, nullable): After `availableFrom1`
  - `availableTo2` (string, nullable): After `availableFrom2`
  - `birthday` (string (date), nullable): Birthday (YYYY-MM-DD)
  - `blockReason` (string, read-only): Reason of the block
  - `blockedAt` (string (date-time), read-only): Time of the block
  - `blockedBy` (string, read-only): Actor of the block
  - `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`.
  - `department` (string): Department
  - `doNotCall` (boolean): Do not call
  - `email1` (string (email)): First e-mail address
  - `email2` (string (email)): Second e-mail address
  - `emailOptOut` (boolean): No marketing e-mails
  - `fax` (string): E.164
  - `firstName` (string): First name (max length 128)
  - `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
  - `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
  - `id` (string (uuid)): Id of the contact person
  - `info` (string): Info text
  - `isActive` (boolean): False when `leftAt` is set (default `true`)
  - `isBlocked` (boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set with `POST /addresses/{id}/contacts/{cid}/block`
  - `isDefault` (boolean): Default contact of the address (at most one)
  - `languageCode` (string): Language (ISO 639-1)
  - `lastName` (string): Last name (max length 128)
  - `leftAt` (string (date), nullable): Date the person left the company; sets `isActive` false
  - `letterSalutation` (string): Salutation line of letters
  - `linkedinUrl` (string (uri)): LinkedIn profile (max length 255)
  - `mobile` (string): E.164
  - `namePrefix` (string): Name prefix
  - `nameSuffix` (string): Name suffix
  - `phone1` (string): E.164
  - `phone2` (string): E.164
  - `portalUserId` (string): Linked desk portal user (max length 255)
  - `position` (string): Position
  - `postalAddressAnsNr` (integer, nullable): `ansNr` of a postal address of the same address
  - `preferredChannel` (string): Preferred contact channel (one of `EMAIL`, `PHONE`, `MOBILE`, `LETTER`, `PORTAL`)
  - `reportsToAspNr` (integer, nullable): `aspNr` of the manager within the same address (no cycles)
  - `roles` (array of string): Roles in the buying centre or for ticket routing
  - `salutationCode` (string): Code of `salutations`
  - `timezone` (string): IANA time zone
  - `title` (string): Title
  - `version` (integer): Version of this contact (child updates)

Example 200 answer:

```json
{
  "items": [
    {
      "aspNr": 1,
      "email1": "georg.moser@alpenhotel-seeblick.example",
      "firstName": "Georg",
      "gdprConsent": "UNKNOWN",
      "id": "6a8c0e2a-4b6d-4f8a-9c0e-2a4b6d8f0a2c",
      "isActive": true,
      "isDefault": true,
      "lastName": "Moser",
      "letterSalutation": "Sehr geehrter Herr Moser",
      "phone1": "+49865298760",
      "position": "Geschäftsführer",
      "postalAddressAnsNr": 1,
      "roles": [
        "DECISION_MAKER"
      ],
      "salutationCode": "HERR",
      "version": 1
    },
    {
      "aspNr": 2,
      "availableFrom1": "08:00",
      "availableTo1": "16:00",
      "customFields": {},
      "doNotCall": false,
      "email1": "katrin.stadler@alpenhotel-seeblick.example",
      "emailOptOut": false,
      "firstName": "Katrin",
      "gdprConsent": "UNKNOWN",
      "id": "8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a",
      "isActive": true,
      "isBlocked": false,
      "isDefault": false,
      "languageCode": "de",
      "lastName": "Stadler",
      "letterSalutation": "Sehr geehrte Frau Stadler",
      "phone1": "+498652987612",
      "position": "Empfangsleitung und IT",
      "postalAddressAnsNr": 1,
      "preferredChannel": "PHONE",
      "roles": [
        "TECHNICAL",
        "SUPPORT"
      ],
      "salutationCode": "FRAU",
      "timezone": "Europe/Berlin",
      "version": 3
    }
  ]
}
```

### Example request

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

## Add a contact person (tenant:masterdata:write)

`POST /api/masterdata/addresses/{id}/contacts`

Module: Master data · operationId: `createContactPerson` · Tag: Contact persons · Auth: access token (`Authorization: Bearer <accessToken>`)

Adds a contact person; `aspNr` is assigned. Setting `isDefault` clears it on the other
contacts. Locks the address, bumps its version and emits `masterdata.address.updated`.

### Parameters

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

### Request body

`application/json` (required)

- `aspNr` (integer): Number within the address; assigned
- `availableFrom1` (string, nullable): Reachable from (HH:MM)
- `availableFrom2` (string, nullable): Second time window: reachable from (HH:MM)
- `availableTo1` (string, nullable): After `availableFrom1`
- `availableTo2` (string, nullable): After `availableFrom2`
- `birthday` (string (date), nullable): Birthday (YYYY-MM-DD)
- `blockReason` (string, read-only): Reason of the block
- `blockedAt` (string (date-time), read-only): Time of the block
- `blockedBy` (string, read-only): Actor of the block
- `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`.
- `department` (string): Department
- `doNotCall` (boolean): Do not call
- `email1` (string (email)): First e-mail address
- `email2` (string (email)): Second e-mail address
- `emailOptOut` (boolean): No marketing e-mails
- `fax` (string): E.164
- `firstName` (string): First name (max length 128)
- `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
- `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
- `id` (string (uuid)): Id of the contact person
- `info` (string): Info text
- `isActive` (boolean): False when `leftAt` is set (default `true`)
- `isBlocked` (boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set with `POST /addresses/{id}/contacts/{cid}/block`
- `isDefault` (boolean): Default contact of the address (at most one)
- `languageCode` (string): Language (ISO 639-1)
- `lastName` (string): Last name (max length 128)
- `leftAt` (string (date), nullable): Date the person left the company; sets `isActive` false
- `letterSalutation` (string): Salutation line of letters
- `linkedinUrl` (string (uri)): LinkedIn profile (max length 255)
- `mobile` (string): E.164
- `namePrefix` (string): Name prefix
- `nameSuffix` (string): Name suffix
- `phone1` (string): E.164
- `phone2` (string): E.164
- `portalUserId` (string): Linked desk portal user (max length 255)
- `position` (string): Position
- `postalAddressAnsNr` (integer, nullable): `ansNr` of a postal address of the same address
- `preferredChannel` (string): Preferred contact channel (one of `EMAIL`, `PHONE`, `MOBILE`, `LETTER`, `PORTAL`)
- `reportsToAspNr` (integer, nullable): `aspNr` of the manager within the same address (no cycles)
- `roles` (array of string): Roles in the buying centre or for ticket routing
- `salutationCode` (string): Code of `salutations`
- `timezone` (string): IANA time zone
- `title` (string): Title
- `version` (integer): Version of this contact (child updates)

Example:

```json
{
  "department": "Finanzen",
  "email1": "max.mustermann@muster.de",
  "firstName": "Max",
  "gdprConsent": "UNKNOWN",
  "lastName": "Mustermann",
  "phone1": "+49 30 1234568",
  "position": "Buchhaltung",
  "roles": [
    "BILLING"
  ],
  "salutationCode": "HERR",
  "version": 0
}
```

### Responses

- **201** Created (`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`)

Fields of the 201 answer:

- `aspNr` (integer): Number within the address; assigned
- `availableFrom1` (string, nullable): Reachable from (HH:MM)
- `availableFrom2` (string, nullable): Second time window: reachable from (HH:MM)
- `availableTo1` (string, nullable): After `availableFrom1`
- `availableTo2` (string, nullable): After `availableFrom2`
- `birthday` (string (date), nullable): Birthday (YYYY-MM-DD)
- `blockReason` (string, read-only): Reason of the block
- `blockedAt` (string (date-time), read-only): Time of the block
- `blockedBy` (string, read-only): Actor of the block
- `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`.
- `department` (string): Department
- `doNotCall` (boolean): Do not call
- `email1` (string (email)): First e-mail address
- `email2` (string (email)): Second e-mail address
- `emailOptOut` (boolean): No marketing e-mails
- `fax` (string): E.164
- `firstName` (string): First name (max length 128)
- `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
- `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
- `id` (string (uuid)): Id of the contact person
- `info` (string): Info text
- `isActive` (boolean): False when `leftAt` is set (default `true`)
- `isBlocked` (boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set with `POST /addresses/{id}/contacts/{cid}/block`
- `isDefault` (boolean): Default contact of the address (at most one)
- `languageCode` (string): Language (ISO 639-1)
- `lastName` (string): Last name (max length 128)
- `leftAt` (string (date), nullable): Date the person left the company; sets `isActive` false
- `letterSalutation` (string): Salutation line of letters
- `linkedinUrl` (string (uri)): LinkedIn profile (max length 255)
- `mobile` (string): E.164
- `namePrefix` (string): Name prefix
- `nameSuffix` (string): Name suffix
- `phone1` (string): E.164
- `phone2` (string): E.164
- `portalUserId` (string): Linked desk portal user (max length 255)
- `position` (string): Position
- `postalAddressAnsNr` (integer, nullable): `ansNr` of a postal address of the same address
- `preferredChannel` (string): Preferred contact channel (one of `EMAIL`, `PHONE`, `MOBILE`, `LETTER`, `PORTAL`)
- `reportsToAspNr` (integer, nullable): `aspNr` of the manager within the same address (no cycles)
- `roles` (array of string): Roles in the buying centre or for ticket routing
- `salutationCode` (string): Code of `salutations`
- `timezone` (string): IANA time zone
- `title` (string): Title
- `version` (integer): Version of this contact (child updates)
- `addressVersion` (integer, required): New version of the address

Example 201 answer:

```json
{
  "addressVersion": 8,
  "aspNr": 2,
  "email1": "katrin.stadler@alpenhotel-seeblick.example",
  "firstName": "Katrin",
  "gdprConsent": "UNKNOWN",
  "id": "8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a",
  "isActive": true,
  "isBlocked": false,
  "isDefault": false,
  "lastName": "Stadler",
  "letterSalutation": "Sehr geehrte Frau Stadler",
  "phone1": "+498652987612",
  "position": "Empfangsleitung und IT",
  "postalAddressAnsNr": 1,
  "roles": [
    "TECHNICAL",
    "SUPPORT"
  ],
  "salutationCode": "FRAU",
  "version": 3
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4/contacts' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"department":"Finanzen","email1":"max.mustermann@muster.de","firstName":"Max","gdprConsent":"UNKNOWN","lastName":"Mustermann","phone1":"+49 30 1234568","position":"Buchhaltung","roles":["BILLING"],"salutationCode":"HERR","version":0}'
```

## Replace a contact person (tenant:masterdata:write)

`PUT /api/masterdata/addresses/{id}/contacts/{cid}`

Module: Master data · operationId: `updateContactPerson` · Tag: Contact persons · Auth: access token (`Authorization: Bearer <accessToken>`)

The body carries the `version` of the contact person (not of the address); `aspNr` is kept. Bumps the address version and emits `masterdata.address.updated`.

### Parameters

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

### Request body

`application/json` (required)

- `aspNr` (integer): Number within the address; assigned
- `availableFrom1` (string, nullable): Reachable from (HH:MM)
- `availableFrom2` (string, nullable): Second time window: reachable from (HH:MM)
- `availableTo1` (string, nullable): After `availableFrom1`
- `availableTo2` (string, nullable): After `availableFrom2`
- `birthday` (string (date), nullable): Birthday (YYYY-MM-DD)
- `blockReason` (string, read-only): Reason of the block
- `blockedAt` (string (date-time), read-only): Time of the block
- `blockedBy` (string, read-only): Actor of the block
- `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`.
- `department` (string): Department
- `doNotCall` (boolean): Do not call
- `email1` (string (email)): First e-mail address
- `email2` (string (email)): Second e-mail address
- `emailOptOut` (boolean): No marketing e-mails
- `fax` (string): E.164
- `firstName` (string): First name (max length 128)
- `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
- `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
- `id` (string (uuid)): Id of the contact person
- `info` (string): Info text
- `isActive` (boolean): False when `leftAt` is set (default `true`)
- `isBlocked` (boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set with `POST /addresses/{id}/contacts/{cid}/block`
- `isDefault` (boolean): Default contact of the address (at most one)
- `languageCode` (string): Language (ISO 639-1)
- `lastName` (string): Last name (max length 128)
- `leftAt` (string (date), nullable): Date the person left the company; sets `isActive` false
- `letterSalutation` (string): Salutation line of letters
- `linkedinUrl` (string (uri)): LinkedIn profile (max length 255)
- `mobile` (string): E.164
- `namePrefix` (string): Name prefix
- `nameSuffix` (string): Name suffix
- `phone1` (string): E.164
- `phone2` (string): E.164
- `portalUserId` (string): Linked desk portal user (max length 255)
- `position` (string): Position
- `postalAddressAnsNr` (integer, nullable): `ansNr` of a postal address of the same address
- `preferredChannel` (string): Preferred contact channel (one of `EMAIL`, `PHONE`, `MOBILE`, `LETTER`, `PORTAL`)
- `reportsToAspNr` (integer, nullable): `aspNr` of the manager within the same address (no cycles)
- `roles` (array of string): Roles in the buying centre or for ticket routing
- `salutationCode` (string): Code of `salutations`
- `timezone` (string): IANA time zone
- `title` (string): Title
- `version` (integer): Version of this contact (child updates)

Example:

```json
{
  "aspNr": 2,
  "availableFrom1": "08:00",
  "availableTo1": "16:00",
  "customFields": {},
  "doNotCall": false,
  "email1": "katrin.stadler@alpenhotel-seeblick.example",
  "emailOptOut": false,
  "firstName": "Katrin",
  "gdprConsent": "UNKNOWN",
  "id": "8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a",
  "isActive": true,
  "isBlocked": false,
  "isDefault": false,
  "languageCode": "de",
  "lastName": "Stadler",
  "letterSalutation": "Sehr geehrte Frau Stadler",
  "phone1": "+498652987612",
  "position": "Empfangsleitung und IT",
  "postalAddressAnsNr": 1,
  "preferredChannel": "PHONE",
  "roles": [
    "TECHNICAL",
    "SUPPORT"
  ],
  "salutationCode": "FRAU",
  "timezone": "Europe/Berlin",
  "version": 3
}
```

### 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:

- `aspNr` (integer): Number within the address; assigned
- `availableFrom1` (string, nullable): Reachable from (HH:MM)
- `availableFrom2` (string, nullable): Second time window: reachable from (HH:MM)
- `availableTo1` (string, nullable): After `availableFrom1`
- `availableTo2` (string, nullable): After `availableFrom2`
- `birthday` (string (date), nullable): Birthday (YYYY-MM-DD)
- `blockReason` (string, read-only): Reason of the block
- `blockedAt` (string (date-time), read-only): Time of the block
- `blockedBy` (string, read-only): Actor of the block
- `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`.
- `department` (string): Department
- `doNotCall` (boolean): Do not call
- `email1` (string (email)): First e-mail address
- `email2` (string (email)): Second e-mail address
- `emailOptOut` (boolean): No marketing e-mails
- `fax` (string): E.164
- `firstName` (string): First name (max length 128)
- `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
- `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
- `id` (string (uuid)): Id of the contact person
- `info` (string): Info text
- `isActive` (boolean): False when `leftAt` is set (default `true`)
- `isBlocked` (boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set with `POST /addresses/{id}/contacts/{cid}/block`
- `isDefault` (boolean): Default contact of the address (at most one)
- `languageCode` (string): Language (ISO 639-1)
- `lastName` (string): Last name (max length 128)
- `leftAt` (string (date), nullable): Date the person left the company; sets `isActive` false
- `letterSalutation` (string): Salutation line of letters
- `linkedinUrl` (string (uri)): LinkedIn profile (max length 255)
- `mobile` (string): E.164
- `namePrefix` (string): Name prefix
- `nameSuffix` (string): Name suffix
- `phone1` (string): E.164
- `phone2` (string): E.164
- `portalUserId` (string): Linked desk portal user (max length 255)
- `position` (string): Position
- `postalAddressAnsNr` (integer, nullable): `ansNr` of a postal address of the same address
- `preferredChannel` (string): Preferred contact channel (one of `EMAIL`, `PHONE`, `MOBILE`, `LETTER`, `PORTAL`)
- `reportsToAspNr` (integer, nullable): `aspNr` of the manager within the same address (no cycles)
- `roles` (array of string): Roles in the buying centre or for ticket routing
- `salutationCode` (string): Code of `salutations`
- `timezone` (string): IANA time zone
- `title` (string): Title
- `version` (integer): Version of this contact (child updates)
- `addressVersion` (integer, required): New version of the address

Example 200 answer:

```json
{
  "addressVersion": 8,
  "aspNr": 2,
  "email1": "katrin.stadler@alpenhotel-seeblick.example",
  "firstName": "Katrin",
  "gdprConsent": "UNKNOWN",
  "id": "8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a",
  "isActive": true,
  "isBlocked": false,
  "isDefault": false,
  "lastName": "Stadler",
  "letterSalutation": "Sehr geehrte Frau Stadler",
  "phone1": "+498652987612",
  "position": "Empfangsleitung und IT",
  "postalAddressAnsNr": 1,
  "roles": [
    "TECHNICAL",
    "SUPPORT"
  ],
  "salutationCode": "FRAU",
  "version": 3
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4/contacts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"aspNr":2,"availableFrom1":"08:00","availableTo1":"16:00","customFields":{},"doNotCall":false,"email1":"katrin.stadler@alpenhotel-seeblick.example","emailOptOut":false,"firstName":"Katrin","gdprConsent":"UNKNOWN","id":"8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a","isActive":true,"isBlocked":false,"isDefault":false,"languageCode":"de","lastName":"Stadler","letterSalutation":"Sehr geehrte Frau Stadler","phone1":"+498652987612","position":"Empfangsleitung und IT","postalAddressAnsNr":1,"preferredChannel":"PHONE","roles":["TECHNICAL","SUPPORT"],"salutationCode":"FRAU","timezone":"Europe/Berlin","version":3}'
```

## Delete a contact person (tenant:masterdata:write)

`DELETE /api/masterdata/addresses/{id}/contacts/{cid}`

Module: Master data · operationId: `deleteContactPerson` · Tag: Contact persons · Auth: access token (`Authorization: Bearer <accessToken>`)

Bumps the address version and emits `masterdata.address.updated`.

### Parameters

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

### Responses

- **200** Deleted (`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:

- `addressVersion` (integer, required): New version of the address

Example 200 answer:

```json
{
  "addressVersion": 8
}
```

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4/contacts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Postal addresses

## 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"
```

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

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

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

Adds a postal address; `ansNr` is assigned. The first postal address of an address becomes
the default billing and shipping address. Bumps the address version and emits
`masterdata.address.updated`.

### Parameters

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

### 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
{
  "city": "Hamburg",
  "countryCode": "DE",
  "deliveryNote": "Anlieferung Tor 3",
  "isDefaultShipping": false,
  "name1": "Muster GmbH",
  "name2": "Lager Nord",
  "postalCode": "22113",
  "street": "Industriestraße 12",
  "version": 0
}
```

### Responses

- **201** Created (`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`)

Fields of the 201 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 201 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 POST 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4/postal-addresses' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"city":"Hamburg","countryCode":"DE","deliveryNote":"Anlieferung Tor 3","isDefaultShipping":false,"name1":"Muster GmbH","name2":"Lager Nord","postalCode":"22113","street":"Industriestraße 12","version":0}'
```

## 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}'
```

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

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

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

The default billing or shipping address cannot be deleted (`409`). 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 |

### Responses

- **200** Deleted (`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:

- `addressVersion` (integer, required): New version of the address

Example 200 answer:

```json
{
  "addressVersion": 8
}
```

### Example request

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

## 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"
```

## Suggest the streets of a postal code (tenant:masterdata:read)

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

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

Street names of a postal code from OpenPLZ that start with `q` (case-insensitive, `ß` = `ss`,
`str.` = `straße`), at most 50. Countries and errors as in `listPostalLocalities`.

### 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) |
| `q` | query | string |  | Beginning of the street name; empty lists all (max length 128) |

### Responses

- **200** Street names (`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 string, required)

Example 200 answer:

```json
{
  "items": [
    "Marienplatz",
    "Marienstr."
  ]
}
```

### Example request

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

# VAT checks

## Check the VAT ID of an address (tenant:masterdata:write)

`POST /api/masterdata/addresses/{id}/vat-check`

Module: Master data · operationId: `checkAddressVatId` · Tag: VAT checks · Auth: access token (`Authorization: Bearer <accessToken>`)

Checks the address's `vatId` and stores the result as a protocol entry; the address gets
`vatCheckStatus` and `vatCheckedAt` (its version is not bumped). A simple check asks VIES (EU
Commission; also German VAT IDs; with the tenant's own VAT ID from the company profile as
requester when set, so VIES returns a consultation number). A qualified check asks the BZSt
eVatR service (needs the own VAT ID) and also sends company name, street, postal code and city of
the main postal address; it returns a match result per field. BZSt checks German VAT IDs only
formally, so a qualified check of a German VAT ID without `method` is a simple VIES check
(`qualified: false`). Greek VAT IDs are checked with the prefix `EL` (`GR` is accepted). The body
may be empty (simple check).

A conclusive result (not `TECHNICAL_ERROR` or `CHECK_NOT_POSSIBLE`) answers the same request
(VAT IDs, method and, when qualified, the sent name and address) of the tenant for 24 hours
without calling VIES or BZSt (`cached: true`); `force: true` skips the cache. A cached result
for another address is stored as its own protocol entry with `sourceCheckId` and the source's
`checkedAt`. The address shows the newest check; an inconclusive one never replaces a conclusive
status, and changing the address's VAT ID clears it. A call to VIES or BZSt that outlasts the
request is still finished and stored (up to 45 s); concurrent identical checks of an address
share one call. Technical failures are stored and returned as status `TECHNICAL_ERROR` with `200`; when the service or
the member state is unavailable (e.g. a maintenance window) `serviceUnavailable` is `true` and
`retryAfter` suggests when to try again. `503` (`vat_check_unavailable`) when the check is
switched off. Emits `masterdata.address.vat_checked`.

### Parameters

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

### Request body

`application/json`

- `force` (boolean): Skip the 24 h cache and ask the service again (default `false`)
- `method` (string): Service to ask; default `vies` for a simple, `bzst` for a qualified check (German VAT IDs: `vies`, simple). VIES offers no qualified check: `400` (one of `vies`, `bzst`)
- `qualified` (boolean): Qualified BZSt confirmation: also send company name, street, postal code and city of the main postal address (default `false`)

Example:

```json
{
  "force": true,
  "qualified": true
}
```

### Responses

- **200** The stored check (`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`)
- **503** The VAT check is switched off (`application/json`)

Fields of the 200 answer:

- `cached` (boolean, required): The answer came from the 24 h cache (no call to VIES or BZSt)
- `checkedAt` (string (date-time), required): Time of the check
- `checkedBy` (string, required): Who ran the check (subject of the token)
- `id` (string (uuid), required): Id of the protocol entry
- `method` (string, required): Service that answered (one of `VIES`, `BZST`)
- `ownVatId` (string, required): The tenant's VAT ID used for the request (may be empty for VIES)
- `qualified` (boolean, required): Qualified check (name and postal address sent)
- `status` (VatCheckStatus, required): `OFFICIALLY_CONFIRMED` (valid), `PARTIALLY_CONFIRMED` (valid, some qualified data differs), `OFFICIALLY_NOT_CONFIRMED` (invalid), `FORMALLY_VALID_NO_OFFICIAL_CHECK` (German VAT ID in a qualified BZSt check: valid format only, BZSt does not confirm German IDs), `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`, `NOT_CHECKED`. (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`, `NOT_CHECKED`)
- `statusDisplay` (string, required): German display text
- `vatId` (string, required): Checked VAT ID
- `addressId` (string (uuid)): Absent for checks of a service without address
- `cityMatch` (VatMatch): Qualified result per field: A match, B mismatch, C not queried, D not provided by the member state (one of `A`, `B`, `C`, `D`)
- `companyNameMatch` (VatMatch): Qualified result per field: A match, B mismatch, C not queried, D not provided by the member state (one of `A`, `B`, `C`, `D`)
- `officialRequestId` (string): Request id of BZSt or consultation number of VIES (evidence)
- `retryAfter` (string (date-time)): Suggested time for a new attempt when `serviceUnavailable`
- `serviceUnavailable` (boolean): VIES
- `sourceCheckId` (string (uuid)): The check whose cached result this entry repeats
- `statusCode` (string): Status code of the service: BZSt `evatr-*`, VIES `VIES_VALID`, `VIES_INVALID` or its error code (e.g. `MS_UNAVAILABLE`), `TECHNICAL_ERROR` for a failed connection
- `statusMessage` (string): Message of the service
- `streetMatch` (VatMatch): Qualified result per field: A match, B mismatch, C not queried, D not provided by the member state (one of `A`, `B`, `C`, `D`)
- `validFrom` (string (date)): Validity start reported by the service (YYYY-MM-DD)
- `validTill` (string (date)): Validity end reported by the service (YYYY-MM-DD)
- `zipMatch` (VatMatch): Qualified result per field: A match, B mismatch, C not queried, D not provided by the member state (one of `A`, `B`, `C`, `D`)

Example 200 answer:

```json
{
  "addressId": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
  "cached": false,
  "checkedAt": "2026-11-03T09:14:22Z",
  "checkedBy": "christina.adler@muster-it.example",
  "id": "1f3b5d7f-9a1c-4e3b-8d5f-7a9c1e3b5d7f",
  "method": "VIES",
  "officialRequestId": "WAPIAAAAZ3hT2k9Q",
  "ownVatId": "DE999000111",
  "qualified": false,
  "status": "OFFICIALLY_CONFIRMED",
  "statusCode": "VALID",
  "statusDisplay": "Gültig",
  "statusMessage": "Die USt-IdNr. ist laut VIES gültig.",
  "vatId": "DE811234567"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4/vat-check' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"force":true,"qualified":true}'
```

## List the VAT check history of an address (tenant:masterdata:read)

`GET /api/masterdata/addresses/{id}/vat-checks`

Module: Master data · operationId: `listAddressVatChecks` · Tag: VAT checks · Auth: access token (`Authorization: Bearer <accessToken>`)

Newest first. `limit` above 200 or below 1 is rejected with `400`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer |  | (default `50`; max 200) |
| `offset` | query | integer |  | Entries to skip; a negative or non-numeric value is `400 invalid` (default `0`) |
| `id` | path | string (uuid) | yes |  |

### Responses

- **200** One page of checks (`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`)

Fields of the 200 answer:

- `items` (array of VatCheck, required): Checks, newest first
  - `cached` (boolean, required): The answer came from the 24 h cache (no call to VIES or BZSt)
  - `checkedAt` (string (date-time), required): Time of the check
  - `checkedBy` (string, required): Who ran the check (subject of the token)
  - `id` (string (uuid), required): Id of the protocol entry
  - `method` (string, required): Service that answered (one of `VIES`, `BZST`)
  - `ownVatId` (string, required): The tenant's VAT ID used for the request (may be empty for VIES)
  - `qualified` (boolean, required): Qualified check (name and postal address sent)
  - `status` (VatCheckStatus, required): `OFFICIALLY_CONFIRMED` (valid), `PARTIALLY_CONFIRMED` (valid, some qualified data differs), `OFFICIALLY_NOT_CONFIRMED` (invalid), `FORMALLY_VALID_NO_OFFICIAL_CHECK` (German VAT ID in a qualified BZSt check: valid format only, BZSt does not confirm German IDs), `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`, `NOT_CHECKED`. (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`, `NOT_CHECKED`)
  - `statusDisplay` (string, required): German display text
  - `vatId` (string, required): Checked VAT ID
  - `addressId` (string (uuid)): Absent for checks of a service without address
  - `cityMatch` (VatMatch): Qualified result per field: A match, B mismatch, C not queried, D not provided by the member state (one of `A`, `B`, `C`, `D`)
  - `companyNameMatch` (VatMatch): Qualified result per field: A match, B mismatch, C not queried, D not provided by the member state (one of `A`, `B`, `C`, `D`)
  - `officialRequestId` (string): Request id of BZSt or consultation number of VIES (evidence)
  - `retryAfter` (string (date-time)): Suggested time for a new attempt when `serviceUnavailable`
  - `serviceUnavailable` (boolean): VIES
  - `sourceCheckId` (string (uuid)): The check whose cached result this entry repeats
  - `statusCode` (string): Status code of the service: BZSt `evatr-*`, VIES `VIES_VALID`, `VIES_INVALID` or its error code (e.g. `MS_UNAVAILABLE`), `TECHNICAL_ERROR` for a failed connection
  - `statusMessage` (string): Message of the service
  - `streetMatch` (VatMatch): Qualified result per field: A match, B mismatch, C not queried, D not provided by the member state (one of `A`, `B`, `C`, `D`)
  - `validFrom` (string (date)): Validity start reported by the service (YYYY-MM-DD)
  - `validTill` (string (date)): Validity end reported by the service (YYYY-MM-DD)
  - `zipMatch` (VatMatch): Qualified result per field: A match, B mismatch, C not queried, D not provided by the member state (one of `A`, `B`, `C`, `D`)
- `total` (integer, required): Number of checks of the address

Example 200 answer:

```json
{
  "items": [
    {
      "addressId": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
      "cached": false,
      "checkedAt": "2026-11-03T09:14:22Z",
      "checkedBy": "christina.adler@muster-it.example",
      "id": "1f3b5d7f-9a1c-4e3b-8d5f-7a9c1e3b5d7f",
      "method": "VIES",
      "officialRequestId": "WAPIAAAAZ3hT2k9Q",
      "ownVatId": "DE999000111",
      "qualified": false,
      "status": "OFFICIALLY_CONFIRMED",
      "statusCode": "VALID",
      "statusDisplay": "Gültig",
      "statusMessage": "Die USt-IdNr. ist laut VIES gültig.",
      "vatId": "DE811234567"
    }
  ],
  "total": 1
}
```

### Example request

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

# Distributor IDs

## List distributor IDs (tenant:masterdata:read)

`GET /api/masterdata/distributor-ids`

Module: Master data · operationId: `listDistributorIds` · Tag: Distributor IDs · Auth: access token (`Authorization: Bearer <accessToken>`)

Ordered by source and distributor ID. An invalid `source` returns an empty list.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `source` | query | string |  | Only this distributor source |

### Responses

- **200** Distributor IDs (`application/json`)
- **401** Missing, invalid or expired token (empty body)
- **403** The token lacks the permission or carries no tenant (`application/json`)

Fields of the 200 answer:

- `items` (array of DistributorID, required)
  - `addressId` (string (uuid), required): Supplier address the distributor ID maps to
  - `addressName` (string, required): Display name of that address
  - `adrNr` (string, required): Address number of that address
  - `distributorId` (string, required): The distributor's own ID
  - `source` (string, required): Distributor (lower case, e.g. egis, ingram)
  - `updatedAt` (string (date-time), required): Time of the last change
  - `distributorName` (string): Name of the distributor

Example 200 answer:

```json
{
  "items": [
    {
      "addressId": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
      "addressName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
      "adrNr": "10001",
      "distributorId": "700123",
      "distributorName": "EGIS Computer Service-Center GmbH",
      "source": "egis",
      "updatedAt": "2026-05-20T11:40:00Z"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/masterdata/distributor-ids' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Assign a distributor ID to an address (tenant:masterdata:write)

`PUT /api/masterdata/distributor-ids/{source}/{distributorId}`

Module: Master data · operationId: `assignDistributorId` · Tag: Distributor IDs · Auth: access token (`Authorization: Bearer <accessToken>`)

Links the distributor ID with the address; an ID already linked with another address moves to the new one. An omitted `distributorName` keeps the stored name. Emits `masterdata.distributor_id.assigned`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `source` | path | string | yes | Distributor source, lower-case (`egis`, `ingram`, `infinigate`, `amazon`, …) |
| `distributorId` | path | string | yes | The distributor's own supplier ID (matched case-insensitively) (max length 64) |

### Request body

`application/json` (required)

- `addressId` (string (uuid), required): Supplier address the distributor stands for
- `distributorName` (string): Name of the distributor (kept when empty) (max length 255)

Example:

```json
{
  "addressId": "3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4",
  "distributorName": "EGIS Computer Service-Center GmbH"
}
```

### Responses

- **200** Assigned (`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`)

Fields of the 200 answer:

- `addressId` (string (uuid), required): Supplier address the distributor ID maps to
- `addressName` (string, required): Display name of that address
- `adrNr` (string, required): Address number of that address
- `distributorId` (string, required): The distributor's own ID
- `source` (string, required): Distributor (lower case, e.g. egis, ingram)
- `updatedAt` (string (date-time), required): Time of the last change
- `distributorName` (string): Name of the distributor

Example 200 answer:

```json
{
  "addressId": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
  "addressName": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
  "adrNr": "10001",
  "distributorId": "700123",
  "distributorName": "EGIS Computer Service-Center GmbH",
  "source": "egis",
  "updatedAt": "2026-05-20T11:40:00Z"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/masterdata/distributor-ids/egis/700123' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"addressId":"3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4","distributorName":"EGIS Computer Service-Center GmbH"}'
```

## Remove a distributor ID (tenant:masterdata:write)

`DELETE /api/masterdata/distributor-ids/{source}/{distributorId}`

Module: Master data · operationId: `removeDistributorId` · Tag: Distributor IDs · Auth: access token (`Authorization: Bearer <accessToken>`)

Emits `masterdata.distributor_id.removed`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `source` | path | string | yes | Distributor source, lower-case (`egis`, `ingram`, `infinigate`, `amazon`, …) |
| `distributorId` | path | string | yes | The distributor's own supplier ID (matched case-insensitively) (max length 64) |

### Responses

- **204** Removed
- **400** Invalid input (`invalid`); `field` names the first, `details.fields` each invalid field (`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`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/masterdata/distributor-ids/egis/700123' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Articles

## List articles (tenant:masterdata:read)

`GET /api/masterdata/products`

Module: Master data · operationId: `listProducts` · Tag: Articles · Auth: access token (`Authorization: Bearer <accessToken>`)

Returns one page of compact article rows. `q` searches article number, search term, short name, name,
manufacturer part number and EAN (case-insensitive substring). `netPrice` is the sales price (`salesPrice`),
`purchasePrice` the price of the default supplier. `incomplete` marks articles that miss a field their
type requires (see `Product`); they stay readable but must be completed before they can be saved.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `q` | query | string |  | Search text |
| `search` | query | string |  | Alias of `q` (used when `q` is empty) |
| `groupId` | query | string (uuid) |  | Only articles of this product group (an invalid id matches nothing) |
| `type` | query | string |  | Comma-separated article types |
| `blocked` | query | string |  | `true` only blocked, `false` only unblocked articles (one of `true`, `false`) |
| `incomplete` | query | string |  | `true` only articles missing a field their type requires (TEXT articles never are), `false` only complete ones (one of `true`, `false`) |
| `sort` | query | string |  | Sort key, prefix `-` for descending; `name` sorts by the short name. Unknown keys sort by article number. (one of `articleNumber`, `-articleNumber`, `name`, `-name`, `price`, `-price`, `purchasePrice`, `-purchasePrice`, `group`, `-group`, `updatedAt`, `-updatedAt`, `createdAt`, `-createdAt`; default `"articleNumber"`) |
| `limit` | query | integer |  | Page size 1–200; any other value is `400 invalid` (default `50`; max 200) |
| `cursor` | query | string |  | `nextCursor` of the previous page; leave out for the first page. Keep `sort` and the filters unchanged while paging: a cursor of another sort or an altered one is `400 invalid` (`field: cursor`). (max length 1024) |

### Responses

- **200** One page of articles (`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`)

Fields of the 200 answer:

- `items` (array of ProductListItem, required): One page of articles
  - `articleNumber` (string, required): Article number
  - `articleType` (string, required): Article type (one of `GOODS`, `SERVICE`, `SUBSCRIPTION`, `TEXT`, `FEE`)
  - `id` (string (uuid), required): Id of the article
  - `incomplete` (boolean, required): The article misses a field its type requires (group
  - `isBlocked` (boolean, required): Blocked article
  - `name` (string, required): Name as stored (may be empty or span lines); lists show `shortName`
  - `shortName` (string, required): Short name (Kurzbezeichnung)
  - `updatedAt` (string (date-time), required): Time of the last change
  - `version` (integer, required): Optimistic locking version
  - `ean` (string): EAN/GTIN
  - `manufacturerPartNumber` (string): Manufacturer part number (MPN)
  - `netPrice` (number): Net sales price (`salesPrice`)
  - `productGroupId` (string (uuid)): Product group
  - `productGroupName` (string): Name of the product group
  - `purchasePrice` (number): Price of the default supplier
  - `unitCode` (string): Code of `units`
- `total` (integer, required): Number of matching articles
- `nextCursor` (string): Cursor of the next page (pass it as `cursor`); missing on the last page

Example 200 answer:

```json
{
  "items": [
    {
      "articleNumber": "HW-1004",
      "articleType": "GOODS",
      "ean": "4061234500045",
      "id": "6e8a0c2e-4f6a-4b8c-8d0e-2f4a6c8e0a2c",
      "incomplete": false,
      "isBlocked": false,
      "manufacturerPartNumber": "NL-DOCKC100",
      "name": "USB-C Dockingstation 100 W",
      "netPrice": 189,
      "productGroupId": "8d0b6f3e-2c4a-4e7b-9a1d-5f3c2e1b0a97",
      "productGroupName": "Hardware",
      "purchasePrice": 139,
      "shortName": "USB-C Dockingstation 100 W",
      "unitCode": "STK",
      "updatedAt": "2026-10-07T13:12:00Z",
      "version": 4
    }
  ],
  "total": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/masterdata/products' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create an article (tenant:masterdata:write)

`POST /api/masterdata/products`

Module: Master data · operationId: `createProduct` · Tag: Articles · Auth: access token (`Authorization: Bearer <accessToken>`)

Stores a new article with its sales price and suppliers. An empty `articleNumber` is assigned from
the `PRODUCT` number range, an empty `searchTerm` is derived from the short name, an empty
`articleType` is `GOODS`, a `priceQuantity` of 0 is 1. `shortName` is required; GOODS, SERVICE and FEE
also need `productGroupId`, `unitCode`, `taxKeyCode` and `salesPrice` (0 is allowed; unit and tax key may
come from the product group), SUBSCRIPTION in addition `svcBilling` (not NONE), `svcBillingCycleMonths`
and `svcTermMonths`. TEXT articles need nothing; their group, tax key and prices are cleared. A missing
field answers `400` naming it. The first supplier becomes the default supplier. Emits
`masterdata.product.created`.

### Request body

`application/json` (required)

- `shortName` (string, required): Kurzbezeichnung: required, one line (no line breaks); the name in lists, pickers and trade records (max length 80)
- `accounting` (object, read-only): Resolved revenue account and cost center (only on the single article, not in lists)
- `articleNumber` (string): Unique per tenant; assigned from the PRODUCT range when empty (max length 64)
- `articleType` (string): Article type; decides the required fields (one of `GOODS`, `SERVICE`, `SUBSCRIPTION`, `TEXT`, `FEE`; default `"GOODS"`)
- `basePriceUnit` (string): Unit of the base price
- `blockReason` (string): Reason of the block (max length 255)
- `blockedFrom` (string (date), nullable): First day of the block (YYYY-MM-DD)
- `blockedUntil` (string (date), nullable): After `blockedFrom`
- `commissionRate` (number, nullable): Commission in percent
- `contentQuantity` (number, nullable): Content quantity (for the base price)
- `contentUnit` (string): Unit of the content quantity
- `createdAt` (string (date-time), read-only): Creation time
- `createdBy` (string, read-only): Who created the article (subject of the token)
- `customerNo` (string, read-only): Tenant customer number (from the token)
- `customsTariffNo` (string): Customs tariff number
- `defaultSupplierId` (string (uuid), read-only): Id of the default supplier link
- `defaultWarehouseCode` (string): Default warehouse
- `description` (string): Beschreibung: long text without limit
- `dimensionUnit` (string): Unit of length, width and height (one of `MM`, `CM`, `M`)
- `ean` (string): EAN/GTIN with 8, 12, 13 or 14 digits and check digit
- `height` (number, nullable): Height in `dimensionUnit`
- `id` (string (uuid), read-only): Id of the article
- `isBatchTracked` (boolean): Only for GOODS
- `isBlocked` (boolean): Blocked article
- `isCommissionEligible` (boolean): Commission is paid
- `isDiscountEligible` (boolean): Discounts may be granted
- `isSerialTracked` (boolean): Only for GOODS
- `isSkontoEligible` (boolean): Cash discount (Skonto) may be granted
- `isStockItem` (boolean): Only for GOODS
- `length` (number, nullable): Length in `dimensionUnit`
- `manufacturerAddressId` (string (uuid), nullable): Manufacturer address
- `manufacturerName` (string): Manufacturer name (max length 255)
- `manufacturerPartNumber` (string): Manufacturer part number (MPN) (max length 64)
- `memo` (string): Internal memo
- `minPrice` (number, nullable): Lowest net price the article may be sold for; not above `salesPrice`
- `name` (string): Bezeichnung: optional, may span several lines; documents use `shortName` when empty (max length 2000)
- `originCountryCode` (string): Country of origin (ISO 3166-1 alpha-2)
- `priceQuantity` (number): Quantity the sales price refers to (default `1`)
- `productGroupId` (string (uuid), nullable): Required except for TEXT (cleared there)
- `productGroupName` (string, read-only): Name of the product group
- `purchasePrice` (number, read-only): Purchase price of the default supplier
- `salesPrice` (number, nullable): Net sales price per `priceQuantity`; required (0 is allowed) except for TEXT (cleared there)
- `searchTerm` (string): Upper-cased short name (first 255 characters) when empty (max length 255)
- `specialPrice` (number, nullable): Net special price; not below `minPrice` and not above `salesPrice`
- `specialValidFrom` (string (date), nullable): First day of the special price (dropped without `specialPrice`)
- `specialValidTo` (string (date), nullable): Last day of the special price; not before `specialValidFrom`
- `suppliers` (array of ProductSupplier): Suppliers with one purchase price each
  - `purchasePrice` (number, required): Net purchase price
  - `supplierAddressId` (string (uuid), required): Supplier address; once per article
  - `currencyCode` (string): Currency of the purchase price (ISO 4217)
  - `deliveryDays` (integer, nullable): Delivery time in days
  - `id` (string (uuid)): Id of the supplier link
  - `isDefault` (boolean): At most one; the first supplier is the default when none is set
  - `lastPurchaseAt` (string (date), nullable): Date of the last purchase (YYYY-MM-DD)
  - `minOrderQty` (number, nullable): Minimum order quantity
  - `orderUnitCode` (string): Order unit (code of `units`)
  - `supplierArticleNumber` (string): The supplier's article number (max length 64)
  - `supplierName` (string, read-only): Display name of the supplier address
- `svcAutoRenew` (boolean): Subscription renews automatically
- `svcBilling` (string): Must not be NONE for SUBSCRIPTION (one of `NONE`, `ADVANCE`, `ARREARS`; default `"NONE"`)
- `svcBillingCycleMonths` (integer, nullable): Billing cycle; required for SUBSCRIPTION (max 120)
- `svcNoticePeriodMonths` (integer, nullable): Notice period of the subscription in months
- `svcTermMonths` (integer, nullable): Subscription term; required for SUBSCRIPTION
- `syncStatus` (string, read-only): Reserved for an ERP synchronisation; STANDALONE for records of this API (one of `STANDALONE`, `PENDING_CREATION`, `PENDING_UPDATE`, `SYNCED`, `CONFLICT`, `ERROR`)
- `taxKeyCode` (string): Code of `tax-keys`; empty takes the product group's default tax key; required except for TEXT (cleared there)
- `tenantName` (string, read-only): Tenant name (from the token)
- `unitCode` (string): Code of `units`; empty takes the product group's default unit; required except for TEXT
- `updatedAt` (string (date-time), read-only): Time of the last change
- `updatedBy` (string, read-only): Who changed the article last (subject of the token)
- `version` (integer): Optimistic locking version (ignored on create)
- `weightKg` (number, nullable): Weight in kg
- `width` (number, nullable): Width in `dimensionUnit`

Example:

```json
{
  "articleType": "GOODS",
  "ean": "5397184440988",
  "isStockItem": true,
  "manufacturerName": "Dell",
  "manufacturerPartNumber": "P2422H",
  "name": "Monitor 24\" Full HD\nIPS, 75 Hz, HDMI und DisplayPort",
  "productGroupId": "8d0b6f3e-2c4a-4e7b-9a1d-5f3c2e1b0a97",
  "salesPrice": 189,
  "shortName": "Monitor 24\" Full HD",
  "suppliers": [
    {
      "currencyCode": "EUR",
      "isDefault": true,
      "purchasePrice": 142.5,
      "supplierAddressId": "3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4",
      "supplierArticleNumber": "700-P2422H"
    }
  ],
  "taxKeyCode": "STANDARD",
  "unitCode": "STK"
}
```

### Responses

- **201** Created (`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`)
- **409** Stale version or conflict with existing data (`application/json`)
- **413** The body is over the limit (2 MiB; AI drafts 4 MiB) (`application/json`)

Fields of the 201 answer:

- `shortName` (string, required): Kurzbezeichnung: required, one line (no line breaks); the name in lists, pickers and trade records (max length 80)
- `accounting` (object, read-only): Resolved revenue account and cost center (only on the single article, not in lists)
- `articleNumber` (string): Unique per tenant; assigned from the PRODUCT range when empty (max length 64)
- `articleType` (string): Article type; decides the required fields (one of `GOODS`, `SERVICE`, `SUBSCRIPTION`, `TEXT`, `FEE`; default `"GOODS"`)
- `basePriceUnit` (string): Unit of the base price
- `blockReason` (string): Reason of the block (max length 255)
- `blockedFrom` (string (date), nullable): First day of the block (YYYY-MM-DD)
- `blockedUntil` (string (date), nullable): After `blockedFrom`
- `commissionRate` (number, nullable): Commission in percent
- `contentQuantity` (number, nullable): Content quantity (for the base price)
- `contentUnit` (string): Unit of the content quantity
- `createdAt` (string (date-time), read-only): Creation time
- `createdBy` (string, read-only): Who created the article (subject of the token)
- `customerNo` (string, read-only): Tenant customer number (from the token)
- `customsTariffNo` (string): Customs tariff number
- `defaultSupplierId` (string (uuid), read-only): Id of the default supplier link
- `defaultWarehouseCode` (string): Default warehouse
- `description` (string): Beschreibung: long text without limit
- `dimensionUnit` (string): Unit of length, width and height (one of `MM`, `CM`, `M`)
- `ean` (string): EAN/GTIN with 8, 12, 13 or 14 digits and check digit
- `height` (number, nullable): Height in `dimensionUnit`
- `id` (string (uuid), read-only): Id of the article
- `isBatchTracked` (boolean): Only for GOODS
- `isBlocked` (boolean): Blocked article
- `isCommissionEligible` (boolean): Commission is paid
- `isDiscountEligible` (boolean): Discounts may be granted
- `isSerialTracked` (boolean): Only for GOODS
- `isSkontoEligible` (boolean): Cash discount (Skonto) may be granted
- `isStockItem` (boolean): Only for GOODS
- `length` (number, nullable): Length in `dimensionUnit`
- `manufacturerAddressId` (string (uuid), nullable): Manufacturer address
- `manufacturerName` (string): Manufacturer name (max length 255)
- `manufacturerPartNumber` (string): Manufacturer part number (MPN) (max length 64)
- `memo` (string): Internal memo
- `minPrice` (number, nullable): Lowest net price the article may be sold for; not above `salesPrice`
- `name` (string): Bezeichnung: optional, may span several lines; documents use `shortName` when empty (max length 2000)
- `originCountryCode` (string): Country of origin (ISO 3166-1 alpha-2)
- `priceQuantity` (number): Quantity the sales price refers to (default `1`)
- `productGroupId` (string (uuid), nullable): Required except for TEXT (cleared there)
- `productGroupName` (string, read-only): Name of the product group
- `purchasePrice` (number, read-only): Purchase price of the default supplier
- `salesPrice` (number, nullable): Net sales price per `priceQuantity`; required (0 is allowed) except for TEXT (cleared there)
- `searchTerm` (string): Upper-cased short name (first 255 characters) when empty (max length 255)
- `specialPrice` (number, nullable): Net special price; not below `minPrice` and not above `salesPrice`
- `specialValidFrom` (string (date), nullable): First day of the special price (dropped without `specialPrice`)
- `specialValidTo` (string (date), nullable): Last day of the special price; not before `specialValidFrom`
- `suppliers` (array of ProductSupplier): Suppliers with one purchase price each
  - `purchasePrice` (number, required): Net purchase price
  - `supplierAddressId` (string (uuid), required): Supplier address; once per article
  - `currencyCode` (string): Currency of the purchase price (ISO 4217)
  - `deliveryDays` (integer, nullable): Delivery time in days
  - `id` (string (uuid)): Id of the supplier link
  - `isDefault` (boolean): At most one; the first supplier is the default when none is set
  - `lastPurchaseAt` (string (date), nullable): Date of the last purchase (YYYY-MM-DD)
  - `minOrderQty` (number, nullable): Minimum order quantity
  - `orderUnitCode` (string): Order unit (code of `units`)
  - `supplierArticleNumber` (string): The supplier's article number (max length 64)
  - `supplierName` (string, read-only): Display name of the supplier address
- `svcAutoRenew` (boolean): Subscription renews automatically
- `svcBilling` (string): Must not be NONE for SUBSCRIPTION (one of `NONE`, `ADVANCE`, `ARREARS`; default `"NONE"`)
- `svcBillingCycleMonths` (integer, nullable): Billing cycle; required for SUBSCRIPTION (max 120)
- `svcNoticePeriodMonths` (integer, nullable): Notice period of the subscription in months
- `svcTermMonths` (integer, nullable): Subscription term; required for SUBSCRIPTION
- `syncStatus` (string, read-only): Reserved for an ERP synchronisation; STANDALONE for records of this API (one of `STANDALONE`, `PENDING_CREATION`, `PENDING_UPDATE`, `SYNCED`, `CONFLICT`, `ERROR`)
- `taxKeyCode` (string): Code of `tax-keys`; empty takes the product group's default tax key; required except for TEXT (cleared there)
- `tenantName` (string, read-only): Tenant name (from the token)
- `unitCode` (string): Code of `units`; empty takes the product group's default unit; required except for TEXT
- `updatedAt` (string (date-time), read-only): Time of the last change
- `updatedBy` (string, read-only): Who changed the article last (subject of the token)
- `version` (integer): Optimistic locking version (ignored on create)
- `weightKg` (number, nullable): Weight in kg
- `width` (number, nullable): Width in `dimensionUnit`

Example 201 answer:

```json
{
  "accounting": {
    "costCenter": "4200",
    "costCenterSource": "GROUP",
    "revenueAccount": "4400",
    "source": "GROUP",
    "sourceGroupCode": "HARDWARE",
    "taxKeyCode": "STANDARD"
  },
  "articleNumber": "HW-1004",
  "articleType": "GOODS",
  "createdAt": "2026-01-02T08:00:00Z",
  "createdBy": "laura.kaestner@muster-it.example",
  "customerNo": "99999",
  "defaultSupplierId": "7a9c1e3a-5b7d-4f9a-8c1e-3a5b7d9f1a3c",
  "ean": "4061234500045",
  "id": "6e8a0c2e-4f6a-4b8c-8d0e-2f4a6c8e0a2c",
  "isBatchTracked": false,
  "isBlocked": false,
  "isCommissionEligible": false,
  "isDiscountEligible": true,
  "isSerialTracked": false,
  "isSkontoEligible": true,
  "isStockItem": true,
  "manufacturerName": "Nordlicht IT-Distribution",
  "manufacturerPartNumber": "NL-DOCKC100",
  "name": "USB-C Dockingstation 100 W\n2 × DisplayPort, HDMI, 4 × USB-A, Gigabit-LAN",
  "priceQuantity": 1,
  "productGroupId": "8d0b6f3e-2c4a-4e7b-9a1d-5f3c2e1b0a97",
  "productGroupName": "Hardware",
  "purchasePrice": 139,
  "salesPrice": 189,
  "searchTerm": "DOCKINGSTATION USB-C",
  "shortName": "USB-C Dockingstation 100 W",
  "suppliers": [
    {
      "currencyCode": "EUR",
      "deliveryDays": 2,
      "id": "9c1e3a5c-7d9f-4b1c-8e3a-5c7d9f1b3c5e",
      "isDefault": true,
      "lastPurchaseAt": "2026-09-23",
      "minOrderQty": 1,
      "orderUnitCode": "STK",
      "purchasePrice": 139,
      "supplierAddressId": "7a9c1e3a-5b7d-4f9a-8c1e-3a5b7d9f1a3c",
      "supplierArticleNumber": "NL-DOCKC100",
      "supplierName": "Nordlicht IT-Distribution GmbH"
    }
  ],
  "svcBilling": "NONE",
  "syncStatus": "STANDALONE",
  "taxKeyCode": "STANDARD",
  "tenantName": "DEMO",
  "unitCode": "STK",
  "updatedAt": "2026-10-07T13:12:00Z",
  "updatedBy": "laura.kaestner@muster-it.example",
  "version": 4,
  "weightKg": 0.48
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/masterdata/products' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"articleType":"GOODS","ean":"5397184440988","isStockItem":true,"manufacturerName":"Dell","manufacturerPartNumber":"P2422H","name":"Monitor 24\" Full HD\nIPS, 75 Hz, HDMI und DisplayPort","productGroupId":"8d0b6f3e-2c4a-4e7b-9a1d-5f3c2e1b0a97","salesPrice":189,"shortName":"Monitor 24\" Full HD","suppliers":[{"currencyCode":"EUR","isDefault":true,"purchasePrice":142.5,"supplierAddressId":"3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4","supplierArticleNumber":"700-P2422H"}],"taxKeyCode":"STANDARD","unitCode":"STK"}'
```

## Get an article with its sales price and suppliers (tenant:masterdata:read)

`GET /api/masterdata/products/{id}`

Module: Master data · operationId: `getProduct` · Tag: Articles · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

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

### Responses

- **200** The article (`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:

- `shortName` (string, required): Kurzbezeichnung: required, one line (no line breaks); the name in lists, pickers and trade records (max length 80)
- `accounting` (object, read-only): Resolved revenue account and cost center (only on the single article, not in lists)
- `articleNumber` (string): Unique per tenant; assigned from the PRODUCT range when empty (max length 64)
- `articleType` (string): Article type; decides the required fields (one of `GOODS`, `SERVICE`, `SUBSCRIPTION`, `TEXT`, `FEE`; default `"GOODS"`)
- `basePriceUnit` (string): Unit of the base price
- `blockReason` (string): Reason of the block (max length 255)
- `blockedFrom` (string (date), nullable): First day of the block (YYYY-MM-DD)
- `blockedUntil` (string (date), nullable): After `blockedFrom`
- `commissionRate` (number, nullable): Commission in percent
- `contentQuantity` (number, nullable): Content quantity (for the base price)
- `contentUnit` (string): Unit of the content quantity
- `createdAt` (string (date-time), read-only): Creation time
- `createdBy` (string, read-only): Who created the article (subject of the token)
- `customerNo` (string, read-only): Tenant customer number (from the token)
- `customsTariffNo` (string): Customs tariff number
- `defaultSupplierId` (string (uuid), read-only): Id of the default supplier link
- `defaultWarehouseCode` (string): Default warehouse
- `description` (string): Beschreibung: long text without limit
- `dimensionUnit` (string): Unit of length, width and height (one of `MM`, `CM`, `M`)
- `ean` (string): EAN/GTIN with 8, 12, 13 or 14 digits and check digit
- `height` (number, nullable): Height in `dimensionUnit`
- `id` (string (uuid), read-only): Id of the article
- `isBatchTracked` (boolean): Only for GOODS
- `isBlocked` (boolean): Blocked article
- `isCommissionEligible` (boolean): Commission is paid
- `isDiscountEligible` (boolean): Discounts may be granted
- `isSerialTracked` (boolean): Only for GOODS
- `isSkontoEligible` (boolean): Cash discount (Skonto) may be granted
- `isStockItem` (boolean): Only for GOODS
- `length` (number, nullable): Length in `dimensionUnit`
- `manufacturerAddressId` (string (uuid), nullable): Manufacturer address
- `manufacturerName` (string): Manufacturer name (max length 255)
- `manufacturerPartNumber` (string): Manufacturer part number (MPN) (max length 64)
- `memo` (string): Internal memo
- `minPrice` (number, nullable): Lowest net price the article may be sold for; not above `salesPrice`
- `name` (string): Bezeichnung: optional, may span several lines; documents use `shortName` when empty (max length 2000)
- `originCountryCode` (string): Country of origin (ISO 3166-1 alpha-2)
- `priceQuantity` (number): Quantity the sales price refers to (default `1`)
- `productGroupId` (string (uuid), nullable): Required except for TEXT (cleared there)
- `productGroupName` (string, read-only): Name of the product group
- `purchasePrice` (number, read-only): Purchase price of the default supplier
- `salesPrice` (number, nullable): Net sales price per `priceQuantity`; required (0 is allowed) except for TEXT (cleared there)
- `searchTerm` (string): Upper-cased short name (first 255 characters) when empty (max length 255)
- `specialPrice` (number, nullable): Net special price; not below `minPrice` and not above `salesPrice`
- `specialValidFrom` (string (date), nullable): First day of the special price (dropped without `specialPrice`)
- `specialValidTo` (string (date), nullable): Last day of the special price; not before `specialValidFrom`
- `suppliers` (array of ProductSupplier): Suppliers with one purchase price each
  - `purchasePrice` (number, required): Net purchase price
  - `supplierAddressId` (string (uuid), required): Supplier address; once per article
  - `currencyCode` (string): Currency of the purchase price (ISO 4217)
  - `deliveryDays` (integer, nullable): Delivery time in days
  - `id` (string (uuid)): Id of the supplier link
  - `isDefault` (boolean): At most one; the first supplier is the default when none is set
  - `lastPurchaseAt` (string (date), nullable): Date of the last purchase (YYYY-MM-DD)
  - `minOrderQty` (number, nullable): Minimum order quantity
  - `orderUnitCode` (string): Order unit (code of `units`)
  - `supplierArticleNumber` (string): The supplier's article number (max length 64)
  - `supplierName` (string, read-only): Display name of the supplier address
- `svcAutoRenew` (boolean): Subscription renews automatically
- `svcBilling` (string): Must not be NONE for SUBSCRIPTION (one of `NONE`, `ADVANCE`, `ARREARS`; default `"NONE"`)
- `svcBillingCycleMonths` (integer, nullable): Billing cycle; required for SUBSCRIPTION (max 120)
- `svcNoticePeriodMonths` (integer, nullable): Notice period of the subscription in months
- `svcTermMonths` (integer, nullable): Subscription term; required for SUBSCRIPTION
- `syncStatus` (string, read-only): Reserved for an ERP synchronisation; STANDALONE for records of this API (one of `STANDALONE`, `PENDING_CREATION`, `PENDING_UPDATE`, `SYNCED`, `CONFLICT`, `ERROR`)
- `taxKeyCode` (string): Code of `tax-keys`; empty takes the product group's default tax key; required except for TEXT (cleared there)
- `tenantName` (string, read-only): Tenant name (from the token)
- `unitCode` (string): Code of `units`; empty takes the product group's default unit; required except for TEXT
- `updatedAt` (string (date-time), read-only): Time of the last change
- `updatedBy` (string, read-only): Who changed the article last (subject of the token)
- `version` (integer): Optimistic locking version (ignored on create)
- `weightKg` (number, nullable): Weight in kg
- `width` (number, nullable): Width in `dimensionUnit`

Example 200 answer:

```json
{
  "accounting": {
    "costCenter": "4200",
    "costCenterSource": "GROUP",
    "revenueAccount": "4400",
    "source": "GROUP",
    "sourceGroupCode": "HARDWARE",
    "taxKeyCode": "STANDARD"
  },
  "articleNumber": "HW-1004",
  "articleType": "GOODS",
  "createdAt": "2026-01-02T08:00:00Z",
  "createdBy": "laura.kaestner@muster-it.example",
  "customerNo": "99999",
  "defaultSupplierId": "7a9c1e3a-5b7d-4f9a-8c1e-3a5b7d9f1a3c",
  "ean": "4061234500045",
  "id": "6e8a0c2e-4f6a-4b8c-8d0e-2f4a6c8e0a2c",
  "isBatchTracked": false,
  "isBlocked": false,
  "isCommissionEligible": false,
  "isDiscountEligible": true,
  "isSerialTracked": false,
  "isSkontoEligible": true,
  "isStockItem": true,
  "manufacturerName": "Nordlicht IT-Distribution",
  "manufacturerPartNumber": "NL-DOCKC100",
  "name": "USB-C Dockingstation 100 W\n2 × DisplayPort, HDMI, 4 × USB-A, Gigabit-LAN",
  "priceQuantity": 1,
  "productGroupId": "8d0b6f3e-2c4a-4e7b-9a1d-5f3c2e1b0a97",
  "productGroupName": "Hardware",
  "purchasePrice": 139,
  "salesPrice": 189,
  "searchTerm": "DOCKINGSTATION USB-C",
  "shortName": "USB-C Dockingstation 100 W",
  "suppliers": [
    {
      "currencyCode": "EUR",
      "deliveryDays": 2,
      "id": "9c1e3a5c-7d9f-4b1c-8e3a-5c7d9f1b3c5e",
      "isDefault": true,
      "lastPurchaseAt": "2026-09-23",
      "minOrderQty": 1,
      "orderUnitCode": "STK",
      "purchasePrice": 139,
      "supplierAddressId": "7a9c1e3a-5b7d-4f9a-8c1e-3a5b7d9f1a3c",
      "supplierArticleNumber": "NL-DOCKC100",
      "supplierName": "Nordlicht IT-Distribution GmbH"
    }
  ],
  "svcBilling": "NONE",
  "syncStatus": "STANDALONE",
  "taxKeyCode": "STANDARD",
  "tenantName": "DEMO",
  "unitCode": "STK",
  "updatedAt": "2026-10-07T13:12:00Z",
  "updatedBy": "laura.kaestner@muster-it.example",
  "version": 4,
  "weightKg": 0.48
}
```

### Example request

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

## Replace an article (tenant:masterdata:write)

`PUT /api/masterdata/products/{id}`

Module: Master data · operationId: `updateProduct` · Tag: Articles · Auth: access token (`Authorization: Bearer <accessToken>`)

Replaces the article including its sales price and `suppliers`; `version` must match. The rules of
`createProduct` apply: an article stored before them that misses a required field answers `400` naming
the field until it is completed. Emits `masterdata.product.updated`.

### Parameters

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

### Request body

`application/json` (required)

- `shortName` (string, required): Kurzbezeichnung: required, one line (no line breaks); the name in lists, pickers and trade records (max length 80)
- `accounting` (object, read-only): Resolved revenue account and cost center (only on the single article, not in lists)
- `articleNumber` (string): Unique per tenant; assigned from the PRODUCT range when empty (max length 64)
- `articleType` (string): Article type; decides the required fields (one of `GOODS`, `SERVICE`, `SUBSCRIPTION`, `TEXT`, `FEE`; default `"GOODS"`)
- `basePriceUnit` (string): Unit of the base price
- `blockReason` (string): Reason of the block (max length 255)
- `blockedFrom` (string (date), nullable): First day of the block (YYYY-MM-DD)
- `blockedUntil` (string (date), nullable): After `blockedFrom`
- `commissionRate` (number, nullable): Commission in percent
- `contentQuantity` (number, nullable): Content quantity (for the base price)
- `contentUnit` (string): Unit of the content quantity
- `createdAt` (string (date-time), read-only): Creation time
- `createdBy` (string, read-only): Who created the article (subject of the token)
- `customerNo` (string, read-only): Tenant customer number (from the token)
- `customsTariffNo` (string): Customs tariff number
- `defaultSupplierId` (string (uuid), read-only): Id of the default supplier link
- `defaultWarehouseCode` (string): Default warehouse
- `description` (string): Beschreibung: long text without limit
- `dimensionUnit` (string): Unit of length, width and height (one of `MM`, `CM`, `M`)
- `ean` (string): EAN/GTIN with 8, 12, 13 or 14 digits and check digit
- `height` (number, nullable): Height in `dimensionUnit`
- `id` (string (uuid), read-only): Id of the article
- `isBatchTracked` (boolean): Only for GOODS
- `isBlocked` (boolean): Blocked article
- `isCommissionEligible` (boolean): Commission is paid
- `isDiscountEligible` (boolean): Discounts may be granted
- `isSerialTracked` (boolean): Only for GOODS
- `isSkontoEligible` (boolean): Cash discount (Skonto) may be granted
- `isStockItem` (boolean): Only for GOODS
- `length` (number, nullable): Length in `dimensionUnit`
- `manufacturerAddressId` (string (uuid), nullable): Manufacturer address
- `manufacturerName` (string): Manufacturer name (max length 255)
- `manufacturerPartNumber` (string): Manufacturer part number (MPN) (max length 64)
- `memo` (string): Internal memo
- `minPrice` (number, nullable): Lowest net price the article may be sold for; not above `salesPrice`
- `name` (string): Bezeichnung: optional, may span several lines; documents use `shortName` when empty (max length 2000)
- `originCountryCode` (string): Country of origin (ISO 3166-1 alpha-2)
- `priceQuantity` (number): Quantity the sales price refers to (default `1`)
- `productGroupId` (string (uuid), nullable): Required except for TEXT (cleared there)
- `productGroupName` (string, read-only): Name of the product group
- `purchasePrice` (number, read-only): Purchase price of the default supplier
- `salesPrice` (number, nullable): Net sales price per `priceQuantity`; required (0 is allowed) except for TEXT (cleared there)
- `searchTerm` (string): Upper-cased short name (first 255 characters) when empty (max length 255)
- `specialPrice` (number, nullable): Net special price; not below `minPrice` and not above `salesPrice`
- `specialValidFrom` (string (date), nullable): First day of the special price (dropped without `specialPrice`)
- `specialValidTo` (string (date), nullable): Last day of the special price; not before `specialValidFrom`
- `suppliers` (array of ProductSupplier): Suppliers with one purchase price each
  - `purchasePrice` (number, required): Net purchase price
  - `supplierAddressId` (string (uuid), required): Supplier address; once per article
  - `currencyCode` (string): Currency of the purchase price (ISO 4217)
  - `deliveryDays` (integer, nullable): Delivery time in days
  - `id` (string (uuid)): Id of the supplier link
  - `isDefault` (boolean): At most one; the first supplier is the default when none is set
  - `lastPurchaseAt` (string (date), nullable): Date of the last purchase (YYYY-MM-DD)
  - `minOrderQty` (number, nullable): Minimum order quantity
  - `orderUnitCode` (string): Order unit (code of `units`)
  - `supplierArticleNumber` (string): The supplier's article number (max length 64)
  - `supplierName` (string, read-only): Display name of the supplier address
- `svcAutoRenew` (boolean): Subscription renews automatically
- `svcBilling` (string): Must not be NONE for SUBSCRIPTION (one of `NONE`, `ADVANCE`, `ARREARS`; default `"NONE"`)
- `svcBillingCycleMonths` (integer, nullable): Billing cycle; required for SUBSCRIPTION (max 120)
- `svcNoticePeriodMonths` (integer, nullable): Notice period of the subscription in months
- `svcTermMonths` (integer, nullable): Subscription term; required for SUBSCRIPTION
- `syncStatus` (string, read-only): Reserved for an ERP synchronisation; STANDALONE for records of this API (one of `STANDALONE`, `PENDING_CREATION`, `PENDING_UPDATE`, `SYNCED`, `CONFLICT`, `ERROR`)
- `taxKeyCode` (string): Code of `tax-keys`; empty takes the product group's default tax key; required except for TEXT (cleared there)
- `tenantName` (string, read-only): Tenant name (from the token)
- `unitCode` (string): Code of `units`; empty takes the product group's default unit; required except for TEXT
- `updatedAt` (string (date-time), read-only): Time of the last change
- `updatedBy` (string, read-only): Who changed the article last (subject of the token)
- `version` (integer): Optimistic locking version (ignored on create)
- `weightKg` (number, nullable): Weight in kg
- `width` (number, nullable): Width in `dimensionUnit`

Example:

```json
{
  "accounting": {
    "costCenter": "4200",
    "costCenterSource": "GROUP",
    "revenueAccount": "4400",
    "source": "GROUP",
    "sourceGroupCode": "HARDWARE",
    "taxKeyCode": "STANDARD"
  },
  "articleNumber": "HW-1004",
  "articleType": "GOODS",
  "createdAt": "2026-01-02T08:00:00Z",
  "createdBy": "laura.kaestner@muster-it.example",
  "customerNo": "99999",
  "defaultSupplierId": "7a9c1e3a-5b7d-4f9a-8c1e-3a5b7d9f1a3c",
  "ean": "4061234500045",
  "id": "6e8a0c2e-4f6a-4b8c-8d0e-2f4a6c8e0a2c",
  "isBatchTracked": false,
  "isBlocked": false,
  "isCommissionEligible": false,
  "isDiscountEligible": true,
  "isSerialTracked": false,
  "isSkontoEligible": true,
  "isStockItem": true,
  "manufacturerName": "Nordlicht IT-Distribution",
  "manufacturerPartNumber": "NL-DOCKC100",
  "name": "USB-C Dockingstation 100 W\n2 × DisplayPort, HDMI, 4 × USB-A, Gigabit-LAN",
  "priceQuantity": 1,
  "productGroupId": "8d0b6f3e-2c4a-4e7b-9a1d-5f3c2e1b0a97",
  "productGroupName": "Hardware",
  "purchasePrice": 139,
  "salesPrice": 189,
  "searchTerm": "DOCKINGSTATION USB-C",
  "shortName": "USB-C Dockingstation 100 W",
  "suppliers": [
    {
      "currencyCode": "EUR",
      "deliveryDays": 2,
      "id": "9c1e3a5c-7d9f-4b1c-8e3a-5c7d9f1b3c5e",
      "isDefault": true,
      "lastPurchaseAt": "2026-09-23",
      "minOrderQty": 1,
      "orderUnitCode": "STK",
      "purchasePrice": 139,
      "supplierAddressId": "7a9c1e3a-5b7d-4f9a-8c1e-3a5b7d9f1a3c",
      "supplierArticleNumber": "NL-DOCKC100",
      "supplierName": "Nordlicht IT-Distribution GmbH"
    }
  ],
  "svcBilling": "NONE",
  "syncStatus": "STANDALONE",
  "taxKeyCode": "STANDARD",
  "tenantName": "DEMO",
  "unitCode": "STK",
  "updatedAt": "2026-10-07T13:12:00Z",
  "updatedBy": "laura.kaestner@muster-it.example",
  "version": 4,
  "weightKg": 0.48
}
```

### 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:

- `shortName` (string, required): Kurzbezeichnung: required, one line (no line breaks); the name in lists, pickers and trade records (max length 80)
- `accounting` (object, read-only): Resolved revenue account and cost center (only on the single article, not in lists)
- `articleNumber` (string): Unique per tenant; assigned from the PRODUCT range when empty (max length 64)
- `articleType` (string): Article type; decides the required fields (one of `GOODS`, `SERVICE`, `SUBSCRIPTION`, `TEXT`, `FEE`; default `"GOODS"`)
- `basePriceUnit` (string): Unit of the base price
- `blockReason` (string): Reason of the block (max length 255)
- `blockedFrom` (string (date), nullable): First day of the block (YYYY-MM-DD)
- `blockedUntil` (string (date), nullable): After `blockedFrom`
- `commissionRate` (number, nullable): Commission in percent
- `contentQuantity` (number, nullable): Content quantity (for the base price)
- `contentUnit` (string): Unit of the content quantity
- `createdAt` (string (date-time), read-only): Creation time
- `createdBy` (string, read-only): Who created the article (subject of the token)
- `customerNo` (string, read-only): Tenant customer number (from the token)
- `customsTariffNo` (string): Customs tariff number
- `defaultSupplierId` (string (uuid), read-only): Id of the default supplier link
- `defaultWarehouseCode` (string): Default warehouse
- `description` (string): Beschreibung: long text without limit
- `dimensionUnit` (string): Unit of length, width and height (one of `MM`, `CM`, `M`)
- `ean` (string): EAN/GTIN with 8, 12, 13 or 14 digits and check digit
- `height` (number, nullable): Height in `dimensionUnit`
- `id` (string (uuid), read-only): Id of the article
- `isBatchTracked` (boolean): Only for GOODS
- `isBlocked` (boolean): Blocked article
- `isCommissionEligible` (boolean): Commission is paid
- `isDiscountEligible` (boolean): Discounts may be granted
- `isSerialTracked` (boolean): Only for GOODS
- `isSkontoEligible` (boolean): Cash discount (Skonto) may be granted
- `isStockItem` (boolean): Only for GOODS
- `length` (number, nullable): Length in `dimensionUnit`
- `manufacturerAddressId` (string (uuid), nullable): Manufacturer address
- `manufacturerName` (string): Manufacturer name (max length 255)
- `manufacturerPartNumber` (string): Manufacturer part number (MPN) (max length 64)
- `memo` (string): Internal memo
- `minPrice` (number, nullable): Lowest net price the article may be sold for; not above `salesPrice`
- `name` (string): Bezeichnung: optional, may span several lines; documents use `shortName` when empty (max length 2000)
- `originCountryCode` (string): Country of origin (ISO 3166-1 alpha-2)
- `priceQuantity` (number): Quantity the sales price refers to (default `1`)
- `productGroupId` (string (uuid), nullable): Required except for TEXT (cleared there)
- `productGroupName` (string, read-only): Name of the product group
- `purchasePrice` (number, read-only): Purchase price of the default supplier
- `salesPrice` (number, nullable): Net sales price per `priceQuantity`; required (0 is allowed) except for TEXT (cleared there)
- `searchTerm` (string): Upper-cased short name (first 255 characters) when empty (max length 255)
- `specialPrice` (number, nullable): Net special price; not below `minPrice` and not above `salesPrice`
- `specialValidFrom` (string (date), nullable): First day of the special price (dropped without `specialPrice`)
- `specialValidTo` (string (date), nullable): Last day of the special price; not before `specialValidFrom`
- `suppliers` (array of ProductSupplier): Suppliers with one purchase price each
  - `purchasePrice` (number, required): Net purchase price
  - `supplierAddressId` (string (uuid), required): Supplier address; once per article
  - `currencyCode` (string): Currency of the purchase price (ISO 4217)
  - `deliveryDays` (integer, nullable): Delivery time in days
  - `id` (string (uuid)): Id of the supplier link
  - `isDefault` (boolean): At most one; the first supplier is the default when none is set
  - `lastPurchaseAt` (string (date), nullable): Date of the last purchase (YYYY-MM-DD)
  - `minOrderQty` (number, nullable): Minimum order quantity
  - `orderUnitCode` (string): Order unit (code of `units`)
  - `supplierArticleNumber` (string): The supplier's article number (max length 64)
  - `supplierName` (string, read-only): Display name of the supplier address
- `svcAutoRenew` (boolean): Subscription renews automatically
- `svcBilling` (string): Must not be NONE for SUBSCRIPTION (one of `NONE`, `ADVANCE`, `ARREARS`; default `"NONE"`)
- `svcBillingCycleMonths` (integer, nullable): Billing cycle; required for SUBSCRIPTION (max 120)
- `svcNoticePeriodMonths` (integer, nullable): Notice period of the subscription in months
- `svcTermMonths` (integer, nullable): Subscription term; required for SUBSCRIPTION
- `syncStatus` (string, read-only): Reserved for an ERP synchronisation; STANDALONE for records of this API (one of `STANDALONE`, `PENDING_CREATION`, `PENDING_UPDATE`, `SYNCED`, `CONFLICT`, `ERROR`)
- `taxKeyCode` (string): Code of `tax-keys`; empty takes the product group's default tax key; required except for TEXT (cleared there)
- `tenantName` (string, read-only): Tenant name (from the token)
- `unitCode` (string): Code of `units`; empty takes the product group's default unit; required except for TEXT
- `updatedAt` (string (date-time), read-only): Time of the last change
- `updatedBy` (string, read-only): Who changed the article last (subject of the token)
- `version` (integer): Optimistic locking version (ignored on create)
- `weightKg` (number, nullable): Weight in kg
- `width` (number, nullable): Width in `dimensionUnit`

Example 200 answer:

```json
{
  "accounting": {
    "costCenter": "4200",
    "costCenterSource": "GROUP",
    "revenueAccount": "4400",
    "source": "GROUP",
    "sourceGroupCode": "HARDWARE",
    "taxKeyCode": "STANDARD"
  },
  "articleNumber": "HW-1004",
  "articleType": "GOODS",
  "createdAt": "2026-01-02T08:00:00Z",
  "createdBy": "laura.kaestner@muster-it.example",
  "customerNo": "99999",
  "defaultSupplierId": "7a9c1e3a-5b7d-4f9a-8c1e-3a5b7d9f1a3c",
  "ean": "4061234500045",
  "id": "6e8a0c2e-4f6a-4b8c-8d0e-2f4a6c8e0a2c",
  "isBatchTracked": false,
  "isBlocked": false,
  "isCommissionEligible": false,
  "isDiscountEligible": true,
  "isSerialTracked": false,
  "isSkontoEligible": true,
  "isStockItem": true,
  "manufacturerName": "Nordlicht IT-Distribution",
  "manufacturerPartNumber": "NL-DOCKC100",
  "name": "USB-C Dockingstation 100 W\n2 × DisplayPort, HDMI, 4 × USB-A, Gigabit-LAN",
  "priceQuantity": 1,
  "productGroupId": "8d0b6f3e-2c4a-4e7b-9a1d-5f3c2e1b0a97",
  "productGroupName": "Hardware",
  "purchasePrice": 139,
  "salesPrice": 189,
  "searchTerm": "DOCKINGSTATION USB-C",
  "shortName": "USB-C Dockingstation 100 W",
  "suppliers": [
    {
      "currencyCode": "EUR",
      "deliveryDays": 2,
      "id": "9c1e3a5c-7d9f-4b1c-8e3a-5c7d9f1b3c5e",
      "isDefault": true,
      "lastPurchaseAt": "2026-09-23",
      "minOrderQty": 1,
      "orderUnitCode": "STK",
      "purchasePrice": 139,
      "supplierAddressId": "7a9c1e3a-5b7d-4f9a-8c1e-3a5b7d9f1a3c",
      "supplierArticleNumber": "NL-DOCKC100",
      "supplierName": "Nordlicht IT-Distribution GmbH"
    }
  ],
  "svcBilling": "NONE",
  "syncStatus": "STANDALONE",
  "taxKeyCode": "STANDARD",
  "tenantName": "DEMO",
  "unitCode": "STK",
  "updatedAt": "2026-10-07T13:12:00Z",
  "updatedBy": "laura.kaestner@muster-it.example",
  "version": 4,
  "weightKg": 0.48
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/masterdata/products/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"accounting":{"costCenter":"4200","costCenterSource":"GROUP","revenueAccount":"4400","source":"GROUP","sourceGroupCode":"HARDWARE","taxKeyCode":"STANDARD"},"articleNumber":"HW-1004","articleType":"GOODS","createdAt":"2026-01-02T08:00:00Z","createdBy":"laura.kaestner@muster-it.example","customerNo":"99999","defaultSupplierId":"7a9c1e3a-5b7d-4f9a-8c1e-3a5b7d9f1a3c","ean":"4061234500045","id":"6e8a0c2e-4f6a-4b8c-8d0e-2f4a6c8e0a2c","isBatchTracked":false,"isBlocked":false,"isCommissionEligible":false,"isDiscountEligible":true,"isSerialTracked":false,"isSkontoEligible":true,"isStockItem":true,"manufacturerName":"Nordlicht IT-Distribution","manufacturerPartNumber":"NL-DOCKC100","name":"USB-C Dockingstation 100 W\n2 × DisplayPort, HDMI, 4 × USB-A, Gigabit-LAN","priceQuantity":1,"productGroupId":"8d0b6f3e-2c4a-4e7b-9a1d-5f3c2e1b0a97","productGroupName":"Hardware","purchasePrice":139,"salesPrice":189,"searchTerm":"DOCKINGSTATION USB-C","shortName":"USB-C Dockingstation 100 W","suppliers":[{"currencyCode":"EUR","deliveryDays":2,"id":"9c1e3a5c-7d9f-4b1c-8e3a-5c7d9f1b3c5e","isDefault":true,"lastPurchaseAt":"2026-09-23","minOrderQty":1,"orderUnitCode":"STK","purchasePrice":139,"supplierAddressId":"7a9c1e3a-5b7d-4f9a-8c1e-3a5b7d9f1a3c","supplierArticleNumber":"NL-DOCKC100","supplierName":"Nordlicht IT-Distribution GmbH"}],"svcBilling":"NONE","syncStatus":"STANDALONE","taxKeyCode":"STANDARD","tenantName":"DEMO","unitCode":"STK","updatedAt":"2026-10-07T13:12:00Z","updatedBy":"laura.kaestner@muster-it.example","version":4,"weightKg":0.48}'
```

## Delete an article (tenant:masterdata:write)

`DELETE /api/masterdata/products/{id}`

Module: Master data · operationId: `deleteProduct` · Tag: Articles · Auth: access token (`Authorization: Bearer <accessToken>`)

Soft-deletes the article. Emits `masterdata.product.deleted`.

### Parameters

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

### Responses

- **204** Deleted
- **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`)

### Example request

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

# Product groups

## List product groups (tenant:masterdata:read)

`GET /api/masterdata/product-groups`

Module: Master data · operationId: `listProductGroups` · Tag: Product groups · Auth: access token (`Authorization: Bearer <accessToken>`)

All groups of the tenant ordered by code, with the number of articles each.

### Responses

- **200** Product groups (`application/json`)
- **401** Missing, invalid or expired token (empty body)
- **403** The token lacks the permission or carries no tenant (`application/json`)

Fields of the 200 answer:

- `items` (array of ProductGroup, required)
  - `code` (string, required): Unique per tenant
  - `defaultTaxKeyCode` (string, required): Code of `tax-keys`; new articles of the group without tax key get it
  - `name` (string, required): Name (max length 255)
  - `accounts` (array of ProductGroupAccount): Revenue accounts per tax key, saved as a whole set (overrides the tax key's default account for the group and its sub-groups)
    - `revenueAccount` (string, required): Revenue account
    - `taxKeyCode` (string, required): Code of `tax-keys` (once per group)
  - `costCenter` (string): Cost center; sub-groups without one inherit it (max length 32)
  - `createdAt` (string (date-time), read-only): Creation time
  - `defaultUnitCode` (string): Code of `units`; new articles of the group without unit get it
  - `id` (string (uuid), read-only): Id of the product group
  - `info` (string): Info text
  - `parentId` (string (uuid), nullable): Parent group (no cycles)
  - `priceTiers` (array of PriceTier): The group's own price calculation scale (same rules as `PUT /price-tiers`); it replaces the inherited scale completely. `null` or absent: the group uses its parent's scale, then the tenant's (saving without it removes the group's own scale).
    - `fromCost` (number, required): Purchase price from which the row applies (inclusive, net, base currency); the first row is 0
    - `markupRate` (number, required): Markup in percent of the purchase price (max 1000)
    - `rounding` (string, required): `NONE` rounds half up to cents; `UP_x` rounds up to the next multiple of x (0.05, 0.10, 0.50, 1, 5, 10); `END_90`/`END_99` take the smallest price ending in .90/.99 that is not below the value. (one of `NONE`, `UP_0_05`, `UP_0_10`, `UP_0_50`, `UP_1`, `UP_5`, `UP_10`, `END_90`, `END_99`)
  - `productCount` (integer, read-only): Number of articles in the group
  - `updatedAt` (string (date-time), read-only): Time of the last change
  - `version` (integer): Optimistic locking version (updates)

Example 200 answer:

```json
{
  "items": [
    {
      "accounts": [
        {
          "revenueAccount": "4400",
          "taxKeyCode": "STANDARD"
        }
      ],
      "code": "HARDWARE",
      "costCenter": "4200",
      "createdAt": "2026-01-02T08:00:00Z",
      "defaultTaxKeyCode": "STANDARD",
      "defaultUnitCode": "STK",
      "id": "8d0b6f3e-2c4a-4e7b-9a1d-5f3c2e1b0a97",
      "name": "Hardware",
      "parentId": null,
      "priceTiers": [
        {
          "fromCost": 0,
          "markupRate": 35,
          "rounding": "END_99"
        },
        {
          "fromCost": 500,
          "markupRate": 25,
          "rounding": "END_99"
        }
      ],
      "productCount": 14,
      "updatedAt": "2026-04-11T15:20:00Z",
      "version": 2
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/masterdata/product-groups' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create a product group (tenant:masterdata:write)

`POST /api/masterdata/product-groups`

Module: Master data · operationId: `createProductGroup` · Tag: Product groups · Auth: access token (`Authorization: Bearer <accessToken>`)

Emits `masterdata.product_group.created`.

### Request body

`application/json` (required)

- `code` (string, required): Unique per tenant
- `defaultTaxKeyCode` (string, required): Code of `tax-keys`; new articles of the group without tax key get it
- `name` (string, required): Name (max length 255)
- `accounts` (array of ProductGroupAccount): Revenue accounts per tax key, saved as a whole set (overrides the tax key's default account for the group and its sub-groups)
  - `revenueAccount` (string, required): Revenue account
  - `taxKeyCode` (string, required): Code of `tax-keys` (once per group)
- `costCenter` (string): Cost center; sub-groups without one inherit it (max length 32)
- `createdAt` (string (date-time), read-only): Creation time
- `defaultUnitCode` (string): Code of `units`; new articles of the group without unit get it
- `id` (string (uuid), read-only): Id of the product group
- `info` (string): Info text
- `parentId` (string (uuid), nullable): Parent group (no cycles)
- `priceTiers` (array of PriceTier): The group's own price calculation scale (same rules as `PUT /price-tiers`); it replaces the inherited scale completely. `null` or absent: the group uses its parent's scale, then the tenant's (saving without it removes the group's own scale).
  - `fromCost` (number, required): Purchase price from which the row applies (inclusive, net, base currency); the first row is 0
  - `markupRate` (number, required): Markup in percent of the purchase price (max 1000)
  - `rounding` (string, required): `NONE` rounds half up to cents; `UP_x` rounds up to the next multiple of x (0.05, 0.10, 0.50, 1, 5, 10); `END_90`/`END_99` take the smallest price ending in .90/.99 that is not below the value. (one of `NONE`, `UP_0_05`, `UP_0_10`, `UP_0_50`, `UP_1`, `UP_5`, `UP_10`, `END_90`, `END_99`)
- `productCount` (integer, read-only): Number of articles in the group
- `updatedAt` (string (date-time), read-only): Time of the last change
- `version` (integer): Optimistic locking version (updates)

Example:

```json
{
  "code": "MON",
  "defaultTaxKeyCode": "STANDARD",
  "name": "Monitore"
}
```

### Responses

- **201** Created (`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`)
- **409** Stale version or conflict with existing data (`application/json`)

Fields of the 201 answer:

- `code` (string, required): Unique per tenant
- `defaultTaxKeyCode` (string, required): Code of `tax-keys`; new articles of the group without tax key get it
- `name` (string, required): Name (max length 255)
- `accounts` (array of ProductGroupAccount): Revenue accounts per tax key, saved as a whole set (overrides the tax key's default account for the group and its sub-groups)
  - `revenueAccount` (string, required): Revenue account
  - `taxKeyCode` (string, required): Code of `tax-keys` (once per group)
- `costCenter` (string): Cost center; sub-groups without one inherit it (max length 32)
- `createdAt` (string (date-time), read-only): Creation time
- `defaultUnitCode` (string): Code of `units`; new articles of the group without unit get it
- `id` (string (uuid), read-only): Id of the product group
- `info` (string): Info text
- `parentId` (string (uuid), nullable): Parent group (no cycles)
- `priceTiers` (array of PriceTier): The group's own price calculation scale (same rules as `PUT /price-tiers`); it replaces the inherited scale completely. `null` or absent: the group uses its parent's scale, then the tenant's (saving without it removes the group's own scale).
  - `fromCost` (number, required): Purchase price from which the row applies (inclusive, net, base currency); the first row is 0
  - `markupRate` (number, required): Markup in percent of the purchase price (max 1000)
  - `rounding` (string, required): `NONE` rounds half up to cents; `UP_x` rounds up to the next multiple of x (0.05, 0.10, 0.50, 1, 5, 10); `END_90`/`END_99` take the smallest price ending in .90/.99 that is not below the value. (one of `NONE`, `UP_0_05`, `UP_0_10`, `UP_0_50`, `UP_1`, `UP_5`, `UP_10`, `END_90`, `END_99`)
- `productCount` (integer, read-only): Number of articles in the group
- `updatedAt` (string (date-time), read-only): Time of the last change
- `version` (integer): Optimistic locking version (updates)

Example 201 answer:

```json
{
  "accounts": [
    {
      "revenueAccount": "4400",
      "taxKeyCode": "STANDARD"
    }
  ],
  "code": "HARDWARE",
  "costCenter": "4200",
  "createdAt": "2026-01-02T08:00:00Z",
  "defaultTaxKeyCode": "STANDARD",
  "defaultUnitCode": "STK",
  "id": "8d0b6f3e-2c4a-4e7b-9a1d-5f3c2e1b0a97",
  "name": "Hardware",
  "parentId": null,
  "priceTiers": [
    {
      "fromCost": 0,
      "markupRate": 35,
      "rounding": "END_99"
    },
    {
      "fromCost": 500,
      "markupRate": 25,
      "rounding": "END_99"
    }
  ],
  "productCount": 14,
  "updatedAt": "2026-04-11T15:20:00Z",
  "version": 2
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/masterdata/product-groups' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"code":"MON","defaultTaxKeyCode":"STANDARD","name":"Monitore"}'
```

## Update a product group (tenant:masterdata:write)

`PUT /api/masterdata/product-groups/{id}`

Module: Master data · operationId: `updateProductGroup` · Tag: Product groups · Auth: access token (`Authorization: Bearer <accessToken>`)

`version` must match. A parent that is unknown or would create a cycle answers `400`. Emits `masterdata.product_group.updated`.

### Parameters

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

### Request body

`application/json` (required)

- `code` (string, required): Unique per tenant
- `defaultTaxKeyCode` (string, required): Code of `tax-keys`; new articles of the group without tax key get it
- `name` (string, required): Name (max length 255)
- `accounts` (array of ProductGroupAccount): Revenue accounts per tax key, saved as a whole set (overrides the tax key's default account for the group and its sub-groups)
  - `revenueAccount` (string, required): Revenue account
  - `taxKeyCode` (string, required): Code of `tax-keys` (once per group)
- `costCenter` (string): Cost center; sub-groups without one inherit it (max length 32)
- `createdAt` (string (date-time), read-only): Creation time
- `defaultUnitCode` (string): Code of `units`; new articles of the group without unit get it
- `id` (string (uuid), read-only): Id of the product group
- `info` (string): Info text
- `parentId` (string (uuid), nullable): Parent group (no cycles)
- `priceTiers` (array of PriceTier): The group's own price calculation scale (same rules as `PUT /price-tiers`); it replaces the inherited scale completely. `null` or absent: the group uses its parent's scale, then the tenant's (saving without it removes the group's own scale).
  - `fromCost` (number, required): Purchase price from which the row applies (inclusive, net, base currency); the first row is 0
  - `markupRate` (number, required): Markup in percent of the purchase price (max 1000)
  - `rounding` (string, required): `NONE` rounds half up to cents; `UP_x` rounds up to the next multiple of x (0.05, 0.10, 0.50, 1, 5, 10); `END_90`/`END_99` take the smallest price ending in .90/.99 that is not below the value. (one of `NONE`, `UP_0_05`, `UP_0_10`, `UP_0_50`, `UP_1`, `UP_5`, `UP_10`, `END_90`, `END_99`)
- `productCount` (integer, read-only): Number of articles in the group
- `updatedAt` (string (date-time), read-only): Time of the last change
- `version` (integer): Optimistic locking version (updates)

Example:

```json
{
  "accounts": [
    {
      "revenueAccount": "4400",
      "taxKeyCode": "STANDARD"
    }
  ],
  "code": "HARDWARE",
  "costCenter": "4200",
  "createdAt": "2026-01-02T08:00:00Z",
  "defaultTaxKeyCode": "STANDARD",
  "defaultUnitCode": "STK",
  "id": "8d0b6f3e-2c4a-4e7b-9a1d-5f3c2e1b0a97",
  "name": "Hardware",
  "parentId": null,
  "priceTiers": [
    {
      "fromCost": 0,
      "markupRate": 35,
      "rounding": "END_99"
    },
    {
      "fromCost": 500,
      "markupRate": 25,
      "rounding": "END_99"
    }
  ],
  "productCount": 14,
  "updatedAt": "2026-04-11T15:20:00Z",
  "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:

- `code` (string, required): Unique per tenant
- `defaultTaxKeyCode` (string, required): Code of `tax-keys`; new articles of the group without tax key get it
- `name` (string, required): Name (max length 255)
- `accounts` (array of ProductGroupAccount): Revenue accounts per tax key, saved as a whole set (overrides the tax key's default account for the group and its sub-groups)
  - `revenueAccount` (string, required): Revenue account
  - `taxKeyCode` (string, required): Code of `tax-keys` (once per group)
- `costCenter` (string): Cost center; sub-groups without one inherit it (max length 32)
- `createdAt` (string (date-time), read-only): Creation time
- `defaultUnitCode` (string): Code of `units`; new articles of the group without unit get it
- `id` (string (uuid), read-only): Id of the product group
- `info` (string): Info text
- `parentId` (string (uuid), nullable): Parent group (no cycles)
- `priceTiers` (array of PriceTier): The group's own price calculation scale (same rules as `PUT /price-tiers`); it replaces the inherited scale completely. `null` or absent: the group uses its parent's scale, then the tenant's (saving without it removes the group's own scale).
  - `fromCost` (number, required): Purchase price from which the row applies (inclusive, net, base currency); the first row is 0
  - `markupRate` (number, required): Markup in percent of the purchase price (max 1000)
  - `rounding` (string, required): `NONE` rounds half up to cents; `UP_x` rounds up to the next multiple of x (0.05, 0.10, 0.50, 1, 5, 10); `END_90`/`END_99` take the smallest price ending in .90/.99 that is not below the value. (one of `NONE`, `UP_0_05`, `UP_0_10`, `UP_0_50`, `UP_1`, `UP_5`, `UP_10`, `END_90`, `END_99`)
- `productCount` (integer, read-only): Number of articles in the group
- `updatedAt` (string (date-time), read-only): Time of the last change
- `version` (integer): Optimistic locking version (updates)

Example 200 answer:

```json
{
  "accounts": [
    {
      "revenueAccount": "4400",
      "taxKeyCode": "STANDARD"
    }
  ],
  "code": "HARDWARE",
  "costCenter": "4200",
  "createdAt": "2026-01-02T08:00:00Z",
  "defaultTaxKeyCode": "STANDARD",
  "defaultUnitCode": "STK",
  "id": "8d0b6f3e-2c4a-4e7b-9a1d-5f3c2e1b0a97",
  "name": "Hardware",
  "parentId": null,
  "priceTiers": [
    {
      "fromCost": 0,
      "markupRate": 35,
      "rounding": "END_99"
    },
    {
      "fromCost": 500,
      "markupRate": 25,
      "rounding": "END_99"
    }
  ],
  "productCount": 14,
  "updatedAt": "2026-04-11T15:20:00Z",
  "version": 2
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/masterdata/product-groups/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"accounts":[{"revenueAccount":"4400","taxKeyCode":"STANDARD"}],"code":"HARDWARE","costCenter":"4200","createdAt":"2026-01-02T08:00:00Z","defaultTaxKeyCode":"STANDARD","defaultUnitCode":"STK","id":"8d0b6f3e-2c4a-4e7b-9a1d-5f3c2e1b0a97","name":"Hardware","parentId":null,"priceTiers":[{"fromCost":0,"markupRate":35,"rounding":"END_99"},{"fromCost":500,"markupRate":25,"rounding":"END_99"}],"productCount":14,"updatedAt":"2026-04-11T15:20:00Z","version":2}'
```

## Delete a product group (tenant:masterdata:write)

`DELETE /api/masterdata/product-groups/{id}`

Module: Master data · operationId: `deleteProductGroup` · Tag: Product groups · Auth: access token (`Authorization: Bearer <accessToken>`)

Soft-deletes a group without articles and sub-groups (else `409`). Emits `masterdata.product_group.deleted`.

### Parameters

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

### Responses

- **204** Deleted
- **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`)

### Example request

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

# Drafts

## Draft an address from text, an image or a website (tenant:masterdata:write)

`POST /api/masterdata/addresses:draft`

Module: Master data · operationId: `draftAddress` · Tag: Drafts · Auth: access token (`Authorization: Bearer <accessToken>`)

Extracts an address from pasted text (email signature, letterhead), an image (business card,
scan) and/or the imprint of a website or email domain. Nothing is stored and the input is not
logged. `draft` is a body for `POST /api/masterdata/addresses`; `fieldSources` names where each
pre-filled field came from, `warnings` lists unknown lookup codes, invalid formats or failed
sources, `duplicates` lists existing addresses that look the same. When the AI is not available
the draft is built from the imprint only (`aiAvailable: false`).

### Request body

`application/json` (required)

- `email` (string): Email address whose domain is looked up (address drafts only) (max length 320)
- `imageData` (string): Base64 image or data URI (business card, scanned letter); read via OCR after a malware scan (an image with a finding, or when the scan is unavailable, is not read and a warning on imageData says why) (max length 3145728)
- `mimeType` (string): `image/*` or `application/pdf` (max length 64)
- `text` (string): Pasted text: email signature, letterhead, delivery address … (max length 20000)
- `url` (string): Website or imprint URL (address drafts only) (max length 2048)

Example:

```json
{
  "text": "Muster GmbH\nErika Musterfrau, Einkauf\nHauptstraße 1, 10115 Berlin\nTel. +49 30 1234567\neinkauf@muster.de"
}
```

### Responses

- **200** The draft (`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`)
- **413** The body is over the limit (2 MiB; AI drafts 4 MiB) (`application/json`)
- **429** Too many AI drafts or imprint lookups of this person – wait `Retry-After` seconds ([rate limits](/guides/rate-limits)) (`application/json`)
- **502** The AI could not read the input (`application/json`)
- **503** The AI is not reachable (`application/json`)

Fields of the 200 answer:

- `aiAvailable` (boolean, required): False when the AI was not available (draft from the imprint only)
- `draft` (Address, required): The address aggregate. Read-only fields are ignored on write. `companyName` is required for `partyType` `COMPANY`, `lastName` for `PERSON`. `statusCode` is required: the status decides the `roles`.
  - `statusCode` (string, required): Code of `address-statuses` (required). Its flags decide the `roles`
  - `version` (integer, required): Optimistic locking version; send the version you read (ignored on create)
  - `accountOwner` (string): Account owner (responsible person) in CRM (max length 255)
  - `accountType` (string): Individual or collective account (one of `INDIVIDUAL`, `COLLECTIVE`; default `"INDIVIDUAL"`)
  - `additionalName` (string): Name addition (second name line) (max length 255)
  - `adrNr` (string): Address number, unique per tenant; assigned from the ADDRESS range when empty (max length 32)
  - `annualRevenue` (number, nullable): Annual revenue
  - `bankAccounts` (array of BankAccount): Bank accounts
    - `iban` (string, required): Unique per address
    - `accountHolder` (string): Account holder (max length 255)
    - `bankName` (string): Name of the bank (max length 128)
    - `bic` (string): BIC
    - `id` (string (uuid)): Id of the bank account
    - `isDefault` (boolean): At most one; the first account is the default when none is set
  - `blockReason` (string): Cleared when `isBlocked` is false (max length 255)
  - `blockedAt` (string (date-time), read-only): Time of the general block
  - `blockedBy` (string, read-only): Actor of the general block
  - `commercialRegister` (string): Commercial register number (Handelsregister) (max length 128)
  - `companyName` (string): Company name (required for `partyType` COMPANY) (max length 255)
  - `contactPersons` (array of ContactPerson): Contact persons (Ansprechpartner)
    - `aspNr` (integer): Number within the address; assigned
    - `availableFrom1` (string, nullable): Reachable from (HH:MM)
    - `availableFrom2` (string, nullable): Second time window: reachable from (HH:MM)
    - `availableTo1` (string, nullable): After `availableFrom1`
    - `availableTo2` (string, nullable): After `availableFrom2`
    - `birthday` (string (date), nullable): Birthday (YYYY-MM-DD)
    - `blockReason` (string, read-only): Reason of the block
    - `blockedAt` (string (date-time), read-only): Time of the block
    - `blockedBy` (string, read-only): Actor of the block
    - `customFields` (CustomFields)
    - `department` (string): Department
    - `doNotCall` (boolean): Do not call
    - `email1` (string (email)): First e-mail address
    - `email2` (string (email)): Second e-mail address
    - `emailOptOut` (boolean): No marketing e-mails
    - `fax` (string): E.164
    - `firstName` (string): First name (max length 128)
    - `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
    - `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
    - `id` (string (uuid)): Id of the contact person
    - `info` (string): Info text
    - `isActive` (boolean): False when `leftAt` is set (default `true`)
    - `isBlocked` (boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set with `POST /addresses/{id}/contacts/{cid}/block`
    - `isDefault` (boolean): Default contact of the address (at most one)
    - `languageCode` (string): Language (ISO 639-1)
    - `lastName` (string): Last name (max length 128)
    - `leftAt` (string (date), nullable): Date the person left the company; sets `isActive` false
    - `letterSalutation` (string): Salutation line of letters
    - `linkedinUrl` (string (uri)): LinkedIn profile (max length 255)
    - `mobile` (string): E.164
    - `namePrefix` (string): Name prefix
    - `nameSuffix` (string): Name suffix
    - `phone1` (string): E.164
    - `phone2` (string): E.164
    - `portalUserId` (string): Linked desk portal user (max length 255)
    - `position` (string): Position
    - `postalAddressAnsNr` (integer, nullable): `ansNr` of a postal address of the same address
    - `preferredChannel` (string): Preferred contact channel (one of `EMAIL`, `PHONE`, `MOBILE`, `LETTER`, `PORTAL`)
    - `reportsToAspNr` (integer, nullable): `aspNr` of the manager within the same address (no cycles)
    - `roles` (array of string): Roles in the buying centre or for ticket routing
    - `salutationCode` (string): Code of `salutations`
    - `timezone` (string): IANA time zone
    - `title` (string): Title
    - `version` (integer): Version of this contact (child updates)
  - `createdAt` (string (date-time), read-only): Creation time
  - `createdBy` (string, read-only): Who created the address (subject of the token)
  - `creditLimit` (number, nullable): Credit limit
  - `creditorAccountNo` (string): Creditor account. With `glAccountLength` g it must lie in [7*10^g, 10^(g+1)-1] (g=4: 70000-99999); checked only when the value changes, else 400 (max length 32)
  - `currencyCode` (string): ISO 4217
  - `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`.
  - `customerNo` (string, read-only): Tenant customer number (from the token)
  - `customerNumber` (string): Customer number (Kundennummer), unique among the live addresses of the tenant (`409` `customer_number_taken`). Empty on an address with the role CUSTOMER: the address number (adrNr) is used while no other address has it as customer number, except in the platform operator tenant (max length 64)
  - `customerSince` (string (date), nullable): Customer since (YYYY-MM-DD)
  - `dataQualityScore` (integer, read-only): Completeness score computed on save (max 100)
  - `deletionBlockedUntil` (string (date), nullable): Deleting the address or merging it away (as source) through this date (inclusive) answers 409 (Löschsperre bis TT.MM.JJJJ); a merge keeps the later date of both addresses
  - `deliveryBlockReason` (string, read-only): Reason of the delivery block
  - `deliveryBlocked` (boolean, read-only): Delivery block (set with `POST /addresses/{id}/blocks`; a PUT keeps it)
  - `deliveryBlockedAt` (string (date-time), read-only): Time of the delivery block
  - `deliveryBlockedBy` (string, read-only): Actor of the delivery block
  - `deliveryCondition` (string): Delivery condition (free text) (max length 255)
  - `discountRate` (number, nullable): Discount in percent (max 100)
  - `displayName` (string, read-only): Company name, else first and last name
  - `distributorIds` (array of DistributorID, read-only): Maintained via /api/masterdata/distributor-ids
    - `addressId` (string (uuid), required): Supplier address the distributor ID maps to
    - `addressName` (string, required): Display name of that address
    - `adrNr` (string, required): Address number of that address
    - `distributorId` (string, required): The distributor's own ID
    - `source` (string, required): Distributor (lower case, e.g. egis, ingram)
    - `updatedAt` (string (date-time), required): Time of the last change
    - `distributorName` (string): Name of the distributor
  - `dunningBlocked` (boolean): Dunning block (also set with `POST /addresses/{id}/blocks`, type DUNNING)
  - `dunningBlockedAt` (string (date-time), read-only): Time of the dunning block
  - `dunningBlockedBy` (string, read-only): Actor of the dunning block
  - `eInvoiceBuyerRef` (string): Leitweg-ID (XRechnung buyer reference)
  - `eInvoiceFormat` (string): Preferred e-invoice format (one of `XRECHNUNG`, `ZUGFERD`, `PEPPOL`, `PDF`)
  - `email` (string (email)): Main e-mail address (max length 255)
  - `employeeCount` (integer, nullable): Number of employees
  - `enrichedAt` (string (date-time), read-only): Time of the last enrichment
  - `enrichmentData` (any): Free JSON of an enrichment
  - `enrichmentStatus` (string): State of the data enrichment (one of `NOT_ENRICHED`, `PENDING`, `ENRICHED`, `FAILED`; default `"NOT_ENRICHED"`)
  - `externalIds` (object): Keys of other systems, at most 20; key `^[a-z0-9_-]{1,64}$`, value max. 255 characters
  - `fax` (string): E.164 (max length 64)
  - `firstName` (string): First name (of a person) (max length 128)
  - `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
  - `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
  - `gdprDataOrigin` (string): GDPR: where the data came from (max length 255)
  - `gdprPurpose` (string): GDPR: purpose of the processing (max length 255)
  - `gln` (string): Global Location Number with check digit
  - `id` (string (uuid), read-only): Id of the address
  - `industryCode` (string): Code of `industries`
  - `info` (string): Info text
  - `invoiceEmail` (string (email)): E-mail address for invoices (max length 255)
  - `isBlocked` (boolean): General block of the address
  - `isDiscountEligible` (boolean): Discounts may be granted
  - `isEuForeign` (boolean, read-only): Derived like `isForeign` (both countries in the EU)
  - `isForeign` (boolean, read-only): Derived on every write from the billing country (default billing postal address, else the first one) and the tenant country; ignored on write
  - `isOneTime` (boolean): One-time account (Diverse)
  - `isTaxInclusive` (boolean): Prices are gross (tax inclusive)
  - `languageCode` (string): ISO 639-1, optionally with region
  - `lastName` (string): Last name (required for `partyType` PERSON) (max length 128)
  - `legalForm` (string): Legal form (max length 64)
  - `marketingObjection` (boolean): Objection to advertising
  - `marketingObjectionAt` (string (date-time), nullable, read-only): Set by the server when `marketingObjection` turns true
  - `memo` (string): Internal memo
  - `mergedIntoId` (string (uuid), read-only): Set when the address was merged into another one
  - `mobile` (string): E.164 (max length 64)
  - `netDays` (integer, nullable): Payment term in days (net)
  - `ourCustomerNumber` (string): Our customer number at this party (max length 64)
  - `parentAddressId` (string (uuid)): Parent company (another address of the tenant; no cycles)
  - `parentName` (string, read-only): Display name of the parent address (set on read)
  - `partyType` (string): COMPANY needs `companyName`, PERSON needs `lastName` (one of `COMPANY`, `PERSON`; default `"COMPANY"`)
  - `paymentBlockReason` (string, read-only): Reason of the payment block
  - `paymentBlocked` (boolean, read-only): Payment block (set with `POST /addresses/{id}/blocks`; a PUT keeps it)
  - `paymentBlockedAt` (string (date-time), read-only): Time of the payment block
  - `paymentBlockedBy` (string, read-only): Actor of the payment block
  - `paymentMethodCode` (string): Code of `payment-methods`
  - `paymentTermCode` (string): Code of `payment-terms`
  - `peppolId` (string): Peppol participant ID `scheme:id`
  - `phone` (string): E.164 (+4989123456). Input is normalised with the country of the default billing postal address, else of the tenant profile, else DE; extensions are dropped; a changed value that cannot be parsed answers 400 (a value equal to the stored one is kept) (max length 64)
  - `postalAddresses` (array of PostalAddress): Postal addresses (Anschriften)
    - `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)
    - `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
  - `postingAccountNo` (string): Debtor account (Debitorenkonto). With the tenant's `glAccountLength` g it must lie in [10^g, 7*10^g-1] (g=4: 10000-69999); checked only when the value changes, else 400 (max length 32)
  - `purchaseOrderEmail` (string (email)): Mail address that receives the purchase orders sent to this supplier; empty falls back to `email` (max length 254)
  - `purchaseOrderRequired` (boolean, nullable): Invoices of this supplier need a purchase order. Omitted: `true` on create, unchanged on update
  - `registerCourt` (string): Register court (max length 128)
  - `reverseCharge` (boolean): Reverse charge (§13b UStG)
  - `roles` (array of string, read-only): Derived from the flags of the status (`isCustomer` CUSTOMER, `isVendor` SUPPLIER, `isLead` PROSPECT, `isPartner` PARTNER); a value in the request is ignored
  - `salesRepCommissionRate` (number, nullable): Commission of the sales representative in percent (max 100)
  - `salesRepNo` (string): Number of the sales representative (max length 32)
  - `salutationCode` (string): Code of `salutations`
  - `searchTerm` (string): Search term (Suchbegriff); derived from the name when empty (max length 255)
  - `sepaMandates` (array of SepaMandate): SEPA direct debit mandates
    - `bankAccountIban` (string, required): IBAN of a bank account of this address
    - `signedAt` (string (date), required): Date of signature (YYYY-MM-DD)
    - `bankAccountId` (string (uuid), read-only): Id of the linked bank account
    - `creditorId` (string): Creditor identifier (max length 35)
    - `id` (string (uuid)): Id of the mandate
    - `lastUsedAt` (string (date), nullable): Set when a collection uses the mandate. A mandate with lastUsedAt cannot be deleted, also not together with its bank account: a PUT that omits it answers 409; revoke it with status REVOKED instead
    - `mandateReference` (string): Assigned from the MANDATE range when empty
    - `mandateType` (string): CORE or B2B direct debit (one of `CORE`, `B2B`; default `"CORE"`)
    - `revokedAt` (string (date), nullable): Set by the server for status REVOKED (the first stamp stays; a client value is ignored)
    - `sequenceType` (string): Sequence type of the next collection (one of `FRST`, `RCUR`, `OOFF`, `FNAL`; default `"FRST"`)
    - `status` (string): State of the mandate (one of `ACTIVE`, `REVOKED`, `EXPIRED`; default `"ACTIVE"`)
    - `validFrom` (string (date), nullable): Valid from (YYYY-MM-DD)
  - `shippingTypeCode` (string): Code of `shipping-types`
  - `skontoDays1` (integer, nullable): Days for the first cash discount
  - `skontoDays2` (integer, nullable): Days for the second cash discount
  - `skontoRate1` (number, nullable): First cash discount in percent (max 100)
  - `skontoRate2` (number, nullable): Second cash discount in percent (max 100)
  - `smallBusiness` (boolean): Small business (§19 UStG)
  - `source` (string): Where the address came from (lead source) (max length 64)
  - `supplierNumber` (string): Supplier number (Lieferantennummer), unique among the live addresses of the tenant (`409` `supplier_number_taken`). Empty on an address with the role SUPPLIER: the address number (adrNr) is used while no other address has it as supplier number (max length 64)
  - `syncStatus` (string, read-only): Reserved for an ERP synchronisation; STANDALONE for records of this API (one of `STANDALONE`, `PENDING_CREATION`, `PENDING_UPDATE`, `SYNCED`, `CONFLICT`, `ERROR`)
  - `tags` (array of string): Duplicates (case-insensitive) are removed
  - `taxNumber` (string): Tax number (Steuernummer) (max length 64)
  - `taxZone` (string, read-only): Derived on every write: DOMESTIC (billing country = tenant country), EU_VATID (EU with `vatId`), EU_PRIVATE (EU without `vatId`), THIRD_COUNTRY; empty without a postal address. Ignored on write. `vatCategory` stays for compatibility (one of `DOMESTIC`, `EU_VATID`, `EU_PRIVATE`, `THIRD_COUNTRY`)
  - `tenantName` (string, read-only): Tenant name (from the token)
  - `title` (string): Title of the party (e.g. Dr.) (max length 64)
  - `updatedAt` (string (date-time), read-only): Time of the last change
  - `updatedBy` (string, read-only): Who changed the address last (subject of the token)
  - `valutaDays` (integer, nullable): Value date days
  - `vatCategory` (integer): VAT category (microtech) (max 9)
  - `vatCheckStatus` (VatCheckStatus, read-only): Result of the latest official VAT check (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`, `NOT_CHECKED`)
  - `vatCheckedAt` (string (date-time), read-only): Time of the latest official VAT check
  - `vatId` (string): VAT ID (USt-IdNr.)
  - `website` (string (uri)): Website (max length 255)
- `duplicates` (array of DuplicateCandidate, required): Existing addresses that look the same
  - `adrNr` (string, required): Address number
  - `displayName` (string, required): Display name
  - `id` (string (uuid), required): Id of the existing address
  - `reasons` (array of string, required): Why it may be the same
  - `score` (integer, required): Similarity score (at least 40) (max 100)
  - `city` (string): City of the default billing postal address (else the lowest `ansNr`)
- `fieldSources` (FieldSources, required): Where each pre-filled field (JSON name) came from
- `warnings` (array of DraftWarning, required): Unknown lookup codes, invalid formats or failed sources
  - `message` (string, required): German hint
  - `field` (string): JSON name of the draft field (empty for the whole draft)
- `imprintUrl` (string): The imprint page that was read

Example 200 answer:

```json
{
  "aiAvailable": true,
  "draft": {
    "companyName": "Hotel Waldblick Bodenmais",
    "contactPersons": [
      {
        "email1": "info@hotel-waldblick.example",
        "firstName": "Markus",
        "lastName": "Pongratz",
        "position": "Inhaber",
        "salutationCode": "HERR"
      }
    ],
    "email": "info@hotel-waldblick.example",
    "legalForm": "GmbH",
    "partyType": "COMPANY",
    "phone": "+49992477810",
    "postalAddresses": [
      {
        "city": "Bodenmais",
        "countryCode": "DE",
        "isDefaultBilling": true,
        "postalCode": "94249",
        "street": "Waldweg 7"
      }
    ],
    "statusCode": "INTERESSENT",
    "version": 0,
    "website": "https://www.hotel-waldblick.example"
  },
  "duplicates": [],
  "fieldSources": {
    "companyName": "imprint",
    "email": "imprint",
    "legalForm": "imprint",
    "phone": "imprint",
    "website": "text"
  },
  "imprintUrl": "https://www.hotel-waldblick.example/impressum",
  "warnings": [
    {
      "field": "vatId",
      "message": "Im Impressum wurde keine USt-IdNr. gefunden."
    }
  ]
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/masterdata/addresses:draft' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"text":"Muster GmbH\nErika Musterfrau, Einkauf\nHauptstraße 1, 10115 Berlin\nTel. +49 30 1234567\neinkauf@muster.de"}'
```

## Read the imprint of a website (tenant:masterdata:read)

`POST /api/masterdata/imprint:lookup`

Module: Master data · operationId: `lookupImprint` · Tag: Drafts · Auth: access token (`Authorization: Bearer <accessToken>`)

Fetches and parses a German imprint (Impressum). A URL with a path is read as given; a
homepage, a domain or an email address starts the discovery (homepage → imprint link →
`/impressum`, `/imprint`). Only public web addresses are fetched. Free-mail domains answer
`422` (`free_mail_domain`), invalid or disallowed targets `400` (`invalid`),
unreachable sites or timeouts `502` (`unavailable`).

### Request body

`application/json` (required)

- `domain` (string): Domain whose website is searched for an imprint (max length 255)
- `email` (string): E-mail address whose domain is looked up (max length 320)
- `url` (string): Imprint URL (read as given) or homepage (max length 2048)

Example:

```json
{
  "domain": "muster.de"
}
```

### Responses

- **200** The parsed imprint (`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`)
- **429** Too many AI drafts or imprint lookups of this person – wait `Retry-After` seconds ([rate limits](/guides/rate-limits)) (`application/json`)
- **502** The website could not be read (`application/json`)

Fields of the 200 answer:

- `managingDirectors` (array of string, required): Managing directors (empty when none were found)
- `url` (string, required): The page that was read
- `city` (string): City
- `companyName` (string): Company name
- `email` (string): E-mail address
- `legalForm` (string): Legal form
- `phone` (string): Phone number
- `registerCourt` (string): Register court
- `registerNo` (string): Commercial register number
- `street` (string): Street with house number
- `vatId` (string): VAT ID
- `zip` (string): Postal code

Example 200 answer:

```json
{
  "city": "Bodenmais",
  "companyName": "Hotel Waldblick Bodenmais GmbH",
  "email": "info@hotel-waldblick.example",
  "legalForm": "GmbH",
  "managingDirectors": [
    "Markus Pongratz"
  ],
  "phone": "+49 9924 77810",
  "registerCourt": "Amtsgericht Deggendorf",
  "registerNo": "HRB 9876",
  "street": "Waldweg 7",
  "url": "https://www.hotel-waldblick.example/impressum",
  "zip": "94249"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/masterdata/imprint:lookup' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"domain":"muster.de"}'
```

## Draft a contact person from text or an image (tenant:masterdata:write)

`POST /api/masterdata/addresses/{id}/contacts:draft`

Module: Master data · operationId: `draftContactPerson` · Tag: Drafts · Auth: access token (`Authorization: Bearer <accessToken>`)

Extracts a contact person of the address from pasted text or an image (`url` and `email` are
not used). Nothing is stored. `duplicates` lists contacts of the same address that look the same.

### Parameters

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

### Request body

`application/json` (required)

- `email` (string): Email address whose domain is looked up (address drafts only) (max length 320)
- `imageData` (string): Base64 image or data URI (business card, scanned letter); read via OCR after a malware scan (an image with a finding, or when the scan is unavailable, is not read and a warning on imageData says why) (max length 3145728)
- `mimeType` (string): `image/*` or `application/pdf` (max length 64)
- `text` (string): Pasted text: email signature, letterhead, delivery address … (max length 20000)
- `url` (string): Website or imprint URL (address drafts only) (max length 2048)

Example:

```json
{
  "text": "Erika Musterfrau\nLeitung Einkauf\nMobil +49 171 1234567\nerika.musterfrau@muster.de"
}
```

### Responses

- **200** The draft (`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`)
- **413** The body is over the limit (2 MiB; AI drafts 4 MiB) (`application/json`)
- **429** Too many AI drafts or imprint lookups of this person – wait `Retry-After` seconds ([rate limits](/guides/rate-limits)) (`application/json`)
- **502** The AI could not read the input (`application/json`)
- **503** The AI is not reachable (`application/json`)

Fields of the 200 answer:

- `aiAvailable` (boolean, required): False when the AI was not available
- `draft` (ContactPerson, required): One contact person (Ansprechpartner). Needs a first or last name; at most one default contact.
  - `aspNr` (integer): Number within the address; assigned
  - `availableFrom1` (string, nullable): Reachable from (HH:MM)
  - `availableFrom2` (string, nullable): Second time window: reachable from (HH:MM)
  - `availableTo1` (string, nullable): After `availableFrom1`
  - `availableTo2` (string, nullable): After `availableFrom2`
  - `birthday` (string (date), nullable): Birthday (YYYY-MM-DD)
  - `blockReason` (string, read-only): Reason of the block
  - `blockedAt` (string (date-time), read-only): Time of the block
  - `blockedBy` (string, read-only): Actor of the block
  - `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`.
  - `department` (string): Department
  - `doNotCall` (boolean): Do not call
  - `email1` (string (email)): First e-mail address
  - `email2` (string (email)): Second e-mail address
  - `emailOptOut` (boolean): No marketing e-mails
  - `fax` (string): E.164
  - `firstName` (string): First name (max length 128)
  - `gdprConsent` (string): GDPR consent state (one of `UNKNOWN`, `GRANTED`, `DENIED`, `REVOKED`; default `"UNKNOWN"`)
  - `gdprConsentDate` (string (date), nullable): Required when `gdprConsent` is GRANTED
  - `id` (string (uuid)): Id of the contact person
  - `info` (string): Info text
  - `isActive` (boolean): False when `leftAt` is set (default `true`)
  - `isBlocked` (boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set with `POST /addresses/{id}/contacts/{cid}/block`
  - `isDefault` (boolean): Default contact of the address (at most one)
  - `languageCode` (string): Language (ISO 639-1)
  - `lastName` (string): Last name (max length 128)
  - `leftAt` (string (date), nullable): Date the person left the company; sets `isActive` false
  - `letterSalutation` (string): Salutation line of letters
  - `linkedinUrl` (string (uri)): LinkedIn profile (max length 255)
  - `mobile` (string): E.164
  - `namePrefix` (string): Name prefix
  - `nameSuffix` (string): Name suffix
  - `phone1` (string): E.164
  - `phone2` (string): E.164
  - `portalUserId` (string): Linked desk portal user (max length 255)
  - `position` (string): Position
  - `postalAddressAnsNr` (integer, nullable): `ansNr` of a postal address of the same address
  - `preferredChannel` (string): Preferred contact channel (one of `EMAIL`, `PHONE`, `MOBILE`, `LETTER`, `PORTAL`)
  - `reportsToAspNr` (integer, nullable): `aspNr` of the manager within the same address (no cycles)
  - `roles` (array of string): Roles in the buying centre or for ticket routing
  - `salutationCode` (string): Code of `salutations`
  - `timezone` (string): IANA time zone
  - `title` (string): Title
  - `version` (integer): Version of this contact (child updates)
- `duplicates` (array of ChildDuplicate, required): Contact persons of the same address that look the same
  - `id` (string (uuid), required): Id of the existing contact person or postal address
  - `label` (string, required): Name or street line of the existing entry
  - `number` (integer, required): `aspNr` or `ansNr`
  - `reason` (string, required): Why it looks the same (EMAIL, NAME or POSTAL_CODE)
- `fieldSources` (FieldSources, required): Where each pre-filled field (JSON name) came from
- `warnings` (array of DraftWarning, required): Unknown lookup codes, invalid formats or failed sources
  - `message` (string, required): German hint
  - `field` (string): JSON name of the draft field (empty for the whole draft)

Example 200 answer:

```json
{
  "aiAvailable": true,
  "draft": {
    "email1": "info@hotel-waldblick.example",
    "firstName": "Markus",
    "lastName": "Pongratz",
    "phone1": "+49992477810",
    "position": "Inhaber",
    "salutationCode": "HERR"
  },
  "duplicates": [],
  "fieldSources": {
    "email1": "text",
    "firstName": "text",
    "lastName": "text",
    "phone1": "text",
    "position": "text"
  },
  "warnings": []
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4/contacts:draft' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"text":"Erika Musterfrau\nLeitung Einkauf\nMobil +49 171 1234567\nerika.musterfrau@muster.de"}'
```

## Draft a postal address from text or an image (tenant:masterdata:write)

`POST /api/masterdata/addresses/{id}/postal-addresses:draft`

Module: Master data · operationId: `draftPostalAddress` · Tag: Drafts · Auth: access token (`Authorization: Bearer <accessToken>`)

Extracts a postal address (e.g. a delivery address) of the address from pasted text or an image (`url` and `email` are not used). Nothing is stored.

### Parameters

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

### Request body

`application/json` (required)

- `email` (string): Email address whose domain is looked up (address drafts only) (max length 320)
- `imageData` (string): Base64 image or data URI (business card, scanned letter); read via OCR after a malware scan (an image with a finding, or when the scan is unavailable, is not read and a warning on imageData says why) (max length 3145728)
- `mimeType` (string): `image/*` or `application/pdf` (max length 64)
- `text` (string): Pasted text: email signature, letterhead, delivery address … (max length 20000)
- `url` (string): Website or imprint URL (address drafts only) (max length 2048)

Example:

```json
{
  "text": "Lieferanschrift: Muster GmbH, Lager Nord, Industriestraße 12, 22113 Hamburg"
}
```

### Responses

- **200** The draft (`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`)
- **413** The body is over the limit (2 MiB; AI drafts 4 MiB) (`application/json`)
- **429** Too many AI drafts or imprint lookups of this person – wait `Retry-After` seconds ([rate limits](/guides/rate-limits)) (`application/json`)
- **502** The AI could not read the input (`application/json`)
- **503** The AI is not reachable (`application/json`)

Fields of the 200 answer:

- `aiAvailable` (boolean, required): False when the AI was not available
- `draft` (PostalAddress, required): One postal address (Anschrift). Needs a street, PO box or city. At most one default per kind.
  - `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
- `duplicates` (array of ChildDuplicate, required): Postal addresses of the same address that look the same
  - `id` (string (uuid), required): Id of the existing contact person or postal address
  - `label` (string, required): Name or street line of the existing entry
  - `number` (integer, required): `aspNr` or `ansNr`
  - `reason` (string, required): Why it looks the same (EMAIL, NAME or POSTAL_CODE)
- `fieldSources` (FieldSources, required): Where each pre-filled field (JSON name) came from
- `warnings` (array of DraftWarning, required): Unknown lookup codes, invalid formats or failed sources
  - `message` (string, required): German hint
  - `field` (string): JSON name of the draft field (empty for the whole draft)

Example 200 answer:

```json
{
  "aiAvailable": true,
  "draft": {
    "city": "Bodenmais",
    "countryCode": "DE",
    "name1": "Hotel Waldblick Bodenmais",
    "postalCode": "94249",
    "street": "Waldweg 7"
  },
  "duplicates": [],
  "fieldSources": {
    "city": "text",
    "name1": "text",
    "postalCode": "text",
    "street": "text"
  },
  "warnings": []
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4/postal-addresses:draft' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"text":"Lieferanschrift: Muster GmbH, Lager Nord, Industriestraße 12, 22113 Hamburg"}'
```

# Lookups

## List the parameter tables (tenant:masterdata:read)

`GET /api/masterdata/lookups`

Module: Master data · operationId: `listLookupKinds` · Tag: Lookups · Auth: access token (`Authorization: Bearer <accessToken>`)

### Responses

- **200** Names of the parameter tables, sorted (`application/json`)
- **401** Missing, invalid or expired token (empty body)
- **403** The token lacks the permission or carries no tenant (`application/json`)

Fields of the 200 answer:

- `items` (array of LookupKind, required)

Example 200 answer:

```json
{
  "items": [
    "address-statuses",
    "currencies",
    "industries",
    "payment-methods",
    "payment-terms",
    "salutations",
    "shipping-types",
    "tax-keys",
    "units"
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/masterdata/lookups' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List the UN/ECE Recommendation 20 unit codes (tenant:masterdata:read)

`GET /api/masterdata/lookups/unece-units`

Module: Master data · operationId: `listUneceUnits` · Tag: Lookups · Auth: access token (`Authorization: Bearer <accessToken>`)

The catalogue a unit's `uneceCode` must come from. `unece-units` is a fixed route, not a parameter table.

### Responses

- **200** Catalogue (`application/json`)
- **401** Missing, invalid or expired token (empty body)
- **403** The token lacks the permission or carries no tenant (`application/json`)

Fields of the 200 answer:

- `items` (array of UneceUnit, required)
  - `code` (string, required): UN/ECE Recommendation 20 unit code
  - `name` (string, required): German name of the unit

Example 200 answer:

```json
{
  "items": [
    {
      "code": "C62",
      "name": "Stück"
    },
    {
      "code": "HUR",
      "name": "Stunde"
    },
    {
      "code": "MTR",
      "name": "Meter"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/masterdata/lookups/unece-units' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List the entries of a parameter table (tenant:masterdata:read)

`GET /api/masterdata/lookups/{kind}`

Module: Master data · operationId: `listLookupEntries` · Tag: Lookups · Auth: access token (`Authorization: Bearer <accessToken>`)

Ordered by `sortOrder`, then code. An unknown kind answers `404`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `active` | query | boolean |  | `true` returns active entries only (for selects) (default `false`) |
| `kind` | path | LookupKind | yes | Parameter table (one of `address-statuses`, `currencies`, `industries`, `payment-methods`, `payment-terms`, `salutations`, `shipping-types`, `tax-keys`, `units`) |

### Responses

- **200** Entries (`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 LookupEntry, required)
  - `name` (string, required): Display name (max length 128)
  - `code` (string, read-only): Taken from the path on write
  - `isActive` (boolean): Offered in selects (default `true`)
  - `sortOrder` (integer): Position in the table (default `0`)
  - `updatedAt` (string (date-time), read-only): Time of the last change

Example 200 answer:

```json
{
  "items": [
    {
      "code": "NETTO30",
      "isActive": true,
      "name": "30 Tage netto",
      "netDays": 30,
      "sortOrder": 0,
      "text": "Zahlbar innerhalb von 30 Tagen ohne Abzug.",
      "updatedAt": "2026-01-02T08:00:00Z"
    },
    {
      "code": "SKONTO14",
      "isActive": true,
      "name": "14 Tage 2 % Skonto, 30 Tage netto",
      "netDays": 30,
      "skontoDays1": 14,
      "skontoRate1": 2,
      "sortOrder": 1,
      "text": "Zahlbar innerhalb von 14 Tagen mit 2 % Skonto oder 30 Tagen ohne Abzug.",
      "updatedAt": "2026-01-02T08:00:00Z"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/masterdata/lookups/address-statuses' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Reorder a parameter table (tenant:settings:write)

`PATCH /api/masterdata/lookups/{kind}`

Module: Master data · operationId: `reorderLookupEntries` · Tag: Lookups · Auth: access token (`Authorization: Bearer <accessToken>`)

`order` must name every code of the table exactly once, first to last; the entries get the
sort orders 10, 20, …. When the table changed meanwhile nothing is written and the answer is
`409`. Emits `masterdata.lookup.updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `kind` | path | LookupKind | yes | Parameter table (one of `address-statuses`, `currencies`, `industries`, `payment-methods`, `payment-terms`, `salutations`, `shipping-types`, `tax-keys`, `units`) |

### Request body

`application/json` (required)

- `order` (array of string, required): Every code of the table in the new order

Example:

```json
{
  "order": [
    "NETTO30",
    "NETTO14",
    "SKONTO2_14",
    "SOFORT"
  ]
}
```

### Responses

- **204** Reordered
- **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`)

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/masterdata/lookups/address-statuses' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"order":["NETTO30","NETTO14","SKONTO2_14","SOFORT"]}'
```

## Create or replace a lookup entry (tenant:settings:write)

`PUT /api/masterdata/lookups/{kind}/{code}`

Module: Master data · operationId: `upsertLookupEntry` · Tag: Lookups · Auth: access token (`Authorization: Bearer <accessToken>`)

Kind-specific columns that are omitted are reset to their default. For `currencies` the ECB rate wins over the `exchangeRate` of the body when the ECB publishes the currency (`rateSource` `ECB`); `rateSource` and `rateDate` are read-only. For `address-statuses` the roles of every address with the status are re-derived in the same transaction; in the operator tenant `10639/MBCOM` removing `isCustomer` from a status of an address with active platform tenants answers `409`. Emits `masterdata.lookup.updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `kind` | path | LookupKind | yes | Parameter table (one of `address-statuses`, `currencies`, `industries`, `payment-methods`, `payment-terms`, `salutations`, `shipping-types`, `tax-keys`, `units`) |
| `code` | path | string | yes | Entry code (`^[A-Za-z0-9_.-]{1,32}$`, stored upper-case), for `currencies` an ISO 4217 code |

### Request body

`application/json` (required)

- `name` (string, required): Display name (max length 128)
- `code` (string, read-only): Taken from the path on write
- `isActive` (boolean): Offered in selects (default `true`)
- `sortOrder` (integer): Position in the table (default `0`)
- `updatedAt` (string (date-time), read-only): Time of the last change

Example:

```json
{
  "isActive": true,
  "name": "30 Tage netto",
  "netDays": 30,
  "sortOrder": 30,
  "text": "Zahlbar innerhalb von 30 Tagen ohne Abzug."
}
```

### 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:

- `name` (string, required): Display name (max length 128)
- `code` (string, read-only): Taken from the path on write
- `isActive` (boolean): Offered in selects (default `true`)
- `sortOrder` (integer): Position in the table (default `0`)
- `updatedAt` (string (date-time), read-only): Time of the last change

Example 200 answer:

```json
{
  "code": "NETTO30",
  "isActive": true,
  "name": "30 Tage netto",
  "netDays": 30,
  "sortOrder": 0,
  "text": "Zahlbar innerhalb von 30 Tagen ohne Abzug.",
  "updatedAt": "2026-01-02T08:00:00Z"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/masterdata/lookups/address-statuses/NETTO30' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"isActive":true,"name":"30 Tage netto","netDays":30,"sortOrder":30,"text":"Zahlbar innerhalb von 30 Tagen ohne Abzug."}'
```

## Delete an unused lookup entry (tenant:settings:write)

`DELETE /api/masterdata/lookups/{kind}/{code}`

Module: Master data · operationId: `deleteLookupEntry` · Tag: Lookups · Auth: access token (`Authorization: Bearer <accessToken>`)

An entry still used by addresses or articles answers `409`; deactivate it (`isActive` false) instead. Emits `masterdata.lookup.updated`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `kind` | path | LookupKind | yes | Parameter table (one of `address-statuses`, `currencies`, `industries`, `payment-methods`, `payment-terms`, `salutations`, `shipping-types`, `tax-keys`, `units`) |
| `code` | path | string | yes | Entry code (`^[A-Za-z0-9_.-]{1,32}$`, stored upper-case), for `currencies` an ISO 4217 code |

### Responses

- **204** Deleted
- **400** Invalid input (`invalid`); `field` names the first, `details.fields` each invalid field (`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`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/masterdata/lookups/address-statuses/NETTO30' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Settings

## List the number ranges (tenant:masterdata:read)

`GET /api/masterdata/sequences`

Module: Master data · operationId: `listSequences` · Tag: Settings · Auth: access token (`Authorization: Bearer <accessToken>`)

### Responses

- **200** Number ranges (`application/json`)
- **401** Missing, invalid or expired token (empty body)
- **403** The token lacks the permission or carries no tenant (`application/json`)

Fields of the 200 answer:

- `items` (array of Sequence, required)
  - `currentValue` (integer (int64), required): Last assigned value
  - `highestIssued` (integer (int64), required): Highest number with this prefix already in use (0 when none); the counter cannot be set below it
  - `minDigits` (integer, required): Minimum number of digits (zero-padded)
  - `nextNumber` (string, required): The next number that would be assigned
  - `prefix` (string, required): Prefix of the numbers
  - `sequenceType` (string, required): ADDRESS, PRODUCT, MANDATE or a named address range ADDRESS:NAME
  - `updatedAt` (string (date-time), required): Time of the last change
  - `label` (string): Name of a named range

Example 200 answer:

```json
{
  "items": [
    {
      "currentValue": 10031,
      "highestIssued": 10031,
      "label": "Adressen",
      "minDigits": 5,
      "nextNumber": "10032",
      "prefix": "",
      "sequenceType": "ADDRESS",
      "updatedAt": "2026-11-04T09:15:00Z"
    },
    {
      "currentValue": 70011,
      "highestIssued": 70011,
      "label": "Lieferantennummern",
      "minDigits": 5,
      "nextNumber": "70012",
      "prefix": "",
      "sequenceType": "ADDRESS:LIEFERANT",
      "updatedAt": "2026-09-02T14:30:00Z"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/masterdata/sequences' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create a number range (tenant:settings:write)

`POST /api/masterdata/sequences`

Module: Master data · operationId: `createSequence` · Tag: Settings · Auth: access token (`Authorization: Bearer <accessToken>`)

Creates a named address range `ADDRESS:NAME` (capitals, digits, `_`, `-`; up to 24 characters after the colon) that address statuses can name (`sequenceType` of `address-statuses`). A range that exists answers `409`; a `currentValue` below the highest number already issued with that prefix answers `400` on `currentValue`.

### Request body

`application/json` (required)

- `minDigits` (integer, required): Minimum number of digits (zero-padded) (max 18)
- `sequenceType` (string, required): Named address range ADDRESS:NAME (max length 32)
- `currentValue` (integer (int64)): Last assigned value
- `label` (string): Name of the range (max length 128)
- `prefix` (string): No whitespace (max length 16)

Example:

```json
{
  "currentValue": 0,
  "label": "Privatkunden",
  "minDigits": 5,
  "prefix": "P",
  "sequenceType": "ADDRESS:PRIVAT"
}
```

### Responses

- **201** Created (`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`)
- **409** Stale version or conflict with existing data (`application/json`)

Fields of the 201 answer:

- `currentValue` (integer (int64), required): Last assigned value
- `highestIssued` (integer (int64), required): Highest number with this prefix already in use (0 when none); the counter cannot be set below it
- `minDigits` (integer, required): Minimum number of digits (zero-padded)
- `nextNumber` (string, required): The next number that would be assigned
- `prefix` (string, required): Prefix of the numbers
- `sequenceType` (string, required): ADDRESS, PRODUCT, MANDATE or a named address range ADDRESS:NAME
- `updatedAt` (string (date-time), required): Time of the last change
- `label` (string): Name of a named range

Example 201 answer:

```json
{
  "currentValue": 70011,
  "highestIssued": 70011,
  "label": "Lieferantennummern",
  "minDigits": 5,
  "nextNumber": "70012",
  "prefix": "",
  "sequenceType": "ADDRESS:LIEFERANT",
  "updatedAt": "2026-09-02T14:30:00Z"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/masterdata/sequences' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"currentValue":0,"label":"Privatkunden","minDigits":5,"prefix":"P","sequenceType":"ADDRESS:PRIVAT"}'
```

## Change a number range (tenant:settings:write)

`PUT /api/masterdata/sequences/{type}`

Module: Master data · operationId: `updateSequence` · Tag: Settings · Auth: access token (`Authorization: Bearer <accessToken>`)

Sets prefix, counter (the last assigned value) and the minimum number of digits. Numbers that are already taken are skipped when assigning. A counter below the highest number already issued with that prefix (`highestIssued`) answers `400` on `currentValue`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `type` | path | string | yes | Number range (case-insensitive): ADDRESS, PRODUCT, MANDATE or a named address range ADDRESS:NAME |

### Request body

`application/json` (required)

- `minDigits` (integer, required): Minimum number of digits (zero-padded) (max 18)
- `currentValue` (integer (int64)): Last assigned value; not below `highestIssued`
- `label` (string): Optional; omitted keeps the label (max length 128)
- `prefix` (string): No whitespace (max length 16)

Example:

```json
{
  "currentValue": 41,
  "minDigits": 5,
  "prefix": "A"
}
```

### 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`)

Fields of the 200 answer:

- `currentValue` (integer (int64), required): Last assigned value
- `highestIssued` (integer (int64), required): Highest number with this prefix already in use (0 when none); the counter cannot be set below it
- `minDigits` (integer, required): Minimum number of digits (zero-padded)
- `nextNumber` (string, required): The next number that would be assigned
- `prefix` (string, required): Prefix of the numbers
- `sequenceType` (string, required): ADDRESS, PRODUCT, MANDATE or a named address range ADDRESS:NAME
- `updatedAt` (string (date-time), required): Time of the last change
- `label` (string): Name of a named range

Example 200 answer:

```json
{
  "currentValue": 70011,
  "highestIssued": 70011,
  "label": "Lieferantennummern",
  "minDigits": 5,
  "nextNumber": "70012",
  "prefix": "",
  "sequenceType": "ADDRESS:LIEFERANT",
  "updatedAt": "2026-09-02T14:30:00Z"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/masterdata/sequences/ADDRESS:KUNDEN' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"currentValue":41,"minDigits":5,"prefix":"A"}'
```

## Delete a named address range (tenant:settings:write)

`DELETE /api/masterdata/sequences/{type}`

Module: Master data · operationId: `deleteSequence` · Tag: Settings · Auth: access token (`Authorization: Bearer <accessToken>`)

Only ranges `ADDRESS:NAME` can be deleted (`400` for the standard ranges); a range an address status still names answers `409`. Numbers already assigned stay.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `type` | path | string | yes | Number range (case-insensitive): ADDRESS, PRODUCT, MANDATE or a named address range ADDRESS:NAME |

### Responses

- **204** Deleted
- **400** Invalid input (`invalid`); `field` names the first, `details.fields` each invalid field (`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`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/masterdata/sequences/ADDRESS:KUNDEN' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Get the tenant's own company profile (tenant:masterdata:read)

`GET /api/masterdata/tenant-profile`

Module: Master data · operationId: `getTenantProfile` · Tag: Settings · Auth: access token (`Authorization: Bearer <accessToken>`)

`404` until the profile was saved once.

### Responses

- **200** The profile (`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:

- `companyName` (string, required): Company name of the tenant (max length 255)
- `version` (integer, required): 0 creates the profile; otherwise the version you read
- `city` (string): City (max length 128)
- `commercialRegister` (string): Commercial register number (max length 128)
- `companyNameAddition` (string): Company name addition (max length 255)
- `countryCode` (string): Country (ISO 3166-1 alpha-2); decides whether addresses are foreign (default `"DE"`)
- `defaultBankName` (string): Name of the default bank (max length 128)
- `defaultBic` (string): BIC of the default bank account
- `defaultIban` (string): IBAN of the default bank account
- `email` (string (email)): E-mail address (max length 255)
- `geocodePrecision` (string, read-only): See `PostalAddress.geocodePrecision` (one of `HOUSE`, `STREET`, `LOCALITY`, `POSTCODE`)
- `geocodeStatus` (string, read-only): See `PostalAddress.geocodeStatus` (one of `PENDING`, `DONE`, `FAILED`, `SKIPPED`)
- `glAccountLength` (integer, nullable): Length g of the G/L accounts; unset: account numbers of addresses are not checked. Changing it never fails because of existing addresses (max 8)
- `invoiceContactEmail` (string (email)): E-mail of the invoice contact (BT-43); empty: `invoiceEmail`, else `email` (max length 255)
- `invoiceContactName` (string): Contact person outgoing invoices name (XRechnung BT-41, required there) (max length 128)
- `invoiceContactPhone` (string): Phone of the invoice contact (BT-42); empty: `phone` (max length 64)
- `invoiceEmail` (string (email)): Electronic address of the seller on outgoing e-invoices (BT-34, scheme EM); empty: `email` (max length 255)
- `latitude` (number, nullable, read-only): WGS 84, geocoded from the address like a postal address (origin of distances); ignored on writes
- `longitude` (number, nullable, read-only): WGS 84
- `managingDirectors` (string): Managing directors (max length 255)
- `phone` (string): Phone (max length 64)
- `postalCode` (string): Postal code (max length 32)
- `registerCourt` (string): Register court (max length 128)
- `sepaCreditorId` (string): SEPA creditor identifier (max length 35)
- `street` (string): Street with house number (max length 255)
- `taxNumber` (string): Tax number (max length 64)
- `updatedAt` (string (date-time), read-only): Time of the last change
- `vatId` (string): VAT ID of the tenant (used for official VAT checks)
- `website` (string): Website (max length 255)

Example 200 answer:

```json
{
  "city": "Regensburg",
  "commercialRegister": "HRB 99999",
  "companyName": "Muster IT-Systemhaus GmbH",
  "countryCode": "DE",
  "defaultBankName": "Stadtsparkasse München",
  "defaultBic": "SSKMDEMMXXX",
  "defaultIban": "DE66701500000001234567",
  "email": "info@muster-it.example",
  "geocodePrecision": "HOUSE",
  "geocodeStatus": "DONE",
  "glAccountLength": 4,
  "invoiceContactEmail": "christina.adler@muster-it.example",
  "invoiceContactName": "Christina Adler",
  "invoiceContactPhone": "+4994112345015",
  "invoiceEmail": "rechnungen@muster-it.example",
  "latitude": 49.0134,
  "longitude": 12.1325,
  "managingDirectors": "Thomas Pfeiffer",
  "phone": "+49941123450",
  "postalCode": "93055",
  "registerCourt": "Amtsgericht Regensburg",
  "street": "Industriestraße 12",
  "updatedAt": "2026-06-01T10:00:00Z",
  "vatId": "DE999000111",
  "version": 4,
  "website": "https://www.muster-it.example"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/masterdata/tenant-profile' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Save the tenant's own company profile (tenant:settings:write)

`PUT /api/masterdata/tenant-profile`

Module: Master data · operationId: `saveTenantProfile` · Tag: Settings · Auth: access token (`Authorization: Bearer <accessToken>`)

`version` 0 creates the profile (`409` if one exists), otherwise `version` must match the
stored one. The VAT ID is used for official VAT checks, the country decides whether addresses
are foreign. Emits `masterdata.tenant_profile.updated`.

### Request body

`application/json` (required)

- `companyName` (string, required): Company name of the tenant (max length 255)
- `version` (integer, required): 0 creates the profile; otherwise the version you read
- `city` (string): City (max length 128)
- `commercialRegister` (string): Commercial register number (max length 128)
- `companyNameAddition` (string): Company name addition (max length 255)
- `countryCode` (string): Country (ISO 3166-1 alpha-2); decides whether addresses are foreign (default `"DE"`)
- `defaultBankName` (string): Name of the default bank (max length 128)
- `defaultBic` (string): BIC of the default bank account
- `defaultIban` (string): IBAN of the default bank account
- `email` (string (email)): E-mail address (max length 255)
- `geocodePrecision` (string, read-only): See `PostalAddress.geocodePrecision` (one of `HOUSE`, `STREET`, `LOCALITY`, `POSTCODE`)
- `geocodeStatus` (string, read-only): See `PostalAddress.geocodeStatus` (one of `PENDING`, `DONE`, `FAILED`, `SKIPPED`)
- `glAccountLength` (integer, nullable): Length g of the G/L accounts; unset: account numbers of addresses are not checked. Changing it never fails because of existing addresses (max 8)
- `invoiceContactEmail` (string (email)): E-mail of the invoice contact (BT-43); empty: `invoiceEmail`, else `email` (max length 255)
- `invoiceContactName` (string): Contact person outgoing invoices name (XRechnung BT-41, required there) (max length 128)
- `invoiceContactPhone` (string): Phone of the invoice contact (BT-42); empty: `phone` (max length 64)
- `invoiceEmail` (string (email)): Electronic address of the seller on outgoing e-invoices (BT-34, scheme EM); empty: `email` (max length 255)
- `latitude` (number, nullable, read-only): WGS 84, geocoded from the address like a postal address (origin of distances); ignored on writes
- `longitude` (number, nullable, read-only): WGS 84
- `managingDirectors` (string): Managing directors (max length 255)
- `phone` (string): Phone (max length 64)
- `postalCode` (string): Postal code (max length 32)
- `registerCourt` (string): Register court (max length 128)
- `sepaCreditorId` (string): SEPA creditor identifier (max length 35)
- `street` (string): Street with house number (max length 255)
- `taxNumber` (string): Tax number (max length 64)
- `updatedAt` (string (date-time), read-only): Time of the last change
- `vatId` (string): VAT ID of the tenant (used for official VAT checks)
- `website` (string): Website (max length 255)

Example:

```json
{
  "city": "Regensburg",
  "commercialRegister": "HRB 99999",
  "companyName": "Muster IT-Systemhaus GmbH",
  "countryCode": "DE",
  "defaultBankName": "Stadtsparkasse München",
  "defaultBic": "SSKMDEMMXXX",
  "defaultIban": "DE66701500000001234567",
  "email": "info@muster-it.example",
  "geocodePrecision": "HOUSE",
  "geocodeStatus": "DONE",
  "glAccountLength": 4,
  "invoiceContactEmail": "christina.adler@muster-it.example",
  "invoiceContactName": "Christina Adler",
  "invoiceContactPhone": "+4994112345015",
  "invoiceEmail": "rechnungen@muster-it.example",
  "latitude": 49.0134,
  "longitude": 12.1325,
  "managingDirectors": "Thomas Pfeiffer",
  "phone": "+49941123450",
  "postalCode": "93055",
  "registerCourt": "Amtsgericht Regensburg",
  "street": "Industriestraße 12",
  "updatedAt": "2026-06-01T10:00:00Z",
  "vatId": "DE999000111",
  "version": 4,
  "website": "https://www.muster-it.example"
}
```

### 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`)
- **409** Stale version or conflict with existing data (`application/json`)

Fields of the 200 answer:

- `companyName` (string, required): Company name of the tenant (max length 255)
- `version` (integer, required): 0 creates the profile; otherwise the version you read
- `city` (string): City (max length 128)
- `commercialRegister` (string): Commercial register number (max length 128)
- `companyNameAddition` (string): Company name addition (max length 255)
- `countryCode` (string): Country (ISO 3166-1 alpha-2); decides whether addresses are foreign (default `"DE"`)
- `defaultBankName` (string): Name of the default bank (max length 128)
- `defaultBic` (string): BIC of the default bank account
- `defaultIban` (string): IBAN of the default bank account
- `email` (string (email)): E-mail address (max length 255)
- `geocodePrecision` (string, read-only): See `PostalAddress.geocodePrecision` (one of `HOUSE`, `STREET`, `LOCALITY`, `POSTCODE`)
- `geocodeStatus` (string, read-only): See `PostalAddress.geocodeStatus` (one of `PENDING`, `DONE`, `FAILED`, `SKIPPED`)
- `glAccountLength` (integer, nullable): Length g of the G/L accounts; unset: account numbers of addresses are not checked. Changing it never fails because of existing addresses (max 8)
- `invoiceContactEmail` (string (email)): E-mail of the invoice contact (BT-43); empty: `invoiceEmail`, else `email` (max length 255)
- `invoiceContactName` (string): Contact person outgoing invoices name (XRechnung BT-41, required there) (max length 128)
- `invoiceContactPhone` (string): Phone of the invoice contact (BT-42); empty: `phone` (max length 64)
- `invoiceEmail` (string (email)): Electronic address of the seller on outgoing e-invoices (BT-34, scheme EM); empty: `email` (max length 255)
- `latitude` (number, nullable, read-only): WGS 84, geocoded from the address like a postal address (origin of distances); ignored on writes
- `longitude` (number, nullable, read-only): WGS 84
- `managingDirectors` (string): Managing directors (max length 255)
- `phone` (string): Phone (max length 64)
- `postalCode` (string): Postal code (max length 32)
- `registerCourt` (string): Register court (max length 128)
- `sepaCreditorId` (string): SEPA creditor identifier (max length 35)
- `street` (string): Street with house number (max length 255)
- `taxNumber` (string): Tax number (max length 64)
- `updatedAt` (string (date-time), read-only): Time of the last change
- `vatId` (string): VAT ID of the tenant (used for official VAT checks)
- `website` (string): Website (max length 255)

Example 200 answer:

```json
{
  "city": "Regensburg",
  "commercialRegister": "HRB 99999",
  "companyName": "Muster IT-Systemhaus GmbH",
  "countryCode": "DE",
  "defaultBankName": "Stadtsparkasse München",
  "defaultBic": "SSKMDEMMXXX",
  "defaultIban": "DE66701500000001234567",
  "email": "info@muster-it.example",
  "geocodePrecision": "HOUSE",
  "geocodeStatus": "DONE",
  "glAccountLength": 4,
  "invoiceContactEmail": "christina.adler@muster-it.example",
  "invoiceContactName": "Christina Adler",
  "invoiceContactPhone": "+4994112345015",
  "invoiceEmail": "rechnungen@muster-it.example",
  "latitude": 49.0134,
  "longitude": 12.1325,
  "managingDirectors": "Thomas Pfeiffer",
  "phone": "+49941123450",
  "postalCode": "93055",
  "registerCourt": "Amtsgericht Regensburg",
  "street": "Industriestraße 12",
  "updatedAt": "2026-06-01T10:00:00Z",
  "vatId": "DE999000111",
  "version": 4,
  "website": "https://www.muster-it.example"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/masterdata/tenant-profile' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"city":"Regensburg","commercialRegister":"HRB 99999","companyName":"Muster IT-Systemhaus GmbH","countryCode":"DE","defaultBankName":"Stadtsparkasse München","defaultBic":"SSKMDEMMXXX","defaultIban":"DE66701500000001234567","email":"info@muster-it.example","geocodePrecision":"HOUSE","geocodeStatus":"DONE","glAccountLength":4,"invoiceContactEmail":"christina.adler@muster-it.example","invoiceContactName":"Christina Adler","invoiceContactPhone":"+4994112345015","invoiceEmail":"rechnungen@muster-it.example","latitude":49.0134,"longitude":12.1325,"managingDirectors":"Thomas Pfeiffer","phone":"+49941123450","postalCode":"93055","registerCourt":"Amtsgericht Regensburg","street":"Industriestraße 12","updatedAt":"2026-06-01T10:00:00Z","vatId":"DE999000111","version":4,"website":"https://www.muster-it.example"}'
```

## Get the tenant's accounting settings (tenant:masterdata:read)

`GET /api/masterdata/tenant-settings`

Module: Master data · operationId: `getTenantSettings` · Tag: Settings · Auth: access token (`Authorization: Bearer <accessToken>`)

`version` 0 and an empty `chartOfAccounts` while no chart was chosen.

### Responses

- **200** The settings (`application/json`)
- **401** Missing, invalid or expired token (empty body)
- **403** The token lacks the permission or carries no tenant (`application/json`)

Fields of the 200 answer:

- `chartOfAccounts` (string, required): DATEV chart of accounts (empty in a response while none was chosen) (one of `SKR03`, `SKR04`)
- `version` (integer, required): Optimistic locking version (0 while not stored)

Example 200 answer:

```json
{
  "chartOfAccounts": "SKR04",
  "version": 2
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/masterdata/tenant-settings' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Set the tenant's chart of accounts (tenant:settings:write)

`PUT /api/masterdata/tenant-settings`

Module: Master data · operationId: `saveTenantSettings` · Tag: Settings · Auth: access token (`Authorization: Bearer <accessToken>`)

`version` must match the stored one (0 while none is stored). The default revenue accounts of the
standard tax keys follow the chart where they are empty or still the previous chart's account;
changed accounts stay (each changed tax key emits `masterdata.lookup.updated`). A chart that is
already set cannot change once product groups have revenue accounts (`409`).

### Request body

`application/json` (required)

- `chartOfAccounts` (string, required): DATEV chart of accounts (empty in a response while none was chosen) (one of `SKR03`, `SKR04`)
- `version` (integer, required): Optimistic locking version (0 while not stored)

Example:

```json
{
  "chartOfAccounts": "SKR04",
  "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`)
- **409** Stale version or conflict with existing data (`application/json`)

Fields of the 200 answer:

- `chartOfAccounts` (string, required): DATEV chart of accounts (empty in a response while none was chosen) (one of `SKR03`, `SKR04`)
- `version` (integer, required): Optimistic locking version (0 while not stored)

Example 200 answer:

```json
{
  "chartOfAccounts": "SKR04",
  "version": 2
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/masterdata/tenant-settings' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"chartOfAccounts":"SKR04","version":2}'
```

## Get the tenant's price calculation scale (tenant:masterdata:read)

`GET /api/masterdata/price-tiers`

Module: Master data · operationId: `getPriceTiers` · Tag: Settings · Auth: access token (`Authorization: Bearer <accessToken>`)

Markup and rounding per purchase price range, ordered by `fromCost`. Product groups without own
`priceTiers` use their parent's scale, then this one. While none is stored the answer is the
default scale: one row from 0 with 0 % and `NONE`.

### Responses

- **200** The scale (`application/json`)
- **401** Missing, invalid or expired token (empty body)
- **403** The token lacks the permission or carries no tenant (`application/json`)

Fields of the 200 answer:

- `priceTiers` (array of PriceTier, required): Rows ordered by `fromCost`
  - `fromCost` (number, required): Purchase price from which the row applies (inclusive, net, base currency); the first row is 0
  - `markupRate` (number, required): Markup in percent of the purchase price (max 1000)
  - `rounding` (string, required): `NONE` rounds half up to cents; `UP_x` rounds up to the next multiple of x (0.05, 0.10, 0.50, 1, 5, 10); `END_90`/`END_99` take the smallest price ending in .90/.99 that is not below the value. (one of `NONE`, `UP_0_05`, `UP_0_10`, `UP_0_50`, `UP_1`, `UP_5`, `UP_10`, `END_90`, `END_99`)

Example 200 answer:

```json
{
  "priceTiers": [
    {
      "fromCost": 0,
      "markupRate": 35,
      "rounding": "END_99"
    },
    {
      "fromCost": 500,
      "markupRate": 25,
      "rounding": "END_99"
    },
    {
      "fromCost": 2000,
      "markupRate": 15,
      "rounding": "UP_10"
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/masterdata/price-tiers' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Replace the tenant's price calculation scale (tenant:settings:write)

`PUT /api/masterdata/price-tiers`

Module: Master data · operationId: `savePriceTiers` · Tag: Settings · Auth: access token (`Authorization: Bearer <accessToken>`)

Replaces the scale as a whole. At least one row; the first starts at `fromCost` 0, `fromCost`
rises strictly from row to row (4 decimals), `markupRate` is 0–1000, at most 50 rows. Invalid rows
answer `400` with field keys like `priceTiers[1].fromCost`.

### Request body

`application/json` (required)

- `priceTiers` (array of PriceTier, required): Rows ordered by `fromCost`
  - `fromCost` (number, required): Purchase price from which the row applies (inclusive, net, base currency); the first row is 0
  - `markupRate` (number, required): Markup in percent of the purchase price (max 1000)
  - `rounding` (string, required): `NONE` rounds half up to cents; `UP_x` rounds up to the next multiple of x (0.05, 0.10, 0.50, 1, 5, 10); `END_90`/`END_99` take the smallest price ending in .90/.99 that is not below the value. (one of `NONE`, `UP_0_05`, `UP_0_10`, `UP_0_50`, `UP_1`, `UP_5`, `UP_10`, `END_90`, `END_99`)

Example:

```json
{
  "priceTiers": [
    {
      "fromCost": 0,
      "markupRate": 35,
      "rounding": "END_99"
    },
    {
      "fromCost": 500,
      "markupRate": 25,
      "rounding": "END_99"
    },
    {
      "fromCost": 2000,
      "markupRate": 15,
      "rounding": "UP_10"
    }
  ]
}
```

### 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`)

Fields of the 200 answer:

- `priceTiers` (array of PriceTier, required): Rows ordered by `fromCost`
  - `fromCost` (number, required): Purchase price from which the row applies (inclusive, net, base currency); the first row is 0
  - `markupRate` (number, required): Markup in percent of the purchase price (max 1000)
  - `rounding` (string, required): `NONE` rounds half up to cents; `UP_x` rounds up to the next multiple of x (0.05, 0.10, 0.50, 1, 5, 10); `END_90`/`END_99` take the smallest price ending in .90/.99 that is not below the value. (one of `NONE`, `UP_0_05`, `UP_0_10`, `UP_0_50`, `UP_1`, `UP_5`, `UP_10`, `END_90`, `END_99`)

Example 200 answer:

```json
{
  "priceTiers": [
    {
      "fromCost": 0,
      "markupRate": 35,
      "rounding": "END_99"
    },
    {
      "fromCost": 500,
      "markupRate": 25,
      "rounding": "END_99"
    },
    {
      "fromCost": 2000,
      "markupRate": 15,
      "rounding": "UP_10"
    }
  ]
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/masterdata/price-tiers' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"priceTiers":[{"fromCost":0,"markupRate":35,"rounding":"END_99"},{"fromCost":500,"markupRate":25,"rounding":"END_99"},{"fromCost":2000,"markupRate":15,"rounding":"UP_10"}]}'
```

## List tenant-defined fields (tenant:masterdata:read)

`GET /api/masterdata/field-defs`

Module: Master data · operationId: `listFieldDefs` · Tag: Settings · Auth: access token (`Authorization: Bearer <accessToken>`)

Ordered by entity, sort order and key.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `entity` | query | string |  | Only fields of this entity (case-insensitive); all when omitted (one of `ADDRESS`, `CONTACT`, `POSTAL`) |
| `includeArchived` | query | boolean |  | (default `false`) |

### Responses

- **200** Field definitions (`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`)

Fields of the 200 answer:

- `items` (array of FieldDef, required)
  - `entity` (string, required): Immutable (one of `ADDRESS`, `CONTACT`, `POSTAL`)
  - `key` (string, required): Immutable; values are stored under this key and filtered with `cf.<key>`
  - `kind` (string, required): Immutable (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `url`)
  - `label` (string, required): Label shown in forms (max length 128)
  - `archived` (boolean): Hidden; values are kept, writes refused
  - `createdAt` (string (date-time), read-only): Creation time
  - `description` (string): Help text (max length 1000)
  - `id` (string (uuid), read-only): Id of the field definition
  - `options` (array of FieldOption): Unique non-empty values (select and multiselect)
    - `value` (string, required): Stored value
    - `color` (string): Display colour
    - `label` (string): Defaults to `value`
  - `required` (boolean): A value is required on write
  - `sortOrder` (integer): Position in forms
  - `updatedAt` (string (date-time), read-only): Time of the last change
  - `version` (integer): Optimistic locking version (updates)

Example 200 answer:

```json
{
  "items": [
    {
      "archived": false,
      "createdAt": "2026-01-02T08:00:00Z",
      "entity": "ADDRESS",
      "id": "0a2c4e6a-8b0d-4f2a-9c4e-6a8b0d2f4a6c",
      "key": "branche",
      "kind": "select",
      "label": "Branche",
      "options": [
        {
          "label": "Hotel und Gastronomie",
          "value": "hotel"
        },
        {
          "label": "Kanzlei",
          "value": "kanzlei"
        },
        {
          "label": "Handwerk",
          "value": "handwerk"
        }
      ],
      "required": false,
      "sortOrder": 1,
      "updatedAt": "2026-01-02T08:00:00Z",
      "version": 1
    }
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/masterdata/field-defs' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create a tenant-defined field (tenant:settings:write)

`POST /api/masterdata/field-defs`

Module: Master data · operationId: `createFieldDef` · Tag: Settings · Auth: access token (`Authorization: Bearer <accessToken>`)

A key that exists for the entity answers `409`.

### Request body

`application/json` (required)

- `entity` (string, required): Immutable (one of `ADDRESS`, `CONTACT`, `POSTAL`)
- `key` (string, required): Immutable; values are stored under this key and filtered with `cf.<key>`
- `kind` (string, required): Immutable (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `url`)
- `label` (string, required): Label shown in forms (max length 128)
- `archived` (boolean): Hidden; values are kept, writes refused
- `createdAt` (string (date-time), read-only): Creation time
- `description` (string): Help text (max length 1000)
- `id` (string (uuid), read-only): Id of the field definition
- `options` (array of FieldOption): Unique non-empty values (select and multiselect)
  - `value` (string, required): Stored value
  - `color` (string): Display colour
  - `label` (string): Defaults to `value`
- `required` (boolean): A value is required on write
- `sortOrder` (integer): Position in forms
- `updatedAt` (string (date-time), read-only): Time of the last change
- `version` (integer): Optimistic locking version (updates)

Example:

```json
{
  "entity": "ADDRESS",
  "key": "branche",
  "kind": "select",
  "label": "Branche",
  "options": [
    {
      "label": "IT",
      "value": "it"
    },
    {
      "label": "Handel",
      "value": "handel"
    }
  ],
  "required": false,
  "sortOrder": 10
}
```

### Responses

- **201** Created (`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`)
- **409** Stale version or conflict with existing data (`application/json`)

Fields of the 201 answer:

- `entity` (string, required): Immutable (one of `ADDRESS`, `CONTACT`, `POSTAL`)
- `key` (string, required): Immutable; values are stored under this key and filtered with `cf.<key>`
- `kind` (string, required): Immutable (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `url`)
- `label` (string, required): Label shown in forms (max length 128)
- `archived` (boolean): Hidden; values are kept, writes refused
- `createdAt` (string (date-time), read-only): Creation time
- `description` (string): Help text (max length 1000)
- `id` (string (uuid), read-only): Id of the field definition
- `options` (array of FieldOption): Unique non-empty values (select and multiselect)
  - `value` (string, required): Stored value
  - `color` (string): Display colour
  - `label` (string): Defaults to `value`
- `required` (boolean): A value is required on write
- `sortOrder` (integer): Position in forms
- `updatedAt` (string (date-time), read-only): Time of the last change
- `version` (integer): Optimistic locking version (updates)

Example 201 answer:

```json
{
  "archived": false,
  "createdAt": "2026-01-02T08:00:00Z",
  "entity": "ADDRESS",
  "id": "0a2c4e6a-8b0d-4f2a-9c4e-6a8b0d2f4a6c",
  "key": "branche",
  "kind": "select",
  "label": "Branche",
  "options": [
    {
      "label": "Hotel und Gastronomie",
      "value": "hotel"
    },
    {
      "label": "Kanzlei",
      "value": "kanzlei"
    },
    {
      "label": "Handwerk",
      "value": "handwerk"
    }
  ],
  "required": false,
  "sortOrder": 1,
  "updatedAt": "2026-01-02T08:00:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/masterdata/field-defs' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"entity":"ADDRESS","key":"branche","kind":"select","label":"Branche","options":[{"label":"IT","value":"it"},{"label":"Handel","value":"handel"}],"required":false,"sortOrder":10}'
```

## Update a tenant-defined field (tenant:settings:write)

`PUT /api/masterdata/field-defs/{id}`

Module: Master data · operationId: `updateFieldDef` · Tag: Settings · Auth: access token (`Authorization: Bearer <accessToken>`)

`key`, `kind` and `entity` cannot change (`400`); `version` must match.

### Parameters

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

### Request body

`application/json` (required)

- `entity` (string, required): Immutable (one of `ADDRESS`, `CONTACT`, `POSTAL`)
- `key` (string, required): Immutable; values are stored under this key and filtered with `cf.<key>`
- `kind` (string, required): Immutable (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `url`)
- `label` (string, required): Label shown in forms (max length 128)
- `archived` (boolean): Hidden; values are kept, writes refused
- `createdAt` (string (date-time), read-only): Creation time
- `description` (string): Help text (max length 1000)
- `id` (string (uuid), read-only): Id of the field definition
- `options` (array of FieldOption): Unique non-empty values (select and multiselect)
  - `value` (string, required): Stored value
  - `color` (string): Display colour
  - `label` (string): Defaults to `value`
- `required` (boolean): A value is required on write
- `sortOrder` (integer): Position in forms
- `updatedAt` (string (date-time), read-only): Time of the last change
- `version` (integer): Optimistic locking version (updates)

Example:

```json
{
  "archived": false,
  "createdAt": "2026-01-02T08:00:00Z",
  "entity": "ADDRESS",
  "id": "0a2c4e6a-8b0d-4f2a-9c4e-6a8b0d2f4a6c",
  "key": "branche",
  "kind": "select",
  "label": "Branche",
  "options": [
    {
      "label": "Hotel und Gastronomie",
      "value": "hotel"
    },
    {
      "label": "Kanzlei",
      "value": "kanzlei"
    },
    {
      "label": "Handwerk",
      "value": "handwerk"
    }
  ],
  "required": false,
  "sortOrder": 1,
  "updatedAt": "2026-01-02T08:00:00Z",
  "version": 1
}
```

### 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:

- `entity` (string, required): Immutable (one of `ADDRESS`, `CONTACT`, `POSTAL`)
- `key` (string, required): Immutable; values are stored under this key and filtered with `cf.<key>`
- `kind` (string, required): Immutable (one of `text`, `longtext`, `number`, `date`, `datetime`, `bool`, `select`, `multiselect`, `url`)
- `label` (string, required): Label shown in forms (max length 128)
- `archived` (boolean): Hidden; values are kept, writes refused
- `createdAt` (string (date-time), read-only): Creation time
- `description` (string): Help text (max length 1000)
- `id` (string (uuid), read-only): Id of the field definition
- `options` (array of FieldOption): Unique non-empty values (select and multiselect)
  - `value` (string, required): Stored value
  - `color` (string): Display colour
  - `label` (string): Defaults to `value`
- `required` (boolean): A value is required on write
- `sortOrder` (integer): Position in forms
- `updatedAt` (string (date-time), read-only): Time of the last change
- `version` (integer): Optimistic locking version (updates)

Example 200 answer:

```json
{
  "archived": false,
  "createdAt": "2026-01-02T08:00:00Z",
  "entity": "ADDRESS",
  "id": "0a2c4e6a-8b0d-4f2a-9c4e-6a8b0d2f4a6c",
  "key": "branche",
  "kind": "select",
  "label": "Branche",
  "options": [
    {
      "label": "Hotel und Gastronomie",
      "value": "hotel"
    },
    {
      "label": "Kanzlei",
      "value": "kanzlei"
    },
    {
      "label": "Handwerk",
      "value": "handwerk"
    }
  ],
  "required": false,
  "sortOrder": 1,
  "updatedAt": "2026-01-02T08:00:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/masterdata/field-defs/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"archived":false,"createdAt":"2026-01-02T08:00:00Z","entity":"ADDRESS","id":"0a2c4e6a-8b0d-4f2a-9c4e-6a8b0d2f4a6c","key":"branche","kind":"select","label":"Branche","options":[{"label":"Hotel und Gastronomie","value":"hotel"},{"label":"Kanzlei","value":"kanzlei"},{"label":"Handwerk","value":"handwerk"}],"required":false,"sortOrder":1,"updatedAt":"2026-01-02T08:00:00Z","version":1}'
```

## Archive a tenant-defined field (tenant:settings:write)

`DELETE /api/masterdata/field-defs/{id}`

Module: Master data · operationId: `archiveFieldDef` · Tag: Settings · Auth: access token (`Authorization: Bearer <accessToken>`)

Hides the field; stored values are kept. Archived fields are rejected on write.

### Parameters

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

### Responses

- **204** Archived
- **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`)

### Example request

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

