TimeOff Manager API Documentation

Integrate powerful leave management capabilities into your HR systems, payroll software, and custom applications with our comprehensive RESTful API.

Version 1.0 RESTful API JSON Responses

Getting Started

The TimeOff Manager API allows you to integrate leave management functionality into your existing HR systems, payroll software, or custom applications. Our RESTful API provides comprehensive access to employee data, leave requests, company information, and compliance tracking.

Employee Management

Create, update, and manage employee records

Leave Requests

Submit, approve, and track time-off requests

Holiday Tracking

Access public holidays for any country

Compliance Ready

Built-in support for labor law compliance

Base URL

https://timeoffmanager.us/api/v1

Authentication

All API requests must include your API key in the request header: 

X-API-Key: tk_your_api_key_here

Note: API keys can be generated from your admin dashboard after logging in. Each key provides secure access to your company's data.

Quick Start Example

cURL Example:

curl -X GET "https://timeoffmanager.us/api/v1/employees" \
  -H "X-API-Key: tk_your_api_key_here" \
  -H "Content-Type: application/json"

JavaScript Example:

fetch('https://timeoffmanager.us/api/v1/employees', {
  headers: {
    'X-API-Key': 'tk_your_api_key_here',
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data));

API Endpoints

Employee Management

GET /employees
List all employees

Retrieve a paginated list of employees in your company.

Query Parameters:

Parameter Type Description
department string Filter by department
is_active boolean Filter by active status
search string Search by name, email, or employee number
per_page integer Results per page (default: 20)

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
  }
}
POST /employees
Create new employee

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:

Field Type Required Description
first_name string ✓ Employee's first name
last_name string ✓ Employee's last name
email string ✓ Unique email address
password string ✓ Minimum 8 characters
employee_number string — Unique employee identifier
title string — Job title
department string — Department name
manager_id integer — ID of reporting manager
hire_date date — Date of hire (YYYY-MM-DD)
employment_type enum — full-time, part-time, contract, temporary
work_phone string — Work phone number
mobile_phone string — Mobile phone number
work_locations array — Array of work location objects
emergency_contact object — Emergency contact information
payroll_id string — External payroll system ID
ssn_sin string — SSN/SIN (encrypted in storage)
country_code string(2) ✓ ISO country code (default: CA)
timezone string ✓ Timezone identifier
GET /employees/{id}
Get employee details

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

Response includes:

  • Complete employee profile information
  • Current year PTO balance and usage
  • Public holidays count for their country
  • Pending leave request days
PUT /employees/{id}
Update employee

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

Note: Use "sometimes" validation rules - only provided fields will be updated.

DELETE /employees/{id}
Deactivate employee

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

Leave Requests

GET /leave-requests
List leave requests

Retrieve leave requests with optional filtering.

Query Parameters:

Parameter Type Description
employee_id integer Filter by employee ID
status string Filter by status (pending, approved, rejected)
type string Filter by type (vacation, sick, personal, unpaid)
year integer Filter by year
POST /leave-requests/{id}/approve
Approve leave request

Approve a pending leave request. The employee will be notified via email.

Other Resources

GET /holidays/{country_code}
Get public holidays

Retrieve public holidays for a specific country.

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
  }
}

Error Handling

The API uses standard HTTP status codes to indicate success or failure of requests.

Status Code Description
200 Success - Request completed successfully
201 Created - Resource created successfully
401 Unauthorized - Invalid or missing API key
403 Forbidden - Access denied to resource
404 Not Found - Resource not found
422 Unprocessable Entity - Validation error
429 Too Many Requests - Rate limit exceeded

Error Response Format

{
  "error": "Validation Error",
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."],
    "employee_number": ["The employee number has already been taken."]
  }
}

Rate Limiting

API requests are rate limited to ensure fair usage and system stability. The default limit is 1000 requests per hour per API key.

Rate Limit Headers

Each API response includes headers with rate limit information:

  • X-RateLimit-Limit - Maximum requests per hour
  • X-RateLimit-Remaining - Requests remaining
  • X-RateLimit-Reset - Time when limit resets (Unix timestamp)

SDKs & Libraries

While we don't yet provide official SDKs, our RESTful API works seamlessly with any HTTP client library in your preferred programming language.

Node.js / JavaScript

Use fetch, axios, or any HTTP client:

axios, fetch, request

Python

Compatible with popular libraries:

requests, httpx, urllib

PHP

Works with standard HTTP clients:

Guzzle, cURL, file_get_contents

Need Help?

Getting Started

Support Channels

  • • Email: support@timeoffmanager.com
  • • Response time: < 24 hours
  • • Available: Monday-Friday, 9 AM - 5 PM PST
  • • Enterprise support available