Get Enrolled Individuals

Get Enrolled Individuals

Use this endpoint to return the deduction configuration for individuals enrolled in a benefit. You can filter to specific individuals with individual_ids, or omit it to return every enrolled individual.

Key Points

• Depends on — a benefit_id (from POST /benefits) and, optionally, individual_id values from GET /benefits/{benefit_id}/enrolled.
• Amounts — all monetary amounts are in cents; percentages are in basis points (400 = 4%).
• Partial results — when you request multiple individuals and some are not enrolled, the call returns 207 with a per-item code.

GET benefits/{benefit_id}/individuals 

Header Parameters

Field	Type	Description
Authorization	string	Required. Bearer token obtained from the Auth endpoint. Format: Bearer <access_token>.
X-TaxBandits-Version	string	API version string. Use 1.0.0.

Query Parameters

Field	Type	Description
entity_ids	string	The organization ID. Must be exactly one UUID.
individual_ids	string	Optional Comma-separated individual UUIDs to filter. Omit to return all enrolled individuals.

Path Parameters

Field	Type	Description
benefit_id	string	The benefit UUID from the create or list endpoints.

Response Body

Field	Type	Description
status	string	SUCCESS or FAILURE.
status_code	number	HTTP-style status code (200, 207, or 404).
message	string	Human-readable status message.
response	object[]	One entry per requested/enrolled individual.
individual_id	string	The employee UUID.
code	number	Per-item status (200 found, 404 not enrolled).
message	string	Per-item message (present when code is not 200).
body	object	Deduction configuration (null when not enrolled).
employee_deduction	object	Employee's deduction.
type	string	fixed or percent.
amount	number	Amount in cents (fixed) or basis points (percent).
annual_maximum	number	Annual cap in cents, or null.
company_contribution	object	Employer contribution (same shape as employee_deduction).
catch_up	boolean	Whether catch-up contributions apply.
effective_date	string	Effective date of the deduction (YYYY-MM-DD).
annual_contribution_limit	string	individual or family. Present only for hsa_pre benefits; omitted for all other benefit types.

Payload

Request

GET benefits/e8b90071-0c11-471c-86e8-e303ef2f6782/individuals?entity_ids=519a84f4-5e56-496a-82f3-18f51fdf3d75
Header: X-TaxBandits-Version: 1.0.0

Response Json

Sample	Description	Action
200	Success Response - Returned when all enrolled individuals are found (no filter, or all requested are enrolled).
207	Multi-Status Response - Returned when multiple individuals are requested and some are not enrolled. Check each item's code.
404	Not Found Response - Returned when a single requested individual is not enrolled in the benefit.
400	Bad Request Response - You'll get the below response when entity_ids or benefit_id is missing or invalid.

{
  "status": "SUCCESS",
  "status_code": 200,
  "message": "Request processed successfully",
  "response": [
    {
      "individual_id": "7a3f1c2d-11bb-4e6a-9c0d-f83a57e12346",
      "code": 200,
      "body": {
        "employee_deduction": {
          "type": "fixed",
          "amount": 10000,
          "annual_maximum": null
        },
        "company_contribution": {
          "type": "percent",
          "amount": 400,
          "annual_maximum": null
        },
        "catch_up": false,
        "effective_date": "2026-01-01"
      }
    }
  ]
}