Finch

Read employment data from any payroll or HR system through one connection - the company, the employee directory, individual and employment records, payroll runs and pay statements, pay groups and the benefits an employer offers.

Actions

Action	What it does
Get benefit	Read one company benefit, with its contribution rule - a fixed amount, a percentage, or a tiered schedule.
Get benefit enrollments	Read each person's own settings for one benefit - how much they contribute, the company's match, any annual maximum, and whether catch-up contributions apply.
Get company	Read the employer's own record: legal name, EIN, entity type and subtype, departments, work locations, and the bank accounts payroll is funded from.
Get connection details	Read what this connection actually is: which employer and payroll provider it points at, and which products it was authorised for.
Get data sync job	Read one data-sync job: whether it is pending, running, complete or failed, and when it ran.
Get employments	Read employment records for the individuals named - job title, employment type and status, start and end dates, manager, department, work location, and current and historical pay rates.
Get individuals	Read personal profiles for the individuals named - preferred name, date of birth, home address, emails and phone numbers.
Get pay group	Read one pay group, with the IDs of everyone in it and how often it is paid.
Get pay statements	Read the per-employee pay statements behind one or more payroll runs: every earning, tax, employee deduction and employer contribution, with the employer's own name for each line alongside Finch's normalised type.
List benefits	List every benefit the employer offers, with its normalised type, the employer's own description of it, how often it is deducted, and the company's contribution rule.
List data sync jobs	List the data-sync jobs Finch has run for this connection, most recent first, with the status of each.
List directory	List everyone in the employer's directory - name, department, manager and whether they are currently active - a page at a time.
List enrolled individuals	List the IDs of everyone enrolled in one benefit.
List pay groups	List the employer's pay groups and how often each is paid.
List pay statement items	List the distinct earnings, taxes, deductions and employer contributions this employer's payroll actually uses - the catalogue of line items, not any one person's amounts.
List payments	List the employer's payroll runs whose pay date falls in a date range, with gross and net pay, employee and employer taxes, the company debit, and the pay period each covers.
List providers	List every payroll and HR system Finch can connect to, with the products each supports and how it authenticates.
List supported benefits	List which benefit types this employer's payroll provider supports through Finch, and what may be set on each - the frequencies allowed, the deduction and contribution styles, and whether annual maximums and catch-up contributions apply.

Get benefit

Read one company benefit, with its contribution rule - a fixed amount, a percentage, or a tiered schedule.

Inputs

Benefitbenefit_idtextRequired: The benefit to read. Pick one, or paste a Finch benefit ID.

Outputs

benefit_idtext
company_contributionobject
descriptiontext
frequencytext
typetext

Example output

{
  "benefit_id": "f1b6a0d5-2c48-49ab-9e73-0a5d3c81b6f4",
  "company_contribution": {
    "amount": 400,
    "type": "percent"
  },
  "description": "Company 401(k)",
  "frequency": "every_paycheck",
  "type": "401k"
}

Get benefit enrollments

Read each person's own settings for one benefit - how much they contribute, the company's match, any annual maximum, and whether catch-up contributions apply. Leave the individual IDs empty to read everyone enrolled.

Inputs

Benefitbenefit_idtextRequired: The benefit to read. Pick one, or paste a Finch benefit ID.
Individual IDsindividual_idslist: Only read these people's settings. Leave empty for everyone enrolled in the benefit.

Outputs

benefit_idtext: The benefit these settings are for
countnumber: Records returned
enrollmentslist: Each person's settings for this benefit
error_countnumber: How many IDs failed
errorslist: IDs Finch could not answer for, with its reason
requested_countnumber: IDs asked for

Example output

{
  "benefit_id": "f1b6a0d5-2c48-49ab-9e73-0a5d3c81b6f4",
  "count": 1,
  "enrollments": [
    {
      "annual_maximum": 2350000,
      "catch_up": false,
      "company_contribution": {
        "amount": 400,
        "type": "percent"
      },
      "employee_deduction": {
        "amount": 500,
        "type": "percent"
      },
      "individual_id": "5cbf7c8c-3f4c-4b1e-9d6b-2f0a1c9d4e77"
    }
  ],
  "error_count": 0,
  "errors": [],
  "requested_count": 0
}

