Jobs: forms and resources
Set one named job form answer
/a/Job_setField
Save a single named main-form answer, including clearing an image reference.
When to use this endpoint
Use for a focused main-form answer edit, not for job record columns or table cells. The UI uses this route to clear image answers and save child-job references.
Prefer Job_setFields for a normal group of answer edits; that route explicitly rejects a missing active job and supports per-field history.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. The handler performs no additional page or role-permission check.
Job and form IDs refer to the authenticated account. Cross-account writes occur only through the stored outsourcing relationship on the routes that explicitly mirror changes.
The dispatcher also applies account/user and IP restrictions. A CRM session carrying a CSRF token must supply it through X-FMCSRF or _csrf; missing/incorrect tokens can be rejected before this handler runs.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer string | Yes | Positive physical job ID. |
name | String | Yes | Truthy form-answer name, not the field meta ID. Omitted, blank and the string 0 are rejected; whitespace is not trimmed. Unknown names are not rejected. |
value | Form value | Yes | Required by isset, so null is not accepted. Empty string clears the answer. Values are stored without field-type validation. |
Example request
$result = FM_api('Job_setField', ['id'=>'1042', 'name'=>'Site photo', 'value'=>'']);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"} | Job ID is nonpositive. |
{"error":"missing or invalid parameter: value"} | value is missing/null. |
{"error":"cannot set a field if you do not supply a field name"} | name is absent or PHP-falsy. |
{"error":"Unable to save job"} | The primary database save failed. Successful-save history and subsequent follow-ups are not run. |
{"error":"job does not exist"} | The job does not exist or is soft-deleted; no answer or resource write is performed. |
{"ok":1,"warning":"Job saved; follow-up incomplete. Inspect saved state before retrying.","warnings":["Job_updateAssetJobs: job does not exist"],"saved":1} | The primary save succeeded, but a recalculation, asset rebuild, notification or outsourced mirror failed. warnings identifies the failed follow-up; any normal response fields remain present. A benign no-change result from a follow-up is not a failure. Read saved state before retrying. |
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 and merges only the requested named answer; all other answer keys remain unchanged.
- Form definitions are used only to identify asset fields; they are never copied into the answer collection.
- A requested field whose definition has type assets triggers an asset-association refresh using its field name.
- Malformed or scalar stored answer JSON is normalized to an empty collection. There is no filtering, paging, type allowlist or form-name membership enforcement.
Side effects
- Checked active-job UPDATE of form_values, last_edited and edited_uuid; meetings-cache invalidation and generic job history after the save succeeds.
- An asset-link rebuild is conditional on the requested field having type assets. No cost recalculation, image-file deletion or outsourced answer mirror is performed.
See it in Fieldmotion
CRM1
In the job Form page’s image editor, Delete calls Job_setField with value set to an empty string. Watch that route in Network; it clears the reference, not the stored image file.
CRM2
In the job Form, clear an image or create a linked child job. pageJobForm.js sends Job_setField with the field name and either an empty string or child-job ID.
Related endpoints
Job_setFieldsmerges a map of named main-form answers.Job_setFieldImageuploads image bytes into a named main-form answer.Job_setTableCellspatches selected row/field positions while retaining unspecified cells.