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?updated_at_from=2026-06-01T00:00:00Z&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

id

string

Fetch a single job by its FieldInsight ID. Returns it in the `jobs` array if it belongs to your account, otherwise an empty list. Example: `?id=21172159`.

state

open | closed | all

Filter by open/closed (your operator configures which statuses count as each). IMPORTANT — open and closed behave differently: `open` returns ALL currently-open jobs and is NOT paginated; `closed` returns only the MOST-RECENT closed jobs (not the full history) and is not paginated — to find an older closed job use id/external_id/site/date filters instead; `all` (or omit) is the normal paginated listing. Requires open/closed statuses configured (else 422), and cannot be combined with `status`.

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". Mutually exclusive with `state`.

site

string

Filter to a single FieldInsight site by ID (from /v1/sites). Example: `?site=3065756`.

project

string

Filter to a single FieldInsight project by ID (from /v1/projects). Example: `?project=1052232`.

external_id

string

Filter by the external reference you set on a job. Example: `?external_id=WO-4471`.

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. Not used with `state=open|closed` (those return a single bounded result with `next_cursor: null`).

Errors

400 invalid-query401 unauthorized403 no-scope422 state-not-configured422 invalid-query (state + status together)422 invalid-request429 rate-limited502 schema-drift502 upstream-scope-violation

next_cursor is null when there's no further page — and is always null for state=open|closed, which return a single bounded result rather than a paginated list.