Get company

Read the employer's own record: legal name, EIN, entity type and subtype, departments, work locations, and the bank accounts payroll is funded from. Takes no input - it describes whichever employer this connection is for.

Inputs

None.

Outputs

accountslist
departmentslist
eintext
entityobject
idtext
legal_nametext
locationslist
primary_emailtext
primary_phone_numbertext

Example output

{
  "accounts": [
    {
      "account_name": "Payroll operating",
      "account_number": "****4417",
      "account_type": "checking",
      "institution_name": "Puget Sound Bank",
      "routing_number": "125000024"
    }
  ],
  "departments": [
    {
      "name": "Roastery",
      "parent": null
    },
    {
      "name": "Retail",
      "parent": {
        "name": "Operations"
      }
    }
  ],
  "ein": "84-3927115",
  "entity": {
    "subtype": "s_corporation",
    "type": "corporation"
  },
  "id": "d7c1f0aa-4b52-4c9e-8a31-6e2b5d9c7f10",
  "legal_name": "Sterling Wharf Coffee Roasters, Inc.",
  "locations": [
    {
      "city": "Seattle",
      "country": "US",
      "line1": "1420 Alaskan Way",
      "line2": "Suite 300",
      "postal_code": "98101",
      "state": "WA"
    }
  ],
  "primary_email": "people@sterlingwharf.example",
  "primary_phone_number": "+1-206-555-0142"
}

Get connection details

Read what this connection actually is: which employer and payroll provider it points at, and which products it was authorised for. Start here when another step fails with a permission error - 'products' is the authoritative list of what this token may read.

Inputs

None.

Outputs

authentication_methodslist
client_idtext
client_typetext
company_idtext
connection_idtext
connection_typetext
idtext
payroll_provider_idtext
productslist
provider_idtext
usernametext

Example output

{
  "client_id": "5c1f0a7d-2b93-4e18-8a6f-71c0d4b39e52",
  "client_type": "sandbox",
  "company_id": "d7c1f0aa-4b52-4c9e-8a31-6e2b5d9c7f10",
  "connection_id": "ec42a7b9-3d15-4c80-9f6a-2b18d0c7e594",
  "connection_type": "provider",
  "id": "b3d81f27-59c4-4a0e-91d7-5f2a6c48e310",
  "products": [
    "company",
    "directory",
    "individual",
    "employment",
    "payment",
    "pay_statement",
    "benefits"
  ],
  "provider_id": "gusto"
}

Get data sync job

Read one data-sync job: whether it is pending, running, complete or failed, and when it ran. Use it to wait for a sync to finish before reading payroll data that depends on it.

Inputs

Job IDjob_idtextRequired: The job to read, from a 'List data sync jobs' step.

Outputs

completed_attext
created_attext
job_idtext
job_urltext
paramsobject
scheduled_attext
started_attext
statustext
typetext

Example output

{
  "completed_at": "2026-08-30T02:18:41Z",
  "created_at": "2026-08-30T02:15:00Z",
  "job_id": "a0f3c7d1-8b24-4e59-91c6-3d70a5e28b14",
  "status": "complete",
  "type": "data_sync_all"
}

Get employments

Read employment records for the individuals named - job title, employment type and status, start and end dates, manager, department, work location, and current and historical pay rates. IDs Finch cannot resolve come back under 'errors' while the rest still return.

Inputs

Individual IDsindividual_idslistRequired: Finch individual IDs to look up. Accepts a list, a single ID, or the records from a 'List directory' step - their 'id' is read for you.

Outputs

countnumber: Records returned
employmentslist: The employment records Finch could resolve
error_countnumber: How many IDs failed
errorslist: IDs Finch could not answer for, with its reason
requested_countnumber: IDs asked for

Example output

