Endpoint Reference
Complete reference for all TempClock API v1 endpoints. All endpoints require Bearer token authentication and return JSON responses.
Base URL
https://tempclock.com/api/v1/
Endpoints
GET
/workers.php
Retrieve a paginated list of workers, or a single worker by ID. Returns worker names, contact details, locations, and status.
Required scope:
workers:read
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer | No | Return a single worker by ID. Overrides other filters. |
| location_id | integer | No | Filter workers by their assigned location. |
| active | boolean | No | Filter by active status. Use 1 for active, 0 for inactive. |
| search | string | No | Search by first name, last name, or employee reference. |
| limit | integer | No | Number of results per page. Default: 50, max: 100. |
| offset | integer | No | Number of results to skip for pagination. Default: 0. |
Example Request — List Workers
curl -H "Authorization: Bearer tc_live_a1b2c3..." \
"https://tempclock.com/api/v1/workers.php?active=1&location_id=3&limit=2"
Example Response
{
"data": [
{
"id": 142,
"first_name": "Sarah",
"last_name": "Mitchell",
"employee_ref": "EMP-0142",
"email": "s.mitchell@example.com",
"phone": "07700 900142",
"location_id": 3,
"location_name": "Manchester Warehouse",
"department": "Picking",
"active": true,
"created_at": "2025-06-15T09:30:00Z"
},
{
"id": 156,
"first_name": "James",
"last_name": "Okonkwo",
"employee_ref": "EMP-0156",
"email": "j.okonkwo@example.com",
"phone": "07700 900156",
"location_id": 3,
"location_name": "Manchester Warehouse",
"department": "Packing",
"active": true,
"created_at": "2025-08-22T14:15:00Z"
}
],
"pagination": {
"total": 34,
"limit": 2,
"offset": 0,
"has_more": true
}
}
Example Request — Single Worker
curl -H "Authorization: Bearer tc_live_a1b2c3..." \
"https://tempclock.com/api/v1/workers.php?id=142"
Example Response
{
"data": {
"id": 142,
"first_name": "Sarah",
"last_name": "Mitchell",
"employee_ref": "EMP-0142",
"email": "s.mitchell@example.com",
"phone": "07700 900142",
"location_id": 3,
"location_name": "Manchester Warehouse",
"department": "Picking",
"active": true,
"created_at": "2025-06-15T09:30:00Z"
}
}
GET
/timesheets.php
Retrieve a paginated list of time entries (clock-in/clock-out records). Filter by date range, worker, or location. Ideal for payroll integrations and reporting.
Required scope:
timesheets:read
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| date_from | string | No | Start date filter in YYYY-MM-DD format. |
| date_to | string | No | End date filter in YYYY-MM-DD format. |
| worker_id | integer | No | Filter entries for a specific worker. |
| location_id | integer | No | Filter entries by location. |
| limit | integer | No | Results per page. Default: 50, max: 100. |
| offset | integer | No | Number of results to skip. Default: 0. |
Example Request
curl -H "Authorization: Bearer tc_live_a1b2c3..." \
"https://tempclock.com/api/v1/timesheets.php?date_from=2026-03-01&date_to=2026-03-07&location_id=3"
Example Response
{
"data": [
{
"id": 8921,
"worker_id": 142,
"worker_name": "Sarah Mitchell",
"location_id": 3,
"location_name": "Manchester Warehouse",
"date": "2026-03-03",
"clock_in": "2026-03-03T07:02:14Z",
"clock_out": "2026-03-03T15:31:47Z",
"hours_worked": 8.49,
"break_minutes": 30,
"status": "approved",
"clock_in_method": "facial_recognition",
"notes": null
},
{
"id": 8935,
"worker_id": 156,
"worker_name": "James Okonkwo",
"location_id": 3,
"location_name": "Manchester Warehouse",
"date": "2026-03-03",
"clock_in": "2026-03-03T06:58:33Z",
"clock_out": "2026-03-03T14:05:12Z",
"hours_worked": 7.11,
"break_minutes": 0,
"status": "approved",
"clock_in_method": "pin",
"notes": "Early finish — medical appointment"
}
],
"pagination": {
"total": 128,
"limit": 50,
"offset": 0,
"has_more": true
}
}
GET
/locations.php
Retrieve a list of locations (work sites), or a single location by ID. Includes address, capacity, and active status.
Required scope:
locations:read
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | integer | No | Return a single location by ID. |
| active | boolean | No | Filter by active status. 1 for active, 0 for inactive. |
| limit | integer | No | Results per page. Default: 50, max: 100. |
| offset | integer | No | Number of results to skip. Default: 0. |
Example Request
curl -H "Authorization: Bearer tc_live_a1b2c3..." \
"https://tempclock.com/api/v1/locations.php?active=1"
Example Response
{
"data": [
{
"id": 1,
"name": "London Head Office",
"address": "45 King Street, London EC2V 8DQ",
"capacity": 200,
"active": true,
"created_at": "2024-01-10T08:00:00Z"
},
{
"id": 3,
"name": "Manchester Warehouse",
"address": "Unit 12, Trafford Park, Manchester M17 1HH",
"capacity": 150,
"active": true,
"created_at": "2024-03-15T10:30:00Z"
}
],
"pagination": {
"total": 5,
"limit": 50,
"offset": 0,
"has_more": false
}
}
POST
/clock.php
Clock a worker in or out. This creates a real time entry in the system, identical to a kiosk clock-in. Use with care in production environments.
Required scope:
clock:write
Request Body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
| worker_id | integer | Yes | The ID of the worker to clock in or out. |
| action | string | Yes | Either "in" or "out". |
| location_id | integer | No | Location to clock in at. Defaults to the worker's assigned location. |
| notes | string | No | Optional note attached to the time entry. |
Example Request — Clock In
curl -X POST \
"https://tempclock.com/api/v1/clock.php" \
-H "Authorization: Bearer tc_live_a1b2c3..." \
-H "Content-Type: application/json" \
-d '{
"worker_id": 142,
"action": "in",
"location_id": 3,
"notes": "Clocked in via API integration"
}'
Example Response (201 Created)
{
"data": {
"id": 9012,
"worker_id": 142,
"worker_name": "Sarah Mitchell",
"action": "in",
"location_id": 3,
"location_name": "Manchester Warehouse",
"timestamp": "2026-03-10T07:02:00Z",
"notes": "Clocked in via API integration"
},
"message": "Worker clocked in successfully."
}
Error Responses
409 Conflict — Returned if the worker is already clocked in and you attempt another clock-in, or if the worker has no open clock-in and you attempt a clock-out.
{ "error": true, "message": "Worker is already clocked in.", "status": 409 }
400 Bad Request — Returned if required fields are missing or the action value is not “in” or “out”.
404 Not Found — Returned if the worker_id does not exist or belongs to another client.
GET
POST
/shifts.php
List scheduled shifts or create new ones. GET retrieves existing shifts with filtering; POST creates a new shift assignment for a worker.
Required scopes:
shifts:read (GET)
shifts:write (POST)
GET Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| date_from | string | No | Start date filter (YYYY-MM-DD). |
| date_to | string | No | End date filter (YYYY-MM-DD). |
| worker_id | integer | No | Filter shifts for a specific worker. |
| location_id | integer | No | Filter shifts by location. |
| limit | integer | No | Results per page. Default: 50, max: 100. |
| offset | integer | No | Number of results to skip. Default: 0. |
GET Example Request
curl -H "Authorization: Bearer tc_live_a1b2c3..." \
"https://tempclock.com/api/v1/shifts.php?date_from=2026-03-10&date_to=2026-03-14&location_id=3"
GET Example Response
{
"data": [
{
"id": 504,
"worker_id": 142,
"worker_name": "Sarah Mitchell",
"location_id": 3,
"location_name": "Manchester Warehouse",
"shift_date": "2026-03-10",
"start_time": "07:00",
"end_time": "15:00",
"notes": null
},
{
"id": 505,
"worker_id": 156,
"worker_name": "James Okonkwo",
"location_id": 3,
"location_name": "Manchester Warehouse",
"shift_date": "2026-03-10",
"start_time": "06:00",
"end_time": "14:00",
"notes": "Early start — goods delivery"
}
],
"pagination": {
"total": 18,
"limit": 50,
"offset": 0,
"has_more": false
}
}
POST Request Body (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
| worker_id | integer | Yes | The worker to assign the shift to. |
| shift_date | string | Yes | Date of the shift (YYYY-MM-DD). |
| start_time | string | Yes | Shift start time in HH:MM 24-hour format. |
| end_time | string | Yes | Shift end time in HH:MM 24-hour format. |
| location_id | integer | No | Location for the shift. Defaults to the worker's assigned location. |
| notes | string | No | Optional note for the shift. |
POST Example Request
curl -X POST \
"https://tempclock.com/api/v1/shifts.php" \
-H "Authorization: Bearer tc_live_a1b2c3..." \
-H "Content-Type: application/json" \
-d '{
"worker_id": 142,
"shift_date": "2026-03-15",
"start_time": "08:00",
"end_time": "16:00",
"location_id": 3,
"notes": "Saturday overtime shift"
}'
POST Example Response (201 Created)
{
"data": {
"id": 512,
"worker_id": 142,
"worker_name": "Sarah Mitchell",
"location_id": 3,
"location_name": "Manchester Warehouse",
"shift_date": "2026-03-15",
"start_time": "08:00",
"end_time": "16:00",
"notes": "Saturday overtime shift"
},
"message": "Shift created successfully."
}
GET
/departments.php
Retrieve a list of departments configured for your account. Useful for mapping workers to organisational units.
Required scope:
departments:read
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| active | boolean | No | Filter by active status. 1 for active, 0 for inactive. |
| limit | integer | No | Results per page. Default: 50, max: 100. |
| offset | integer | No | Number of results to skip. Default: 0. |
Example Request
curl -H "Authorization: Bearer tc_live_a1b2c3..." \
"https://tempclock.com/api/v1/departments.php?active=1"
Example Response
{
"data": [
{
"id": 1,
"name": "Picking",
"active": true,
"created_at": "2024-01-10T08:00:00Z"
},
{
"id": 2,
"name": "Packing",
"active": true,
"created_at": "2024-01-10T08:00:00Z"
},
{
"id": 3,
"name": "Driving",
"active": true,
"created_at": "2024-02-20T11:15:00Z"
},
{
"id": 4,
"name": "Administration",
"active": true,
"created_at": "2024-03-01T09:00:00Z"
}
],
"pagination": {
"total": 4,
"limit": 50,
"offset": 0,
"has_more": false
}
}
GET
/cost-codes.php
Retrieve a list of cost codes used for project tracking and financial reporting. Cost codes allow you to allocate time entries to specific projects or budgets.
Required scope:
cost-codes:read
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| active | boolean | No | Filter by active status. |
| limit | integer | No | Results per page. Default: 50, max: 100. |
| offset | integer | No | Number of results to skip. Default: 0. |
Example Request
curl -H "Authorization: Bearer tc_live_a1b2c3..." \
"https://tempclock.com/api/v1/cost-codes.php?active=1"
Example Response
{
"data": [
{
"id": 1,
"code": "PRJ-001",
"name": "Warehouse Expansion Phase 2",
"active": true,
"created_at": "2025-09-01T08:00:00Z"
},
{
"id": 2,
"code": "PRJ-002",
"name": "Seasonal Q1 Campaign",
"active": true,
"created_at": "2026-01-05T10:30:00Z"
},
{
"id": 3,
"code": "GEN-OPS",
"name": "General Operations",
"active": true,
"created_at": "2024-01-10T08:00:00Z"
}
],
"pagination": {
"total": 3,
"limit": 50,
"offset": 0,
"has_more": false
}
}
Changelog
API version history and notable changes.
v1.0
Current
January 2026
- Initial public API release
- 7 endpoints: workers, timesheets, locations, clock, shifts, departments, cost-codes
- Bearer token authentication with scoped API keys
- Rate limiting at 60 requests/minute per key
- Paginated list responses with consistent format