Getting started

Before you start

You need an API token for your company. Someone at your company with portal access creates it on the API tokens page and shares the token with you — your integration never signs in.

Each token is scoped to specific APIs, so ask for one scoped to the endpoints you actually call. A narrowly scoped token is safer and easier to replace than one that can reach everything.

Check connectivity

No token needed, so this verifies reachability first:

curl https://YOUR_HOST/health

{"status":"ok"}

Your first request

Send the token as a bearer Authorization header on every call. Here are one day’s tasks:

curl -sS 'https://YOUR_HOST/v1/tasks?date=2026-03-20' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses share the same envelope:

{
  "success": true,
  "numTasks": 2,
  "tasks": [
    {
      "taskId": "…",
      "userName": "…",
      "truckNumber": "114",
      "loadCount": 6,
      "startTime": "2026-03-20T13:02:11.000Z",
      "jobName": "…",
      "status": "…"
    }
  ]
}

You never pass a company identifier. Requests are scoped to the company that issued your token, so you only ever see your own data.

When something goes wrong

Errors return the same shape — a code and a human-readable message.

• 400 — a parameter is missing or malformed. The message names the parameter.
• 401 — the token is wrong or was revoked. Check the header format first.
• 403 — your token is valid but not allowed to make this call. The message says which of two reasons applies: the token is not scoped to this API, which whoever manages your tokens can change, or your company is not approved for it, which needs Iron Sheepdog Support.
• 5xx — a failure on our side. Retry with backoff; if it persists, contact Support with the time of the request.

Things worth knowing

• Dates are UTC. A date parameter means a UTC calendar day, so a request near midnight may not match your local day.
• Lists are paged, never truncated. A response carries hasMore and nextCursor. Keep requesting with the cursor until hasMore is false — a full page on its own does not mean you have everything. Most list cursors (for example /v1/tasks) resume against the live store and do not expire on a timer; /v1/backhaul-matches pages a cached snapshot, so that cursor can expire — see the Backhaul paging notes.
• One token per integration. Scope each token to just the APIs that integration calls, so it can be rotated or revoked without disrupting the rest — and a leaked one reaches less.

Next steps

The developer documentation has the full endpoint reference, request and response shapes, and a panel for trying each endpoint live in the browser. A machine-readable OpenAPI description is at /openapi.json for generating clients.