Guide to the Deductions API

The Deductions API lets a benefits administration platform keep a worker's recurring deductions in Everee in sync with its own records. You can start, change and end deductions without anyone working in Everee.

There are three endpoints, one for each kind of deduction. They work the same way and differ in which pay codes and amount options they accept.

One request to start, change or end

Each endpoint is a single POST that does the right thing based on which dates you send:

A deduction is identified by the worker and the pay code, so you don't store any Everee deduction ID. For other deductions you also supply an externalId, because a worker can have more than one deduction of the same type.

Changing a deduction

• If the worker has no deduction for that pay code, or their last one ended before your effectiveDate, a new one is created.
• If the existing deduction hasn't been used in a finalized payroll yet, it's updated in place.
• Otherwise the existing deduction is ended the day before your effectiveDate, and a new one starts on it. This keeps past payrolls unchanged.

The start date can't be earlier than the worker's earliest editable date. If it is, it's moved forward to that date. The response always contains the dates that were actually used.

Ending a deduction

To end a deduction, send the workerId and payCode (and externalId) with only an effectiveEndDate. The deduction must exist and still be active or upcoming, otherwise you get a 404. A deduction that was never used in a finalized payroll is removed entirely, and its response still returns the start date and the end date you sent. One that was used is ended on the date you gave, or the earliest date that's still editable.

The response

Each response echoes workerId and payCode (and externalId), along with:

• status: ACTIVE, or ENDED if the end date is today or earlier in the company's time zone
• effectiveDate and effectiveEndDate: the dates that now apply

Amounts

Send exactly one of deductionAmount or deductionPercentage. Which one a pay code allows is listed below. Sending both, neither, or one the pay code doesn't allow returns a 422.

Fixed amounts (deductionAmount) are amounts per period. Send the amount with the periodType it applies to (WEEKLY, BI_WEEKLY, SEMI_MONTHLY or MONTHLY). For companies that deduct a monthly amount, Everee converts it to a monthly total: the amount times the number of periods in a year, divided by 12. Companies configured to deduct on every payment have the amount applied as sent, per payment. Use employerAmount for any employer contribution. It defaults to zero.

Percentages (deductionPercentage) are decimal fractions, not whole percentages: send 0.05 for 5%. Use employerPercentage for any employer contribution. An optional limit caps the dollar amount deducted per payment, per month or per pay period.

lifetimeLimit caps the total deducted from the worker over the life of the deduction. It's available on the benefit and other deduction endpoints.

Retirement employer match

The retirement endpoint doesn't take an employer amount or percentage. Describe the employer's match with employerMatchTiers instead: an ordered list of tiers, each with a matchRate and the share of wages (percentOfWages) it covers. Both are decimal fractions. For example, a 100% match on the first 3% of wages and a 50% match on the next 2% is:

"employerMatchTiers": [
  { "matchRate": 1.0, "percentOfWages": 0.03 },
  { "matchRate": 0.5, "percentOfWages": 0.02 }
]

Match tiers aren't accepted for state retirement plan Roth 401(k) or PAYROLL_DEDUCTION_IRA pay codes.

HSA limit

For HSA deductions, hsaLimitType sets whether the contribution limit is INDIVIDUAL or FAMILY. If you leave it out, the worker's existing limit type is kept. Sending it with any other pay code is rejected.

Pay codes

The payCode says what kind of deduction this is. Use one of the values below, or the apiKey of a custom pay code your company has set up for one of these deduction types. Each endpoint only accepts its own types. Anything else returns a 404.

Benefit deductions

All benefit deductions use deductionAmount.

Other deductions

Retirement deductions

All of these accept deductionAmount or deductionPercentage.

ERISA_401K, ROTH_401K, ERISA_403B, TRADITIONAL_IRA, SIMPLE_IRA, SIMPLE_IRA_POST_TAX, PAYROLL_DEDUCTION_IRA, and state retirement plan Roth 401(k)s.

State retirement plan Roth 401(k)s are sent with a two-letter state prefix, like CA_STATE_RETIREMENT_PLAN_ROTH_401K. The prefix must be one of the participating states: CA, CO, CT, DE, IL, ME, MD, MN, NJ, NV, NY, OR, RI, VA or VT. The unprefixed STATE_RETIREMENT_PLAN_ROTH_401K is rejected.

Errors