Skip to main content
POST
/
employer
/
benefits
/
{benefit_id}
/
individuals
JavaScript
import Finch from '@tryfinch/finch-api';

const client = new Finch({
  accessToken: 'My Access Token',
});

const enrolledIndividualBenefitResponse = await client.hris.benefits.individuals.enrollMany(
  'benefit_id',
);

console.log(enrolledIndividualBenefitResponse.job_id);
{
  "job_id": "be1b3351-a88e-46c2-96e4-c2cf38e529a7"
}
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
FieldTypeDescription
employee_deduction.typestringDeduction Type (fixed or percent)
employee_deduction.amountintegerDeduction amount in cents (if fixed) or basis points (if percent)
company_contribution.typestringContribution Type (fixed or percent)
company_contribution.amountintegerContribution amount in cents (if fixed) or basis points
catch_upbooleanWhether to enable catch up for this individual
annual_maximuminteger (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

FieldTypeDescription
employee_deduction.typestringDeduction Type (fixed or percent)
employee_deduction.amountintegerDeduction amount in cents (if fixed) or basis points (if percent)
company_contribution.typestringContribution Type (fixed or percent)
company_contribution.amountintegerContribution amount in cents (if fixed) or basis points
catch_upbooleanWhether to enable catch up for this individual
annual_maximuminteger (nullable)The annual maximum in cents for this individual
annual_contribution_limitstring (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

FieldTypeDescription
employee_deduction.typestringDeduction Type (fixed or percent)
employee_deduction.amountintegerDeduction amount in cents (if fixed) or basis points (if percent)
company_contribution.typestringContribution Type (fixed or percent)
company_contribution.amountintegerContribution amount in cents (if fixed) or basis points
effective_date*string (nullable)The date which the benefit should take effect by (mm/dd/yyyy)
  • Note: effective_dates that are undefined or in the past will default to the date the request was made. We recommend grouping enrollments by effective_date for a request. If multiple distinct effective_dates are included, the job will be in pending status until the latest effective_date enrollment is processed. Sandbox integrations do not currently support multiple distinct effective_dates within the same request.

Authorizations

​
Authorization
string
header
required

Please use your Access Token

Headers

​
Finch-API-Version
string<date>
default:2020-09-17
required

Header used to specify the version for a given API request. Current version is 2020-09-17.

Pattern: ([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]))
​
Content-Type
string
default:application/json
required

Used to indicate the original media type of the resource

Path Parameters

​
benefit_id
string
required

Query Parameters

​
entity_ids
string<uuid>[]

The entity IDs to specify which entities' data to access.

Required array length: 1 element
Example:
["550e8400-e29b-41d4-a716-446655440000"]

Body

application/json
​
individual_id
string

Finch id (uuidv4) for the individual to enroll

​
configuration
object

Response

Successfully enqueued job to enroll individuals in the benefit

​
job_id
string<uuid>
required