Set customer notes · Fieldmotion API

When to use this endpoint

Use Customer_setNotes only when the caller intends to replace the entire stored notes value for a known customer.

CRM1 treats this field as encoded note data in some screens, but the endpoint does not parse or merge it. Read and preserve existing content before appending an entry.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler performs no additional page or role-permission check.

The lookup and any write use the authenticated tenant; an ID from another tenant cannot be addressed through this call.

Parameters

Parameter	Type	Required	Description
`id`	Integer string	Yes	Customer ID; it must convert to a positive integer.
`val`	String	No	Preferred complete replacement value. If present, it takes precedence over `value`, even when blank.
`value`	String	No	Legacy alias used only when `val` is absent. If both parameters are omitted, the endpoint clears notes.

Example request

$result = FM_api('Customer_setNotes', [
	'id' => '1088',
	'val' => json_encode([
		['date' => '2026-09-24', 'note' => 'Gate code confirmed'],
	]),
]);

Example response

{
  "ok": 1
}

The same response is returned for a nonexistent ID and for an unchanged value.

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 invalid. Neither notes parameter is required.

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

Behaviour and edge cases

Omission clears and success is not confirmation. If both val and value are absent, an empty string is written. The handler also does not verify that the customer exists or that a row changed.

The endpoint performs no JSON validation, merge, length check, existence lookup, active/deleted filter, or no-change detection.
When both aliases are supplied, val wins.
Retrying an identical replacement still advances last_edited and emits the audit/event side effects.
This is a single-record mutation; it provides no list filtering or pagination.

Side effects

The update attempts to set notes, last_edited, and edited_uuid, and invalidates the customer cache.
It writes a customer audit-log entry and fires Customer_edit, even when the ID matches no row.

See it in Fieldmotion

CRM1

The legacy customer edit popup reads its JSON note list, appends an item, then sends the complete encoded value as val. The Job screen Customer Notes widget calls the same endpoint with value. Filter Network requests for Customer_setNotes.

CRM2

No direct production CRM2 caller was found. CRM2 customer forms use their layout-driven update contract.

Related endpoints

Customer_get reads the current value before a safe read-modify-write sequence.
Customers_getById can retrieve selected fields for known customers.