Skip to content
TimeTracking

Request an integration

Tell us which system you want to connect. We review every request weekly and publish a step-by-step guide or build the connection.

API changelog

Changes to the TimeTracking REST API, webhooks, CLI and MCP server, newest first.

Last updated: · Markdown version

Late hours and reminders — October 2026

  • late in GET /org/week. Rows get late (boolean), kpis.late counts people, and deadline gives the deadline of the payroll period containing the week (date, minute, passed).
  • Notifications for employees. GET /me/notifications (items + unread count) and POST /me/notifications/read.
  • Reminder settings. GET /org/reminders and PUT /org/reminders (admin): deadline weekday + time, in-app reminders on/off, WhatsApp follow-up on/off and delay (default Monday 09:00, WhatsApp after 90 minutes). Reminders never go by email.

1.1.0 update — October 2026 (fixes)

  • API key scope admin. It implies write. Admin keys can lock periods, manage webhooks (incl. deliveries, test, replay, rotate-secret) and kiosk devices, anonymize people, and list/revoke API keys. No API key can create keys or change office roles (403 Not available with an API key). Admin keys are created with POST /api-keys and an admin user token.
  • Read keys can now list /leave, /expenses, /shifts and /inbox. Export preview (POST /exports) still needs a write or admin key.
  • Idempotency-Key on every authenticated write route, including /exports, /days/approve, /approval-links, /periods/lock, /weeks/submit, /conflicts/{id}/resolve and /import.
  • Events. person.* and placement.* fire from every API create/update path (POST, PATCH, by-external, batch; DELETE → *.updated with active:false). Payloads now carry only the ID. New events client.created, client.updated, conflict.resolved (21 in total).
  • Webhook retries. Exactly 7 delivery attempts (retries after 1 m, 5 m, 30 m, 2 h, 6 h, 12 h).
  • Windows-1252. GET /exports/runs/{id}/file delivers mappings with encoding: "windows-1252" as Windows-1252 (Latin-1 bytes; unsupported characters → ?).
  • Claims on exported/locked days are refused with 423 before anything is stored. New message: This day is exported or locked; book a correction in an open period.
  • Client by-external upserts keep their external reference on repeat calls.
  • People write responses no longer include kiosk_pin_hash.
  • Kiosk PINs are exactly 6 digits. The MCP tool and Claude Skill descriptions now say that approval links are emailed, and that record_hours returns 423 for exported days.

1.1.0 — October 2026

Master data sync

  • PUT /people/by-external/{source}/{ref}, PUT /clients/by-external/{source}/{ref}, PUT /placements/by-external/{source}/{ref}: idempotent upsert by your own system's ID. Placements accept personExternalRef / clientExternalRef from the same source. Responses include external_source, external_ref and created.
  • GET, PATCH and DELETE on /people/{id}, /clients/{id} and /placements/{id}. PATCH takes the full object. DELETE deactivates people and placements; a client can only be deleted when it has no placements (otherwise 409).
  • Batch endpoints POST /people/batch, /clients/batch, /placements/batch, /claims/batch: up to 500 items, results per row ({ok, failed, results}).

Reads

  • Cursor pagination (limit, cursor, updated_since → {items, next_cursor}) on /people, /clients, /placements. Without those parameters the v1 full-array response is unchanged.
  • GET /days: resolved hours over any date range, with filters on status, person, placement, client and updated_since.
  • GET /claims: raw claims over a date range.
  • GET /exports/runs, GET /exports/runs/{id} (pay lines, warnings, mapping snapshot), GET /exports/runs/{id}/file (the committed file).

Webhooks

  • New events: person.created, person.updated, placement.created, placement.updated, claim.created, expense.decided, leave.cancelled, webhook.test (client.* and conflict.resolved followed in the 1.1.0 update).
  • GET /webhooks/{id}/deliveries, POST /webhooks/{id}/test, POST /webhooks/{id}/rotate-secret, POST /webhook-deliveries/{id}/replay.
  • The spec now has a webhooks section with the event envelope schema.

Reliability and security

  • Idempotency-Key header on writes (24 h replay, idempotent-replayed: true). See idempotency for the routes that do not honour it yet.
  • Rate limit of 600 requests per minute per API key (429 + Retry-After: 60).
  • Invalid JSON bodies return 422 instead of 500.
  • Client approval now requires an emailed code when the client has an approver contact (POST /client/approve/{token}/code, /verify → proof, header x-approval-proof).
  • Webhook URLs must be public HTTPS. Private and loopback addresses are rejected and redirects are not followed.

Spec

  • OpenAPI 3.1 spec version 1.1.0: 64 paths, operationIds, response schemas, error schema, examples.

Dashboard (related)

  • Admins can edit export mappings ("Exportformaten") in the dashboard: copy a preset, edit columns, code tables and validation, set a default.

1.0.0 — October 2026

  • First public API: 44 paths covering hours (/org/week, /claims, /weeks/submit, /days/approve, /conflicts), client approval links, exports (preview/commit), period lock, master data (/people, /clients, /placements, /import), rosters, leave, expenses, inbox, kiosk, employee self-service (/me/*), API keys and webhooks.
  • 10 webhook events signed with tt-signature (HMAC-SHA256).
  • CLI @timetracking/cli (tt), MCP server @timetracking/mcp (18 tools), Claude Skill timetracking.

Planned

  • Export-mapping CRUD over the API (today the dashboard only).
  • OAuth2 for marketplace apps.
  • Sandbox organisations and test keys.
  • TypeScript and Python SDKs.
  • Bulk export feed for BI.
  • CLI and MCP commands for the v1.1 endpoints (use tt api meanwhile).