Write Payroll Deductions & Contributions
In this guide, you’ll learn how to write deductions and contribution changes to Finch’s benefits API endpoint.
In addition to Reading Data via Finch, 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.
The APIs allow you to:
- Create, read, and update benefits at the company-level
- Manage enrollment amounts for company contributions and employee deductions at the individual-level
Keep in mind, not every use case will need the ability to write deductions and contributions back to the payroll provider. If you have any questions about if writing data applies to you, contact your Finch account representative.
Setup
Before implementing our Deductions APIs, make sure you consider the unique limitations of each provider:
Understand Assisted vs Automated Integrations
Specific providers are supported by either automated or assisted integations.
-
Automated integrations support both the reading and writing of deductions and contributions.
-
Assisted integrations only allow the writing of deductions and contributions.
This information is available in our provider documentation.
Using benefits metadata
The types and features of each benefit can vary between payroll systems depending on the configuration that the company has set up. For this reason, we provide a benefits_support
field on the /providers
endpoint, which will provide the types and features available for the employer whose deductions and contributions you are managing. If you try to make a request using an access token that does not allow a certain configuration or benefit 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
Providers have varying limitations on which operations are available and which actions can be performed.
For example, you should be prepared for providers which do not allow for automatic benefit creation (Paychex Flex, Paycom, Trinet, etc. ) and design your workflow to accommodate those cases. As Finch encounters new provider limitations, we add them to our Provider Field Support. For each of the limited providers, you should confirm with the employer that the correct benefits are set up in their system prior to enrolling individuals through Finch.
If you try to enroll an employee in a benefit that is not set up, you may receive a 422
response code from Finch indicating that the benefit is not set up by the employer. In these cases, you should reach back out to the employer to ensure the benefits have been correctly set up.
Getting and Creating Company Benefits
Our API allows you to both create new benefits in a payroll system and get existing benefits from the system. Both of these requests will respond with a benefit_id
in the response body. For example, a creation request will respond with:
{
"benefit_id": "e8b90071-0c11-471c-86e8-e303ef2f6782"
}
You can use this benefit_id
to perform enrollment, un-enrollment, and benefit retrieval actions on individuals.
Read our API Reference docs to understand the functionality and required parameters of each of our Deductions endpoints. Some highlights:
Enrolling and Unenrolling Individuals
Creating new enrollments
Enrolling a new individual is as simple as using the benefit_id
returned from the Deductions endpoints above, and using it in a POST /benefits/{benefit_id}/individuals
request. In the body, you should provide a list of objects which specify the enrollment, one per individual. Each object should contain a flexible configuration
object which specifies the enrollment configuration to applies to that individual. The schema of the configuration varies depending on the type of benefit you are enrolling, so please refer to the docs to ensure you are using the right schema.
Updating existing enrollments
To update enrollment configurations for currently enrolled individuals, you can 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 benefitsGET /employer/benefits/{benefit_id}
to list benefit information for a given benefitGET /employer/benefits/{benefit_id}/enrolled
to list individuals currently enrolled in a given benefitGET /employer/benefits/{benefits_id}/individuals
to get enrollment information for the given individuals
Write:
POST /employer/benefits
to create a new company-wide benefit or individual deductionPOST /employer/benefits/{benefit_id}/individuals
to enroll employee(s) in an existing benefit or deductionPOST /employer/benefits/{benefit_id}
to update an existing company-wide benefit or individual 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 benefits, deductions, and contributions to providers:
Write:
POST /employer/benefits
to create a new company-wide benefit or individual deductionPOST /employer/benefits/{benefit_id}/individuals
to enroll employee(s) in an existing benefit or deductionPOST /employer/benefits/{benefit_id}
to update an existing company-wide benefit or individual deductionGET /employer/benefits/meta
to list the available benefit 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:
{
"benefit_id": "264122c0-0216-4f21-a4cd-7b3bcddbe3fc",
"job_id": "497d98f3-580a-4ab9-830a-af2346d029b2"
}
Example POST /employer/benefits/{benefit_id}/individuals
response:
{
"job_id": "3a82a144-d168-4207-942a-a5852b11df1c"
}
This will be the same for DELETE /employer/benefits/{benefit_id}/individuals
Example GET /jobs/{job_id}
response after initial job submission:
{
"job_id": "3a82a144-d168-4207-942a-a5852b11df1c",
"code": 202,
"status": "pending"
}
Example GET /jobs/{job_id}
response after job is completed for a POST /employer/benefits/individuals
request with multiple individuals:
{
"job_id": "3a82a144-d168-4207-942a-a5852b11df1c",
"code": 207,
"status": "complete",
"body": [
{
"individual_id": "430f9d95-1dcf-4b99-b616-45f814416890",
"code": 201,
"message": "Successfully enrolled individual in benefit",
},
{
"individual_id": "647975ac-1e0f-4e9c-b705-e3042da48581",
"code": 200,
"message": "Successfully updated enrollment for individual",
},
{
"individual_id": "4a0a3b15-d3d6-41c2-a4a4-ca4ed1b68cf8",
"code": 404,
"message": "Individual not found"
},
...
]
}
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 automated providers, you should inspect the body
object of the response body to discern failures. Note that the top-level response status code will be a 207, but may be individual errors. Example:
[
{
"individual_id": "d02a6346-1f08-4312-a064-49ff3cafaa7a",
"code": 500,
"body": {
"name": "internal_server_error",
"message": "Internal sever error"
}
},
{
"individual_id": "e63c21ab-7cde-49d8-b6d6-ce208e84bf09",
"code": 500,
"body": {
"name": "internal_server_error",
"message": "Internal sever error"
}
}
]
Assisted providers will follow a similar format, but on the /jobs
endpoint instead. Example:
{
"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.
- 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
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.
Timing submissions for assisted connections
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 explicitly specified in your API request via the effective_date
request parameter). Otherwise, the change will be executed on the next payroll period.
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 benefits 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
Was this page helpful?