Fieldmotion API Getting started

Jobs: lookups and details

Retrieve selected jobs by ID

POST /a/Jobs_getById

Fetch a selected batch of active jobs, optionally projecting only fields required by a consumer.

When to use this endpoint

Fetch a selected batch of active jobs, optionally projecting only fields required by a consumer.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. These calls use the authenticated account’s data; the handler has no additional job-page, department, assignee or client-admin permission check unless stated below.

Parameters

ParameterTypeRequiredDescription
idsNative array or JSON-encoded arrayYesValues are converted to integers; nonpositive values are discarded and positives deduplicated. At least one positive ID must remain. Numeric-looking strings follow intval coercion.
fieldsNative array or JSON-encoded arrayNoWhen supplied, only the allowlisted stored aliases below are selected; unknown values are ignored and duplicates removed. An explicit empty/unknown-only list errors. id is not automatically added.

Example request

$jobs = FM_api('Jobs_getById', ['ids' => json_encode(['1042', '1088']), 'fields' => json_encode(['id', 'job_ref', 'meeting_time', 'is_complete'])]);

Example response

[{"id":"1042","job_ref":"JOB-0042","meeting_time_e":"1791795600","is_complete":"0","meeting_time":"2026-10-12 09:00:00"}]

Errors and unusual responses

ResponseCondition
{"error":"not logged in"}No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
{"error":"missing or invalid parameter: ids"}ids is absent, fails array decoding, or has no positive values; presence is checked before login.
{"error":"missing or invalid parameter: fields"}Explicit fields fails array decoding.
{"error":"no fields selected"}No stored fields remain after filtering the explicit selection.
[]All requested positive IDs are missing or deleted.
false or a runtime warning/failureDatabase queries fail; there is no checked query-error envelope.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

  • Returns a bare list. Missing/deleted IDs are omitted; no request-order guarantee, default sort, paging, cap or placeholder rows are provided.
  • Allowed fields: cdate, contract_id, customer_details, customer_id, customer_type, date_completed, date_completed_e, department_id, due_date, form_id, form_num, form_values, hours, id, is_complete, job_ref, job_ref_customer, last_edited, meeting_time, meeting_time_e, meta, notes, priority, schedule_of_rates, schedule_of_rates2, stock_used, subform_values, type_id, user_id, user_type, user_status.
  • With fields omitted, selects allowed columns found on an existing job plus form_name from the joined form, and derives meeting_time. It is not SELECT * and does not expose every job column. Missing rows still return an empty list.
  • Requesting meeting_time selects meeting_time_e as needed and returns both; the local string uses the account timezone (UTC fallback), or blank for epochs at/below 1000000000. Requesting meeting_time_e alone does not add meeting_time.
  • Requesting type_id adds type_name: blank for zero/null/missing type labels, otherwise the stored job-type name. The type lookup does not filter archived/deleted types.
  • Explicit job_ref_customer selection uses its nonblank physical column, then legacy metadata fallback. In the omitted-fields branch, blank physical values fall back when meta was selected. form_values/subform_values/meta/customer_details/stock_used remain encoded stored JSON, not decoded objects.
  • date_completed_e is the canonical completion epoch; the legacy date_completed datetime is independently available. No customer snapshot repair, invoice lookup or write runs.

See it in Fieldmotion

CRM1

Use multi-job editing, recurring-job details or Bill of Materials. jobsMultiEdit.js and widgetJobsBillOfMaterials.js call Jobs_getById with selected IDs and fields; widgetExport.js also uses it.

CRM2

The shared jobGet batching in header.js sends native ids without fields; multi-edit, exports and Bill of Materials send JSON field projections. Bill of Materials does not request id, demonstrating that it is not automatically included.

Related endpoints