List Customers

Returns a paginated list of all customers of the company.

Breaking Change

Without the new status parameter, this list now also returns deleted customers (archived customers were already included before). Get only active customers with status=active.

Without a timestamp filter, the list now sorts by internal ID ascending instead of by last name and first name.

Request

GET /api/oauth/v2/resource/customers

Header

Header	Value
Authorization	Bearer {access_token}

Query parameters

Parameter	Type	Required	Description
offset	integer	No	Start position (default: 0)
limit	integer	No	Number of results (default: 50, max: 200)
term	string	No	Search term for name (min. 3 characters)
customerNumber	string	No	Customer number (exact match)
socialNumber	string	No	Social security number (exact match)
email	string	No	Email address (exact match)
phone	string	No	Phone number. Matches the national number (123412345678), E.164 with plus (+43123412345678), and 00-prefix (0043123412345678).
groupId	string (UUID)	No	Filters customers to members of a specific customer group. The value matches the id returned by GET /customers/groups.
status	string	No	Comma-separated list (default: all). Allowed values: active, archived, deleted. active returns customers that are neither archived nor deleted. Invalid value → 400 validation_error. See Conventions for details.
createdSince	string (ISO 8601)	No	Only customers created at or after this timestamp (createdAt >=)
createdUntil	string (ISO 8601)	No	Only customers created at or before this timestamp (createdAt <=)
updatedSince	string (ISO 8601)	No	Only customers modified at or after this timestamp (updatedAt >=). Newly created customers are included, because the modification timestamp is set on creation.
updatedUntil	string (ISO 8601)	No	Only customers modified at or before this timestamp (updatedAt <=)
deletedSince	string (ISO 8601)	No	Only deleted customers with a deletion timestamp at or after this value (deletedAt >=). This filter does not return active customers.
view	string	No	default (the default) or slim. slim returns only the most important fields per customer — see Conventions for details. Invalid value → 400 validation_error.

Note: All search filters can be combined (AND logic). For example, you can filter by socialNumber and term at the same time. There is one exception: deletedSince excludes the other timestamp filters — see below.

Note: customerNumber is currently not guaranteed to be unique. The filter can theoretically return more than one customer.

Note: groupId filters the customer list to members of the given customer group, e.g. GET /api/oauth/v2/resource/customers?groupId=b2c3d4e5-f6a7-8901-bcde-f12345678901. The response structure stays the same, and meta.total reflects the filtered count. If the customer group is unknown or the UUID format is invalid, the API responds with 404 not_found in both cases instead of an empty list. An empty value (?groupId=) acts like no filter — the API returns the unfiltered list.

Known limitation: data[].groups currently always returns an empty array on this list route, even when customer groups are assigned to the customer. The detail route GET /customers/{uuid} returns the assigned customer groups correctly.

Note: For a sync, updatedSince alone is enough — it covers new and modified customers. Fetch deleted customers with a second request using deletedSince.

Note: deletedSince cannot be combined with createdSince, createdUntil, updatedSince, or updatedUntil. The API responds with 400 validation_error, because deletedSince switches the result set to deleted customers. So query changes and deletions in two separate requests.

Note: Formats, time zone behavior, sorting, cursor strategy, and the meta.total trap work the same across all timestamp filters. See Incremental Sync.

Note on customers without a modification timestamp: For some customers, updatedAt is empty. This affects legacy data from before automatic timestamping, as well as bulk imports. updatedSince does not return those customers, not even with a very early date.

So for the initial sync, fetch the full set once without a timestamp filter. After that, continue incrementally with updatedSince.

Response

