Change a job’s user substatus

When to use this endpoint

Replace the saved positive user-status code without changing the job’s completion state.

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

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.

No extra page, role, assignee, department or client-administrator check is applied by this handler.

Parameter	Type	Required	Description
`id`	Integer string	Yes	Physical job ID in the authenticated account, converted with intval; must be positive.
`user_status`	Integer string	Yes	Converted with intval; must be positive. No configured-status existence or allowed-transition check. Zero cannot clear this field.

$result = FM_api('Job_setUserStatus', ['id'=>'1042', 'user_status'=>'3']);

{"ok":1}

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":"missing or invalid parameter: user_status"}`	user_status is absent or converts to a nonpositive integer.
`{"error":"job does not exist"}`	No row is read, or the read fails.
`{"ok":1,"warning":"already set"}`	The user-status code is unchanged.
`{"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.

Both lookup and UPDATE exclude deleted jobs. Retained deleted rows cannot be changed through this endpoint.
If the converted user_status already matches, returns early with a warning.
Does not change is_complete, run on-complete actions, enqueue Workflow runs, notify users or mirror outsourcing. A changed value records job history with its old/new values.
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.

Writes last_edited and edited_uuid with the changed fields and invalidates the meetings cache.
Records a job history entry for a changed user_status. No-change requests do not write history.

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.

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

Job_getStatus reads the separate completion flag, not user_status.
Jobs_getSome reads selected job records before editing and verifies the stored result afterward.