Our Deductions product allows developers to write payroll contributions and deductions changes for retirement, medical, and other benefit use cases. Finch Deductions APIs operate at two levels: the company-level and the individual-level. Company-level APIs allow you to create and update deductions at the company-level. For automated integrations you can also read company-level deductions. Individual-level APIs allow you to enroll and un-enroll individuals in deductions, and update their individual-level configurations. For automated integrations you can also read individual-level enrollments.

​
Identify Supported Providers

Before implementing our Deductions APIs, make sure you identify providers that support the types of deductions and features your use case requires.

​
Assisted vs Automated Integrations Deductions Support

You can identify which providers are automated and assisted using our Provider Network.

​
Automated Integrations

  • Both reading and writing are supported.
  • Writing is performed near-real-time in the provider.
  • Reading provides state of the system when the request is executed.
  • No configuration period.

​
Assisted Integrations

​
Use the providers endpoint or field support matrix to identify provider that support your use case

The types and features of each deduction can vary between providers. Providers have varying limitations on which operations are available and which actions can be performed. Finch provides two tools to help you identify the types and features of deductions available for a given provider.
  1. Providers Endpoint - The providers endpoint provides a list of all providers and the types of deductions they support.
  2. Field Support Matrix - The Field Support Matrix provides a list of all providers and the types of deductions they support, as well as the features available for each deduction type.
If you try to make a request using an access token that does not allow a certain configuration or deduction type, our API will respond with a 400 or 422 status code (see Errors), depending on the error. This endpoint can help you avoid those errors by understanding beforehand what types of requests you can make.

​
Prepare for provider limitations when creating company level deductions

Some providers do not allow creation of company level deductions using the Finch API (Create Deduction). Use the providers endpoint or field support matrix explained above to identify providers that do not support this for deductions. For those providers, you should confirm with the employer that the correct deduction is set up in their system prior to enrolling individuals through Finch. Then use the Register (assisted integrations) or Get All Deductions (automated integrations) endpoints to get the deduction_id for the company level deduction. Then you can enroll and update invidual level deductions. If you try to enroll an employee in a deduction that is not set up, you may receive a 422 response code from Finch indicating that the deduction is not set up by the employer. In these cases, you should reach back out to the employer to ensure the deduction has been correctly set up.

​
Getting and Creating Company Level Deductions

Before your application can manage individual enrollments and updates for individuals, your system needs the Finch benefit_id for the company wide deduction that the individual is or will be enrolled in. The Finch Deduction API has three endpoints that return a benefit_id in the response body. For example, a creation request will respond with: 
{
  "benefit_id": "e8b90071-0c11-471c-86e8-e303ef2f6782",
  "job_id": "be1b3351-a88e-46c2-96e4-c2cf38e529a7"
}
Your application will use this benefit_id to perform enrollment, un-enrollment, and deduction retrieval actions on individuals. Your application can use the job_id and the Retrieve a Manual Job endpoint to get the status of the job. The valid job status responses will be either pending, in_progress, complete, or error with a response body further explaining the response. Create Deduction, Register Deduction, and Get All Deductions are the endpoints that return a benefit_id to use for enrolling and updating individual deductions and contributions. Your application should use the appropriate endpoint based on if the connection is automated or assisted for deductions and if the deduction already exists in the provider system.
EndpointDescriptionAutomated/Assited Support
Get All DeductionsGet all existing company-wide deductions and contributionsAutomated Only
Register DeductionRegister one existing company-wide deduction or contributionAutomated and Assisted
Create DeductionCreate a new company-wide deduction or contribution (not supported for all providers)Automated and Assisted

​
Enrolling and Unenrolling Individuals

​
Creating new individual enrollments

To enroll a new individual for a contribution or deduction, use the benefit_id returned from the appropriate deductions endpoints above, and make a request to POST /benefits/{benefit_id}/individuals request. This is a batch request endpoint. In the request body, you should provide a list of objects. Each object will specify the individual_id (from the directory endpoint in Organization), and a configuration object which specifies the enrollment configuration to applies to that individual Use the API Reference to identify which fields should be included in the object for specific types of deductions. Note that none are required by our API, but the provider may require specific fields and return an error if they are not included.

​
Updating existing individual enrollments

To update the enrollment for currently enrolled individuals, use the same POST /benefits/{benefit_id}/individuals endpoint that you use to enroll new individuals. When updating an existing enrollment for an individual, the enrollment configuration will be completely overwritten with the new configuration provided in the request, so please make sure to include the entire desired configuration. Since they both use the same endpoint, these update requests can be submitted in the same batch request as new enrollment requests.

