Architecture reference

How Merge works

Your app, Merge, and the third-party platform each have a role:

• Your app embeds Merge Link in the frontend, stores account tokens, and calls the Merge API from the backend.
• Merge handles authentication with third-party platforms, runs syncs on a schedule, normalizes data into Common Models, and delivers webhooks when data changes.
• The third-party platform (BambooHR, Greenhouse, HubSpot, etc.) is the source of truth. Merge reads from and writes to it on your behalf.

Our recommended integration path

This is the path we recommend for getting a Merge integration into production. Each step links to the relevant guide.

1. Connect Merge Link — Embed the Merge Link component in your frontend so your end users can authorize their integrations. This is the entry point for every Linked Account. See the Merge Link guide.

2. Set up webhooks — Register a webhook endpoint to receive sync_completed events from Merge. This tells your app when new data is available. See Webhooks.

3. Sync data — Use a combination of webhooks and polling to pull Common Model data into your app. Call endpoints like GET /hris/v1/employees?modified_after={timestamp} to fetch only what has changed. See Syncing best practices.

4. Write data back — If your integration requires creating or updating records in the third-party platform, use Merge’s write endpoints. See Writing data.

5. Handle supplemental data — For data beyond Common Models, use Remote Data, Passthrough Requests, or Field Mapping to access provider-specific fields. See Supplemental data.

6. Go to production — Switch from your Test Access key to a Production Access key, ensure Merge Link uses production link_tokens, and register your production webhook endpoint. See Authentication for key management.

Use cases

See real-world examples of what teams build with Merge across every supported category.