Pay Rule Policies

List the account's pay rules, see which rules sit in each policy, add or remove a rule on a policy, assign an employee with an effective date, list who is on a policy, and remove an assignment.

A pay rule policy is the pay structure Job Schedule and Time Clock use for an employee: regular hours plus overtime, premiums, and differentials. Create the reusable pay rules in the Connecteam dashboard. This API composes those rules into policies and manages who they apply to. Integrators and the Connecteam agent use the same endpoints. The agent relies on them to help admins attach the right pay structure during setup.

Endpoints

The first five rows after Get policies are new. Get policies is extended: each policy now returns isDefaultForNewUsers and payRules. Assign is unchanged, except a change that would touch approved or locked timesheet days is now rejected.

📘

Related

Scheduling rule policies and working hours live on the same Company Policies API. See Scheduling Rule Policies and Working Hours Policies.

Overview

• A pay rule is a reusable definition (regular hours, an overtime tier, a premium). The same rule can belong to several policies.
• A policy is a named bundle of those rules. It always contains exactly one regular rule.
• Adding a regular rule replaces the policy's current regular rule. Adding a rule the policy already has succeeds and changes nothing.
• The regular rule cannot be removed. The last non-regular rule cannot be removed either. Removing a rule never deletes the policy or its assignments.
• Composition changes apply immediately to everyone on the policy, including hours already worked in an open pay period.
• Assignments are effective-dated. An employee is on one policy at a time. The active assignment for a date is the one with the latest effectiveDate on or before that date.
• If effectiveDate is earlier than an existing assignment, the old assignment is replaced. Assign and unassign are rejected when they would change approved or locked timesheet days.
• An employee left with no policy is paid on regular hours only until they are assigned again.
• The Connecteam agent uses these endpoints to look up policies and attach people during setup.

👍

Good to know

Resolve policy contents against Get pay rules. Get policies returns each rule's id and name. Use Get pay rules when you need type, factor, and code.

Authentication

• API Key (X-API-KEY header), or
• OAuth 2.0

These endpoints require the Time Clock API plan limitation (timeClockApi).

📘

Admin permissions

For non-owner admins: view for reads, manage policies for adding or removing rules, and edit users for assignment changes.

Get company pay rules

Retrieves every pay rule in the account. Use the returned id when adding a rule to a policy.

Example Request

curl --request GET \
  --url https://api.connecteam.com/company-policies/v1/pay-rules \
  --header 'X-API-KEY: YOUR_API_KEY'

Response

{
  "requestId": "0b1c2d3e-4f56-7890-abcd-ef0123456789",
  "data": {
    "payRules": [
      {
        "id": "a1f3c9d2-4b7e-4a10-9c8f-2d5e6f7a8b90",
        "name": "Regular hours",
        "type": "regular",
        "calculationMode": "multiplier",
        "factor": 1.0
      },
      {
        "id": "b2e4d0a3-5c8f-4b21-8d9a-3e6f7a8b9c01",
        "name": "Daily overtime after 8h",
        "type": "overtime",
        "calculationMode": "multiplier",
        "factor": 1.5,
        "code": "OT1"
      },
      {
        "id": "c3f5e1b4-6d9a-4c32-9e0b-4f7a8b9c0d12",
        "name": "Night differential",
        "type": "additionalHourlyRate",
        "calculationMode": "addition",
        "factor": 2.0
      }
    ]
  }
}

API Reference

Get pay rule policies

Retrieves enabled company policies, including the pay rules in each one. Custom per-employee policies are excluded. payRulesPolicies, id, and name are unchanged for existing integrations.

Example Request

curl --request GET \
  --url https://api.connecteam.com/company-policies/v1/pay-rule-policies \
  --header 'X-API-KEY: YOUR_API_KEY'

Response

{
  "requestId": "0b1c2d3e-4f56-7890-abcd-ef0123456789",
  "data": {
    "payRulesPolicies": [
      {
        "id": 7781,
        "name": "Default",
        "isDefaultForNewUsers": true,
        "payRules": [
          { "id": "a1f3c9d2-4b7e-4a10-9c8f-2d5e6f7a8b90", "name": "Regular hours" },
          { "id": "b2e4d0a3-5c8f-4b21-8d9a-3e6f7a8b9c01", "name": "Daily overtime after 8h" }
        ]
      },
      {
        "id": 7782,
        "name": "California hourly",
        "isDefaultForNewUsers": false,
        "payRules": [
          { "id": "a1f3c9d2-4b7e-4a10-9c8f-2d5e6f7a8b90", "name": "Regular hours" },
          { "id": "b2e4d0a3-5c8f-4b21-8d9a-3e6f7a8b9c01", "name": "Daily overtime after 8h" },
          { "id": "c3f5e1b4-6d9a-4c32-9e0b-4f7a8b9c0d12", "name": "Night differential" }
        ]
      }
    ]
  }
}

API Reference

Add a pay rule to a policy

Adds an existing pay rule to the policy. The change applies immediately to every assigned employee. Adding a regular rule replaces the current regular rule. Adding a rule the policy already contains is a no-op.

🚧

Applies immediately

Everyone already on this policy is affected, including hours already worked in an open pay period. Adding a regular rule replaces the current one.

curl --request PUT \
  --url https://api.connecteam.com/company-policies/v1/pay-rule-policies/7782/pay-rules/c3f5e1b4-6d9a-4c32-9e0b-4f7a8b9c0d12 \
  --header 'X-API-KEY: YOUR_API_KEY'

