# Personio

SureCloud connects to Personio to retrieve employee records, employment status, and organisational data. This allows SureCloud to monitor joiner, mover, and leaver events within Personio — confirming that HR records reflect current employment status, that access provisioning and deprovisioning controls are aligned with lifecycle events, and that employee data is being maintained consistently across connected systems.

## Authentication and setup

Personio authenticates API requests using a Client ID and Client Secret, which are exchanged for a short-lived bearer token. SureCloud manages this token exchange automatically.

{% stepper %}
{% step %}
**Create an API credential in Personio**

Log in to Personio with an Administrator account. Navigate to **Settings → Integrations → API Credentials** and click **Generate New Credentials**. Give the credential set a name such as `SureCloud CCM`. Select read-only access for Employees and the relevant HR data objects. Click **Generate** and copy the **Client ID** and **Client Secret**.
{% endstep %}

{% step %}
**Enter the credentials in SureCloud**

Navigate to **SureCloud → Integrations → Personio → Connect**. Enter the **Client ID** and **Client Secret**. Click **Save** and then **Test Connection**.
{% endstep %}

{% step %}
**Test the connection**

SureCloud will authenticate against `POST /auth` and call `GET /company/employees` to confirm data access. A green status confirms the connection is live.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Store the Client Secret securely. SureCloud encrypts it at rest, but treat it as a sensitive credential. Rotate it every 90 days in **Personio → Settings → Integrations → API Credentials** and update it in **SureCloud → Integrations → Personio → Edit Connection**.
{% endhint %}

## Endpoints

| API Call                      | Use Case                                                                              |
| ----------------------------- | ------------------------------------------------------------------------------------- |
| `POST /auth`                  | Exchange Client ID and Secret for a bearer token                                      |
| `GET /company/employees`      | Enumerate all employees including employment status, start date, and termination date |
| `GET /company/employees/{id}` | Retrieve individual employee detail including department, position, and supervisor    |
| `GET /company/attendances`    | Retrieve attendance records for work pattern and presence evidence                    |
| `GET /company/time-off-types` | Retrieve time-off type definitions for HR data completeness checks                    |
| `GET /company/departments`    | List departments for organisational structure mapping                                 |

## Pagination

`GET /company/employees` supports page-based pagination. SureCloud sets `limit` and `offset` parameters and increments the offset until the returned count is less than the limit.

```json
GET /company/employees?limit=200&offset=200
```

`GET /company/departments` and `GET /company/time-off-types` return complete result sets in a single response.

## Required permissions

SureCloud requires Personio API credentials with read access to:

| Data Object    | Purpose                                              |
| -------------- | ---------------------------------------------------- |
| Employees      | Read employee profiles, status, and employment dates |
| Departments    | Read organisational structure                        |
| Attendances    | Read work pattern evidence                           |
| Time-off types | Read leave type definitions                          |

No write, payroll, or document management permissions are required.

## Polling frequency

| Data Type                              | Interval       |
| -------------------------------------- | -------------- |
| Employee records and employment status | Every 24 hours |
| Department structure                   | Every 24 hours |
| Attendance records                     | Every 24 hours |

## Troubleshooting

<details>

<summary>Authentication returns "invalid_credentials"</summary>

The Client ID or Client Secret is incorrect or has been regenerated in Personio. Navigate to **Personio → Settings → Integrations → API Credentials**, confirm the credential set is active, and update the credentials in **SureCloud → Integrations → Personio → Edit Connection**.

</details>

<details>

<summary>Employee data is incomplete — missing attributes on some records</summary>

Personio's API only returns employee attributes that have been enabled in the API credential's attribute permission settings. If certain fields (e.g. department, cost centre, or manager) are missing, navigate to the API credential in **Personio → Settings → Integrations → API Credentials** and enable read access for the missing attributes.

</details>

<details>

<summary>Terminated employees are not returned</summary>

Personio returns employees with `status: inactive` for terminated records. If these are missing from SureCloud, confirm the API credential has read access to inactive employees. Some Personio configurations restrict inactive record visibility by role — check with your Personio administrator if needed.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/personio.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.