Overview

This guide is for teams moving their HRIS and payroll integrations from Merge to Finch. It covers what carries over, what your engineering team will need to change, the technical differences between the two APIs, and how Finch's implementation team supports you through the switch.

At a glance

• What stays the same: The basic pattern is the same: an embedded auth modal, one token per employer connection, normalized employee data, daily syncs, webhooks, and a passthrough option for non-standard data. Teams that already built a provider-agnostic adapter for Merge can usually plug Finch into it.

• What changes: Each employer has to reconnect through Finch Connect. Custom field mappings need to be rebuilt. Multi-entity employers need per-entity requests. Employment status values and webhook event names are different, and rate limits need to be planned for.

• Support model: You get a dedicated Implementation Engineer through go-live and migration, then a Developer Success Engineer and an Account Manager for the long term.

What stays the same

Most of the integration mechanics map one-to-one. Think of it like plugging Finch into your existing generic sync adapter you already built to support Merge.

Quick reference links:

Authentication Guides ​

Provider Network

Field Support

What needs to change on the technical side:

1. Rebuild custom field mappings

This was the largest source of migration work. Employers who relied on Merge Field Mappings, for example to filter or sort employees by a custom attribute, need those mappings recreated against Finch data. Finch doesn't automatically bring Merge mappings over.

• Inventory first: Before migrating, list every employer with custom mappings, along with the fields and providers involved. Share the list with your Implementation Engineer so Finch can help coordinate.

• Check the standard model: Many "custom" fields are already in the Finch data model. Examples include preferred_name, department, manager, location, and employment.subtype.

• Employment custom fields: /employment returns a custom_fields array of name/value pairs where the provider supports it. Custom fields aren't available on assisted connections.

• Request Forwarding: For data outside the Finch model, Request Forwarding (POST /forward) sends a request to the provider's own API using the employer's Finch credentials. Finch doesn't transform these requests or responses, so you own the parsing and mapping. It's available on Pro and Premier plans, and supports a specific list of providers.

• Run in parallel: Even employers with no Merge mappings may need new ones, because default field coverage differs between the two platforms. Test both cases.

2. Handle multi-entity employers

Some employers have several entities in one payroll system, such as EINs, company codes, or divisions. Finch represents these with multi-entity mode:

• The token exchange returns one access token and a list of entity_ids.

• Every request on a multi-entity token needs an entity_ids query parameter, and you can pass only one entity at a time. If you leave it out, the request fails with entity_id_required. Single-entity tokens don't need the parameter.

• Request each entity separately and combine the results in your app. /introspect lists the entities and their status.

• If an employer selected the wrong entities, a re-authentication session lets them update their selection.

3. Update employment status and termination logic

• Finch returns an explicit employment_status (active, leave, onboarding, prehire, retired, deceased, terminated), plus is_active, start_date, and end_date.

• Merge marks terminated employees with an employment_status of INACTIVE and a termination date.

• Parsing logic written for Merge may not filter out Finch's terminated status.

4. Map names and other defaults deliberately

Check that each field means the same thing on both platforms. For example, one customer changed their mapping to use preferred_name first and fall back to the legal first name, to match what their product showed under Merge. Use a parallel run to compare outputs field by field.

5. Update webhook handling

• Initial and recurring syncs send different job events: job.initial_data_sync_*.succeeded for the first sync and job.data_sync_all.completed for later ones. Handle both.

• Data-change webhooks (employment.updated, individual.updated, and so on) contain IDs only, not the changed record. Use them to decide which connections need a refresh, then fetch the updated records.

• Verify the Finch-Signature header on every webhook.

• Use account and job webhooks to confirm on your side that every connection the Dashboard shows as successful also shows up correctly in your app.

6. Design for Finch rate limits

Finch rate limits apply:

• Use the batch endpoints (/individual, /employment) and add client-side throttling that backs off before you get a 429.

• Finch's rate limits assume you refresh data when it changes, not that you pull a full sync for every connection every day. Data-change webhooks let you skip connections with no changes.

• Request Forwarding calls add to your request volume, so include them in your capacity planning.

• If your product needs every connection synced in a tight window, such as overnight before a 9 AM send, raise this early with your Implementation Engineer.

7. Build a re-authentication flow that doesn't disconnect

When a connection needs reauthentication, for example after a 401 or an expired provider credential, send the employer through POST /connect/sessions/reauthenticate. Don't disconnect and start over. Re-authentication keeps the same connection_id and issues a new token.

Technical difference: normalized data vs. raw payloads

