---
title: "List pay codes"
method: GET
path: "/payroll/hub/us/pay-codes"
tags: ["Pay codes"]
---

# List pay codes

`GET /payroll/hub/us/pay-codes`

## Request

- Base URL: `https://api.hibob.com/v1`
- URL: `https://api.hibob.com/v1/payroll/hub/us/pay-codes`
- Auth: HTTP bearer

**Beta.** Returns the standard pay codes for US payroll. The MVP returns a
curated list; partners use this during onboarding to map their internal codes
to HiBob's pay code identifiers. The list does not vary per company.

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

## Response `200`

Success

- ListPayCodesOutput
  - `items` PayCode[], required: Pay codes available for US payroll.
    - `name` string, required: Display name of the pay code (human-readable label).
    - `payCode` string, required: Short identifier of the pay code (e.g. `"SPRO"`, `"JRYU"`). Use this as the pay code key when posting paycheck rows to US payroll.
    - `refId` string, required: Stable UUID reference for the pay code. Prefer `refId` over `payCode` when persisting mappings on the partner side.
    - `category` 'HOURS' | 'ADDITIONAL_WAGE' | 'PTO' | 'UNPAID_HOURS', required: Pay code category — controls how payroll engines interpret the line.
    - `taxable` boolean, required: `true` if amounts on this pay code are subject to US payroll taxes.
    - `payable` boolean, required: `true` if amounts on this pay code result in a payment to the employee. `false` for purely informational pay codes (e.g. unpaid leave hours).
  - `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)