Finch API Implementation Guide

Finch’s developer-friendly Unified Employment API makes implementation simple and straightforward.

1. Sign up for a free account to receive credentials and pilot how Finch works in our sandbox — a safe testing environment with mock data.
2. Integrate Finch Connect into your frontend. (Finch Connect is the user inferface that allows your customers to safely and securely grant your application access to their employment systems.) You can opt to redirect to Finch Connect or embed it directly into your application.
3. Integrate the Finch API into your application’s backend.
4. Optimize and secure your application to maintain a smooth user experience that is both efficient and protected while using Finch.
5. Once your integration has been tested thoroughly, go live with all of your customers.

​

Frontend + Backend

In a full implementation, Finch requires both a frontend and a backend application to exist. The frontend application coordinates connecting the employer’s system, and the backend server securely manages the requests and responses to and from Finch APIs.

​

Frontend User Interface

Before being able to pull data from an employment provider through Finch, your customer needs to consent to the data being transferred. Without consent, Finch is not authorized to pull the data on behalf of the customer. Finch Connect is our user-facing product to help you obtain customer consent, and it is a prerequisite step before calling Finch APIs.

There are two ways to integrate Finch Connect into your application’s frontend user interface.

1. Your application can embed Finch Connect using our various frontend SDKs. Embedding Finch Connect allows your customer to remain on your application’s domain during the entire connection process.
2. Your application can redirect to Finch Connect from the customer’s browser. In this case, Finch Connect is securely hosted by Finch on https://connect.tryfinch.com instead of your application. After completion, they will be redirected to a URI that you specify.

​

Backend Security

Finch takes security seriously, so we require a backend server to manage all requests and responses to and from Finch APIs. Once the connection has been created via Finch Connect, you can obtain an access_token which will be used to call the Finch APIs. We offer several backend SDKs to make the backend integration smoother.

We require a backend for several reasons:

1. Since the data from payroll providers is sensitive, making API requests from the backend and storing that data on the backend reduces the likelihood of this data being exposed to malicious persons.
2. Exchanging the authorization code for an access_token should always take place in your backend to ensure your client_secret and access_token are never publicly exposed.
3. Likewise, your backend should always store the access token in a secure database and should never return the access token to the frontend application.