Policy Assignments

Assign users to time-off policies with optional initial balance configuration.

Endpoint

Method	Endpoint	Description
PUT	/time-off/v1/time-off-policies/{timeOffPolicyId}/assignments	Assign user to a policy

Assign User to Policy

Assign a user to a specific time-off policy. This enables the user to request time off under that policy and have a balance tracked.

📝
Policy ID vs Policy Type ID
Use the policy ID (not policy type ID) for assignments. Get policy IDs from the Get Policy Types endpoint - they're in the policies[].id field.

Path Parameters

Parameter	Type	Required	Description
timeOffPolicyId	string	Yes	The policy ID (from policies array, not policy type)

Request Body

Field	Type	Required	Description
userId	integer	Yes	The user's ID to assign
balance	number	No	Initial balance to set
unit	string	No	Balance unit: `hours` or `days`

💡
Setting Initial Balance
If you provide balance and unit, the user will be assigned with that initial balance. If omitted, the user is assigned with the policy's default balance rules.

Examples

Basic Assignment

Assign a user to a policy with default balance:

curl --request PUT \
  --url https://api.connecteam.com/time-off/v1/time-off-policies/pol-vac-ft-001/assignments \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "userId": 9170357
  }'

Assignment with Initial Balance (Days)

Assign a user with a specific starting balance in days:

curl --request PUT \
  --url https://api.connecteam.com/time-off/v1/time-off-policies/pol-vac-ft-001/assignments \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "userId": 9170357,
    "balance": 15.0,
    "unit": "days"
  }'

Assignment with Initial Balance (Hours)

Assign a user with a specific starting balance in hours:

curl --request PUT \
  --url https://api.connecteam.com/time-off/v1/time-off-policies/pol-sick-001/assignments \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "userId": 9170357,
    "balance": 40.0,
    "unit": "hours"
  }'

Response

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {}
}

Bulk Assignment Example

Assign multiple users to a policy:

async function assignUsersToPolicy(policyId, userIds, initialBalance, unit) {
  const results = [];
  
  for (const userId of userIds) {
    const response = await fetch(
      `https://api.connecteam.com/time-off/v1/time-off-policies/${policyId}/assignments`,
      {
        method: 'PUT',
        headers: {
          'X-API-KEY': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          userId: userId,
          balance: initialBalance,
          unit: unit
        })
      }
    );
    
    results.push({
      userId,
      success: response.ok
    });
  }
  
  return results;
}

// Example usage
assignUsersToPolicy('pol-vac-ft-001', [9170357, 9170358, 9170359], 15, 'days');

Onboarding New Employees

When onboarding new employees, assign them to relevant policies:

async function onboardEmployee(userId, employeeType) {
  const policies = {
    'full-time': [
      { id: 'pol-vac-ft-001', balance: 15, unit: 'days' },
      { id: 'pol-sick-001', balance: 40, unit: 'hours' }
    ],
    'part-time': [
      { id: 'pol-vac-pt-001', balance: 40, unit: 'hours' },
      { id: 'pol-sick-001', balance: 20, unit: 'hours' }
    ]
  };
  
  const assignments = policies[employeeType] || [];
  
  for (const policy of assignments) {
    await fetch(
      `https://api.connecteam.com/time-off/v1/time-off-policies/${policy.id}/assignments`,
      {
        method: 'PUT',
        headers: {
          'X-API-KEY': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          userId: userId,
          balance: policy.balance,
          unit: policy.unit
        })
      }
    );
  }
}

Error Responses

404 Not Found

{
  "detail": "Policy not found"
}

{
  "detail": "User not found"
}

422 Validation Error

{
  "detail": [
    {
      "loc": ["body", "userId"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

API Reference