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);from finch import Finch
client = Finch(
access_token="My Access Token",
)
enrolled_individual_benefit_response = client.hris.benefits.individuals.enroll_many(
benefit_id="benefit_id",
)
print(enrolled_individual_benefit_response.job_id)package main
import (
"context"
"fmt"
"github.com/Finch-API/finch-api-go"
"github.com/Finch-API/finch-api-go/option"
)
func main() {
client := finchgo.NewClient(
option.WithAccessToken("My Access Token"),
)
enrolledIndividualBenefitResponse, err := client.HRIS.Benefits.Individuals.EnrollMany(
context.TODO(),
"benefit_id",
finchgo.HRISBenefitIndividualEnrollManyParams{},
)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", enrolledIndividualBenefitResponse.JobID)
}
package com.tryfinch.api.example;
import com.tryfinch.api.client.FinchClient;
import com.tryfinch.api.client.okhttp.FinchOkHttpClient;
import com.tryfinch.api.models.EnrolledIndividualBenefitResponse;
import com.tryfinch.api.models.HrisBenefitIndividualEnrollManyParams;
public final class Main {
private Main() {}
public static void main(String[] args) {
FinchClient client = FinchOkHttpClient.builder()
.fromEnv()
.accessToken("My Access Token")
.build();
EnrolledIndividualBenefitResponse enrolledIndividualBenefitResponse = client.hris().benefits().individuals().enrollMany("benefit_id");
}
}package com.tryfinch.api.example
import com.tryfinch.api.client.FinchClient
import com.tryfinch.api.client.okhttp.FinchOkHttpClient
import com.tryfinch.api.models.EnrolledIndividualBenefitResponse
import com.tryfinch.api.models.HrisBenefitIndividualEnrollManyParams
fun main() {
val client: FinchClient = FinchOkHttpClient.builder()
.fromEnv()
.accessToken("My Access Token")
.build()
val enrolledIndividualBenefitResponse: EnrolledIndividualBenefitResponse = client.hris().benefits().individuals().enrollMany("benefit_id")
}require "finch_api"
finch = FinchAPI::Client.new(access_token: "My Access Token")
enrolled_individual_benefit_response = finch.hris.benefits.individuals.enroll_many("benefit_id")
puts(enrolled_individual_benefit_response)curl --request POST \
--url https://api.tryfinch.com/employer/benefits/{benefit_id}/individuals \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: <content-type>' \
--header 'Finch-API-Version: <finch-api-version>' \
--data '
[
{
"individual_id": "d02a6346-1f08-4312-a064-49ff3cafaa7a",
"configuration": {
"employee_deduction": {
"type": "percent",
"amount": 1000
},
"company_contribution": {
"type": "percent",
"amount": 400
},
"catch_up": false,
"annual_maximum": 500000,
"effective_date": "2025-01-01T00:00:00.000Z"
}
}
]
'<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tryfinch.com/employer/benefits/{benefit_id}/individuals",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
[
'individual_id' => 'd02a6346-1f08-4312-a064-49ff3cafaa7a',
'configuration' => [
'employee_deduction' => [
'type' => 'percent',
'amount' => 1000
],
'company_contribution' => [
'type' => 'percent',
'amount' => 400
],
'catch_up' => false,
'annual_maximum' => 500000,
'effective_date' => '2025-01-01T00:00:00.000Z'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: <content-type>",
"Finch-API-Version: <finch-api-version>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"job_id": "be1b3351-a88e-46c2-96e4-c2cf38e529a7"
}{
"code": 400,
"name": "bad_request_error",
"finch_code": "malformed_request",
"message": "Malformed request"
}{
"code": 404,
"name": "not_found_error",
"finch_code": "benefit_not_found",
"message": "Benefit not found"
}{
"code": 422,
"name": "unprocessable_request_error",
"finch_code": "unprocessable_parameters",
"message": "HSA enrollment are not currently available for this provider"
}Deductions
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.
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);from finch import Finch
client = Finch(
access_token="My Access Token",
)
enrolled_individual_benefit_response = client.hris.benefits.individuals.enroll_many(
benefit_id="benefit_id",
)
print(enrolled_individual_benefit_response.job_id)package main
import (
"context"
"fmt"
"github.com/Finch-API/finch-api-go"
"github.com/Finch-API/finch-api-go/option"
)
func main() {
client := finchgo.NewClient(
option.WithAccessToken("My Access Token"),
)
enrolledIndividualBenefitResponse, err := client.HRIS.Benefits.Individuals.EnrollMany(
context.TODO(),
"benefit_id",
finchgo.HRISBenefitIndividualEnrollManyParams{},
)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", enrolledIndividualBenefitResponse.JobID)
}
package com.tryfinch.api.example;
import com.tryfinch.api.client.FinchClient;
import com.tryfinch.api.client.okhttp.FinchOkHttpClient;
import com.tryfinch.api.models.EnrolledIndividualBenefitResponse;
import com.tryfinch.api.models.HrisBenefitIndividualEnrollManyParams;
public final class Main {
private Main() {}
public static void main(String[] args) {
FinchClient client = FinchOkHttpClient.builder()
.fromEnv()
.accessToken("My Access Token")
.build();
EnrolledIndividualBenefitResponse enrolledIndividualBenefitResponse = client.hris().benefits().individuals().enrollMany("benefit_id");
}
}package com.tryfinch.api.example
import com.tryfinch.api.client.FinchClient
import com.tryfinch.api.client.okhttp.FinchOkHttpClient
import com.tryfinch.api.models.EnrolledIndividualBenefitResponse
import com.tryfinch.api.models.HrisBenefitIndividualEnrollManyParams
fun main() {
val client: FinchClient = FinchOkHttpClient.builder()
.fromEnv()
.accessToken("My Access Token")
.build()
val enrolledIndividualBenefitResponse: EnrolledIndividualBenefitResponse = client.hris().benefits().individuals().enrollMany("benefit_id")
}require "finch_api"
finch = FinchAPI::Client.new(access_token: "My Access Token")
enrolled_individual_benefit_response = finch.hris.benefits.individuals.enroll_many("benefit_id")
puts(enrolled_individual_benefit_response)curl --request POST \
--url https://api.tryfinch.com/employer/benefits/{benefit_id}/individuals \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: <content-type>' \
--header 'Finch-API-Version: <finch-api-version>' \
--data '
[
{
"individual_id": "d02a6346-1f08-4312-a064-49ff3cafaa7a",
"configuration": {
"employee_deduction": {
"type": "percent",
"amount": 1000
},
"company_contribution": {
"type": "percent",
"amount": 400
},
"catch_up": false,
"annual_maximum": 500000,
"effective_date": "2025-01-01T00:00:00.000Z"
}
}
]
'<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tryfinch.com/employer/benefits/{benefit_id}/individuals",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
[
'individual_id' => 'd02a6346-1f08-4312-a064-49ff3cafaa7a',
'configuration' => [
'employee_deduction' => [
'type' => 'percent',
'amount' => 1000
],
'company_contribution' => [
'type' => 'percent',
'amount' => 400
],
'catch_up' => false,
'annual_maximum' => 500000,
'effective_date' => '2025-01-01T00:00:00.000Z'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: <content-type>",
"Finch-API-Version: <finch-api-version>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"job_id": "be1b3351-a88e-46c2-96e4-c2cf38e529a7"
}{
"code": 400,
"name": "bad_request_error",
"finch_code": "malformed_request",
"message": "Malformed request"
}{
"code": 404,
"name": "not_found_error",
"finch_code": "benefit_not_found",
"message": "Benefit not found"
}{
"code": 422,
"name": "unprocessable_request_error",
"finch_code": "unprocessable_parameters",
"message": "HSA enrollment are not currently available for this provider"
}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.
The request body is a bare array of enrollment objects —
[ { "individual_id": …, "configuration": … } ]. Do not wrap it in an object: sending { "items": [ … ] } returns 400 Expected array but received object. In the schema below, the items. prefix labels each element of the array, not a top-level items field.Enrollment Bodies
Enrollment bodies have a common format for each benefit type, with a differentconfiguration 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) |
- Note:
effective_dates that are undefined or in the past will default to the date the request was made. We recommend grouping enrollments byeffective_datefor a request. If multiple distincteffective_dates are included, the job will be in pending status until the latesteffective_dateenrollment is processed. Sandbox integrations do not currently support multiple distincteffective_dates within the same request.
Authorizations
Please use your Access Token
Headers
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]))Used to indicate the original media type of the resource
Path Parameters
Query Parameters
The entity IDs to specify which entities' data to access. Provide exactly one entity ID per request; a maximum of one is accepted.
Required array length:
1 elementExample:
["550e8400-e29b-41d4-a716-446655440000"]
Body
application/json
Response
Successfully enqueued job to enroll individuals in the benefit
Was this page helpful?