Integration Types

​

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. If you need data more frequently, you can use our refresh endpoint to kick off a new ad-hoc data sync.

​

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 on our Scale plan. 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.

The table below summarizes the key differences between the automated and assisted experience:

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.

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 developers@tryfinch.com 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 finch.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 wand 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: