API reference

A predictable REST API for time, catalog, billing, and reporting data. Machine-readable spec: /api/v1/openapi.json (imports straight into Postman).

Authentication

Send Authorization: Bearer <token>. Two token kinds, both created on the in-app Developer page:

Personal access tokens act as their owner: time entries land on your timesheet, your role applies, and member-grade tokens only see their own time and expenses.
Organization keys act org-wide with no person attached — writes that need a person (like logging time) require an explicit user_id.

Endpoints marked manager+ or admin refuse lower-grade personal tokens — money (rates, invoices, reports) never reaches member tokens.

Conventions

Lists return a consistent envelope: items keyed by resource name plus per_page, total_pages, total_entries, next_page, previous_page, and a links object.
Errors are {"message": "…"} with meaningful status codes; business rules refuse with 422.
Rate limit: 100 requests / 15 seconds per token (429 with Retry-After).
Safe retries: send an Idempotency-Key header (any unique string, ≤255 chars) with POSTs. Retrying with the same key and payload within 24 hours replays the original response (Idempotency-Replayed: true) instead of creating a duplicate; the same key with a different payload is refused with 422.
Conventions to note: ids are UUID strings; tasks belong to a project; approval_status maps open and rejected weeks to unsubmitted.

Company

The authenticated workspace.

GET/v1/companyRetrieve the company

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "name": "Fieldnote Studio",
  "is_active": true,
  "base_uri": "https://fieldnote.timetrakkr.com",
  "full_domain": "fieldnote.timetrakkr.com",
  "week_start_day": "Monday",
  "currency": "USD",
  "time_zone": "America/New_York"
}

ERRORS

{
  "message": "Project not found"
}

Time entries

Tracked time. Member-grade personal tokens see and modify only their own entries; submitted or approved weeks are locked.

GET/v1/time_entriesList time entries

PARAMETERS

from — Only entries on/after this date (YYYY-MM-DD)
to — Only entries on/before this date
user_id — Filter to one member
client_id — Filter by client
project_id — Filter by project
task_id — Filter by task
billable — true/false
is_billed — true = already invoiced
is_running — true = timer currently running
approval_status — unsubmitted, submitted, or approved
external_reference_id — Match an external reference
updated_since — ISO 8601 datetime
page — Page number, starting at 1
per_page — Items per page (default 100, max 2000)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope
429Rate limited. Retry after the Retry-After header.

EXAMPLE LIST

{
  "time_entries": [
    {
      "id": "3f0a1c2e-5b6d-4e7f-8a90-1b2c3d4e5f60",
      "spent_date": "2026-08-03",
      "hours": 2,
      "notes": "Homepage hero — second revision round",
      "billable": true,
      "is_locked": false,
      "is_billed": false,
      "is_running": false,
      "approval_status": "unsubmitted",
      "user": {
        "id": "7a1b2c3d-4e5f-4061-8273-8495a6b7c8d9",
        "name": "Priya Nair"
      },
      "project": {
        "id": "9c8b7a65-4321-4fed-9876-543210fedcba",
        "name": "Acme Rebrand"
      },
      "task": {
        "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "name": "Design"
      },
      "client": {
        "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
        "name": "Acme Corp"
      },
      "external_reference": null,
      "created_at": "2026-08-03T09:12:00.000Z",
      "updated_at": "2026-08-03T09:12:00.000Z"
    }
  ],
  "per_page": 100,
  "total_pages": 1,
  "total_entries": 1,
  "next_page": null,
  "previous_page": null,
  "page": 1,
  "links": {
    "first": "https://timetrakkr.com/api/v1/time_entries?page=1",
    "next": null,
    "previous": null,
    "last": "https://timetrakkr.com/api/v1/time_entries?page=1"
  }
}

ERRORS

{
  "message": "Project not found"
}

POST/v1/time_entriesCreate a time entry

Personal tokens log as their owner. Weeks already submitted for approval refuse new time (422). Omitting `hours` starts a running timer and returns the entry with `is_running` true.

BODY

project_id — UUID, required
task_id — UUID, required
spent_date — YYYY-MM-DD, required
hours — Decimal hours (rounded per org policy). OMIT to start a running timer instead.
notes — Entry notes
billable — Defaults true
external_reference.id — External system reference — import provenance, unique per org
issue_key — Jira issue this entry is for, e.g. ACME-142. Several entries may share one.
user_id — Required with an organization key; ignored for personal tokens

RESPONSES

201Created
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "3f0a1c2e-5b6d-4e7f-8a90-1b2c3d4e5f60",
  "spent_date": "2026-08-03",
  "hours": 2,
  "notes": "Homepage hero — second revision round",
  "billable": true,
  "is_locked": false,
  "is_billed": false,
  "is_running": false,
  "approval_status": "unsubmitted",
  "user": {
    "id": "7a1b2c3d-4e5f-4061-8273-8495a6b7c8d9",
    "name": "Priya Nair"
  },
  "project": {
    "id": "9c8b7a65-4321-4fed-9876-543210fedcba",
    "name": "Acme Rebrand"
  },
  "task": {
    "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Design"
  },
  "client": {
    "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
    "name": "Acme Corp"
  },
  "external_reference": null,
  "created_at": "2026-08-03T09:12:00.000Z",
  "updated_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

GET/v1/time_entries/{id}Retrieve a time entry

PARAMETERS

id (required) — The time entry id (UUID)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope
404No such record in this workspace
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "3f0a1c2e-5b6d-4e7f-8a90-1b2c3d4e5f60",
  "spent_date": "2026-08-03",
  "hours": 2,
  "notes": "Homepage hero — second revision round",
  "billable": true,
  "is_locked": false,
  "is_billed": false,
  "is_running": false,
  "approval_status": "unsubmitted",
  "user": {
    "id": "7a1b2c3d-4e5f-4061-8273-8495a6b7c8d9",
    "name": "Priya Nair"
  },
  "project": {
    "id": "9c8b7a65-4321-4fed-9876-543210fedcba",
    "name": "Acme Rebrand"
  },
  "task": {
    "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Design"
  },
  "client": {
    "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
    "name": "Acme Corp"
  },
  "external_reference": null,
  "created_at": "2026-08-03T09:12:00.000Z",
  "updated_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

