Change a customer’s job reference

When to use this endpoint

Save or clear the customer-provided reference and repair legacy split reference storage.

Read the target job 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. The request uses the authenticated account’s job IDs, not mobile app IDs.

The legacy userdata.permissions bit 128 blocks editing with No permission to edit; this handler does not exempt client administrators from that bit. It does not add an assignee/department scope.

Parameters

Parameter	Type	Required	Description
`id`	Integer string	Yes	Physical job ID in the authenticated account, converted with intval; must be positive.
`value`	String	No	Trimmed reference up to 50 bytes. Omitted input defaults to blank, so omission also clears the field; no numeric-only or uniqueness rule applies.

Example request

$result = FM_api('Job_setJobRefCustomer', ['id'=>'1042', 'value'=>'PO-7832']);

Example response

{"ok":1}

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: id"}`	id is absent or converts to a nonpositive integer.
`{"error":"No permission to edit"}`	The legacy edit restriction bit is set.
`{"error":"value too long. max length 50 characters"}`	The trimmed byte length exceeds 50, despite the legacy error saying characters.
`{"error":"job does not exist"}`	No active job is read, or its query fails.
`{"ok":1,"warning":"value already set"}`	Metadata, top-level reference and length all match.
`{"error":"Unable to save job"}`	The primary database write failed. History and dependent effects are not performed for that failed save.
`{"ok":1,"warning":"Job saved, but the outsourced copy could not be updated"}`	The local save committed but an outsourced read/write failed. Do not repeat the local mutation blindly.

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

Behaviour and edge cases

Requires an active job. Updates meta.job_ref_customer, the top-level job_ref_customer column and its byte-length column together.
No-change detection requires all three representations to match. If visible metadata already matches but the columns are stale, the call repairs them instead of returning early.
This is not the office job_ref and does not allocate a number.
The primary UPDATE is checked before history and dependent effects. There is no transaction combining this field write with later cross-object effects; inspect committed-success warnings before retrying.

Side effects

Writes last_edited and edited_uuid with the changed fields and invalidates the meetings cache.
Records a job history entry. No mail is sent directly by this setter.
Touches active directly/legacy-linked invoices and fires Invoice_edit to invalidate PDF freshness.
Mirrors the customer reference and byte length to the outsourced counterpart while merging that counterpart’s metadata. Destination read/write failures return committed success with a warning; its writes lack an active-row filter.

See it in Fieldmotion

CRM1

On Jobs list edit the customer-reference part of the Job Ref cell. pageJobs.js sends Job_setJobRefCustomer with value; reload to inspect the repaired canonical fields.

CRM2

No direct CRM2 caller was found in the canonical/legacy route search. CRM2’s layout-driven updates are a separate contract.

Related endpoints

Job_setJobRef changes the job’s own reference instead.
Jobs_getSome reads selected job records before editing and verifies the stored result afterward.