Scheduling Rule Policies

List company scheduling rule policies, see which rules apply to an employee, assign users in bulk, and delete a policy.

Scheduling rule policies are named bundles of labor constraints that Job Schedule enforces for assigned employees: weekly hour caps, rest between shifts, and shift-count limits. Create and edit the policy contents in the Connecteam dashboard; this API is the read-and-assign surface.

Endpoints

Overview

• A company policy is a named, shareable set of rules. List these with the collection GET. Employee-specific custom rules are not included there.
• An employee can also have custom scheduling rules set on their profile. Those are returned only by the user GET, as a policy with isCustomPolicy: true and no name.
• An employee can be governed by a company policy, custom rules, or both at once. Where the same rule type appears in both, the strictest value wins: the lowest for max* types, the highest for min* types and minHoursBetweenShifts.
• Assignments take effect immediately. There is no effectiveDate (unlike pay rule policies).
• An employee can be assigned to one company scheduling rule policy at a time. Assigning them to a different policy replaces the previous scheduling-rule assignment. Custom profile rules are not changed.
• Disabled policies (isEnabled: false) appear in the company list but are never enforced. You cannot assign employees to a disabled policy.
• Create and edit policy rules in the dashboard. Creating, updating, and setting custom profile rules are not part of this public surface.

👍

Good to know

Look up "which rules apply to this employee" with the user GET. It returns only enabled policies, including custom profile rules. Use the company list to discover policy IDs you can assign.

📘

Did you know?

When several rules of the same type apply, the strictest wins. If a company policy caps the week at 40 hours and the employee's custom rules cap it at 24, the employee is effectively capped at 24.

Authentication

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

These endpoints require the Schedule API plan limitation (schedulerApi).

Rule Types

Each policy contains one or more rules. Each type appears at most once in a policy.

Rule fields

applyToSpecificShifts is a filter tree: groups use { "op": "and" | "or", "filters": [...] }, and leaves use { "id": "field", "filterType": "is", "filterCriteria": { "value": "string" } }. Common leaf id values are jobIds and customTextField_{fieldId}.

Get scheduling rule policies

Retrieves all company scheduling rule policies, including disabled ones and the rules configured in each. Custom employee-profile rules are not included. Use the returned id when assigning employees.

Example Request

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

Response

{
  "requestId": "0b1c2d3e-4f56-7890-abcd-ef0123456789",
  "data": {
    "schedulingRulePolicies": [
      {
        "id": 4021,
        "name": "Standard Work Week",
        "isEnabled": true,
        "isDefaultForNewUsers": true,
        "isCustomPolicy": false,
        "rules": [
          {
            "type": "maxHoursPerWeek",
            "value": 40.0,
            "preventClaim": true
          },
          {
            "type": "minHoursBetweenShifts",
            "value": 11.0,
            "preventClaim": false
          }
        ]
      },
      {
        "id": 4022,
        "name": "Night Shift Limits",
        "isEnabled": true,
        "isDefaultForNewUsers": false,
        "isCustomPolicy": false,
        "rules": [
          {
            "type": "maxHoursPerWeek",
            "value": 35.0,
            "preventClaim": true,
            "applyToSpecificSchedulerId": 8817,
            "applyToSpecificShifts": {
              "op": "and",
              "filters": [
                {
                  "op": "or",
                  "filters": [
                    {
                      "id": "customTextField_104",
                      "filterType": "is",
                      "filterCriteria": { "value": "1762437964833" }
                    }
                  ]
                }
              ]
            }
          }
        ]
      }
    ]
  }
}

Response Fields

API Reference

Get user scheduling rule policies

Retrieves the enabled policies currently governing one employee, including custom rules on their profile. This is the lookup for "which scheduling rules apply to this employee".

The response is an array because an employee can have a company policy, custom rules, or both. Custom rules have isCustomPolicy: true and no name. An employee with no scheduling rules returns an empty array (200), not 404. 404 is returned only when the user does not exist.

Path Parameters

Example Request

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

Response — company policy and custom rules

{
  "requestId": "0b1c2d3e-4f56-7890-abcd-ef0123456789",
  "data": {
    "schedulingRulePolicies": [
      {
        "id": 4021,
        "name": "Standard Work Week",
        "isEnabled": true,
        "isDefaultForNewUsers": true,
        "isCustomPolicy": false,
        "rules": [
          {
            "type": "maxHoursPerWeek",
            "value": 40.0,
            "preventClaim": true
          }
        ]
      },
      {
        "id": 4098,
        "isEnabled": true,
        "isDefaultForNewUsers": false,
        "isCustomPolicy": true,
        "rules": [
          {
            "type": "maxHoursPerWeek",
            "value": 24.0,
            "preventClaim": true
          }
        ]
      }
    ]
  }
}

In this example both sets apply, so the employee is effectively capped at 24 hours per week.

