# Personio

> Personio HR - employees, absences, attendances, projects, documents and recruiting via the Personnel Data API.

Lets an agent read and manage HR data in Personio - employees, absences and
time-offs, attendances, projects, documents and recruiting applications.

## What it can do

| Method | What it does |
| --- | --- |
| `personio_list_employees` | List employees; filter by email, updated_since, attributes; paginate. |
| `personio_get_employee` | Get one employee by id. |
| `personio_create_employee` | Create an employee (email, first_name, last_name, hire_date). |
| `personio_update_employee` | Update an employee's fields. |
| `personio_get_employee_absence_balance` | Get an employee's time-off balance. |
| `personio_list_employee_attributes` | List allowed employee custom attributes. |
| `personio_list_time_off_types` | List time-off (absence) types and their ids. |
| `personio_list_time_offs` | List day-based time-offs in a date range. |
| `personio_get_time_off` | Get one time-off by id. |
| `personio_create_time_off` | Create a day-based time-off (absence). |
| `personio_delete_time_off` | Delete a time-off. |
| `personio_list_absence_periods` | List hour-based absence periods. |
| `personio_create_absence_period` | Create an hour-based absence period. |
| `personio_list_attendances` | List attendances in a date range. |
| `personio_create_attendance` | Create an attendance entry for an employee. |
| `personio_update_attendance` | Update an attendance entry. |
| `personio_delete_attendance` | Delete an attendance entry. |
| `personio_list_attendance_periods_v2` | List attendance periods (v2, replaces deprecated v1 attendances); filter by person, date, project, status. |
| `personio_get_attendance_period_v2` | Get one attendance period by id (v2). |
| `personio_list_projects` | List attendance projects. |
| `personio_create_project` | Create an attendance project. |
| `personio_update_project` | Update an attendance project. |
| `personio_delete_project` | Delete an attendance project. |
| `personio_list_projects_v2` | List projects (v2, replaces deprecated v1 projects); filter by id, name, status, code, parent. |
| `personio_get_project_v2` | Get one project by id (v2). |
| `personio_list_custom_reports` | List custom reports metadata; filter by report ids and status. |
| `personio_get_custom_report` | Get a custom report's data (rows) by id; paginate and translate via locale. |
| `personio_list_custom_report_columns` | List human-readable labels and data types for report column ids. |
| `personio_list_document_categories` | List employee document categories. |
| `personio_upload_document` | Upload a document to an employee from a URL. |
| `personio_list_recruiting_jobs` | List recruiting jobs and their job_position ids (v2, beta). |
| `personio_list_recruiting_applications` | List existing recruiting applications (v2, beta). |
| `personio_list_recruiting_categories` | List recruiting job categories (v2, beta). |
| `personio_create_application` | Create a recruiting application for a job posting. |
| `personio_upload_application_document` | Upload a file to attach to a recruiting application. |

## How to get credentials

Personio authenticates with a client id and client secret, which FlyMyAI
exchanges for a short-lived Bearer token on every call.

1. Open the Personio [API getting-started guide](https://developer.personio.de/docs/getting-started-with-the-personio-api).
2. In Personio, go to **Settings > Integrations > API credentials**.
3. **Generate new credential** and grant it read/write access to the data
   the agent needs (Employees, Absences, Attendances, Documents, Recruiting).
4. Copy the **Client ID** and **Client Secret**.

The recruiting actions need the credential to have Recruiting API access
enabled on the same integration.

## Fields to fill in FlyMyAI

| FlyMyAI field | Where it comes from |
| --- | --- |
| `PERSONIO_CLIENT_ID` | Settings > Integrations > API credentials > Client ID |
| `PERSONIO_CLIENT_SECRET` | Settings > Integrations > API credentials > Client Secret |

## Links

- [Get started with the Personio API](https://developer.personio.de/docs/getting-started-with-the-personio-api)
- [API reference](https://developer.personio.de/reference)