Skip to main content
POST
JavaScript
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 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

HSA

Section 125 Benefits, FSA, Custom Benefits

  • 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. Provide exactly one entity ID per request; a maximum of one is accepted.

Required array length: 1 element
Example:

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