Personio connector for AI agents

Tools your HR agent reaches for on Personio, scoped before every call.

CALL ANY TOOL

53 tools for HR management in Personio: people and employments, absences and attendance, projects, compensation and salary bands, custom reports, org units, and recruiting candidates and applications.

personio_absence_period_breakdown_list

List absence period breakdown

List the day-by-day breakdown of one absence period in Personio. Returns one entry per day with the date and the effective duration of the absence on that day. Use this to see how much time an absence actually takes on each day. Use personio_absence_period_get for the absence itself.

Parameters

Name

Type

Required

Description

absence_period_id

string

Required

The ID of the absence period. Get it from personio_absence_period_list. Example: 493eff0a-2c5a-467e-8966-f70b4e3805a6.

cursor

string

Optional

Pagination cursor for the breakdowns list. Leave empty for the first page. To get the next page, pass the cursor from the previous response's _meta.links.next.href (the value of its cursor query parameter). Example: cur_82sQwR2eZvKilo2duNh219Kw.

limit

integer

Optional

Maximum number of daily breakdowns to return in one page, from 1 to 100. Leave empty to use the Personio default of 28. Example: 50.

personio_absence_period_create

Create absence period

Create an absence period (time off) for a person in Personio, such as vacation or sick leave. Returns the new absence period's id. Use this to book time off. Use personio_absence_period_update to change an existing one. Get the absence type ID from personio_absence_type_list first; whether hours or half days are allowed depends on that type's unit.

Parameters

Name

Type

Required

Description

absence_type_id

string

Required

ID of the absence type (for example Paid vacation). Get it from personio_absence_type_list. Example: cba6fa09-d8fe-4de0-be03-f0a1d48df766.

person_id

string

Required

ID of the person taking the absence. Get it from personio_person_list. Example: 12345.

starts_from

string

Required

When the absence starts, as a local date-time without a timezone offset (YYYY-MM-DDTHH:MM:SS), in the person's timezone. Do not add Z or an offset. Example: 2025-07-01T00:00:00.

comment

string

Optional

Comment attached to the absence. Example: Summer vacation.

ends_at

string

Optional

When the absence ends, as a local date-time without a timezone offset (YYYY-MM-DDTHH:MM:SS), in the person's timezone. Leave empty for an open-ended absence such as long-term sick leave. Example: 2025-07-05T00:00:00.

ends_at_type

string

Optional

For half-day absence types, whether the absence ends after the FIRST_HALF or SECOND_HALF of the end day. Only used with ends_at. Example: SECOND_HALF. One of: `FIRST_HALF`, `SECOND_HALF`.

skip_approval

boolean

Optional

Set to true to skip any approval step this change would otherwise need in Personio (for example, a manager approval). Leave empty or false to follow the company's normal approval rules. Example: false.

starts_from_type

string

Optional

For half-day absence types, whether the absence starts in the FIRST_HALF or SECOND_HALF of the start day. Leave empty for full days or hourly types. Example: FIRST_HALF. One of: `FIRST_HALF`, `SECOND_HALF`.

substitute_id

string

Optional

Person ID of the colleague covering during the absence. Only used if the absence type's policy allows substitutes. Example: 67890.

personio_absence_period_get

Get absence period

personio_absence_period_list

List absence period

List absence periods (time off such as vacation or sick leave) in Personio, filtered by person, absence type, date range or update time. Returns a page of absence periods with id, person, absence type, start and end (date-time and half-day type), timezone, comment, approval status and timestamps. Use this to see who is or was off and when. Use personio_absence_period_get for one known absence period.

Parameters

Name

Type

Required

Description

absence_type_id

string

Optional

Only return absences of these absence types. Separate multiple IDs with commas; get them from personio_absence_type_list. Example: cba6fa09-d8fe-4de0-be03-f0a1d48df766.

cursor

string

Optional

Pagination cursor for the absence periods list. Leave empty for the first page. To get the next page, pass the cursor from the previous response's _meta.links.next.href (the value of its cursor query parameter). Example: cur_82sQwR2eZvKilo2duNh219Kw.

ends_at_gte

string

Optional

Only return absences ending at or after this date-time (RFC 3339). Example: 2025-01-01T00:00:00Z.

ends_at_lte

string

Optional

Only return absences ending at or before this date-time (RFC 3339). Example: 2025-12-31T23:59:59Z.

