Code examples

export TC_BASE="https://tempclock.com/api/v1"   # your TempClock address + /api/v1
export TC_KEY="tc_live_..."                       # Setup > API keys

curl

curl -s "$TC_BASE/me.php" -H "Authorization: Bearer $TC_KEY"

PHP

<?php
$ch = curl_init(getenv('TC_BASE') . '/me.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('TC_KEY')],
]);
$me = json_decode(curl_exec($ch), true);
echo $me['data']['client_name'], ': ', implode(', ', $me['data']['effective_scopes']), "\n";

Python

import os, time, uuid, requests

BASE, KEY = os.environ["TC_BASE"], os.environ["TC_KEY"]

class TempClockError(Exception):
    def __init__(self, status, body, request_id):
        self.status, self.code, self.request_id = status, body.get("error_code"), request_id
        super().__init__(f"{status} {self.code}: {body.get('message')} (request {request_id})")

def tc(method, path, params=None, body=None, idempotency_key=None):
    headers = {"Authorization": f"Bearer {KEY}"}
    if method in ("POST", "PUT"):
        headers["Idempotency-Key"] = idempotency_key or str(uuid.uuid4())   # the same key on every retry
    for attempt in range(5):
        r = requests.request(method, f"{BASE}/{path}", params=params, json=body, headers=headers, timeout=30)
        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", "60"))); continue
        if r.status_code >= 500:
            time.sleep(2 ** attempt); continue
        j = r.json()
        if r.status_code >= 400:
            raise TempClockError(r.status_code, j, r.headers.get("X-Request-Id"))
        return j
    raise TempClockError(r.status_code, r.json(), r.headers.get("X-Request-Id"))

Python

def all_rows(path, **params):
    offset = 0
    while True:
        page = tc("GET", path, params={**params, "limit": 100, "offset": offset})
        yield from page["data"]
        if not page["pagination"]["has_more"]:
            return
        offset += page["pagination"]["limit"]

for w in all_rows("workers.php", active="true"):
    print(w["employee_id"], w["name"], w["department_id"])

Python

def pull_pay_week(any_date):
    week = tc("GET", "pay-weeks.php", params={"week_start": any_date})["data"][0]
    if week["status"] not in ("locked", "exported"):
        raise RuntimeError(f"Week of {week['week_start']} is {week['status']}: "
                           f"{week['exceptions_open']} shifts still to sort out")
    lines, adjustments, offset = [], [], 0
    while True:
        page = tc("GET", "payroll.php", params={"week": week["week_start"], "limit": 200,
                                                 "offset": offset, "adjustments": 1})
        lines += page["data"]
        adjustments = page.get("adjustments", adjustments)
        if not page["pagination"]["has_more"]:
            break
        offset += 200
    for line in lines:
        for el in line["pay_elements"]:
            import_pay_line(line["employee_id"], el["sage_ref"], el["hours"], el["pay_rate"],
                            el["pay"], el["department"], el["cost_centre"])
    for a in adjustments:
        if a["state"] == "due" and a["adjust_week"] == week["week_start"]:
            flag_late_clock(a["employee_id"], a["clock_in"], a["paid_minutes"])
    return week["batches"]          # the Sage files TempClock made for this week

Node.js

// Node.js 18+ (global fetch)
const BASE = process.env.TC_BASE, KEY = process.env.TC_KEY;

async function tc(path, params = {}) {
  const url = new URL(`${BASE}/${path}`);
  Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
  for (;;) {
    const r = await fetch(url, { headers: { Authorization: `Bearer ${KEY}` } });
    if (r.status === 429) { await new Promise(s => setTimeout(s, 1000 * (r.headers.get('Retry-After') || 60))); continue; }
    const j = await r.json();
    if (!r.ok) throw new Error(`${r.status} ${j.error_code}: ${j.message} (request ${r.headers.get('X-Request-Id')})`);
    return j;
  }
}

async function syncWorkers(lastRunStartedAt) {           // e.g. '2026-10-05T23:00:00Z'
  const startedAt = new Date(Date.now() - 60_000).toISOString();  // a minute early, from our own clock
  let offset = 0, page;
  do {
    page = await tc('workers.php', { updated_since: lastRunStartedAt, limit: 100, offset });
    for (const w of page.data) {
      await upsertWorker(w.id, {                         // keyed on id: a repeat is harmless
        employeeId: w.employee_id, name: w.name, active: w.active, status: w.status,
        siteId: w.location_id, departmentId: w.department_id, costCodeId: w.cost_code_id,
      });
    }
    offset += page.pagination.limit;
  } while (page.pagination.has_more);
  return startedAt;                                      // store it for the next run
}

Python

import hashlib

def send_badge_read(read):                       # read = {"badge": "AX014", "direction": "in", "at": "2026-10-06T05:58:41Z", "terminal": "GATE-2"}
    key = hashlib.sha256(f"{read['terminal']}|{read['badge']}|{read['at']}".encode()).hexdigest()[:40]
    try:
        r = tc("POST", "clock.php", idempotency_key=key, body={
            "employee_id": read["badge"],
            "action": read["direction"],          # "in" or "out"
            "location_id": GATE_SITE_ID,
            "occurred_at": read["at"],
        })
        return r["data"]["entry_id"]
    except TempClockError as e:
        if e.code in ("already_clocked_in", "no_open_clock_in"):
            return None                           # a double read: nothing to do
        if e.code in ("worker_pending", "worker_inactive", "not_found"):
            alert_supervisor(read, e)             # someone who should not be on site
            return None
        raise

PHP

<?php
function tc(string $method, string $path, ?array $body = null): array {
    $ch = curl_init(getenv('TC_BASE') . '/' . $path);
    $h = ['Authorization: Bearer ' . getenv('TC_KEY'), 'Content-Type: application/json',
          'Idempotency-Key: ' . bin2hex(random_bytes(16))];
    curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => $method, CURLOPT_HTTPHEADER => $h]);
    if ($body !== null) curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
    $j = json_decode((string)curl_exec($ch), true);
    if (!empty($j['error'])) throw new RuntimeException($j['error_code'] . ': ' . $j['message']);
    return $j;
}

$siteId = 37; $workerId = 377;      // ids from your account (GET /locations.php, /workers.php)

// A requirement for 3 pickers, then one worker booked onto it.
$req = tc('POST', 'demands.php', ['location_id' => $siteId, 'shift_date' => '2026-10-28',
          'start_time' => '06:00', 'end_time' => '14:00', 'headcount' => 3, 'job_role' => 'Picker']);
try {
    $shift = tc('POST', 'shifts.php', ['worker_id' => $workerId, 'demand_id' => $req['data']['id'], 'status' => 'published']);
} catch (RuntimeException $e) {
    // not_eligible: the worker cannot take it (block_codes says why, for example overlap or absence)
    exit($e->getMessage() . "\n");
}
// The client cancels: the slot shows as open again and the cancelled-booking pay policy applies.
tc('POST', 'shifts.php?id=' . $shift['data']['id'] . '&action=cancel',
   ['status' => 'client_cancelled', 'cancel_reason' => 'Client reduced headcount']);

Node.js

const crypto = require('crypto');
function verifyTempClock(rawBody, signatureHeader, secret) {
  const want = Buffer.from('sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex'));
  const sent = Buffer.from(signatureHeader || '');
  return want.length === sent.length && crypto.timingSafeEqual(want, sent);
}