Fieldmotion API Getting started

Customers

Set a customer email address

POST /a/Customer_setEmail

Replace one customer primary email address after syntax validation.

When to use this endpoint

Use Customer_setEmail for a focused correction to the primary email address on a known customer.

This setter cannot clear the field. A workflow that intentionally removes an address must use a broader, separately verified customer update contract.

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

ParameterTypeRequiredDescription
idInteger stringYesCustomer to update; it must convert to a positive integer.
valEmail stringYesNew primary address. It is trimmed and must pass PHP email validation. Blank is rejected.

Example request

$result = FM_api('Customer_setEmail', [
	'id' => '1088',
	'val' => 'accounts@example.test',
]);

Example response

{
  "ok": 1
}

An unchanged address returns {"ok":1,"warning":"no change made"}.

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"}id is absent or invalid.
{"error":"missing parameter: val"}val was omitted.
{"error":"invalid parameter: val"}The trimmed value is blank or fails email syntax validation.
{"error":"customer does not exist: 1088"}No customer row exists; the requested ID is appended to the message.

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

Behaviour and edge cases

  • The lookup has no active/deleted filter, so inactive and soft-deleted rows can be changed.
  • The endpoint validates syntax only; it does not prove ownership, deliverability, or uniqueness.
  • Comparison and storage use the trimmed address.
  • This is a single-record mutation; it provides no list filtering or pagination.

Side effects

  • A real change updates email and last_edited, and invalidates the customer cache. This setter does not update edited_uuid.
  • It writes a customer audit-log entry and fires Customer_edit; it sends no email itself.

See it in Fieldmotion

CRM1

The legacy customer edit popup and its invalid-email checker both call Customer_setEmail. Change Email or accept the checker correction, then filter Network requests by the function name.

CRM2

The QuickBooks connection email-check workflow directly calls Customer_setEmail when correcting an invalid customer address and can also mark that customer not to receive invoice emails. Normal CRM2 customer forms use the broader layout update flow.

Related endpoints