PATCH/v1/time_entries/{id}Update a time entry

Locked (approved/invoiced) and submitted entries return 422.

PARAMETERS

id (required) — The time entry id (UUID)

BODY

project_id — UUID
task_id — UUID
spent_date — YYYY-MM-DD (target week must be open)
hours — Decimal hours
notes — Entry notes
billable — true/false
external_reference.id — Set or replace the external reference

RESPONSES

200OK
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "3f0a1c2e-5b6d-4e7f-8a90-1b2c3d4e5f60",
  "spent_date": "2026-08-03",
  "hours": 2,
  "notes": "Homepage hero — second revision round",
  "billable": true,
  "is_locked": false,
  "is_billed": false,
  "is_running": false,
  "approval_status": "unsubmitted",
  "user": {
    "id": "7a1b2c3d-4e5f-4061-8273-8495a6b7c8d9",
    "name": "Priya Nair"
  },
  "project": {
    "id": "9c8b7a65-4321-4fed-9876-543210fedcba",
    "name": "Acme Rebrand"
  },
  "task": {
    "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Design"
  },
  "client": {
    "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
    "name": "Acme Corp"
  },
  "external_reference": null,
  "created_at": "2026-08-03T09:12:00.000Z",
  "updated_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

DELETE/v1/time_entries/{id}Delete a time entry

PARAMETERS

id (required) — The time entry id (UUID)

RESPONSES

204Deleted. No body.
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

ERRORS

{
  "message": "Project not found"
}

PATCH/v1/time_entries/{id}/restartRestart the timer on an entry · personal token

Personal tokens only — timers belong to a person. Stops any other running timer.

PARAMETERS

id (required) — The time entry id (UUID)

RESPONSES

200OK
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (personal)
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "3f0a1c2e-5b6d-4e7f-8a90-1b2c3d4e5f60",
  "spent_date": "2026-08-03",
  "hours": 2,
  "notes": "Homepage hero — second revision round",
  "billable": true,
  "is_locked": false,
  "is_billed": false,
  "is_running": false,
  "approval_status": "unsubmitted",
  "user": {
    "id": "7a1b2c3d-4e5f-4061-8273-8495a6b7c8d9",
    "name": "Priya Nair"
  },
  "project": {
    "id": "9c8b7a65-4321-4fed-9876-543210fedcba",
    "name": "Acme Rebrand"
  },
  "task": {
    "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Design"
  },
  "client": {
    "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
    "name": "Acme Corp"
  },
  "external_reference": null,
  "created_at": "2026-08-03T09:12:00.000Z",
  "updated_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

PATCH/v1/time_entries/{id}/stopStop the running timer on an entry

A timer that has run past the sanity cap refuses with 409 and a message; re-send with actual_hours to bank the real figure.

PARAMETERS

id (required) — The time entry id (UUID)

BODY

actual_hours — Hours actually worked. Only needed to stop a timer that ran implausibly long and was refused (409).

RESPONSES

200OK
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "3f0a1c2e-5b6d-4e7f-8a90-1b2c3d4e5f60",
  "spent_date": "2026-08-03",
  "hours": 2,
  "notes": "Homepage hero — second revision round",
  "billable": true,
  "is_locked": false,
  "is_billed": false,
  "is_running": false,
  "approval_status": "unsubmitted",
  "user": {
    "id": "7a1b2c3d-4e5f-4061-8273-8495a6b7c8d9",
    "name": "Priya Nair"
  },
  "project": {
    "id": "9c8b7a65-4321-4fed-9876-543210fedcba",
    "name": "Acme Rebrand"
  },
  "task": {
    "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Design"
  },
  "client": {
    "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
    "name": "Acme Corp"
  },
  "external_reference": null,
  "created_at": "2026-08-03T09:12:00.000Z",
  "updated_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

DELETE/v1/time_entries/{id}/external_referenceRemove an entry’s external reference

PARAMETERS

id (required) — The time entry id (UUID)

RESPONSES

204Deleted. No body.
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

ERRORS

{
  "message": "Project not found"
}

Clients

Clients and their currencies.

GET/v1/clientsList clients

PARAMETERS

name — Case-insensitive name fragment
page — Page number, starting at 1
per_page — Items per page (default 100, max 2000)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope
429Rate limited. Retry after the Retry-After header.

EXAMPLE LIST

{
  "clients": [
    {
      "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
      "name": "Acme Corp",
      "is_active": true,
      "address": "14 Bridge Street, Bristol BS1 4TW",
      "currency": "USD",
      "created_at": "2026-08-03T09:12:00.000Z",
      "updated_at": "2026-08-03T09:12:00.000Z"
    }
  ],
  "per_page": 100,
  "total_pages": 1,
  "total_entries": 1,
  "next_page": null,
  "previous_page": null,
  "page": 1,
  "links": {
    "first": "https://timetrakkr.com/api/v1/clients?page=1",
    "next": null,
    "previous": null,
    "last": "https://timetrakkr.com/api/v1/clients?page=1"
  }
}

ERRORS

{
  "message": "Project not found"
}

POST/v1/clientsCreate a client · manager+

BODY

name — Required
currency — 3-letter code
address — Postal address
notes — Notes

RESPONSES

201Created
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (org-wide)
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
  "name": "Acme Corp",
  "is_active": true,
  "address": "14 Bridge Street, Bristol BS1 4TW",
  "currency": "USD",
  "created_at": "2026-08-03T09:12:00.000Z",
  "updated_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

GET/v1/clients/{id}Retrieve a client

PARAMETERS

id (required) — The client id (UUID)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope
404No such record in this workspace
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
  "name": "Acme Corp",
  "is_active": true,
  "address": "14 Bridge Street, Bristol BS1 4TW",
  "currency": "USD",
  "created_at": "2026-08-03T09:12:00.000Z",
  "updated_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

PATCH/v1/clients/{id}Update a client · manager+

PARAMETERS

id (required) — The client id (UUID)

BODY

name — Client name
currency — 3-letter code
address — Postal address
notes — Notes

RESPONSES

