How do I check sync status through the API?

Updated 4 days ago

Call Get Connectors to read each connector's link status, the result of its latest sync, its sync timing and its employee counts. Use this to show sync status and errors in your own portal.

curl --request GET \
  --url 'https://api.bindbee.dev/api/hris/v1/connectors?origin_id=<YOUR_CUSTOMER_ID>' \
  --header 'Authorization: Bearer <BINDBEE_API_KEY>'

This endpoint doesn't take the connector token as a header. To look up one connector, pass connector_token or origin_id as a query parameter. For ATS or LMS connectors, replace hris in the path.

Fields to read

Field	What it tells you
`status`	Link status: `COMPLETE`, `INCOMPLETE` or `RELINK_NEEDED`
`sync_status`	The most recent sync: `Syncing`, `Done` or `Failed`
`sync_progress`	Progress of a running sync, `0` to `100`
`last_sync_start_time`, `next_sync_start_time`	When the last sync started and when the next scheduled one starts
`total_employees`, `active_employees`	Employee counts from the last completed sync
`avg_sync_duration`	Average time a sync takes for this connector
`relink_needed_at`	When the connector's credentials stopped working

status and sync_status are independent. A connector can be COMPLETE with its last sync Failed: the credentials work, but data isn't arriving.

Getting error details

Get Connectors returns one sync_status for the whole sync, not a per-model breakdown or error text. For errors in your own systems, subscribe to the connector_sync_error webhook. Its payload includes an error object with the failure time and a summary, and the connector's status.

The per-model breakdown (which models synced, were skipped or failed, with record counts) is only in the dashboard, on the connector's Sync tab.

Subscribe to connector_sync_started, connector_synced and connector_sync_error instead of polling. Together they cover every sync state, and each event names the connector and the sync it belongs to.

Was this helpful?