Reference

Lookups

Reference data — the IDs the gateway will accept on job and site operations.

All lookups respond with { "items": [...] }. Results are scoped to what your key can see and returned in full — there is no cursor or pagination in v1. customers and projects return one item per ID in your scope; sites, job-types, and job-statuses return the complete list. All lookup endpoints require at least the jobs:read scope.

Each lookup hits FieldInsight fresh — there is no server-side cache. These IDs change rarely (only on operator action in FieldInsight). Cache the results in your application — refresh on a daily schedule, or on demand if a lookup fails. See Rate limits for why this matters.

GET/v1/customersscope: jobs:read

The customers your key can act on. Returned by fetching each scoped customer ID directly from FieldInsight — not by filtering a full account list. Use the ID to filter jobs or attach a site to a customer on create.

{ "items": [{ "id": "245715", "name": "Acme" }] }

GET/v1/sitesscope: jobs:read

Sites under your customers. Each item also carries `customerId` — the owning FieldInsight customer. Omit params for all your sites, or pass `id` to fetch one; for a single site prefer GET /v1/sites/{id} (returns the object directly, 404 if out of scope). Use the ID as `site=` on POST /v1/jobs. To add or edit a site, see POST and PATCH /v1/sites (requires sites:write scope).

{ "items": [{ "id": "3065756", "name": "Acme Depot — Unit 3/24 Brand Dr", "customerId": "245715" }] }

GET/v1/projectsscope: jobs:read

Projects you may attach to a job. This is an operator-curated allowlist — not all FieldInsight projects appear here, and FieldInsight exposes no project→customer link. Use the ID as `project=` on POST /v1/jobs.

{ "items": [{ "id": "1052232", "name": "Test Project #1" }] }

GET/v1/job-typesscope: jobs:read

Available job types (global to the account). Use the ID as `job_type=` on POST /v1/jobs.

{ "items": [{ "id": "29400", "name": "Installation" }] }

GET/v1/job-statusesscope: jobs:read

Available job statuses (global to the account). Use IDs as `?status=` on GET /v1/jobs to filter by status.

{ "items": [{ "id": "68392", "name": "Tentative" }] }

GET/v1/custom-fieldsscope: jobs:read

Custom-field names you may send under `custom_fields` on POST / PATCH /v1/jobs.

{ "items": [{ "external_name": "scope_of_work", "fi_field_id": "349661", "job_type_id": null }] }