Fieldmotion API Getting started

Customers

Set a customer contact name

POST /a/Customer_setContactName

Replace or clear the primary contact name stored on one customer.

When to use this endpoint

Use Customer_setContactName for a focused primary-contact-name edit on a known customer.

This field is plain text and is distinct from the structured contacts column maintained by Customer_setContacts.

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.
valStringYesNew primary contact name. It is stored exactly as supplied; blank clears it, and whitespace is not trimmed.

Example request

$result = FM_api('Customer_setContactName', [
	'id' => '1088',
	'val' => 'Alex Morgan',
]);

Example response

{
  "ok": 1
}

A value considered equal by the legacy loose comparison returns {"ok":1,"msg":"no change needed"}.

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 or invalid parameter: val"}val was omitted.
{"error":"customer does not exist"}No matching customer row exists.

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.
  • The handler performs no trimming, maximum-length, or content validation.
  • The no-change check uses loose comparison; a request it considers equal returns before the write, log, or event.
  • This is a single-record mutation; it provides no list filtering or pagination.

Side effects

  • A real change updates contact_name, last_edited, and edited_uuid.
  • It writes a customer audit-log entry and fires Customer_edit, but does not explicitly invalidate the customer cache.

See it in Fieldmotion

CRM1

Open the legacy customer edit popup, change Contact Name, and filter Network requests for Customer_setContactName. The value saves immediately.

CRM2

No direct production CRM2 caller was found. CRM2 uses its mapped customer layout update.

Related endpoints