Write Payroll Deductions & Contributions

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:

• Create a New Benefit
• Enroll Individuals
• Unenroll Individuals

​

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 benefits
• GET /employer/benefits/{benefit_id} to list benefit information for a given benefit
• GET /employer/benefits/{benefit_id}/enrolled to list individuals currently enrolled in a given benefit
• GET /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 deduction
• POST /employer/benefits/{benefit_id}/individuals to enroll employee(s) in an existing benefit or deduction
• POST /employer/benefits/{benefit_id} to update an existing company-wide benefit or individual deduction
• DELETE /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.

• Read more about Assisted Deductions

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 deduction
• POST /employer/benefits/{benefit_id}/individuals to enroll employee(s) in an existing benefit or deduction
• POST /employer/benefits/{benefit_id} to update an existing company-wide benefit or individual deduction
• GET /employer/benefits/meta to list the available benefit types and configurations for the provider associated with the access token
• 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.

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.

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

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.

​

Learn more

• Deductions API
• Supported Providers
• Integration Types: Assisted