Oniva REST API
Erfahre, wie du mit der Oniva REST API programmatisch auf Eventdaten zugreifst – zum Beispiel für eigene Integrationen, Auswertungen oder automatisierte Workflows.
Was ist die REST API?
Die Oniva REST API ermöglicht es, von aussen auf Daten in Oniva zuzugreifen – ohne die Benutzeroberfläche. Sie eignet sich für Entwicklerinnen und Entwickler, die Oniva in bestehende Systeme einbinden oder eigene Anwendungen darauf aufbauen möchten.
Im Unterschied zu Webhooks, die Daten automatisch bei einem Ereignis senden, kannst du mit der REST API gezielt Daten abrufen – wann immer du sie brauchst.
👉 Benötigst du mehr Flexibilität? Für komplexere Integrationen steht zusätzlich die Oniva GraphQL API zur Verfügung. Sie ermöglicht frei definierbare Abfragen und eignet sich für Anwendungsfälle, die über den Funktionsumfang der REST API hinausgehen.
Was ist über die API möglich?
Über die REST API kannst du folgende Bereiche abfragen:
Events
- Einzelne Events abrufen (inkl. Optionen, Status, Datum, Ort)
- Alle Events eines Mandanten auflisten und filtern – z. B. nach Status, Zeitraum oder Workspace
Buchungen
- Buchungen eines Events abrufen
- Einzelne Buchung mit Kontaktdaten, Zahlungsinformationen und gebuchten Optionen abrufen
- Buchungen filtern – z. B. nach Status, E-Mail-Adresse oder Zeitraum
Benutzerinformationen
- Informationen zum authentifizierten API-Client abrufen
Wofür kann man die API nutzen?
Die API ermöglicht die gezielte Verbindung von Oniva mit anderen Systemen. Typische Anwendungsfälle sind:
Eigene Auswertungen und Reports: Buchungsdaten können periodisch abgerufen und in ein eigenes Analyse- oder Reporting-Tool übertragen werden – ohne manuelle Exporte.
Beispiel: Oniva → REST API → Python-Skript → Excel / Power BI
Individuelle Integrationen: Wenn ein Drittsystem Buchungs- oder Eventdaten benötigt, kann es diese direkt über die API abrufen. Das erlaubt massgeschneiderte Verbindungen, die über Standard-Webhooks hinausgehen.
Datensynchronisation: Daten aus Oniva können regelmässig abgerufen und mit anderen Systemen synchronisiert werden – z. B. CRM, Mitgliederdatenbanken oder interne Tools.
💡 Tipp: Für Echtzeit-Benachrichtigungen bei Buchungen oder Check-Ins eignen sich Webhooks besser. Die REST API ist ideal, wenn du Daten gezielt und auf Abruf benötigst.
API einrichten
Voraussetzungen
- Mandanten-Admin Rechte
- Die API-Funktion muss auf der Lizenz aktiviert sein
Falls die Funktion noch nicht verfügbar ist, kann sie vom Oniva Support Team aktiviert werden.
API-Client anlegen
- Navigiere zu Mandanten-Einstellungen → API-Clients
- Erstelle einen neuen API-Client
- Nach dem Erstellen erhältst du:
- Client-ID – dein eindeutiger Identifikator
- Client-Secret – dein geheimes Passwort (wird nur einmalig angezeigt, sofort sichern!)
- Verwende Client-ID und Client-Secret, um dich gegenüber der API zu authentifizieren
⚠️ Wichtig: Das Client-Secret wird nach dem Erstellen nur einmal angezeigt. Stelle sicher, dass du es sofort an einem sicheren Ort speicherst.
Authentifizierung
Die API verwendet OAuth 2.0 Client Credentials. Das bedeutet: Du tauschst Client-ID und Client-Secret gegen ein zeitlich begrenztes Zugriffstoken (Bearer Token) ein. Dieses Token gibst du bei jeder API-Anfrage mit.
Token sind 1 Stunde lang gültig. Danach muss ein neues angefordert werden.
API-Dokumentation aufrufen
Die vollständige technische Dokumentation mit allen verfügbaren Endpunkten, Parametern und Beispiel-Anfragen findest du direkt in deinem Oniva-Account unter:
/admin/de/apidocs
Dort kannst du Endpunkte auch direkt im Browser ausprobieren.
Rahmenbedingungen
Rate Limiting: Die API erlaubt maximal 300 Anfragen pro Minute (pro OAuth-Client). Authentifizierungsendpunkte sind auf 20 Anfragen pro Minute und IP-Adresse limitiert. Bei Überschreitung erhältst du eine entsprechende Fehlermeldung mit der Angabe, wie lange du warten musst.
Paginierung: Listenabfragen (z. B. alle Buchungen eines Events) werden seitenweise zurückgegeben. Standardmässig werden 10 Einträge pro Anfrage zurückgegeben, maximal 100.
API-Version: Die API befindet sich aktuell im Beta-Stadium. Änderungen sind möglich. Wir empfehlen, Integrationen regelmässig auf Kompatibilität zu prüfen.
🔐 Hinweis zum Datenschutz
Bei der Nutzung der REST API werden Event- und Teilnehmerdaten an externe Systeme übertragen. Stelle daher sicher, dass das empfangende System die geltenden Datenschutzanforderungen erfüllt und die Daten sicher verarbeitet werden.
Prüfe insbesondere, ob das Zielsystem den Schweizer bzw. europäischen Datenschutzanforderungen entspricht. Als Betreiber:in des Zielsystems bist du dafür verantwortlich, dass die Weiterverarbeitung der Daten datenschutzkonform erfolgt. Bei Unsicherheiten empfiehlt es sich, die Integration mit deiner Datenschutzverantwortlichen Person oder der IT-Abteilung abzustimmen.
