Data Delivery

Payroll data arrives and updates in stages after a user connects an account. Choose readiness events based on the records your workflow requires.

​

Delivery order

Initial delivery begins after the user successfully authenticates the payroll account.

• Person, employment, and other information that changes less frequently is generally available first.
• Paystubs, shifts, gigs, and other time-based records are delivered from the most recent records backward.

Accounts with many records, such as gig accounts, can take longer to finish syncing. Delivery speed also depends on what the connected payroll system makes available.

​

Resource availability

Resource webhooks indicate when individual records become available:

• A resource .added event is sent when the first available record or field is delivered.
• Resource .updated events can continue while additional fields or records are delivered.
• Partial-synchronization events indicate that a configured amount of historical data is available.

Do not treat the first .added event as confirmation that every field or historical record is available.

​

Readiness webhooks

The users.fully_synced webhook is not sent when an existing account reconnects. Use account and resource webhooks for reconnection and ongoing-update workflows.

​

Multiple accounts

Track each account separately while initial data is arriving. One account can complete, fail, or require action before another account attached to the same user. Use the users.fully_synced webhook only when the workflow must wait for all newly connected payroll accounts.

​

Retrieving paystubs

Set config.days_synced when subscribing to the paystubs.partially_synced webhook to specify the number of days of paystub history you need. You can create separate subscriptions for different history windows.

1. Track the IDs of successfully connected payroll accounts using the accounts.connected webhook or the Accounts API.
2. Wait for partial or full synchronization, with a timeout appropriate for your application.
3. If the paystubs.partially_synced webhook arrives, retrieve paystubs using the account ID and the available_from / available_to dates in the webhook. Track the account and days_synced value so duplicate deliveries or different subscriptions do not count as additional accounts.
4. If the paystubs.fully_synced webhook arrives first, retrieve the available paystubs for that account. If the users.fully_synced webhook arrives first, retrieve the available records for the user’s newly connected payroll accounts.
5. Check whether the returned records meet your requirements. If the timeout expires before the required data is available, offer another method, such as Document Uploads.

When your workflow requires data from multiple accounts, track which accounts have returned the required window or completed retrieval. Do not use the number of webhook deliveries as the number of ready accounts. A completed sync does not guarantee a particular number of paystubs or that every requested field is populated. Retrieve identities separately when your application needs employment information even if no paystubs are available.

​

Example

A user connects two payroll accounts. Your application subscribes to the accounts.connected, paystubs.partially_synced, paystubs.fully_synced, and users.fully_synced webhooks.

• The first account sends the paystubs.partially_synced webhook for the requested window. Retrieve that account’s available paystubs.
• The second account completes in one pull and sends the paystubs.fully_synced webhook without a partial-sync webhook. Retrieve its available paystubs and check that they meet your requirements.
• The users.fully_synced webhook indicates that initial delivery has finished for both newly connected accounts. Later or duplicate events should update existing records rather than create duplicates.

Continue with Ongoing Refresh when your application needs new records after the initial delivery.