In this guide, you’ll learn how to write deduction and contribution changes to Finch’s deductions API endpoints.
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.
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.
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
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 | Automated and Assisted |
Create Deduction | Create a new company-wide deduction or contribution (not supported for all providers) | Automated and Assisted |
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.
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.
DELETE /benefits/{benefit_id}/individuals
endpoint. This will remove the enrollment configuration for an individual.
/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 individualsPOST /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 deductionPOST /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/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:
POST /employer/benefits/{benefit_id}/individuals
response:
DELETE /employer/benefits/{benefit_id}/individuals
Example GET /jobs/{job_id}
response after initial job submission:
GET /jobs/{job_id}
response after job is completed for a POST /employer/benefits/individuals
request with multiple individuals:
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
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
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.effective_date
is not specified, the change will take effect on the payroll period that the change is processed.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
.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.”effective_date
is optional
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.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 requestJune 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.
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_date
s 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.