Create Benefit

Create Benefit

Use this endpoint to create a new benefit for the employer. Pass the benefit type, a description, and an effective_date in the request body. On success, the API returns a benefit_id and a job_id — poll the job to confirm creation.

Key Points

• Returns two IDs — benefit_id (used for all subsequent benefit operations) and job_id (used to confirm the result).
• No duplicates — an employer cannot have more than one active benefit of the same type, except mdv_pre.

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

Request Body

Field	Type	Description
type	string	Required. One of the supported benefit type values. Allowed values "simple_ira", "401k", "fsa_medical", "hsa_pre", "403b_roth", "403b", "mdv_pre", "401k_roth", "fsa_dependent_care"
description	string	Required. 1-75 characters. Must contain at least one letter. Special characters < > ; { } [ ] _ \ ! : ? = are not allowed.
effective_date	string	Required. YYYY-MM-DD. Must be a valid calendar date.
insurance_type	string	Required only when type is mdv_pre. Allowed values: MEDICAL, DENTAL, VISION.

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 created benefit references.
benefit_id	string	UUID of the newly created benefit. Copy it for subsequent benefit operations.
job_id	string	UUID of the background job. Poll it to confirm creation.

Copy benefit_id for subsequent benefit operations, and copy job_id to check status via GET /jobs/manual/{job_id}. You cannot create a duplicate benefit of the same type for the same employer (except mdv_pre).

Payload

Request Json

Sample	Description	Action
Sample 1	Create a standard 401k benefit.
Sample 2	Create an mdv_pre benefit — insurance_type is required.

Sample 1

{
  "type": "401k",
  "description": "Company 401k Plan",
  "effective_date": "2025-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.
400 Duplicate	Duplicate Benefit Response - You'll get the below response when an active benefit of the same type already exists (except mdv_pre).

{
  "status": "SUCCESS",
  "status_code": 200,
  "message": "Request processed successfully",
  "response": {
    "benefit_id": "e8b90071-0c11-471c-86e8-e303ef2f6782",
    "job_id": "be1b3351-a88e-46c2-96e4-c2cf38e529a7"
  }
}