Provider
A provider is an employer’s HRIS, Payroll, or other employment system. The provider is the system of record for the data connected to the Finch APIs. Providers can be referenced within the Finch APIs by theirpayroll_provider_id
.
Employer
An employer is an organization, company, or entity that hires and pays employees. An employer may consist of one or many sub-entities and use one or many systems of record (i.e. payroll providers) to manage and pay employees. Employers (or any sub-entities) can be referenced within the Finch APIs by their Finch-issuedconnection_id
. If an employer has multiple sub-entities within their payroll system, these may be represented as multiple connections with different connection_id
. You can use the EIN or Legal Name that returns in the /company
endpoint to reconcile your records internally.
Individual
An individual is a unique person with distinctive attributes, represented as fields, who is currently or formerly employed at an employer. Individuals can be referenced within the Finch APIs by their finch-issuedindividual_id
. Contractors are also considered individuals.
Field
A field is a specific employment data element or attribute displayed within Finch’s standardized data model pulled directly from an employment system.Product
A product is a subgroup of Finch’s standardized data model related to a particular segment or workflow of an employment system. Finch currently has three products: Organization, Payroll, and Benefits.Connection
A connection is the link created between your application and the employer’s provider through Finch. A connection is established after an employer authenticates via Finch Connect. A connection is defined by a uniqueconnection_id
. Therefore, an employer may have one or many connections depending on if the employer is made up of sub-entities.
(Employer) Account
An employer account is used to connect their company’s data to Finch. Employers can connect with various authentication methods such as an HR admin’s account, an API service account (i.e. API token), or a third-party administrator account.Access Token
An access token represents a single connection with an employer entity and allows the developer to query data from the associated employment system of the employer entity. You should treat access tokens with the same level of security as you would passwords.Product scope
A product scope determines the specific data your application can access from the employer’s provider. Each product scope refers directly to a Finch API endpoint. If a connection’s access token does not have the product included, the request will be blocked with a 401 Unauthorized error.Application
An application is a unique set ofclient_id
and client_secret
credentials that enable you to launch Finch Connect and receive access tokens. An application essentially groups your connections with your Finch “environment”. Finch has three environments: sandbox, testing, and production. The sandbox application connects only mock providers. The testing application connects live providers, but in a limited capacity. The production application connects live providers without any limitations.
Authentication Method
An authentication method is the specific technique that an employer account uses to connect their provider. Finch supports OAuth 2.0, API token, user credentials, and assisted as authentication methods to allow you maximum flexibility in offering integrations to your end customer. Each method provides a distinct balance between reliability and data accessibility depending on the needs of your application and your customer. See the “Products” section in the Provider Field Support for each provider’s supported authentication methods. You can also use theauthentication_methods
field on the Providers endpoint of the API.
Integration Type
An integration type refers to one of two ways that Finch organizes our provider integrations. Automated integrations are the primary integration type offered by Finch, and offer the highest level of data responsiveness. Assisted integrations enable Finch to offer the highest level of provider coverage, while maintaining an API-first experience for developers. See our Integration Types page for more details.Automated Integration
An automated integration syncs data automatically from the employment system once a connection is created. Finch will then proactively sync with the employment system on our periodic Data Sync cadence. A full list of Finch’s automated integrations can be referenced on the Providers overview.Assisted Integration
An assisted integration syncs data through a manual service model powered by Finch’s Product Operations team. The data is synced on a slower cadence compared to automated integrations. Assisted integrations help expand coverage to the long tail of providers not otherwise covered by automated integrations. Finch is continuously updating assisted integrations to automated integrations based on customer demand and provider availability. A full list of Finch’s assisted integrations can be referenced on the Providers overview.Data Sync
A data sync is the cadence that Finch synchronizes our system with the employer’s provider system to ensure consistent, up-to-date data. Finch’s API responses will return employer data from the most recent successful data sync to increase performance and reduce latency.Job
A job is a reference object to an API request submitted to Finch which is scheduled to be asynchronously completed. Jobs can be completed automatically (such as data syncs or automated benefit tasks) or asynchronously (such as assisted benefit tasks). A job can be referenced within the Finch APIs by its Finch-issuedjob_id
.
Payment
A payment is the summary of the monetary transactions an employer provides to employees in return for their work during a specified period of time. Types of payments can include regular payments (salary, wages, etc.) or off-cycle payments (bonuses, commissions, etc.). Payments can be referenced by their Finch-issuedpayment_id
.
Pay Statement
A pay statement is a detailed breakdown of the payment by employee. Pay statements, also known in the industry as “paystub” or “payslip” provide comprehensive information on an individual’s gross pay, net pay, earnings, taxes, employee deductions, and employer contributions for a specified pay period. Pay statements can be referenced by their Finch-issuedpayment_id
.
Pay Groups
A pay group refers to a group of employees within an employer that are paid on the same payroll frequency for on-cycle payments. An employer can have multiple pay groups. Each pay group retrieved by Finch will have a description and the payroll frequency associated with it, as obtained from the payroll system.Earning
An earning refers to the various types of compensation an employee receives in exchange for their services during a specific pay period. Some examples of earnings are salary, wage, bonus, commissions, tips, and allowances. Earnings are the detailed breakdown of an employee’sgross_pay
found on the pay statement.