Defining Benefits

Defining employee benefit types and timing

Benefits represent payroll contributions from employees and/or employers, with defined taxability at the federal, state, and, at times, local level. For example, benefits may include both employee and employer contributions to a health insurance account, or employee contributions to a Roth 401(k) retirement account. In some cases, contributions to a 401(k) are treated as pre-tax, whereas contributions to a Roth 401(k) account are always treated as post-tax.

Use the Benefits API to create and configure benefits for your employees. The following fields are available:

  • effective_start: The date this Benefit will be considered effective. Payrolls with a payday before this date will not include the Benefit.
  • effective_end (optional): The date this Benefit will no longer be considered effective. Payrolls with a payday after this date will not include the Benefit.
  • company_contribution_amount: How much the company will contribute toward this employee benefit every payroll. Valid input is a dollar amount represented as a string, such as “100.23” for “$100.23”.
  • company_contribution_percent: How much the company will contribute toward this employee benefit every payroll, expressed as a percentage of employee earnings. Percentage based contributions are always a percentage of the payroll item's gross total. Valid input is the percentage as a float, such as “8.5” for “8.5%”.
  • employee_contribution_amount: How much the employee will contribute from their paycheck toward this employee benefit every payroll. Valid input is a dollar amount represented as a string, such as “100.23” for “$100.23”.
  • employee_contribution_percent: How much the employee will contribute from their paycheck toward this employee benefit every payroll, expressed as a percentage of employee earnings. Percentage based contributions are always a percentage of the payroll item's gross total. Valid input is the percentage as a float, such as “8.5” for “8.5%”.
  • hsa_contribution_limit (optional): The contribution limit for a HSA Benefit. Only applicable for Benefits of type hsa and must be either “single” or “family”. Default is “single”.

At least one of company_contribution_amount and company_contribution_percent must be specified, and specifying both is not allowed. This is also true for employee_contribution_amount and employee_contribution_percent.

See Types of benefits in the Check API documentation for the list of supported Benefit types. Each Benefit type has a limit on the amount that may be contributed during a given year. Check will automatically track the contribution limits of these Benefit types, and reduce the benefit contributions calculated on payrolls so that benefits are no longer contributed to once the limit has been reached.

Note: Benefits must be configured for a payroll before that payroll is run, or they will not be applied.

Creating Benefits

Create a "one-time" Benefit

This example defines a one-time employee-only contribution of $125 to a section 125 Dental plan. Note that the effective start and effective end are the same day. In order for this Benefit to be applied to the employee, the employee must have a payroll item on a payroll with a payday of “2021-04-01”.

curl -X POST \
  https://sandbox.checkhq.com/benefits \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "employee":"emp_FZEOSqW0QTKcE1iVU1C5",
      "benefit": "125_dental",
      "company_contribution_amount": "0",
      "employee_contribution_amount": "125",
      "effective_start": "2021-04-01",
      "effective_end": "2021-04-01",
      "description": "Employee Dental Plan Contribution"
   }'

Example response

{
    "id": "ben_QI3vspnG34jAZcwnrFS5",
    "employee": "emp_1ATPRmtf6XBdR6jDa9M5",
    "benefit": "125_dental",
    "description": "Employee Dental Plan Contribution",
    "effective_start": "2021-04-01",
    "effective_end": "2021-04-01",
    "company_contribution_amount": "0.00",
    "company_contribution_percent": null,
    "employee_contribution_amount": "125.00",
    "employee_contribution_percent": null,
    "hsa_contribution_limit": null
}

Create a recurring employee-only contribution

This example defines a recurring employee-only 401(k) contribution, for a set amount of $150 per pay period.

curl -X POST \
  https://sandbox.checkhq.com/benefits \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "employee":"emp_FZEOSqW0QTKcE1iVU1C5",
      "benefit": "401k",
      "company_contribution_amount": "0",
      "employee_contribution_amount": "150",
      "effective_start": "2021-04-01",
      "description": "Employee 401k plan"
   }'

Example response

{
    "id": "ben_QWLA9oP9WNVOUXYtBXvS",
    "employee": "emp_FZEOSqW0QTKcE1iVU1C5",
    "benefit": "401k",
    "description": "Employee 401k plan",
    "effective_start": "2021-04-01",
    "effective_end": null,
    "company_contribution_amount": "0.00",
    "company_contribution_percent": null,
    "employee_contribution_amount": "150.00",
    "employee_contribution_percent": null,
    "hsa_contribution_limit": null
}

