Online lernen für die Zeitarbeit Abonnements
Kurse
Für Unternehmen
Für Geschäftsführung und Niederlassungsleitung

Ihr ganzes Team schulen.

Team anmelden
Wissen
Lexikon, Blog und Branchen-Updates

Wissen für die Zeitarbeit.

Über uns
Preise

Für Firmenkunden

API-Dokumentation

Verbinden Sie den Team-Zugang Ihrer Firma mit Ihrem Personal- oder HR-System: Konten anlegen, Kurse zuweisen, Abschlüsse abrufen.

Überblick

Die Kurse der Zeitarbeit-Akademie laufen im Lernportal ONYX LMS. Firmenkunden mit Team-Zugang können dieses Portal über eine REST-API mit JSON ansprechen. Die API gehört zum Standardumfang eines Team-Zugangs.

Typische Aufgaben, die Ihr System damit selbst erledigt:

  • Konten für neue Mitarbeitende anlegen oder Personen per E-Mail einladen
  • Personen Gruppen zuordnen, etwa einer Niederlassung oder einem Team
  • Kurse und Wissenspfade zuweisen, zum Beispiel Personaldisposition für neue Disponentinnen und Disponenten
  • Fortschritt, Abschlüsse und Berichte abrufen
  • Abschlüsse aus einem Vorsystem übernehmen
  • Teilnahmebestätigungen als PDF abrufen
  • per Webhook erfahren, wenn jemand einen Kurs abgeschlossen hat

Wer die API nutzen kann

Ein Team-Zugang hat im Lernportal einen eigenen Verwaltungsbereich. Dort legen Administratorinnen und Administratoren Ihrer Firma unter „API & Webhooks“ die Tokens an. Sie entscheiden dabei, welche Rechte ein Token bekommt und ob es eine Laufzeit von 1 bis 365 Tagen hat. Ohne Laufzeit gilt es, bis Sie es löschen.

Wer als Privatperson bucht, bekommt ein persönliches Lernkonto ohne Verwaltungsbereich. Ein solches Konto kann keine Tokens anlegen, die API steht deshalb nur Firmenkunden offen. Team-Zugänge planen Sie im Kurskonfigurator.

Token und Rechte

Jede Anfrage trägt das Token im Header:

Authorization: Bearer <TOKEN>

Das Lernportal zeigt das Token nur einmal, direkt nach dem Anlegen. Speichern Sie es sofort in Ihrem Passwortspeicher oder Ihrer Konfiguration. Geht es verloren, legen Sie ein neues an und löschen das alte im Verwaltungsbereich.

Geben Sie jedem Token nur die Rechte, die das anbindende System braucht. Fehlt ein Recht, antwortet die API mit 403.

Rechte eines API-Tokens
RechtErlaubt
users.readKonten und offene Einladungen lesen
users.writeKonten anlegen und ändern, Personen einladen
courses.readFreigeschaltete Kurse und Einschreibungen lesen
courses.writeIn Kurse einschreiben, Abschlüsse übernehmen, Kurse einer Gruppe zuweisen
learning_paths.readWissenspfade lesen
learning_paths.writeWissenspfade anlegen, ändern und Personen einschreiben
groups.readGruppen und Mitglieder lesen
groups.writeGruppen anlegen, ändern und Mitglieder hinzufügen
reports.readBerichte zu Kursen, Lernenden und Aktivität lesen
stats.readKennzahlen Ihres Zugangs lesen
certificates.readTeilnahmebestätigungen lesen und als PDF abrufen
webhooks.readWebhooks lesen
webhooks.writeWebhooks anlegen

Basis-URL und Version

Alle Pfade auf dieser Seite hängen Sie an diese Adresse an:

https://portal.onyx-lms.de/api/v1

Die Version steht im Pfad (/v1). Senden Sie bei jeder Anfrage Accept: application/json mit, bei Anfragen mit Inhalt zusätzlich Content-Type: application/json.

Die API kennt keine DELETE-Aufrufe. Konten, Gruppen und Webhooks entfernen Sie im Verwaltungsbereich.

Endpunkte

Die Tabelle nennt für jeden Aufruf das Recht, das das Token braucht. Die Kursliste zeigt nur die Kurse, die für Ihren Zugang freigeschaltet sind.