Success (200 OK)

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": null,
      "firstName": "Anna",
      "lastName": "Muster",
      "email": "anna.muster@example.com",
      "phone": "00436641234567",
      "tel": "6641234567",
      "telCode": "0043",
      "phoneSecondary": null,
      "telSecondary": null,
      "telCodeSecondary": null,
      "birthday": "1985-04-12",
      "socialNumber": "1234 120485",
      "customerNumber": "K-00123",
      "tenancies": [
        {
          "id": "f0e1d2c3-b4a5-6789-fedc-ba9876543210",
          "name": "Ordination Muster",
          "abbreviation": "OM",
          "color": "#00adba"
        }
      ],
      "groups": [],
      "archived": false,
      "deleted": false,
      "createdAt": "2026-05-02T08:15:00+02:00",
      "updatedAt": "2026-06-14T11:42:00+02:00",
      "deletedAt": null
    }
  ],
  "meta": {
    "total": 1200,
    "offset": 0,
    "limit": 50
  }
}

Response fields

Field	Type	Description
data	Array	List of customers
data[].id	string (UUID)	Unique customer ID
data[].title	string | null	Title (e.g. Dr., Mag.)
data[].firstName	string | null	First name
data[].lastName	string | null	Last name
data[].email	string | null	Email address
data[].phone	string | null	Full primary number: country code + national number, concatenated in 00-format (e.g. 00436641234567)
data[].tel	string | null	National primary number without country code (e.g. 6641234567)
data[].telCode	string | null	Country dialing code of the primary number in 00-format (e.g. 0043)
data[].phoneSecondary	string | null	Full secondary number: country code + number, concatenated in 00-format
data[].telSecondary	string | null	National secondary number without country code
data[].telCodeSecondary	string | null	Country dialing code of the secondary number in 00-format
data[].birthday	string | null	Date of birth (YYYY-MM-DD)
data[].socialNumber	string | null	Social security number
data[].customerNumber	string | null	Customer number
data[].tenancies	Array	Assigned tenants
data[].tenancies[].id	string (UUID)	Tenant ID
data[].tenancies[].name	string	Name of the tenant
data[].tenancies[].abbreviation	string	Abbreviation
data[].tenancies[].color	string	Color as hex code
data[].groups	Array	Assigned customer groups, see customer groups reference
data[].groups[].id	string (UUID)	Unique customer group ID
data[].groups[].name	string	Name of the customer group
data[].archived	boolean	true if the customer is archived
data[].deleted	boolean	true if the customer is deleted
data[].createdAt	string (ISO 8601) | null	Creation timestamp
data[].updatedAt	string (ISO 8601) | null	Last modification timestamp
data[].deletedAt	string (ISO 8601) | null	Deletion timestamp, null if not deleted
meta.total	integer	Total number of customers
meta.offset	integer	Current start position
meta.limit	integer	Number of returned entries

Beispiele

bash

curl -X GET "https://my.offisy.at/api/oauth/v2/resource/customers?offset=0&limit=50&term=Muster&customerNumber=beispiel&socialNumber=1234010190&email=anna.muster%40example.com&phone=%2B43+664+1234567&groupId=b2c3d4e5-f6a7-8901-bcde-f01234567890&status=all&createdSince=beispiel&createdUntil=beispiel&updatedSince=2026-04-15T10%3A00%3A00&updatedUntil=2026-04-15T10%3A00%3A00&deletedSince=beispiel&view=default" \
  -H "Authorization: Bearer {access_token}"

Server

Client-ID

Client-Secret

Parameter

offset integer

limit integer

term string

customerNumber string

socialNumber string

email string

phone string

groupId string

status string

createdSince string

createdUntil string

updatedSince string

updatedUntil string

deletedSince string

view string

Zuerst Token anfordern

Possible errors

Status	Code	Description
400	validation_error	A timestamp filter contains an invalid value
400	validation_error	deletedSince was combined with createdSince, createdUntil, updatedSince, or updatedUntil
400	validation_error	status contains an invalid value
400	validation_error	view is neither default nor slim
401	invalid_client	Invalid or missing access token
403	insufficient_scope	Scope customers not present
404	not_found	Customer group for groupId not found (also on invalid UUID format)