string

Optional

Only return absence periods with these IDs. Separate multiple IDs with commas. Example: abc6fa09-d8fe-4de0-be03-f0a1d48df766.

limit

integer

Optional

Maximum number of absence periods to return in one page, from 1 to 100. Leave empty to use the Personio default of 100. Example: 50.

person_id

string

Optional

Only return absences of these persons. Separate multiple person IDs with commas. Example: 12345,67890.

starts_from_gte

string

Optional

Only return absences starting at or after this date-time (RFC 3339). Example: 2025-01-01T00:00:00Z.

starts_from_lte

string

Optional

Only return absences starting at or before this date-time (RFC 3339). Example: 2025-12-31T23:59:59Z.

updated_at_gte

string

Optional

Only return absences updated at or after this date-time (RFC 3339). Example: 2025-06-01T00:00:00Z.

updated_at_lte

string

Optional

Only return absences updated at or before this date-time (RFC 3339). Example: 2025-06-30T23:59:59Z.

personio_absence_period_update

Update absence period

personio_absence_type_get

Get absence type

personio_attendance_period_create

Create attendance period

personio_attendance_period_list

List attendance period

List attendance periods (tracked working time and breaks) in Personio, filtered by person, project, status, date range or update time. Returns a page of attendance periods with id, person, type (WORK or BREAK), start, end, duration, attribution date, approval status, project and comment. Use this to review tracked hours. Use personio_attendance_period_get for one known period.

Parameters

Name

Type

Required

Description

attribution_date_gte

string

Optional

Only return periods attributed to this date or later (YYYY-MM-DD). Example: 2025-01-01.

attribution_date_lte

string

Optional

Only return periods attributed to this date or earlier (YYYY-MM-DD). Example: 2025-01-31.

cursor

string

Optional

Pagination cursor for the attendance periods list. Leave empty for the first page. To get the next page, pass the cursor from the previous response's _meta.links.next.href (the value of its cursor query parameter). Example: cur_82sQwR2eZvKilo2duNh219Kw.

end_gte

string

Optional

Only return periods ending at or after this time, as a local date-time without a timezone offset (YYYY-MM-DDTHH:MM:SS). Example: 2025-01-01T00:00:00.

end_lte

string

Optional

Only return periods ending at or before this time, as a local date-time without a timezone offset (YYYY-MM-DDTHH:MM:SS). Example: 2025-01-31T23:59:59.

array

Optional

Only return attendance periods with these IDs. Example: ["bd242cd1-5116-41a0-99aa-c12af4837c81"].

limit

integer

Optional

Maximum number of attendance periods to return in one page, from 1 to 100. Leave empty to use the Personio default of 100. Example: 50.

person_id

array

Optional

Only return attendance periods of these persons. Example: ["12345", "67890"].

project_id

array

Optional

Only return attendance periods booked on these projects. Example: ["1234"].

sort

string

Optional

Comma-separated sort fields; prefix a field with - for descending. Allowed fields: person.id, start.date_time, end.date_time, updated_at, status. Default: person.id,start.date_time,end.date_time. Example: -start.date_time.

start_gte

string

Optional

Only return periods starting at or after this time, as a local date-time without a timezone offset (YYYY-MM-DDTHH:MM:SS). Example: 2025-01-01T00:00:00.

start_lte

string

Optional

Only return periods starting at or before this time, as a local date-time without a timezone offset (YYYY-MM-DDTHH:MM:SS). Example: 2025-01-31T23:59:59.

status

string

Optional

Only return attendance periods with this approval status. Example: CONFIRMED. One of: `PENDING`, `CONFIRMED`, `REJECTED`.

updated_at_gte

string

Optional

Only return periods updated at or after this date-time (RFC 3339). Example: 2025-06-01T00:00:00Z.

updated_at_lte

string

Optional

Only return periods updated at or before this date-time (RFC 3339). Example: 2025-06-30T23:59:59Z.

personio_compensation_type_create

Create compensation type

personio_compensation_type_list

List compensation type

personio_cost_center_list

List cost center

personio_document_update

Update document

personio_employment_get

Get employment

personio_employment_list

List employment

personio_legal_entity_get

Get legal entity

personio_legal_entity_list

List legal entity

personio_person_get

Get person

personio_person_list

List person

