Help / Integrations

The API and webhooks

Time Trakkr has a public REST API for reading and writing your data, plus outbound webhooks that notify your own systems when things happen. This article is a short pointer to both; the full, always-current details live in the reference.

Where the full reference lives

The complete API reference, with every endpoint and its parameters, is at timetrakkr.com/developers. A machine-readable OpenAPI spec is served at /api/v1/openapi.json and imports straight into tools like Postman.

Token kinds

Every request sends Authorization: Bearer <token>. There are three kinds of credential:

  • Personal access tokens act as you. Time entries created with one land on your timesheet, your role applies, and a member-grade token only ever sees its owner's own time and expenses. Anyone can create one under Integrations; managers and admins also find them on the Developer page.
  • Organization keys act org-wide with no person attached. Writes that need a person, such as logging time, require an explicit user_id. Only owners and admins can create, see and revoke them, on the Developer page; managers see the page's webhooks and their own tokens, but not organization keys. A key reaches invoices and estimates, which is why it is kept to the same people who can see those. Keys a manager created before this changed still work until an admin revokes them; an admin can see and revoke them on the same page.
  • Connected apps are apps you approved through OAuth, such as an AI client connected over MCP. They act as you, but only on the routes their approval screen described: time entries, projects, tasks, clients, reports and your own user. Invoices, rates and the user directory are out of their reach whatever your role. You can see and revoke the apps you approved under Integrations.

Endpoints marked manager+ or admin refuse lower-grade personal tokens, so money such as rates and reports never reaches a member token. Invoices and estimates are admin-only, as they are in the app: every /v1/invoices and /v1/estimates endpoint, reading included, answers a manager's or member's token with 403, and answers an admin's or owner's token and an organization key. This mirrors the roles and permissions that apply throughout the app. Requests are rate-limited (100 requests per 15 seconds per person, however many tokens they hold, or per key for an organization key), returning 429 with a Retry-After header when you go over.

Safe retries with Idempotency-Key

Because network calls can fail after the server has already acted, POST requests accept an Idempotency-Key header — any unique string up to 255 characters. Retrying with the same key and the same payload within 24 hours replays the original response (marked Idempotency-Replayed: true) instead of creating a duplicate. Reusing the same key with a different payload is refused, so a mistaken retry can never overwrite something.

What a personal token can reach

A personal access token is created with a set of scopes, and a route that needs a scope the token does not carry refuses it.

  • Read and write is what a new token gets. It reaches everything your role allows.
  • People profile data is off unless you tick Include People profile data when you create the token. /v1/people needs it: without it the endpoint refuses the token, even an HR administrator's. With it, an HR administrator's token gets everybody's profile and anyone else's gets only their own. Organization keys never reach /v1/people.

A scope is chosen when the token is made and cannot be added later. To widen a token, create a new one and revoke the old.

Budgets

Projects carry their budget: budget (hours), budget_is_monthly, over_budget_notification_percentage, show_budget_to_all, cost_budget and cost_budget_include_expenses, and the fee budget: fee_budget (money the billable hours at their hourly rates are measured against), fee_budget_is_monthly and fee_budget_notification_percentage. They are returned on every project and can be set on POST /v1/projects and PATCH /v1/projects/{id}. The names match Harvest's v2 API, so an integration written for Harvest needs little change.

  • Per person: budget on POST and PATCH /v1/projects/{id}/user_assignments.
  • Per task: budget on PATCH /v1/tasks/{id}, and shown on the task and on task_assignments.
  • Send only what you are changing. A field left out keeps its value; null removes a budget.
  • Settings need a budget. budget_is_monthly, over_budget_notification_percentage and cost_budget_include_expenses describe a budget, so sending them for a project with no hours or cost budget is refused with 422 — and so is sending one in the same request that removes the last budget; the message says which happened. Removing the last budget removes its settings too, and over_budget_notification_percentage then reads back as null. The fee budget's settings work the same way against fee_budget.
  • Alerts off is null. Send over_budget_notification_percentage: null to switch a budget's alert off. A budget with alerts off reads back as null too, and stays off when you change its other fields.
  • Hours take up to two decimals, and cost_budget up to four. More is refused rather than rounded.
  • Unknown fields are refused with 400 on these endpoints, so a misspelled field is an error rather than a change that silently did not happen.
  • A plain member's key sees a project's hours budget only when it is shown to everyone, and never sees cost budgets, fee budgets or other people's budgets.

