: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

Employer Resources

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

Finch's Provider Network includes popular HRIS and payroll systems like ADP, Quickbooks, Gusto, Paycor, TriNet, and UKG.

Providers

Explore coverage across all providers for your use case.

Field Support

AlphaStaff

Deel

Factorial HR

Gusto

TriNet PEO

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

In this integration guide, you will sign up for a Finch Account, set up Finch Connect, integrate the Finch API, and go into production.

Finch API Implementation Guide

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

Create a Finch Developer Account

In this guide, you'll integrate Finch Connect into your application’s frontend.

Set Up Finch Connect

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

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

Write Payroll Deductions & Contributions

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, 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

Explore our best practices for storing access tokens securely. Finch requires developers to store tokens on the backend server for improved security controls.

Store Tokens

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

Disconnect Tokens

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

Control Access (Optional)

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

Increase Employer Adoption

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

Validate that your application is ready for deployment with the Finch go-live checklist. Set yourself up for success when you launch 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

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

Finch Developer FAQs

Learn how to authenticate with ADP Comprehensive Services via Finch Connect.

ADP Comprehensive Services

Learn how to authenticate with ADP Enterprise via Finch Connect.

ADP Enterprise

Learn how to authenticate with ADP Next Gen via Finch Connect.

ADP Next Gen

Learn how to authenticate with ADP Run via Finch Connect.

ADP Run

Learn how to authenticate with ADP TeamPay via Finch Connect.

ADP TeamPay

Learn how to authenticate with ADP TotalSource via Finch Connect.

ADP TotalSource

Learn how to authenticate with ADP Vantage via Finch Connect.

ADP Vantage

Learn how to authenticate with ADP Workforce Now via Finch Connect.

ADP Workforce Now

Learn how to authenticate with Bob via Finch Connect.

Learn how to authenticate with Insperity API via Finch Connect.

Insperity API

Learn how to authenticate with isolved via Finch Connect.

isolved

Learn how to authenticate with Paycom API via Finch Connect.

Paycom API

Learn how to authenticate with Paylocity API via Finch Connect.

Paylocity API

Learn how to authenticate with TriNet API via Finch Connect.

TriNet API

Learn how to authenticate with UKG Pro via Finch Connect.

UKG Pro

Learn how to authenticate with UKG Ready API via Finch Connect.

UKG Ready API

Learn how to authenticate with Workday API via Finch Connect.

Workday API

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

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

Exchange the authorization code for an access token

Create Access Token

Return details on all available payroll and HR systems.

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. Currently, only the `data_sync_all` job type is supported, which will 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.

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

Management

Sandbox

Development Guides

Headers

Request Headers

Response Headers

Organization

Payroll

Deductions

Management

Sandbox

Development Guides

​Request Headers

​Response Headers

Request Headers

Response Headers