List people (employees) in Personio, filtered by ID, email, name, status, or created/updated date. Returns a page of persons with id, email, first and last name, preferred name, gender, status, custom attributes and a summary of their employments, plus _meta.links for the next page. Use this to find a person's ID or browse employees. Use personio_person_get for one known person.

Parameters

Name

Type

Required

Description

created_at_gt

string

Optional

Only return persons created after this date-time (RFC 3339). Example: 2024-01-01T00:00:00Z.

created_at_lt

string

Optional

Only return persons created before this date-time (RFC 3339). Example: 2024-12-31T23:59:59Z.

cursor

string

Optional

Pagination cursor for the persons list. Leave empty for the first page. To get the next page, pass the cursor from the previous response's _meta.links.next.href (the value of its cursor query parameter). Example: cur_82sQwR2eZvKilo2duNh219Kw.

string

Optional

Only return persons with these email addresses. Separate multiple emails with commas. Example: jane.doe@example.com.

first_name

string

Optional

Only return persons with this exact first name. Example: Jane.

string

Optional

Only return persons with these IDs. Separate multiple IDs with commas. Example: 12345,67890.

last_name

string

Optional

Only return persons with this exact last name. Example: Doe.

limit

integer

Optional

Maximum number of persons to return in one page, from 1 to 50. Leave empty to use the Personio default of 10. Example: 50.

preferred_name

string

Optional

Only return persons with this preferred name. Example: JJ.

status

string

Optional

Filter by employment status. ACTIVE includes persons whose latest employment is active, on leave, or onboarding; INACTIVE includes persons whose latest employment is inactive. Example: ACTIVE. One of: `ACTIVE`, `INACTIVE`.

updated_at_gt

string

Optional

Only return persons updated after this date-time (RFC 3339). Useful for incremental syncs. Example: 2024-06-01T00:00:00Z.

updated_at_lt

string

Optional

Only return persons updated before this date-time (RFC 3339). Example: 2024-06-30T23:59:59Z.

personio_person_update

Update person

personio_project_create

Create project

personio_project_list

List project

personio_project_member_add

Add project member

personio_recruiting_application_get

Get recruiting application

personio_recruiting_application_list

List recruiting application

personio_recruiting_candidate_list

List recruiting candidate

personio_recruiting_category_get

Get recruiting category

personio_recruiting_category_list

List recruiting category

personio_report_attribute_list

List report attribute

personio_report_get

Get report

personio_salary_band_list

List salary band

For more tools, view docs.

Build your Agent

Same auth pattern across LangChain, OpenAI, Anthropic, and Google ADK.

import { ScalekitClient } from "@scalekit-sdk/node";
import { createReactAgent } from "@langchain/langgraph/prebuilt";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);

// Personio tools available to this agent
const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["personio"], toolNames: [
    "personio_person_list",
    "personio_absence_type_list",
    "personio_absence_period_create"] },
  pageSize: 100,
});

const agent = createReactAgent({ llm, tools });
await agent.invoke({ messages: [{ role: "user", content: "Book 3 days of paid vacation for Sam Lee starting December 22" }] });

import OpenAI from "openai";
import { ScalekitClient } from "@scalekit-sdk/node";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);
const openai = new OpenAI();

const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["personio"] }, pageSize: 100,
});

const res = await openai.chat.completions.create({
  model: "gpt-5",
  messages: [{ role: "user", content: "Book 3 days of paid vacation for Sam Lee starting December 22" }],
  tools,
});

// Execute the tool call with the vaulted Personio service account credentials
await sk.tools.executeTool(res.choices[0].message.tool_calls[0], "user_123");

import Anthropic from "@anthropic-ai/sdk";
import { ScalekitClient } from "@scalekit-sdk/node";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);
const anthropic = new Anthropic();

const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["personio"] }, pageSize: 100,
});

const msg = await anthropic.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Book 3 days of paid vacation for Sam Lee starting December 22" }],
  tools,
});

// Tool call runs with the vaulted Personio service account credentials
await sk.tools.executeTool(msg.content, "user_123");

import { Agent } from "@google/adk/agents";
import { ScalekitClient } from "@scalekit-sdk/node";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);

const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["personio"] }, pageSize: 100,
});

const agent = new Agent({
  name: "hr_agent",
  model: "gemini-2.5-pro",
  instruction: "Personio tools available to this agent",
  tools,
});

