Finch’s API data model normalizes payroll, HR, and benefits data from 250+ providers. Walk through the core entities and how they connect in one map.
The diagrams below give you a working mental model of the Finch API. Each section explains the high-level functionality of Finch’s products, each of which contains multiple endpoints.
A Finch connection typically covers one Company, which can include one or many entities (separate EINs, divisions, or subsidiaries) with one or many employees. Each employee has two records that share the same individual_id: an Individual record for identity data (name, DOB, SSN, home address) and an Employment record for job data (title, manager, start date, income). Querying them separately means you can pull only what you need.To enumerate everyone at a connection, call GET /employer/directory first. It returns a paginated list of individual_ids you can then fetch in detail via the endpoints above.
The same person can have multiple Employment records over time (rehires, role changes, multi-EIN setups). Treat individual_id as the stable identity key and Employment as historical job state.
A Payment is one payrun, and it’s the starting point for all payroll data. Each Payment contains one Pay Statement per person, broken down into earnings (base, overtime, bonus), taxes (federal, state, FICA), employee deductions (401k, health premiums, FSA), and employer contributions (401k match, employer-paid benefits). Deductions and contributions live in separate fields on the Pay Statement so you can read or aggregate each side cleanly.Use the Pay Statement Item endpoint to retrieve all payroll items that have appeared in a company’s processed payroll, including taxes, deductions, earnings, and employer contributions. For example, if your customer’s organization labels a health deduction as EE_MED_PPO_PREM in the provider system, this endpoint surfaces that name alongside its category and type. From there you can use the Rules endpoint to apply the right labels and context in your system.
Deductions: company benefits and per-employee contributions
Finch’s Deductions product represents benefits from the payroll side, in two connected views. A company-level deduction defines the benefit at the company: type (401k, HSA, FSA, etc.), frequency, and the employer’s contribution rule. An individual deduction record then holds the per-person amounts: employee contribution, employer contribution, and annual maximum. The per-paycheck amount itself lives on the Pay Statement Item. The deduction record tells you what should happen each pay period; the pay statement item tells you what actually happened.You can add individuals to a deduction, update contribution amounts, and remove individuals where the provider allows it. Call the /providers endpoint to see which deduction types and operations each provider supports before you build against them.
Finch’s Documents product reads structured data out of HR documents using ML-based parsing. Two endpoints carry the data: GET /employer/documents returns a list of available documents (filterable by individual or document type), and GET /employer/documents/{document_id} returns the parsed fields for one document.Documents is async. Before either read endpoint will return fresh data, queue an automated job with POST /jobs/automated so Finch can sync from the provider. The product is currently in beta with W-4 support; expect more document types over time.
