# 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.

URL: https://timetracking.tech/developers

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 /claims` or `POST /claims/batch`. Client emails go to the [inbound email](data-in/inbound-email.md) pipeline. Tablets on site use the [kiosk](data-in/kiosk.md).
- **Approved hours out to payroll.** Run [export mappings](data-out/export-mappings.md) (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](webhooks/overview.md) 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 and `updated_since`.
- **AI assistants that run the weekly close.** Use the [MCP server](tools/mcp.md), the [CLI](tools/cli.md) and the [Claude Skill](tools/claude-skill.md). Copy-paste prompts are in [prompts](tools/prompts.md).

## 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](quickstart.md) · [Authentication](api/authentication.md) · [API reference](api/reference.md) · [Webhooks](webhooks/overview.md) |
| **CLI / MCP / Claude Skill** | A person or an AI assistant operates TimeTracking from a terminal or chat | [CLI](tools/cli.md) · [MCP server](tools/mcp.md) · [Claude Skill](tools/claude-skill.md) · [ChatGPT Actions](tools/chatgpt-actions.md) · [Prompts](tools/prompts.md) |
| **File-based** | The other system only speaks CSV/XLSX or email | [CSV import](data-in/csv-import.md) · [Competitor import](data-in/competitor-import.md) · [Inbound email](data-in/inbound-email.md) · [Export mappings](data-out/export-mappings.md) · [Payroll files](data-out/payroll-files.md) |

## Core rules, in one place

- **Units:** durations are integer **minutes** (7.5 h = `450`). Money is integer **cents**. Dates are `YYYY-MM-DD`. Times of day are minutes after midnight (`startMin: 420` = 07:00).
- **Envelope:** a success is `{ "data": … }`. A failure is `{ "error": { "code", "message" } }`, plus `issues` on 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](concepts/status-lifecycle.md).
- **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](concepts/sources-and-conflicts.md).
- **Credentials:** an org API key (`tt_live_…`) has scope `read`, `write` or `admin` (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](api/authentication.md).

## 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](integrations/index.md) for every system.

## Page map

- Concepts: [data model](concepts/data-model.md) · [glossary](concepts/glossary.md) · [status lifecycle](concepts/status-lifecycle.md) · [sources and conflicts](concepts/sources-and-conflicts.md) · [hour types and rule packs](concepts/hour-types-and-rule-packs.md) · [periods and locking](concepts/periods-and-locking.md)
- API: [authentication](api/authentication.md) · [errors](api/errors.md) · [rate limits](api/rate-limits.md) · [pagination](api/pagination.md) · [idempotency](api/idempotency.md) · [versioning](api/versioning.md) · [changelog](api/changelog.md) · [reference](api/reference.md)
- Webhooks: [overview](webhooks/overview.md) · [events](webhooks/events.md) · [verify signatures](webhooks/verify-signatures.md) · [retries](webhooks/retries.md)
- Data in: [CSV import](data-in/csv-import.md) · [Toggl/Clockify/TimeChimp/Harvest import](data-in/competitor-import.md) · [inbound email](data-in/inbound-email.md) · [client approval links](data-in/client-approval-links.md) · [kiosk](data-in/kiosk.md)
- Data out: [export mappings](data-out/export-mappings.md) · [presets](data-out/presets.md) · [payroll files](data-out/payroll-files.md)
- Office help: [weekly close](help/office/weekly-close.md) · [import](help/office/import.md) · [export and lock](help/office/export-and-lock.md) · [client approval](help/office/client-approval.md) · [inbox](help/office/inbox.md) · [kiosk setup](help/office/kiosk-setup.md)

## Documents

- [Quickstart](https://timetracking.tech/developers/quickstart.md): 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](https://timetracking.tech/developers/guides.md): 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](https://timetracking.tech/developers/guides/add-timetracking-to-your-crm.md): 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](https://timetracking.tech/developers/api/authentication.md): 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](https://timetracking.tech/developers/api/changelog.md): Changes to the TimeTracking REST API, webhooks, CLI and MCP server, newest first.
- [Errors](https://timetracking.tech/developers/api/errors.md): 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](https://timetracking.tech/developers/api/idempotency.md): 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](https://timetracking.tech/developers/api/pagination.md): Cursor pagination with limit, cursor and updated_since on TimeTracking list endpoints, which endpoints support it, and how to run incremental syncs.
- [Rate limits](https://timetracking.tech/developers/api/rate-limits.md): 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](https://timetracking.tech/developers/api/reference.md): Every TimeTracking REST API v1.1 endpoint with parameters, request fields, who may call it, and real captured request/response examples.
- [Versioning](https://timetracking.tech/developers/api/versioning.md): 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](https://timetracking.tech/developers/concepts/data-model.md): The TimeTracking entities (organisation, person, client, placement, claim, day, conflict, leave, expense, shift, export run, period) and how they relate.
- [Glossary](https://timetracking.tech/developers/concepts/glossary.md): 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](https://timetracking.tech/developers/concepts/hour-types-and-rule-packs.md): 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](https://timetracking.tech/developers/concepts/periods-and-locking.md): 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](https://timetracking.tech/developers/concepts/sources-and-conflicts.md): 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](https://timetracking.tech/developers/concepts/status-lifecycle.md): 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](https://timetracking.tech/developers/data-in/client-approval-links.md): 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](https://timetracking.tech/developers/data-in/competitor-import.md): 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](https://timetracking.tech/developers/data-in/csv-import.md): 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)](https://timetracking.tech/developers/data-in/inbound-email.md): 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)](https://timetracking.tech/developers/data-in/kiosk.md): 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](https://timetracking.tech/developers/data-out/export-mappings.md): 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](https://timetracking.tech/developers/data-out/payroll-files.md): 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](https://timetracking.tech/developers/data-out/presets.md): 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](https://timetracking.tech/developers/help/office/client-approval.md): Office guide: set up which clients must approve hours, send secure approval links, and handle corrections and rejections.
- [Export and lock](https://timetracking.tech/developers/help/office/export-and-lock.md): Office guide: preview, export and download the payroll file, then lock the period once payroll has processed it.
- [Import master data](https://timetracking.tech/developers/help/office/import.md): Office guide: import employees, clients and placements from one CSV file, with a check before anything is saved.
- [Inbox (client timesheets)](https://timetracking.tech/developers/help/office/inbox.md): Office guide: receive client timesheets by email or upload, let TimeTracking read them, and review what it could not apply automatically.
- [Kiosk setup](https://timetracking.tech/developers/help/office/kiosk-setup.md): Office guide: set up a tablet on site where workers clock in and out with a PIN.
- [Weekly close](https://timetracking.tech/developers/help/office/weekly-close.md): Step-by-step guide for office staff: check, correct and approve a week of hours in TimeTracking, then hand over to export.
- [Integrations](https://timetracking.tech/developers/integrations.md): Matrix of every system TimeTracking connects to, with honest status (Live, Recipe, Planned), mechanism and data direction.
- [Bullhorn integration](https://timetracking.tech/developers/integrations/ats-crm/bullhorn.md): 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](https://timetracking.tech/developers/integrations/ats-crm/carerix.md): Sync Carerix employees, companies and placements into TimeTracking with external-ID upserts and batches, and report approved hours back with GET /days.
- [HubSpot integration](https://timetracking.tech/developers/integrations/ats-crm/hubspot.md): 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](https://timetracking.tech/developers/integrations/ats-crm/otys.md): Sync OTYS candidates, relations and placements into TimeTracking with external-ID upserts, batches and the OTYS web services.
- [Pipedrive integration](https://timetracking.tech/developers/integrations/ats-crm/pipedrive.md): Create TimeTracking clients and placements from won Pipedrive deals using Pipedrive webhooks and idempotent external-ID upserts.
- [Recruitee integration](https://timetracking.tech/developers/integrations/ats-crm/recruitee.md): Create TimeTracking people and placements when a Recruitee candidate is hired, using a Recruitee webhook and idempotent external-ID upserts.
- [Salesforce integration](https://timetracking.tech/developers/integrations/ats-crm/salesforce.md): 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](https://timetracking.tech/developers/integrations/bi/looker-studio.md): 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](https://timetracking.tech/developers/integrations/bi/power-bi.md): 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](https://timetracking.tech/developers/integrations/calendar/google-calendar.md): Put published TimeTracking shifts into Google Calendar with the shift.published webhook, GET /shifts and the Google Calendar API.
- [Microsoft 365 (Outlook) calendar integration](https://timetracking.tech/developers/integrations/calendar/microsoft-365.md): Put published TimeTracking shifts into Outlook calendars with the shift.published webhook, GET /shifts and Microsoft Graph.
- [Slack notifications](https://timetracking.tech/developers/integrations/chat/slack.md): Post TimeTracking events (submitted, approved, conflicts, exports, leave) to Slack channels through a signature-verifying relay and Slack incoming webhooks.
- [Microsoft Teams notifications](https://timetracking.tech/developers/integrations/chat/teams.md): Post TimeTracking events to Microsoft Teams channels through a signature-verifying relay and a Teams Workflows (Power Automate) webhook.
- [Make recipes](https://timetracking.tech/developers/integrations/ipaas/make.md): Use TimeTracking with Make (Integromat) today: custom webhooks with signature checks via sha256 HMAC, and HTTP modules for API calls.
- [n8n recipes](https://timetracking.tech/developers/integrations/ipaas/n8n.md): Use TimeTracking with n8n today: Webhook node with raw body, Crypto node HMAC verification, and HTTP Request nodes with header auth.
- [Zapier recipes](https://timetracking.tech/developers/integrations/ipaas/zapier.md): 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](https://timetracking.tech/developers/integrations/payroll/afas.md): 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)](https://timetracking.tech/developers/integrations/payroll/datev.md): 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](https://timetracking.tech/developers/integrations/payroll/easyflex.md): 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](https://timetracking.tech/developers/integrations/payroll/exact-online.md): 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](https://timetracking.tech/developers/integrations/payroll/loket.md): 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](https://timetracking.tech/developers/integrations/payroll/mysolution.md): 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](https://timetracking.tech/developers/integrations/payroll/nmbrs.md): 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](https://timetracking.tech/developers/integrations/payroll/personio.md): 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](https://timetracking.tech/developers/integrations/payroll/planbition.md): Combine Planbition workforce planning with TimeTracking: import Planbition hours as claims for matching, or send approved TimeTracking hours to Planbition.
- [SD Worx payroll export](https://timetracking.tech/developers/integrations/payroll/sd-worx.md): 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](https://timetracking.tech/developers/integrations/payroll/visma-raet.md): Deliver approved TimeTracking hours, allowances, expenses and leave to Visma | Raet Youforce payroll as a variable-data file.
- [ChatGPT Actions](https://timetracking.tech/developers/tools/chatgpt-actions.md): 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](https://timetracking.tech/developers/tools/claude-skill.md): 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)](https://timetracking.tech/developers/tools/cli.md): Reference for the tt command line: install, authentication, every command and option, output formats and exit codes.
- [MCP server](https://timetracking.tech/developers/tools/mcp.md): Connect Claude and other MCP clients to TimeTracking: setup, every tool with its inputs, confirmation rules, key scopes and known gaps.
- [Prompts](https://timetracking.tech/developers/tools/prompts.md): Copy-paste prompts for Claude and other AI assistants to operate TimeTracking and to build integrations against its API.
- [Webhook events](https://timetracking.tech/developers/webhooks/events.md): Every TimeTracking webhook event with when it fires, its data fields, a real captured payload, and which API call to make next.
- [Webhooks overview](https://timetracking.tech/developers/webhooks/overview.md): How TimeTracking webhooks work: creating a subscription, the delivery request, the event envelope, latency, testing, inspecting deliveries, replay and secret rotation.
- [Webhook retries](https://timetracking.tech/developers/webhooks/retries.md): 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](https://timetracking.tech/developers/webhooks/verify-signatures.md): 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.

## API reference

- [OpenAPI spec (JSON)](https://app.timetracking.tech/api/v1/openapi.json)