For historical reasons, Deductions endpoints live under the
/employer/benefits path.What you can do
- Create deductions — set up a new company-level deduction in the payroll system, or register one that already exists.
- Manage enrollments — enroll individuals in a deduction with per-person amounts, update their configurations, and unenroll them.
- Read deduction state — list all company-level deductions, see who is enrolled, and read each individual’s employee and employer amounts.
Read endpoints
Write endpoints
Write requests are asynchronous: each returns a
job_id you poll for completion, and batched enrollments can partially succeed. Read the async Deductions guide for job polling, batch response handling, and payroll cutoff timing.
Provider coverage
Supported deduction types and operations vary by provider — for example, some providers do not allow Finch to create new deductions, only to manage existing ones. Call the/providers endpoint and check its benefits_support field, or review the Providers page, before you build. Some providers also require deductions setup steps before the first write.
Combine with Organization and Payroll
Deductions pairs with Finch’s read products for end-to-end control: Organization shows employment changes that affect eligibility, Payroll pay statements show whether a deduction was actually applied to a paycheck, and Deductions writes the change itself.Common use cases
- Retirement and 401(k) — set up and update employee 401(k) contributions directly in payroll.
- Tax-advantaged accounts — manage pre- and post-tax deductions for HSA, FSA, and commuter benefits.
- Employer-sponsored benefits — create and manage employer contributions alongside employee deductions.
Next steps
Deductions API reference
Request and response schemas for all Deductions endpoints.
Async Deductions guide
Job polling, batch responses, and payroll cutoff timing.
Write data
Implementation patterns for writing to payroll systems.
Provider setup
Provider-specific requirements before your first write.