Enroll Individuals in Deductions
Enroll an individual into a deduction or contribution. This is an overwrite operation. If the employee is already enrolled, the enrollment amounts will be adjusted. Making the same request multiple times will not create new enrollments, but will continue to set the state of the existing enrollment.
Availability: Automated and Assisted providers
This is a live request to the provider. Latencies may vary from seconds to minutes depending on the provider and number of benefits.
Making changes to an individual’s deductions may have tax consequences based on IRS regulations. Please consult a tax expert to ensure all changes being made to the system are compliant with local, state, and federal law.
Enrollment Bodies
Enrollment bodies have a common format for each benefit type, with a different configuration schema based on the benefit type. The configurations for each type are outlined below. These are general configurations and may vary per provider. Please use the /provider endpoint to view provider specific supported configurations.
Retirement Benefits
Includes 401(k), Roth 401(k), 403(b), Roth 403(b), 457, Roth 457, and Simple IRA
| Field | Type | Description |
|---|---|---|
employee_deduction.type | string | Deduction Type (fixed or percent) |
employee_deduction.amount | integer | Deduction amount in cents (if fixed) or basis points (if percent) |
company_contribution.type | string | Contribution Type (fixed or percent) |
company_contribution.amount | integer | Contribution amount in cents (if fixed) or basis points |
catch_up | boolean | Whether to enable catch up for this individual |
annual_maximum | integer (nullable) | The annual maximum in cents for this individual |
effective_date | string (nullable) | The date which the benefit should take effect by (mm/dd/yyyy) |
HSA
| Field | Type | Description |
|---|---|---|
employee_deduction.type | string | Deduction Type (fixed or percent) |
employee_deduction.amount | integer | Deduction amount in cents (if fixed) or basis points (if percent) |
company_contribution.type | string | Contribution Type (fixed or percent) |
company_contribution.amount | integer | Contribution amount in cents (if fixed) or basis points |
catch_up | boolean | Whether to enable catch up for this individual |
annual_maximum | integer (nullable) | The annual maximum in cents for this individual |
annual_contribution_limit | string (nullable) | Whether HSA is applied towards individual or family |
effective_date | string (nullable) | The date which the benefit should take effect by (mm/dd/yyyy) |
Section 125 Benefits, FSA, Custom Benefits
| Field | Type | Description |
|---|---|---|
employee_deduction.type | string | Deduction Type (fixed or percent) |
employee_deduction.amount | integer | Deduction amount in cents (if fixed) or basis points (if percent) |
company_contribution.type | string | Contribution Type (fixed or percent) |
company_contribution.amount | integer | Contribution amount in cents (if fixed) or basis points |
effective_date | string (nullable) | The date which the benefit should take effect by (mm/dd/yyyy) |
Authorizations
Please use your Access Token
Headers
Header used to specify the version for a given API request. Current version is 2020-09-17.
Used to indicate the original media type of the resource
Path Parameters
Body
Finch id (uuidv4) for the individual to enroll
Response
HTTP status code. Either 201 or 200
200, 201, 404, 403 Was this page helpful?