200OK
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (org-wide)
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
  "name": "Acme Corp",
  "is_active": true,
  "address": "14 Bridge Street, Bristol BS1 4TW",
  "currency": "USD",
  "created_at": "2026-08-03T09:12:00.000Z",
  "updated_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

DELETE/v1/clients/{id}Archive a client · manager+

Refuses (422) while the client has active projects.

PARAMETERS

id (required) — The client id (UUID)

RESPONSES

204Deleted. No body.
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (org-wide)
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

ERRORS

{
  "message": "Project not found"
}

Projects

Projects, and who is assigned to them.

GET/v1/projectsList projects

PARAMETERS

client_id — Filter by client
is_active — true/false
page — Page number, starting at 1
per_page — Items per page (default 100, max 2000)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope
429Rate limited. Retry after the Retry-After header.

EXAMPLE LIST

{
  "projects": [
    {
      "id": "9c8b7a65-4321-4fed-9876-543210fedcba",
      "name": "Acme Rebrand",
      "code": null,
      "is_active": true,
      "client": {
        "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
        "name": "Acme Corp"
      },
      "hourly_rate": 145,
      "created_at": "2026-08-03T09:12:00.000Z",
      "updated_at": "2026-08-03T09:12:00.000Z"
    }
  ],
  "per_page": 100,
  "total_pages": 1,
  "total_entries": 1,
  "next_page": null,
  "previous_page": null,
  "page": 1,
  "links": {
    "first": "https://timetrakkr.com/api/v1/projects?page=1",
    "next": null,
    "previous": null,
    "last": "https://timetrakkr.com/api/v1/projects?page=1"
  }
}

ERRORS

{
  "message": "Project not found"
}

POST/v1/projectsCreate a project · manager+

BODY

client_id — UUID, required
name — Required
code — Short code
hourly_rate — Project hourly rate
starts_on — YYYY-MM-DD
ends_on — YYYY-MM-DD

RESPONSES

201Created
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (org-wide)
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "9c8b7a65-4321-4fed-9876-543210fedcba",
  "name": "Acme Rebrand",
  "code": null,
  "is_active": true,
  "client": {
    "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
    "name": "Acme Corp"
  },
  "hourly_rate": 145,
  "created_at": "2026-08-03T09:12:00.000Z",
  "updated_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

GET/v1/projects/{id}Retrieve a project

PARAMETERS

id (required) — The project id (UUID)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope
404No such record in this workspace
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "9c8b7a65-4321-4fed-9876-543210fedcba",
  "name": "Acme Rebrand",
  "code": null,
  "is_active": true,
  "client": {
    "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
    "name": "Acme Corp"
  },
  "hourly_rate": 145,
  "created_at": "2026-08-03T09:12:00.000Z",
  "updated_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

PATCH/v1/projects/{id}Update a project · manager+

PARAMETERS

id (required) — The project id (UUID)

BODY

client_id — UUID
name — Project name
code — Short code
is_active — false archives, true restores
hourly_rate — Project hourly rate
starts_on — YYYY-MM-DD
ends_on — YYYY-MM-DD

RESPONSES

200OK
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (org-wide)
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "9c8b7a65-4321-4fed-9876-543210fedcba",
  "name": "Acme Rebrand",
  "code": null,
  "is_active": true,
  "client": {
    "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
    "name": "Acme Corp"
  },
  "hourly_rate": 145,
  "created_at": "2026-08-03T09:12:00.000Z",
  "updated_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

DELETE/v1/projects/{id}Archive a project · manager+

PARAMETERS

id (required) — The project id (UUID)

RESPONSES

204Deleted. No body.
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (org-wide)
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

ERRORS

{
  "message": "Project not found"
}

GET/v1/projects/{id}/user_assignmentsList a project’s people

PARAMETERS

id (required) — The project id (UUID)
page — Page number, starting at 1
per_page — Items per page (default 100, max 2000)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope
404No such record in this workspace
429Rate limited. Retry after the Retry-After header.

EXAMPLE LIST

{
  "user_assignments": [
    {
      "id": "5e6f7081-92a3-4d4e-b5c6-d7e8f90a1b2c",
      "is_project_manager": false,
      "is_active": true,
      "hourly_rate": 145,
      "user": {
        "id": "7a1b2c3d-4e5f-4061-8273-8495a6b7c8d9",
        "name": "Priya Nair"
      },
      "project": {
        "id": "9c8b7a65-4321-4fed-9876-543210fedcba",
        "name": "Acme Rebrand"
      }
    }
  ],
  "per_page": 100,
  "total_pages": 1,
  "total_entries": 1,
  "next_page": null,
  "previous_page": null,
  "page": 1,
  "links": {
    "first": "https://timetrakkr.com/api/v1/projects/ID/user_assignments?page=1",
    "next": null,
    "previous": null,
    "last": "https://timetrakkr.com/api/v1/projects/ID/user_assignments?page=1"
  }
}

ERRORS

{
  "message": "Project not found"
}

POST/v1/projects/{id}/user_assignmentsAssign a person to a project · manager+

PARAMETERS

id (required) — The project id (UUID)

BODY

user_id — Member UUID, required
is_project_manager — Grants the PM flag
hourly_rate — Per-assignment billable rate

RESPONSES

201Created
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (org-wide)
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "5e6f7081-92a3-4d4e-b5c6-d7e8f90a1b2c",
  "is_project_manager": false,
  "is_active": true,
  "hourly_rate": 145,
  "user": {
    "id": "7a1b2c3d-4e5f-4061-8273-8495a6b7c8d9",
    "name": "Priya Nair"
  },
  "project": {
    "id": "9c8b7a65-4321-4fed-9876-543210fedcba",
    "name": "Acme Rebrand"
  }
}

ERRORS

{
  "message": "Project not found"
}

PATCH/v1/projects/{id}/user_assignments/{assignmentId}Update an assignment · manager+

PARAMETERS

id (required) — The project id (UUID)
assignmentId (required) — Assignment UUID

BODY

is_project_manager — PM flag
hourly_rate — Per-assignment billable rate

RESPONSES

200OK
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (org-wide)
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "5e6f7081-92a3-4d4e-b5c6-d7e8f90a1b2c",
  "is_project_manager": false,
  "is_active": true,
  "hourly_rate": 145,
  "user": {
    "id": "7a1b2c3d-4e5f-4061-8273-8495a6b7c8d9",
    "name": "Priya Nair"
  },
  "project": {
    "id": "9c8b7a65-4321-4fed-9876-543210fedcba",
    "name": "Acme Rebrand"
  }
}

