Update employee deduction

put

https://api.hibob.com/v1/payroll/hub/us/employers/{employerId}/employees/{employeeId}/deductions/{deductionId}

Update an existing deduction by ID; changes apply from the next pay cycle.

Beta. Updates an existing deduction by ID. Changes apply to the next pay
cycle. Same body shape as create — pass the full deduction (PUT replaces all
fields). If US Payroll rejects the update at downstream validation time, the
API returns HTTP 400 with the standard error body (not HTTP 200 with a
status: failed field).

Rate limit: 200 requests per minute per authenticated caller.

Path Params

employerId

string

required

Unique identifier of the employer.

employeeId

string

required

Unique Bob employee identifier.

deductionId

string

required

Unique identifier of the deduction to update.

Body Params

Bulk request body for create and update deduction operations. The items
array must contain exactly one deduction object.

vendorName

string

required

Vendor name to record as the source of this deduction in US payroll
(e.g. "Fidelity", "Empower"). Required so the deduction can be
reconciled back to the integrator.

items

array of objects

required

length between 1 and 1

Deductions to create or update. Exactly one item is allowed per request.

items*

deductionType

string

required

Deduction type code as a numeric string. See HiBob's deduction type
reference list for valid values (e.g. "1" for 401(k)).

deductionName

string

required

Display name of the deduction.

employeeCost

object

required

Employee-paid portion of the deduction.

employerCost

object

required

Employer-paid portion of the deduction.

employeeAnnualMaximum

Annual maximum the employee can contribute, when applicable.

employerAnnualMaximum

Annual maximum the employer can contribute, when applicable.

employeeStartDate

string

required

^\d{4}-\d{2}-\d{2}$

Effective start date for the employee's deduction.

employeeEndDate

string | null

^\d{4}-\d{2}-\d{2}$

Effective end date for the employee's deduction. Omit for open-ended deductions.

employerStartDate

string | null

^\d{4}-\d{2}-\d{2}$

Effective start date for the employer's contribution.

employerEndDate

string | null

^\d{4}-\d{2}-\d{2}$

Effective end date for the employer's contribution. Omit for open-ended contributions.

coverageAmount

Coverage amount when applicable (e.g. life insurance face value).

coverageType

string | null

Coverage type label (e.g. "Flat Amount", "Based on Salary").

Valid values come from the coverageTypes system list (GET /metadata/lists/coverageTypes).

limitOption

string | null

Limit option label when applicable (e.g. "Family", "Individual").

Valid values come from the limitOptions system list (GET /metadata/lists/limitOptions).

catchUp

boolean | null

Defaults to true

true to enable catch-up contributions. Defaults to true when omitted.

Responses

Language

Credentials

Bearer

OAuth 2.0

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Success

400Bad request — invalid request body, validation error, or deduction rejected by US Payroll.

401Unauthorized — the OAuth 2.0 access token is missing, invalid, or expired.

403Forbidden — the authenticated caller does not have permission to perform this operation on the requested company, employer, or employee.

404Not found — the requested employer, employee, pay cycle, or deduction could not be found, or the authenticated caller is not authorized to see it.

429Too many requests — rate limit exceeded. Read the limit per operation (most reads are 5/minute, mutations 200/minute) and retry after the indicated delay.

500Internal server error — an unexpected error occurred. Retry with exponential backoff; if the error persists, contact HiBob support with the requestId from the response body.