---
title: "Create employee deduction"
method: POST
path: "/payroll/hub/us/employers/{employerId}/employees/{employeeId}/deductions"
tags: ["Deductions"]
---

# Create employee deduction

`POST /payroll/hub/us/employers/{employerId}/employees/{employeeId}/deductions`

## Request

- Base URL: `https://api.hibob.com/v1`
- URL: `https://api.hibob.com/v1/payroll/hub/us/employers/{employerId}/employees/{employeeId}/deductions`
- Auth: HTTP bearer

**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 parameters

- `employerId` string, required
- `employeeId` string, required

## Request body

- BulkDeductionMutationBody: 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` DeductionMutationItemBody[], required: Deductions to create or update. Exactly one item is allowed per request.
    - `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` DeductionAmount, required: Money amount used in deductions — supports either a flat amount (with currency) or a percentage. Values are sent as strings to preserve decimal precision.
      - `type` 'percentage' | 'amount', required: Amount type — `PERCENTAGE` for a percentage value, `AMOUNT` for a fixed monetary value.
      - `amount` string, required: Decimal value as a string (e.g. `"5.00"` for 5% or 5.00 USD). Always a string to avoid floating-point precision issues. Must match `^\\d+(\\.\\d+)?$`.
      - `currency` string, required: Three-letter ISO 4217 currency code, uppercase (e.g. `"USD"`). Required even for percentage values so that derived amounts can be denominated correctly.
    - `employerCost` DeductionAmount, required: Money amount used in deductions — supports either a flat amount (with currency) or a percentage. Values are sent as strings to preserve decimal precision.
      - `type` 'percentage' | 'amount', required: Amount type — `PERCENTAGE` for a percentage value, `AMOUNT` for a fixed monetary value.
      - `amount` string, required: Decimal value as a string (e.g. `"5.00"` for 5% or 5.00 USD). Always a string to avoid floating-point precision issues. Must match `^\\d+(\\.\\d+)?$`.
      - `currency` string, required: Three-letter ISO 4217 currency code, uppercase (e.g. `"USD"`). Required even for percentage values so that derived amounts can be denominated correctly.
    - `employeeAnnualMaximum` DeductionAmount: Money amount used in deductions — supports either a flat amount (with currency) or a percentage. Values are sent as strings to preserve decimal precision.
      - `type` 'percentage' | 'amount', required: Amount type — `PERCENTAGE` for a percentage value, `AMOUNT` for a fixed monetary value.
      - `amount` string, required: Decimal value as a string (e.g. `"5.00"` for 5% or 5.00 USD). Always a string to avoid floating-point precision issues. Must match `^\\d+(\\.\\d+)?$`.
      - `currency` string, required: Three-letter ISO 4217 currency code, uppercase (e.g. `"USD"`). Required even for percentage values so that derived amounts can be denominated correctly.
    - `employerAnnualMaximum` DeductionAmount: Money amount used in deductions — supports either a flat amount (with currency) or a percentage. Values are sent as strings to preserve decimal precision.
      - `type` 'percentage' | 'amount', required: Amount type — `PERCENTAGE` for a percentage value, `AMOUNT` for a fixed monetary value.
      - `amount` string, required: Decimal value as a string (e.g. `"5.00"` for 5% or 5.00 USD). Always a string to avoid floating-point precision issues. Must match `^\\d+(\\.\\d+)?$`.
      - `currency` string, required: Three-letter ISO 4217 currency code, uppercase (e.g. `"USD"`). Required even for percentage values so that derived amounts can be denominated correctly.
    - `employeeStartDate` string, required: Effective start date for the employee's deduction.
    - `employeeEndDate` string, nullable: Effective end date for the employee's deduction. Omit for open-ended deductions.
    - `employerStartDate` string, nullable: Effective start date for the employer's contribution.
    - `employerEndDate` string, nullable: Effective end date for the employer's contribution. Omit for open-ended contributions.
    - `coverageAmount` DeductionAmount: Money amount used in deductions — supports either a flat amount (with currency) or a percentage. Values are sent as strings to preserve decimal precision.
      - `type` 'percentage' | 'amount', required: Amount type — `PERCENTAGE` for a percentage value, `AMOUNT` for a fixed monetary value.
      - `amount` string, required: Decimal value as a string (e.g. `"5.00"` for 5% or 5.00 USD). Always a string to avoid floating-point precision issues. Must match `^\\d+(\\.\\d+)?$`.
      - `currency` string, required: Three-letter ISO 4217 currency code, uppercase (e.g. `"USD"`). Required even for percentage values so that derived amounts can be denominated correctly.
    - `coverageType` string, nullable: Coverage type label (e.g. `"Flat Amount"`, `"Based on Salary"`). Valid values come from the **coverageTypes** system list (GET /metadata/lists/coverageTypes).
    - `limitOption` string, nullable: Limit option label when applicable (e.g. `"Family"`, `"Individual"`). Valid values come from the **limitOptions** system list (GET /metadata/lists/limitOptions).
    - `catchUp` boolean, nullable: `true` to enable catch-up contributions. Defaults to `true` when omitted.

## Response `200`

Success

- BulkDeductionMutationOutput
  - `items` DeductionMutationOutput[], required: Results for each submitted deduction. Exactly one item is returned per request.
    - `status` 'success', required
    - `deductionId` string, required: Unique identifier of the created or updated deduction.

## Other responses

- `400`: Bad request — invalid request body, validation error, or deduction rejected by US Payroll.
- `401`: Unauthorized — the OAuth 2.0 access token is missing, invalid, or expired.
- `403`: Forbidden — the authenticated caller does not have permission to perform this operation on the requested company, employer, or employee.
- `404`: Not found — the requested employer, employee, pay cycle, or deduction could not be found, or the authenticated caller is not authorized to see it.
- `429`: Too many requests — rate limit exceeded. Read the limit per operation (most reads are 5/minute, mutations 200/minute) and retry after the indicated delay.
- `500`: Internal server error — an unexpected error occurred. Retry with exponential backoff; if the error persists, contact HiBob support with the `requestId` from the response body.

---

[API](https://skmtc.dev/hibob/apis/retirement-partners-api.md) - [All operations](https://skmtc.dev/hibob/apis/retirement-partners-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hibob/apis/retirement-partners-api/revisions/5ebd2ae67958?raw)