> ## Documentation Index
> Fetch the complete documentation index at: https://developer.tryfinch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How the Finch API is organized

> 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.

## Organization: company, individual, and employment

<Frame caption="One Company contains many Individuals and many Employment records. Identity and employment are split so you can query them independently.">
  <img src="https://mintcdn.com/finch/08B9OENKYadKN_zD/images/how-finch-works/data-model-org.svg?fit=max&auto=format&n=08B9OENKYadKN_zD&q=85&s=4c16308fafb43245f95d895a2b812454" alt="Company maps one-to-many to Individual and Employment, which share an individual_id" width="760" height="500" data-path="images/how-finch-works/data-model-org.svg" />
</Frame>

A Finch [connection](/implementation-guide/Backend-Application/Manage-Connections) typically covers one [Company](/api-reference/organization/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](/api-reference/organization/individual) record for identity data (name, DOB, SSN, home address) and an [Employment](/api-reference/organization/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`](/api-reference/organization/directory) first. It returns a paginated list of `individual_id`s you can then fetch in detail via the endpoints above.

<Tip>
  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.
</Tip>

## Payroll: payments and pay statements

<Frame caption="One Payment fans out into per-person Pay Statements, then into earnings, taxes, employee deductions, and employer contributions. Each line is also exposed as a flat Pay Statement Item.">
  <img src="https://mintcdn.com/finch/qVypC4iNFFCY2LRz/images/how-finch-works/data-model-payroll.svg?fit=max&auto=format&n=qVypC4iNFFCY2LRz&q=85&s=e0423768fb715d5c011034c91352b17a" alt="Payment contains pay statements, which contain earnings, taxes, employee deductions, and employer contributions, all flattened into pay statement items" width="880" height="780" data-path="images/how-finch-works/data-model-payroll.svg" />
</Frame>

A [Payment](/api-reference/payroll/payment) is one payrun, and it's the starting point for all payroll data. Each Payment contains one [Pay Statement](/api-reference/payroll/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](/api-reference/payroll/get-pay-statement-items) 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](/api-reference/payroll/get-rules) to apply the right labels and context in your system.

## Deductions: company benefits and per-employee contributions

<Frame caption="A company-level deduction defines the benefit. An individual deduction record holds the per-person amounts. The per-paycheck amount appears as a Pay Statement Item.">
  <img src="https://mintcdn.com/finch/08B9OENKYadKN_zD/images/how-finch-works/data-model-deductions.svg?fit=max&auto=format&n=08B9OENKYadKN_zD&q=85&s=34ba8f8f87f9430114e8662c2a9caf89" alt="Company deduction maps to per-individual deduction records, which are referenced by pay statement items as deduction or contribution lines" width="760" height="640" data-path="images/how-finch-works/data-model-deductions.svg" />
</Frame>

Finch's [Deductions](/products/deductions/Overview) 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](/api-reference/deductions/get-enrolled-individuals) 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](/api-reference/deductions/enroll-individuals-in-deductions), [update contribution amounts](/api-reference/deductions/update-deduction), and [remove individuals](/api-reference/deductions/unenroll-individuals-from-deductions) where the provider allows it. Call the [`/providers`](/api-reference/management/providers) endpoint to see which deduction types and operations each provider supports before you build against them.

## Documents: parsed data from HR forms

<Frame caption="Queue a job, then list documents for an individual or document type, then fetch a specific document to read its parsed fields.">
  <img src="https://mintcdn.com/finch/08B9OENKYadKN_zD/images/how-finch-works/data-model-documents.svg?fit=max&auto=format&n=08B9OENKYadKN_zD&q=85&s=24d78057125a2109d79a3601db2b6f07" alt="Queue a job leads to a documents list, then drill into a specific document to read parsed fields" width="760" height="480" data-path="images/how-finch-works/data-model-documents.svg" />
</Frame>

Finch's [Documents](/products/documents/Overview) product reads structured data out of HR documents using ML-based parsing. Two endpoints carry the data: [`GET /employer/documents`](/api-reference/documents/get-documents) returns a list of available documents (filterable by individual or document type), and [`GET /employer/documents/{document_id}`](/api-reference/documents/get-document) 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`](/api-reference/management/enqueue-a-new-automated-job) 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

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/how-finch-works/quickstart">
    Mint a sandbox token and pull your first employer record.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference">
    Every endpoint, request shape, and response field.
  </Card>

  <Card title="Finch Sandbox" icon="flask" href="/implementation-guide/Test/Finch-Sandbox">
    Test the data model with realistic fixtures before wiring up production.
  </Card>

  <Card title="Glossary" icon="book" href="/how-finch-works/unified-employment-api-glossary">
    Reference for every term used across the Finch API.
  </Card>
</CardGroup>
