API-Referenz

Authentifizierung

Alle API-Anfragen erfordern eine Authentifizierung über einen API-Key. Fügen Sie Ihren Key im Authorization-Header hinzu.

Authorization: Bearer pr_live_<ihr_api_key>

Sie können API-Keys im Settings Bereich verwalten.

Mitarbeitende

curl -H "Authorization: Bearer pr_live_..." \
  "https://skills.personalrampe.de/api/v1/employees?page=1&limit=20"

// JavaScript (fetch)
const response = await fetch(
  "https://skills.personalrampe.de/api/v1/employees?page=1&limit=20",
  { headers: { Authorization: "Bearer pr_live_..." } }
);
const data = await response.json();

# Python (requests)
import requests
response = requests.get(
    "https://skills.personalrampe.de/api/v1/employees",
    params={"page": 1, "limit": 20},
    headers={"Authorization": "Bearer pr_live_..."}
)
data = response.json()

curl -H "Authorization: Bearer pr_live_..." \
  "https://skills.personalrampe.de/api/v1/employees/abc-123"

curl -X POST \
-H "Authorization: Bearer pr_live_..." \
-H "Content-Type: application/json" \
-d '{
  "personnelNumber": "EMP-001",
  "firstName": "Max",
  "lastName": "Mustermann",
  "businessEmail": "max@example.com",
  "title": "Software Engineer",
  "hiredAt": "2024-01-15T00:00:00Z"
}' \
"https://skills.personalrampe.de/api/v1/employees"

curl -X PATCH \
-H "Authorization: Bearer pr_live_..." \
-H "Content-Type: application/json" \
-d '{"title": "Senior Software Engineer", "leftAt": null}' \
"https://skills.personalrampe.de/api/v1/employees/abc-123"

curl -X DELETE \
-H "Authorization: Bearer pr_live_..." \
"https://skills.personalrampe.de/api/v1/employees/abc-123"

Mitarbeiter-Skills

curl -X PUT \
-H "Authorization: Bearer pr_live_..." \
-H "Content-Type: application/json" \
-d '{
  "score": 4,
  "ratingType": "MANAGER_EVALUATION",
  "comment": "Starke Leistung"
}' \
"https://skills.personalrampe.de/api/v1/employees/abc-123/skills/skill-456"

Bewertungen / Assessments

curl -X POST \
-H "Authorization: Bearer pr_live_..." \
-H "Content-Type: application/json" \
-d '{
  "skillId": "skill-456",
  "score": 3,
  "ratingType": "SELF_ASSESMENT",
  "comment": "In Entwicklung"
}' \
"https://skills.personalrampe.de/api/v1/employees/abc-123/ratings"

Skills

curl -X POST \
-H "Authorization: Bearer pr_live_..." \
-H "Content-Type: application/json" \
-d '{
  "name": "Projektmanagement",
  "description": "Fähigkeit, Projekte zu leiten",
  "ratingScaleMin": 0,
  "ratingScaleMax": 5,
  "ratingScaleType": "NUMERIC"
}' \
"https://skills.personalrampe.de/api/v1/skills"

Positionen

Webhooks

Webhooks ermöglichen es, externe Systeme in Echtzeit über Änderungen in Personalrampe Skills zu benachrichtigen. Sobald ein Ereignis eintritt – z. B. ein neuer Mitarbeiter wird angelegt – sendet die Plattform automatisch eine HTTP-POST-Anfrage an die von dir registrierte URL.

Wie Webhooks funktionieren

Wenn ein Ereignis ausgelöst wird, sendet Personalrampe Skills einen POST-Request an alle für dieses Ereignis registrierten Endpunkte deiner Organisation. Der Request enthält einen JSON-Body mit dem Ereignistyp, einem Zeitstempel und den zugehörigen Daten. Die Anfrage wird asynchron versandt – dein System muss nicht auf die Antwort der Plattform warten.

Voraussetzungen

• Die Ziel-URL muss HTTPS verwenden. Reine HTTP-URLs werden abgelehnt.
• Dein Endpunkt muss innerhalb einer angemessenen Zeit mit einem HTTP-Statuscode antworten (z. B. 200 OK). Fehler werden in der Konsole protokolliert, es gibt aktuell keine automatischen Wiederholungsversuche.
• Die Authentifizierung erfolgt über einen API-Schlüssel (Bearer Token), den du in den Einstellungen unter Einstellungen → API-Schlüssel verwalten kannst.

Verfügbare Ereignisse

Es gibt genau fünf Ereignisse, auf die du subscriben kannst:

Du kannst einen Webhook-Endpunkt für ein oder mehrere Ereignisse gleichzeitig registrieren. Mindestens ein Ereignis ist dabei Pflicht.

Payload-Struktur

Jede Webhook-Anfrage enthält einen JSON-Body nach folgendem Schema:

{
  "event": "employee.created",
  "timestamp": "2026-06-26T09:30:47.000Z",
  "data": { ... }
}

• event – Der Name des Ereignisses (z. B. employee.created)
• timestamp – ISO-8601-Zeitstempel, wann das Ereignis eingetreten ist
• data – Das eigentliche Nutzdaten-Objekt (z. B. die Mitarbeiterdaten)

Signaturprüfung (Empfohlen)

Beim Anlegen eines Webhooks kannst du optional ein Secret angeben. Wenn du ein Secret festlegst, signiert Personalrampe Skills jede ausgehende Anfrage mit HMAC-SHA256 und sendet die Signatur im HTTP-Header X-Personalrampe-Signature mit.

Der Header-Wert hat das Format: sha256=<hex-digest>

So kannst du auf deiner Seite prüfen, ob die Anfrage wirklich von Personalrampe Skills stammt und nicht verfälscht wurde. Berechne dazu den HMAC-SHA256 des rohen JSON-Body mit deinem Secret und vergleiche ihn mit dem Header-Wert. Stimmen beide überein, ist die Anfrage authentisch.

Das Secret ist optional – wenn du keines angibst, wird die Anfrage trotzdem gesendet, enthält aber eine leere Signatur (berechnet auf Basis eines leeren Strings).

Webhook-Endpunkte verwalten

Alle Webhooks auflisten

Neuen Webhook registrieren

curl -X POST \
-H "Authorization: Bearer pr_live_..." \
-H "Content-Type: application/json" \
-d '{
  "url": "https://ihr-system.de/webhooks/personalrampe",
  "events": ["employee.created", "skill.rated"],
  "secret": "ihr-webhook-secret"
}' \
"https://skills.personalrampe.de/api/v1/webhooks"

Bei Erfolg wird der neue Endpunkt mit HTTP 201 Created und den Feldern id, url, events und createdAt zurückgegeben.

Webhook löschen

Typischer Ablauf

1. API-Schlüssel in den Einstellungen anlegen ( Einstellungen → API-Schlüssel)
2. Webhook registrieren via POST /api/v1/webhooks mit URL, gewünschten Ereignissen und optional einem Secret
3. Empfangenen Endpunkt so konfigurieren, dass er mit 200 OK antwortet
4. Optional: Signatur im Header X-Personalrampe-Signature prüfen

Fehlerbehandlung

Alle Fehler geben eine konsistente JSON-Struktur zurück:

{
  "success": false,
  "error": {
    "message": "Employee not found",
    "code": "NOT_FOUND"
  }
}