Endpunkte der API mit Methode, Pfad, Zweck und Recht
MethodePfadZweckRecht
GET /users/users/{id} Konten auflisten (Filter role, search) oder einzeln abrufen users.read
POST /users Konto anlegen users.write
PATCH /users/{id} Lernendenkonto ändern, is_active: false deaktiviert es (Admin-Konten: 403) users.write
GET /invitations/invitations/{userId} Offene Einladungen auflisten oder einzeln abrufen users.read
POST /invitations Person einladen users.write
GET /courses/courses/{id} Für Sie freigeschaltete Kurse courses.read
GET /courses/{id}/enrollments Einschreibungen mit Status courses.read
POST /courses/{id}/enroll 1 bis 100 Personen einschreiben courses.write
POST /courses/{id}/users/{userId}/completion Abschluss aus einem Vorsystem übernehmen courses.write
PUT /courses/{id}/groups/{groupId} Kurs einer Gruppe zuweisen und alle Mitglieder einschreiben courses.write
GET /learning-paths/learning-paths/{id}/learning-paths/{id}/courses Wissenspfade und ihre Kurse in Reihenfolge learning_paths.read
POST /learning-paths Wissenspfad anlegen learning_paths.write
PATCH /learning-paths/{id} Wissenspfad ändern learning_paths.write
POST /learning-paths/{id}/enroll 1 bis 100 Personen einschreiben learning_paths.write
GET /groups/groups/{id} Gruppen auflisten oder einzeln abrufen groups.read
POST /groups Gruppe anlegen groups.write
PATCH /groups/{id} Gruppe ändern groups.write
GET /groups/{id}/users/users/{id}/groups Mitglieder einer Gruppe, Gruppen einer Person groups.read
PUT /groups/{id}/users/{userId} Mitglied hinzufügen groups.write
GET /reports/courses/reports/courses/{id}/reports/learners/reports/learners/{id}/reports/activity Berichte zu Kursen, Lernenden und Aktivität reports.read
GET /stats Kennzahlen im Überblick stats.read
GET /certificates/certificates/{id} Teilnahmebestätigungen auflisten (Filter user_id, course_id, certificate_number, since) oder einzeln abrufen certificates.read
GET /certificates/{id}/download Teilnahmebestätigung als PDF certificates.read
GET /webhooks/webhooks/{id} Webhooks auflisten oder einzeln abrufen webhooks.read
POST /webhooks Webhook anlegen webhooks.write

Ein übernommener Abschluss schreibt die Person bei Bedarf zuerst in den Kurs ein und löst wie ein Abschluss im Lernportal den Webhook course.completed aus.

Das PDF einer Teilnahmebestätigung rufen Sie mit dem Recht certificates.read über GET /certificates/{id}/download ab. Es ist dasselbe Dokument, das Lernende im Lernbereich und die Administration im Verwaltungsbereich herunterladen. Die ID steht in der Liste /certificates, in der Antwort der Abschluss-Übernahme und im Webhook course.completed. Sie sehen nur Bestätigungen, die in Ihrem Zugang ausgestellt wurden. Bestätigungen deaktivierter Konten bleiben abrufbar. Die Antworten nennen IDs und keine Namen, und jeder PDF-Abruf wird protokolliert.

Beispiele

Die IDs sind Beispielwerte. Die echten Kurs-IDs Ihres Zugangs liefert GET /courses.

Drei Personen in den Kurs Personaldisposition einschreiben

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"user_ids":[1,2,3]}' \
  "https://portal.onyx-lms.de/api/v1/courses/12/enroll"

Antwort:

{
  "data": {
    "enrolled_count": 3,
    "user_ids": [1, 2, 3],
    "rejected_count": 0,
    "rejected_user_ids": []
  }
}

enrolled_count zählt nur neue Einschreibungen. Wer schon eingeschrieben ist, bleibt unverändert. In rejected_user_ids stehen Personen, die das Lernportal nicht einschreiben konnte: einzelne, wenn für den Kurs keine Plätze mehr frei sind, oder der ganze Stapel, wenn der Kurs oder seine Freischaltung abgelaufen ist. Die Antwort hat trotzdem den Status 200.

Stand der Einschreibungen abrufen

