Fieldmotion API Getting started

Job types

Retrieve job types by ID

POST /a/JobTypes_getById

Fetch selected raw fields for a known batch of job-type IDs, as used by object caches and export rendering.

When to use this endpoint

Use JobTypes_getById after another workflow has supplied job-type IDs and you need a compact ID-to-details lookup. Use JobType_getRequestedDetails when CRM2 mapped field names or field filters are required.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler performs no additional page or role-permission check.

The lookup and any write use the authenticated tenant; an ID from another tenant cannot be addressed through this call.

Parameters

ParameterTypeRequiredDescription
idsJSON array or native arrayYesJob-type IDs. Values are integer-converted and deduplicated; 0 is retained. A scalar JSON value is not promoted to a list.
fieldsJSON array or native arrayNoAny of id, name, last_edited, notes, priority, meta, archived, tax_settings, and department. Omission selects all nine; unknown and duplicate names are discarded.

Example request

$types = FM_api('JobTypes_getById', [
	'ids' => json_encode(['42', '43']),
	'fields' => json_encode(['id', 'name', 'priority']),
]);

Example response

[
  {"id": "42", "name": "Emergency repair", "priority": "4"},
  {"id": "43", "name": "Inspection", "priority": "2"}
]

Numeric database values remain strings. meta and tax_settings remain encoded text rather than decoded objects.

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"}The ids key is absent.
{"error":"no ids in list"}The decoded/native ID array is empty.
{"error":"no fields selected"}fields is present but contains no allowed field.
Runtime warning or type errorids or fields is malformed JSON or decodes to a non-array value.

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

Behaviour and edge cases

  • Missing IDs are silently omitted. There are no null placeholders, archived-row filter, pagination, or endpoint limit.
  • The query defines no ordering; do not assume rows follow the input ID order.
  • nominal_code is deliberately not in this route’s field allowlist even though other job-type endpoints expose it.

See it in Fieldmotion

CRM1

Open a job and select a Job Type to load its defaults, or export data containing job-type values. CRM1 uses this route both through its JobType cache and to resolve export labels.

CRM2

Open Job Details or export data containing job-type values. CRM2’s JobType cache and export widgets request this route, commonly with only id and name.

Related endpoints