---
title: "Migrate from Finch to Unified.to"
url: "https://docs.unified.to/migrate/finch"
description: "Map Finch Connect, access tokens, employer endpoints, data syncs, webhooks and request forwarding to their Unified.to equivalents."
updated: "2026-10-17T21:14:52.000Z"
---
# Migrate from Finch to Unified.to

Updated: October 17, 2026

Finch focuses on HRIS, payroll and benefits. Unified.to covers the same employee, payroll and benefit data in its [HRIS category](https://docs.unified.to/hris/overview.md), and uses the same connection and API model for more than 25 other categories, such as ATS, CRM and accounting.

Two things change the most. First, Finch issues an access token per connection, while Unified.to uses one workspace API key and puts the connection ID in the URL. Second, Finch serves reads from its most recent sync of each provider (every 24 hours for automated integrations), while Unified.to is [real-time pass-through](https://docs.unified.to/concepts/architecture.md): each request goes to the provider and returns current data, and no employee data is stored on our side.

This guide maps each Finch concept to its Unified.to equivalent. For the overall plan and checklist, see [Migrate to Unified.to](https://docs.unified.to/migrate.md).

## [Concepts](https://docs.unified.to/migrate/finch.md#concepts)

| Finch                                          | Unified.to                                                                                          |
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Connection, with a per-connection access token | Connection, with a connection ID; one workspace API key for all connections                         |
| customer\_id                                   | external\_xref                                                                                      |
| Provider (e.g. gusto, bamboohr)                | Integration type (e.g. gusto, bamboohr)                                                             |
| Products (directory, individual, …)            | [Scopes](https://docs.unified.to/concepts/scopes.md) (hris\_employee\_read, hris\_payslip\_read, …) |
| Finch Connect                                  | [Authorization component](https://docs.unified.to/concepts/embedded-components.md) or auth URL      |
| Data syncs and POST /jobs/automated            | Not needed: reads are live                                                                          |
| Webhooks                                       | [Native and virtual webhooks](https://docs.unified.to/reference/webhooks.md)                        |
| Request forwarding (POST /forward)             | [Passthrough API](https://docs.unified.to/passthrough/overview.md)                                  |

## [What changes without a sync](https://docs.unified.to/migrate/finch.md#what-changes-without-a-sync)

* **No initial sync.** Finch pulls historical data before a new connection is fully usable. A Unified.to connection can be read as soon as the user authorizes it.
* **Current data on every read.** You no longer need `Finch-Data-Retrieved` to judge freshness, or refresh jobs to get newer data.
* **Reads call the provider.** Payroll providers often have tight rate limits. If you read the same data repeatedly, keep a copy in your own database and update it with `updated_gte` or webhooks.
* **Assisted integrations.** Finch's assisted integrations are run manually by Finch's team. Unified.to integrations are all API-based. Check [Supported integrations](https://docs.unified.to/hris/integrations.md) for each provider you rely on, and [contact us](https://unified.to/contact) about any gaps.

## [Authentication](https://docs.unified.to/migrate/finch.md#authentication)

Finch requires a per-connection access token and an API version header. Unified.to needs your workspace API key; the connection is part of the URL.

```
# Finch
GET https://api.tryfinch.com/employer/directory
Authorization: Bearer {CONNECTION_ACCESS_TOKEN}
Finch-API-Version: 2020-09-17

# Unified.to
GET https://api.unified.to/hris/{connection_id}/employee
Authorization: Bearer {UNIFIED_API_KEY}

```

You'll no longer store a secret per customer, only a connection ID, which is useless without your workspace API key.

## [Authorizing end users](https://docs.unified.to/migrate/finch.md#authorizing-end-users)

Finch Connect takes three steps: your backend creates a session (`POST /connect/sessions`), your frontend opens it with `useFinchConnect`, and your backend exchanges the returned `code` for an access token (`POST /auth/token`).

Unified.to takes one: embed the Authorization component, or redirect the user to the auth URL. The user comes back to your `success_redirect` with the connection ID in the URL, and there's no code to exchange.

```
// Before: Finch Connect
import { useFinchConnect } from '@tryfinch/react-connect';

const { open } = useFinchConnect({
    onSuccess: ({ code }) => exchangeCodeOnYourServer(code), // POST /auth/token
});
open({ sessionId }); // sessionId from POST /connect/sessions

// After: Unified.to Authorization component
import UnifiedDirectory from '@unified-api/react-directory';

<UnifiedDirectory
    workspaceId={WORKSPACE_ID}
    categories={['hris']}
    external_xref={customerId}
    success_redirect="https://yourapp.com/integrations/callback"
/>;

```

Or, without a framework:

```
<script src="https://api.unified.to/docs/unified.js?wid=YOUR_WORKSPACE_ID&did=unified_widget&env=Production&cat=hris&uid=customer_123&surl=https%3A%2F%2Fyourapp.com%2Fintegrations%2Fcallback"></script>
<div id="unified_widget"></div>

```

In the embed script, `cat` limits the list to one category, `uid` sets `external_xref` (the equivalent of Finch's `customer_id`), and `surl` / `furl` set the success and failure redirects. The dashboard's **Embedded components** page generates the exact code for each framework.

If you pass `integration` to Finch Connect to send users straight to one provider, use the auth URL for that integration instead:

```
https://api.unified.to/unified/integration/auth/{WORKSPACE_ID}/gusto
    ?success_redirect=https://yourapp.com/integrations/callback
    &failure_redirect=https://yourapp.com/integrations/error
    &external_xref=customer_123
    &scopes=hris_employee_read,hris_payslip_read
    &redirect=1

```

On success, the callback URL receives `id` (the connection ID), `state`, `nonce`, `type` and `sig`. [Verify the signature](https://docs.unified.to/concepts/embedded-components.md#signature-calculation), then store the connection ID where you store the Finch access token today.

## [Moving existing connections](https://docs.unified.to/migrate/finch.md#moving-existing-connections)

Finch access tokens are issued for Finch's API and can't be used with Unified.to, so customers need to **re-authorize** through the Authorization component. You can do this gradually: send new customers through Unified.to and ask existing ones to reconnect when they next visit your integrations page, then call Finch's `POST /disconnect` for each migrated customer.

For providers where you hold the credentials yourself, such as API keys your customers gave you, **import** them with [Create connection](https://docs.unified.to/unified/connection/Create%5Fconnection.md). See [Move your connections](https://docs.unified.to/migrate.md#%5F3-move-your-connections).

## [Making API calls](https://docs.unified.to/migrate/finch.md#making-api-calls)

Finch splits employee data across several endpoints: the directory lists people, and `/employer/individual` and `/employer/employment` take batches of IDs in a POST body. Unified.to returns personal and employment details together on one employee object, so a single paginated `GET` replaces all three.

```
# Finch: list people, then fetch details in batches
curl "https://api.tryfinch.com/employer/directory?limit=100&offset=0" \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Finch-API-Version: 2020-09-17"

curl -X POST https://api.tryfinch.com/employer/employment \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Finch-API-Version: 2020-09-17" \
  -H "Content-Type: application/json" \
  -d '{ "requests": [{ "individual_id": "…" }] }'

# Unified.to: one call
curl "https://api.unified.to/hris/$CONNECTION_ID/employee?limit=100&offset=0" \
  -H "Authorization: Bearer $UNIFIED_API_KEY"

```

```
// Finch
import Finch from '@tryfinch/finch-api';

const finch = new Finch({ accessToken });
for await (const person of finch.hris.directory.list()) {
    // …then individuals.retrieveMany / employments.retrieveMany
}

// Unified.to
import { UnifiedTo } from '@unified-api/typescript-sdk';

const unified = new UnifiedTo({ security: { jwt: process.env.UNIFIED_API_KEY } });
const employees = await unified.hris.listHrisEmployees({ connectionId, limit: 100, offset: 0 });

```

### [Common objects](https://docs.unified.to/migrate/finch.md#common-objects)

| Finch                                                 | Unified.to                                                                                                              |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| GET /employer/company                                 | GET /hris/{connection\_id}/company                                                                                      |
| GET /employer/directory                               | GET /hris/{connection\_id}/employee                                                                                     |
| POST /employer/individual                             | GET /hris/{connection\_id}/employee/{id} (or the list above)                                                            |
| POST /employer/employment                             | Same employee object: title, employment\_status, employment\_type, hired\_at, terminated\_at, compensation, manager\_id |
| GET /employer/payment \+ POST /employer/pay-statement | GET /hris/{connection\_id}/payslip                                                                                      |
| GET /employer/benefits                                | GET /hris/{connection\_id}/benefit                                                                                      |
| Benefit enrollments and deductions                    | /hris/{connection\_id}/deduction                                                                                        |
| Locations and departments on the employment object    | /hris/{connection\_id}/location, /hris/{connection\_id}/group                                                           |

Finch's `payment` and `pay_statement` split a pay run from each employee's statement. Unified.to's payslip is per employee and pay period; filter it by `user_id` for one employee. Field names differ between the two models, so update your mappers object by object using the [API Reference](https://docs.unified.to/hris/overview.md).

## [Pagination and filtering](https://docs.unified.to/migrate/finch.md#pagination-and-filtering)

| Finch                                  | Unified.to                                                  |
| -------------------------------------- | ----------------------------------------------------------- |
| limit / offset on /employer/directory  | limit / offset on every list endpoint                       |
| Batched requests arrays in POST bodies | Paginated GET lists, or get by ID                           |
| start\_date / end\_date on payments    | updated\_gte on payslips (see each object's filters)        |
| entity\_ids                            | company\_id filter where the provider has several companies |

See [Pagination, filtering & sorting](https://docs.unified.to/reference/pagination.md).

## [Custom fields and raw data](https://docs.unified.to/migrate/finch.md#custom-fields-and-raw-data)

Finch returns custom fields through its own model where available. Unified.to returns the provider's original record in `raw` when you ask for it:

```
GET /hris/{connection_id}/employee?fields=id,name,compensation,raw

```

See [Custom & original fields](https://docs.unified.to/reference/fields.md).

## [Request forwarding](https://docs.unified.to/migrate/finch.md#request-forwarding)

Finch's `POST /forward` takes the method and route in the body. Unified.to's Passthrough API takes the provider path in the URL and uses the HTTP method you call it with:

```
# Finch
curl -X POST https://api.tryfinch.com/forward \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Finch-API-Version: 2020-09-17" \
  -H "Content-Type: application/json" \
  -d '{ "method": "GET", "route": "/v1/companies" }'

# Unified.to
curl "https://api.unified.to/passthrough/$CONNECTION_ID/v1/companies" \
  -H "Authorization: Bearer $UNIFIED_API_KEY"

```

Unified.to adds the provider's base URL and authentication, and returns the provider's response unchanged. See [Passthrough](https://docs.unified.to/passthrough/overview.md).

## [Webhooks](https://docs.unified.to/migrate/finch.md#webhooks)

Finch fires webhooks after each sync. Unified.to webhooks are created per connection and object, and each delivery carries the changed records.

| Finch event                                                | Unified.to                                                                  |
| ---------------------------------------------------------- | --------------------------------------------------------------------------- |
| directory.created, individual.created                      | object\_type: hris\_employee, event: created                                |
| employment.updated, individual.updated                     | object\_type: hris\_employee, event: updated                                |
| directory.deleted                                          | object\_type: hris\_employee, event: deleted, where supported               |
| pay\_statement.created, payment.created                    | object\_type: hris\_payslip, event: created                                 |
| company.updated                                            | object\_type: hris\_company, event: updated                                 |
| job.data\_sync\_all.completed, job.initial\_data\_sync\_\* | Not needed; the first delivery is marked INITIAL-PARTIAL / INITIAL-COMPLETE |

```
curl -X POST https://api.unified.to/unified/webhook \
  -H "Authorization: Bearer $UNIFIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "'$CONNECTION_ID'",
    "object_type": "hris_employee",
    "event": "updated",
    "hook_url": "https://yourapp.com/webhooks/unified",
    "interval": 60
  }'

```

Most HRIS and payroll providers don't offer webhooks, so Unified.to uses [virtual webhooks](https://docs.unified.to/concepts/virtual%5Fwebhooks.md) for them and checks for changes every `interval` minutes, rather than once a day.

**Signature verification.** Replace your `Finch-Signature` check with a check of the `sig256` field in the payload body: `HMAC-SHA256(workspace secret, JSON of data + nonce)`, base64-encoded. See [Webhooks](https://docs.unified.to/reference/webhooks.md#best-practices-for-signature-validation).

## [Disconnecting](https://docs.unified.to/migrate/finch.md#disconnecting)

Replace `POST /disconnect` with `DELETE /unified/connection/{connection_id}`.

## [Next steps](https://docs.unified.to/migrate/finch.md#next-steps)

* Follow the [migration plan and checklist](https://docs.unified.to/migrate.md#migration-plan)
* Browse [Supported HRIS integrations](https://docs.unified.to/hris/integrations.md) to confirm coverage
* Questions? Email [hello@unified.to](mailto:hello@unified.to) or join our [Discord](https://discord.gg/2nsAPmbx)
