Kunden abrufen

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

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`).
`view`	string	Nein	Antwortform: `default` (Vorgabe) oder `slim`
`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.

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: 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"
        }
      ],
      "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[].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

Schlanker Abruf (`?view=slim`)

Der Query-Parameter view=slim liefert eine schlanke Payload mit nur den wichtigsten Feldern. Ohne den Parameter bleibt der Abruf unverändert – bestehende Integrationen müssen nichts anpassen.

Wird view mehrfach angegeben, gilt die letzte Angabe – ?view=default&view=slim liefert also die schlanke Antwort.

Die schlanke Payload enthält folgende Felder:

id, title, firstName, lastName, companyName, sex, birthday, email, phone, street, zip, city, country, customerNumber, archived, deleted, createdAt, updatedAt, deletedAt

Hinweis: Die Sozialversicherungsnummer (socialNumber) und die identificationNumber sind im schlanken Abruf nicht enthalten. Wer Kunden über die Sozialversicherungsnummer abgleicht, braucht den Standardabruf.
Hinweis: Der schlanke Abruf liefert derzeit zusätzlich createdAt, updatedAt und deletedAt.

Warnung: Gelöschte Kunden sind über diesen Endpoint derzeit nicht erkennbar – er gibt gelöschte Kunden nicht zurück. deleted ist deshalb aktuell immer false und deletedAt immer null. Ein gelöschter Kunde verschwindet dadurch stillschweigend aus der Liste, statt markiert zu werden. Für einen vollständigen Abgleich ist bis auf Weiteres ein periodischer Vollabruf nötig.

Beispiel: view=slim

json

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": null,
      "firstName": "Anna",
      "lastName": "Muster",
      "companyName": null,
      "sex": "female",
      "birthday": "1985-04-12",
      "email": "anna.muster@example.com",
      "phone": "00436641234567",
      "street": "Hauptstraße 1",
      "zip": "1010",
      "city": "Wien",
      "country": "AT",
      "customerNumber": "K-00123",
      "archived": false,
      "deleted": false,
      "createdAt": "2026-03-01T09:00:00+01:00",
      "updatedAt": "2026-03-01T09:00:00+01:00",
      "deletedAt": null
    }
  ],
  "meta": {
    "total": 1200,
    "offset": 0,
    "limit": 50
  }
}

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&view=default&createdSince=beispiel&createdUntil=beispiel&updatedSince=2026-04-15T10%3A00%3A00&updatedUntil=2026-04-15T10%3A00%3A00&deletedSince=beispiel" \
  -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

view string

createdSince string

createdUntil string

updatedSince string

updatedUntil string

deletedSince string

Zuerst Token anfordern

Mögliche Fehler

Status	Code	Beschreibung
400	`validation_error`	Ungültiger Wert für `view` (gültige Werte: `default`, `slim`)
400	`validation_error`	Ein Zeitstempel-Filter enthält einen ungültigen Wert
400	`validation_error`	`deletedSince` wurde mit `createdSince`, `createdUntil`, `updatedSince` oder `updatedUntil` kombiniert
401	`invalid_client`	Ungültiger oder fehlender Access Token
403	`insufficient_scope`	Scope `customers` nicht vorhanden

Kunden abrufen ​

Request ​

Header ​

Query-Parameter ​

Response ​

Erfolg (200 OK) ​

Response-Felder ​

Schlanker Abruf (?view=slim) ​

Mögliche Fehler ​