> For the complete documentation index, see [llms.txt](https://hub.equipme.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hub.equipme.io/dokumentation/organization/hr-sync.md).

# HR sync

HR sync: take over employees, locations, departments, supervisors and cost centers automatically from the HR system or Microsoft Entra ID.

With the **HR sync**, equipme takes over the organizational data automatically from your HR system, e.g. Personio, Workday, SAP SuccessFactors or many others. Microsoft Entra ID or Google Workspace are also possible. New employees are created, changes are applied and departing employees are moved to offboarding.

**Path:** Settings → **"Integrations"** → **"HR sync"** tab (or "Employees" → "Synchronize")

**Prerequisites:** administrator rights in equipme, credentials with administrator rights for the HR system and the activated HR sync module. If it is not activated, an information page appears. Hosted customers contact their provider to have it activated.

## How the synchronization works

* Synchronization runs **every 3 hours by default**. With **"Start synchronization now"** you trigger the synchronization immediately.
* The synchronization is **one-way**: The HR system is the leading system. Changes you make in equipme to synchronized fields are overwritten in the next run. No data is written back to the HR system.
* Existing employees are matched via the **username** (email or UPN).
* **One** HR integration can be set up.

## Setting up

1. Click **"Add"** and select the HR system.
2. In the connection dialog, log in with the HR system's credentials. The dialog opens in your app language and guides you through connecting the selected system (see below).
3. Optionally **"Set up employee filter"**: e.g. only take over certain locations, departments or groups.
4. Optionally **"Configure settings"** (see below).
5. **"Enable integration"**. The first synchronization may take longer for large organizations.

### Where do I find the instructions for my HR system?

There is no separate setup guide per HR system, neither as a page in equipme nor in this guide. The instructions are part of the **connection dialog**: after you select the HR system under "Add", it guides you step by step through connecting exactly this system. The same dialog also opens for "Update access rights and reconnect the integration" and for "Set up employee filter".

Have an account with administrator rights in the HR system at hand. If you get stuck or need help on the HR system side, contact [Support](/dokumentation/help/support.md).

{% hint style="info" %}
If you use both an HR system and Microsoft Entra ID, preferably connect the **HR system**: It usually provides more complete data (start date, cost center, location).
{% endhint %}

## The integration overview

Columns: "Integration", "Category", "Status", "Created", "Last synchronization", "Synchronized employees".

| Status              | Meaning                                                                                                              |
| ------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **"Active"**        | The synchronization runs regularly.                                                                                  |
| **"Inactive"**      | Set up, but not active. Filters and settings can only be changed in this status.                                     |
| **"Synchronizing"** | A synchronization is currently running.                                                                              |
| **"Invalid"**       | Credentials are missing or invalid. Use "Update access rights and reconnect the integration" (with the same tenant). |

**"Delete integration"** ends the synchronization. Data already taken over is retained.

## Settings ("HR sync configuration")

| Area          | Option                                   | Effect                                                                                                          |
| ------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Employees** | "Enable self-service"                    | Newly created employees may request in self-service right away.                                                 |
|               | "Status of newly synchronized employees" | Fixed initial status (e.g. "Onboarding"). Leave empty to take over the status from the HR system (recommended). |
| **Locations** | "Synchronize locations"                  | Create locations from the HR system and assign employees.                                                       |
|               | "Default location"                       | Used if the HR system provides no location or location synchronization is off.                                  |
| **Groups**    | "Create company groups"                  | One group of type "Company" per company in the HR system.                                                       |
|               | "Divide groups by company"               | Departments with the same name in different companies remain separate (e.g. "IT – Company A").                  |
|               | "Synchronize Entra groups"               | Only with Microsoft Entra ID: take over additional groups by object ID, e.g. for self-service tags.             |

## What is taken over

* **Employees:** first and last name, username, business and private email, phone, position, personnel number, start and exit date, status, location, supervisor, cost center, groups (departments, teams etc.) and home office address.
* **Locations, departments and cost centers** are created as needed. Locations taken over from Microsoft Entra ID initially have **no address**; add it before you have anything delivered there.
* **Supervisors** are created as well if needed.
* **Inactive employees** in the HR system are locked in equipme.
* **Departing employees:** Those with services receive the status "Offboarding"; those without services are removed.

### Locked fields

Synchronized employees show the note "The employee is synchronized via HR sync from the source '…'. Therefore, not all fields are available for editing." in their profile.

* **Not editable:** name, username, business email, mobile number, position, cost center, supervisor, department, start and exit date as well as the location (with active location synchronization).
* **Editable:** e.g. representative, notes, private email and roles.

In lists, the **"Source"** column shows whether a record comes from equipme or from the HR system.

### Mapping for Microsoft Entra ID

| Microsoft Entra ID           | equipme                               |
| ---------------------------- | ------------------------------------- |
| givenName / surname          | First name / last name                |
| userPrincipalName            | Username                              |
| jobTitle                     | Position                              |
| department                   | Department (group; created if needed) |
| employeeId                   | Personnel number                      |
| officeLocation               | Location (created without an address) |
| businessPhones / mobilePhone | Business phone / mobile               |
| mail                         | Business email                        |
| employeeOrgData.costCenter   | Cost center                           |
| manager                      | Supervisor                            |

### Additional fields from the HR system

Custom fields in the HR connection can deliver further values:

| Field                               | Effect                                                                                          |
| ----------------------------------- | ----------------------------------------------------------------------------------------------- |
| `eq_upn`                            | Username (otherwise the business email)                                                         |
| `eq_business_phone`                 | Business phone number                                                                           |
| `eq_overwrite_cost_center`          | Cost center code; created if needed                                                             |
| `eq_overwrite_location`             | Replaces the location name from the HR system                                                   |
| `eq_metadata_1`, `eq_metadata_2`, … | Values under "Further information" on the employee (overwrites manual changes to these entries) |

For an individual field mapping, contact [Support](/dokumentation/help/support.md).

## Frequently asked questions

**How quickly do changes from the HR system appear?**

At the latest with the next regular synchronization (every 3 hours) or immediately after "Start synchronization now".

**Can I change synchronized data in equipme?**

No, you change synchronized fields in the HR system. You continue to maintain non-synchronized fields, roles and permissions in equipme.

**What happens if I delete the integration?**

The synchronization ends; all data taken over so far is retained and can be edited in equipme again.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://hub.equipme.io/dokumentation/organization/hr-sync.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.