Guides

Recipes

The integrations people build most, each in a few steps you can copy. Every example works with an API key; pick your region first.

Export approved hours to payroll or BI#

Wait for timesheets to be approved, then read the period's totals. Needs time:read (and reports:read for the CSV).

Listen for approvals
Subscribe a webhook to timesheet.approved and timesheet.reopened. The event has the person and period_start.
Read the period
Get one row per person with worked, overtime, time off and status for the pay period that contains date:

curl -G https://ca-api.clocklap.com/v1/timesheets -H "Authorization: Bearer $CLOCKLAP_API_KEY" -d date=2026-10-19

const res = await fetch('https://ca-api.clocklap.com/v1/timesheets?date=2026-10-19', { headers: { Authorization: `Bearer ${process.env.CLOCKLAP_API_KEY}` } });
const grid = await res.json();
const approved = grid.data.filter((row) => row.status === 'approved');

grid = requests.get("https://ca-api.clocklap.com/v1/timesheets", headers=HEADERS, params={"date": "2026-10-19"}).json()
approved = [row for row in grid["data"] if row["status"] == "approved"]

Prefer a file? GET /v1/timesheets/export?date=2026-10-19&format=summary returns CSV (formats: summary, detail, adp, quickbooks). For ADP, Gusto, QuickBooks and others there's no code to write: use Connections in the console.

Overtime is worked out per person per week, across all their sites, so read it from the timesheet rather than adding up shifts yourself.

Show who’s on site#

For a wall screen or a muster list. Needs time:read.

curl -G https://ca-api.clocklap.com/v1/live/attendance -H "Authorization: Bearer $CLOCKLAP_API_KEY" -d location_id=loc_01J9Q…

const live = await (await fetch('https://ca-api.clocklap.com/v1/live/attendance?location_id=loc_01J9Q…', { headers: { Authorization: `Bearer ${process.env.CLOCKLAP_API_KEY}` } })).json();
console.log(live.counts); // { on_site, on_break, late, off_today }
for (const e of live.people) console.log(e.user.name, 'since', e.clock_in_at);

The response has counts and people (each an open shift with the person). To update instantly instead of every minute, subscribe to time_entry.clocked_in, time_entry.clocked_out, break.started and break.ended.

Keep people in step with your HR system#

Match people by the ID your HR system uses, then add or update them. Needs people:read and people:write.

Look the person up by your ID
GET /v1/users/lookup?key=bamboohr_employee_id&value=1042 returns them, or 404 if they’re new. key is a kind of external ID: built-in ones such as bamboohr_employee_id or adp_file_number, or your own. List them with GET /v1/external-id-keys.
Add new people
POST /v1/users with their name, email, sites and role. They get an invite to install the app unless you send "send_invite": false.
Update the rest
PATCH /v1/users/{id} with what changed. To end someone’s access when they leave: POST /v1/users/{id}/archive.

curl -X POST https://ca-api.clocklap.com/v1/users \
  -H "Authorization: Bearer $CLOCKLAP_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: hr-sync-1042" \
  -d '{
    "name": "Ava Singh",
    "email": "[email protected]",
    "employee_no": "E1002",
    "location_ids": ["loc_01J9Q…"],
    "role_key": "worker",
    "external_ids": { "bamboohr_employee_id": "1042" }
  }'

Using Okta, Microsoft Entra ID or Google Workspace? SCIM does this for you. BambooHR, HiBob, Personio, Rippling and Workday connect without code under Connections.

Clock people in from your own system#

For a badge reader, a door controller or another app. Send a punch on the person's behalf with source: "api". Needs time:write.

curl -X POST https://ca-api.clocklap.com/v1/punches \
  -H "Authorization: Bearer $CLOCKLAP_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "type": "in",
    "at": "2026-10-26T08:02:00-04:00",
    "source": "api",
    "user_id": "usr_01J9…",
    "location_id": "loc_01J9Q…",
    "local_id": "door-7-20261026-080200-ava"
  }'

type is in, out, break_start or break_end.
local_id is your own unique ID for this punch (6 to 64 characters). Send the same punch twice and the second gets 200 instead of 201: nothing is doubled.
A punch that can't apply gets 422 with a code such as already_clocked_in or not_clocked_in (see punch errors).
Sending many at once? POST /v1/punches/batch takes up to 200.

Add or fix a shift#

Someone forgot to clock in. Add the shift with a reason (it's kept in the shift's history). Needs time:write.

curl -X POST https://ca-api.clocklap.com/v1/time-entries \
  -H "Authorization: Bearer $CLOCKLAP_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_01J9…",
    "location_id": "loc_01J9Q…",
    "clock_in_at": "2026-10-26T08:00:00-04:00",
    "clock_out_at": "2026-10-26T16:30:00-04:00",
    "reason": "Forgot to clock in; confirmed with supervisor"
  }'

To change one: PATCH /v1/time-entries/{id} with the new times and a reason. Hours in a locked pay period can't change (entry_locked).

Get a report as a file#

Ask for it
POST /v1/exports with kind (hours, overtime, attendance, timesheet, people, locations, time, attendance_insights), format (csv, xlsx or pdf) and params. You get 202 and an export id.
Wait for it
Subscribe to export.completed, or check GET /v1/exports/{id} every few seconds.
Download it
GET /v1/exports/{id}/download. Files are kept for 30 days.