TimeTracking developer documentation
What you can build on TimeTracking and the three ways to integrate: the REST API, AI tools (CLI, MCP server, Claude Skill), and file-based import/export.
Last updated: · Markdown version
TimeTracking is B2B time tracking for staffing agencies and employers. Employees record hours per placement (a person working for a client), clients confirm them, the office approves them, and approved hours go to payroll as an export file. Every piece of data is readable and writable over a REST API (version 1.1).
These pages are written for people and for LLMs. Each page stands on its own, uses exact field names, and has copy-pasteable examples. Example responses were captured from the real API.
What you can build
- ATS/CRM → TimeTracking master data sync. Push candidates, clients and placements from Bullhorn, Carerix, Salesforce and similar systems. Use idempotent upserts by your own IDs (
PUT /people/by-external/{source}/{ref}). - Hours in from any source. Office entries, client timesheets and imports go to
POST /claimsorPOST /claims/batch. Client emails go to the inbound email pipeline. Tablets on site use the kiosk. - Approved hours out to payroll. Run export mappings (SD Worx concept preset, generic CSV/XML/fixed-width TXT, or your own format edited in the dashboard). Fetch committed files with
GET /exports/runs/{id}/file. - Event-driven automations. Webhooks cover submitted and approved timesheets, conflicts (created and resolved), exports, locks, leave, expenses, shifts, people, clients, placements and claims. They are signed with HMAC-SHA256 and can be replayed.
- BI and reporting. Read resolved hours over any date range with
GET /days, with cursor pagination andupdated_since. - AI assistants that run the weekly close. Use the MCP server, the CLI and the Claude Skill. Copy-paste prompts are in prompts.
Three integration paths
| Path | Use it when | Start here |
|---|---|---|
REST API (https://app.timetracking.tech/api/v1) |
You write code or use an iPaaS (Zapier, Make, n8n) | Quickstart · Authentication · API reference · Webhooks |
| CLI / MCP / Claude Skill | A person or an AI assistant operates TimeTracking from a terminal or chat | CLI · MCP server · Claude Skill · ChatGPT Actions · Prompts |
| File-based | The other system only speaks CSV/XLSX or email | CSV import · Competitor import · Inbound email · Export mappings · Payroll files |
Core rules, in one place
- Units: durations are integer minutes (7.5 h =
450). Money is integer cents. Dates areYYYY-MM-DD. Times of day are minutes after midnight (startMin: 420= 07:00). - Envelope: a success is
{ "data": … }. A failure is{ "error": { "code", "message" } }, plusissueson validation errors. - Status flow: a day moves
draft → submitted → approved → exported → locked. Exported and locked days never change; a correction goes into an open period. See status lifecycle. - Claims vs days: you write raw claims (one per source). TimeTracking resolves them into one day value per placement and date. When sources disagree, the day gets a conflict that a person resolves. See sources and conflicts.
- Credentials: an org API key (
tt_live_…) has scoperead,writeoradmin(admin implies write and also allows webhooks, period lock, kiosk devices and GDPR erasure). Creating API keys and changing office roles always need a signed-in admin. See authentication.
Integration status
| Status | Meaning |
|---|---|
| Live | Shipped and supported: REST API v1.1, webhooks, CLI, MCP server, Claude Skill, inbound email, CSV master-data import, generic CSV export (plus XLSX/JSON download in the dashboard), SD Worx concept export preset, export mappings editable in the dashboard |
| Recipe | Works today if you combine the API, webhooks, export mappings or an iPaaS yourself. Each system has a step-by-step guide |
| Planned | Not available yet: export-mapping CRUD over the API, OAuth2 marketplace apps, sandbox/test keys, SDKs, native iPaaS apps, BI bulk feed |
See the integration matrix for every system.
Page map
- Concepts: data model · glossary · status lifecycle · sources and conflicts · hour types and rule packs · periods and locking
- API: authentication · errors · rate limits · pagination · idempotency · versioning · changelog · reference
- Webhooks: overview · events · verify signatures · retries
- Data in: CSV import · Toggl/Clockify/TimeChimp/Harvest import · inbound email · client approval links · kiosk
- Data out: export mappings · presets · payroll files
- Office help: weekly close · import · export and lock · client approval · inbox · kiosk setup
All developer docs
Quickstart
In five minutes: create an API key, make your first GET, record hours and preview a payroll export, with curl, TypeScript and Python.
How-to guides
Step-by-step guides for the things teams ask most: connect your CRM or ATS, send hours to payroll, import workers, get client approval, set up a kiosk and use Claude.
How to add TimeTracking to your own CRM
Connect any CRM, ATS or back office you built or run yourself: push workers, clients and placements in with external IDs, and pull approved hours back, with or without code.
Authentication
How to authenticate to the TimeTracking API with org API keys (read, write or admin scope) or user access tokens, what each credential may do, and how to create, rotate and revoke keys.
API changelog
Changes to the TimeTracking REST API, webhooks, CLI and MCP server, newest first.
Errors
The TimeTracking API error envelope, every HTTP status and error code, real error messages captured from the API, and how a client should react to each.
Idempotency
Safe retries in the TimeTracking API: the Idempotency-Key header, upsert by external ID, client-generated claim IDs, and which endpoints honour which mechanism.
Pagination
Cursor pagination with limit, cursor and updated_since on TimeTracking list endpoints, which endpoints support it, and how to run incremental syncs.
Rate limits
The TimeTracking API allows 600 requests per minute per API key; how the window works, what a 429 looks like, and how to stay under the limit with batch endpoints and pagination.
API reference
Every TimeTracking REST API v1.1 endpoint with parameters, request fields, who may call it, and real captured request/response examples.
Versioning
How the TimeTracking API is versioned (/v1 path, spec version 1.1.0), what counts as a breaking change, and how to detect the version you are talking to.
Data model
The TimeTracking entities (organisation, person, client, placement, claim, day, conflict, leave, expense, shift, export run, period) and how they relate.
Glossary
Definitions of TimeTracking terms with their Dutch UI labels: placement, claim, day, conflict, approval mode, export mapping, rule pack, period lock and more.
Hour types and rule packs
How approved minutes are split into payroll hour types (normal, overtime, ORT bands, holidays) by a JSON rule pack, which compliance warnings it raises, and the full list of hour-type codes.
Periods and locking
Payroll period kinds, how export commit and period lock freeze hours, the preconditions for locking, and how to handle corrections after a period is closed.
Sources and conflicts
How TimeTracking merges raw claims from the app, kiosk, client email, imports, the office and the client portal into one value per day, and how conflicts are detected and resolved.
Status lifecycle
How a timesheet day moves from draft to submitted, approved, exported and locked; who may make each transition; and how client approval modes and corrections interact.
Client approval links
Magic links that let a client contact approve, correct or reject hours without an account: creating links, the email-code verification flow, the public endpoints, and how decisions change day status.
Importing from Toggl, Clockify, TimeChimp and Harvest
Import time entries from Toggl Track, Clockify, TimeChimp and Harvest CSV exports: recognised columns, date and duration formats, matching to people and placements, dry run, person mapping and POST /import/time-entries.
CSV master-data import
Exact CSV format for importing people, clients and placements into TimeTracking: header aliases (Dutch and English), date formats, matching rules, dry run and the POST /import response.
Inbound email (client timesheets)
How clients email timesheets to TimeTracking: the address, sender verification and quarantine, supported formats (CSV, XLSX, text, PDF/photo with AI), table layouts and header aliases, matching rules, and the inbox API.
Kiosk (clock in/out tablets)
How the TimeTracking kiosk works: device tokens, 6-digit PINs, the identify and punch endpoints, automatic breaks, lockout rules, and how punches become kiosk claims.
Export mappings
The ExportMapping JSON schema that turns TimeTracking pay lines into a payroll import file: fields, every transform with input/output examples, code tables, grouping, validation, and how to create and use mappings.
Payroll files
End-to-end payroll export with the TimeTracking API: preview, commit, fetching the committed file, automating on export.completed, locking, and reconciling with GET /days.
Export presets
The built-in export mappings preset-sdworx (SD Worx concept), preset-generic (generic CSV per day), preset-generic-xml and preset-generic-fixed: full JSON, real output, and their limitations.
Client approval
Office guide: set up which clients must approve hours, send secure approval links, and handle corrections and rejections.
Export and lock
Office guide: preview, export and download the payroll file, then lock the period once payroll has processed it.
Import master data
Office guide: import employees, clients and placements from one CSV file, with a check before anything is saved.
Inbox (client timesheets)
Office guide: receive client timesheets by email or upload, let TimeTracking read them, and review what it could not apply automatically.
Kiosk setup
Office guide: set up a tablet on site where workers clock in and out with a PIN.
Weekly close
Step-by-step guide for office staff: check, correct and approve a week of hours in TimeTracking, then hand over to export.
Integrations
Matrix of every system TimeTracking connects to, with honest status (Live, Recipe, Planned), mechanism and data direction.
Bullhorn integration
Sync Bullhorn candidates, client corporations and placements into TimeTracking with external-ID upserts and batch endpoints, and push approved hours back with GET /days.
Carerix integration
Sync Carerix employees, companies and placements into TimeTracking with external-ID upserts and batches, and report approved hours back with GET /days.
HubSpot integration
Create TimeTracking clients and placements from HubSpot companies and won deals with external-ID upserts, and write approved-hour totals back using GET /days.
OTYS integration
Sync OTYS candidates, relations and placements into TimeTracking with external-ID upserts, batches and the OTYS web services.
Pipedrive integration
Create TimeTracking clients and placements from won Pipedrive deals using Pipedrive webhooks and idempotent external-ID upserts.
Recruitee integration
Create TimeTracking people and placements when a Recruitee candidate is hired, using a Recruitee webhook and idempotent external-ID upserts.
Salesforce integration
Sync Salesforce Accounts, Contacts and a custom Placement object with TimeTracking using Apex callouts to external-ID upserts, and pull approved hours with GET /days.
Looker Studio
Report on TimeTracking hours in Looker Studio by loading GET /days and master data into Google Sheets with Apps Script and a read-only key.
Power BI
Load TimeTracking days, claims, export runs and master data into Power BI with Power Query, a read-only API key and cursor pagination.
Google Calendar integration
Put published TimeTracking shifts into Google Calendar with the shift.published webhook, GET /shifts and the Google Calendar API.
Microsoft 365 (Outlook) calendar integration
Put published TimeTracking shifts into Outlook calendars with the shift.published webhook, GET /shifts and Microsoft Graph.
Slack notifications
Post TimeTracking events (submitted, approved, conflicts, exports, leave) to Slack channels through a signature-verifying relay and Slack incoming webhooks.
Microsoft Teams notifications
Post TimeTracking events to Microsoft Teams channels through a signature-verifying relay and a Teams Workflows (Power Automate) webhook.
Make recipes
Use TimeTracking with Make (Integromat) today: custom webhooks with signature checks via sha256 HMAC, and HTTP modules for API calls.
n8n recipes
Use TimeTracking with n8n today: Webhook node with raw body, Crypto node HMAC verification, and HTTP Request nodes with header auth.
Zapier recipes
Use TimeTracking with Zapier today: Catch Raw Hook for signed webhooks, Code by Zapier for signature checks, and Webhooks by Zapier for API calls.
AFAS Profit payroll export
Send approved TimeTracking hours, allowances, expenses and leave to AFAS Profit payroll as variable values, via file import or an AFAS UpdateConnector script.
DATEV payroll export (LODAS / Lohn und Gehalt)
Produce DATEV LODAS or Lohn und Gehalt movement data (Bewegungsdaten) from approved TimeTracking hours, with an export mapping plus a small post-processing step.
Easyflex payroll and placements
Sync Easyflex flex workers and placements into TimeTracking and send approved hours back to Easyflex per placement, using CSV import, the REST API and an hours file.
Exact Online payroll and project hours
Send approved TimeTracking hours to Exact Online, either as payroll variable data (Exact Online Loonadministratie) or as project time transactions for invoicing.
Loket.nl payroll export
Get approved TimeTracking hours, allowances, expenses and leave into Loket.nl as variable payroll data, via a CSV export mapping or the Loket API.
Mysolution staffing and payroll
Connect Mysolution (Salesforce-based staffing software) to TimeTracking: placements in via external-ID upserts, approved hours out via GET /days or export runs and webhooks.
Nmbrs payroll export
Bring approved TimeTracking hours, allowances, expenses and leave into Nmbrs as hours and variable wage components, via file import or the Nmbrs API.
Personio HR and payroll
Sync employees and absences from Personio into TimeTracking and push approved TimeTracking hours to Personio attendances with a script or iPaaS.
Planbition planning and hours
Combine Planbition workforce planning with TimeTracking: import Planbition hours as claims for matching, or send approved TimeTracking hours to Planbition.
SD Worx payroll export
Export approved hours, allowances, expenses and leave from TimeTracking to SD Worx as variable wage components with the preset-sdworx export mapping.
Visma | Raet (Youforce) payroll export
Deliver approved TimeTracking hours, allowances, expenses and leave to Visma | Raet Youforce payroll as a variable-data file.
ChatGPT Actions
Recipe: build a Custom GPT that reads TimeTracking data through GPT Actions, using a trimmed OpenAPI schema and a read-only API key.
Claude Skill
Install the TimeTracking Agent Skill so Claude knows the domain model and the safe weekly-close workflow, using the tt CLI or the MCP tools.
CLI (tt)
Reference for the tt command line: install, authentication, every command and option, output formats and exit codes.
MCP server
Connect Claude and other MCP clients to TimeTracking: setup, every tool with its inputs, confirmation rules, key scopes and known gaps.
Prompts
Copy-paste prompts for Claude and other AI assistants to operate TimeTracking and to build integrations against its API.
Webhook events
Every TimeTracking webhook event with when it fires, its data fields, a real captured payload, and which API call to make next.
Webhooks overview
How TimeTracking webhooks work: creating a subscription, the delivery request, the event envelope, latency, testing, inspecting deliveries, replay and secret rotation.
Webhook retries
TimeTracking webhook retry schedule (7 attempts over about 21 hours), what counts as failure, how to inspect and replay deliveries, and how to build an idempotent receiver.
Verify webhook signatures
Verify the tt-signature HMAC-SHA256 header on TimeTracking webhooks, with a real test vector and copy-paste code for Node.js, Python, PHP, C#, Go and Ruby.