{
  "count": 1,
  "employments": [
    {
      "class_code": null,
      "department": {
        "name": "Roastery"
      },
      "employment": {
        "subtype": "full_time",
        "type": "employee"
      },
      "employment_status": "active",
      "end_date": null,
      "first_name": "Dana",
      "flsa_status": "non_exempt",
      "id": "5cbf7c8c-3f4c-4b1e-9d6b-2f0a1c9d4e77",
      "income": {
        "amount": 7200000,
        "currency": "usd",
        "effective_date": "2025-01-01",
        "unit": "yearly"
      },
      "individual_id": "5cbf7c8c-3f4c-4b1e-9d6b-2f0a1c9d4e77",
      "is_active": true,
      "last_name": "Okafor",
      "location": {
        "city": "Seattle",
        "country": "US",
        "state": "WA"
      },
      "manager": {
        "id": "1a7d9e30-88bb-4c6f-9a2e-5d40b7c1e982"
      },
      "start_date": "2022-03-14",
      "title": "Lead Roaster"
    }
  ],
  "error_count": 0,
  "errors": [],
  "requested_count": 1
}

Get individuals

Read personal profiles for the individuals named - preferred name, date of birth, home address, emails and phone numbers. Finch answers each ID separately, so IDs it cannot resolve come back under 'errors' while the rest still return.

Inputs

Individual IDsindividual_idslistRequired: Finch individual IDs to look up. Accepts a list, a single ID, or the records from a 'List directory' step - their 'id' is read for you.
Also includeincludelist: Sensitive fields to include. Finch redacts a social security number unless it is asked for by name, and only returns it if this connection is scoped for it.One or more of: ssn (Social security number).

Outputs

countnumber: Records returned
error_countnumber: How many IDs failed
errorslist: IDs Finch could not answer for, with its reason
individualslist: The profiles Finch could resolve
requested_countnumber: IDs asked for

Example output

{
  "count": 1,
  "error_count": 0,
  "errors": [],
  "individuals": [
    {
      "dob": "1991-04-17",
      "emails": [
        {
          "data": "dana.okafor@sterlingwharf.example",
          "type": "work"
        }
      ],
      "ethnicity": "decline_to_specify",
      "first_name": "Dana",
      "gender": "female",
      "id": "5cbf7c8c-3f4c-4b1e-9d6b-2f0a1c9d4e77",
      "individual_id": "5cbf7c8c-3f4c-4b1e-9d6b-2f0a1c9d4e77",
      "last_name": "Okafor",
      "marital_status": "single",
      "phone_numbers": [
        {
          "data": "+1-206-555-0188",
          "type": "personal"
        }
      ],
      "preferred_name": "Dee",
      "residence": {
        "city": "Seattle",
        "country": "US",
        "line1": "88 Beacon Hill Rd",
        "postal_code": "98109",
        "state": "WA"
      }
    }
  ],
  "requested_count": 1
}

Get pay group

Read one pay group, with the IDs of everyone in it and how often it is paid.

Inputs

Pay grouppay_group_idtextRequired: The pay group to read. Pick one, or paste a Finch pay group ID.

Outputs

idtext
individual_idslist
nametext
pay_frequencieslist

Example output

{
  "id": "7c9a1b44-0e52-4d18-b6f3-92a4d0e18c55",
  "individual_ids": [
    "5cbf7c8c-3f4c-4b1e-9d6b-2f0a1c9d4e77"
  ],
  "name": "Hourly - Bi-weekly",
  "pay_frequencies": [
    "bi_weekly"
  ]
}

Get pay statements

Read the per-employee pay statements behind one or more payroll runs: every earning, tax, employee deduction and employer contribution, with the employer's own name for each line alongside Finch's normalised type. Amounts are in the currency's minor units, so 276900 is $2,769.00.

Inputs

Payment IDspayment_idslistRequired: Finch payment IDs, from a 'List payments' step. Accepts a list, a single ID, or that step's records.
Page sizelimitnumber: How many records to return, 1-1000. Defaults to 100.From 1 to 1000. Default: 100.
Start atoffsetnumber: How many records to skip before this page. Use the 'next_offset' from a previous run to read the following page.From 0 to 1000000. Default: 0.

Outputs

countnumber: Records returned
error_countnumber: How many IDs failed
errorslist: IDs Finch could not answer for, with its reason
pay_statementslist: One group of pay statements per payroll run
pendinglist: IDs whose data Finch is still fetching from the provider; these usually succeed on a later run
pending_countnumber: How many IDs are still syncing
requested_countnumber: IDs asked for

Example output

