Finch

# Finch

## Docs

- [Create a new connect session](https://developer.tryfinch.com/api-reference/connect/new-session.md): Create a new connect session for an employer
- [Create a new Connect session for reauthentication](https://developer.tryfinch.com/api-reference/connect/reauthenticate-session.md): Create a new Connect session for reauthenticating an existing connection
- [Create Deduction](https://developer.tryfinch.com/api-reference/deductions/create-deduction.md): 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.md): 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.md): List all company-wide deductions and contributions.
- [Get Deduction](https://developer.tryfinch.com/api-reference/deductions/get-deduction.md): Lists deductions and contributions information for a given item
- [Get Deductions for Individuals](https://developer.tryfinch.com/api-reference/deductions/get-deductions-for-individuals.md): Get enrollment information for the given individuals.
- [Get Enrolled Individuals](https://developer.tryfinch.com/api-reference/deductions/get-enrolled-individuals.md): Lists individuals currently enrolled in a given deduction.
- [Register Deduction](https://developer.tryfinch.com/api-reference/deductions/register-deduction.md): 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.md): Unenroll individuals from a deduction or contribution
- [Update Deduction](https://developer.tryfinch.com/api-reference/deductions/update-deduction.md): Updates an existing company-wide deduction or contribution
- [Handling API Responses](https://developer.tryfinch.com/api-reference/development-guides/Handling-API-Responses.md)
- [Headers](https://developer.tryfinch.com/api-reference/development-guides/Headers.md)
- [Permissions](https://developer.tryfinch.com/api-reference/development-guides/Permissions.md)
- [Rate Limits](https://developer.tryfinch.com/api-reference/development-guides/Rate-Limits.md): 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.md)
- [Error Handling](https://developer.tryfinch.com/api-reference/development-guides/errors/Error-Handling.md)
- [Error Types](https://developer.tryfinch.com/api-reference/development-guides/errors/Error-Types.md)
- [Get Document](https://developer.tryfinch.com/api-reference/documents/get-document.md): **Beta:** This endpoint is in beta and may change.
Retrieve details of a specific document by its ID.

- [List Documents](https://developer.tryfinch.com/api-reference/documents/get-documents.md): **Beta:** This endpoint is in beta and may change.
Retrieve a list of company-wide documents.

- [Create Access Token](https://developer.tryfinch.com/api-reference/management/create-access-token.md): Exchange the authorization code for an access token
- [Disconnect](https://developer.tryfinch.com/api-reference/management/disconnect.md): 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.md): 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.
- [Introspect](https://developer.tryfinch.com/api-reference/management/introspect.md): Read account information associated with an `access_token`
- [List All Automated Jobs](https://developer.tryfinch.com/api-reference/management/list-all-automated-jobs.md): 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.md): Return details on all available payroll and HR systems.
- [Request Forwarding](https://developer.tryfinch.com/api-reference/management/request-forwarding.md): 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.md): 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.md): Get an automated job by `job_id`.
- [Company](https://developer.tryfinch.com/api-reference/organization/company.md): Read basic company data
- [Directory](https://developer.tryfinch.com/api-reference/organization/directory.md): Read company directory and organization structure
- [Employment](https://developer.tryfinch.com/api-reference/organization/employment.md): Read individual employment and income data
- [Individual](https://developer.tryfinch.com/api-reference/organization/individual.md): Read individual data, excluding income and employment data
- [Create Rule](https://developer.tryfinch.com/api-reference/payroll/create-rule.md): **Beta:** this endpoint currently serves employers onboarded after March 4th and historical support will be added soon
Custom rules can be created to associate specific attributes to pay statement items depending on the use case. For example, pay statement items that meet certain conditions can be labeled as a pre-tax 401k. This metadata can be retrieved where pay statement item information is available.

- [Delete Rule](https://developer.tryfinch.com/api-reference/payroll/delete-rule.md): **Beta:** this endpoint currently serves employers onboarded after March 4th and historical support will be added soon
Delete a rule for a pay statement item.

- [Get Pay Group](https://developer.tryfinch.com/api-reference/payroll/get-pay-group.md): Read information from a single pay group
- [Get All Pay Groups](https://developer.tryfinch.com/api-reference/payroll/get-pay-groups.md): Read company pay groups and frequencies
- [Pay Statement Item](https://developer.tryfinch.com/api-reference/payroll/get-pay-statement-items.md): **Beta:** this endpoint currently serves employers onboarded after March 4th and historical support will be added soon
 Retrieve a list of detailed pay statement items for the access token's connection account.

- [Get Rules](https://developer.tryfinch.com/api-reference/payroll/get-rules.md): **Beta:** this endpoint currently serves employers onboarded after March 4th and historical support will be added soon
List all rules of a connection account.

- [Pay Statement](https://developer.tryfinch.com/api-reference/payroll/pay-statement.md): 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.md): Read payroll and contractor related payments by the company.
- [Update Rule](https://developer.tryfinch.com/api-reference/payroll/update-rule.md): **Beta:** this endpoint currently serves employers onboarded after March 4th and historical support will be added soon
Update a rule for a pay statement item.

- [Create a new sandbox account](https://developer.tryfinch.com/api-reference/sandbox/create-sandbox-account.md): 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.md): 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.md)
- [Add a new sandbox payment](https://developer.tryfinch.com/api-reference/sandbox/create-sandbox-payment.md)
- [Get configurations for sandbox jobs](https://developer.tryfinch.com/api-reference/sandbox/get-sandbox-jobs-configuration.md)
- [Enqueue a new sandbox job](https://developer.tryfinch.com/api-reference/sandbox/refresh-job.md)
- [Update a sandbox account](https://developer.tryfinch.com/api-reference/sandbox/update-sandbox-account.md): 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.md)
- [Update sandbox employment](https://developer.tryfinch.com/api-reference/sandbox/update-sandbox-employment.md)
- [Update sandbox individual](https://developer.tryfinch.com/api-reference/sandbox/update-sandbox-individual.md)
- [Update configurations for sandbox jobs](https://developer.tryfinch.com/api-reference/sandbox/update-sandbox-jobs-configuration.md)
- [W-2 Box 1](https://developer.tryfinch.com/developer-resources/Calculating-W2-Box1-value.md): 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.md): Learn how to calculate year-to-date (YTD) gross wages for individual employees using data returned from Finch Organization endpoints.
- [Data Access Controls](https://developer.tryfinch.com/developer-resources/Data-Access-Controls.md): Learn how to disable fields from API responses.
- [Data Syncs](https://developer.tryfinch.com/developer-resources/Data-Syncs.md): Learn how Finch syncs data after an employer connects and how you can verify the freshness and scope of the data you receive.
- [Finch Developer FAQs](https://developer.tryfinch.com/developer-resources/Developer-FAQs.md): 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.md): 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.
- [MCP](https://developer.tryfinch.com/developer-resources/Finch-MCP-Server.md): Use the Finch MCP Server to enable natural language access to the Finch API via large language models (LLMs).
- [Pay Statement Items & Rules](https://developer.tryfinch.com/developer-resources/Pay-Statement-Items-Rules.md): Assign labels, categories, and metadata to pay statement items based on custom rules. 
- [Pay Statement Type Classification](https://developer.tryfinch.com/developer-resources/Pay-Statement-Type-Classification.md): Learn how to classify Contributions and Deductions retrieved from the Finch Payroll endpoints.
- [Reauthentication](https://developer.tryfinch.com/developer-resources/Reauthentication.md): 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.md): 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.md): 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.md): 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.md): Get notified when data has changed with Finch Webhooks. You can create, test, and manage Finch Webhooks in the Developer Dashboard.
- [API Changes and Updates](https://developer.tryfinch.com/developer-resources/api-changes.md):  Keep track of changes and upgrades to the Finch API 
- [Connect an Employer](https://developer.tryfinch.com/how-finch-works/finch-connect.md): 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.md): The Finch API powers integrations to employment systems through a single, standardized data model.
- [Quickstart](https://developer.tryfinch.com/how-finch-works/quickstart.md): This API Quickstart guide will help you send your first request to Finch, the unified API for HR and payroll.
- [Unified API Glossary](https://developer.tryfinch.com/how-finch-works/unified-employment-api-glossary.md): Use this glossary to familiarize yourself with terminology used in Finch's documentation and API reference.