The initial sync
The initial sync starts the moment your end user completes authentication, however the connection was created — see How to connect. Until it finishes, reads return200 with partial data and nothing on the response says so.
You can watch its progress on the connector with Get Connectors. That endpoint scopes by a connector_token query parameter, not the usual header.
Two status fields on the connector answer different questions:
A connector can be
COMPLETE and still hold no data, because the two are independent.
The dashboard uses its own words for the same field. It shows Synced where sync_status is Done, and Partial for a run that loaded some models and failed others, which is not a sync_status value at all - see Sync status.
Rather than polling, subscribe to the connector_synced webhook. It fires when a sync job finishes successfully — the cleanest signal that a newly connected account is ready to use.
The recurring schedule
After the initial sync, a Production connector syncs again automatically, once every 24 hours by default. Nothing is required from you or your end user. The interval is configurable on request — see Sync frequency.last_sync_start_time is when the most recent job began; next_sync_start_time is when the next scheduled one will.
Every webhook payload carries a sync object identifying the job behind it, and sync_type is AUTOMATED for a scheduled run or MANUAL for one you triggered. That distinction is worth using: if you force a sync in response to a user action, you can match the resulting webhook back to that action rather than treating it as routine traffic. See Events & payloads.
Frequency bounds when data changes, not how often you can read. Call the API as often as you like within your rate limits — the data will not differ between syncs.
Development connectors
Development connectors run the same initial sync as Production ones: it starts on authorization and needs nothing from you. What they do not have is the recurring schedule that follows it. After that first run the data is frozen until you trigger a sync yourself. See Environments for everything else the two differ on.Forcing a resync
When you need data sooner than the next scheduled run — and always, in Development, after the first one:connector_synced or poll sync_status until it returns to Done.
When force sync needed:
- Your end user changed something in their HRIS and expects to see it straight away.
- You completed a write and go to the source system, so a sync has to pick them up before they are readable.
- You changed a custom field mapping and want existing records populated.
- You are investigating a discrepancy for one customer.
Triggering a job on completion
Reading on a timer instead goes wrong in four ways:- A paginated walk shifts under you mid-sync.
- Counts come back short.
- A census extract is quietly incomplete.
- A stalled connector looks identical to a quiet one.
connector_synced rather than a clock. The event names the connector and the sync job, so a handler can process exactly what finished — and pair it with modified_after to read only what that run touched, as in modified_after.
For creating the subscription, the payload shape and delivery guarantees, see Webhooks.
When a sync fails
A failed job setssync_status to Failed and fires the connector_sync_error webhook, whose payload carries an error object with the failure time and a summary.
Previously synced data stays readable throughout. A failure means your copy is stale, not missing — which is also why a broken connector does not announce itself on your reads, and has to be watched separately. See Monitor sync status for what to alert on and how to diagnose a specific failure.
If status has become RELINK_NEEDED, the credentials themselves stopped working and your end user must reconnect before syncing resumes — see Connections to relink.
Related
Sync frequency
How often a connector syncs, and how to change it.
Force Resync a Connector
API reference for triggering a sync on demand.
Webhooks
Sync and data-change events, payloads, and delivery.
Monitor sync status
What to track, and what to do when a sync fails.