If you have followed the Implementation Guide completely, your application is ready for deployment. The following checklist is focused list of recommendations to validate that your application is ready for deployment. This will ensure a seamless experience for your customers, make your integration more robust and secure, and set you up for success when you launch into production.

Integrate Finch Connect

Finch Connect is the frontend user interface that allows your customers to safely and securely grant your application access to their employment systems. The following steps will optimize your integration to increase conversion, improve your user experience, and avoid common configuration errors.

  • Define the list of product scopes your application needs to request to onboard an employer.
  • Integrate Finch Connect into your application’s frontend. Finch Connect should be displayed as a part of your onboarding flow, preferably behind an authentication login.
  • Exchange an authorization code for an access token without any human intervention.

Design a seamless onboarding experience

Support customer with multiple connections

  • Some of your customers may use multiple employment systems for various reasons. Your application should be able to handle multiple connections per customer.

Configure authentication methods

Integrate Finch API

Given the nature of the underlying systems the Finch APIs are built on top of, the following steps are recommended to build a resilient integration.

Send API requests

Handle API responses

  • Most data points returned by the API are nullable. This is because employers can intentionally or unintentionally leave fields blank in the employment system; Finch merely returns what is in the employment system as is. You must ensure your application is resilient to null fields showing up in unexpected ways.

Handle response headers

  • Finch syncs data with providers on a scheduled cadence, and the status of the data we return is available in the API response headers. Ensure your integration checks these response headers as needed.

Handle error responses

Your application should expect and handle errors from the Finch API.

There are three important errors your application should be aware of.

  • Ensure there are user flows built to support reauthentication, i.e. when your user needs to go through Finch Connect again to reconnect their employment system if their initial connection has stopped working.
  • Implement the troubleshooting tips to gracefully handle server_errors from Finch.
  • If you use our batch endpoints, ensure your application handles errors returned in the batch format.

Support users with custom setups

  • Some of your customers may use multiple employment systems. This will involve application logic and database schema considerations on your end.


The data stored within your customers’ systems are sensitive and should be handled using best security practices.

  • Store your client_secret in a backend data store. It should never be exposed client-side. It is recommended to store it encrypted.
  • Since your client_secret should remain on the backend, you should always perform an authorization code for an access_token exchange only on your back-end server and never on the client-side.
  • Save access_tokens in a backend data store against the users of your application. It should never be exposed client-side. It is recommended to store them encrypted.

Storage and Logging

Storing and logging key identifiers will ensure a faster turnaround time when contacting Support about issues.

  • Each Finch access_token is associated with a static Finch company_id. You can find the id using the /introspect endpoint. Save this in your data store alongside the access token and use it when contacting Finch Support about an issue.
  • Each Finch API response returns a Finch-Request-ID in the headers. Reference this ID when contacting Finch Support about an issue.

Auth Fallback and Email Forwarding

  • Email forwarding to Finch allows you to provision a custom email address for some API integrations. Contact your Development Success Representative or send an email to developers@tryfinch.com to get started.

  • With email forwarding set up, ask our team to opt in to authentication fallback to allow your customers better ability to authenticate through Finch Connect. This feature is only available to Scale tier customers.

Test your Finch integration and going live

Before going live, it is valuable to know the options available for you to test your Finch integration. Below are our suggested steps:

  • Use the Finch Sandbox to test your integration against mock data.
  • Some employment systems like Bamboo HR, TriNet HR Platform (fka Zenefits), and Gusto allow you to sign up for free demos. You can use these accounts to test against a real employment system.
  • If your application requires write operations, send our team a message on Slack or developers@tryfinch.com.

Once you have tested your Finch integration with test accounts, you can go live.

  • Start small with a few, trusted customers.
  • Once your integration works as expected, launch the integration for all of your customers.


The following steps will ensure you and your team is set up for success once your Finch integration has gone live.

  • You can contact Finch Support any of three ways: submit a ticket in the Finch Support Portal, an email to developers@tryfinch.com, or @Finch Support if you have a shared Slack channel with Finch.
  • Learn how to use the Finch Developer Dashboard to keep track of your connected customers and the health of each connection.

Learn more