Write Deductions
In this guide, you’ll learn how to write deduction and contribution changes to Finch’s deductions API endpoints.
Our Deductions
product allows developers to write payroll contributions and deductions for retirement, medical, and fringe 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.
- Does not support effective_date param.
Assisted Integrations
- Only writing is supported.
- See Integration Types: Assisted for the most up to date SLAs for configuration period and data syncs.
- Supports effective_date param.
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.
- Providers Endpoint - The
/providers
endpoint provides a list of all providers and the types of deductions they support. - Field Support Matrix - The Field Support Matrix provides a list of all providers and the types of https://localhost:3000/implementation-guide/API-Calls/Write-Data#assisted-integrations-integrations 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:
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.
Endpoint | Description | Automated/Assited Support |
---|---|---|
Get All Deductions | Get all existing company-wide deductions and contributions | Automated Only |
Register Deduction | Register one existing company-wide deduction or contribution | Assisted Only |
Create Deduction | Create 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
Requests made for connections to automated providers will be fulfilled synchronously, so the response you receive from the /employer/benefits
endpoints will contain the results of the request.
Automated integrations support the reading and writing of deductions and contributions from providers:
Read:
GET /employer/benefits
to list all company-wide deductionsGET /employer/benefits/{benefit_id}
to list deduction information for a given deductionGET /employer/benefits/{benefit_id}/enrolled
to list individuals currently enrolled in a given deductionGET /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 deductionPOST /employer/benefits/{benefit_id}/individuals
to enroll employee(s) in an existing deductionPOST /employer/benefits/{benefit_id}
to update an existing company-wide deductionDELETE /employer/benefits/{benefit_id}/individuals
* to unenroll individuals from a deduction
Automated Deductions Sequence Diagram
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:
Write:
POST /employer/benefits
to create a new company-wide deductionPOST /employer/benefits/{benefit_id}/individuals
to enroll employee(s) in an existing company level deductionPOST /employer/benefits/{benefit_id}
to update an existing company-wide deductionGET /employer/benefits/meta
to list the available deduction types and configurations for the provider associated with the access tokenDELETE /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.
Example POST /employer/benefits
response:
Example POST /employer/benefits/{benefit_id}/individuals
response:
This will be the same for DELETE /employer/benefits/{benefit_id}/individuals
Example GET /jobs/{job_id}
response after initial job submission:
Example GET /jobs/{job_id}
response after job is completed for a POST /employer/benefits/individuals
request with multiple individuals:
These diagrams further explain the difference between the assisted and automated workflows:
Assisted Deductions Sequence Diagram
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 8 days to account for the 7 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.
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.
- Payroll Start Date - The first day of the pay period
- Payroll End Date - The last day of the pay period
- Payroll Close Date - The last date to make changes for that pay period
- 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 7 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 is only available for assisted connections.You can include it in requests for automated connections, but it will be ignored. - The
effective_date
parameter can be used to specify a future date on which the change should take effect. The use case for including aneffective_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 ofone_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 ofone_time
.
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 9 for those to take effect during the June 1 - 15 payroll.
June 2022 Su Mo Tu We Th Fr Sa 1 2 3 4 5 6 7 8 9 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.
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.