​
Un-enrolling individuals

You can unenroll individuals by using the DELETE /benefits/{benefit_id}/individuals endpoint. This will remove the enrollment configuration for an individual.

​
Automated Deductions

Automated deductions run asyncronously and will return a job id. Use the jobs endpoint to check the status of the job, including if the job completed and succeeded. Automated integrations support the reading and writing of deductions and contributions from providers: Read:
  • GET /employer/benefits to list all company-wide deductions
  • GET /employer/benefits/{benefit_id} to list deduction information for a given deduction
  • GET /employer/benefits/{benefit_id}/enrolled to list individuals currently enrolled in a given deduction
  • GET /employer/benefits/{benefits_id}/individuals to get enrollment information for the given individuals
Write:
  • POST /employer/benefits to create a new company-wide deduction or individual deduction
  • POST /employer/benefits/{benefit_id}/individuals to enroll employee(s) in an existing deduction
  • POST /employer/benefits/{benefit_id} to update an existing company-wide deduction
  • DELETE /employer/benefits/{benefit_id}/individuals* to unenroll individuals from a deduction

​
Assisted Deductions

Assisted requests are fulfilled by our operations team, and so have slight differences in behavior and functionality compared to automated integrations. Assisted integrations only support writing of deductions to providers:
  • POST /employer/benefits to create a new company-wide deduction
  • POST /employer/benefits/{benefit_id}/individuals to enroll employee(s) in an existing company level deduction
  • POST /employer/benefits/{benefit_id} to update an existing company-wide deduction
  • DELETE /employer/benefits/{benefit_id}/individuals* to unenroll individuals from a deduction
For providers which support Deductions via Assisted, the response you receive from the /employer/benefits endpoints will contain a job_id. While our dedicated product operations team makes the necessary changes in the provider’s system, you can continue to call  GET /jobs/{job_id} to get the status of the job. The valid job status responses will be either pending, in_progress, complete, or error with a response body further explaining the response. See our API Reference for example responses for all the deductions endpoints.

​
Note about job endpoints

For all deduction jobs, both automated and assisted, you can call either  GET /jobs/{job_id} or the retrieve a manual job endpoint to check the job status and response body.

​
Deduction Sequence Diagram

The following diagram shows the basic deductions flow. It can be used with either Register or Create endpoints to obtain the benefit_id. The flow is very similar for use with the Get All Deductions (automated integrations only) except that your application will need to handle a response with multiple benefit objects (see the API reference for response fields and examples). deductions flow.png

​
Handling Failures

Managing deductions and contributions is a time and money-sensitive activity. Therefore, in the unlikely event that a request through Finch fails, we recommend that your team have a process in place to handle enrollments or to inform employers. We recommend leaving adequate buffer between request submission via Finch and payroll cutoff dates to account for time to address issues. Our recommendation is that you submit a request with enough time to have at least 1 day between the response from Finch and the cutoff date. For an automated connection, that means submitting the request at least 24 hours before the cutoff. For an assisted connection, the recommended time is 3 days to account for the 2 day SLA. Enrollment and un-enrollment requests and responses are batched. This means that some enrollments/un-enrollments could succeed while others fail. For both automated and assisted integrations expect a job_id in the response body. You can use this job_id to get the status of the job and see which individuals were successfully enrolled or un-enrolled.
Top-level
{
  "job_id": "497d98f3-580a-4ab9-830a-af2346d029b2",
  "status": "complete",
  "body": [
    {
      "individual_id": "430f9d95-1dcf-4b99-b616-45f814416890",
      "code": 500,
      "message": "Internal server error"
    },
    {
      "individual_id": "647975ac-1e0f-4e9c-b705-e3042da48581",
      "code": 404,
      "message": "Individual not found"
    }
  ]
}

​
General Deductions Schedule

Since enrolling individuals in deductions and contributions can be a sensitive activity, it is helpful to understand some of the nuances around payroll in general.

​
How do payroll deductions work?

Each payroll contains four important dates to know.
  1. Payroll Start Date - The first day of the pay period
  2. Payroll End Date - The last day of the pay period
  3. Payroll Close Date - The last date to make changes for that pay period
  4. Paycheck Date - The date on which employees are paid
Note - You can get the payroll start_date, end_date, and the pay_date for past pay statements using our pay statement API, but our system cannnot provide the payroll close date. You will need to either get that information from the employer or set expectations for update based on their close date generically

​
Timing submissions

