> ## Documentation Index
> Fetch the complete documentation index at: https://help.honestly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How do I import employees via the REST API?

> Connect the REST API integration to import your active employees into Honestly from your own HR system and keep them in sync.

[Go to Integrations ↗](https://webapp.honestly.de/app#/integrations) · Opens the webapp — please log in first

The REST API lets you send your active employees to Honestly. They run through the same import engine as every other employee source, so the REST API is the programmable alternative to the CSV import over SFTP. Instead of uploading a file, your HR system pushes the employees directly whenever something changes.

This article is for HR admins and their IT, who set up the import. The full technical description of the interface is in the [API documentation](/developers/api-reference/employee-import).

Only admins can see and manage the integrations page.

### Connect the integration

1. Go to **Settings → Integrations** and open the **REST API** card.
2. Click **Connect**. Honestly generates an **API Key**.
3. Copy it with **Copy key** and store it in the system that pushes your HR data. Then confirm with **I have copied the key**.

<Note>
  The **API Key** is shown only once. If it is lost, open the card via **Edit** and use **Rotate key** to generate a new one. The old key becomes invalid immediately.
</Note>

The same dialog shows the **Endpoint** and the note that authentication uses the **X-Api-Key** header. The key from this integration may only write employees; it cannot read any data through the Export API. Conversely, the read keys created on the API keys page do not work here.

### How the import works

Every request carries the **complete list of your active employees** — it is a snapshot, not an addition to your existing employees. This means:

* Employees you send are created or updated.
* Employees you stop sending are offboarded, meaning removed from your active employees — but only those that were created via the REST API.

Employees created manually, via Excel, via SFTP-CSV, or through an HCM connector are left untouched by this import. The **Source** column in your employee list shows where each entry came from; see [Check import source](/help/employees/check-import-source) for more.

### The deletion threshold

So that a faulty transfer cannot accidentally remove a large part of your workforce, the connect dialog has a **Deletion Threshold**.

An import that would delete more than this share of the employees imported via the REST API is cancelled in full and changes nothing. The default is 20%; you can adjust the value in the dialog.

<Warning>
  Raise the **Deletion Threshold** only for a planned mass offboarding, and set it back afterwards. At a very high value almost nothing is protected: a broken request can then offboard your entire workforce.
</Warning>

### REST API or CSV/SFTP?

Both paths run through the same import engine and follow the same snapshot principle. The difference is in how the data is transferred:

* **REST API** — your HR system pushes the employees directly whenever something changes.
* **CSV over SFTP** — you drop a file that is read in at fixed times. See [Sync with HR system](/help/employees/sync-hr-data).

Only one employee source can be active at a time. While another connection — CSV/SFTP or an HCM connector — is connected, the **REST API** card cannot be connected. Disconnect the existing one first.

For **SAP SuccessFactors** there is no direct connector. The connection therefore runs either over CSV/SFTP or over the REST API.