API v3.2

User Provisioning API - Dokumentation

API URL: https://api.parq-app.com

Version 3.2 - Aktualisiert: 30. November 2025

NEU in Version 3.2 (30.11.2025)

Vollständige API-Konsistenz

  • ✓ "Already Active" Prüfung: Alle /activate Endpunkte prüfen, ob die Entität bereits aktiv ist (HTTP 409 mit ALREADY_ACTIVE)
  • ✓ deleted_at wird gelöscht: Aktivierung setzt deleted_at auf null (konsistent für alle Entitäten)
  • ✓ Kompaktes Antwortformat: Alle /deactivate Endpunkte geben einheitlich zurück
  • ✓ Einheitliche Fehlercodes: ALREADY_ACTIVE für alle drei Entitätstypen

RESTful Path Parameter Support (v2.2)

Die API unterstützt beide Formate für maximale Flexibilität:

✅ Empfohlen: Path Parameter

DELETE /api/v1/organizations/550e8400-...
GET    /api/v1/users/learners/EMP-67890
PUT    /api/v1/users/team-leads/TL-12345

✅ Weiterhin unterstützt: Query Parameter

DELETE /api/v1/organizations?id=550e8400-...
GET    /api/v1/users/learners?id=EMP-67890
PUT    /api/v1/users/team-leads?id=TL-12345

Beide Formate funktionieren identisch. Path Parameter sind der REST-Standard für sauberere URLs.

External ID Unterstützung

Verwenden Sie Ihre eigenen internen IDs anstelle von UUIDs:

Was ist external_id? Ihre eigene interne ID aus Ihrem System

Vorteile: Direkte Referenzierung ohne UUID-Mapping

Beispiel: EMP-67890 statt 660e8400-e29b-41d4-...

UUID hat Vorrang: Wenn ein Wert wie UUID aussieht, wird er als UUID behandelt

Eindeutigkeit: external_id muss pro Firma eindeutig sein

Optional: external_id ist optional bei Erstellung

# Lernenden mit external_id abrufen
curl -X GET "https://api.parq-app.com/api/v1/users/learners/EMP-67890" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL"

Übersicht

Die User Provisioning API ermöglicht es Ihnen, Benutzer und Organisationen in der PARQ-Plattform zu verwalten:

  • Organisationen erstellen und verwalten
  • Teamleiter (Team Leads) erstellen und verwalten
  • Lernende (Learners) erstellen und verwalten
  • Lernende zu Organisationen zuweisen
  • Benutzer deaktivieren oder löschen

Benutzer-Hierarchie

Ihre Firma
    |-- Organisationen (z.B. "Rotes Kreuz", "UNICEF")
    |-- Teamleiter (verwalten Lernende)
    +-- Lernende (gehören zu einem Teamleiter und einer oder mehreren Organisationen)

Authentifizierung

Alle API-Anfragen erfordern einen API-Schlüssel im Authorization-Header:

Authorization: Bearer IHR_API_SCHLÜSSEL

Sicherheit

  • Bewahren Sie Ihren API-Schlüssel sicher auf
  • Teilen Sie den Schlüssel niemals öffentlich
  • Verwenden Sie HTTPS für alle Anfragen
  • Der Schlüssel ist nur für Ihre Firma gültig

Antwortformat

Erfolgreiche Antwort

{ 
  "success": true,
  "data": { 
    "id": "123e4567-e89b-12d3-...",
    "name": "Beispielorganisation"
  },
  "meta": { 
    "timestamp": "2025-11-01T12:34:56Z",
    "request_id": "req_abc123"
  } 
}

Fehlerantwort

{ 
  "success": false,
  "error": { 
    "code": "VALIDATION_ERROR",
    "message": "E-Mail existiert bereits"
  },
  "meta": { 
    "timestamp": "2025-11-01T12:34:56Z",
    "request_id": "req_abc123"
  } 
}

Rate Limits

100

