> ## Documentation Index > Fetch the complete documentation index at: https://developer.tryfinch.com/llms.txt > Use this file to discover all available pages before exploring further. # 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`) | * Note: `effective_date`s 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_date`s 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_date`s within the same request. ## OpenAPI ````yaml post /employer/benefits/{benefit_id}/individuals openapi: 3.1.0 info: title: API Reference version: '2020-09-17' contact: {} description: >- The Finch HRIS API provides a unified way to connect to a multitide of HRIS systems. The API requires an access token issued by Finch. By default, Organization and Payroll requests use Finch's [Data Syncs](/developer-resources/Data-Syncs). If a request is made before the initial sync has completed, Finch will request data live from the provider. The latency on live requests may range from seconds to minutes depending on the provider and batch size. For automated integrations, Deductions requests (both read and write) are always made live to the provider. Latencies may range from seconds to minutes depending on the provider and batch size. Employer products are specified by the product parameter, a space-separated list of products that your application requests from an employer authenticating through Finch Connect. Valid product names are— - `company`: Read basic company data - `directory`: Read company directory and organization structure - `individual`: Read individual data, excluding income and employment data - `employment`: Read individual employment and income data - `payment`: Read payroll and contractor related payments by the company - `pay_statement`: Read detailed pay statements for each individual - `benefits`: Create and manage deductions and contributions and enrollment for an employer [![Open in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/21027137-08db0929-883d-4094-a9ce-dbf5a9bee4a4?action=collection%2Ffork&collection-url=entityId%3D21027137-08db0929-883d-4094-a9ce-dbf5a9bee4a4%26entityType%3Dcollection%26workspaceId%3D1edf19bc-e0a8-41e9-ac55-481a4b50790b) servers: - url: https://api.tryfinch.com description: '' security: [] tags: - name: Organization - name: Payroll - name: Deductions - name: Management - name: Sandbox paths: /employer/benefits/{benefit_id}/individuals: parameters: - schema: type: string name: benefit_id in: path required: true post: tags: - Deductions summary: Enroll Individuals in Deductions description: >- 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. operationId: post-employer-individual-benefits-benefit_id parameters: - name: entity_ids in: query required: false description: The entity IDs to specify which entities' data to access. schema: type: array items: type: string format: uuid minItems: 1 maxItems: 1 example: - 550e8400-e29b-41d4-a716-446655440000 style: form explode: true - $ref: '#/components/parameters/API-Version' - $ref: '#/components/parameters/Content-Type' requestBody: content: application/json: schema: type: array items: type: object properties: individual_id: type: string description: Finch id (uuidv4) for the individual to enroll configuration: type: object properties: employee_deduction: type: object properties: type: type: string enum: - fixed - percent amount: type: integer description: >- Amount in cents for fixed type or basis points (1/100th of a percent) for percent type company_contribution: type: object properties: type: type: string enum: - fixed - percent - tiered amount: type: integer description: >- Amount in cents for fixed type or basis points (1/100th of a percent) for percent type tiers: type: array description: >- Array of tier objects for tiered contribution matching (required when type is tiered) items: type: object properties: match: type: integer description: >- The employer match percentage in basis points (0-10000 = 0-100%) threshold: type: integer description: >- The employee contribution threshold in basis points (0-10000 = 0-100%) required: - match - threshold annual_maximum: type: integer nullable: true description: Maximum annual amount in cents annual_contribution_limit: type: string enum: - individual - family description: >- For HSA benefits only - whether the contribution limit is for an individual or family catch_up: type: boolean description: >- For retirement benefits only - whether catch up contributions are enabled effective_date: type: string format: date description: The date the enrollment will take effect examples: Retirement: value: - 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' HSA: value: - individual_id: d02a6346-1f08-4312-a064-49ff3cafaa7a configuration: employee_deduction: type: fixed amount: 10000 company_contribution: type: fixed amount: 0 annual_maximum: null annual_contribution_limit: individual Custom: value: - individual_id: string configuration: employee_deduction: type: fixed amount: 10000 company_contribution: type: fixed amount: 0 responses: '200': description: Successfully enqueued job to enroll individuals in the benefit content: application/json: schema: $ref: '#/components/schemas/EnrollIndividualBenefitResponse' examples: Success: value: job_id: be1b3351-a88e-46c2-96e4-c2cf38e529a7 '400': description: Malformed Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: Malformed Request: value: code: 400 name: bad_request_error finch_code: malformed_request message: Malformed request '404': description: Benefit Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: Not Found: value: code: 404 name: not_found_error finch_code: benefit_not_found message: Benefit not found '422': description: Unprocessable Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: Cannot Enroll: value: code: 422 name: unprocessable_request_error finch_code: unprocessable_parameters message: >- HSA enrollment are not currently available for this provider security: - bearerAuth: [] x-codeSamples: - lang: JavaScript source: >- 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); - lang: Python source: >- 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) - lang: Ruby source: >- 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) components: parameters: API-Version: name: Finch-API-Version in: header required: true schema: type: string default: '2020-09-17' format: date pattern: ([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])) description: >- Header used to specify the version for a given API request. Current version is 2020-09-17. Content-Type: name: Content-Type in: header required: true schema: type: string default: application/json description: 'Used to indicate the original media type of the resource ' schemas: EnrollIndividualBenefitResponse: type: object properties: job_id: type: string format: uuid required: - job_id Error: title: Error type: object description: Generic error response structure properties: code: type: integer description: The status code of the request. name: type: string description: Identifier describing the error. finch_code: type: string description: A descriptive identifier for the error. message: type: string description: >- A short English description that provides more information about the error. securitySchemes: bearerAuth: type: http scheme: bearer description: Please use your Access Token ````