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