API Reference

Authentication

All API requests require authentication via an API key. Include your key in the Authorization header.

Authorization: Bearer pr_live_<your_api_key_here>

You can manage API keys in the Settings page.

Employees

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": "John",
  "lastName": "Doe",
  "businessEmail": "john@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"

Employee Skills

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

Ratings / Assessments

curl -X POST \
-H "Authorization: Bearer pr_live_..." \
-H "Content-Type: application/json" \
-d '{
  "skillId": "skill-456",
  "score": 3,
  "ratingType": "SELF_ASSESMENT",
  "comment": "Developing"
}' \
"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": "Project Management",
  "description": "Ability to lead projects",
  "ratingScaleMin": 0,
  "ratingScaleMax": 5,
  "ratingScaleType": "NUMERIC"
}' \
"https://skills.personalrampe.de/api/v1/skills"

Positions

Webhooks

Webhooks let you receive real-time notifications in external systems whenever something changes in Personalrampe Skills. When an event occurs – for example, a new employee is created – the platform automatically sends an HTTP POST request to the URL you registered.

How Webhooks Work

When an event is triggered, Personalrampe Skills sends a POST request to all endpoints in your organisation that are subscribed to that event. The request body is JSON and contains the event name, a timestamp and the relevant data. Delivery is asynchronous – your system does not need to wait for the platform to respond.

Requirements

• The target URL must use HTTPS. Plain HTTP URLs are rejected.
• Your endpoint should respond with an HTTP success status code (e.g. 200 OK) in a timely manner. Errors are logged to the console; there are currently no automatic retries.
• Authentication uses an API key (Bearer Token) that you manage in the application under Settings → API Keys.

Available Events

There are exactly five events you can subscribe to:

One webhook endpoint can be subscribed to one or multiple events simultaneously. At least one event is required.

Payload Structure

Every webhook request contains a JSON body with the following shape:

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

• event – The event name (e.g. employee.created)
• timestamp – ISO 8601 timestamp of when the event occurred
• data – The actual payload object (e.g. employee data)

Signature Verification (Recommended)

When creating a webhook you can optionally provide a secret. If you do, Personalrampe Skills will sign every outgoing request using HMAC-SHA256 and send the signature in the HTTP header X-Personalrampe-Signature.

The header value follows the format: sha256=<hex-digest>

On your end, you can verify the request by computing the HMAC-SHA256 of the raw JSON request body using your secret and comparing the result to the header value. If they match, the request is authentic and has not been tampered with.

The secret is optional – if you do not provide one, the request is still sent but the signature is computed using an empty string as the key.

Managing Webhook Endpoints

List all webhooks

Register a new webhook

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

On success the new endpoint is returned with HTTP 201 Created containing id, url, events and createdAt.

Delete a webhook

Typical Setup Flow

1. Create an API key in the application under Settings → API Keys
2. Register a webhook via POST /api/v1/webhooks with your URL, desired events and optionally a secret
3. Configure your receiving endpoint to respond with 200 OK
4. Optionally verify the X-Personalrampe-Signature header on every incoming request

Error Handling

All errors return a consistent JSON structure:

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