ERRORS

{
  "message": "Project not found"
}

DELETE/v1/projects/{id}/user_assignments/{assignmentId}Remove an assignment · manager+

PARAMETERS

id (required) — The project id (UUID)
assignmentId (required) — Assignment UUID

RESPONSES

204Deleted. No body.
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (org-wide)
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

ERRORS

{
  "message": "Project not found"
}

GET/v1/projects/{id}/task_assignmentsList a project’s tasks (compatibility view)

Tasks belong to projects here, so each task is its own assignment.

PARAMETERS

id (required) — The project id (UUID)
page — Page number, starting at 1
per_page — Items per page (default 100, max 2000)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope
404No such record in this workspace
429Rate limited. Retry after the Retry-After header.

EXAMPLE LIST

{
  "tasks": [
    {
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Design",
      "project_id": "9c8b7a65-4321-4fed-9876-543210fedcba",
      "billable_by_default": true,
      "default_hourly_rate": 145,
      "is_active": true,
      "created_at": "2026-08-03T09:12:00.000Z",
      "updated_at": "2026-08-03T09:12:00.000Z"
    }
  ],
  "per_page": 100,
  "total_pages": 1,
  "total_entries": 1,
  "next_page": null,
  "previous_page": null,
  "page": 1,
  "links": {
    "first": "https://timetrakkr.com/api/v1/projects/ID/task_assignments?page=1",
    "next": null,
    "previous": null,
    "last": "https://timetrakkr.com/api/v1/projects/ID/task_assignments?page=1"
  }
}

ERRORS

{
  "message": "Project not found"
}

Tasks

Tasks (each belongs to one project).

GET/v1/tasksList tasks

PARAMETERS

project_id — Filter by project
page — Page number, starting at 1
per_page — Items per page (default 100, max 2000)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope
429Rate limited. Retry after the Retry-After header.

EXAMPLE LIST

{
  "tasks": [
    {
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Design",
      "project_id": "9c8b7a65-4321-4fed-9876-543210fedcba",
      "billable_by_default": true,
      "default_hourly_rate": 145,
      "is_active": true,
      "created_at": "2026-08-03T09:12:00.000Z",
      "updated_at": "2026-08-03T09:12:00.000Z"
    }
  ],
  "per_page": 100,
  "total_pages": 1,
  "total_entries": 1,
  "next_page": null,
  "previous_page": null,
  "page": 1,
  "links": {
    "first": "https://timetrakkr.com/api/v1/tasks?page=1",
    "next": null,
    "previous": null,
    "last": "https://timetrakkr.com/api/v1/tasks?page=1"
  }
}

ERRORS

{
  "message": "Project not found"
}

POST/v1/tasksCreate a task · manager+

BODY

project_id — UUID, required
name — Required
billable_by_default — Defaults true
default_hourly_rate — Task rate

RESPONSES

201Created
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (org-wide)
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "name": "Design",
  "project_id": "9c8b7a65-4321-4fed-9876-543210fedcba",
  "billable_by_default": true,
  "default_hourly_rate": 145,
  "is_active": true,
  "created_at": "2026-08-03T09:12:00.000Z",
  "updated_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

GET/v1/tasks/{id}Retrieve a task

PARAMETERS

id (required) — The task id (UUID)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope
404No such record in this workspace
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "name": "Design",
  "project_id": "9c8b7a65-4321-4fed-9876-543210fedcba",
  "billable_by_default": true,
  "default_hourly_rate": 145,
  "is_active": true,
  "created_at": "2026-08-03T09:12:00.000Z",
  "updated_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

PATCH/v1/tasks/{id}Update a task · manager+

PARAMETERS

id (required) — The task id (UUID)

BODY

name — Task name
billable_by_default — true/false
default_hourly_rate — Task rate

RESPONSES

200OK
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (org-wide)
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "name": "Design",
  "project_id": "9c8b7a65-4321-4fed-9876-543210fedcba",
  "billable_by_default": true,
  "default_hourly_rate": 145,
  "is_active": true,
  "created_at": "2026-08-03T09:12:00.000Z",
  "updated_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

DELETE/v1/tasks/{id}Delete a task · manager+

PARAMETERS

id (required) — The task id (UUID)

RESPONSES

204Deleted. No body.
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (org-wide)
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

ERRORS

{
  "message": "Project not found"
}

Users

Workspace members. Rates are money — manager+ tokens only.

GET/v1/usersList users

PARAMETERS

role — owner, admin, manager, or member
page — Page number, starting at 1
per_page — Items per page (default 100, max 2000)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope
429Rate limited. Retry after the Retry-After header.

EXAMPLE LIST

{
  "users": [
    {
      "id": "7a1b2c3d-4e5f-4061-8273-8495a6b7c8d9",
      "name": "Priya Nair",
      "first_name": "Priya",
      "last_name": "Nair",
      "email": "[email protected]",
      "is_active": true,
      "access_roles": [
        "member"
      ],
      "created_at": "2026-08-03T09:12:00.000Z",
      "updated_at": "2026-08-03T09:12:00.000Z"
    }
  ],
  "per_page": 100,
  "total_pages": 1,
  "total_entries": 1,
  "next_page": null,
  "previous_page": null,
  "page": 1,
  "links": {
    "first": "https://timetrakkr.com/api/v1/users?page=1",
    "next": null,
    "previous": null,
    "last": "https://timetrakkr.com/api/v1/users?page=1"
  }
}

ERRORS

{
  "message": "Project not found"
}

GET/v1/users/meRetrieve the token’s owner · personal token

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope or the required grade (personal)
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "7a1b2c3d-4e5f-4061-8273-8495a6b7c8d9",
  "name": "Priya Nair",
  "first_name": "Priya",
  "last_name": "Nair",
  "email": "[email protected]",
  "is_active": true,
  "access_roles": [
    "member"
  ],
  "created_at": "2026-08-03T09:12:00.000Z",
  "updated_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

GET/v1/users/{id}Retrieve a user

