Set a common reference on selected jobs

When to use this endpoint

Assign the same office reference to several jobs and invalidate their linked invoice PDF freshness.

Read the target jobs first with Jobs_getSome to obtain the current values and confirm the IDs belong to the intended account.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Requests address physical job IDs in the authenticated account.

The legacy job-edit restriction bit 128 blocks the request with No permission to edit, including client administrators, matching the restricted focused setters. No additional assignee or department scope is applied.

Parameters

Parameter	Type	Required	Description
`job_ref`	String	Yes	Trimmed nonblank reference up to 47 bytes. The string '0' is accepted. When job-ref-only-numeric=1, the reference must consist only of digits; rejection occurs before batch writes.
`ids`	Native array or JSON-encoded array	Yes	Job IDs converted with intval. Supply a valid list; decoded scalar/malformed JSON and nonscalar list members are rejected. No pagination or automatic chunking.

Example request

$result = FM_api('Jobs_setJobRef', ['job_ref'=>'BATCH-0042', 'ids'=>json_encode(['1042','1088'])]);

Example response

{"errors":[]}

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"}`	The trimmed reference is blank.
`{"error":"parameter too long: job_ref (47)"}`	The trimmed byte length exceeds 47.
`{"error":"missing or invalid parameter: ids"}`	ids is absent or null.
`{"errors":["Job 1088 does not exist"]}`	A requested active job cannot be read, including read failure; other IDs continue.
`{"error":"No permission to edit"}`	The legacy job-edit restriction applies to this authenticated user.
`{"error":"Unable to save job","failedId":1088,"updatedIds":[1042]}`	A primary write failed for failedId. updatedIds contains the earlier successfully written IDs, not a promise of an atomic batch.
`{"error":"Job Ref must be Numeric"}`	The numeric-only setting is enabled and the trimmed reference contains nondigits.

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 an errors list, possibly alongside committed changes, rather than a count or ok flag. Existing reference/byte-length matches are skipped without adding an error.
Each supplied ID is processed in request order; IDs are not deduplicated. Later duplicates normally observe the first change and skip.
All selected jobs receive the same reference: no uniqueness check, suffix allocation or meta.job_ref_reason update occurs.
Does not mirror job references to outsourced counterparts.
Primary writes are checked. A failed write stops the batch with error, failedId and updatedIds (the successfully written prefix). Earlier writes remain committed; re-read the selected jobs before retrying.

Side effects

For changed jobs, advances last_edited/edited_uuid and invalidates the meetings cache.
Writes job_ref and job_ref_len and records job history for each changed job.
Touches active directly/legacy-linked invoices and fires Invoice_edit events. This refreshes PDF edit metadata; it does not create, charge or mail an invoice directly.

See it in Fieldmotion

CRM1

In CRM1 Jobs list select several rows, open the bulk-edit menu and choose Change Job Ref. jobsMultiEdit.js calls Jobs_setJobRef; filter Network for that route.

CRM2

In CRM2 Jobs list select several rows, open the bulk-edit menu and choose Change Job Ref. lib/jobsMultiEdit.js calls Jobs_setJobRef; filter Network for that route.

Related endpoints

Job_setJobRef changes one job and records a manual-reference reason.
Jobs_getSome reads selected job records before editing and verifies the stored result afterward.