Integration Types

Automated Integrations

Automated integrations are Finch’s primary integration type. The employer authenticates through Finch Connect using OAuth, credentials, or an API token. Once authenticated, Finch runs an initial data sync that populates data for all requested products, then syncs with the provider on a 24-hour refresh cadence.

Assisted Integrations

Assisted integrations extend Finch’s coverage to the long tail of HRIS and payroll systems beyond the automated integration network. Finch manages the data sync with the provider on the employer’s behalf. Assisted integrations are available through Finch Assist, on the Pro and Premier plans. Assisted integrations require the employer to set up a third-party administrator in their system of record. Once the connection is established, data is refreshed every 7 days and changes are written back within 2 business days. The table below summarizes the differences between the automated and assisted experience:

	Automated	Assisted
Coverage (Read)	30+ Providers	175+ Providers
Coverage (Write)	5 Providers	20+ Providers
Request new providers	No	Yes
Default data syncs	24 hours	7 days
Write deductions	24 hours	2 business days
On-demand data syncs	Yes	No
Configuration period	None	1-2 weeks
Custom fields	Yes	No
Authentication Method(s)	OAuth, API token, or Credentials	3rd-Party Admin Credentials
Connection Monitoring	Yes	Yes
Pricing	All plans	Pro & Premier plans only

For the full list of assisted integrations, see Providers. For field support on assisted integrations, filter by Authentication Type > Assisted in Field Support. To enable Finch Assist, reach out to your Developer Success Representative.

Assisted Connect Flow

For your user

As with automated integrations, the employer authenticates through Finch Connect.Finch Connect proviedes the instructions for the employer to set up a third-party administrator user in the provider system.

For you

After Finch verifies admin permissions, a one-time configuration period follows during which you cannot read data or push changes to the employer’s system. During this period, Finch collects the requested data and sets up the weekly sync. After the initial collection, data is refreshed every 7 days.

Configuration Periods

All assisted integrations require a one-time configuration period before data is available. The configuration period depends on the product:

Product	Integration Type	Configuration Period
Organization	Assisted	2 weeks
Payroll	Assisted	2 weeks
Deductions	Assisted	1 week

A configuration period begins only after Finch verifies that the employer granted the required permissions.

Integrate the Assisted Connect Flow Into Your App

Reach out to developers@tryfinch.com to enable the Assisted Connect Flow. Then follow the instructions below.

1. Launch Finch Connect with the `manual` flag

Set manual to true when you create the Connect session so the employer sees every provider that supports assisted integrations. After the employer grants your application access, exchange the authorization code for an access_token as usual.

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

const client = new Finch({
  clientId: 'My Client ID',
  clientSecret: 'My Client Secret',
});

async function main() {
  const session = await client.connect.sessions.new({
    customer_id: customer.id,
    customer_name: customer.name,
    products: ['company', 'directory', 'individual', 'employment', 'payment', 'pay_statement'],
    manual: true,
  });

  console.log(session);
}

main();

{
  "session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "connect_url": "https://connect.tryfinch.com/authorize?session=f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

2. Handle API Responses

202 status code response With automated integrations, you can create an access_token and begin making pull and push requests immediately. However, with assisted integrations, there is a delay from when the access_token is created to when you can use it to make data requests. Until the access_token is ready for use, Finch will return an empty response from data endpoints with the HTTP status code 202 indicating the request is valid but data is still pending. When the access_token is ready, data endpoints will return data with the HTTP status code 200 as usual. Finch Data Retrieved Header Since the data is retrieved and refreshed on a periodic cadence, you may want to know the freshness of the data returned by an API call. You can use the Finch-Data-Retrieved header to get the date and time in ISO-8601 format the data was retrieved.

3. Monitor the setup and status of assisted connections

To check the status of your connected employers, use either the Connections page in the Finch Dashboard or the connection_status field on the /introspect endpoint.

{
  ...
  "authentication_methods": [
    {
      "type": "assisted",
      "connection_status": {
        "status": "pending",
        "message": "The employer has created a token, and we are waiting for access to its provider."
      }
    },
    ...
  ],
  ...
}

The connection status is one of the following:

Status	Description
Pending	The employer has created a token, and we are waiting for access to its provider.
Processing	We have received an invitation from the employer’s provider with the correct permissions and are in the process of pulling their data for the first time.
No Account Set Up	The employer has created a token, but we have not received an invitation to its system. Please instruct the employer to follow the instructions in Finch Connect to add Finch as a third-party admin.
Improper Permissions	The employer has added Finch successfully, but with improper permissions. Please instruct the employer to re-add Finch following the instructions in Finch Connect.
Connected	The connection is set up and Finch is able to access the required data.
Disconnected	All accounts for this employer have been disconnected.

How Finch Works

Integrations

Products

Implementation Guide

Developer Resources

Integration Types

Automated Integrations

Assisted Integrations

Assisted Connect Flow

For your user

For you

Configuration Periods

Integrate the Assisted Connect Flow Into Your App

1. Launch Finch Connect with the `manual` flag

2. Handle API Responses

3. Monitor the setup and status of assisted connections

​Automated Integrations

​Assisted Integrations

​Assisted Connect Flow

​For your user

​For you

​Configuration Periods

​Integrate the Assisted Connect Flow Into Your App

​1. Launch Finch Connect with the manual flag

​2. Handle API Responses

​3. Monitor the setup and status of assisted connections

Automated Integrations

Assisted Integrations

Assisted Connect Flow

For your user

For you

Configuration Periods

Integrate the Assisted Connect Flow Into Your App

1. Launch Finch Connect with the `manual` flag

2. Handle API Responses

3. Monitor the setup and status of assisted connections