PARAMETERS

id (required) — The user id (UUID)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope
404No such record in this workspace
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "7a1b2c3d-4e5f-4061-8273-8495a6b7c8d9",
  "name": "Priya Nair",
  "first_name": "Priya",
  "last_name": "Nair",
  "email": "[email protected]",
  "is_active": true,
  "access_roles": [
    "member"
  ],
  "created_at": "2026-08-03T09:12:00.000Z",
  "updated_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

GET/v1/users/{id}/billable_ratesList a user’s billable rates · manager+

PARAMETERS

id (required) — The user id (UUID)
page — Page number, starting at 1
per_page — Items per page (default 100, max 2000)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope or the required grade (org-wide)
404No such record in this workspace
429Rate limited. Retry after the Retry-After header.

EXAMPLE LIST

{
  "billable_rates": [
    {
      "id": "6f708192-a3b4-4e5f-c6d7-e8f90a1b2c3d",
      "amount": 145,
      "start_date": "2026-01-01",
      "end_date": null
    }
  ],
  "per_page": 100,
  "total_pages": 1,
  "total_entries": 1,
  "next_page": null,
  "previous_page": null,
  "page": 1,
  "links": {
    "first": "https://timetrakkr.com/api/v1/users/ID/billable_rates?page=1",
    "next": null,
    "previous": null,
    "last": "https://timetrakkr.com/api/v1/users/ID/billable_rates?page=1"
  }
}

ERRORS

{
  "message": "Project not found"
}

GET/v1/users/{id}/cost_ratesList a user’s cost rates · manager+

PARAMETERS

id (required) — The user id (UUID)
page — Page number, starting at 1
per_page — Items per page (default 100, max 2000)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope or the required grade (org-wide)
404No such record in this workspace
429Rate limited. Retry after the Retry-After header.

EXAMPLE LIST

{
  "cost_rates": [
    {
      "id": "6f708192-a3b4-4e5f-c6d7-e8f90a1b2c3d",
      "amount": 68,
      "start_date": "2026-01-01",
      "end_date": null
    }
  ],
  "per_page": 100,
  "total_pages": 1,
  "total_entries": 1,
  "next_page": null,
  "previous_page": null,
  "page": 1,
  "links": {
    "first": "https://timetrakkr.com/api/v1/users/ID/cost_rates?page=1",
    "next": null,
    "previous": null,
    "last": "https://timetrakkr.com/api/v1/users/ID/cost_rates?page=1"
  }
}

ERRORS

{
  "message": "Project not found"
}

GET/v1/users/{id}/project_assignmentsList a user’s project assignments

PARAMETERS

id (required) — The user id (UUID)
page — Page number, starting at 1
per_page — Items per page (default 100, max 2000)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope
404No such record in this workspace
429Rate limited. Retry after the Retry-After header.

EXAMPLE LIST

{
  "user_assignments": [
    {
      "id": "5e6f7081-92a3-4d4e-b5c6-d7e8f90a1b2c",
      "is_project_manager": false,
      "is_active": true,
      "hourly_rate": 145,
      "user": {
        "id": "7a1b2c3d-4e5f-4061-8273-8495a6b7c8d9",
        "name": "Priya Nair"
      },
      "project": {
        "id": "9c8b7a65-4321-4fed-9876-543210fedcba",
        "name": "Acme Rebrand"
      }
    }
  ],
  "per_page": 100,
  "total_pages": 1,
  "total_entries": 1,
  "next_page": null,
  "previous_page": null,
  "page": 1,
  "links": {
    "first": "https://timetrakkr.com/api/v1/users/ID/project_assignments?page=1",
    "next": null,
    "previous": null,
    "last": "https://timetrakkr.com/api/v1/users/ID/project_assignments?page=1"
  }
}

ERRORS

{
  "message": "Project not found"
}

GET/v1/users/{id}/teammatesList a user’s direct reports

PARAMETERS

id (required) — The user id (UUID)
page — Page number, starting at 1
per_page — Items per page (default 100, max 2000)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope
404No such record in this workspace
429Rate limited. Retry after the Retry-After header.

EXAMPLE LIST

{
  "users": [
    {
      "id": "7a1b2c3d-4e5f-4061-8273-8495a6b7c8d9",
      "name": "Priya Nair",
      "first_name": "Priya",
      "last_name": "Nair",
      "email": "[email protected]",
      "is_active": true,
      "access_roles": [
        "member"
      ],
      "created_at": "2026-08-03T09:12:00.000Z",
      "updated_at": "2026-08-03T09:12:00.000Z"
    }
  ],
  "per_page": 100,
  "total_pages": 1,
  "total_entries": 1,
  "next_page": null,
  "previous_page": null,
  "page": 1,
  "links": {
    "first": "https://timetrakkr.com/api/v1/users/ID/teammates?page=1",
    "next": null,
    "previous": null,
    "last": "https://timetrakkr.com/api/v1/users/ID/teammates?page=1"
  }
}

ERRORS

{
  "message": "Project not found"
}

Roles

Work roles (job functions), assignable to members.

GET/v1/rolesList roles

PARAMETERS

page — Page number, starting at 1
per_page — Items per page (default 100, max 2000)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope
429Rate limited. Retry after the Retry-After header.

EXAMPLE LIST

{
  "roles": [
    {
      "id": "80192a3b-4c5d-4f60-9718-293a4b5c6d7e",
      "name": "Senior designer",
      "created_at": "2026-08-03T09:12:00.000Z",
      "updated_at": "2026-08-03T09:12:00.000Z"
    }
  ],
  "per_page": 100,
  "total_pages": 1,
  "total_entries": 1,
  "next_page": null,
  "previous_page": null,
  "page": 1,
  "links": {
    "first": "https://timetrakkr.com/api/v1/roles?page=1",
    "next": null,
    "previous": null,
    "last": "https://timetrakkr.com/api/v1/roles?page=1"
  }
}

ERRORS

{
  "message": "Project not found"
}

POST/v1/rolesCreate a role · manager+

BODY

name — Required

RESPONSES

201Created
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (org-wide)
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "80192a3b-4c5d-4f60-9718-293a4b5c6d7e",
  "name": "Senior designer",
  "created_at": "2026-08-03T09:12:00.000Z",
  "updated_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

