: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);
}


Changelog

API Status

Finch

API Reference

Sign In

Sign Up

Update configurations for sandbox jobs

SandboxJobConfiguration

bearerAuth

basicAuth

megaphone

signal-bars

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

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

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

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

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

Headers

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.

Organization

Payroll

Deductions

Documents

Connect

Management

Sandbox

Development Guides

Update configurations for sandbox jobs

Authorizations

Body

Response