Fieldmotion API Getting started

Accounts and tax types

Find tax types by name

POST /a/AccountCategories_listByNames

Resolve a batch of exact tax-type names to category IDs during imports.

When to use this endpoint

Use AccountCategories_listByNames when converting imported category-name cells into Fieldmotion category IDs.

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
namesJSON array of stringsYesExact stored names. Every member must be a JSON string; numbers and other values reject the whole request.

Example request

$matches = FM_api('AccountCategories_listByNames', [
	'names' => json_encode(['Standard VAT', 'Zero rated']),
]);

Example response

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

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 parameter is absent.
{"error":"invalid parameter: names"}JSON decoding does not produce an array.
{"error":"invalid name string","name":...}Any array member is not a string; the invalid value is echoed in name.

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, de-duplication, or result placeholder for an unmatched requested name.
  • An empty input array queries for an empty name and normally returns an empty list; it is not rejected.
  • Matching uses SQL equality with the tenant table collation. No trimming or case normalization is performed by the endpoint.

See it in Fieldmotion

CRM1

CRM1’s import widget calls this route when a Tax Type field is configured to translate by name.

CRM2

CRM2’s import widget uses the same translation flow.

Related endpoints