List Benefits

List Benefits

Use this endpoint to return all active benefits configured for the employer identified by entity_ids. Call it first to check what already exists before creating new ones — an employer cannot have a duplicate active benefit of the same type (except mdv_pre).

GET benefits 

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.

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[]	Array of active benefits for the employer.
benefit_id	string	Benefit UUID. Use it for get, update, enroll, and unenroll operations.
type	string	The benefit type value (see Supported Benefit Types).
description	string	Human-readable description of the benefit.
frequency	string	Deduction frequency (e.g. every_paycheck).
effective_date	string	Effective date of the benefit (YYYY-MM-DD).
insurance_type	string	Insurance sub-type (e.g. medical, dental, vision). Present only for mdv_pre benefits; omitted for all other types.

Payload

Request

GET benefits?entity_ids=519a84f4-5e56-496a-82f3-18f51fdf3d75
Header: X-TaxBandits-Version: 1.0.0

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 entity_ids is missing or invalid.

{
  "status": "SUCCESS",
  "status_code": 200,
  "message": "Request processed successfully",
  "response": [
    {
      "benefit_id": "e8b90071-0c11-471c-86e8-e303ef2f6782",
      "type": "401k",
      "description": "Employee Retirement Plan",
      "frequency": "every_paycheck",
      "effective_date": "2025-01-01"
    }
  ]
}