Referenz: Qualifikationen (/v1/qualifications)

Qualifikationen, Unterweisungen und Fachkundenachweise. Alle Felder, Filter, Rechte und Fehler dieser Ressource.

Für wen

Entwicklerinnen und Entwickler, die elyph anbinden.

Voraussetzungen

Schlüssel mit dem Recht qualifications:read bzw. qualifications:write Grundlagen aus „Erste Anfrage an die elyph API“

Schritt für Schritt

1
Liste abrufen
GET https://api.elyph.io/v1/qualifications liefert die Objekte des Mandanten, sortiert nach letzter Änderung. Erforderliches Recht: qualifications:read.
curl
curl -sS "https://api.elyph.io/v1/qualifications?limit=50&status=approved" \ -H "Authorization: Bearer $ELYPH_API_KEY"

Antwort lesen

Die Antwort enthält `data` mit den Objekten, `page.next` als Fortsetzungsmarke und `rate` mit dem verbleibenden Abfragekontingent.

Antwort

{
  "data": [
    {
      "id": "b21f0f6a-8f52-4f7c-9f0e-3b9b0f21a4c8",
      "title": "Unterweisung Gabelstapler",
      "kind": "unterweisung",
      "group_code": "FLURFOERDER",
      "person": {
        "name": "Jens Roth",
        "email": "jens.roth@example.com"
      },
      "issuer": "Werksicherheit",
      "certificate_number": "UW-2025-0442",
      "legal_basis": "DGUV Vorschrift 68",
      "issued_at": "2025-09-01",
      "valid_until": "2026-08-31",
      "update_due_at": "2026-08-01",
      "status": "valid",
      "updated_at": "2025-09-01T12:00:00Z"
    }
  ],
  "page": {
    "next": null,
    "limit": 50
  },
  "rate": {
    "limit": 120,
    "remaining": 118,
    "reset_at": "2026-02-01T10:31:00Z"
  }
}

3
Filter setzen
Verfügbare Filter: `status` — Statuswert exakt wie im Feld `status`. `expires_before` — Nur Nachweise, deren Gültigkeit bis zu diesem Datum endet. `updated_since` — Nur Objekte, die seit diesem Zeitpunkt geändert wurden (ISO 8601). Grundlage jeder Synchronisation. `limit` — Anzahl der Objekte je Seite, 1 bis 200. Standard 50. `page` — Fortsetzungsmarke aus `page.next` der vorherigen Antwort. Keine Seitenzahl. Mehrere Filter werden mit `&` verbunden und wirken zusammen.
4
Einzelnes Objekt holen
Der Pfad /v1/qualifications/{Kennung} liefert genau ein Objekt. Kennung ist `id` (UUID des Nachweises). Unbekannte Kennungen ergeben 404 `not_found`.
curl
curl -sS "https://api.elyph.io/v1/qualifications/{kennung}" \ -H "Authorization: Bearer $ELYPH_API_KEY"

Objekt anlegen

POST /v1/qualifications — erforderliches Recht: qualifications:write. Der Nachweis wird dem Mandanten des Schlüssels zugeordnet. Für Fortschreibungen bestehender Nachweise wird PATCH mit der `id` im Pfad benutzt.

curl

curl -sS "https://api.elyph.io/v1/qualifications" \
  -H "Authorization: Bearer $ELYPH_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
  "person_name": "Jens Roth",
  "title": "Unterweisung Gabelstapler",
  "kind": "unterweisung",
  "issued_at": "2026-09-01",
  "valid_until": "2027-08-31",
  "issuer": "Werksicherheit"
}'

Felder der Antwort

Feld	Typ	Bedeutung
id	string (UUID)	Kennung des Nachweises.
title	string	Bezeichnung, etwa „Unterweisung Gabelstapler“.
kind	string	Art: Unterweisung, Fachkunde, Befähigung, Vorsorge.
group_code	string \| null	Gruppierung für Serienauswertungen.
person.name	string \| null	Person, für die der Nachweis gilt.
person.email	string \| null	E-Mail, sofern ein Konto verknüpft ist.
issuer	string \| null	Ausstellende Stelle.
certificate_number	string \| null	Nummer der Bescheinigung.
legal_basis	string \| null	Rechtsgrundlage der Pflicht.
issued_at	string \| null	Ausstellungsdatum.
valid_until	string \| null	Ende der Gültigkeit.
update_due_at	string \| null	Termin der Auffrischung.
status	string	`valid`, `expiring`, `expired`.
updated_at	string (ISO 8601)	Letzte Änderung. Sortierfeld der Liste und Grundlage für `updated_since`.

