API Reference

Build custom integrations against your Tidyflow tenant — sync clients, create jobs, post time logs, and pull reporting data.

---

Base URL & versioning

https://app.tidyflow.com/api/v1

There is currently one version (v1). Breaking changes will be introduced under a new prefix.

---

Authentication

The Tidyflow API uses personal access tokens sent as a Bearer header.

Generate a token

1. Log in to Tidyflow.
2. Open Settings > API tokens.
3. Click New token, give it a name (e.g. Zapier, Internal sync), and copy the token immediately — it will not be shown again.
4. Revoke a token at any time by deleting it from the same page.

Each token inherits the permissions of the user that created it and is scoped to that user’s tenant. Tokens do not expire; revoke any token that may have been exposed.

Sending the token

Add the token to every request:

Authorization: Bearer <your-token>
Accept: application/json

A missing or invalid token returns 401 Unauthenticated.

---

Conventions

Identifiers

Every resource exposes a stable uuid — always use the UUID in URLs and references, not the numeric id.

Pagination

List endpoints return a standard Laravel paginator:

{
  "data": [ ... ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "last_page": 10, "per_page": 50, "total": 480 }
}

Control page size with ?limit= (clients, contacts) or ?per_page= (time logs). Default page size is large — set an explicit limit for predictable results.

Filtering

Filters are passed as query parameters. Array filters use repeated keys: ?tags[]=12&tags[]=15.

Errors

Validation error body:

{
  "message": "The given data was invalid.",
  "errors": {
    "name": ["The name field is required."]
  }
}

Rate limits

Each API token can make up to 300 requests per minute across the API, and some endpoints have lower limits. Over a limit, the API returns 429 Too Many Requests with a Retry-After header giving the seconds to wait. Login is rate-limited separately.

---

Users

Read-only. Useful for resolving user IDs when assigning clients or jobs.

List users

GET /api/v1/users

Query parameters: search.

Get user by ID

GET /api/v1/users/{id}

Find user by email

GET /api/v1/users/email/{email}

Returns the user object, or { "data": null } if no user matches.

User shape

{
  "id": 42,
  "fullname": "Jane Doe",
  "firstname": "Jane",
  "lastname": "Doe",
  "email": "jane@example.com",
  "initials": "JD",
  "avatar_url": "https://...",
  "role": "Admin",
  "timezone": "Australia/Sydney",
  "client_access": "all",
  "is_contractor": false,
  "is_owner": false,
  "archived_date": null
}

client_access is one of all, client_groups, or assigned_clients, and reflects how a Standard user’s client visibility is limited. is_contractor is deprecated (it is true only when client_access is assigned_clients); use client_access instead.

---

Clients

List clients

GET /api/v1/clients

Query parameters:

Search clients (autocomplete)

GET /api/v1/clients/search?q=acme

Returns up to 10 lightweight matches:

{ "clients": [ { "id": 7, "uuid": "...", "name": "Acme Pty Ltd" } ] }

Get a client

GET /api/v1/clients/{uuid}

Create a client

POST /api/v1/clients

Body:

Nested contact object:

Returns the created client in the same shape as GET /clients/{uuid}.

Update a client

PUT /api/v1/clients/{uuid}

All fields are optional — send only what you want to change. Accepts the same fields as create (excluding the nested contact), plus tags (array of tag IDs).

Client shape

{
  "uuid": "...",
  "name": "Acme Pty Ltd",
  "client_id": "AC-001",
  "reg_number": "12 345 678 901",
  "website": "https://acme.com",
  "country": "Australia",
  "state": "NSW",
  "city": "Sydney",
  "street_address": "1 George St",
  "postal_code": "2000",
  "year_end": "06-30",
  "year_end_text": "30 June",
  "is_archived": false,
  "client_status": "active",
  "created_at": "2026-09-12T02:30:32+00:00",
  "contacts": [ ... ]
}

Custom fields defined in your tenant are merged into the response keyed by field name.

---

Contacts

List contacts

GET /api/v1/contacts

Query parameters:

Get a contact

GET /api/v1/contacts/{uuid}

Create a contact

POST /api/v1/contacts

Update a contact

PUT /api/v1/contacts/{uuid}

All fields optional.

Contact shape

{
  "uuid": "...",
  "firstname": "Jane",
  "lastname": "Doe",
  "preferred_name": "Jane",
  "email": "jane@acme.com",
  "phone_number": "+61 400 000 000",
  "portal_enabled": true,
  "clients": [ { "uuid": "...", "name": "Acme Pty Ltd" } ]
}

---

Jobs

The Tidyflow UI calls these “Jobs”. The API path uses /jobs.

List jobs

GET /api/v1/jobs

Query parameters:

Get a job

GET /api/v1/jobs/{uuid}

Includes client, assignees, followers, tags, parent, and subtasks.

Create a job

POST /api/v1/jobs

Job shape (key fields)

{
  "uuid": "...",
  "name": "FY24 financials",
  "description": "...",
  "status": "in_progress",
  "status_name": "In progress",
  "client_uuid": "...",
  "client": { ... },
  "users": [ ... ],
  "tags": [ ... ],
  "start_date": "2026-05-01",
  "due_date": "2026-06-30",
  "estimated_hours": 12,
  "is_overdue": false,
  "is_completed": false,
  "completed_date": null,
  "is_repeating": false,
  "is_subtask": false,
  "parent_uuid": null,
  "sub_tasks": [ ... ]
}

Repeating-job fields are also returned — see the full payload in a real response if you need to replicate recurrence.

---

Time logs

Read-only listing of recorded time.

List time logs

GET /api/v1/time-logs

Query parameters:

Time log shape

{
  "uuid": "...",
  "client": { "uuid": "...", "name": "Acme Pty Ltd" },
  "task":   { "uuid": "...", "name": "FY24 financials" },
  "user":   { "id": 42, "fullname": "Jane Doe" },
  "note": "Reviewed trial balance",
  "hours": 1.5,
  "hours_time": "01:30",
  "date": "2026-05-01",
  "formatted_date": "1 May 2026",
  "created_at": "2026-05-01T09:14:22Z",
  "updated_at": "2026-05-01T09:14:22Z"
}