---
title: "List Pay Codes"
method: GET
path: "/v1/companies/{company_id}/legal-entities/{legal_entity_id}/pay-codes"
tags: ["Pay Items"]
---

# List Pay Codes

`GET /v1/companies/{company_id}/legal-entities/{legal_entity_id}/pay-codes`

## Request

- Base URL: `https://gateway.remote.com`
- URL: `https://gateway.remote.com/v1/companies/{company_id}/legal-entities/{legal_entity_id}/pay-codes`
- Auth: one of:
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `https://gateway.remote.com/company.manage`
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `pay_item:read`
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `all:read`
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `all:write`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `pay_item:read`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `all:read`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `all:write`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `https://gateway.remote.com/company.manage`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `payroll`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `all:read`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `all:write`
  - HTTP bearer

Lists pay codes available for a legal entity.
Pay codes represent the allowed pay element types that can be submitted via `POST /v1/pay-items/bulk`.

## Authentication

This endpoint accepts any one of the following token types:

- **Company-scoped access token** (`OAuth2AuthorizationCode`) — obtained by a company manager through the Authorization Code flow or the Refresh Token flow. See [Authentication for partners](https://developer.remote.com/docs/authentication-for-partners).
- **Company-scoped access token (assertion)** (`OAuth2CompanyManagerAssertion`) — obtained through the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant for a company manager. See [OAuth Assertion](https://developer.remote.com/docs/authorization-method-oauth-assertion).
- **Client credentials access token** (`OAuth2ClientCredentials`) — obtained through the Client Credentials flow or the Refresh Token flow. See [Authentication for partners](https://developer.remote.com/docs/authentication-for-partners).
- **Customer API token** (`CustomerAPIToken`) — generated by the customer on their Integration Settings page, with the scopes they choose there. See [Authorization for customers](https://developer.remote.com/docs/authorization-for-customers).

## Scopes

Any one of the scopes in a token type's row is enough. `all:read` and `all:write` work too.

| Token type | Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|---|
| Company-scoped access token | Manage payroll runs (`payroll`) | View pay items (`pay_item:read`) | Manage pay items (`pay_item:write`) |
| Company-scoped access token (assertion) | Manage payroll runs (`payroll`) | View pay items (`pay_item:read`) | Manage pay items (`pay_item:write`) |
| Client credentials access token | Manage payroll runs (`payroll`) | - | - |
| Customer API token | Manage payroll runs (`payroll`) | View pay items (`pay_item:read`) | Manage pay items (`pay_item:write`) |

## Path parameters

- `company_id` string, uuid, required: A unique identifier in UUID v4 format.
- `legal_entity_id` string, uuid, required: A unique identifier in UUID v4 format.

## Query parameters

- `page` integer
- `page_size` integer

## Response `200`

Success

- ListPayCodesResponse: Response schema listing many pay_codes
  - `data` object
    - `current_page` integer: The current page among all of the total_pages
    - `pay_codes` PayCode[]
      - `category` string, required: Pay element category (e.g. time_and_attendance, bonus)
      - `code` string, required: Code to use in the `code` field of POST /v1/pay-items/bulk
      - `custom_configuration` PayCodeCustomConfiguration: The pay item custom configuration this pay code uses, such as the employee's company car. Present only on pay codes whose custom configuration is filled in for each employee.
        - `key` string, required: The `custom_configuration.key` to send, with the values, when creating or updating a pay item via POST /v1/pay-items/bulk or PATCH /v1/pay-items/:id.
        - `label` string, required: Human-readable name of the custom configuration
        - `required` boolean, required: Whether every pay item for this pay code must include the custom configuration values
        - `schema` object, required: JSON Schema the custom configuration values must match. Money values are whole numbers in the currency's minor unit, e.g. pence for GBP.
      - `description` string, nullable: Description of the pay code
      - `external_import_code` string, nullable: Customer-specific code used for bulk import mapping
      - `name` string, required: Human-readable name of the pay code
      - `slug` string, uuid, required: Unique identifier for this pay code
      - `type` string, required: How the `amount` field on POST /v1/pay-items/bulk must be encoded for this pay code: `amount` in cents, `percentage` in basis points, `unit` as a raw count, `hours` as a whole number of hours, `duration` in seconds.
    - `total_count` integer: The total number of records in the result
    - `total_pages` integer: The total number of pages the user can go through

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found

---

[API](https://skmtc.dev/remote-com/apis/pay-compensation.md) - [All operations](https://skmtc.dev/remote-com/apis/pay-compensation/llms.txt) - [OpenAPI document](https://skmtc.dev/remote-com/apis/pay-compensation/revisions/ec29f1865c5e?raw)