Filter

Parameter	Beschreibung	Beispiel
status	Statuswert exakt wie im Feld `status`.	status=approved
expires_before	Nur Nachweise, deren Gültigkeit bis zu diesem Datum endet.	expires_before=2026-06-30
updated_since	Nur Objekte, die seit diesem Zeitpunkt geändert wurden (ISO 8601). Grundlage jeder Synchronisation.	updated_since=2026-01-01T00:00:00Z
limit	Anzahl der Objekte je Seite, 1 bis 200. Standard 50.	limit=100
page	Fortsetzungsmarke aus `page.next` der vorherigen Antwort. Keine Seitenzahl.	page=eyJ1IjoiMjAy…

Rechte und Methoden

Angabe	Wert
Pfad	/v1/qualifications
Methoden	GET, POST, PATCH
Rechte	qualifications:read, qualifications:write
Kennung	`id` (UUID des Nachweises)

API-Konsole

Anfrage zusammenstellen, Code kopieren und — angemeldet und mit eigenem Schlüssel — wirklich ausführen. Die Konsole führt ausschließlich lesende Aufrufe aus.

Ressource

Adresse

GET https://api.elyph.io/v1/qualifications?limit=10

status

Statuswert exakt wie im Feld `status`.

expires_before

Nur Nachweise, deren Gültigkeit bis zu diesem Datum endet.

updated_since

Nur Objekte, die seit diesem Zeitpunkt geändert wurden (ISO 8601). Grundlage jeder Synchronisation.

limit

Anzahl der Objekte je Seite, 1 bis 200. Standard 50.

page

Fortsetzungsmarke aus `page.next` der vorherigen Antwort. Keine Seitenzahl.

curl

curl -sS "https://api.elyph.io/v1/qualifications?limit=10" \
  -H "Authorization: Bearer $ELYPH_API_KEY"

Echttest

Nach der Anmeldung führen Sie dieselbe Anfrage hier mit Ihrem eigenen Schlüssel aus. So sieht eine echte Antwort aus:

Beispielantwort

{
  "data": [
    {
      "id": "b21f0f6a-8f52-4f7c-9f0e-3b9b0f21a4c8",
      "title": "Unterweisung Gabelstapler",
      "kind": "unterweisung",
      "group_code": "FLURFOERDER",
      "person": {
        "name": "Jens Roth",
        "email": "jens.roth@example.com"
      },
      "issuer": "Werksicherheit",
      "certificate_number": "UW-2025-0442",
      "legal_basis": "DGUV Vorschrift 68",
      "issued_at": "2025-09-01",
      "valid_until": "2026-08-31",
      "update_due_at": "2026-08-01",
      "status": "valid",
      "updated_at": "2025-09-01T12:00:00Z"
    }
  ],
  "page": {
    "next": null,
    "limit": 10
  },
  "rate": {
    "limit": 120,
    "remaining": 118,
    "reset_at": "2026-02-01T10:31:00Z"
  }
}

Ergebnis

Sie können qualifikationen zuverlässig lesen und schreiben, filtern und mit Ihrem System abgleichen.

Häufige Stolpersteine

Interne UUIDs statt der fachlichen Kennung speichern: Verwenden Sie `id` (UUID des Nachweises) als stabile Verknüpfung.
Alle Daten bei jedem Lauf neu laden: Mit `updated_since` holen Sie nur Änderungen.
Schreibrechte pauschal vergeben: Erteilen Sie qualifications:write nur dem System, das wirklich schreibt.

Hintergrund

Die Ressource ist streng auf den Mandanten des Schlüssels begrenzt. Ist der Zugang auf Standorte eingeschränkt, liefert die Liste nur Objekte dieser Standorte. Jede Anfrage wird mit Zeitpunkt, Pfad, Status und Trefferzahl protokolliert und ist in der Verwaltung einsehbar.