:root {
  --finch-purple: #3E4AE7;
  --finch-purple-dark: #7A84FF;
}

#table-of-contents:empty {
  position: absolute;
}

:is(.prose a):not(.dark .prose a):not(:where([aria-label="Navigate to header"])) {
  color: var(--finch-purple);
  border-bottom: 1px solid var(--finch-purple);
}

:is(.dark .prose a):not(:where([aria-label="Navigate to header"])) {
  color: var(--finch-purple-dark);
  border-bottom: 1px solid var(--finch-purple-dark);
}


Request Headers

Response Headers

Changelog

API Status

Finch

API Reference

Sign In

Sign Up

Headers

This API Quickstart guide will help you send your first request to Finch, the unified API for HR and payroll.

Quickstart

The Finch API powers integrations to employment systems through a single, standardized data model.

What is Finch?

Finch Connect is an embedded onboarding flow that enables employers to connect their HR or payroll system to your app.

Connect an Employer

Use this glossary to familiarize yourself with employment terminology used in Finch's documentation and API reference.

Glossary

Unified Employment API Glossary

Finch automated integrations sync data from HR and payroll providers every 24 hours. For our assisted integrations, data is refreshed every 7 days.

Integration Types

Find a list of every HRIS and payroll system supported by Finch

Provider Network

Explore coverage across all providers for your use case.

Field Support

Learn about provider-specific instructions required for initial integration setup and deductions setup.

Provider Setup Instructions

Read company and employee data from employment systems with Finch's Organization APIs.

Organization

Dig into the details of each company payment and employee pay statement with Finch's Payroll APIs.

Payroll

Manage the full lifecycle of deductions and contributions for employers with Finch's Deductions APIs.

Deductions

Retrieve data from employee and employer documents via Finch’s Documents APIs. Now in Beta and supported for W-4 files.

Documents

 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.  <br /> <br /> Use this Implementation Guide and Go Live Checklist to set up your frontend and backend applications. You will sign up for a Finch Account, set up Finch Connect, integrate the Finch API, and go into production.

Go Live Checklist

Create your Finch Developer Account, recieve your application credentials, and pilot how Finch works in our sandbox environment.

Create a Finch Developer Account

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. 

Integrate Finch Connect Into Your Application

In this guide, you’ll exchange the authorization code for an access token. Access tokens are required for making API requests to Finch endpoints.

Retrieve Access Token

In this guide, you'll build a robust testing, validation, and maintenance plan for your Finch API integration to improve reliability, accuracy, and performance.

Develop Your Test Plan

Use Provider Sandboxes to test up to 5 connections with live providers for free. Test with Gusto, Deel, Hibob, BambooHR, TriNet HR Platform (fka Zenefits), and more.

Provider Sandboxes

Use the Finch Sandbox to generate mock connections with Finch providers, see which fields are supported, and configure the data for unique testing scenarios.

Finch Sandbox

You can utilize three different environments to test your integration with Finch: Sandbox, Development, and Production. Each has specific uses and limitations.

