Skip to main content

List job items

GEThttps://api.fieldtask.example/public/v1/jobs/{job_id}/items
Permissions
job_items:read, jobs:read
Pagination
Cursor, up to 100 per page
Also available as
fieldtask_list_job_items

Returns the items on one job, oldest first by default, one page at a time.

Items include catalog products and services added to the job, and work steps added in the FieldTask app. Each item shows the values saved on the job: name, quantity, unit price, amount and status. Lists show current data, so an item added or changed while you page through may or may not appear.

The job must exist in your organization and not be deleted; otherwise the response is 404 resource_not_found. Jobs in any status can be listed.

Permissions​

PermissionDependency in the permission map
job_items:readDepends on jobs:read
jobs:readNo dependencies

Request​

Responses​

OK

Response Headers
    Cache-Control

    Responses must not be cached.

    X-Request-ID

    Server-generated request correlation ID.

Pagination​

This endpoint has no filters.

  • page_size sets the number of items per page, from 1 to 100. The default is 25.
  • ordering is created_at (oldest first, the default) or -created_at (newest first).
  • When page.has_more is true, request page.next_page_url with the same Authorization header. It keeps your page size and ordering. It's null on the last page.
  • If you build URLs yourself, pass page.next_cursor as cursor and keep the job and every other parameter unchanged. Cursors expire within 24 hours and only work with the job, query and connection that produced them.

See Pagination.

Item fields​

FieldMeaning
id, job_idThe item's ID and the job it belongs to.
name, descriptionThe item's name and description as saved on the job. Either can be null.
item_typeThe item's type: service, product or other. Older items can have other values, so handle values you don't recognize.
price_nameThe name of the price option chosen when the item was added. null for the legacy unit price, and for items not priced from a named option.
quantity, unit_priceDecimal strings with two decimal places, such as "2.50" and "185.00".
amountquantity × unit_price, exact, with four decimal places.
currencyYour organization's current currency.
statusThe item's progress on the job: to do, done or not done. Older items can have other values, so handle values you don't recognize.
allow_evidencesWhether evidence collection is turned on for this item in the app.
created_at, updated_atUTC timestamps.

Work steps and priced items​

The list includes every item on the job, including work steps added in the FieldTask app. No field tells a work step from a priced item, and a unit_price of "0.00" doesn't mean an item is a work step. Use the values as they are rather than classifying them.

Status​

A new item starts as to do. Items currently use to do, done and not done. Handle any other value rather than failing.

Items don't include a product or price ID. Their name, description, type and unit price were copied from the catalog when the item was added, and later catalog changes don't affect them.

Amounts and totals​

amount is the exact product of quantity and unit_price with four decimal places: "1.25" × "12.34" is "15.4250". The app may show line amounts rounded to two decimal places. Neither is an invoice total or an amount paid.

For the job's overall value, read job_value from Get a job. Don't add up item amounts instead: a page holds only some items, and job_value also counts items that are kept on the job but marked inactive, which this list doesn't return.

Evidence​

allow_evidences only reports whether evidence collection is turned on. Evidence itself, such as photos, audio recordings and notes, isn't available through the API.

Errors​

StatuscodeMeaningWhat to do
400invalid_queryA parameter is unknown or repeated, or page_size or ordering is invalid. This endpoint has no filters.Send only page_size, ordering and cursor, each once.
400invalid_cursorThe cursor is malformed, was changed, or belongs to a different query, connection or page size.Use next_page_url or the cursor exactly as returned, with the same query. To change the query, start again without a cursor.
401invalid_tokenThe bearer token is missing, malformed, expired, revoked or issued for a different resource (for example an MCP sign-in).Send a current REST API token or REST OAuth access token as Authorization: Bearer ….
403api_access_not_enabledFieldTask hasn't enabled API access for this organization, or has disabled it.An owner or admin requests access in Settings → API connections.
403insufficient_scopeThe connection lacks job_items:read or jobs:read. error.code is missing_permission.Add the permission named in error.message to the connection.
404resource_not_foundNo job with this ID exists in your organization, the job has been deleted, job item reads aren't available in this environment, or the URL is wrong.Check the job ID with GET /public/v1/jobs, and check the API origin and path (no trailing slash).
405method_not_allowedThis path doesn't accept the HTTP method, or the create isn't enabled in this environment. The Allow header lists the methods that are.Use a method listed in Allow.
429rate_limit_exceededToo many requests in the current minute, or too many concurrent requests, for the organization or connection.Wait for Retry-After seconds, then retry.
429daily_quota_exceededThe organization or connection has used its daily allowance for this kind of request. Allowances reset at 00:00 UTC.Wait for Retry-After seconds, or check remaining allowance in Settings → API connections.
503temporarily_unavailableThe service couldn't complete the request.Retry with exponential backoff. Retry creates with the same key and body.