{
  "count": 1,
  "error_count": 0,
  "errors": [],
  "pay_statements": [
    {
      "paging": {
        "count": 1,
        "offset": 0
      },
      "pay_statements": [
        {
          "earnings": [
            {
              "amount": 276900,
              "currency": "usd",
              "hours": 80,
              "name": "Regular",
              "type": "salary"
            }
          ],
          "employee_deductions": [
            {
              "amount": 13800,
              "currency": "usd",
              "name": "401(k)",
              "pre_tax": true,
              "type": "401k"
            }
          ],
          "employer_contributions": [
            {
              "amount": 13800,
              "currency": "usd",
              "name": "401(k) match",
              "type": "401k"
            }
          ],
          "gross_pay": {
            "amount": 276900,
            "currency": "usd"
          },
          "individual_id": "5cbf7c8c-3f4c-4b1e-9d6b-2f0a1c9d4e77",
          "net_pay": {
            "amount": 210400,
            "currency": "usd"
          },
          "payment_method": "direct_deposit",
          "taxes": [
            {
              "amount": 41500,
              "currency": "usd",
              "employer": false,
              "name": "Federal Income Tax",
              "type": "federal"
            }
          ],
          "total_hours": 80,
          "type": "regular_payroll"
        }
      ],
      "payment_id": "9b2e4a11-7c33-4a2f-8d5e-16b0c7a94d21"
    }
  ],
  "requested_count": 1
}

List benefits

List every benefit the employer offers, with its normalised type, the employer's own description of it, how often it is deducted, and the company's contribution rule.

Inputs

None.

Outputs

benefitslist: The benefits this employer offers
countnumber: Records on this page
has_moretrue/false: Whether a page follows
total_countnumber: Records matching in total, when Finch reports one

Example output

{
  "benefits": [
    {
      "benefit_id": "f1b6a0d5-2c48-49ab-9e73-0a5d3c81b6f4",
      "company_contribution": {
        "amount": 400,
        "type": "percent"
      },
      "description": "Company 401(k)",
      "frequency": "every_paycheck",
      "type": "401k"
    }
  ],
  "count": 1,
  "has_more": false
}

List data sync jobs

List the data-sync jobs Finch has run for this connection, most recent first, with the status of each. A 'reauth_error' or 'permissions_error' here is why other steps started returning stale or empty data - both mean the employer has to reconnect.

Inputs

Page sizelimitnumber: How many records to return, 1-1000. Defaults to 100.From 1 to 1000. Default: 100.
Start atoffsetnumber: How many records to skip before this page. Use the 'next_offset' from a previous run to read the following page.From 0 to 1000000. Default: 0.

Outputs

countnumber: Records on this page
has_moretrue/false: Whether a page follows
jobslist: Data sync jobs for this connection
next_offsetnumber: The 'offset' that reads the next page
total_countnumber: Records matching in total, when Finch reports one

Example output

{
  "count": 1,
  "has_more": false,
  "jobs": [
    {
      "completed_at": "2026-08-30T02:18:41Z",
      "created_at": "2026-08-30T02:15:00Z",
      "job_id": "a0f3c7d1-8b24-4e59-91c6-3d70a5e28b14",
      "scheduled_at": "2026-08-30T02:15:00Z",
      "started_at": "2026-08-30T02:15:07Z",
      "status": "complete",
      "type": "data_sync_all"
    }
  ]
}

List directory

List everyone in the employer's directory - name, department, manager and whether they are currently active - a page at a time. This is the index: use the IDs it returns with 'Get individuals' or 'Get employments' to read someone's detail.

Inputs

Page sizelimitnumber: How many records to return, 1-1000. Defaults to 100.From 1 to 1000. Default: 100.
Start atoffsetnumber: How many records to skip before this page. Use the 'next_offset' from a previous run to read the following page.From 0 to 1000000. Default: 0.

Outputs

countnumber: Records on this page
has_moretrue/false: Whether a page follows
individualslist: Everyone on this page of the directory
next_offsetnumber: The 'offset' that reads the next page
total_countnumber: Records matching in total, when Finch reports one

Example output