Response — no scheduling rules

{
  "requestId": "0b1c2d3e-4f56-7890-abcd-ef0123456789",
  "data": {
    "schedulingRulePolicies": []
  }
}

API Reference

List scheduling rule policy assignments

Retrieves the employees currently assigned to a company policy. To go the other way (policies for one employee), use the user GET.

Path Parameters

Query Parameters

paging.offset is the position after the last returned record. Pass it as offset on the next request. paging.total is the full match count, ignoring pagination.

Example Request

curl --request GET \
  --url 'https://api.connecteam.com/company-policies/v1/scheduling-rule-policies/4021/assignments?limit=100&offset=0' \
  --header 'X-API-KEY: YOUR_API_KEY'

Response

{
  "requestId": "0b1c2d3e-4f56-7890-abcd-ef0123456789",
  "paging": {
    "offset": 2,
    "total": 2
  },
  "data": {
    "assignments": [
      {
        "assignmentId": 90233,
        "userId": 1045
      },
      {
        "assignmentId": 90234,
        "userId": 1046
      }
    ]
  }
}

API Reference

Assign users to a scheduling rule policy

Assigns one or more employees to the policy. Pass them in userIds. The call is all or nothing: if any ID does not exist, nothing is assigned.

If a user is already assigned to another scheduling rule policy, that assignment is replaced. Assigning a user who is already on this policy leaves the existing assignment in place. Custom profile rules are not affected.

Path Parameters

Request Body

Example Request

curl --request PUT \
  --url https://api.connecteam.com/company-policies/v1/scheduling-rule-policies/4021/assignments \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "userIds": [1045, 1046, 1047]
  }'

Response

{
  "requestId": "0b1c2d3e-4f56-7890-abcd-ef0123456789",
  "data": {
    "assignments": [
      { "assignmentId": 90233, "userId": 1045 },
      { "assignmentId": 90234, "userId": 1046 },
      { "assignmentId": 90235, "userId": 1047 }
    ]
  }
}

API Reference

Delete a scheduling rule policy

Deletes the policy and all of its employee assignments. Assigned employees are left without that company policy, so none of its constraints apply to them any more. Custom profile rules are not deleted. This cannot be undone.

Path Parameters

Example Request

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

Response

{
  "requestId": "0b1c2d3e-4f56-7890-abcd-ef0123456789"
}

API Reference

Error Codes

The user GET returns 200 with an empty array when the employee has no scheduling rules.

Integration Example — Assign new hires from an HRIS

async function assignUsersToSchedulingPolicy(policyId, userIds) {
  const chunks = [];
  for (let i = 0; i < userIds.length; i += 100) {
    chunks.push(userIds.slice(i, i + 100));
  }

  const assigned = [];
  for (const userIdsChunk of chunks) {
    const res = await fetch(
      `https://api.connecteam.com/company-policies/v1/scheduling-rule-policies/${policyId}/assignments`,
      {
        method: 'PUT',
        headers: {
          'X-API-KEY': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ userIds: userIdsChunk })
      }
    );
    if (!res.ok) {
      const err = await res.json();
      throw new Error(`Assign failed: ${JSON.stringify(err)}`);
    }
    const body = await res.json();
    assigned.push(...body.data.assignments);
  }
  return assigned;
}

// Confirm which rules apply after assign
async function getUserSchedulingRules(userId) {
  const res = await fetch(
    `https://api.connecteam.com/company-policies/v1/users/$USERID/scheduling-rule-policies`,
    { headers: { 'X-API-KEY': 'YOUR_API_KEY' } }
  );
  const body = await res.json();
  return body.data.schedulingRulePolicies;
}

const policiesRes = await fetch(
  'https://api.connecteam.com/company-policies/v1/scheduling-rule-policies',
  { headers: { 'X-API-KEY': 'YOUR_API_KEY' } }
);
const policies = (await policiesRes.json()).data.schedulingRulePolicies;
const standard = policies.find((p) => p.name === 'Standard Work Week');

await assignUsersToSchedulingPolicy(standard.id, [1045, 1046, 1047]);
await getUserSchedulingRules(1045);

Notes

📝

Important Considerations

• Create and edit the contents of a policy (rule types and values) in the Connecteam dashboard. This API lists those policies and manages who they apply to.
• Assigning a user to a new company policy replaces their previous scheduling-rule assignment. It does not change custom rules on their employee profile.
• There is no public unassign endpoint. To stop a company policy applying to someone, assign them to a different policy or delete the policy (which removes every assignment).
• Deleting a policy cannot be undone and immediately drops its constraints for every assigned employee.
• Pay rule assignments are a different family, with effective dates. See Pay Rule Policies.
• Job Schedule enforces these rules when shifts are created, claimed, or auto-assigned. See the Scheduler overview.

API Reference