await agent.run("Book 3 days of paid vacation for Sam Lee starting December 22");

Try these prompts

Copy any prompt into your agent. Each maps directly to a Personio tool. Click to copy, paste into your agent, done.

People

Copy the prompt

Copied

Look up the employment details for dana.kim@acme.com.

Copy the prompt

Copied

List people created in Personio in the last 30 days.

Copy the prompt

Copied

Set Maria Lopez as the supervisor on Alex Rivera's employment.

Time

Copy the prompt

Copied

Who has approved time off next week?

Copy the prompt

Copied

Book 3 days of paid vacation for Sam Lee starting December 22.

Copy the prompt

Copied

Log 8 hours of attendance for Chen Wei on the Website Redesign project yesterday.

Reports and recruiting

Copy the prompt

Copied

Run the Headcount by Department report.

Copy the prompt

Copied

List recruiting applications updated this week.

Copy the prompt

Copied

Show the salary band for the Senior Product Manager job.

SEE HOW AUTH WORKS

You connect Personio once with a service account, and Scalekit authenticates every call. Service account credentials stay vaulted, every call is scope checked, and every action is logged.

Authorize

Your user connects

Personio

once. We tie it to their identity and the meetings they approved — no shared bot account, no org-wide access

Who:

user ‘A’

when:

Once per user

access:

Limited to user

Store

Their

Personio

token lives in a vault scoped to them. User A's meetings are never reachable by an agent acting for user B, even on the same connection

vault:

encrypted

scope:

per-user

tokens:

auto-refreshed

Resolve

When your agent calls a

Personio

tool, we fetch the right token server-side. It never touches your agent, never appears in the LLM context, never shows up in your logs

speed:

~40ms

check:

before every call

seen by:

nobody

Audit

Every

Personio

tool call is logged — who triggered it, which meeting was fetched, what came back. 90 days of history, tied to the user who authorized it

history:

90 days

export:

SIEM-ready

logged:

every call

Test other agents

See the same auth pattern across other HR and finance connectors.

People Ops and HR teams

Offer letter routing agent

Drafts the offer in PandaDoc, blocks on the hiring manager's approval in Slack, then emails the candidate their e-signature link. Every call runs as the recruiter who triggered it, never a shared HR bot.

People Ops and HR teams

Performance review collector

Collects review feedback from Airtable and Google Forms scoped to each manager's direct reports, writes per-employee summaries to Notion, and DMs the manager a Slack digest.

Why Scalekit

Secure your agent's access. Connectors ship in minutes

01.

Service account secrets stay out of agent code

Pasting a Personio client secret into agent code puts it one log line away from a leak. Scalekit keeps the service account credentials in its vault, authenticates each call at request time, and records which agent run made it.

// secret in code
env → prompt, logs

// scalekit
vault → call ✓

02.

Authentication is not authorization

03.

Multi-tenancy is architectural

04.

Personio today. Ten connectors tomorrow.

“Our agents act across Salesforce, Gong, Google Drive, and more, on behalf of every customer. Scalekit behind the scenes meant we can keep adding tools without ever rebuilding how credentials or tool calling work.”

Venu Madhav Kattagoni

Head of Engineering / Von

FAQs

Frequently Asked Questions

Does the agent use a shared service account for Personio?

Yes. You connect Personio once with a service account, and Scalekit authenticates every call with those Personio API credentials (OAuth 2.0 client credentials). The agent reaches the data those credentials can access, and audit logs record every action the agent takes.

Where are the Personio service account credentials stored?

In Scalekit's managed AES-256 token vault, namespaced per tenant. Revocation is a single dashboard action. Credentials never appear in prompts, logs, or LLM context.

Can I limit what the agent does in Personio?

Yes. Filter by tool name in listScopedTools to expose only what you want, for example the people, absence, and report read tools without personio_compensation_create or personio_employment_update. No Personio tool deletes data. Scalekit also enforces scope checks before every API call.

What happens when Personio access is turned off?

Disable the connection in the Scalekit dashboard and the next tool call fails closed with a clear error. Other tenants are unaffected, and the change is logged.

Which Personio data can the agent change?

Absences and attendance periods, people and their employments, compensations and compensation types, attendance projects and their members, document metadata, and new recruiting applications. Reports, salary bands, org units, legal entities, and jobs are read-only.