Enroll Individuals

Enroll Individuals

Use this endpoint to enroll one or more individuals in a benefit. This operation is asynchronous — it returns a job_id immediately and processes enrollments in the background.

Key Points

• Depends on — a benefit_id from POST /benefits and individual_id values from GET /organization/directory.
• Asynchronous — poll the returned job_id with GET /jobs/manual/{job_id} to check whether enrollment succeeded per individual.
• Limits — a maximum of 25 individuals per request. Duplicate individual_id values are automatically de-duplicated.
• Amounts — monetary amounts are in cents; percentages are in basis points (100 = 1%).

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

Path Parameters

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

Request Body

The request body is an array of individual enrollment objects (max 25).

Field	Type	Description
individual_id	string	Required. The employee UUID to enroll.
configuration	object	Required. The deduction configuration.
employee_deduction	object	Required. The employee's deduction.
type	string	Required. fixed or percent.
amount	number	Required. Fixed: positive integer in cents, <= 12 digits. Percent: integer 1-10000 (basis points, 100 = 1%).
annual_maximum	number	Optional Positive integer in cents, or null.
company_contribution	object	Optional Employer contribution.
type	string	If provided, fixed or percent.
amount	number	If provided, same rules as the employee amount.
annual_maximum	number	Optional Positive integer in cents, or null.
catch_up	boolean	Optional true / false. Only valid when the individual is catch-up eligible.
effective_date	string	Optional YYYY-MM-DD. Must be after the benefit's own effective date.
annual_contribution_limit	string	Conditionally required for the hsa_pre benefit type. Values: individual or family.

Response Body

Field	Type	Description
status	string	SUCCESS or FAILURE.
status_code	number	HTTP-style status code (e.g. 200, 400).
message	string	Human-readable status message.
response	object	The background job reference.
job_id	string	UUID of the background job. Poll it to confirm per-individual enrollment.

Payload

Request Json

Sample	Description	Action
Sample 1	Enroll one individual with a fixed employee deduction and a percent company contribution.

Sample 1

[
  {
    "individual_id": "7a3f1c2d-11bb-4e6a-9c0d-f83a57e12346",
    "configuration": {
      "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"
    }
  }
]

Response Json

Sample	Description	Action
200	Success Response - This is a sample response for successful API requests.
400	Bad Request Response - You'll get the below response when the request body fails validation.
404	Not Found Response - You'll get the below response when no benefit matches the supplied benefit_id.

{
  "status": "SUCCESS",
  "status_code": 200,
  "message": "Request processed successfully",
  "response": {
    "job_id": "be1b3351-a88e-46c2-96e4-c2cf38e529a7"
  }
}