PATCH/v1/roles/{id}Update a role · manager+

PARAMETERS

id (required) — The role id (UUID)

BODY

name — Required

RESPONSES

200OK
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (org-wide)
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "80192a3b-4c5d-4f60-9718-293a4b5c6d7e",
  "name": "Senior designer",
  "created_at": "2026-08-03T09:12:00.000Z",
  "updated_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

DELETE/v1/roles/{id}Delete a role · manager+

PARAMETERS

id (required) — The role id (UUID)

RESPONSES

204Deleted. No body.
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (org-wide)
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

ERRORS

{
  "message": "Project not found"
}

Invoices

Invoices, payments, and sending. Admin tokens or organization keys only.

GET/v1/invoicesList invoices

PARAMETERS

state — draft, open, partially_paid, paid, closed
client_id — Filter by client
page — Page number, starting at 1
per_page — Items per page (default 100, max 2000)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope
429Rate limited. Retry after the Retry-After header.

EXAMPLE LIST

{
  "invoices": [
    {
      "id": "4d5e6f70-8192-4c3d-a4b5-c6d7e8f90a1b",
      "number": "1042",
      "state": "draft",
      "subject": "August retainer",
      "client": {
        "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
        "name": "Acme Corp"
      },
      "amount": 5400,
      "paid_amount": 0,
      "due_amount": 5400,
      "currency": "USD",
      "issue_date": "2026-08-01",
      "due_date": "2026-08-31",
      "period_start": "2026-07-01",
      "period_end": "2026-07-31",
      "sent_at": null,
      "created_at": "2026-08-03T09:12:00.000Z",
      "updated_at": "2026-08-03T09:12:00.000Z"
    }
  ],
  "per_page": 100,
  "total_pages": 1,
  "total_entries": 1,
  "next_page": null,
  "previous_page": null,
  "page": 1,
  "links": {
    "first": "https://timetrakkr.com/api/v1/invoices?page=1",
    "next": null,
    "previous": null,
    "last": "https://timetrakkr.com/api/v1/invoices?page=1"
  }
}

ERRORS

{
  "message": "Project not found"
}

POST/v1/invoicesCreate an invoice · admin

Provide line_items OR period_start+period_end. Generated invoices mark hours billed so nothing is double-invoiced.

BODY

client_id — UUID, required
line_items — Array of {kind, description, quantity, unit_price} for a free-form invoice
period_start — With period_end: generate from uninvoiced time instead
period_end — YYYY-MM-DD
grouping — task (default), person, or detailed
include_expenses — Defaults true
subject — Subject line
issue_date — Defaults today
due_date — YYYY-MM-DD
tax — Percent
discount — Percent

RESPONSES

201Created
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (admin)
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "4d5e6f70-8192-4c3d-a4b5-c6d7e8f90a1b",
  "number": "1042",
  "state": "draft",
  "subject": "August retainer",
  "client": {
    "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
    "name": "Acme Corp"
  },
  "amount": 5400,
  "paid_amount": 0,
  "due_amount": 5400,
  "currency": "USD",
  "issue_date": "2026-08-01",
  "due_date": "2026-08-31",
  "period_start": "2026-07-01",
  "period_end": "2026-07-31",
  "sent_at": null,
  "created_at": "2026-08-03T09:12:00.000Z",
  "updated_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

GET/v1/invoices/{id}Retrieve an invoice (lines + payments)

PARAMETERS

id (required) — The invoice id (UUID)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope
404No such record in this workspace
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "4d5e6f70-8192-4c3d-a4b5-c6d7e8f90a1b",
  "number": "1042",
  "state": "draft",
  "subject": "August retainer",
  "client": {
    "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
    "name": "Acme Corp"
  },
  "amount": 5400,
  "paid_amount": 0,
  "due_amount": 5400,
  "currency": "USD",
  "issue_date": "2026-08-01",
  "due_date": "2026-08-31",
  "period_start": "2026-07-01",
  "period_end": "2026-07-31",
  "sent_at": null,
  "created_at": "2026-08-03T09:12:00.000Z",
  "updated_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

GET/v1/invoices/{id}/ublDownload the invoice as a UBL 2.1 (EN 16931) XML e-invoice

Returns application/xml (not the JSON envelope). Supplier details come from Invoices → Configure → Company info.

PARAMETERS

id (required) — The invoice id (UUID)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope
404No such record in this workspace
429Rate limited. Retry after the Retry-After header.

ERRORS

{
  "message": "Project not found"
}

PATCH/v1/invoices/{id}Update a draft invoice · admin

PARAMETERS

id (required) — The invoice id (UUID)

BODY

subject — Subject
notes — Notes
issue_date — YYYY-MM-DD
due_date — YYYY-MM-DD
tax — Percent
discount — Percent

RESPONSES

200OK
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (admin)
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "4d5e6f70-8192-4c3d-a4b5-c6d7e8f90a1b",
  "number": "1042",
  "state": "draft",
  "subject": "August retainer",
  "client": {
    "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
    "name": "Acme Corp"
  },
  "amount": 5400,
  "paid_amount": 0,
  "due_amount": 5400,
  "currency": "USD",
  "issue_date": "2026-08-01",
  "due_date": "2026-08-31",
  "period_start": "2026-07-01",
  "period_end": "2026-07-31",
  "sent_at": null,
  "created_at": "2026-08-03T09:12:00.000Z",
  "updated_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

DELETE/v1/invoices/{id}Delete a draft invoice · admin

PARAMETERS

id (required) — The invoice id (UUID)

RESPONSES

204Deleted. No body.
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (admin)
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

ERRORS

{
  "message": "Project not found"
}

POST/v1/invoices/{id}/messagesMark an invoice sent · admin

Moves draft → open. Email delivery stays a deliberate in-app action.

PARAMETERS

id (required) — The invoice id (UUID)

RESPONSES

201Created
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (admin)
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "4d5e6f70-8192-4c3d-a4b5-c6d7e8f90a1b",
  "event_type": "send",
  "state": "open"
}

ERRORS

{
  "message": "Project not found"
}

POST/v1/invoices/{id}/paymentsRecord a payment · admin

