Kunden abrufen

Gibt eine paginierte Liste aller Kunden des Unternehmens zurück.

Breaking Change

Ohne den neuen Parameter status liefert diese Liste jetzt auch gelöschte Kunden (archivierte Kunden waren schon bisher enthalten). Nur aktive Kunden bekommst du mit status=active.

Ohne Zeitstempel-Filter sortiert die Liste jetzt nach interner ID aufsteigend statt nach Nachname und Vorname.

Request

GET /api/oauth/v2/resource/customers

Header	Wert
`Authorization`	`Bearer {access_token}`

Query-Parameter

Parameter	Typ	Pflicht	Beschreibung
`offset`	integer	Nein	Startposition (Standard: 0)
`limit`	integer	Nein	Anzahl Ergebnisse (Standard: 50, Max: 200)
`term`	string	Nein	Suchbegriff für Name (min. 3 Zeichen)
`customerNumber`	string	Nein	Kundennummer (exakte Übereinstimmung)
`socialNumber`	string	Nein	Sozialversicherungsnummer (exakte Übereinstimmung)
`email`	string	Nein	E-Mail-Adresse (exakte Übereinstimmung)
`phone`	string	Nein	Telefonnummer. Matcht die nationale Nummer (`123412345678`), E.164 mit Plus (`+43123412345678`) und 00-Präfix (`0043123412345678`).
`groupId`	string (UUID)	Nein	Filtert Kunden auf Mitglieder einer bestimmten Kundengruppe. Der Wert entspricht der `id`, die `GET /customers/groups` liefert.
`status`	string	Nein	Kommaseparierte Liste (Standard: `all`). Erlaubte Werte: `active`, `archived`, `deleted`. `active` liefert Kunden, die weder archiviert noch gelöscht sind. Ungültiger Wert → `400 validation_error`. Details siehe Konventionen.
`createdSince`	string (ISO 8601)	Nein	Nur Kunden, die ab diesem Zeitpunkt angelegt wurden (`createdAt >=`)
`createdUntil`	string (ISO 8601)	Nein	Nur Kunden, die bis zu diesem Zeitpunkt angelegt wurden (`createdAt <=`)
`updatedSince`	string (ISO 8601)	Nein	Nur Kunden, die ab diesem Zeitpunkt geändert wurden (`updatedAt >=`). Neu angelegte Kunden kommen mit, weil der Änderungszeitpunkt beim Anlegen gesetzt wird.
`updatedUntil`	string (ISO 8601)	Nein	Nur Kunden, die bis zu diesem Zeitpunkt geändert wurden (`updatedAt <=`)
`deletedSince`	string (ISO 8601)	Nein	Nur gelöschte Kunden mit Löschzeitpunkt ab diesem Wert (`deletedAt >=`). Aktive Kunden liefert dieser Filter nicht.
`view`	string	Nein	`default` (Standard) oder `slim`. `slim` liefert pro Kunde nur die wichtigsten Felder – Details siehe Konventionen. Ungültiger Wert → `400 validation_error`.

Hinweis: Alle Suchfilter können kombiniert werden (UND-Verknüpfung). So kann z.B. gleichzeitig nach socialNumber und term gefiltert werden. Eine Ausnahme gibt es: deletedSince schließt die übrigen Zeitstempel-Filter aus – siehe unten.
Hinweis: customerNumber ist aktuell nicht garantiert eindeutig. Der Filter kann theoretisch mehrere Kunden liefern.
Hinweis: groupId filtert die Kundenliste auf Mitglieder der angegebenen Kundengruppe, z.B. GET /api/oauth/v2/resource/customers?groupId=b2c3d4e5-f6a7-8901-bcde-f12345678901. Die Response-Struktur bleibt unverändert, meta.total spiegelt dabei die gefilterte Menge wider. Ist die Kundengruppe unbekannt oder das UUID-Format ungültig, antwortet die API in beiden Fällen mit 404 not_found statt mit einer leeren Liste. Ein leerer Wert (?groupId=) wirkt dagegen wie kein Filter – die API antwortet mit der ungefilterten Liste.
Bekannte Einschränkung: data[].groups liefert auf dieser Listenroute aktuell immer ein leeres Array, auch wenn dem Kunden Kundengruppen zugeordnet sind. Die Detailroute GET /customers/{uuid} liefert die zugeordneten Kundengruppen korrekt.

Hinweis: Für einen Abgleich genügt updatedSince – der Wert deckt neue und geänderte Kunden ab. Gelöschte Kunden holst du in einem zweiten Request mit deletedSince.

