--- title: "List employee deductions" method: GET path: "/payroll/hub/us/employers/{employerId}/employees/deductions" tags: ["Deductions"] --- # List employee deductions `GET /payroll/hub/us/employers/{employerId}/employees/deductions` ## Request - Base URL: `https://api.hibob.com/v1` - URL: `https://api.hibob.com/v1/payroll/hub/us/employers/{employerId}/employees/deductions` - Auth: HTTP bearer **Beta.** Returns current deductions for the requested employees under an employer. Provide a comma-separated `employeeIds` query parameter (maximum 25 IDs). Results are filtered to the caller's authorized employees; unknown or unauthorized IDs are silently dropped from the response, not returned as errors. The response is a final list (`items` only) — no cursor pagination. **Rate limit:** 5 requests per minute per authenticated caller. ## Path parameters - `employerId` string, required ## Query parameters - `employeeIds` string, required ## Response `200` Success - ListEmployeeDeductionsOutput - `items` EmployeeDeductionsGroup[], required: Per-employee deduction groups. One entry per employee that has at least one deduction; employees with no deductions are omitted. Returns the full set for the requested employees (capped at 25 employees). - `employeeId` string, required: Unique Bob employee identifier this group belongs to. - `deductions` Deduction[], required: Active deductions for the employee. - `deductionId` string, required: Unique identifier of the deduction. Use this as the `deductionId` path parameter on [`UpdateEmployeeDeduction`](/reference/put_payroll-hub-us-employers-employerid-employees-employeeid-deductions-deductionid). - `deductionType` string, required: Deduction type code as a numeric string (e.g. `"1"` for 401(k)). See HiBob's deduction type reference list for the full mapping. - `deductionName` string, required: Display name of the deduction (e.g. `"401k Plan"`, `"Dental"`). - `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 (ISO 8601 calendar date). - `employeeEndDate` string, nullable: Effective end date for the employee's deduction. Absent 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. Absent 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` when catch-up contributions are enabled. Defaults to `true` on creation. ## 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)