503
error that looks like this:
sync-finished
webhook, as described in setting up your webhook.
page_size
query param to the maximum batching (250 elements) to minimize the number of API calls and maximize API response size.next
key in our API response and passing it in the cursor
query paramupdated_after
query parameter, which you can use in the following way:
customer_id | kombo_integration_id | kombo_last_sync_started_at |
---|---|---|
<end_user.origin_id> | personio:8d1hpPsbjxUkoCoa1veLZGe5 | 1970-01-01T00:00:00.000Z |
<end_user.origin_id> | hibob:B1hu5NGyhdjSq5X3hxEz4bAN | 1970-01-01T01:13:24.000Z |
sync-finished
webhook that looks like this: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:employment_status
property of an employee)name
of a group the employee is part of)id
: This is a unique, Kombo-specific id that is randomly generated and not present in any other systemremote_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 possiblework_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.user_id | hris_id | kombo_id |
---|---|---|
<your_user_id1> | <kombo_remote_id1> | <kombo_id> |
1234 | 1239463 | 7E2gyuv6TmvtByzBxW9Sxt53 |
sync-finished
has a data.sync_state
property that is not "SUCCEEDED"
:
sync_state | Explanation | Next Steps |
---|---|---|
SUCCEEDED | Everything went fine | |
PARTIALLY_FAILED | Succeeded with non-fatal errors | Kombo will be notified and look into the issue asap |
sync_state | Explanation | Next Steps |
---|---|---|
CANCELLED | The sync was actively canceled by Kombo | This happens very rarely, has no negative side-effects, and if it does happen, we will schedule a new sync shortly after |
FAILED | There was a critical error during the sync and the sync did not finish. | If this happens, we get an alert and will look into the issue to fix it ASAP |
TIMED_OUT | The sync timed out before completion | This happens rarely and will cause an immediate and automatic restart of the sync. Kombo will be notified and look into the issue ASAP |
integration-state-changed
webhook with state INVALID
and you / your customer will have to re-connect.
sync_state | Explanation | Next Steps |
---|---|---|
AUTHENTICATION_FAILED | The sync couldn’t complete because the API credentials are invalid or don’t allow requesting all data points in your scope | This can only be fixed by your customer adding additional permissions to the credentials or updating the credentials all-together |