For spend against the budget, use GET /v1/reports/project_budget. Each row carries client_id and client_name. For a monthly budget, compare budget_spent with budget_for_range (the monthly budget times months_in_range) rather than with budget, which stays one month's allowance. On a project with per-person budgets, budget_people also lists everyone else who logged time in the range, with has_budget: false. A project with a fee budget adds fee_budget, fee_budget_spent (billable hours in range at their rates), fee_budget_remaining, and fee_budget_for_range with fee_budget_remaining_for_range for a monthly fee budget. budget_by says what budget is: project_hours whenever the project has an hours budget. Without one, budget is null and budget_by names the budget the row is there for: project_fees, person_hours or internal_cost, in that order when a project has several, or none. More on budgets in project budgets.

Time reports

GET /v1/reports/time/{clients|projects|tasks|team|engagements}?from=&to= totals the time in a date range. Narrow it with any of these, which combine:

  • client_id, project_id or engagement_id — time on that client's projects, that project, or that engagement's projects (archived ones included).
  • user_id — one person's time, using the same user id as /v1/time_entries.
  • billable=true or billable=false — billable or non-billable time only.

Each row carries the id of what it groups by beside its name: client_id, project_id, user_id, or engagement_id on the engagements report, where the "No engagement" row has engagement_id: null. Two engagements with the same name are two rows, so match on the id. An id that is not a UUID is refused with 400; an id your workspace does not have returns no rows. Every report refuses a query parameter it does not take with 400 naming it, so a misspelled or unsupported filter is an error rather than a full, unfiltered report that looks filtered. page and per_page work on all of them.

Finding a client or project before creating one

An integration that creates clients and projects, a Zap say, usually needs to check whether the record is already there first. The API supports that directly:

  • Look up by whole name. GET /v1/clients?name_exact=Acme Corp matches the whole name, ignoring capitalization. name is still a fragment search, so name=acme also finds "Acme Holdings". Projects take the same two filters, and client_id narrows them to one client.
  • Archived records are left out of GET /v1/clients and GET /v1/projects unless you add include_archived=true. For projects, is_active=false still lists only the archived ones.
  • DELETE answers 200 with an empty body. The one exception is removing a client contact, which answers 204. DELETE /v1/projects/{id} and DELETE /v1/clients/{id} archive the record rather than delete it; deleting for good is done in the app.
  • Find-or-create in one call. Send "find_existing": true with POST /v1/clients or POST /v1/projects. If an active record of that name already exists (for a project, under the same client), you get it back with 200 and nothing is changed. Otherwise it is created and you get 201.
  • Client contacts live at /v1/clients/{id}/contacts. A contact needs a name; title, email and phone are optional. An email already on that client is refused with 409, and the response's contact_id is the contact that already has it — so a Zap can treat 409 as "found".

Client responses include the client's notes.

Webhooks with signed payloads

Webhook endpoints are managed on the same Developer page, by a manager or admin. Add an endpoint URL, tick the events you want, and Time Trakkr will POST to it when they happen.

Events you can subscribe to

EventWhat arrives
time_entry.createdA time entry was logged. Sends the whole entry.
time_entry.updatedA time entry changed. Sends the entry as it now stands.
time_entry.deletedA time entry was removed. Sends only its id.
invoice.createdAn invoice was drafted. Sends the invoice; it has not been sent to anyone.
invoice.sentAn invoice was sent to its client. Sends the invoice.
invoice.paidAn invoice was marked paid. Sends the invoice as it now stands.

An endpoint only receives the events it is subscribed to. The body is always { "event": "...", "data": ..., "sentAt": "..." }, and the event name is repeated in an X-TT-Event header so you can route without parsing the body.

What to rely on, and what not to

  • Every payload is signed. Time Trakkr sends an X-TT-Signature header containing an HMAC-SHA256 signature of the raw request body. Verify it against your endpoint's signing secret to be sure the request really came from Time Trakkr.
  • The secret is shown once. When you create an endpoint, its signing secret is displayed a single time — copy it then and store it safely.
  • Test before you rely on it. Each endpoint has a Test button that sends a sample delivery so you can confirm your receiver verifies the signature and responds.
  • Your endpoint must be reachable over HTTPS at a public address. A URL that resolves to a private or internal address is refused, and it is re-checked on every delivery rather than only when you add it.
  • Delivery is attempted once and is not retried. A failure is recorded in the deliveries list on the Developer page, and the action that triggered it still succeeds — a webhook your receiver rejected never blocks someone's time entry. If you need guaranteed delivery, poll the API for anything you may have missed rather than assuming every event arrived.

For connecting an AI client such as Claude or Cursor over MCP rather than the plain REST API, see MCP and AI clients.

Updated 2026-11-08. Still stuck? Contact support or return to the Help Center.