In this guide, you’ll learn how to read data from Finch’s company, directory, individual, employment, payment, and pay statement API endpoints.
/company
, /directory
, /individual
, /employment
, /payment
, and /pay-statement
. These endpoints only allow the reading of data from employment providers; they do not permit the writing of data back to the system. Writing deductions and contributions back to the provider is covered in Write Data step.
In this step, you will learn how to make API requests, handle responses, and manage request rate limits.
/company
: Retrieve company information, such as name, address, and Federal Employer Identification Number (EIN)./directory
: List all the employees at the company, both active and inactive./individual
: Obtain individual information, such as name, date of birth, and contact details./employment
: Access employment-related data, like job title, department, and start and end dates, and income./payment
: Get payroll information, including pay frequency and last payment date./pay-statement
: Fetch detailed individual paycheck data, including earnings, taxes, employee deductions, and employer contributions./benefits
: Create and enroll employees in various types of benefits directly in the employer’s provider. The “benefits” are applied directly to the employee’s next paycheck in the deductions or contributions section. This endpoint is covered more in Write Data.Authorization
header using the format Bearer <your_access_token>
. Make sure the HTTP request uses the appropriate method (GET, POST, etc.) and includes any required parameters.
4XX
or 5XX
error types due to unsupported responses from the underlying employment system. Retrying immediately may not resolve the issue, so consider implementing a retry strategy with a delay. If the error persists, submit a support ticket with the Finch-Request-ID
present in the headers of the response.
401
HTTP status code and a finch_code
of reauthenticate_user
, it indicates Finch has lost access to the employer’s provider. If this happens, display a prompt on your frontend to have the end-user go through Finch Connect again to reconnect the provider. Upon successful re-authentication, obtain a new access token and continue making API requests with the new token. The old token can be discarded.
429
HTTP status code, your application has exceeded the rate limit for a product. To reduce rate limit errors, you can implement a backoff strategy to retry requests when encountering rate limit errors.