Authenticate to the Personio API v2 with client credentials and retrieve a paginated list of employee (person) records.
domain: developer.personio.de · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
In Personio, go to Settings > API Credentials and generate a new client_id/client_secret pair, whitelisting which employee attributes this credential is allowed to read.
POST the client_id and client_secret as a JSON or form-encoded body (not query-string, which is deprecated) to https://api.personio.de/v1/auth to obtain a bearer access token prefixed 'papi-'.
Cache the token instead of re-authenticating per call — it stays valid and reusable for 24 hours, including for parallel requests.
Call GET https://api.personio.de/v2/persons with header Authorization: Bearer <token>, which requires the personio:persons:read scope.
Page through results with the cursor query parameter (limit 1-50, default 10); pass the cursor returned in the prior response to fetch the next page.
Narrow results with filters such as id, email, first_name/last_name, created_at/updated_at, or status=ACTIVE|INACTIVE as needed.
Known gotchas
The v2 authentication endpoint is rate-limited to 150 requests/minute; exceeding it throttles you to 1 request/second for the next 60 seconds, so reuse the 24-hour token rather than re-authenticating per call.
Only attributes explicitly whitelisted on the API credential are returned by /v2/persons; unwhitelisted fields are omitted regardless of scope, and no salary data beyond fixed salary 100%/hourly wage is ever exposed via the API.
Sending credentials as query-string parameters on POST /v1/auth is deprecated — use a JSON or URL-encoded request body.
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?