Fieldmotion API Getting started

Suppliers

Retrieve suppliers by ID

POST /a/Suppliers_getById

Fetch selected active supplier rows by ID with an optional allowlisted set of stored fields.

When to use this endpoint

Use Suppliers_getById after another operation has supplied supplier IDs and you need raw stored fields. It does not search, paginate, or calculate display values.

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
idsJSON array or native arrayYesSupplier IDs. Values are integer-converted and deduplicated. Signed external requests should send a JSON array.
fieldsJSON array or native arrayNoStored fields to return. Omission selects all allowed fields. Allowed names are account_number, cdate, contact_name, country, county, edited_uuid, email, id, is_active, last_edited, meta, name, notes, on_hold, phone, postcode, street_address1, street_address2, tax_id, terms, town, type, and website.

Example request

$suppliers = FM_api('Suppliers_getById', [
	'ids' => json_encode(['488104', '488105']),
	'fields' => json_encode(['id', 'name', 'email', 'last_edited']),
]);

Example response

[
  {"id":"488104","name":"Northshore Components","email":"orders@example.test","last_edited":"2026-09-30 11:20:00"}
]

Database scalars are normally serialized as strings. Stored meta remains a JSON-encoded string rather than a decoded object.

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: ids"}ids is absent.
{"error":"no fields selected"}A supplied fields value contains no allowlisted field.
[]No requested ID matches a non-deleted supplier.
Runtime warning or database errorids is malformed JSON or an empty array. The legacy handler does not validate the decoded array before iterating and building its SQL list.

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

Behaviour and edge cases

  • Soft-deleted suppliers are excluded. Inactive and on-hold suppliers are not excluded.
  • Unknown requested fields are silently skipped as long as at least one valid field remains.
  • The response omits unknown IDs and duplicate requested IDs. It does not preserve one response slot per request value.
  • There is no explicit ordering or pagination. Match returned rows by ID and keep batches moderate.

See it in Fieldmotion

CRM1

CRM1’s shared Supplier object cache batches detail reads through Suppliers_getById when supplier records are opened or selected.

CRM2

CRM2 also uses the shared object cache for known supplier IDs; filter developer tools for Suppliers_getById while opening supplier-linked purchasing screens.

Related endpoints