Fieldmotion API Getting started

Suppliers

Find suppliers by name

POST /a/Suppliers_listByNames

Resolve an import batch of exact supplier names to supplier IDs.

When to use this endpoint

Use Suppliers_listByNames when an import refers to suppliers by name and needs IDs before importing dependent rows. Retain IDs after the initial match because names are not unique.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler calls the normal login guard but performs no additional Suppliers-page, stock, purchasing, role, create, edit, or delete permission check.

All records are selected from the authenticated tenant. CRM1 and CRM2 hide some controls through client-side permissions, but these endpoints do not repeat those UI checks.

Parameters

ParameterTypeRequiredDescription
namesJSON array of stringsYesComplete supplier names. Unlike similar customer helpers, this route always JSON-decodes the value; send a JSON string rather than a native request array.

Example request

$suppliers = FM_api('Suppliers_listByNames', [
	'names' => json_encode(['Northshore Components', 'Harbour Parts']),
]);

Example response

[
  {"id":"488104","name":"Northshore Components"},
  {"id":"488105","name":"Harbour Parts"}
]

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"}names is absent.
{"error":"invalid parameter: names"}The JSON value does not decode to an array.
{"error":"invalid name string","name":...}Any decoded element is not a string; the response includes that value.
[]No stored supplier name matches.

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

Behaviour and edge cases

  • Database matching uses exact SQL IN values and the tenant database collation, normally case-insensitive. There is no substring search or input trimming.
  • Duplicate stored supplier names can produce multiple rows. The endpoint does not create missing suppliers.
  • The database does not promise request order. Match response entries by both name and, where possible, a previously known ID.
  • There is no pagination or explicit batch-size limit; keep name arrays moderate.

See it in Fieldmotion

CRM1

The spreadsheet import dependency resolver calls Suppliers_listByNames for distinct supplier names found in imported rows.

CRM2

CRM2’s equivalent import widget uses the same dependency lookup endpoint.

Related endpoints