Benefits Overview

The Benefits endpoints let you create and manage the benefits an employer offers, and enroll or unenroll individual employees in those benefits. This is the most involved route in the Payroll Integration API — several operations are asynchronous and return a job_id you must poll to confirm the result.

Every Benefits endpoint requires the X-TaxBandits-Version header (1.0.0) and the entity_ids query parameter (the organization ID). See the Payroll Integration API Overview for prerequisites and the response envelope.

Key elements

• entity_ids — The organization ID. Required on every call.
• benefit_id — A unique identifier returned when you create/register a benefit. Used to get, update, enroll, unenroll, and read deductions for that benefit.
• individual_id — An employee UUID from GET /organization/directory. Used to enroll and unenroll employees. See Organization.
• job_id — Returned by every asynchronous write (create, register, enroll, unenroll). Poll it with GET /jobs/manual/{job_id} to confirm the result. See Jobs.

All monetary amounts are in cents (e.g. 10000 = $100.00). Percentage amounts are in basis points (e.g. 400 = 4%).

Recommended Integration Order

Data flows between these endpoints — IDs returned by one call become inputs to the next. Follow this order end-to-end:

• Create a benefit — POST /benefits returns a benefit_id and a job_id.
• Confirm creation — poll GET /jobs/manual/{job_id} until the job completes.
• Get / update the benefit — GET /benefits/{benefit_id} reads it back; PATCH /benefits/{benefit_id} updates the description or effective date.
• Enroll individuals — POST /benefits/{benefit_id}/individuals returns a job_id; poll it to confirm each enrollment.
• Check job status — GET /jobs/manual/{job_id} shows per-individual results.
• Get the enrolled list — GET /benefits/{benefit_id}/enrolled returns the enrolled individual_id values.
• Get deductions — GET /benefits/{benefit_id}/individuals returns the deduction configuration for enrolled individuals.
• Unenroll individuals — DELETE /benefits/{benefit_id}/individuals returns a job_id; poll it to confirm each removal.

Benefits Endpoints

Method	Path	Purpose
GET	/benefits	Return all active benefits configured for the employer.
POST	/benefits	Create a benefit for the employer.
GET	/benefits/{benefit_id}	Retrieve full details of a single benefit.
PATCH	/benefits/{benefit_id}	Update the description and/or effective date of a benefit.
GET	/benefits/{benefit_id}/enrolled	Return the individual UUIDs currently enrolled in the benefit.
GET	/benefits/{benefit_id}/individuals	Return the deduction configuration for enrolled individuals.
POST	/benefits/{benefit_id}/individuals	Enroll one or more individuals in a benefit (asynchronous).
DELETE	/benefits/{benefit_id}/individuals	Unenroll one or more individuals from a benefit (asynchronous).

Supported Benefit Types

The type field identifies the kind of benefit. Use the type value (not the plan name) in requests.

Plan Name	type Value
Simple IRA	simple_ira
401(k) Traditional	401k
Flexible Spending Account – Medical (FSA)	fsa_medical
Health Savings Account (HSA)	hsa_pre
Roth 403(b) Post Tax	403b_roth
403(b) Pre-Tax	403b
Medical, Dental & Vision	mdv_pre
401(k) Roth	401k_roth
Flexible Spending Account – Dependent Care	fsa_dependent_care

An employer cannot have more than one active benefit of the same type. The only exception is mdv_pre, which allows multiple active benefits of the same type per employer (for example, separate MEDICAL, DENTAL, and VISION plans).