It is important to submit any employee deductions and contribution changes before the pay close date in order to take affect for the current pay period. If any changes are submitted after the payroll close date, they will only affect the next pay period, not the current. Since each payroll close date is different per provider, it is important to know this date and set proper expectations with your customers. For assisted connections, it is important to submit payroll deductions to our API 3 days before the customer’s payroll close date. This will help ensure that changes can be processed within the current payroll period (unless an effective_date for a future payroll period is explicitly specified in your API request). Otherwise, the change will be executed on the next payroll period. Effective Date
  • The effective_date parameter can be used to specify a future date on which the change should take effect. The use case for including an effective_date is for when your system is making a call during the current payroll period, but it should take effect in a future payroll period.
  • If the effective_date is not specified, the change will take effect on the payroll period that the change is processed.
  • The effective_date will not work for retroactive (past payroll periods). If you need to make a contribution or deduction change for a past payroll period, you should confirm with the employer that you can process a one time deduction. To do this you would create a company wide deduction with a frequency of one_time and enroll the individual in that deduction. It will process once for the next payroll period that is is processed in time for. Note that not all deduction types and systems support frequecy of one_time.
  • For automated integrations, effective dates in the past will be processed as now since we cannot retroactively set the dates.
  • For assisted integrations, the effective_date will be entered into the provider system if the field is available and the date is within the allowed range. For future effective dates, we will run the job on the effective date and the job status will remain as pending until all requests in the batch complete (complete can be either succeed or fail). Note that there is limited support for past effective dates and those will process on the current date if not supported by the provider.”
Batch Requests by Effective Date Note - effective_date is optional
  • If you are inluding effective_date, we recommend that you batch requests by effective_date since a batched job will not complete and return a response until all requests in the batch have been processed.
  • For all requests, you will receive a job_id in the response body. You can use this job_id to check the status of the job and see if the request was successful or if there were any errors. Note, a completed job does not mean that the request was successful for all individuals. You should check the response body for each individual to see if there were any errors or if the request was successful. If the effective_date can be entered into the provider system, the job will be completed asap, else we will wait until the effective date to process the request
Example As an example, if the payroll period is June 1 - 15. The payroll close date might be June 16 so payroll can be processed before Friday, June 17. Therefore, it would be important to submit payroll deductions via the Finch API by June 13 for those to take effect during the June 1 - 15 payroll. 
June 2022
Su Mo Tu We Th Fr Sa
01 02 03 04 05 06 07
08 09 10 11 12 13 14
15 16 17 18 19 20 21
22 23 24 25 26 27 28
29 30
Some payroll providers offer a dedicated payroll representative to help with making payroll changes. If a payroll rep is helping your customer’s HR admin with changes in their system, it is important that you make it explicitly clear who does what so that the payroll rep does not overwrite any changes Finch has previously made. Calling out Benefit Code types and using thoughtful descriptions (e.g. with your company name) help.

​
FAQs

Question Are all deductions requests processed First In First Out (FIFO)? Answer If requests do not include an effective_date, the requests are processed in the order they are received. If you submit multiple requests for the same individual the last request processed will overwrite any previous requests. For requests that include an effective_date, those enroll requests will be processed on the future effective_date rather than the order in which they are received. Question What happens if I submit an enroll request for an individual who is already enrolled in a deduction? Answer If you submit an enroll request for an individual who is already enrolled in a deduction, the existing enrollment will be updated with the new configuration provided in the request. The status of the request will be a 200 instead of a 201. Question How does including an effective_date affect when the request is processed? For example, if for the same individual we submit multiple requests with different effective dates, will the requests still be processed in the order they are received or by effective_date? Answer The effective_date parameter determines when the request is processed in the provider system. The request will be processed on the effective_date, which must be in the future. Requests should be batched by effective_date, and the order of processing will be based on the effective_date rather than the order in which they are received. If you submit multiple requests with different effective_dates for the same individual, the last request with the latest effective_date will overwrite any previous requests. Question Is the effective_date that is included in the request, the date that is input into the provider’s system? Answer For assisted integrations The effective_date that is submitted will be entered into the provider system if the field is available and the date is within the allowed range. effective_date is not supported across all providers, some do not accept past effective dates, and some have a limited future window for dates. For automated integrations, we do not enter an effective date into the provider system. You can expect that the enrollment will be effective for the pay period that the request is processed if it is processed before the close date of that pay period. Include an effective_date in a future pay period if you want the enrollment to be effective for that pay period.

​
Checkpoint + Next Step

After completing this step, you will have a good understanding of how to utilize the Finch Deductions API to manage company-level deductions and employee-level enrollments in a robust manner accommodating various provider limitations. Now that you have everything in place for full 360° read/write integrations, you can Prepare the Employer Experience.

​
Learn more