Fieldmotion API Getting started

Jobs: reports, email and links

Notify recipients of a job notes change

POST /a/Job_emailChangeNotes

Queue the configured job-notes notification after notes have already been saved.

When to use this endpoint

Use after a notes save, not as a notes editor. Job_setNotes calls this helper and converts a failed notification into a committed-save warning.

Authentication and permissions

Signed API-key authentication or a logged-in CRM session is required. The handler uses the authenticated tenant and has no additional role/page check.

The dispatcher also applies user/account and IP restrictions. CRM sessions carrying a CSRF token must supply X-FMCSRF or _csrf; missing or incorrect tokens can be rejected before the handler runs.

Parameters

ParameterTypeRequiredDescription
idInteger stringYesPositive active job ID.
newNotesStringYesPresence is required, including an empty string. The value is read but not incorporated into the helper’s message; templates render saved job state.

Example request

$result = FM_api('Job_emailChangeNotes', [
	'id' => '1042',
	'newNotes' => 'Access via the side gate.',
]);

Example response

{"ok":1}

Errors and unusual responses

ResponseCondition
{"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"}Missing/nonpositive id.
{"error":"missing parameter: newNotes"}newNotes is absent.
{"error":"Job not found!"}Job is missing/deleted.
{"error":"No valid Email"}Enabled notification has no recipient entries; this is an entry count, not address validation.
{"error":"Unable to queue job notes notification"}A mail reply failed the helper’s ok check or the call threw. Earlier recipients may already have been queued.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

  • Only enabled notification_types.job_on_change_notes sends. Disabled/missing configuration returns ok without mail.
  • Selects the configured template, then form-based default and the first numerically matching positive form-ID override.
  • Recipient switches are email_customer, email_user and email_creator; asset customer mail uses its owner. email_other is split on commas and trimmed. Entries are not deduplicated or syntax-validated; empty addresses may reach the mail service.
  • The body is the configured text only, not newNotes. It uses type-2 mail with job_on_change_notes source metadata.
  • No filtering/pagination or recipient cap applies. It does not check the job’s completion status or save notes.

Side effects

  • Attempts mail per recipient. It changes no job row, timestamp or history itself; the enclosing notes setter has already saved/audited the notes.

See it in Fieldmotion

CRM1

Edit job notes. Network shows Job_setNotes; its PHP follow-up invokes this helper and can return saved=1 with a notification warning.

CRM2

No direct caller was found. This is the legacy notes-setter follow-up, not a guarantee that every mapped notes change sends mail.

Related endpoints