The 200 response is the policy with its resulting payRules, so you can confirm a replaced regular rule without a second call.

API Reference

Remove a pay rule from a policy

Removes a pay rule from the policy. The rule itself is not deleted and stays available to other policies. The regular rule cannot be removed, and neither can the last remaining non-regular rule. This never deletes the policy or its assignments.

❗️

Two rules you cannot remove

The regular rule stays. So does the last remaining non-regular rule. To change regular hours, add a different regular rule instead.

curl --request DELETE \
  --url https://api.connecteam.com/company-policies/v1/pay-rule-policies/7782/pay-rules/c3f5e1b4-6d9a-4c32-9e0b-4f7a8b9c0d12 \
  --header 'X-API-KEY: YOUR_API_KEY'

API Reference

Assign a user to a policy

Assigns one employee from effectiveDate. One user per call. If that date is earlier than an existing assignment, the old assignment is replaced.

🚧

Approved or locked days

If the effective date falls in a period with approved or locked timesheet days, the call is rejected. Choose a later date, or unlock the period in the dashboard first.

Request Body

curl --request PUT \
  --url https://api.connecteam.com/company-policies/v1/pay-rule-policies/7782/assignments \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "userId": 3067712,
    "effectiveDate": "2026-03-01"
  }'

{
  "requestId": "0b1c2d3e-4f56-7890-abcd-ef0123456789",
  "data": { "assignmentId": 90233 }
}

API Reference

List pay rule policy assignments

Retrieves who is on the policy on a given date. Defaults to today. Use assignmentId to remove an assignment.

Query Parameters

curl --request GET \
  --url 'https://api.connecteam.com/company-policies/v1/pay-rule-policies/7782/assignments?effectiveDate=2026-03-01&limit=100&offset=0' \
  --header 'X-API-KEY: YOUR_API_KEY'

{
  "requestId": "0b1c2d3e-4f56-7890-abcd-ef0123456789",
  "paging": { "offset": 0, "total": 2 },
  "data": {
    "assignments": [
      { "assignmentId": 90233, "userId": 3067712, "effectiveDate": "2026-03-01" },
      { "assignmentId": 90234, "userId": 3067713, "effectiveDate": "2025-01-01" }
    ]
  }
}

API Reference

Remove a pay rule policy assignment

Removes one assignment record. An employee can have several assignments to the same policy over time. Removing one does not remove the rest of that history. If the employee is left with no policy in effect, they are paid on regular hours only.

curl --request DELETE \
  --url https://api.connecteam.com/company-policies/v1/pay-rule-policies/7782/assignments/90233 \
  --header 'X-API-KEY: YOUR_API_KEY'

API Reference

Error Codes

Errors use the standard External API envelope: requestId, path, error, and details (errorMessage, errorCode).

Example: regular rule cannot be removed

{
  "requestId": "0b1c2d3e-4f56-7890-abcd-ef0123456789",
  "path": "/company-policies/v1/pay-rule-policies/7782/pay-rules/a1f3c9d2-4b7e-4a10-9c8f-2d5e6f7a8b90",
  "error": {
    "payRuleId": "The regular hours pay rule cannot be removed from a policy. To change it, add a different regular hours pay rule to this policy instead."
  },
  "details": {
    "errorMessage": "The regular hours pay rule cannot be removed from a policy. To change it, add a different regular hours pay rule to this policy instead.",
    "errorCode": "REGULAR_PAY_RULE_CANNOT_BE_REMOVED"
  }
}

Integration Example — Compose a policy, then assign from an HRIS (or the agent)

const headers = { 'X-API-KEY': 'YOUR_API_KEY', 'Content-Type': 'application/json' };
const base = 'https://api.connecteam.com/company-policies/v1';

const rules = (await (await fetch(`${base}/pay-rules`, { headers })).json()).data.payRules;
const overtime = rules.find((r) => r.name === 'Daily overtime after 8h');

const policies = (await (await fetch(`${base}/pay-rule-policies`, { headers })).json()).data.payRulesPolicies;
const california = policies.find((p) => p.name === 'California hourly');

await fetch(`${base}/pay-rule-policies/${california.id}/pay-rules/${overtime.id}`, {
  method: 'PUT',
  headers
});

const assignRes = await fetch(`${base}/pay-rule-policies/${california.id}/assignments`, {
  method: 'PUT',
  headers,
  body: JSON.stringify({ userId: 3067712, effectiveDate: '2026-03-01' })
});
if (!assignRes.ok) {
  const err = await assignRes.json();
  throw new Error(`Assign failed: ${JSON.stringify(err)}`);
}

Assign is one user per call. Handle a 400 on a locked period per user; do not assume a loop of assigns all succeed.

The Connecteam agent follows the same flow during setup: list policies, confirm the rules inside, and assign the new person from their start date.

Notes

🚧

Important Considerations

• Create overtime and premium rules in the dashboard. This API attaches existing rules to policies and manages who they apply to.
• A policy must keep its regular rule and at least one other rule.
• Composition changes apply immediately, including to open pay periods.
• Assign and unassign are rejected on approved or locked timesheet days.
• An employee with no policy in effect is paid on regular hours only.
• See Scheduling Rule Policies and Working Hours Policies for the sibling families.