Sync API
Learn how to use and implement Sync API in your app.
Usage
The Sync API and Permissions API authorize with a Paragon User Token. Add this token to the Authorization header of your requests to the Sync API or Permissions API:
For testing purposes, you can use our Hosted Demo Environment to generate and copy a Paragon User Token in your browser that you can use with Managed Sync.
Required audience claim in token
Ensure that your Paragon User Token includes an aud
claim with your Paragon instance hostname and Project ID. While not required for other Paragon APIs, the aud
claim is required for Managed Sync.
If you are using your existing Paragon User Token, update your JWT generation code to include the aud
claim with your Paragon instance hostname and Project ID.
See code examples of encoding your JWT using your project’s Signing Key in the Connect SDK documentation.
Sync Lifecycle
After you Enable a Sync for one of your users, Syncs run through the following lifecycle:
- Initial sync: When the sync is first enabled, Paragon will pull all data from the integration (limited by any sync-specific filters) and index the records for later retrieval and change detection.
- You will receive a
sync_completed
webhook when the initial sync is complete. - The Sync status will have an
IDLE
status and alastSyncedAt
timestamp when the initial sync is complete.
- You will receive a
- Incremental syncs: After the initial sync, Paragon will check periodically for changes to the data.
- When records are created or updated, you will receive
record_created
orrecord_updated
webhook events with metadata about the affected records. - The frequency of incremental syncs is every minute by default, but can vary by integration. See integration-specific details in Integrations Reference.
- When records are created or updated, you will receive
- Periodic full sync: Every 24 hours, Paragon will perform a full refresh of your users’ data to detect any content drift or deletions that are not visible by incremental syncs.
- After a periodic full sync runs, you may receive a batch of
record_deleted
webhook events for content that is no longer accessible by the Sync (meaning that the record was deleted or unshared from the connecting account).
- After a periodic full sync runs, you may receive a batch of
Implementing Sync API
To implement Sync API in a production context, your application will need to handle initial and incremental sync phases, as illustrated below:
Initial sync:
- Enable the sync for a user.
- Poll the Sync API to check on the status of the sync or wait for a
sync_completed
webhook. - Paginate through the records in the sync and pull them into your database or RAG pipeline.
Incremental syncs:
To handle ongoing updates, you can either:
- Poll the Sync API for new or updated records, using the
cursor
property to get records synced after the last record you pulled. - Wait for
record_created
andrecord_updated
webhooks to trigger when new or updated records are available.