This is the biggest conceptual change for teams coming from Merge.

• Merge: Merge can return a remote_data array next to its normalized Common Model fields. The array holds the provider's original, unnormalized response for each underlying API path. Merge Field Mappings depend on remote_data, and teams can browse the raw payload to find and map fields themselves.

• Finch: Finch returns the normalized Finch data model only. There's no full raw provider response in standard API responses. Finch handles provider-specific parsing, normalization, and quirks, so your code works against one consistent schema across providers.

• When you need something outside the model: Use employment custom_fields where supported. Use Request Forwarding for providers on the supported list, which returns the provider's own response for you to parse. Or ask your Implementation Engineer to confirm whether Finch already supports the field or can add it.

What this means in practice: Your engineers write less provider-specific code, but you can't self-serve every raw field the way remote_data allowed. Teams with many custom mappings should inventory them early and work through them with Finch before migrating those employers.

Operational considerations:

1. Every employer reconnects through Finch Connect

Existing Merge connections don't carry over. Each employer completes Finch Connect, and your app exchanges the authorization code for a Finch access token. Plan the employer outreach as its own workstream.

• Use POST /connect/sessions with a stable customer_id for each employer. Reuse it across retries so abandoned attempts don't create duplicate staged connections. See the Connection & Session ID guide.

• Staged sessions that were started but not completed stay visible in the Dashboard. They aren't billable.

• Link to Finch's provider-specific authentication guides from your own help center, especially for your highest-volume providers. Finch Connect also shows in-modal instructions when an employer needs to take an extra step.

2. Plan for assisted integrations

Finch offers integrations to providers that have no API available through Finch Assist. If you plan to use assisted integrations, you should plan for:

• Pass manual: true when you create the Connect session, or assisted providers won't appear in Finch Connect. This flow also has to be enabled for your application.

• Data refreshes every 7 days instead of every 24 hours. There's a one-time setup period before data is available, and data endpoints return 202 until it's ready.

• Custom fields and on-demand syncs aren't supported.

• Set up email forwarding early. Finch requires it for assisted connections so the connection stays authenticated, and it often takes longer to set up than teams expect.

Recommended migration plan

Phase 1: Plan and inventory

• Export every live Merge Linked Account. For each one, record the provider, entity count, custom mappings, filters or exclusions, and any provider Finch doesn't currently support.

• Share the inventory with your Implementation Engineer. Finch checks provider coverage and custom fields, and scopes any providers that aren't supported yet. New integrations usually launch as assisted first and need a test employer account.

• Agree on success metrics, such as reliability and uptime, time to connect, and integration-related engineering tickets, so you can compare against your Merge baseline.

Phase 2: Build and validate

• Work through Finch's technical implementation checklist. It covers all the essentials for a successful integration.

• Test in the Finch Sandbox and Provider Sandbox.

Phase 3: Pilot

• Start with a small group of employers on your highest-priority providers. Prioritize migrating one provider at a time so provider-specific issues come up early and stay contained.

• Include at least one employer with no custom mappings and one with mappings.

• Your Implementation Engineer monitors these first connections on Finch's side.

Phase 4: Run in parallel and check data parity

• Keep each employer's Merge connection live until their Finch connection is verified.

• Compare synced data from both sources, recreate mappings, and preview the mapped output before switching over.

Phase 5: Full employer rollout with outreach and cutover

• Send employers their Finch Connect links in batches, and expect a spike in new connections after each send.

• Assign an owner to follow up on staged sessions that weren't completed.

• After an employer's Finch connection is verified, switch them over and remove their Merge Linked Account.

• Watch your connection count against your Finch plan as volume ramps up.

The Finch white-glove migration experience

Moving providers involves your engineering team, your customer success team, and every employer you serve, not only your code. Finch provides guided support at each stage:

• Dedicated Implementation Engineer: Your main contact from kickoff through go-live and the early migration. They run weekly check-ins, review your technical checklist, monitor your first production connections, pre-validate custom field availability, and coordinate with Finch engineering, product, and partnerships for you.

• Structured kickoff and project plan: Shared goals, success metrics, milestones, and project tracking for both teams' action items.

• Customer success enablement: Troubleshooting training for your CS team so they can quickly tell how to troubleshoot questions. Also go-to-market resources such as talk tracks/objection handling, security FAQs, and branded collateral.

• Long-term support: After implementation, a Developer Success Engineer is your ongoing technical contact and an Account Manager handles strategy and business reviews.

Questions? Contact your Implementation Engineer or Developer Success Engineer, or email developers@tryfinch.com.