Environments

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](/developer-resources/SDKs#backend-sdks) to make the backend integration smoother.

Backend Security

***Finch requires developers to store tokens on the backend server for improved security controls***. To reduce the likelihood of unitentional exposure of employer access tokens or other private information, you'll need to ensure all access tokens are stored securely.

Store Tokens

Learn how Finch defines connections, and how to safely disconnect all access tokens associated with a connection if needed.

Disconnect Tokens

In this guide, you'll learn how to identify and mitigate common errors such as server errors, reauthentication errors, and rate limit errors.

Mitigate Errors

In this guide, you'll find best practices for monitoring your application's usage of Finch to identify patterns and potential issues.

Monitor Usage

Learn how to control data access within multi-tenancy applications through role-based access control (RBAC) or other authorization methods.

Control Access (Optional)

In this guide, you’ll learn how to define and manage multi-account, multi-provider, and multi-entity connections based on your customers’ needs.

Manage Connections

In this guide, you'll learn how to read data from Finch's company, directory, individual, employment, payment, and pay statement API endpoints.

Read Organization and Payroll Data

Learn how to monitor your application’s usage of Finch APIs, optimize your requests, and handle rate limits and errors.

Batch Requests

In this guide, you'll learn how to write deductions and contribution changes to Finch's benefits API endpoint.

Write Payroll Deductions & Contributions

Set up email forwarding for ADP Workforce Now and Assisted Integrations.

Email Forwarding

Customize the list of Providers your customers see in Finch Connect. Validate field support for each provider you plan to use, and disable any that don't fit your use case.

Manage Integrations

Learn more about the four authentication methods offered by Finch -- OAuth, Credentials, API token, and Assisted.

Configure Auth Methods

Some providers require security reviews to ensure that your application is secure and compliant with our standards. Please identify any providers that require a security review and initiate that process with Finch. 

Security Reviews

Explore our best practices for optimizing employer adoption and conversion in Finch Connect.

Increase Employer Adoption

We have a range of resources available to help you get started with Finch, including our [API Reference](https://developer.tryfinch.com/api-reference/organization/company), [Documentation](https://developer.tryfinch.com/how-finch-works/quickstart), and [Support Center](https://support.tryfinch.com/hc/en-us). Additionally, our Technical Support team is here to help you with any questions you may have about our products. If you have any questions or need help with your integration, please don't hesitate to get in touch with us. We're here to help!

Get Support

Explore our frontend and backend SDK repositories. Finch supports SDKs in JavaScript, React, Node, Python, Java, Kotlin, and Go.

SDKs

Get notified when data has changed with Finch Webhooks. You can create, test, and manage Finch Webhooks in the Developer Dashboard.

Webhooks

Finch Request Forwarding is a passthrough API feature that enables you to issue raw requests directly against an employment system’s API.

Request Forwarding

In this guide, you'll learn about data sync cadences and batch requests. Finch syncs data on a 24-hour or 7-day cadence depending on the integration type.

Data Syncs

Learn what to do if Finch returns a 401 Unauthorized HTTP status code error with a 'finch_code' of 'reauthenticate_user' when a connection fails. 

Reauthentication

Learn how to reconcile employee profiles in Finch using PII such as full name and date of birth (DOB), email, or SSN.

Reconcile Employees

In this guide, you'll learn how to enable the social security number (SSN) field in Finch. The SSN field must be explicitly authorized by the employer.

Enable Social Security Number (SSN) Field

Learn how to calculate year-to-date (YTD) gross wages for individual employees using data returned from Finch Organization endpoints.

Calculate Year-To-Date (YTD) Wages

Finch's data can be used to run an individual's W-2 Box 1 calculation using data returned from Finch Pay endpoints.

W-2 Box 1

Learn how to classify Contributions and Deductions retrieved from the Finch Payroll endpoints.

Pay Statement Type Classification

Explore Finch developers' most frequently asked questions (FAQ) and answers. Topics include Products & Integrations, API & Data Model, Security, and more.

Finch Developer FAQs

Company

Read company directory and organization structure

Individual

Read individual employment and income data

Employment

Read payroll and contractor related payments by the company.

Payment

Read detailed pay statements for each individual.

Deduction and contribution types are supported by the payroll systems that supports Benefits.

Pay Statement

Get All Pay Groups

Get Pay Group

List all company-wide deductions and contributions.

Get All Deductions

Register existing benefits from the customer on the provider, on Finch's end. Please use the `/provider` endpoint to view available types for each provider.

Register Deduction

Creates a new company-wide deduction or contribution. Please use the `/providers` endpoint to view available types for each provider.

Create Deduction

Lists deductions and contributions information for a given item

Get Deduction

Updates an existing company-wide deduction or contribution

Update Deduction

Lists individuals currently enrolled in a given deduction.

Get Enrolled Individuals

Get enrollment information for the given individuals.

Get Deductions for Individuals

Enroll an individual into a deduction or contribution. This is an overwrite operation. If the employee is already enrolled, the enrollment amounts will be adjusted. Making the same request multiple times will not create new enrollments, but will continue to set the state of the existing enrollment.

Enroll Individuals in Deductions

Unenroll individuals from a deduction or contribution

Unenroll Individuals from Deductions

**Beta:** This endpoint is in beta and may change.  
Retrieve a list of company-wide documents.


List Documents

**Beta:** This endpoint is in beta and may change.  
Retrieve details of a specific document by its ID.


Get Document

Create a new connect session for an employer

Create a new connect session

Create a new Connect session for reauthenticating an existing connection

Create a new Connect session for reauthentication

Exchange the authorization code for an access token

Create Access Token

Return details on all available payroll and HR systems.

Providers

Read account information associated with an `access_token`

Introspect

Disconnect one or more `access_token`s from your application.

Disconnect

The Forward API allows you to make direct requests to an employment system. If Finch’s unified API
doesn’t have a data model that cleanly fits your needs, then Forward allows you to push or pull
data models directly against an integration’s API.

Get all automated jobs. Automated jobs are completed by a machine. By default, jobs are sorted in descending order by submission time. For scheduled jobs such as data syncs, only the next scheduled job is shown.

List All Automated Jobs

Enqueue an automated job. 

`data_sync_all`: Enqueue a job to re-sync all data for a connection. `data_sync_all` has a concurrency limit of 1 job at a time per connection. This means that if this endpoint is called while a job is already in progress for this connection, Finch will return the `job_id` of the job that is currently in progress. Finch allows a fixed window rate limit of 1 forced refresh per hour per connection.

`w4_form_employee_sync`: Enqueues a job for sync W-4 data for a particular individual, identified by `individual_id`. This feature is currently in beta.

This endpoint is available for *Scale* tier customers as an add-on. To request access to this endpoint, please contact your Finch account manager.

Enqueue a New Automated Job

Retrieve an Automated Job

Get a manual job by `job_id`. Manual jobs are completed by a human and include Assisted Benefits jobs.

Retrieve a Manual Job

Create a new connection (new company/provider pair) with a new account

Create a new Sandbox Connection

Create a new account for an existing connection (company/provider pair)

Create a new sandbox account

Update an existing sandbox account. Change the connection status to understand how the Finch API responds.

Update a sandbox account

Get configurations for sandbox jobs

Update configurations for sandbox jobs

Add a new sandbox payment

Update sandbox individual

Update sandbox employment

Add new individuals to a sandbox company

Update a sandbox company's data

Enqueue a new sandbox job

Permissions

API Versioning

In this guide, you'll learn about total rate limits for Finch, rate limits for specific IP Addresses, and how to handle rate limit errors.

Header	Description
`Authorization`	Bearer authorization header, which is formed by concatenating the word “Bearer” with the access token, separated by a space.
`Finch-API-Version`	Header used to specify the version for a given API request. Current version is 2020-09-17.

Header	Description
`Finch-Request-Id`	Each response from Finch’s API has a unique request identifier. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.
`Finch-Data-Retrieved`	The date/time in ISO-8601 format that the data was retrieved from the employment system.
`Finch-Last-Attempted-Update-Date`	The date/time in ISO-8601 format that Finch last attempted to update this data.
`Finch-Last-Attempted-Update-Result`	The result of Finch’s last attempted update. Possible values: `success`: the last attempt succeeded `error`: the last attempt errored `partial_error`: (batch requests only) the last attempt succeeded for some items in the batch and failed for others.

Organization

Payroll

Deductions

Documents

Connect

Management

Sandbox

Development Guides

Headers

Request Headers

Response Headers

Organization

Payroll

Deductions

Documents

Connect

Management

Sandbox

Development Guides

​Request Headers

​Response Headers

Request Headers

Response Headers