TimeOff Manager API Documentation

Retrieve a paginated list of people in your company (employees, managers, and company admins). Platform operator accounts are excluded. Pass role to filter.

Query Parameters:

Example Response:

{
  "data": [
    {
      "id": 123,
      "employee_number": "EMP-001",
      "first_name": "John",
      "last_name": "Doe",
      "name": "John Doe",
      "email": "john.doe@company.com",
      "role": "employee",
      "company_id": 1,
      "title": "Senior Developer",
      "department": "Engineering",
      "manager_id": 45,
      "hire_date": "2022-01-15",
      "employment_type": "full-time",
      "work_phone": "+1-555-0123",
      "mobile_phone": "+1-555-0124",
      "work_locations": [
        {
          "address": "123 Main St, New York, NY 10001",
          "is_primary": true
        }
      ],
      "emergency_contact": {
        "name": "Jane Doe",
        "phone": "+1-555-0125",
        "relationship": "Spouse"
      },
      "payroll_id": "PAY-001",
      "country_code": "US",
      "timezone": "America/New_York",
      "is_active": true,
      "created_at": "2022-01-15T10:30:00Z",
      "updated_at": "2024-12-15T14:20:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 95
  }
}

Create a new employee record in your company.

Request Body:

{
  "employee_number": "EMP-002",
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane.smith@company.com",
  "password": "SecurePass123!",
  "title": "HR Manager",
  "department": "Human Resources",
  "manager_id": 45,
  "hire_date": "2023-03-01",
  "employment_type": "full-time",
  "work_phone": "+1-555-0123",
  "mobile_phone": "+1-555-0124",
  "work_locations": [
    {
      "address": "456 Oak Ave, Los Angeles, CA 90210",
      "is_primary": true
    }
  ],
  "emergency_contact": {
    "name": "Bob Smith",
    "phone": "+1-555-0125",
    "relationship": "Brother"
  },
  "payroll_id": "PAY-002",
  "country_code": "US",
  "timezone": "America/Los_Angeles",
  "ssn_sin": "123-45-6789"
}

Field Descriptions:

Retrieve detailed information about a specific employee, including PTO balance.

Response includes:

• Complete employee profile information
• Current-year PTO via the same balance rules as the dashboard (vacation / sick / personal buckets when configured)
• Pending leave days

Update an existing employee's information. All fields are optional except for validation constraints.

Soft delete by setting employee status to inactive. This preserves historical leave data while preventing new requests.

Retrieve leave requests with optional filtering.

Query Parameters:

employee_id must belong to your company (foreign IDs return 422, not 404).

{
  "employee_id": 123,
  "type": "vacation",
  "start_date": "2026-10-01",
  "end_date": "2026-10-03",
  "notes": "Family trip"
}

type: vacation, sick, personal, unpaid, other (annual is still accepted).

Approve a pending leave request. Fires webhook leave_request.approved.

Optional body: {"rejection_reason": "…"}. Fires leave_request.rejected.

Retrieve public holidays for a specific country. Query: year (defaults to current year).

Example Response:

{
  "data": [
    {
      "name": "New Year's Day",
      "date": "2024-01-01",
      "type": "public_holiday",
      "country_code": "US"
    }
  ],
  "meta": {
    "country": "US",
    "year": 2024,
    "total": 10,
    "weekdays": 8
  }
}

Query year. Returns dashboard-accurate buckets: vacation_available, sick_available, remaining_days, pending_days.

id, name, country_code, timezone, total_employees (all company staff, not only role=employee).

Built-in types plus active custom types for the company.