Jobs: field and bulk edits
Change one job reference
/a/Job_setJobRef
Replace the office job reference and invalidate linked invoice PDF freshness.
When to use this endpoint
Replace the office job reference and invalidate linked invoice PDF freshness.
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 | Yes | Trimmed reference, at most 47 bytes. Blank and the string '0' are rejected. When job-ref-only-numeric=1, a changed reference must consist only of digits. |
Example request
$result = FM_api('Job_setJobRef', ['id'=>'1042', 'value'=>'JOB-0042']);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":"missing or invalid parameter: value"} | Trimmed input is falsey, including '0'. |
{"error":"value too long. max length 47"} | The trimmed byte length exceeds 47. |
{"error":"Job Ref must be Numeric"} | A changed value violates the enabled numeric-only setting. |
{"error":"job does not exist"} | The active lookup fails or has no row. |
{"ok":1,"warning":"value already set"} | Both saved reference and length already match. |
{"error":"Unable to save job"} | The primary database write failed. History and dependent effects are not performed for that failed save. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Reads an active job; compares both job_ref and stored byte length. A matching pair returns early before numeric-only validation.
- Stores the trimmed reference, its byte length and meta.job_ref_reason. Malformed/non-array metadata is normalized to an empty collection.
- No uniqueness check or number reservation occurs. The UI may impose extra formatting rules that are not enforced here.
- The job reference deliberately does not propagate to outsourced copies.
- 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 invoices linked directly or through the legacy pointer, updates their Unix last_edited/edited_uuid, and fires Invoice_edit events. No invoice is created, billed or mailed; downstream event handling may do additional configured work.
See it in Fieldmotion
CRM1
On Jobs list click the Job Ref cell and edit it; pageJobs.js sends Job_setJobRef. The legacy full editor also calls it through Job_save. The inline UI additionally rejects numbers followed by nondigit text.
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_checkJobRefchecks whether a reference is already in use without reserving it.Jobs_setJobRefupdates a selected batch with the same numeric-only setting.Jobs_getSomereads selected job records before editing and verifies the stored result afterward.