Reading employees

​

Before you can read data

{
  "status": "error",
  "error": {
    "message": "The first sync of this integration didn't finish yet! You can keep polling this until you get a successful response or react to our webhooks."
  }
}

​

Getting employees

• We recommend setting the page_size query param to the maximum batching (250 elements) to minimize the number of API calls and maximize API response size.
• Our API is optimized to serve a few calls with large payloads at comparatively low latencies. That makes our API perfect for batch-requesting large amounts of data in a few seconds.
• Make sure to implement pagination, by using the next key in our API response and passing it in the cursor query param

curl --request GET \
  --url 'https://api.kombo.dev/v1/hris/employees?cursor=26vafvWSRmbhNcxJYqjCzuJg&page_size=250' \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Integration-Id: <x-integration-id>'

• Users to add: These are all of the records that, until now, did not appear in your query. They need to be inserted into your database and probably should get an invitation in case it’s the first time they are onboarded to your product.
• Users to update: These are users that already have access but were changed in any given property (e.g. changed address, bank details, etc.). Those users can just be updated in the database.
• Users to remove: These are users that you currently have in your database but that don’t show up in the API response anymore. This means you should notify the user that their access will be removed and mark them as deleted. It can happen that a user will lose access and get onboarded at a later time. Therefore you should keep track of off-boarded employees so that you can distinguish them from the ones that get access to the product for the first time. Just storing the ID in the HRIS system is a GDPR-compliant and relatively robust way to do so.

​

Fetching only updated data

1. Store the timestamp at which you start ingesting the data from the first sync in your own database. This field should probably be called something like this:

2. Every time Kombo is done syncing data, we send you a sync-finished webhook that looks like this:

{
  "id": "5gjAtURLPbnTiwgkaBfiA3WJ",
  "type": "sync-finished",
  "data": {
    "sync_id": "B89SCXXho7Yw8PGo8AKJxLn4",
    "sync_state": "SUCCEEDED",
    "sync_started_at": "2021-09-01T12:00:00.000Z",
    "sync_ended_at": "2021-09-01T12:30:00.000Z",
    "sync_duration_seconds": 1800,
    "integration_id": "personio:8d1hpPsbjxUkoCoa1veLZGe5",
    "integration_tool": "personio",
    "integration_category": "HRIS",
    "log_url": "https://app.kombo.dev/env/production/logs/C3xUo6XAsB2sbKC7M1gyXaRX"
  }
}

3. You should make a lookup in your database, finding the kombo_last_sync_started_at for this specific integration and then pass it again in the updated_after query param of the get endpoint, like this:

curl --request GET \
  --url 'https://api.kombo.dev/v1/hris/employees?updated_after=1970-01-01T00:00:00.000Z' \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Integration-Id: <x-integration-id>'

4. We will return all records that have been altered in one of the following ways:
   • property changed (i.e. employment_status property of an employee)
   • relation property changed (name of a group the employee is part of)

​

Implementing Kombo in an existing system (Matching users)

• id: This is a unique, Kombo-specific id that is randomly generated and not present in any other system
• remote_id: This is the id of the record in the “remote” system (the HRIS, e.g. Personio). The ID is always a string but the format will vary widely across tools. This is a fairly robust value to use as an identifier but it will change in case the employee is deleted and re-created in the HRIS.
• work_email: The email address of the employee. While this should be guaranteed to be unique, it could be that the email address of people changes over time (e.g. bc the email naming convention is changed john@example.com → john.d@example.com or the email domain changes john@example.com → john@new-example.com). It could also be that an employee’s work_email is added 2+ to a tool because they left a company and returned OR moved from a temporary to a full time position. You should make sure you are aware and ready to handle these cases if and when they come up.

• remote_id: if you are already storing the external ID of a user in your system, you should use this as much as possible
• work_email: the next best option is using the email to match. Please note above that emails will not always be unique and you should be ready to handle edge cases (e.g someone leaves a company and returns later on) for duplicate emails when matching. For some tools temporary workers will all have the same email making matching on work_email not possible.
• work_email but with a changed domain: there might be cases in which the email differs only by the domain. You can probably match based on the “prefix” of the email, but it’s not a 100% reliable operation and should be done cautiously.
• Edge cases:
  • In case you cannot match all employees between the API response and your own database, you should ask your user to match the remainder of the employees.
  • A possible solution is showing a UI with two sides (the new data on the left, and your current data on the right) that displays the mismatched records.
  • You should suggest a mapping based on the full name / private email of the employee but let your customer confirm that those mappings are correct.
  • If after the manual mapping, there are still some mismatched records, you should consider those employees to be removed/added to your system.

​

Handling failing syncs

{
  "id": "5gjAtURLPbnTiwgkaBfiA3WJ",
  "type": "sync-finished",
  "data": {
    "sync_id": "B89SCXXho7Yw8PGo8AKJxLn4",
    "sync_state": "AUTHENTICATION_FAILED",
    "sync_started_at": "2021-09-01T12:00:00.000Z",
    "sync_ended_at": "2021-09-01T12:30:00.000Z",
    "sync_duration_seconds": 1800,
    "integration_id": "personio:CBNMt7dSNCzBdnRTx87dev4E",
    "integration_tool": "personio",
    "integration_category": "HRIS",
    "log_url": "https://app.kombo.dev/env/production/logs/C3xUo6XAsB2sbKC7M1gyXaRX"
  }
}