Get Pay Rates

The "Get Pay Rates" endpoint retrieves pay rate information for one or more users within a date range.

Endpoint

GET https://api.connecteam.com/pay-rates/v1/pay-rates

Authentication

• API Key or OAuth 2.0
• OAuth Scope: pay_rates.read

Query Parameters

Date Range Behavior

📘

How date filtering works

The response includes the most recent rate with an effective date before startDate if no rate starts exactly on startDate. This ensures you always see which rate is in effect at the beginning of the range.

Specifically:

• Rates with effectiveDate within [startDate, endDate] are always included
• The single most recent rate with effectiveDate before startDate is also included (if it exists), because that rate is still in effect at the start of the range
• Older rates before that most recent one are not included
• If rateType filter is applied, it also applies to the "in effect" rate — a monthly rate in effect at range start will be excluded if you filter by hourly

Example: A user has rates on 2018-01-01, 2022-06-01, and 2026-03-01. Querying startDate=2026-01-01&endDate=2026-06-30 returns only the 2022-06-01 rate (most recent before range) and the 2026-03-01 rate (within range). The 2018-01-01 rate is not returned.

Modification History

When isIncludeHistory=true, each pay rate includes a modifications array showing every change made to that specific effective date entry. Each modification records:

• modifiedBy — the admin who made the change
• modifiedAt — Unix timestamp of the change
• Previous values for rateType, defaultRate, isDefaultRateEnabled, and isResourceRateEnabled

When isIncludeHistory=false (default), the modifications field is omitted entirely. The modifiedAt top-level field still shows the timestamp of the most recent modification (or is omitted if the rate was never modified after creation).

🚧

Performance Note

Setting isIncludeHistory=true may increase response time and payload size, especially for users with frequent rate changes. Use it only when audit data is needed.

Pagination

Results are paginated using limit and offset. The response includes a paging.offset field with the next offset value. To fetch the next page, pass this value as the offset parameter. When fewer results are returned than the limit, you've reached the last page.

Response Structure

Payload example:

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "payRatesByUsers": [
      {
        "userId": 12345,
        "payRate": {
          "effectiveDate": "2025-01-01",
          "rateType": "hourly",
          "isDefaultRateEnabled": true,
          "defaultRate": 25.50,
          "isResourceRateEnabled": true,
          "isApplyDefaultRateToNewResource": true,
          "resourcesRates": [
            {
              "resourceId": "100",
              "rate": 30.00,
              "isUsingDefaultRate": false,
              "subResourcesRates": [
                {
                  "subResourceId": "200",
                  "isUsingParentRate": true
                }
              ]
            }
          ],
          "createdBy": 99999,
          "createdAt": 1704067200,
          "modifiedAt": 1706745600
        }
      }
    ],
    "paging": {
      "offset": 1
    }
  }
}

Response Fields

📘

Null vs Omitted

Fields that are not applicable are omitted from the response (not returned as null). For example, a resource with isUsingDefaultRate: true will not include a rate field.

Error Codes

Pay Rates API Reference