WorkGuru Public API V2

Connecting and Authentication

Every endpoint requires a JWT Bearer token (this documentation page, the token endpoints and GET /api/v2/ping are the only anonymous routes). You authenticate with an API key + secret, created under Settings → API Keys in WorkGuru. The owning tenant is resolved from the key, so there is nothing tenant-specific to configure — you only ever see and change data in your own WorkGuru tenant.

There are two ways to get a token from the same API key; both return the same Bearer JWT.

Recommended — OAuth2 client credentials

Use the standard OAuth2 client-credentials grant, with your API key as client_id and your secret as client_secret:

POST /api/v2/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id={API_KEY}&client_secret={SECRET}

The response is { "access_token": "…", "token_type": "Bearer", "expires_in": 86400 } (the token is valid for 24 hours), plus a scope field when the key is scoped — see below.

To try endpoints in this portal: click Authorize (top of the page), choose OAuth2, then enter your API key in the API Key field and your secret in the API Secret field, and press Authorize. This portal fetches a token from the endpoint above and attaches it to every Test Request for you — no copy-paste. (Credentials Location can be left on either setting; both work.)

Existing integrations — direct key exchange

If you already integrate with WorkGuru, the original direct key-exchange endpoint (JSON { apiKey, secret } → { accessToken, expireInSeconds, … }) is unchanged and fully supported — your existing integration keeps working with no changes. New integrations should prefer the OAuth2 flow above.

Sending the token

Add the header Authorization: Bearer {accessToken} to every request. If you already have a token (e.g. from your own code) and want to paste it here, click Authorize, choose Bearer, and enter the full value including the word — Bearer {accessToken}.

Scopes

A scope limits what an API key can do through this API, on top of the WorkGuru permissions the key already holds — a request must satisfy both. Scopes are granted per key under Settings → API Keys → Scopes.

There is one scope per resource and operation:

• workguru.{resource}.read — the GET endpoints for that resource, e.g. workguru.quotes.read.
• workguru.{resource}.write — everything else on it (POST, PUT, PATCH, DELETE and actions), e.g. workguru.quotes.write.
• workguru.read — a coarse scope granting read on every resource, including margins, unit costs and supplier pricing. Prefer the per-resource read scopes.

{resource} is the path segment: quotes, purchase-orders, stock-levels, and so on. There is deliberately no coarse write scope, so adding a resource to this API never widens an existing key's write access.

A key with no scopes granted cannot reach any data on this API — every /api/v2 data resource refuses it with 403 No scopes granted, however its token was obtained. Only /oauth/token and /ping, which carry no tenant data, sit outside the scope model. Scopes are how a key reaches this API, not a restriction layered on top of it, so a new key needs the scopes your integration uses before it will do anything here. This is also why an existing WorkGuru API key does not work: it predates scopes and therefore has none.

To narrow a token to less than the key holds, send a space-delimited scope parameter to the token endpoint:

grant_type=client_credentials&client_id={API_KEY}&client_secret={SECRET}&scope=workguru.quotes.read workguru.clients.read

The response echoes what the token actually carries in its scope field. Requesting a scope the key has not been granted returns 400 with {"error": "invalid_scope"} rather than quietly issuing a broader token — so what you asked for is always what you hold. Omit scope and the token carries everything the key holds; name a subset to take a narrower token for a particular job without changing the key.

A request the token's scopes do not cover returns 403 with application/problem+json, naming the scope that would have allowed it in requiredScope (and every scope that would, in acceptedScopes).

Core Concepts

WorkGuru models a job-based business — quoting work, delivering it, and billing for it. The core entities and how they relate:

• Clients & Suppliers — the companies you sell to and buy from. Contacts are the people attached to a client or supplier (reach them via GET /api/v2/contacts?clientId=…).
• Leads — prospective work in your sales pipeline, each with a category, stage, and owner.
• Quotes — priced proposals to a client, built from task lines (labour) and product lines (materials). A quote is issued, then accepted or declined. Accepting a quote creates downstream work — either a Project or a Stock Sale (the accept response tells you which was created).
• Projects — the delivery of work. They carry the same task/product lines and accumulate real costs from Timesheets (labour staff log against task lines) and Purchase Orders (materials bought from suppliers). A project's lines are two different kinds of thing and their ids say which: a task line is tl_… and a product line is prl_…. To log time, send a task line's tl_… id as taskId on POST /api/v2/timesheets. Send an id back unchanged when updating a line.
• Production Jobs — a specialised project for manufacturing, adding output lines. They share the Project shape and are update-only (born from converting a quote or from production).
• Purchase Orders — orders placed with a supplier and received into a warehouse.
• Stock Sales — selling stock directly to a client, outside of project work.
• Invoices — billing a client for a project or a stock sale. An invoice's lines carry a type of product, task or purchase, and only product lines can be added through the API: a task line records which project task it bills and a purchase line which purchase order, and that link has no field on the contract because it is established when the line is raised from the project or purchase order itself. Existing task and purchase lines can be updated (send the line's id back) or removed (leave them out), and their links are preserved. Note that id and type are BOTH part of a line's identity — the three collections have independent ids, so a lines array can contain a product line and a task line sharing one id value.
• Credit Notes — a client credit note credits a client; a supplier credit note records a credit from a supplier and is raised against a purchase order.
• Assets — anything you keep a service history against (equipment, vehicles, tools, sites, and so on). Attach custom data to them and schedule work against them.

Typical lifecycle: Lead → Quote → (accept) → Project or Stock Sale → Invoice, with Projects drawing costs from Timesheets and Purchase Orders along the way.

Custom Fields

Most entities support tenant-defined custom fields. Read the field definitions for a type, then read or set the values on a specific record:

• GET /api/v2/custom-fields?entityType=client — the fields defined for that entity type (id, label, data type, whether required).
• GET /api/v2/custom-field-values?entityType=client&entityId={id} — the values set on one record.
• PUT /api/v2/custom-field-values?entityType=client&entityId={id} — set values, sending [{ "fieldId": "…", "value": "…" }]. It is a partial upsert: fields you send are updated, others are left untouched, and an empty string clears a field.

entityType accepts: client, supplier, lead, asset, quote, project, production-job, purchase-order, stock-sale, timesheet.

Reference data (looking up ids)

Writes reference other records by id — projectManagerId on a project, warehouseId on a purchase order, a tax rate on an invoice line. These read-only endpoints are how you find those ids:

They page and filter like every other list. Three things worth knowing:

• Inactive records are returned. A user who has left, or a retired warehouse, still appears, so an id on an older record always resolves to a name. Filter on isActive=true when you're choosing something for a new write.
• modifiedSince is not supported on the lookups, and asking for it returns 400 rather than quietly ignoring it. These are tenant configuration, not transactional records — the backing queries don't track changes on them, so a delta filter would silently hand you everything. Page the full list instead; they are small and change rarely. A few of the configuration lists are served in a fixed order and refuse sort for the same reason, naming the order they do use.
• Tax rates are directional. Check canApplyToRevenue / canApplyToExpenses before using one — a revenue-only rate on a purchase order is rejected. rate is a percentage, so 10 means 10%.

Each has its own scope (workguru.users.read, workguru.warehouses.read, workguru.tax-rates.read), so an integration can be granted exactly the lookups it needs. They are read-only: all three are tenant configuration managed in the WorkGuru app.

API Overview