Create employee deduction

post

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

Create a new deduction for an employee, applied from the next pay cycle.

Beta. Creates a new deduction for an employee under an employer. Changes
apply to the next pay cycle. Do not include a deductionId in the request
body — the server assigns one and returns it in the response.

If US Payroll rejects the deduction 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.

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.