curl -s -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
  "https://portal.onyx-lms.de/api/v1/courses/12/enrollments"
{
  "data": [
    {
      "user_id": 1,
      "email": "max.muster@example.com",
      "name": "Max Muster",
      "assigned_at": "2026-11-02 08:15:00",
      "completed_at": null,
      "current_section": 3,
      "status": "in_progress"
    }
  ]
}

status ist in_progress oder completed.

Webhook nach einem Kursabschluss

So kommt ein Abschluss bei Ihrem Webhook-Ziel an, hier für die Muster GmbH:

POST /lms-webhook HTTP/1.1
Host: hr.muster-gmbh.example
Content-Type: application/json
X-Webhook-Event: course.completed
X-Webhook-Timestamp: 2026-11-16T09:30:12.000000Z
X-Webhook-Signature: sha256=<hex>

{
  "event": "course.completed",
  "timestamp": "2026-11-16T09:30:12.000000Z",
  "tenant_id": 42,
  "data": {
    "event_id": "6f1c2a9e-8d4b-4f0a-9b1e-2c3d4e5f6a7b",
    "user_id": 1,
    "course_id": 12,
    "course_title": "Personaldisposition",
    "completion_cycle": 1,
    "certificate_number": "2026-42-0017",
    "certificate_id": 87
  }
}

certificate_number enthält die Nummer der Teilnahmebestätigung und certificate_id ihre ID für den PDF-Abruf über GET /certificates/{id}/download. Stellt der Kurs keine aus, sind beide null.

Webhooks

Mit Webhooks meldet das Lernportal Ereignisse an eine Adresse Ihres Systems, Sie müssen also nicht regelmäßig nachfragen. Webhooks legen Sie im Verwaltungsbereich oder per POST /webhooks an, mit Ziel-URL, den gewünschten Ereignissen und einer optionalen Beschreibung.

Ereignisse, die ein Webhook empfangen kann
EreignisWird gesendet, wenn
user.createdEin Konto wurde einzeln angelegt: im Verwaltungsbereich, per POST /users oder per POST /invitations. Nicht bei CSV-Import, HRIS-Abgleich oder SSO-Anmeldung.
user.updatedEin Konto wurde geändert oder deaktiviert.
user.deletedEin Konto wurde im Verwaltungsbereich gelöscht.
course.enrolledEine Person wurde über die API in einen Kurs eingeschrieben, auch per Gruppenzuweisung über die API. Einschreibungen im Verwaltungsbereich lösen es nicht aus.
course.completedEine Person hat einen Kurs abgeschlossen.
course.restartedEin Kurs wurde für eine Person neu gestartet.
learning_path.enrolledEine Person wurde über die API in einen Wissenspfad eingeschrieben. Einschreibungen im Verwaltungsbereich lösen es nicht aus.
learning_path.completedEine Person hat alle Pflichtkurse eines Wissenspfads abgeschlossen.

Signatur prüfen

Jeder Webhook hat ein Secret. Legen Sie den Webhook per POST /webhooks an, steht es einmalig in der Antwort. Im Verwaltungsbereich finden Sie es in der Bearbeitungsansicht des Webhooks. Jede Zustellung trägt den Header X-Webhook-Signature: sha256=<hex>, einen HMAC-SHA256 über den rohen Body mit diesem Secret. Rechnen Sie ihn über die empfangenen Bytes nach, nicht über neu kodiertes JSON, und vergleichen Sie zeitkonstant. Ein Beispiel in PHP:

$secret = getenv('LMS_WEBHOOK_SECRET');
$rawBody = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$expected = 'sha256='.hash_hmac('sha256', $rawBody, $secret);

if (! hash_equals($expected, $header)) {
    http_response_code(401);
    exit;
}

Dazu kommen die Header X-Webhook-Event mit dem Namen des Ereignisses und X-Webhook-Timestamp mit dem Sendezeitpunkt.

Zustellung und Wiederholungen

  • Das Ziel muss öffentlich per HTTPS erreichbar sein. Weiterleitungen folgt das Lernportal nicht.
  • Antworten Sie innerhalb von 10 Sekunden mit einem Status 2xx. Längere Verarbeitung erledigen Sie besser nach der Antwort.
  • Schlägt eine Zustellung fehl, unternimmt das Lernportal insgesamt bis zu 5 Versuche, mit Abständen von 30 Sekunden, 2 Minuten, 5 Minuten und 15 Minuten.
  • Nach 10 fehlgeschlagenen Versuchen in Folge schaltet das Lernportal den Webhook ab. Jeder erfolgreiche Versuch setzt den Zähler zurück.
  • Ein Ereignis kann mehr als einmal ankommen. course.completed und learning_path.completed tragen deshalb eine feste event_id, an der Sie doppelte Zustellungen erkennen.

