Skip to main content
Go to 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. 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.
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.
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 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.
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.

​
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.
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.