PARAMETERS

id (required) — The invoice id (UUID)

BODY

amount — Required
paid_date — YYYY-MM-DD, required
notes — Notes

RESPONSES

201Created
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (admin)
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "4d5e6f70-8192-4c3d-a4b5-c6d7e8f90a1b",
  "number": "1042",
  "state": "draft",
  "subject": "August retainer",
  "client": {
    "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
    "name": "Acme Corp"
  },
  "amount": 5400,
  "paid_amount": 0,
  "due_amount": 5400,
  "currency": "USD",
  "issue_date": "2026-08-01",
  "due_date": "2026-08-31",
  "period_start": "2026-07-01",
  "period_end": "2026-07-31",
  "sent_at": null,
  "created_at": "2026-08-03T09:12:00.000Z",
  "updated_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

DELETE/v1/invoices/{id}/payments/{paymentId}Delete a payment · admin

PARAMETERS

id (required) — The invoice id (UUID)
paymentId (required) — Payment UUID

RESPONSES

204Deleted. No body.
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (admin)
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

ERRORS

{
  "message": "Project not found"
}

Estimates

Quotes that convert to invoices. Admin tokens or organization keys only.

GET/v1/estimatesList estimates · manager+

PARAMETERS

page — Page number, starting at 1
per_page — Items per page (default 100, max 2000)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope or the required grade (org-wide)
429Rate limited. Retry after the Retry-After header.

EXAMPLE LIST

{
  "estimates": [
    {
      "id": "b2c3d4e5-f607-4182-93a4-b5c6d7e8f90a",
      "number": "204",
      "state": "draft",
      "subject": "Rebrand — phase two",
      "client": {
        "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
        "name": "Acme Corp"
      },
      "amount": 18500,
      "currency": "USD",
      "issue_date": "2026-08-01",
      "created_at": "2026-08-03T09:12:00.000Z"
    }
  ],
  "per_page": 100,
  "total_pages": 1,
  "total_entries": 1,
  "next_page": null,
  "previous_page": null,
  "page": 1,
  "links": {
    "first": "https://timetrakkr.com/api/v1/estimates?page=1",
    "next": null,
    "previous": null,
    "last": "https://timetrakkr.com/api/v1/estimates?page=1"
  }
}

ERRORS

{
  "message": "Project not found"
}

POST/v1/estimatesCreate an estimate · admin

BODY

client_id — UUID, required
line_items — Array of {kind, description, quantity, unit_price}, required
subject — Subject
issue_date — Defaults today
tax — Percent
discount — Percent

RESPONSES

201Created
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (admin)
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "b2c3d4e5-f607-4182-93a4-b5c6d7e8f90a",
  "number": "204",
  "state": "draft",
  "subject": "Rebrand — phase two",
  "client": {
    "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
    "name": "Acme Corp"
  },
  "amount": 18500,
  "currency": "USD",
  "issue_date": "2026-08-01",
  "created_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

GET/v1/estimates/{id}Retrieve an estimate · manager+

PARAMETERS

id (required) — The estimate id (UUID)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope or the required grade (org-wide)
404No such record in this workspace
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "b2c3d4e5-f607-4182-93a4-b5c6d7e8f90a",
  "number": "204",
  "state": "draft",
  "subject": "Rebrand — phase two",
  "client": {
    "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
    "name": "Acme Corp"
  },
  "amount": 18500,
  "currency": "USD",
  "issue_date": "2026-08-01",
  "created_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

PATCH/v1/estimates/{id}Change estimate state · admin

PARAMETERS

id (required) — The estimate id (UUID)

BODY

state — sent, accepted, or declined

RESPONSES

200OK
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (admin)
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "b2c3d4e5-f607-4182-93a4-b5c6d7e8f90a",
  "number": "204",
  "state": "draft",
  "subject": "Rebrand — phase two",
  "client": {
    "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
    "name": "Acme Corp"
  },
  "amount": 18500,
  "currency": "USD",
  "issue_date": "2026-08-01",
  "created_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

DELETE/v1/estimates/{id}Delete a draft estimate · admin

PARAMETERS

id (required) — The estimate id (UUID)

RESPONSES

204Deleted. No body.
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (admin)
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

ERRORS

{
  "message": "Project not found"
}

POST/v1/estimates/{id}/convertConvert to a draft invoice · admin

PARAMETERS

id (required) — The estimate id (UUID)

RESPONSES

201Created
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (admin)
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "4d5e6f70-8192-4c3d-a4b5-c6d7e8f90a1b",
  "number": "1042",
  "state": "draft",
  "subject": "August retainer",
  "client": {
    "id": "2b3c4d5e-6f70-4b8c-9d0e-1f2a3b4c5d6e",
    "name": "Acme Corp"
  },
  "amount": 5400,
  "paid_amount": 0,
  "due_amount": 5400,
  "currency": "USD",
  "issue_date": "2026-08-01",
  "due_date": "2026-08-31",
  "period_start": "2026-07-01",
  "period_end": "2026-07-31",
  "sent_at": null,
  "created_at": "2026-08-03T09:12:00.000Z",
  "updated_at": "2026-08-03T09:12:00.000Z"
}

ERRORS

{
  "message": "Project not found"
}

Expenses

Expenses and categories. Member tokens manage their own.

GET/v1/expensesList expenses

PARAMETERS

user_id — Required with an organization key
from — YYYY-MM-DD
to — YYYY-MM-DD
page — Page number, starting at 1
per_page — Items per page (default 100, max 2000)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope
429Rate limited. Retry after the Retry-After header.

EXAMPLE LIST

{
  "expenses": [
    {
      "id": "90a1b2c3-d4e5-4f60-8172-93a4b5c6d7e8",
      "spent_date": "2026-08-03",
      "total_cost": 42.5,
      "billable": true,
      "is_reimbursable": true,
      "notes": "Stock photography license",
      "project": {
        "name": "Acme Rebrand"
      },
      "client": {
        "name": "Acme Corp"
      },
      "expense_category": {
        "name": "Software"
      },
      "user": {
        "id": "7a1b2c3d-4e5f-4061-8273-8495a6b7c8d9"
      }
    }
  ],
  "per_page": 100,
  "total_pages": 1,
  "total_entries": 1,
  "next_page": null,
  "previous_page": null,
  "page": 1,
  "links": {
    "first": "https://timetrakkr.com/api/v1/expenses?page=1",
    "next": null,
    "previous": null,
    "last": "https://timetrakkr.com/api/v1/expenses?page=1"
  }
}

