API Documentation

The WorkTime One REST API allows you to programmatically interact with your WorkTime One account. You can manage employees, track attendance, generate reports, and integrate with smart locks.

1. Get Your API Key

Log in to your WorkTime One account and navigate to Settings → API Keys to generate your API key.

2. Make Your First Request

Here's a simple example to get your organization information:

curl -X GET https://api.worktime.one/v1/organization \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

3. Response Format

All responses are returned in JSON format:

{
  "success": true,
  "data": {
    "id": "org_123456",
    "name": "Acme Corporation",
    "employees_count": 42,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

The WorkTime One API uses Bearer token authentication. Include your API key in the Authorization header of every request:

Authorization: Bearer YOUR_API_KEY

API Key Scopes

You can create API keys with different permission levels:

• Read Only: Can only retrieve data (GET requests)
• Read/Write: Can retrieve and modify data (GET, POST, PUT requests)
• Full Access: Complete access including delete operations

Smart Locks

{
  "success": true,
  "data": [
    {
      "id": "event_123456",
      "lock_id": "lock_789",
      "employee_id": "emp_123456",
      "employee_name": "John Doe",
      "access_method": "fingerprint",
      "timestamp": "2024-11-18T09:00:00Z",
      "success": true
    }
  ]
}

The WorkTime One API enforces rate limits to ensure fair usage and system stability:

Rate Limit Headers

Every API response includes rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1700308800

Webhooks allow you to receive real-time notifications when events occur in your WorkTime One account.

Available Events

• employee.created - New employee added
• employee.updated - Employee information changed
• employee.deleted - Employee removed
• attendance.clock_in - Employee clocked in
• attendance.clock_out - Employee clocked out
• penalty.created - Late arrival or early departure penalty
• lock.opened - Smart lock accessed

Webhook Payload Example

{
  "event": "attendance.clock_in",
  "timestamp": "2024-11-18T09:00:00Z",
  "data": {
    "employee_id": "emp_123456",
    "employee_name": "John Doe",
    "lock_id": "lock_789",
    "timestamp": "2024-11-18T09:00:00Z",
    "method": "fingerprint"
  }
}

Setting Up Webhooks

Configure webhooks in your account settings at Settings → Webhooks. Provide your endpoint URL and select the events you want to receive.

We provide official SDKs to make integration easier:

const WorkTime One = require('@worktime/api');
const client = new WorkTime One('YOUR_API_KEY');

const employees = await client.employees.list();
console.log(employees);

from worktime import WorkTime

client = WorkTime One("YOUR_API_KEY")
employees = client.employees.list()
print(employees)

use WorkTime One\Client;

$client = new Client('YOUR_API_KEY');
$employees = $client->employees->list();
print_r($employees);

require 'worktime'

client = WorkTime One::Client.new('YOUR_API_KEY')
employees = client.employees.list
puts employees

The WorkTime One API uses standard HTTP status codes to indicate success or failure:

Error Response Format

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "The 'email' field is required",
    "field": "email"
  }
}