Jobs: field and bulk edits
Replace internal job notes
/a/Job_setInternalNotes
Save the office/internal notes text while leaving the separate job-notes history unchanged.
When to use this endpoint
Save the office/internal notes text while leaving the separate job-notes history unchanged.
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.
No extra page, role, assignee, department or client-administrator check is applied by this handler.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer string | Yes | Physical job ID in the authenticated account, converted with intval; must be positive. |
notes | String | Yes | Required present value; normally plain text. Blank clears internal notes. No trim or length guard is applied; unlike Job_setNotes this is not a JSON note-history list. |
Example request
$result = FM_api('Job_setInternalNotes', ['id'=>'1042', 'notes'=>'Call the office before leaving site.']);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":"invalid or missing parameter: id"} | id is absent or converts to a nonpositive integer. |
{"error":"job does not exist"} | The active lookup fails or has no row. |
{"error":"missing parameter: notes"} | notes was omitted or null. |
{"error":"Unable to save internal notes"} | The primary database write fails. |
{"ok":1,"warning":"notes already set"} | The internal-notes value is unchanged. |
{"ok":1,"warning":"Internal notes saved, but the outsourced copy could not be updated"} | The original save succeeded but the linked-copy write failed. |
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 and updates meta.internal_notes while retaining the source job’s other decoded metadata. Non-array metadata is reset to an empty collection.
- If the internal_notes property already loosely equals notes, returns early with a warning.
- The primary write is checked. A mirror failure is committed success with a warning, not a rollback; do not blindly replay the whole operation.
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.
- Reads the active outsourced counterpart in its routed tenant and changes only that counterpart’s meta.internal_notes, preserving unrelated destination metadata. A failed/missing destination read or failed write returns committed success with a warning.
- No job-notes email-change notification or workflow runs.
See it in Fieldmotion
CRM1
Open Job > Internal Notes and change the text; pageJobInternalNotes.js autosaves with Job_setInternalNotes. Customer Jobs also offers a direct internal-notes edit.
CRM2
Open a job’s Internal Notes page and edit the textarea. pageJobInternalNotes.js sends Job_setInternalNotes on change; inspect the returned warning as well as error.
Related endpoints
Job_getNotesreads the separate job-notes field, not internal notes.Jobs_getSomereads selected job records before editing and verifies the stored result afterward.