{
  "count": 2,
  "has_more": false,
  "individuals": [
    {
      "department": {
        "name": "Roastery"
      },
      "first_name": "Dana",
      "id": "5cbf7c8c-3f4c-4b1e-9d6b-2f0a1c9d4e77",
      "is_active": true,
      "last_name": "Okafor",
      "manager": {
        "id": "1a7d9e30-88bb-4c6f-9a2e-5d40b7c1e982"
      },
      "middle_name": null
    },
    {
      "department": {
        "name": "Operations"
      },
      "first_name": "Priya",
      "id": "1a7d9e30-88bb-4c6f-9a2e-5d40b7c1e982",
      "is_active": true,
      "last_name": "Raman",
      "manager": null,
      "middle_name": "R"
    }
  ],
  "total_count": 2
}

List enrolled individuals

List the IDs of everyone enrolled in one benefit. Pair it with 'Get individuals' to put names to them, or with 'Get benefit enrollments' for each person's own contribution settings.

Inputs

Benefitbenefit_idtextRequired: The benefit to read. Pick one, or paste a Finch benefit ID.

Outputs

benefit_idtext
countnumber: How many people are enrolled
individual_idslist

Example output

{
  "benefit_id": "f1b6a0d5-2c48-49ab-9e73-0a5d3c81b6f4",
  "count": 1,
  "individual_ids": [
    "5cbf7c8c-3f4c-4b1e-9d6b-2f0a1c9d4e77"
  ]
}

List pay groups

List the employer's pay groups and how often each is paid. Filter to the groups one person belongs to, or to particular pay frequencies. Not every payroll provider reports pay groups; an empty list means this one does not.

Inputs

Individual IDindividual_idtext: Only return the pay groups this person belongs to. Leave empty for all of them.
Pay frequenciespay_frequencieslist: Only return groups paid this often.One or more of: annually, semi_annually (Semi-annually), quarterly, monthly, semi_monthly (Semi-monthly), bi_weekly (Bi-weekly), weekly, daily, other.

Outputs

countnumber: Records on this page
has_moretrue/false: Whether a page follows
pay_groupslist: The employer's pay groups
total_countnumber: Records matching in total, when Finch reports one

Example output

{
  "count": 1,
  "has_more": false,
  "pay_groups": [
    {
      "id": "7c9a1b44-0e52-4d18-b6f3-92a4d0e18c55",
      "name": "Hourly - Bi-weekly",
      "pay_frequencies": [
        "bi_weekly"
      ]
    }
  ]
}

List pay statement items

List the distinct earnings, taxes, deductions and employer contributions this employer's payroll actually uses - the catalogue of line items, not any one person's amounts. This is what to read before mapping a payroll into another system.

Inputs

Categoriescategorieslist: Only return items in these categories.One or more of: earnings, taxes, employee_deductions (Employee deductions), employer_contributions (Employer contributions).
Fromstart_datedate: Only include items seen on pay statements from this date onwards.
Toend_datedate: Only include items seen on pay statements up to this date.
Namenametext: Only return items the employer calls this, such as 'Regular' or '401(k)'.
Typeitem_typetext: Only return items of this normalised Finch type, such as 'salary' or '401k'.

Outputs

countnumber: Records on this page
has_moretrue/false: Whether a page follows
itemslist: The line items this employer's payroll uses
total_countnumber: Records matching in total, when Finch reports one

Example output

{
  "count": 2,
  "has_more": false,
  "items": [
    {
      "attributes": {
        "employer": false,
        "metadata": {},
        "pre_tax": false,
        "type": "salary"
      },
      "category": "earnings",
      "name": "Regular"
    },
    {
      "attributes": {
        "employer": false,
        "metadata": {},
        "pre_tax": true,
        "type": "401k"
      },
      "category": "employee_deductions",
      "name": "401(k)"
    }
  ]
}

List payments

List the employer's payroll runs whose pay date falls in a date range, with gross and net pay, employee and employer taxes, the company debit, and the pay period each covers. Both dates are required - Finch refuses an unbounded query. Use the payment IDs with 'Get pay statements' for per-person detail.

Inputs

Fromstart_datedateRequired: Earliest pay date to include, inclusive.
Toend_datedateRequired: Latest pay date to include, inclusive.

Outputs

countnumber: Records on this page
has_moretrue/false: Whether a page follows
paymentslist: Payroll runs in the date range
total_countnumber: Records matching in total, when Finch reports one

Example output

