Syncing Data

When syncing data with Merge, we recommend a combination of webhooks and polling.

Save your users’ account token via Merge Link or webhook
You can get the account token from the normal linking process for an embedded Merge Link. Learn more in our embedded Merge Link guide.
You can also use the Linked Account linked webhook to get the account token. See the example payload on the right and learn how to configure Merge Webhooks in our guide.
To authenticate your API requests to Merge, save your users' account token in your database. You will need the account token to poll for data in step 4.
Sync when Merge emits a sync notification webhook
We recommend using Common Model synced webhooks to manage sync activities at scale and for real-time events.
Whenever you receive sync notification webhooks for your selected Common Models with status DONE or PARTIALLY SYNCED, kick off logic outlined in step 3. If you only want to sync when all your data is available, wait until all webhooks have fired before moving to step 3.
Important fields
hook.event	The event type that triggered the webhook. See our webhooks guide for more information.
linked_account.id	The ID of the associated Linked Account.
data.sync_status	Handle edge cases when sync status is FAILED, DISABLED, and PARTIALLY_SYNCED. See our Help Center article on sync statuses.
data.synced_fields	The fields that have successfully synced.
Create a set of functions in your backend that are responsible for syncing data
These functions should optimally utilize the modified_after and expand query parameters when relevant.
Important: Store the time the last fetch began since data can change during a fetch. Pick up those changes during the next sync.
Query Parameters
---
GET
/{endpoint}/?modified_after={timestamp}
Only pull data that has been changed or created since your last sync.
For example, you can ask for modified_after=2021-03-30T20:44:18, and only pull items that are new or changed.
---
GET
/{endpoint}/?expand={common_model_name}
Pull multiple models that are related to each other instead of making multiple pulls for related information.
Without this query parameter, Merge just returns the id of the related model.
For example, if you are querying for candidates and also want details about associated applications , you can expand=applications , and Merge will return the actual application objects instead of just the application_ids.
Sync periodically and poll using /sync-status endpoint
Make a request to our /sync-status endpoint, which returns an array of syncing statuses for all models in a category. See API reference to learn more.
For the first ping:
• If status is PARTIALLY SYNCED or DONE , go ahead and retrieve data

• If status is SYNCING , retrieve the last_sync_start and continue pinging
For the next pings:
• If status is PARTIALLY SYNCED or DONE , andlast_sync_start is different from the initial last_sync_start , go ahead and retrieve data

• If status is SYNCING and last_sync_start is the same as the initally retrieved last_sync_start , continue pinging