Fieldmotion API Getting started

Customer types

List customer types by name

POST /a/CustomerTypes_listByNames

Resolve exact customer-type names to IDs for import and translation workflows.

When to use this endpoint

Use CustomerTypes_listByNames before an import that needs to reuse existing types by name and create only the missing names.

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
namesJSON array stringYesJSON-encoded array of strings. A native array is not supported. Names are matched exactly under the tenant database collation.

Example request

$types = FM_api('CustomerTypes_listByNames', [
	'names' => json_encode(['Commercial', 'Residential']),
]);

Example response

[
  {"id": "12", "name": "Commercial"},
  {"id": "13", "name": "Residential"}
]

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 parameter: names"}The key is absent.
{"error":"invalid parameter: names"}The JSON does not decode to an array.
{"error":"invalid name string","name":...}At least one decoded item is not a string; the response includes that value.

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

Behaviour and edge cases

  • Names not found are omitted. Repeated requested names do not create repeated database rows.
  • Matching case/accent behavior follows the tenant table collation. No explicit ordering or pagination is applied.
  • An empty JSON array generates a legacy name in ("") condition. It can therefore return rows whose stored name is blank, including rows created through permissive mapped routes.

See it in Fieldmotion

CRM1

Customer import translation uses this lookup to map supplied type names before creation.

CRM2

CRM2’s customer import performs the same lookup, then submits missing values through a create endpoint.

Related endpoints