Policy Types & Balances

Retrieve policy types to understand your organization's time-off structure, and manage user balances.

Endpoints

Method	Endpoint	Description
GET	/time-off/v1/policy-types	Get all policy types
GET	/time-off/v1/policy-types/{policyTypeId}/balances	Get user balances
PUT	/time-off/v1/policy-types/{policyTypeId}/balances/{userId}	Update user balance

Get Policy Types

Retrieve all policy types and their associated policies.

Example Request

curl --request GET \
  --url https://api.connecteam.com/time-off/v1/policy-types \
  --header 'X-API-KEY: YOUR_API_KEY'

Response

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "policyTypes": [
      {
        "id": "pt-vacation-001",
        "name": "Vacation",
        "policies": [
          {
            "id": "pol-vac-ft-001",
            "name": "Vacation - Full-time",
            "unit": "days"
          },
          {
            "id": "pol-vac-pt-001",
            "name": "Vacation - Part-time",
            "unit": "hours"
          }
        ]
      },
      {
        "id": "pt-sick-001",
        "name": "Sick Leave",
        "policies": [
          {
            "id": "pol-sick-001",
            "name": "Sick Leave - All Employees",
            "unit": "hours"
          }
        ]
      }
    ]
  }
}

Response Fields

Policy Type:

Field	Type	Description
id	string	Unique policy type identifier
name	string	Policy type display name
policies	array	List of policies within this type

Policy:

Field	Type	Description
id	string	Unique policy identifier (use for assignments)
name	string	Policy display name
unit	string	Balance unit: `hours` or `days`

📝
Save Policy IDs
Store the policyTypeId for balance operations and the policy id for user assignments.

Get User Balances

Retrieve time-off balances for users within a policy type.

Path Parameters

Parameter	Type	Required	Description
policyTypeId	string	Yes	The policy type ID

Query Parameters

Parameter	Type	Required	Default	Description
userIds	array	No	-	Filter by specific user IDs
limit	integer	No	10	Results per page (1-100)
offset	integer	No	0	Pagination offset

Example: Get All Balances

curl --request GET \
  --url 'https://api.connecteam.com/time-off/v1/policy-types/pt-vacation-001/balances?limit=50' \
  --header 'X-API-KEY: YOUR_API_KEY'

Example: Get Specific Users

curl --request GET \
  --url 'https://api.connecteam.com/time-off/v1/policy-types/pt-vacation-001/balances?userIds=9170357&userIds=9170358' \
  --header 'X-API-KEY: YOUR_API_KEY'

Response

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "balances": [
      {
        "userId": 9170357,
        "units": "days",
        "balance": 15.5
      },
      {
        "userId": 9170358,
        "units": "days",
        "balance": 12.0
      }
    ]
  },
  "paging": {
    "offset": 2
  }
}

Response Fields

Field	Type	Description
userId	integer	User's unique identifier
units	string	Balance unit: `hours` or `days`
balance	number	Remaining balance (can be decimal)

Update User Balance

Set a user's time-off balance for a policy type.

⚠️
Replaces Balance
This operation sets the balance to the specified value. It does not add to or subtract from the existing balance.

Path Parameters

Parameter	Type	Required	Description
policyTypeId	string	Yes	The policy type ID
userId	integer	Yes	The user's ID

Request Body

Field	Type	Required	Description
balance	number	Yes	The new balance value

Example Request

curl --request PUT \
  --url https://api.connecteam.com/time-off/v1/policy-types/pt-vacation-001/balances/9170357 \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "balance": 20.0
  }'

Response

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "balance": {
      "userId": 9170357,
      "units": "days",
      "balance": 20.0
    }
  }
}

Pagination Example

async function getAllBalances(policyTypeId) {
  const balances = [];
  let offset = 0;
  const limit = 100;
  
  while (true) {
    const response = await fetch(
      `https://api.connecteam.com/time-off/v1/policy-types/${policyTypeId}/balances?limit=${limit}&offset=${offset}`,
      { headers: { 'X-API-KEY': 'YOUR_API_KEY' } }
    );
    
    const result = await response.json();
    balances.push(...result.data.balances);
    
    if (result.data.balances.length < limit) {
      break;
    }
    
    offset = result.paging.offset;
  }
  
  return balances;
}

Error Responses

404 Not Found

{
  "detail": "Policy type not found"
}

422 Validation Error

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

API Reference