Reference · GET /v1/jobs

List jobs

Returns the jobs you can see, newest-updated first. Use filters to narrow the result; use the cursor to page through it. Filter names match the response field names.

Request

curl -H "Authorization: Bearer fi_pk_…" \
  "https://<host>/v1/jobs?state=open&page_size=50"

Response

{
  "jobs": [
    {
      "id": "21172159",
      "number": "16",
      "series_number": 16,
      "is_primary": true,
      "title": "Annual service",
      "status": { "id": "68392", "name": "Tentative", "state": "pending" },
      "start_time": "2026-07-01T09:00:00+10:00",
      "end_time":   "2026-07-01T11:00:00+10:00",
      "customer":   { "id": "245715", "name": "Acme" },
      "site":       { "id": "3065756", "address": "Unit 3/24 Brand Dr…" },
      "notes": "",
      "custom_fields": { "scope_of_work": "Install" }
    }
  ],
  "next_cursor": "gt/2634823"
}

Fields

state

open | closed | all

Default: open. Use `closed` for completed/cancelled jobs (e.g. a monthly reconciliation report); `all` when you want both. Most day-to-day reads stick with the default.

status

string

Filter to a single FieldInsight status by ID — fetch the list of valid IDs from /v1/job-statuses. Example: `?status=68392` to return only jobs currently marked "Tentative".

updated_at_from

ISO 8601 UTC

Returns only jobs updated at or after this time. Pair with your last poll timestamp for incremental sync — saves you re-pulling unchanged jobs. Example: `?updated_at_from=2026-06-03T00:00:00Z`.

updated_at_to

ISO 8601 UTC

Upper bound — strictly less than. Combine with updated_at_from for a closed window. Example: a nightly run covers `updated_at_from=<yesterday>` to `updated_at_to=<today>`.

start_time_from

ISO 8601

Returns only jobs scheduled at or after this time. Use for "what’s on this week" or schedule-window views. Example: `?start_time_from=2026-07-01T00:00:00+10:00&start_time_to=2026-07-08T00:00:00+10:00`.

start_time_to

ISO 8601

Upper bound on scheduled start — strictly less than.

number

string

Exact match on the human-readable job number. Quote this number when contacting us about a specific job — it’s the fastest way for us to find it. Example: `?number=16`.

series_number

integer

Returns the primary job plus every revisit that belongs to it. Use when you need the full visit history for a recurring job. Example: `?series_number=16` returns visit 1 (primary) and any follow-up visits.

page_size

1–100

Default 25. Use 100 for bulk syncs to halve your request count; smaller values are fine for interactive UIs.

cursor

string

Pass the `next_cursor` value from the previous response to fetch the next page. Omit on the first call.

Errors

400 invalid-query401 unauthorized429 rate-limited

next_cursor is null when there's no further page in the result set.