Check whether a job reference exists

When to use this endpoint

Check an entered job reference against active jobs before saving a job.

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

Parameter	Type	Required	Description
`job_ref`	String	Yes	Matched as supplied using SQL equality; no trimming, length check or exclusion of the job being edited. Blank is accepted.

Example request

$match = FM_api('Job_checkJobRef', ['job_ref' => 'JOB-0042']);

Example response

{"job_ref":"JOB-0042"}

Errors and unusual responses

Response	Condition
`{"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: job_ref"}`	job_ref is absent.
`false`	No active job matches, or the row query fails.

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 one object containing only job_ref, not a boolean or the matching job’s ID. The row helper selects at most one match with no ordering.
Deleted jobs do not reserve a reference for this lookup. Equality follows the database collation; do not assume case-insensitive matching.
This is advisory, not a reservation or uniqueness constraint. It can match the current job and does not prevent concurrent callers from using the same reference.

See it in Fieldmotion

CRM1

Open the job create/edit dialog and change or click the Job Reference input. jobEdit.js calls Job_checkJobRef; a truthy result highlights the input as already in use.

CRM2

No direct CRM2 caller was found in the reviewed source. For batched job fields, see Jobs_getById.

Related endpoints

Jobs_getJobRefNext suggests a reference without reserving it.
Jobs_getById reads selected job records after their IDs are known.