# PaySuiteTT

> Payroll, invoicing, bookkeeping and time tracking for businesses in Trinidad and Tobago. The time tracking API lets AI assistants and scripts log time, run timers, manage clients and projects, correct entries and pull client reports with an API key.

## API reference

- [API reference (Markdown, everything on one page)](https://paysuitett.com/developers/api.md)
- [OpenAPI 3.1](https://paysuitett.com/developers/api/openapi.json)
- [Introduction](https://paysuitett.com/developers/api)
- [Authentication and keys](https://paysuitett.com/developers/api/authentication)
- [Conventions](https://paysuitett.com/developers/api/conventions)
- [The time entry object](https://paysuitett.com/developers/api/time-entry-object)
- [Errors](https://paysuitett.com/developers/api/errors)
- [AI assistants](https://paysuitett.com/developers/api/ai-assistants)

## Account

- [GET /me: Who the key belongs to](https://paysuitett.com/developers/api/me): The key's holder, their business, the key itself and, in plain words, what it can do. Includes billing: whether this key has billing access (role and invoices service). A good first call to check a key works.
- [GET /people: People reports cover](https://paysuitett.com/developers/api/people): The Staff whose time reports cover, for the `person` report filter. A master key gets everyone in the business, with their role.

## Clients and projects

- [GET /projects/{id}: Read a project](https://paysuitett.com/developers/api/project-get): Returns a visible project, including its customer-facing invoiceName (null when unset).
- [GET /clients: List clients](https://paysuitett.com/developers/api/clients-list): The business's client directory, each client with the projects the key's holder can track time on. `id` is the directory entry's, for PATCH /clients/{id}; null for a client named only on a project.
- [POST /clients: Add a client](https://paysuitett.com/developers/api/clients-create): Adds a client to the directory, or returns the existing one with that name (ignoring case).
- [PATCH /clients/{id}: Change a client](https://paysuitett.com/developers/api/client-update): Changes a client in the directory. Send only what changes. Projects name their client, so a new name is carried onto the client's projects too.
- [GET /projects: List projects](https://paysuitett.com/developers/api/projects-list): Active projects the key's holder can track time on; archived ones too with `archived=true`.
- [POST /projects: Add a project](https://paysuitett.com/developers/api/projects-create): Adds a project for the key's holder, as the tracker app does: its client joins the directory, it's shared with the holder's teams, and it gets a first task (`task`, or "General"). A project with that name the holder can already see is returned instead of a duplicate.
- [PATCH /projects/{id}: Change or archive a project](https://paysuitett.com/developers/api/project-update): Changes a project's name, client, description, budget or billing rate, or archives it (`active: false`) and brings it back. Send only what changes. A new client name joins the directory.
- [DELETE /projects/{id}: Delete a project](https://paysuitett.com/developers/api/project-delete): Deletes a project nobody tracked time on, with its tasks. A project with time can't be deleted: archive it instead (PATCH with `active: false`), so its hours stay with it.
- [GET /projects/{id}/tasks: List a project's tasks](https://paysuitett.com/developers/api/tasks-list): The project's active tasks.
- [POST /projects/{id}/tasks: Find or add a task](https://paysuitett.com/developers/api/tasks-create): Finds the task by name in the project, or adds it.

## Teams

- [GET /teams: List teams](https://paysuitett.com/developers/api/teams-list): The business's teams: each with its members (user IDs) and the projects its members can track time on.
- [POST /teams/{id}/members: Add a person to a team](https://paysuitett.com/developers/api/team-member-add): Adds a person to the team, so they can track time on the team's projects.
- [DELETE /teams/{id}/members: Take a person out of a team](https://paysuitett.com/developers/api/team-member-remove): Takes a person out of the team. Their time stays.
- [POST /projects/{id}/teams: Give a team a project](https://paysuitett.com/developers/api/project-team-add): Lets the team's members track time on the project.
- [DELETE /projects/{id}/teams: Take a project from a team](https://paysuitett.com/developers/api/project-team-remove): Stops the team's members tracking new time on the project through the team. Time already tracked stays.

## Timer

- [GET /timer: Running timers](https://paysuitett.com/developers/api/timer-get): The key holder's running or paused timers (usually one).
- [POST /timer/start: Start a timer](https://paysuitett.com/developers/api/timer-start): Starts a timer for the key's holder. Say where the time goes with one of the ways below.
- [PATCH /timer: Change the running timer](https://paysuitett.com/developers/api/timer-update): Changes the running timer's description, billable flag or project without stopping it.
- [POST /timer/stop: Stop the timer](https://paysuitett.com/developers/api/timer-stop): Stops the running timer. The body is optional.

## Time entries

- [GET /time-entries: List time entries](https://paysuitett.com/developers/api/entries-list): Time entries between two dates, newest first. Dates are business days in Trinidad.
- [POST /time-entries: Add finished time](https://paysuitett.com/developers/api/entries-create): Adds a finished block of time for the key's holder, as "Add time" does in the app. A master key adds it for someone else with `user_id`.
- [GET /time-entries/{id}: Get a time entry](https://paysuitett.com/developers/api/entry-get): One time entry.
- [PATCH /time-entries/{id}: Correct a time entry](https://paysuitett.com/developers/api/entry-update): Changes an entry's description, billable flag, times or project. A corrected entry counts as one block from start to end. Send only what changes.
- [DELETE /time-entries/{id}: Delete a time entry](https://paysuitett.com/developers/api/entry-delete): Removes a wrong entry for good. Only unapproved time outside any pay run and without screenshots (screenshots are kept as evidence). Recorded in the business's audit log.
- [POST /time-entries/{id}/approve: Approve a time entry](https://paysuitett.com/developers/api/entry-approve): Approves a stopped entry, as Approve time does: it counts toward billable hours in reports and goes to payroll. An approver can't approve their own time unless they are the owner.
- [POST /time-entries/{id}/unapprove: Take an approval back](https://paysuitett.com/developers/api/entry-unapprove): Returns an approved entry to Needs approval and takes it out of payroll until it's approved again. Refused once its pay run is approved, finalized or paid; a draft pay run is marked to recompute.

## Kiosk shifts

- [GET /kiosk-shifts: List kiosk shifts](https://paysuitett.com/developers/api/kiosk-shifts-list): Clock-ins and clock-outs from the business's kiosks between two work dates, oldest first, with each worker's name, worked hours (breaks taken off), status and approval.
- [POST /kiosk-shifts/approve: Approve kiosk shifts](https://paysuitett.com/developers/api/kiosk-shifts-approve): Approves closed kiosk shifts for payroll, as the Kiosk shifts page does. Shifts already approved, still open or missing a clock-out are skipped, and so is the approver's own shift.
- [PATCH /kiosk-shifts/{id}: Correct a kiosk shift](https://paysuitett.com/developers/api/kiosk-shift-update): Changes a shift's clock-in, clock-out or break, with a note, and approves it; its payroll hours are rebuilt. Use it to fix a missed clock-out. Send only what changes.

## Reports

- [GET /reports: Time report](https://paysuitett.com/developers/api/reports): Every Staff member's time for a client, project or period, as Time Reports shows it: totals, a summary by group, and every entry. Owners', accountants' and managers' own time is left out, unless a master key sends `scope=everyone`. A personal key reports approved time only, so its per-client reports are final; a master key reports every status.

## Billing

- [GET /customers: Find billing customers](https://paysuitett.com/developers/api/customers): Sales contacts of type customer or both, sorted by name, with whether a billing profile exists.
- [GET /billing-profiles: List billing profiles](https://paysuitett.com/developers/api/billing-profiles): Rates, time sources, cadence and unbilled hours for customers with billing profiles.
- [PUT /billing-profiles/{customerId}: Save a billing profile](https://paysuitett.com/developers/api/billing-profile-save): Upserts a customer's profile. Customer and project IDs must belong to this business. Unknown body fields are rejected.
- [DELETE /billing-profiles/{customerId}: Delete a billing profile](https://paysuitett.com/developers/api/billing-profile-delete): Removes the profile without changing invoices or time entries.
- [POST /billing/preview: Preview time to bill](https://paysuitett.com/developers/api/billing-preview): Approved and awaiting-approval billable time, excluding linked entries. Missing fields use the customer's profile. Missing dates use its next service period; 409 NOTHING_TO_BILL when no period is available. Amount is tracked hours × rate, rounded to two decimals, or zero for a missing rate or currency mismatch. Unknown fields are rejected.
- [POST /billing/descriptions: Write time line descriptions](https://paysuitett.com/developers/api/billing-descriptions): Uses the same avoid-names list and optional AI writer as the app. Without a server Claude key, enabled is false and every line receives its plain fallback. Unknown fields are rejected.
- [GET /invoices: List invoices](https://paysuitett.com/developers/api/invoices-list): Newest issue dates first. Invoice objects omit lines; money is in the invoice's currency (books holds the TTD amounts), with two decimal precision. paid excludes reversed payments; balanceDue subtracts posted credits and is zero for drafts/voids. URLs point to this installation's APP_URL host.
- [GET /invoices/{id}: Read an invoice](https://paysuitett.com/developers/api/invoice-get): Includes ordered lines, linked tracked hours and entry counts. A draft's number is INV-DRAFT until it is posted, unless one was typed (numberEnteredManually). timeSchedule and workReport are null without time links; all URLs are absolute app links on APP_URL.
- [POST /invoices: Create a draft invoice](https://paysuitett.com/developers/api/invoice-create): Computes amounts and VAT server-side, then saves via save_invoice_draft. Emailing, payments and voiding stay in the app. Unknown fields are rejected.
- [PATCH /invoices/{id}: Update a draft invoice](https://paysuitett.com/developers/api/invoice-update): All fields are optional. Sending lines replaces every line. Omitting lines preserves and re-sends existing lines and their time links unchanged. Non-drafts return 409 CONFLICT. Unknown fields are rejected.
- [POST /invoices/from-time: Create a draft from tracked time](https://paysuitett.com/developers/api/invoice-from-time): Runs the preview with the customer's profile, then creates hours lines at exact tracked hours in the profile's currency and sets the service period. Skips missing rates and currency mismatches; 409 NOTHING_TO_BILL when no lines remain. Default billed hours are tracked hours; overrides cannot exceed tracked hours. Unknown fields are rejected.
- [POST /invoices/{id}/post: Post a draft invoice](https://paysuitett.com/developers/api/invoice-post): Posts the draft to the books (a journal in TTD) and assigns its number: PREFIX-YYYYMMDD-MMDD when the customer's profile has a prefix and the invoice a service period, else INV-YYYY-NNNNN. Posting a posted invoice returns it unchanged; void returns 409 CONFLICT. Emailing stays in the app.
- [GET /invoices/{id}/pdf: Download invoice PDF](https://paysuitett.com/developers/api/invoice-pdf): Returns application/pdf bytes using the app's renderer. with=work-report appends the work report, one PDF.
- [GET /invoices/{id}/time-schedule: Download time schedule PDF](https://paysuitett.com/developers/api/invoice-time-schedule): Hours per day per line. 404 without time links.
- [GET /invoices/{id}/work-report: Download work report PDF](https://paysuitett.com/developers/api/invoice-work-report): The Time Reports summary for exactly the time the invoice bills: hours per day and each project's time-entry descriptions, under invoice names. Amounts at the invoice's rates and currency, shown only when every line bills all its tracked time. 404 without time links.

## Optional

- [Guides for using PaySuiteTT](https://paysuitett.com/guides)
- [Support](https://paysuitett.com/support)