Integration Types

Finch automated integrations sync data from HR and payroll providers every 24 hours. For our assisted integrations, data is refreshed every 7 days.

Automated Integrations

Automated integrations are the primary integration type offered by Finch. With automated integrations, your user authenticates via Finch Connect using OAuth, Credentials, or an API token.

Once authenticated, Finch kicks off an initial data sync, which populates data for all requested products. After that, Finch will sync data with the provider on a 24 hour refresh cadence.

Assisted Integrations

Assisted integrations are a unique offering from Finch, designed specifically to help employers connect HRIS and payroll systems that are otherwise inaccessible by API.

Assisted integrations are available for customers using Finch Assist, a feature available to customers on our Pro and Premier plans. With this feature, you unlock every integration in our Provider Network and the ability to add net new integrations.

Assisted integrations require employers to set up a 3rd party administrator in their system of record. Once the connection is established, data is refreshed every 7 days and changes can be written back within 2 business days.

The table below summarizes the key 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

To see a full list of assisted integrations, see Providers.

To see field support for our assisted integrations, filter by Authentication Type > Assisted in our Field Support.

To enable Finch Assist, please reach out to your Developer Success Representative.

Assisted Connect Flow

For your user

As with our automated integrations, your user will need to go through Finch Connect to authenticate. However, instead of our standard login flow the user will follow a set of instructions to set up a new 3rd party administrator. Step-by-step instructions for each provider can be found in our Authentication Guides.

For you

Once admin permissions have been verified by Finch, there is a one-time configuration period where you will be unable to pull data or push changes to your users’ system. During this time, Finch’s product operations team will pull in the requested data and set up the weekly sync. After the initial pull, the data will be refreshed every 7 days.

Configuration Periods

All assisted integrations require a one-time configuration period before data can be retrieved. See the configuration periods for each product below.

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

Please note that configuration periods can only begin once Finch has verified that the employer has granted the required level of permissions.

Integrate the Assisted Connect Flow Into Your App

Reach out to [e-mail] to enable the Assisted Connect Flow. Then follow the instructions below.

1. Launch Finch Connect with the manual flag

Launch Finch Connect with manual=true so your user can see all providers that support assisted integrations. After granting your application access, you can retrieve an authorization code and exchange it for an access_token as usual.

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

const client = new Finch({
  accessToken: 'My Access Token',
});

async function main() {
  const createConnectSessionResponse = await client.connect.sessions.new({
	  products: ["company", "directory", "individual", "employment", "payment", "pay_statement"],
	  customer_id: customer.id, // Your internal customer ID 
	  customer_name: customer.name, // Your customer's name
	  customer_email: customer.email, // The email associated to your customer (optional)
	  integration: { // (optional)
			  provider: 'adp_run', // The provider you want to show up in connect (optional)
			  auth_method: 'credential' // The auth method of the provider to show up (optional)
	  },
	  minutes_to_expire: 20160, // How long you want the session to last for (defaults to 14 days)
	  redirect_uri: '' // The URI to redirect to for the redirect connect flow (optional)
	  sandbox: false // create a sandbox session for a sandbox app (optional)
	  manual: false // A value that, when set to true, displays both Automated and Assisted providers on the selection screen (optional) 
  });

	/**
	 * { 
	 *   "session_id": "<A unique session ID that can be used with embedded connect>",
   *   "connect_url": "<The url of the connect session for the redirect flow>"
   * }
	**/
  console.log(createConnectSessionResponse); 
}

main();

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 view the status of your connected employers, you can use either view the Connections page in the Finch Dashboard or the connection_status 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 status of the connection will be 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.