ConnectCloud Developers

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:

{
  "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"

View as Markdown · Interactive reference · OpenAPI