Client timesheets (documents)

What the timesheet documents a billing run produces contain, who can download them, how they are delivered to billing recipients, and how to fetch them through the API or MCP.

Written for
admin, user, integration-developer
Roles
owner, admin, project-manager, member, billing-contact, agent
Requires
Owner or Admin for every document; Project manager for documents of their own projects; Workspace user with a client-wide document grant; Billing contact with a full login for their own client
Feature
documents

A client timesheet is the document a billing run produces: the priced statement of a client's hours for one period. It is rendered once from the run's own snapshot and never changes afterwards, so what a client downloaded is exactly what SAQ shows later. The Documents page lists "Client timesheets produced by billing runs. You see the artifacts you may download."

What a run produces

  • Scope, from the client's Timesheet layout: Combined gives one document for the period with a section per project; Per project gives one document per project.
  • Formats: each document is produced as HTML and CSV, and as PDF where PDF rendering is available. The three share one document number and appear as separate rows.
  • Number: {prefix}-TS-{year}-{month}-{n}, for example ACME-TS-2026-08-1, numbered per period.
  • Version, Checksum, size, and Locale: the client's Language decides the document language.
  • Documents are immutable. A voided run marks its documents Voided and they can no longer be downloaded.

Content

The heading is "Timesheet {number}" with the client, the period, and the workspace name. For each project:

  • A summary per Category with Hours, Rate, and Amount.
  • A Charged table: Date, Category, Ticket, Description, Hours, Rate, Amount.
  • A Covered by time bank table and a Free of charge table with the same columns and no amounts.
  • "Project total: {hours} h, {amount}".

Then a Time banks table (Bank, Opening, Credit, Carried in, Borrowed, Consumed, Overage, Closing) when the client has banks, "Total charged", the bank and free totals, and, if any, "Work in progress, not yet billed" with the open deliverable tickets.

What the client reads under Description is the ticket's Billing description, never the ticket title, the entry notes, or the person who did the work. Corrections are marked "correction". Hours are decimal (1.50), rates and amounts are in the client's currency and exclude VAT.

The CSV has one row per priced part of an entry: date, project, category, ticket, description, outcome, minutes, rate_minor, amount_minor, currency, with money in minor units.

Who can download

Reader Documents
Owner, Admin All.
Workspace user with a client-wide grant Every document of that client, plus the project documents of projects they manage.
Workspace-user Project manager Project-scope documents of the projects they manage. Combined documents are not included.
Other workspace users None. "You have no document access. Owner and admin grant client-wide access; a project manager sees their own project artifacts."
Billing contact with a password or passkey login Every document of their own client. A magic-link session does not qualify.
Other client users None; the Documents entry is not in their sidebar.

Owners and Admins grant client-wide access under Clients → client → Documents → Client-wide document access: pick a Workspace user and select Grant access. "A workspace user with this grant downloads every artifact of this client and sees its bank balances." A project-scoped API key can only download project-scope documents.

Every download is recorded in the audit log.

Delivery

After rendering, SAQ emails each document to the client's Billing recipients (Clients → client → Contacts → Billing recipients → Designate), through the workspace mailbox, with the text "Your timesheet {number} is attached." A per-project document goes to recipients designated for that project, or to the client-wide recipients when none are; a combined document goes to the client-wide recipients.

The Delivery column shows each address and state: in flight, sent, failed, skipped, no mailbox, or unknown, reconcile; No recipients when nobody is designated. Failed or unknown deliveries are reconciled under Settings → Mailbox. The run moves to Delivered once every document has been sent.

Redaction

Redacting a ticket replaces its content, including the billing description. Documents that carried it are superseded by a new numbered version, and the old artifact refuses download: "This document was redacted." A voided run's documents are marked redacted without a replacement.

API and MCP

  • GET /api/w/{slug}/documents lists what the caller may download, with delivery states.
  • GET /api/w/{slug}/documents/{id}/download returns the file; HTML inline, PDF and CSV as attachments.
  • The get_timesheet MCP tool lists documents, optionally per client, or returns one document's content: PDF as base64, HTML and CSV as text.
curl -o ACME-TS-2026-08-1.pdf \
  "https://saq.no/api/w/acme/documents/01924c3e-6b2a-7d11-9d0e-3a1f4b5c6d7e/download" \
  -H "Authorization: Bearer saq_YOUR_TOKEN"

See Download client timesheets and Documents.

Common problems

"You have no document access." You are a Member without a grant or a managed project. Ask an Owner or Admin for a client-wide grant.

A billing contact sees no Documents entry. They must log in with a password or passkey; magic-link sessions never open documents. The Billing contact flag is "usable after full login".

"This document was voided." The run was voided. A replacement run produces new documents.

"A project-scoped token cannot download combined timesheets." Use a key without a project restriction, or switch the client to Per project layout.

Delivery says "skipped, no mailbox". No workspace mailbox is connected. Connect one under Settings → Mailbox and reconcile, or download and send the file yourself.

  • Run billing for a client Price a client's time for one closed period with the five-step run wizard, fix blockers, review billing descriptions and bank totals, commit, and void a run when needed.
  • Billing fields on a ticket What the Billing client, Policy, Mode, Billing description, and Estimate fields on a ticket mean, who may set them, and what changes when the billing client or kind changes.
  • Contacts and billing recipients Register email identities without a login, designate the addresses that receive timesheet documents, and grant workspace users client-wide document access.
  • Billing contact What the Billing contact flag on a client user gives, how it differs from a billing recipient, and how timesheets and bank balances reach the client.
  • Download client timesheets How to list the client timesheet documents a token may see and download them as HTML, PDF, or CSV through the API or the MCP get_timesheet tool.
  • Documents List and download client timesheets (billing documents) through the SAQ REST API, with formats, headers, who may download, and the browser-only document grants.
  • Client timesheet A client timesheet is the numbered, immutable document a billing run produces for one client and period, as HTML, PDF, and CSV, delivered by email to the client's billing recipients.