ERRORS

{
  "message": "Project not found"
}

POST/v1/expensesCreate an expense

BODY

spent_date — YYYY-MM-DD, required
total_cost — Required
project_id — UUID
expense_category_id — UUID
billable — true/false
is_reimbursable — true/false
notes — Notes
user_id — Required with an organization key

RESPONSES

201Created
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "90a1b2c3-d4e5-4f60-8172-93a4b5c6d7e8",
  "spent_date": "2026-08-03",
  "total_cost": 42.5,
  "billable": true,
  "is_reimbursable": true,
  "notes": "Stock photography license",
  "project": {
    "name": "Acme Rebrand"
  },
  "client": {
    "name": "Acme Corp"
  },
  "expense_category": {
    "name": "Software"
  },
  "user": {
    "id": "7a1b2c3d-4e5f-4061-8273-8495a6b7c8d9"
  }
}

ERRORS

{
  "message": "Project not found"
}

DELETE/v1/expenses/{id}Delete an expense

PARAMETERS

id (required) — The expense id (UUID)

RESPONSES

204Deleted. No body.
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope
404No such record in this workspace
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

ERRORS

{
  "message": "Project not found"
}

GET/v1/expense_categoriesList expense categories

PARAMETERS

page — Page number, starting at 1
per_page — Items per page (default 100, max 2000)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope
429Rate limited. Retry after the Retry-After header.

EXAMPLE LIST

{
  "expense_categories": [
    {
      "id": "a1b2c3d4-e5f6-4071-8293-a4b5c6d7e8f9",
      "name": "Software",
      "unit_price": null,
      "is_active": true
    }
  ],
  "per_page": 100,
  "total_pages": 1,
  "total_entries": 1,
  "next_page": null,
  "previous_page": null,
  "page": 1,
  "links": {
    "first": "https://timetrakkr.com/api/v1/expense_categories?page=1",
    "next": null,
    "previous": null,
    "last": "https://timetrakkr.com/api/v1/expense_categories?page=1"
  }
}

ERRORS

{
  "message": "Project not found"
}

POST/v1/expense_categoriesCreate an expense category · manager+

BODY

name — Required
unit_price — For unit-based categories

RESPONSES

201Created
400Malformed JSON, or a field failed validation
401Missing, expired or invalid token
403Token lacks the write scope or the required grade (org-wide)
422Refused by a business rule — the message says which
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "id": "a1b2c3d4-e5f6-4071-8293-a4b5c6d7e8f9",
  "name": "Software",
  "unit_price": null,
  "is_active": true
}

ERRORS

{
  "message": "Project not found"
}

Reports

Aggregations with money — manager+ tokens or organization keys.

GET/v1/reports/time/{dimension}Time report by clients, projects, tasks, or team · manager+

PARAMETERS

dimension (required) — clients, projects, tasks, or team
from (required) — YYYY-MM-DD
to (required) — YYYY-MM-DD

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope or the required grade (org-wide)
404No such record in this workspace
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "project": "Acme Rebrand",
  "total_hours": 128.5,
  "billable_hours": 119,
  "billable_amount": 17255
}

ERRORS

{
  "message": "Project not found"
}

GET/v1/reports/expenses/{dimension}Expense report by categories, projects, or team · manager+

PARAMETERS

dimension (required) — categories, projects, or team
from (required) — YYYY-MM-DD
to (required) — YYYY-MM-DD

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope or the required grade (org-wide)
404No such record in this workspace
429Rate limited. Retry after the Retry-After header.

EXAMPLE RESPONSE

{
  "project": "Acme Rebrand",
  "total_amount": 412.75,
  "billable_amount": 380
}

ERRORS

{
  "message": "Project not found"
}

GET/v1/reports/project_budgetHours budget vs actual per project · manager+

PARAMETERS

from (required) — YYYY-MM-DD
to (required) — YYYY-MM-DD

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope or the required grade (org-wide)
429Rate limited. Retry after the Retry-After header.

EXAMPLE LIST

{
  "results": [
    {
      "project_id": "9c8b7a65-4321-4fed-9876-543210fedcba",
      "project_name": "Acme Rebrand",
      "budget": 400,
      "budget_spent": 328,
      "budget_remaining": 72,
      "budget_by": "project_hours",
      "budget_people": []
    }
  ],
  "per_page": 100,
  "total_pages": 1,
  "total_entries": 1,
  "next_page": null,
  "previous_page": null,
  "page": 1,
  "links": {
    "first": "https://timetrakkr.com/api/v1/reports/project_budget?page=1",
    "next": null,
    "previous": null,
    "last": "https://timetrakkr.com/api/v1/reports/project_budget?page=1"
  }
}

ERRORS

{
  "message": "Project not found"
}

GET/v1/reports/uninvoicedApproved, unbilled hours and amounts per project · manager+

PARAMETERS

page — Page number, starting at 1
per_page — Items per page (default 100, max 2000)

RESPONSES

200OK
401Missing, expired or invalid token
403Token lacks the read scope or the required grade (org-wide)
429Rate limited. Retry after the Retry-After header.

EXAMPLE LIST

{
  "results": [
    {
      "project_id": "9c8b7a65-4321-4fed-9876-543210fedcba",
      "project_name": "Acme Rebrand",
      "client_name": "Acme Corp",
      "uninvoiced_hours": 22.75,
      "uninvoiced_amount": 3298.75,
      "uninvoiced_expenses": 42.5
    }
  ],
  "per_page": 100,
  "total_pages": 1,
  "total_entries": 1,
  "next_page": null,
  "previous_page": null,
  "page": 1,
  "links": {
    "first": "https://timetrakkr.com/api/v1/reports/uninvoiced?page=1",
    "next": null,
    "previous": null,
    "last": "https://timetrakkr.com/api/v1/reports/uninvoiced?page=1"
  }
}

ERRORS

{
  "message": "Project not found"
}