Jobs: field and bulk edits
Change a job’s form number
/a/Job_setFormNum
Replace the saved form sequence number without allocating or reserving a new sequence.
When to use this endpoint
Replace the saved form sequence number without allocating or reserving a new sequence.
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 | Integer string | Yes | Converted with intval; range 1 through 999999999. No uniqueness check or automatic next-number selection. |
Example request
$result = FM_api('Job_setFormNum', ['id'=>'1042', 'value'=>'42']);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"} | The converted number is below one. |
{"error":"value too high. max is 999999999"} | The converted number exceeds the upper bound. |
{"error":"job does not exist"} | The active job read fails or finds no row. |
{"ok":1,"warning":"value already set"} | The form number is unchanged. |
{"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. If the integer form_num matches, the response contains a warning and no write occurs.
- This changes form_num, not form_id, form_type, job_ref or answers. Duplicate numbers are possible.
- 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.
- Copies form_num and edit markers to a linked outsourced job in its routed tenant. Mirror failure returns committed success with a warning; its write has no deleted filter.
See it in Fieldmotion
CRM1
No direct CRM1 caller was found in the canonical/legacy route search. This is a focused API setter; other edit flows need not use it.
CRM2
No direct CRM2 caller was found in the canonical/legacy route search. CRM2’s layout-driven updates are a separate contract.
Related endpoints
Jobs_setFormIdchanges the form definition rather than its displayed number.Jobs_getSomereads selected job records before editing and verifies the stored result afterward.