Assisted Flow

Assisted API Connections is our semi-automated product that expands coverage to 70+ more providers. In contrast to our Automated API Connections, the data for Assisted API Connections is refreshed periodically. Our full list of coverage — for both Automated API and Assisted API providers — can be found here.

Contact our team at developers@tryfinch.com to get started or for more questions regarding pricing, supported providers, etc.

How Assisted Connect Flow works

For your user

As with our automated integrations, your user will need to go through Finch Connect. However, instead of our standard login flow, the user will need to follow a set of instructions displayed on Finch Connect to manually connect your application to their employment system.

For you

Unlike our automated integrations, you will not be able to make API calls to pull data and push changes to your users' systems immediately. Instead, you will have to wait until your user manually connects their employment system followed by a predetermined number of days for the Finch team to pull in the data. After the initial pull, the data will be periodically refreshed.

The current refresh times are below:

Initial connections with pay data require additional enablement work. For assisted providers which are alreadypay-enabled*, the initial connection time will still be our standard 14 days. For new assisted providers which are not pay-enabled, the initial connection time will be six weeks. Please see our Assisted API Providers page for more information about which providers are currently pay-enabled.

Integrating Assisted Connect Flow into your application

Launch Finch Connect with the manual flag

Launch Finch Connect with manual=true so your user can view all the Assisted API providers Finch supports. After granting your application access, you can retrieve an authorization code and exchange it for an access_token as usual.

https://connect.tryfinch.com/authorize?
&client_id=<your_client_id>
&products=company directory individual employment payment pay_statement
&redirect_uri=https://example.com
&manual=true

<!-- theme: info -->

For Assisted API Providers on Finch Connect, your users will see instructions on how to manually connect their employment systems to Finch and your application.

Handle API responses correctly

202 status code response

With Automated API Providers, you are able to create an access_token and immediately use it to pull in data or push changes to your users' systems. However, with Assisted API Providers, there is a short delta from when the access_token is created to when you can do anything with it.

Until the access_token is ready for use, Finch will return an empty response with the HTTP status code 202 indicating the request is valid but the processing is pending. When the access_token is ready, API calls 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.

Monitoring the status of your Assisted API Connections

To view the status of your connected employers, you can use the Finch Developer Dashboard and navigate to the Employers tab on your application's page.