Anfragen/Minute

200

Anfragen/10 Sekunden

10.000

Anfragen/Tag

Organisationen verwalten

POST Organisation erstellen

/api/v1/organizations 

curl -X POST "https://api.parq-app.com/api/v1/organizations" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Content-Type: application/json" \
  -d '{ 
    "name": "Deutsches Rotes Kreuz",
    "description": "Humanitäre Organisation",
    "website": "https://drk.de",
    "contact_email": "kontakt@drk.de",
    "external_id": "ORG-DRK-001"
  }'

GET Organisation abrufen

/api/v1/organizations/:id

Akzeptiert sowohl UUID als auch external_id

# Mit UUID
curl -X GET "https://api.parq-app.com/api/v1/organizations/org_abc123" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL"

# Mit external_id
curl -X GET "https://api.parq-app.com/api/v1/organizations/ORG-DRK-001" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL"

GET Organisationen auflisten

/api/v1/organizations 

# Nur aktive (Standard)
curl "https://api.parq-app.com/api/v1/organizations" -H "Authorization: Bearer ..."

# Alle (aktive + inaktive)
curl "https://api.parq-app.com/api/v1/organizations?status=all" -H "Authorization: Bearer ..."

# Inklusive soft-gelöschter
curl "https://api.parq-app.com/api/v1/organizations?include_deleted=true" -H "Authorization: Bearer ..."

PUT Organisation aktualisieren

/api/v1/organizations/:id

Hinweis: Der Name kann nicht geändert werden

curl -X PUT "https://api.parq-app.com/api/v1/organizations/org_abc123" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Neue Beschreibung", "website": "https://neue-website.de" }'

PATCH Organisation aktivieren

/api/v1/organizations/:id/activate 

curl -X PATCH "https://api.parq-app.com/api/v1/organizations/org_abc123/activate" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL"

PATCH Organisation deaktivieren (Soft Delete)

/api/v1/organizations/:id/deactivate

Hinweis: Alle Lernenden-Zuweisungen werden deaktiviert. Lernende ohne weitere Organisationen werden automatisch deaktiviert. 

curl -X PATCH "https://api.parq-app.com/api/v1/organizations/org_abc123/deactivate" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL"

DELETE Organisation permanent löschen (Hard Delete)

/api/v1/organizations/:id?permanent=true

WARNUNG: Diese Aktion kann NICHT rückgängig gemacht werden! Verhindert Löschung bei aktiven Lernenden. 

curl -X DELETE "https://api.parq-app.com/api/v1/organizations/org_abc123?permanent=true" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL"

Teamleiter verwalten

POST Teamleiter erstellen

/api/v1/users/team-leads 

curl -X POST "https://api.parq-app.com/api/v1/users/team-leads" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Content-Type: application/json" \
  -d '{ 
    "first_name": "Anna",
    "surname": "Schmidt",
    "email": "anna.schmidt@firma.de",
    "phone": "+49 170 1234567",
    "external_id": "TL-12345"
  }'

Hinweis: Der Teamleiter erhält automatisch eine E-Mail mit Login-Daten.

GET Teamleiter abrufen

/api/v1/users/team-leads/:id 

curl -X GET "https://api.parq-app.com/api/v1/users/team-leads/TL-12345" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL"

GET Teamleiter auflisten

/api/v1/users/team-leads 

curl "https://api.parq-app.com/api/v1/users/team-leads?page=1&limit=50&status=active" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL"

PUT Teamleiter aktualisieren

/api/v1/users/team-leads/:id 

curl -X PUT "https://api.parq-app.com/api/v1/users/team-leads/TL-12345" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Content-Type: application/json" \
  -d '{ "first_name": "Anna", "surname": "Müller", "email": "anna.mueller@firma.de" }'

PATCH Teamleiter aktivieren

/api/v1/users/team-leads/:id/activate 

curl -X PATCH "https://api.parq-app.com/api/v1/users/team-leads/TL-12345/activate" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL"

