Overview

The Pay Rates API lets you manage employee pay rates programmatically — retrieve current and historical rates, create or update rates with effective dates, and remove rate entries.

Endpoints

Authentication

All endpoints require either an API Key or OAuth 2.0 token.

Key Concepts

Effective Dates

Every pay rate has an effectiveDate — the date from which it applies. A user can have multiple pay rates, each with a different effective date. The most recent effective date determines the user's current rate.

Rate Types

Three rate types are supported: hourly, monthly, and yearly.

Rate Hierarchy

Pay rates support a three-level hierarchy:

1. Default Rate — the base rate applied to the user
2. Resource Rate — a per-job override. Can inherit from the default via useDefaultRate
3. Sub-Resource Rate — a per-sub-job override. Can inherit from the parent resource via useParentRate

When inheritance flags are set, the rate value is omitted from the response.

Upsert Semantics

The PUT endpoint uses upsert logic: sending a pay rate for a user + effective date that already exists fully replaces the existing entry. There is no separate create vs update endpoint.

Locked Days Protection

If a user has approved or locked timesheet days on or after the effective date, both PUT and DELETE operations are rejected with HTTP 409 and error code HAS_LOCKED_DAYS. This prevents changes that would affect finalized payroll.

Guides

Detailed documentation for each endpoint:

• Get Pay Rates — query parameters, date range behavior, pagination, modification history
• Set Pay Rates — request body, validation rules, resource rate configuration
• Delete Pay Rate — path parameters, locked days checks, behavior

Common Integration Patterns

1. Payroll sync — GET pay rates for all users in the pay period, then push to your payroll system.
2. Bulk rate updates — PUT with up to 500 users per request for annual raises or rate adjustments.
3. Audit trail — Use isIncludeHistory=true on GET to retrieve the full modification history for compliance.
4. Rate cleanup — DELETE incorrect entries by user ID and effective date.