​

Implement Finch Connect

​

Create a Finch Developer Dashboard Account

• Create a Developer Dashboard account to receive credentials and pilot how Finch works in our sandbox — a safe testing environment with mock data.

​

Integrate Finch Connect Into Your Application

• Integrate Finch Connect into your onboarding flow, preferably behind an authentication login.
• Include all product scopes in the Finch Connect url parameters.
• Enable SSN Field If you are using SSN make sure to include that in the Product Scope and confirm with your DSE or developers@tryfinch.com that it is enabled.

​

Retrieve an Access Token

• Exchange an authorization code for an access token without any human intervention.
• Set up a secure process with your backend application to store the access token that you exchange the authorization code for.

​

Test With Sandboxes

​

Develop Your Test Plan

• Develop a test plan that includes testing against a real employment system and the Finch Sandbox.

​

Provider Sandboxes

• Test against a real provider system using their sandbox environment.

​

Finch Sandbox

• Create connections in the Finch Sandbox to test your integration against mock data.

​

Build Backend Application

​

Backend Security

• 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.

​

Store Tokens

• 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.

​

Disconnect Tokens

• Implement a way to internally use the /disconnect endpoint to disconnect a user’s employment system from your application. Ensure that all teams that will be managing the Finch integration can easily disconnect tokens or know the process to request a disconnect.

​

Mitigate Errors

• Handle null values in the API responses.
• Handle 202 response codes from the Finch API.
• Integrate an external rate limiter into your application that respects the Finch API rate limits.
• Implement the troubleshooting tips to gracefully handle server errors from Finch.
• 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.

​

Monitor Usage

• Store connection_id alongside the access token and use it when contacting Finch Support about an issue.
• Log the finch-request-id for every response, whether successful or unsuccessful.

​

Control Access

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

​

Manage Connections

• Identify if your application needs to handle multi-account, multi-provider, or multi-entity scenarios and implement the necessary logic as needed.

​

Make Finch API Calls

​

Read Organization and Payroll Data

• Use response headers to determine the status of the data returned.
• Handle errors and edge cases in the API response.
• Handle 401 re-authentication errors.
• Handle 202 response codes.
• Manage rate limits.

​

Batch Requests

• For batch endpoints (/individual, /employment, /pay-statement), send multiple ids in a single request to the Finch API to reduce the number of requests your application makes.
• Ensure your application handles errors returned in the batch format.

​

Write Payroll Deductions & Contributions

• Verify field support for deductions and contributions.
• Understand the difference between Automated and Assisted Deductions.
• Create a plan to handle failures.
• Create a schedule for submitting deductions and contributions requests based on the General Deductions Schedule

​

Integration Preparation

​

Email Forwarding

• Set up email forwarding for ADP WFN and Assisted Connections.

​

Manage Integrations

• Use the Preview in Connect feature of the Integrations tab to preview what your employers will see for each provider in Finch Connect.
• Verify provider and field support and disable providers and authentication methods that do not meet your requirements.

​

Configure Auth Methods

• Set up preferred authentication methods for your customers.
• 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 customers on a Pro or Premier plan. Email forwarding must be set up.

​

Security Reviews

• Initiate security reviews for Gusto and TriNet.

​

Deploy and Manage

​

Increase Employer Adoption

• Introduce Finch Connect as the default method of connecting and explain the value the employer is receiving by connecting their employment system.
• Display messaging to your customer prior to launching that explains that they will be prompted to connect their payroll or HRIS system with Finch and offers an explanation for what type of data your app will collect and why.
• Add visual clues to show when the employer’s data import is complete.

​

Support

• Create an account in the Finch Support Portal for submitting and tracking tickets and to gain access to additional resources.

​

Go Live!

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.

​

Learn more

• Product Permissions
• Finch SDKs