Hinweis: deletedSince lässt sich nicht mit createdSince, createdUntil, updatedSince oder updatedUntil kombinieren. Die API antwortet dann mit 400 validation_error, weil deletedSince die Ergebnismenge auf gelöschte Kunden umschaltet. Frage Änderungen und Löschungen deshalb in zwei getrennten Requests ab.

Hinweis: Formate, Zeitzonen-Verhalten, Sortierung im Filter-Modus, Cursor-Strategie und die meta.total-Falle gelten für alle Zeitstempel-Filter gleich – siehe Inkrementeller Abgleich.

Hinweis zu Kunden ohne Änderungszeitpunkt: Bei manchen Kunden ist updatedAt leer. Das betrifft Altbestand aus der Zeit vor der automatischen Zeitstempelung sowie Massenimporte. updatedSince liefert solche Kunden nicht – auch nicht mit einem sehr frühen Datum.
Hol dir für den Erstabgleich deshalb einmal den Vollbestand ohne Zeitstempel-Filter. Danach arbeitest du inkrementell mit updatedSince weiter.

Response

Erfolg (200 OK)

json

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

Feld	Typ	Beschreibung
`data`	Array	Liste der Kunden
`data[].id`	string (UUID)	Eindeutige Kunden-ID
`data[].title`	string \| null	Titel (z.B. Dr., Mag.)
`data[].firstName`	string \| null	Vorname
`data[].lastName`	string \| null	Nachname
`data[].email`	string \| null	E-Mail-Adresse
`data[].phone`	string \| null	Vollständige Primärnummer: Ländervorwahl + nationale Nummer, verkettet im 00-Format (z.B. `00436641234567`)
`data[].tel`	string \| null	Nationale Primärnummer ohne Vorwahl (z.B. `6641234567`)
`data[].telCode`	string \| null	Ländervorwahl der Primärnummer im 00-Format (z.B. `0043`)
`data[].phoneSecondary`	string \| null	Vollständige Zweitnummer: Vorwahl + Nummer, verkettet im 00-Format
`data[].telSecondary`	string \| null	Nationale Zweitnummer ohne Vorwahl
`data[].telCodeSecondary`	string \| null	Ländervorwahl der Zweitnummer im 00-Format
`data[].birthday`	string \| null	Geburtsdatum (YYYY-MM-DD)
`data[].socialNumber`	string \| null	Sozialversicherungsnummer
`data[].customerNumber`	string \| null	Kundennummer
`data[].tenancies`	Array	Zugeordnete Mandanten
`data[].tenancies[].id`	string (UUID)	Mandanten-ID
`data[].tenancies[].name`	string	Name des Mandanten
`data[].tenancies[].abbreviation`	string	Kürzel
`data[].tenancies[].color`	string	Farbe als Hex-Code
`data[].groups`	Array	Zugeordnete Kundengruppen, siehe Kundengruppen-Referenz
`data[].groups[].id`	string (UUID)	Eindeutige ID der Kundengruppe
`data[].groups[].name`	string	Name der Kundengruppe
`data[].archived`	boolean	`true` wenn der Kunde archiviert ist
`data[].deleted`	boolean	`true` wenn der Kunde gelöscht ist
`data[].createdAt`	string (ISO 8601) \| null	Erstellungszeitpunkt
`data[].updatedAt`	string (ISO 8601) \| null	Letzter Änderungszeitpunkt
`data[].deletedAt`	string (ISO 8601) \| null	Löschzeitpunkt, `null` wenn nicht gelöscht
`meta.total`	integer	Gesamtanzahl der Kunden
`meta.offset`	integer	Aktuelle Startposition
`meta.limit`	integer	Anzahl der zurückgegebenen Einträge

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

Mögliche Fehler

Status	Code	Beschreibung
400	`validation_error`	Ein Zeitstempel-Filter enthält einen ungültigen Wert
400	`validation_error`	`deletedSince` wurde mit `createdSince`, `createdUntil`, `updatedSince` oder `updatedUntil` kombiniert
400	`validation_error`	`status` enthält einen ungültigen Wert
400	`validation_error`	`view` ist weder `default` noch `slim`
401	`invalid_client`	Ungültiger oder fehlender Access Token
403	`insufficient_scope`	Scope `customers` nicht vorhanden
404	`not_found`	Kundengruppe zu `groupId` nicht gefunden (auch bei ungültigem UUID-Format)

Kunden abrufen ​

Request ​

Header ​

Query-Parameter ​

Response ​

Erfolg (200 OK) ​

Response-Felder ​

Mögliche Fehler ​