Im Verwaltungsbereich sehen Sie jede Zustellung mit Statuscode und können einen Test-Aufruf an Ihr Ziel senden. Er kommt mit dem Ereignis test.ping an, rechnen Sie also auch mit diesem Namen.

Fehlercodes

Fehler kommen als JSON. Je nach Fall steht der Text im Feld error oder im Feld message. Werten Sie beide aus. error nutzen 401 und die fachlichen 403 und 422, zum Beispiel:

{ "error": "Insufficient permissions.", "required": "users.read" }

message kommt bei 404, 429 und einigen 403. Bei Eingabefehlern (422) nennt die Antwort außerdem unter errors die betroffenen Felder.

HTTP-Statuscodes der API
StatusBedeutung
401Token fehlt, ist ungültig oder abgelaufen.
403Dem Token fehlt das nötige Recht, der Zugang ist nicht aktiv, oder ein schreibender Aufruf kommt nach Vertragsende.
404Die Ressource gibt es nicht oder sie gehört nicht zu Ihrem Zugang.
422Die Eingabe ist ungültig oder verstößt gegen eine fachliche Regel.
429Zu viele Anfragen. Warten Sie die Sekunden aus dem Header Retry-After ab.

Endet Ihr Vertrag, bleibt die API eine Zeit lang lesbar. Lesende Aufrufe (GET) funktionieren weiter, schreibende beantwortet sie mit 403.

Anfragelimit und Seiten

Die API nimmt 600 Anfragen pro Minute je Client-IP an. Darüber hinaus antwortet sie mit 429. Der Header Retry-After sagt, nach wie vielen Sekunden Sie es wieder versuchen können.

Immer in Seiten liefern GET /users, /invitations, /reports/learners und /reports/activity. Die Listen /courses, /courses/{id}/enrollments, /learning-paths, /groups, /groups/{id}/users und /reports/courses liefern ohne Parameter alles auf einmal und blättern, sobald Sie page oder per_page mitschicken. Pro Seite kommen standardmäßig 25 Einträge, höchstens 100.

/reports/courses/{id}, /learning-paths/{id}/courses, /users/{id}/groups und /webhooks liefern immer die ganze Liste ohne meta.

GET https://portal.onyx-lms.de/api/v1/users?page=2&per_page=100

{
  "data": [ … ],
  "meta": { "current_page": 2, "last_page": 3, "per_page": 100, "total": 240 }
}

Datenschutz

Ein Token sieht nur die Daten Ihres eigenen Zugangs. Über die API löscht niemand Daten, dafür gibt es keinen Aufruf. Legen Sie Tokens mit möglichst wenigen Rechten an und löschen Sie Tokens, die Sie nicht mehr brauchen. Die Daten Ihrer Beschäftigten verarbeitet das Lernportal in Ihrem Auftrag. Welcher Vertrag zur Auftragsverarbeitung für Ihren Zugang gilt, sehen Firmen-Admins im Verwaltungsbereich unter „Verträge & Datenschutz“. Wie wir als Webseite personenbezogene Daten verarbeiten, steht in unserer Datenschutzerklärung.

Was die API nicht abdeckt

  • Löschen: Konten, Gruppen und Webhooks entfernen Sie im Verwaltungsbereich.
  • Lexikon und News der Akademie per API: auf Anfrage.

Pflichtunterweisungen und deren Nachweise gehören nicht zum Angebot der Zeitarbeit-Akademie. Sie laufen über ONYX LMS, das dafür eigene Funktionen in derselben API hat.

Fragen zur Anbindung

Sie wollen wissen, ob Ihr System passt, oder brauchen Lexikon und News per API? Schreiben Sie uns über die Kontaktseite.

Porträt von Miriam Hauf

Wir rufen Sie an.

Zwei kurze Fragen, dann melden wir uns bei Ihnen.

Schritt 1 von 2

Für wie viele Mitarbeitende?

Teamgröße
Wann passt ein Anruf? (optional)

Bezug: wird mitgeschickt