POST Lernende übertragen (Bulk-Operation) - NEU

/api/v1/users/team-leads/:from_id/transfer-learners

100x schneller als einzelne Updates - Atomare Operation - Nur ein API-Aufruf 

curl -X POST "https://api.parq-app.com/api/v1/users/team-leads/von_id/transfer-learners" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Content-Type: application/json" \
  -d '{ 
    "to_team_lead_id": "zu_teamleiter_id"
  }'

PATCH Teamleiter deaktivieren (Kaskade!)

/api/v1/users/team-leads/:id/deactivate

WICHTIG: Alle zugewiesenen Lernende werden automatisch deaktiviert! 

curl -X PATCH "https://api.parq-app.com/api/v1/users/team-leads/TL-12345/deactivate" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL"

# Response enthält affected_learners Anzahl:
# { "affected_learners": 47, "message": "Teamleiter deaktiviert..." }

DELETE Teamleiter löschen

/api/v1/users/team-leads/:id (Soft Delete) oder ?permanent=true (Hard Delete)

WARNUNG: Hard Delete kann NICHT rückgängig gemacht werden! Verhindert bei zugewiesenen Lernenden. 

# Soft Delete (empfohlen)
curl -X DELETE "https://api.parq-app.com/api/v1/users/team-leads/TL-12345" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL"

# Permanent löschen (Hard Delete)
curl -X DELETE "https://api.parq-app.com/api/v1/users/team-leads/TL-12345?permanent=true" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL"

Lernende verwalten

POST Lernenden erstellen

/api/v1/users/learners 

curl -X POST "https://api.parq-app.com/api/v1/users/learners" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Content-Type: application/json" \
  -d '{ 
    "first_name": "Max",
    "surname": "Mustermann",
    "email": "max.mustermann@example.de",
    "phone": "+49 170 9876543",
    "external_id": "EMP-67890",
    "team_lead_id": "TL-12345",
    "organizations": ["ORG-DRK-001", "Neue Organisation"]
  }'

Hinweis: team_lead_id und organizations akzeptieren UUID, external_id oder Namen (Namen werden automatisch erstellt)

GET Lernenden abrufen

/api/v1/users/learners/:id 

# Mit UUID oder external_id
curl -X GET "https://api.parq-app.com/api/v1/users/learners/EMP-67890" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL"

PUT Lernenden aktualisieren

/api/v1/users/learners/:id 

curl -X PUT "https://api.parq-app.com/api/v1/users/learners/EMP-67890" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Content-Type: application/json" \
  -d '{ "first_name": "Maximilian", "team_lead_id": "TL-67890" }'

Hinweis: Sie können den zugewiesenen Teamleiter ändern

PATCH Lernenden aktivieren - NEU (v3.1)

/api/v1/users/learners/:id/activate 

curl -X PATCH "https://api.parq-app.com/api/v1/users/learners/EMP-67890/activate" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL"

PATCH Lernenden deaktivieren

/api/v1/users/learners/:id/deactivate 

curl -X PATCH "https://api.parq-app.com/api/v1/users/learners/EMP-67890/deactivate" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL"

GET Lernende auflisten (mit Filtern)

/api/v1/users/learners 

# Nur aktive Lernende (Standard)
curl "https://api.parq-app.com/api/v1/users/learners" -H "Authorization: Bearer ..."

# Alle Lernende (aktive + inaktive)
curl "https://api.parq-app.com/api/v1/users/learners?status=all" -H "Authorization: Bearer ..."

# Inklusive soft-gelöschter Lernender
curl "https://api.parq-app.com/api/v1/users/learners?include_deleted=true" -H "Authorization: Bearer ..."

# Filter nach Teamleiter
curl "https://api.parq-app.com/api/v1/users/learners?team_lead_id=TL-12345" -H "Authorization: Bearer ..."

DELETE Lernenden löschen - GEÄNDERT (v3.1) - Jetzt Soft Delete!

