# Finch

## Docs

- [Create a new connect session](https://developer.tryfinch.com/api-reference/connect/new-session): Create a new connect session for an employer
- [Create a new Connect session for reauthentication](https://developer.tryfinch.com/api-reference/connect/reauthenticate-session): Create a new Connect session for reauthenticating an existing connection
- [Create Deduction](https://developer.tryfinch.com/api-reference/deductions/create-deduction): Creates a new company-wide deduction or contribution. Please use the `/providers` endpoint to view available types for each provider.
- [Enroll Individuals in Deductions](https://developer.tryfinch.com/api-reference/deductions/enroll-individuals-in-deductions): 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.
- [Get All Deductions](https://developer.tryfinch.com/api-reference/deductions/get-all-deductions): List all company-wide deductions and contributions.
- [Get Deduction](https://developer.tryfinch.com/api-reference/deductions/get-deduction): Lists deductions and contributions information for a given item
- [Get Deductions for Individuals](https://developer.tryfinch.com/api-reference/deductions/get-deductions-for-individuals): Get enrollment information for the given individuals.
- [Get Enrolled Individuals](https://developer.tryfinch.com/api-reference/deductions/get-enrolled-individuals): Lists individuals currently enrolled in a given deduction.
- [Register Deduction](https://developer.tryfinch.com/api-reference/deductions/register-deduction): 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.
- [Unenroll Individuals from Deductions](https://developer.tryfinch.com/api-reference/deductions/unenroll-individuals-from-deductions): Unenroll individuals from a deduction or contribution
- [Update Deduction](https://developer.tryfinch.com/api-reference/deductions/update-deduction): Updates an existing company-wide deduction or contribution
- [Handling API Responses](https://developer.tryfinch.com/api-reference/development-guides/Handling-API-Responses)
- [Headers](https://developer.tryfinch.com/api-reference/development-guides/Headers)
- [Permissions](https://developer.tryfinch.com/api-reference/development-guides/Permissions)
- [Rate Limits](https://developer.tryfinch.com/api-reference/development-guides/Rate-Limits): 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.
- [API Versioning](https://developer.tryfinch.com/api-reference/development-guides/Versioning)
- [Error Handling](https://developer.tryfinch.com/api-reference/development-guides/errors/Error-Handling)
- [Error Types](https://developer.tryfinch.com/api-reference/development-guides/errors/Error-Types)
- [Create Access Token](https://developer.tryfinch.com/api-reference/management/create-access-token): Exchange the authorization code for an access token
- [Disconnect](https://developer.tryfinch.com/api-reference/management/disconnect): Disconnect one or more `access_token`s from your application.
- [Enqueue a New Automated Job](https://developer.tryfinch.com/api-reference/management/enqueue-a-new-automated-job): 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.
- [Introspect](https://developer.tryfinch.com/api-reference/management/introspect): Read account information associated with an `access_token`
- [List All Automated Jobs](https://developer.tryfinch.com/api-reference/management/list-all-automated-jobs): 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.
- [Providers](https://developer.tryfinch.com/api-reference/management/providers): Return details on all available payroll and HR systems.
- [Request Forwarding](https://developer.tryfinch.com/api-reference/management/request-forwarding): 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.
- [Retrieve a Manual Job](https://developer.tryfinch.com/api-reference/management/retrieve-a-manual-job): Get a manual job by `job_id`. Manual jobs are completed by a human and include Assisted Benefits jobs.
- [Retrieve an Automated Job](https://developer.tryfinch.com/api-reference/management/retrieve-an-automated-job): Get an automated job by `job_id`.
- [Company](https://developer.tryfinch.com/api-reference/organization/company): Read basic company data
- [Directory](https://developer.tryfinch.com/api-reference/organization/directory): Read company directory and organization structure
- [Employment](https://developer.tryfinch.com/api-reference/organization/employment): Read individual employment and income data
- [Individual](https://developer.tryfinch.com/api-reference/organization/individual): Read individual data, excluding income and employment data
- [Get Pay Group](https://developer.tryfinch.com/api-reference/payroll/get-pay-group): Read information from a single pay group
- [Get All Pay Groups](https://developer.tryfinch.com/api-reference/payroll/get-pay-groups): Read company pay groups and frequencies
- [Pay Statement](https://developer.tryfinch.com/api-reference/payroll/pay-statement): Read detailed pay statements for each individual.

Deduction and contribution types are supported by the payroll systems that supports Benefits.
- [Payment](https://developer.tryfinch.com/api-reference/payroll/payment): Read payroll and contractor related payments by the company.
- [Create a new sandbox account](https://developer.tryfinch.com/api-reference/sandbox/create-sandbox-account): Create a new account for an existing connection (company/provider pair)
- [Create a new Sandbox Connection](https://developer.tryfinch.com/api-reference/sandbox/create-sandbox-connection): Create a new connection (new company/provider pair) with a new account
- [Add new individuals to a sandbox company](https://developer.tryfinch.com/api-reference/sandbox/create-sandbox-employee)
- [Add a new sandbox payment](https://developer.tryfinch.com/api-reference/sandbox/create-sandbox-payment)
- [Get configurations for sandbox jobs](https://developer.tryfinch.com/api-reference/sandbox/get-sandbox-jobs-configuration)
- [Enqueue a new sandbox job](https://developer.tryfinch.com/api-reference/sandbox/refresh-job)
- [Update a sandbox account](https://developer.tryfinch.com/api-reference/sandbox/update-sandbox-account): Update an existing sandbox account. Change the connection status to understand how the Finch API responds.
- [Update a sandbox company's data](https://developer.tryfinch.com/api-reference/sandbox/update-sandbox-company)
- [Update sandbox employment](https://developer.tryfinch.com/api-reference/sandbox/update-sandbox-employment)
- [Update sandbox individual](https://developer.tryfinch.com/api-reference/sandbox/update-sandbox-individual)
- [Update configurations for sandbox jobs](https://developer.tryfinch.com/api-reference/sandbox/update-sandbox-jobs-configuration)
- [W-2 Box 1](https://developer.tryfinch.com/developer-resources/Calculating-W2-Box1-value): Finch's data can be used to run an individual's W-2 Box 1 calculation using data returned from Finch Pay endpoints.
- [Calculate Year-To-Date (YTD) Wages](https://developer.tryfinch.com/developer-resources/Calculating-YTD-Wages): Learn how to calculate year-to-date (YTD) gross wages for individual employees using data returned from Finch Organization endpoints.
- [Data Syncs](https://developer.tryfinch.com/developer-resources/Data-Syncs): 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.
- [Finch Developer FAQs](https://developer.tryfinch.com/developer-resources/Developer-FAQs): Explore Finch developers' most frequently asked questions (FAQ) and answers. Topics include Products & Integrations, API & Data Model, Security, and more.
- [Enable Social Security Number (SSN) Field](https://developer.tryfinch.com/developer-resources/Enable-SSN-Field): 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.
- [Pay Statement Type Classification](https://developer.tryfinch.com/developer-resources/Pay-Statement-Type-Classification): Learn how to classify Contributions and Deductions retrieved from the Finch Payroll endpoints.
- [Reauthentication](https://developer.tryfinch.com/developer-resources/Reauthentication): 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. 
- [Reconcile Employees](https://developer.tryfinch.com/developer-resources/Reconcile-Employees): Learn how to reconcile employee profiles in Finch using PII such as full name and date of birth (DOB), email, or SSN.
- [Request Forwarding](https://developer.tryfinch.com/developer-resources/Request-Forwarding): Finch Request Forwarding is a passthrough API feature that enables you to issue raw requests directly against an employment system’s API.
- [SDKs](https://developer.tryfinch.com/developer-resources/SDKs): Explore our frontend and backend SDK repositories. Finch supports SDKs in JavaScript, React, Node, Python, Java, Kotlin, and Go.
- [Webhooks](https://developer.tryfinch.com/developer-resources/Webhooks): Get notified when data has changed with Finch Webhooks. You can create, test, and manage Finch Webhooks in the Developer Dashboard.
- [Connect an Employer](https://developer.tryfinch.com/how-finch-works/finch-connect): Finch Connect is an embedded onboarding flow that enables employers to connect their HR or payroll system to your app.
- [What is Finch?](https://developer.tryfinch.com/how-finch-works/finch-overview): The Finch API powers integrations to employment systems through a single, standardized data model.
- [Quickstart](https://developer.tryfinch.com/how-finch-works/quickstart): This API Quickstart guide will help you send your first request to Finch, the unified API for HR and payroll.
- [Unified Employment API Glossary](https://developer.tryfinch.com/how-finch-works/unified-employment-api-glossary): Use this glossary to familiarize yourself with employment terminology used in Finch's documentation and API reference.
- [Batch Requests](https://developer.tryfinch.com/implementation-guide/API-Calls/Batch-Requests): Learn how to monitor your application’s usage of Finch APIs, optimize your requests, and handle rate limits and errors.
- [Read Organization and Payroll Data](https://developer.tryfinch.com/implementation-guide/API-Calls/Read-Data): In this guide, you'll learn how to read data from Finch's company, directory, individual, employment, payment, and pay statement API endpoints.
- [Write Payroll Deductions & Contributions](https://developer.tryfinch.com/implementation-guide/API-Calls/Write-Data): In this guide, you'll learn how to write deductions and contribution changes to Finch's benefits API endpoint.
- [Backend Security](https://developer.tryfinch.com/implementation-guide/Backend-Application/Backend-Security): 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.
- [Control Access (Optional)](https://developer.tryfinch.com/implementation-guide/Backend-Application/Control-Access): Learn how to control data access within multi-tenancy applications through role-based access control (RBAC) or other authorization methods.
- [Disconnect Tokens](https://developer.tryfinch.com/implementation-guide/Backend-Application/Disconnect-Tokens): Learn how Finch defines connections, and how to safely disconnect all access tokens associated with a connection if needed.
- [Manage Connections](https://developer.tryfinch.com/implementation-guide/Backend-Application/Manage-Connections): In this guide, you’ll learn how to define and manage multi-account, multi-provider, and multi-entity connections based on your customers’ needs.
- [Mitigate Errors](https://developer.tryfinch.com/implementation-guide/Backend-Application/Mitigate-Errors): In this guide, you'll learn how to identify and mitigate common errors such as server errors, reauthentication errors, and rate limit errors.
- [Monitor Usage](https://developer.tryfinch.com/implementation-guide/Backend-Application/Monitor-Usage): In this guide, you'll find best practices for monitoring your application's usage of Finch to identify patterns and potential issues.
- [Store Tokens](https://developer.tryfinch.com/implementation-guide/Backend-Application/Store-Tokens): ***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.
- [Create a Finch Developer Account](https://developer.tryfinch.com/implementation-guide/Connect/Create-Account): Create your Finch Developer Account, recieve your application credentials, and pilot how Finch works in our sandbox environment.
- [Retrieve Access Token](https://developer.tryfinch.com/implementation-guide/Connect/Retrieve-Access-Token): In this guide, you’ll exchange the authorization code for an access token. Access tokens are required for making API requests to Finch endpoints.
- [Integrate Finch Connect Into Your Application](https://developer.tryfinch.com/implementation-guide/Connect/Set-Up-Finch-Connect): 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. 
- [Increase Employer Adoption](https://developer.tryfinch.com/implementation-guide/Deploy-and-Manage/Increase-Employer-Adoption): Explore our best practices for optimizing employer adoption and conversion in Finch Connect.
- [Get Support](https://developer.tryfinch.com/implementation-guide/Deploy-and-Manage/Support): 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!
- [Configure Auth Methods](https://developer.tryfinch.com/implementation-guide/Integration-Preparation/Configure-Auth-Methods): Learn more about the four authentication methods offered by Finch -- OAuth, Credentials, API token, and Assisted.
- [Email Forwarding](https://developer.tryfinch.com/implementation-guide/Integration-Preparation/Email-Forwarding): Set up email forwarding for ADP Workforce Now and Assisted Integrations.
- [Manage Integrations](https://developer.tryfinch.com/implementation-guide/Integration-Preparation/Manage-Integrations): 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.
- [Security Reviews](https://developer.tryfinch.com/implementation-guide/Integration-Preparation/Security-Reviews): 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. 
- [Environments](https://developer.tryfinch.com/implementation-guide/Test/Environments): You can utilize three different environments to test your integration with Finch: Sandbox, Development, and Production. Each has specific uses and limitations.
- [Finch Sandbox](https://developer.tryfinch.com/implementation-guide/Test/Finch-Sandbox): Use the Finch Sandbox to generate mock connections with Finch providers, see which fields are supported, and configure the data for unique testing scenarios.
- [Provider Sandboxes](https://developer.tryfinch.com/implementation-guide/Test/Provider-Sandboxes): 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.
- [Develop Your Test Plan](https://developer.tryfinch.com/implementation-guide/Test/Testing-Plan): In this guide, you'll build a robust testing, validation, and maintenance plan for your Finch API integration to improve reliability, accuracy, and performance.
- [Go Live Checklist](https://developer.tryfinch.com/implementation-guide/go-live-checklist):  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.
- [Field Support](https://developer.tryfinch.com/integrations/field-support): Explore coverage across all providers for your use case.
- [Integration Types](https://developer.tryfinch.com/integrations/integration-types): Finch automated integrations sync data from HR and payroll providers every 24 hours. For our assisted integrations, data is refreshed every 7 days.
- [ADP Workforce Now](https://developer.tryfinch.com/integrations/provider-information/ADP-Workforce-Now)
- [AlphaStaff](https://developer.tryfinch.com/integrations/provider-information/AlphaStaff)
- [Bob](https://developer.tryfinch.com/integrations/provider-information/Bob)
- [Deel](https://developer.tryfinch.com/integrations/provider-information/Deel)
- [Factorial HR](https://developer.tryfinch.com/integrations/provider-information/Factorial-HR)
- [Gusto](https://developer.tryfinch.com/integrations/provider-information/Gusto)
- [Justworks](https://developer.tryfinch.com/integrations/provider-information/Justworks)
- [Rippling](https://developer.tryfinch.com/integrations/provider-information/Rippling)
- [TriNet PEO](https://developer.tryfinch.com/integrations/provider-information/TriNet)
- [Workday](https://developer.tryfinch.com/integrations/provider-information/Workday)
- [Provider Network](https://developer.tryfinch.com/integrations/providers): Find a list of every HRIS and payroll system supported by Finch
- [Integrate Finch Connect Into Your Application](https://developer.tryfinch.com/legacy-flows/Integrate-Finch-Connect): 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. 
- [Deductions](https://developer.tryfinch.com/products/deductions/Overview): Manage the full lifecycle of deductions and contributions for employers with Finch's Deductions APIs.
- [Organization](https://developer.tryfinch.com/products/organization/Overview): Read company and employee data from employment systems with Finch's Organization APIs.
- [Payroll](https://developer.tryfinch.com/products/payroll/Overview): Dig into the details of each company payment and employee pay statement with Finch's Payroll APIs.


## Optional

- [Changelog](https://changelog.tryfinch.com)
- [API Status](https://status.tryfinch.com)