Fieldmotion API Getting started

Customers

Retrieve customer metadata

POST /a/Customer_getMeta

Retrieve one customer name and its raw encoded metadata value.

When to use this endpoint

Use Customer_getMeta when a workflow needs metadata such as customer-specific invoice discount settings without retrieving the full record.

The meta field remains JSON text. Decode it in the caller and tolerate both object-like and legacy array-like values.

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 read; it must convert to a positive integer.

Example request

$customer = FM_api('Customer_getMeta', [
	'id' => '1088',
]);
$meta = json_decode($customer['meta'], true);

Example response

{
  "name": "Northwind Service Centre",
  "meta": "{\"discount\":\"5\"}"
}

When non-null, meta is a JSON-encoded string, not a decoded nested object. Empty legacy metadata may be "[]", while a database null is returned as JSON null.

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":"customer does not exist"}No matching 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 does not filter inactive or soft-deleted customers.
  • No individual metadata keys are selected or decoded server-side.
  • This is a single-record lookup with no filtering or pagination.

See it in Fieldmotion

CRM1

Open a job invoice that has a normal customer. CRM1 calls Customer_getMeta to offer the configured customer discount; the Customers page also uses it in a customer-related action. Filter Network requests by the function name.

CRM2

Open a job invoice in CRM2. Its invoice editor calls Customer_getMeta for the same customer-discount action; the Customers page also reads it.

Related endpoints