---
title: "List employer deduction plans"
method: GET
path: "/payroll/hub/us/employers/{employerId}/deduction-plans"
tags: ["Employers"]
---

# List employer deduction plans

`GET /payroll/hub/us/employers/{employerId}/deduction-plans`

## Request

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

**Beta.** Returns employer-level deduction plans (e.g., 401k plans) that
the partner needs for onboarding/configuration.

**Rate limit:** 5 requests per minute per authenticated caller.

## Path parameters

- `employerId` string, required

## Query parameters

- `cursor` string
- `limit` integer

## Response `200`

Success

- ListEmployerDeductionPlansOutput
  - `items` DeductionPlan[], required
    - `deductionId` string, required: Unique identifier of the employer-level deduction plan.
    - `deductionType` string, required: Deduction type code for the full mapping.
    - `deductionName` string, required: Display name of the deduction plan (e.g. `"Dental PPO Plan"`).
    - `startDate` string, required: Effective start date of the plan (ISO 8601 calendar date).
    - `endDate` string, nullable: Effective end date of the plan (ISO 8601 calendar date).
    - `status` 'ACTIVE' | 'INACTIVE', required: Employer deduction plan lifecycle status.
  - `responseMetadata` ResponseMetadata, required: Pagination metadata returned with every list response. Use `nextCursor` to fetch the next page; `null` indicates there are no more results.
    - `nextCursor` string, nullable: Opaque cursor identifying the start of the next page of results. Pass this value back as the `cursor` query parameter on the next request to continue paging. `null` (or absent) when the current page is the last one.

## 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.
- `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)