Fieldmotion API Getting started

Accounts and tax types

Find one tax type by nominal code

POST /a/AccountCategory_getByNominal

Resolve an account code to its linked tax type with the highest stored rate.

When to use this endpoint

Use AccountCategory_getByNominal only when a legacy workflow explicitly wants one category rather than the full allowed list.

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 Finance-page, client-admin, role, create, edit, or delete permission check.

All reads and writes use the authenticated tenant. CRM1 and CRM2 decide whether to show finance controls, but these handlers do not repeat those client-side checks.

Parameters

ParameterTypeRequiredDescription
nominalStringYesTrimmed nonempty nominal code. The trimmed value is used for lookup.

Example request

$category = FM_api('AccountCategory_getByNominal', [
	'nominal' => '4000',
]);

Example response

{"id":"271006","name":"Standard VAT","tax_rate":"20","category_group_id":"151003"}

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: nominal"}The nominal code is absent or blank.
{"error":"account does not exist"}No account has the code.
[]The account has no linked category IDs. This differs from the object returned on success.

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

Behaviour and edge cases

  • Among linked categories, the query orders by tax_rate DESC and returns one row. It does not represent an account’s complete allowed tax list.
  • Equal-rate ties have no secondary ordering, so the selected row is not deterministic.
  • If link rows exist but all category targets are missing, the final row lookup returns false.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found. Current CRM1 editors use Account_listCategories or Account_getTaxRates.

CRM2

No direct CRM2 caller was found. Current CRM2 editors also use the full linked-category list.

Related endpoints