Fieldmotion API Getting started

Customers

Set a customer work area

POST /a/Customer_setArea

Assign or clear the work-area ID stored on one customer without validating the area record.

When to use this endpoint

Use Customer_setArea after a user selects a work area or an assignment process has calculated one for a known customer.

The endpoint only stores the relationship ID. The caller must establish that the area is valid for the tenant before sending it.

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 an integer of at least 1.
area_idInteger stringNoWork-area ID. Omitted, blank, and non-numeric values convert to 0, which clears the assignment. Negative integers are stored.

Example request

$result = FM_api('Customer_setArea', [
	'id' => '1088',
	'area_id' => '7',
]);

Example response

{
  "ok": 1
}

An unchanged value 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 not a positive integer.
{"error":"customer does not exist"}No customer row with that ID 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 wire parameter is area_id, not val.
  • The customer lookup has no active/deleted filter.
  • A no-change request has no write, cache, logging, or event side effects.
  • This is a single-record mutation; it provides no list filtering or pagination.

Side effects

  • A real change updates area_id, last_edited, and edited_uuid, and invalidates the customer cache.
  • It writes a customer audit-log entry but does not fire Customer_edit.

See it in Fieldmotion

CRM1

The legacy customer edit page saves the Work Area selection through Customer_setArea. The automatic customer-area assignment tool calls the same endpoint; filter Network requests by that function name.

CRM2

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

Related endpoints

  • Customer_get can be used to confirm the stored customer values.
  • Customers_list can locate customers before applying area assignments.