TradesWork API and webhooks

Version 2026-10-14. Read and write customers, locations, jobs, dispatch, estimates, invoices, payments, the price book and technicians; get a signed webhook for every lifecycle event. Everything you can do here goes through the same rules, permissions and audit trail as the office app.

Authentication

Create an API key in Settings › Integrations › API Application Access (owners and admins) and pick its scopes. Send it as a bearer token. Apps that other companies install use OAuth access tokens instead (below).

curl https://tradesos-three.vercel.app/api/v1/platform/me \
  -H "Authorization: Bearer tos_YOUR_KEY"

Conventions

• Base URL https://tradesos-three.vercel.app/api/v1/platform. JSON in and out. Money is integer cents; times are ISO-8601.
• Lists are newest first: limit (1–100), then pass nextCursor as cursor. Sync with updatedSince; find imported records with externalSource + externalId.
• Every POST that creates something accepts an Idempotency-Key header: a retry with the same key and body returns the first response (header Idempotent-Replayed: true) for 24 hours.
• Rate limit: 120 requests per 60 seconds per credential. Watch X-RateLimit-Remaining; a 429 carries Retry-After.
• Errors: { "error": "plain words", "code": "invalid | unauthenticated | insufficient_scope | forbidden | not_found | rejected | rate_limited | …", "requestId": "…" }. Another company’s id is always a 404.

Endpoints

Full request and response schemas: /api/v1/openapi.json (OpenAPI 3.1; import it into Postman, Insomnia or a client generator).

Webhooks

Add an endpoint in Settings › Integrations › API Application Access (or subscribe through the API). Within about a minute of a change we POST an event. Respond with any 2xx within 10 seconds. Anything else is retried after 1 min, 5 min, 30 min, 2 h, 8 h, 24 h, then marked failed; you can resend it from the delivery log. An endpoint that fails continuously for 3 days is turned off and the owner sees why.

POST https://your-app.example.com/hooks
tradesos-signature: t=1760400000,v1=5f8c…
tradesos-event-id: 3b1c…   tradesos-event-type: job.completed

{ "id": "3b1c…", "type": "job.completed", "apiVersion": "2026-10-14", "createdAt": "…",
  "company": { "id": "…" },
  "data": { "objectType": "job", "objectId": "…", "object": { …same shape as GET /jobs/{id}… }, "change": { "before": …, "after": … } } }

Verify every delivery: compute HMAC-SHA256 of `${t}.${rawBody}` with your endpoint’s signing secret and compare it (constant time) with each v1. Reject timestamps more than 5 minutes old, and skip event ids you have already processed (deliveries can repeat). During a secret rotation two v1 values are sent for 24 hours.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(secret, header, rawBody, now = Date.now()) {
  const parts = Object.groupBy(header.split(","), (p) => p.split("=")[0]);
  const t = Number(parts.t?.[0].split("=")[1]);
  if (!t || Math.abs(now / 1000 - t) > 300) return false;
  const want = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  return (parts.v1 ?? []).some((p) => {
    const got = Buffer.from(p.split("=")[1], "hex");
    return got.length === want.length && timingSafeEqual(got, want);
  });
}

Zapier, n8n and Make

Use REST hooks: with a key that has webhooks:manage, POST /webhooks with the catch URL and event types to subscribe, and DELETE /webhooks/{id} to unsubscribe. A key only receives events for records its scopes can read. Actions map to the POST endpoints (create customer, book job, schedule, record payment).

curl -X POST https://tradesos-three.vercel.app/api/v1/platform/webhooks \
  -H "Authorization: Bearer tos_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.zapier.com/hooks/catch/123/abc","eventTypes":["job.completed","invoice.sent"]}'

OAuth apps

Register your app in Settings › Integrations › API Application Access to get a client id and secret. Authorization code flow with PKCE (S256) is required; access tokens last one hour, refresh tokens rotate on every use, and a replayed code ends the grant. The app never gets more than the approving owner or admin can do.

1. Send the person to:
   https://tradesos-three.vercel.app/oauth/authorize?response_type=code&client_id=tosapp_…&redirect_uri=https://you/cb
     &scope=jobs:read%20invoices:read&state=…&code_challenge=…&code_challenge_method=S256
2. Exchange the code:
   curl -X POST https://tradesos-three.vercel.app/api/oauth/token -u tosapp_…:tossec_… \
     -d grant_type=authorization_code -d code=… -d redirect_uri=https://you/cb -d code_verifier=…
3. Refresh:  -d grant_type=refresh_token -d refresh_token=tosrt_…
4. Revoke:   curl -X POST https://tradesos-three.vercel.app/api/oauth/revoke -u tosapp_…:tossec_… -d token=…