VX Agents

OpenAPI Marketplace · HR

Personio HR

v1.0.0 · 7 endpoints · 0 connections · shared by vx.ai

Lets an agent look up employees in Personio, check absence types and existing time-off, book new absences and review attendance records for a date range. Useful for HR assistants that answer who is out, file leave requests and prepare attendance reports. Based on the Personio API specification.

Connect this API to an AI agent Browse all specs

What you can do with Personio HR via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

MethodPathOperationDescription
GET /company/employees listEmployees List all employees in the company
GET /company/employees/{employee_id} getEmployee Get one employee's profile by Personio id
GET /company/time-off-types listTimeOffTypes List absence types (vacation, sick leave, ...)
GET /company/time-offs listTimeOffs List absences in a date range, optionally for given employees
POST /company/time-offs createTimeOff Book an absence for an employee
GET /company/time-offs/{id} getTimeOff Get one absence period
GET /company/attendances listAttendances List attendance records (worked hours) in a date range

Authentication

bearerAuth

Bearer token — sent as Authorization: Bearer <token>

How to get a credential

  1. In Personio, open Settings > Integrations > API credentials (you need admin rights).
  2. Click Generate new credential, name it (e.g. "VX Agents") and enable the scopes below plus the employee attributes the agent may read (name, email, department, position, status...).
  3. Copy the Client ID and Client Secret.
  4. Exchange them for a token: POST https://api.personio.de/v1/auth with client_id and client_secret. The response's data.token is the bearer token; it expires, so request a new one when calls start returning 401.

Permissions used

Personio access Operations
Employees: read listEmployees, getEmployee
Absences: read listTimeOffTypes, listTimeOffs, getTimeOff
Absences: read/write createTimeOff
Attendances: read listAttendances

Common errors

  • 401 Unauthorized: token missing or expired. Request a new token from /auth and update the credential.
  • 403 Forbidden: the API credential lacks the scope or the employee attribute is not whitelisted. Edit the credential in Personio.
  • 400 / 422 Bad Request: invalid dates (use YYYY-MM-DD), an unknown time_off_type_id, or overlapping absences. Check the message and fix the input.
  • 429 Too Many Requests: rate limit reached. Wait a minute and retry with fewer requests.

Store the bearer token as a VX Agents credential (Bearer token) so it is sent as Authorization: Bearer <token> on every call.

Usage guide

Setup

  1. Create Personio API credentials (Settings > Integrations > API credentials) with Employees read, Absences read/write and Attendances read, and whitelist the employee attributes the agent may see.
  2. Exchange the Client ID and Secret for a token (POST https://api.personio.de/v1/auth) and save it as a Bearer credential. Tokens expire: refresh it when calls return 401.
  3. Optional: pin limit (e.g. 200) on listTimeOffs and listAttendances so pages stay small.

Who is out / book leave

  1. listEmployees (or getEmployee with a known id) to find the employee's numeric id. Match by name or email from the returned attributes.
  2. listTimeOffTypes to get the time_off_type_id for the requested kind of absence (e.g. "Paid vacation", "Sick leave").
  3. listTimeOffs with start_date, end_date and employees[] to see existing absences and avoid overlaps. Use getTimeOff for one period's details.
  4. Show the user the employee, type, dates and half-day flags, and wait for confirmation. Then call createTimeOff with employee_id, time_off_type_id, start_date, end_date, half_day_start, half_day_end (all required) and an optional comment.

Attendance report

  1. listAttendances with required start_date and end_date (optionally employees[]).
  2. Page with offset and limit until fewer than limit rows come back, then sum hours per employee.

Good to know

  • Dates are YYYY-MM-DD; date ranges are inclusive. updated_from/updated_to accept a date or a datetime.
  • Employee and time-off ids are integers. Attribute values come back as objects ({label, value, type}): read value.
  • Only attributes whitelisted on the API credential are returned; a missing field usually means it is not whitelisted.
  • Creating an absence changes HR records and may notify approvers: always confirm with the user first. This spec has no delete operations.
  • Respect rate limits: on 429 wait before retrying.

How to use this spec

  1. Create a free VX Agents account (sandbox tools included).
  2. Open the marketplace and connect “Personio HR” to an agent.
  3. Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.