How the Finch API is organized

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.

​

Organization: company, individual, and employment

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.

​

Payroll: payments and pay statements

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.

​

Benefits: plans, enrollments, and dependents

Benefits is Finch’s source-of-truth product for benefits enrollment. Where Deductions (above) shows the payroll-side evidence of a benefit, like what’s being withheld each paycheck, Benefits returns the canonical plan and enrollment data directly from the benefits administration side of the employer’s system:

• Plan: the company-level benefit plan, including type, carrier, plan year, deduction code, and available coverage tiers.
• Enrollment: the individual’s actual enrollment in a plan, with coverage tier, effective dates, contribution amounts, and covered dependents.
• Dependent: a spouse or child covered under an individual’s enrollment, linked back to its enrollment records.

Use Benefits when you need authoritative enrollment state, for example to verify coverage before quoting a benefit or to retrieve dependent details for compliance. Use Deductions when you need to see what’s actually being withheld each pay period. The two are complementary.

​

Documents: parsed data from HR forms

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.

​

Next steps