POST
/
employer
/
benefits
/
{benefit_id}
/
individuals
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>'
[
  {
    "individual_id": "d02a6346-1f08-4312-a064-49ff3cafaa7a",
    "code": 201,
    "body": {
      "name": "created",
      "finch_code": "enrolled_new_benefit",
      "message": "Successfully enrolled new benefit for individual"
    }
  },
  {
    "individual_id": "e63c21ab-7cde-49d8-b6d6-ce208e84bf09",
    "code": 200,
    "body": {
      "name": "success",
      "finch_code": "updated_existing_enrollment",
      "message": "Benefit information updated for individual"
    }
  }
]

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 /meta 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_datestring (nullable)The date which the benefit should take effect by (mm/dd/yyyy) This field is currently only available for assisted benefits.

​
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_datestring (nullable)The date which the benefit should take effect by (mm/dd/yyyy) This field is currently only available for assisted benefits.

​
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_datestring (nullable)The date which the benefit should take effect by (mm/dd/yyyy) This field is currently only available for assisted benefits.

Authorizations

Authorization
string
headerrequired

Please use your Access Token

Headers

Finch-API-Version
string
default: 2020-09-17required

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

Content-Type
string
default: application/jsonrequired

Used to indicate the original media type of the resource

Path Parameters

benefit_id
string
required

Body

application/json · object[]
individual_id
string

Finch id (uuidv4) for the individual to enroll

configuration
object

Response

200 - application/json
individual_id
string
code
enum<integer>

HTTP status code. Either 201 or 200

Available options:
200,
201,
404,
403
body
object

Was this page helpful?

Get Deductions for IndividualsUnenroll Individuals from Deductions