Create a shared recurring Benefit

This example defines a recurring 125_medical Benefit, to which both the employer and the employee contribute. The employer contributes $275 per pay period, and the employee contributes $38.

curl -X POST \
  https://sandbox.checkhq.com/benefits \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "employee": "emp_bvNhcPxrbvRqgyCrlUcj",
      "benefit": "125_medical",
      "employee_contribution_amount": "38",
      "effective_start": "2021-04-01",
      "description": "Company sponsored medical insurance",
      "company_contribution_amount": "275"
   }'

Example response

{
    "id": "ben_gydbLvSlQiv0XYweHWeb",
    "employee": "emp_FZEOSqW0QTKcE1iVU1C5",
    "benefit": "125_medical",
    "description": "Company sponsored medical insurance",
    "effective_start": "2021-04-01",
    "effective_end": null,
    "company_contribution_amount": "275.00",
    "company_contribution_percent": null,
    "employee_contribution_amount": "38.00",
    "employee_contribution_percent": null,
    "hsa_contribution_limit": null
}

Create an HSA Benefit

This example defines an HSA Benefit with family coverage. Since the hsa_contribution_limit is passed as family, the maximum amount that will be contributed to this account will be the family limit for 2021, which is $7,200.

curl -X POST \
  https://sandbox.checkhq.com/benefits \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "employee": "emp_dF9KJgdpJMFGfXgTRctE",
      "benefit": "hsa",
      "company_contribution_amount": "0",
      "employee_contribution_amount": "375",
      "effective_start": "2021-04-01",
      "description": "HSA family",
      "effective_end": null,
      "hsa_contribution_limit": "family"
   }'

Example response

{
    "id": "ben_9xu6bkPKRRTqCj1IOdIZ",
    "employee": "emp_dF9KJgdpJMFGfXgTRctE",
    "benefit": "hsa",
    "description": "HSA family",
    "effective_start": "2021-04-01",
    "effective_end": null,
    "company_contribution_amount": "0.00",
    "company_contribution_percent": null,
    "employee_contribution_amount": "375.00",
    "employee_contribution_percent": null,
    "hsa_contribution_limit": "family"
}

Updating Benefits

All fields of a Benefit may be updated except for the employee field and the benefit field (which denotes the Benefit type). Changes will impact how the Benefit applies to future payrolls. Changes will not affect how the deduction has applied to previously paid or currently approved payrolls.

As an example, let’s say that an employee wishes to change their 401(k) contribution each payroll from a fixed amount of $100, to 12% of their income. That change could be facilitated by the following request, assuming the Benefit already existed with id “ben_QWLA9oP9WNVOUXYtBXvS”:

curl -X PATCH \
  https://sandbox.checkhq.com/benefits/ben_QWLA9oP9WNVOUXYtBXvS \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "employee":"emp_FZEOSqW0QTKcE1iVU1C5",
      "benefit": "401k",
      "company_contribution_amount": "0",
      "company_contribution_percent": 20.0,
      "employee_contribution_percent": 12.0,
      "employee_contribution_amount": null,
      "effective_start": "2021-04-01",
      "description": "Employee 401k plan"
   }'

Example response

{
    "id": "ben_0DeumV1lYhUua7xUWElX",
    "employee": "emp_1ATPRmtf6XBdR6jDa9M5",
    "benefit": "401k",
    "description": "foo",
    "effective_start": "2021-01-01",
    "effective_end": null,
    "company_contribution_amount": null,
    "company_contribution_percent": 20.0,
    "employee_contribution_amount": null,
    "employee_contribution_percent": 12.0,
    "hsa_contribution_limit": null
}

Deleting Benefits

Deleting a Benefit will remove it forever and prevent it from applying to any future payrolls. A deleted Benefit will not be returned by GET /benefits calls. Calling GET /benefits/:id for a deleted Benefit will return a 404 error. Deleting a benefit will not impact previously paid or already approved payrolls nor will it impact existing reports and paystubs.

Delete a Benefit if it was created by mistake, or if it no longer applies to an employee. For example, a Benefit with an effective_end date that has passed.

curl -X DELETE \
  https://sandbox.checkhq.com/benefits/ben_0DeumV1lYhUua7xUWElX \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json'

Note: The Check system saves a record of all Benefits for auditability.


Did this page help you?