{
  "count": 1,
  "has_more": false,
  "payments": [
    {
      "company_debit": {
        "amount": 4182300,
        "currency": "usd"
      },
      "debit_date": "2026-08-12",
      "employee_taxes": {
        "amount": 616100,
        "currency": "usd"
      },
      "employer_taxes": {
        "amount": 261900,
        "currency": "usd"
      },
      "gross_pay": {
        "amount": 3410000,
        "currency": "usd"
      },
      "id": "9b2e4a11-7c33-4a2f-8d5e-16b0c7a94d21",
      "individual_ids": [
        "5cbf7c8c-3f4c-4b1e-9d6b-2f0a1c9d4e77"
      ],
      "net_pay": {
        "amount": 2588400,
        "currency": "usd"
      },
      "pay_date": "2026-08-14",
      "pay_frequencies": [
        "bi_weekly"
      ],
      "pay_group_ids": [
        "7c9a1b44-0e52-4d18-b6f3-92a4d0e18c55"
      ],
      "pay_period": {
        "end_date": "2026-08-09",
        "start_date": "2026-07-27"
      }
    }
  ]
}

List providers

List every payroll and HR system Finch can connect to, with the products each supports and how it authenticates. This is Finch's own catalogue rather than anything about the current connection, so it answers the same whichever employer is connected - useful for checking coverage before asking one to connect.

Inputs

None.

Outputs

countnumber: Records on this page
has_moretrue/false: Whether a page follows
providerslist: Systems Finch can connect to
total_countnumber: Records matching in total, when Finch reports one

Example output

{
  "count": 1,
  "has_more": false,
  "providers": [
    {
      "beta": false,
      "display_name": "Gusto",
      "id": "gusto",
      "mfa_required": false,
      "products": [
        "company",
        "directory",
        "individual",
        "employment",
        "payment",
        "pay_statement",
        "benefits"
      ]
    }
  ]
}

List supported benefits

List which benefit types this employer's payroll provider supports through Finch, and what may be set on each - the frequencies allowed, the deduction and contribution styles, and whether annual maximums and catch-up contributions apply. Support varies by provider, and this is the only endpoint that says so.

Inputs

None.

Outputs

countnumber: Records on this page
has_moretrue/false: Whether a page follows
supported_benefitslist: Benefit types this provider supports
total_countnumber: Records matching in total, when Finch reports one

Example output

{
  "count": 1,
  "has_more": false,
  "supported_benefits": [
    {
      "annual_maximum": true,
      "catch_up": true,
      "company_contribution": [
        "fixed",
        "percent"
      ],
      "description": "401(k)",
      "employee_deduction": [
        "fixed",
        "percent"
      ],
      "frequencies": [
        "every_paycheck"
      ],
      "type": "401k"
    }
  ]
}

ActionsCopy Anchor Link

Get benefitCopy Anchor Link

Inputs

Outputs

Get benefit enrollmentsCopy Anchor Link

Inputs

Outputs

Get companyCopy Anchor Link

Inputs

Outputs

Get connection detailsCopy Anchor Link

Inputs

Outputs

Get data sync jobCopy Anchor Link

Inputs

Outputs

Get employmentsCopy Anchor Link

Inputs

Outputs

Get individualsCopy Anchor Link

Inputs

Outputs

Get pay groupCopy Anchor Link

Inputs

Outputs

Get pay statementsCopy Anchor Link

Inputs

Outputs

List benefitsCopy Anchor Link

Inputs

Outputs

List data sync jobsCopy Anchor Link

Inputs

Outputs

List directoryCopy Anchor Link

Inputs

Outputs

List enrolled individualsCopy Anchor Link

Inputs

Outputs

List pay groupsCopy Anchor Link

Inputs

Outputs

List pay statement itemsCopy Anchor Link

Inputs

Outputs

List paymentsCopy Anchor Link

Inputs

Outputs

List providersCopy Anchor Link

Inputs

Outputs

List supported benefitsCopy Anchor Link

Inputs

Outputs

On this page

Actions

Get benefit

Get benefit enrollments

Get company

Get connection details

Get data sync job

Get employments

Get individuals

Get pay group

Get pay statements

List benefits

List data sync jobs

List directory

List enrolled individuals

List pay groups

List pay statement items

List payments

List providers

List supported benefits