/api/v1/users/learners/:id

NEU: Dies ist jetzt ein Soft Delete (Deaktivierung), nicht mehr ein Hard Delete! Konsistent mit Organisationen und Teamleitern. 

# Soft Delete (empfohlen)
curl -X DELETE "https://api.parq-app.com/api/v1/users/learners/EMP-67890" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL"

# Für PERMANENTES Löschen (Hard Delete):
curl -X DELETE "https://api.parq-app.com/api/v1/users/learners/EMP-67890?permanent=true" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL"

Organisationszuweisungen verwalten

POST Organisationen zu Lernendem hinzufügen

/api/v1/users/learner-organizations/:id/add 

curl -X POST "https://api.parq-app.com/api/v1/users/learner-organizations/EMP-67890/add" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Content-Type: application/json" \
  -d '{ "organizations": ["ORG-200", "Weitere Organisation"] }'

Hinweis: Organizations akzeptiert UUIDs, external_ids oder Namen (Namen werden automatisch erstellt)

DELETE Organisation von Lernendem entfernen

/api/v1/users/learner-organizations/:learner_id/:org_id

WICHTIG: Wenn dies die letzte Organisation ist, wird der Lernende automatisch deaktiviert! 

curl -X DELETE "https://api.parq-app.com/api/v1/users/learner-organizations/EMP-67890/ORG-100" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL"

# Response bei letzter Organisation:
# { 
#   "status": "inactive",
#   "message": "Organisation entfernt. Benutzer hat keine Organisationen mehr und wurde automatisch deaktiviert."
# }

Fehlerbehandlung

Code HTTP Beschreibung
AUTHENTICATION_REQUIRED401API-Schlüssel fehlt oder ungültig
NOT_FOUND404Ressource nicht gefunden
VALIDATION_ERROR400Fehlende oder ungültige Felder
DUPLICATE_EMAIL409E-Mail existiert bereits
ALREADY_ACTIVE409Entität ist bereits aktiv (v3.2)
DEPENDENCY_ERROR400Aktive Abhängigkeiten verhindern Löschung
RATE_LIMIT_EXCEEDED429Rate Limit überschritten

API-Konsistenz (v3.2)

Ab Version 3.2 haben alle drei Entitätstypen 100% identisches Verhalten:

Endpunkt-Struktur

Aktion Organisationen Teamleiter Lernende
AktivierenPATCH /:id/activatePATCH /:id/activatePATCH /:id/activate
DeaktivierenPATCH /:id/deactivatePATCH /:id/deactivatePATCH /:id/deactivate
Soft DeleteDELETE /:idDELETE /:idDELETE /:id
Hard DeleteDELETE /:id?permanent=trueDELETE /:id?permanent=trueDELETE /:id?permanent=true

Konsistentes Verhalten

Feature Org TL Lernende
"Already Active" Prüfung✓✓✓
deleted_at wird gelöscht✓✓✓
Kompaktes Deaktivierungs-Format✓✓✓
ALREADY_ACTIVE Fehlercode✓✓✓

Vorteile der Konsistenz

  • Kein if/else in Client-Implementierungen nötig
  • Einheitliche Fehlerbehandlung für alle Entitätstypen
  • Einfachere API-Integration und Wartung
  • Vorhersagbares Verhalten bei allen Operationen

Changelog

v3.2 30.11.2025: Vollständige API-Konsistenz - "Already Active" Prüfung, deleted_at Handling, kompaktes Format
v3.1 30.11.2025: Lernenden-Konsistenz - PATCH /activate, DELETE = Soft Delete, ?permanent=true
v3.0 20.11.2025: Aktivierung/Deaktivierung, Kaskaden, Bulk-Transfer, Soft/Hard Delete
v2.2 15.11.2025: RESTful Path Parameter Support

Support

Bei Fragen oder Problemen kontaktieren Sie uns:

support@parq-app.com