Apply retirement deduction

post

https://api.everee.com/integration/v1/deductions/retirement

Start, change or end a worker's retirement plan deduction, like a 401(k), 403(b) or IRA. The employer side is described by employerMatchTiers instead of an employer amount or percentage.

Send an effectiveDate to start or change the deduction, or only an effectiveEndDate to end it. The deduction is identified by workerId and payCode. See the Guide to the Deductions API for how changes are applied.

Body Params

workerId

string

required

The worker's ID (your external worker ID, or the Everee worker ID).

payCode

string

required

The retirement plan type, like ERISA_401K, or the apiKey of a custom pay code. For a state retirement plan Roth 401(k), prefix the state: CA_STATE_RETIREMENT_PLAN_ROTH_401K. See the Guide to the Deductions API for the supported values.

deductionAmount

object

A fixed dollar amount. Send either this or deductionPercentage, depending on what the payCode supports.

deductionPercentage

object

A percentage of pay. Send either this or deductionAmount, depending on what the payCode supports.

employerMatchTiers

array of objects

The employer's tiered match, in order. Not accepted for state retirement plan Roth 401(k) or PAYROLL_DEDUCTION_IRA pay codes.

employerMatchTiers

effectiveDate

date

The date the deduction starts or changes. Send it to create or update the deduction. Omit it, and send only effectiveEndDate, to end an existing deduction. If the date is earlier than the worker's earliest editable date, it's moved forward, and the response shows the date that was used.

effectiveEndDate

date

The last day the deduction applies. Omit for a deduction that continues until you end it. Can't be before effectiveDate.

Responses

Language

Credentials

Header

Loading…

Response

Choose an example:

application/json

200The deduction after the change.

400effectiveEndDate is before effectiveDate.

404The payCode isn't a supported value for this endpoint, or you ended a deduction that doesn't exist or has already ended.

422The request was invalid. For example: neither date was sent; both or neither of deductionAmount and deductionPercentage were sent, or the one sent isn't supported by the payCode; or a required field is missing.