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 addressesadrNr(string, required): Address numberdisplayName(string, required): Company name, else first and last nameid(string (uuid), required): Id of the addressisBlocked(boolean, required): General blockpartyType(string, required): Company or person (one ofCOMPANY,PERSON)roles(array of string, required): Roles derived from the statussearchTerm(string, required): Search termtags(array of string, required): TagsupdatedAt(string (date-time), required): Time of the last changeversion(integer, required): Optimistic locking versionblockReason(string): Reason of the general block (left out unlessisBlocked)city(string): City, seestreetcompanyName(string): Company namecountryCode(string): Country (ISO 3166-1 alpha-2), seestreetcustomFields(CustomFields): Tenant-defined values (left out when none are set)customerNumber(string): Customer numberdataQualityScore(integer): Completeness score 0–100email(string): Main e-mail addressfirstName(string): First namelastName(string): Last namephone(string): Phone (E.164)postalCode(string): Postal code, seestreetstatusCode(string): Code ofaddress-statusesstreet(string): Street of the default billing postal address (else the lowestansNr)supplierNumber(string): Supplier numbervatCheckStatus(VatCheckStatus): Result of the latest VAT check (absent when never checked) (one ofOFFICIALLY_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 addressesnextCursor(string): Cursor of the next page (pass it ascursor); missing on the last page
Example 200 answer:
{
"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
curl -X GET 'https://api.mbcom.cloud/api/masterdata/addresses' \
-H "Authorization: Bearer $ACCESS_TOKEN"