Fieldmotion API Getting started

Accounts and tax types

Retrieve tax types by ID

POST /a/AccountCategories_getById

Fetch selected tax types by ID for export value translation.

When to use this endpoint

Use AccountCategories_getById after another endpoint returns category IDs and an export or integration needs their names or rates.

Authentication and permissions

The request must establish an authenticated tenant context with signed API credentials or a logged-in CRM session. This legacy handler checks for the tenant database prefix rather than calling the normal login guard.

It performs no additional Finance-page, client-admin, role, create, edit, or delete permission check.

Parameters

ParameterTypeRequiredDescription
idsJSON array or native arrayYesCategory IDs. Values are integer-converted and de-duplicated; missing IDs are omitted from the result.
fieldsJSON arrayNoSubset of id, name, and tax_rate. Omission returns all three. Unknown names are ignored; at least one valid field must remain.

Example request

$categories = FM_api('AccountCategories_getById', [
	'ids' => json_encode([271006, 271009]),
	'fields' => json_encode(['id', 'name', 'tax_rate']),
]);

Example response

[
  {"id":"271006","name":"Standard VAT","tax_rate":"20"},
  {"id":"271009","name":"Zero rated","tax_rate":"0"}
]

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"}The parameter is absent.
{"error":"no ids in list"}No IDs remain after decoding/conversion. Malformed JSON can also reach this response after a runtime warning.
{"error":"no fields selected"}fields contains no valid field names.
Runtime/type errorA native array is supplied as fields; this legacy handler always JSON-decodes that parameter.

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 query has no explicit ordering; response order is not guaranteed to match ids.
  • Unknown or deleted IDs are silently omitted rather than represented with null placeholders.
  • There is no maximum batch size or pagination.

See it in Fieldmotion

CRM1

CRM1’s export widget calls this route when translating stored tax-code or tax-rate IDs to names/rates before generating CSV.

CRM2

CRM2’s export widgets use the same translation flow for tax-code and tax-rate fields.

Related endpoints