Fieldmotion API Getting started

Accounts and tax types

Replace an account’s tax types

POST /a/Account_setCategories

Replace the complete set of tax types linked to one account.

When to use this endpoint

Use Account_setCategories when saving CRM1’s multi-select tax-type field for an account. Send the complete desired set, not only additions.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. This legacy handler checks the authenticated user ID directly rather than calling the normal login guard.

All data belongs to the authenticated tenant. No Finance-page, client-admin, role, create, edit, or delete permission is checked by the handler.

Parameters

ParameterTypeRequiredDescription
idInteger-compatibleYesAccount ID. A legacy validation bug accepts 0; use a real positive account ID.
categoriesJSON arrayYesComplete category-ID list. Each member is integer-converted; zero values are skipped. An empty array removes every link.

Example request

$result = FM_api('Account_setCategories', [
	'id' => 331042,
	'categories' => json_encode([271006, 271009]),
]);

Example response

{"ok":1}

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: id"}id is absent or integer-converts below 0. Exact zero is not rejected.
{"error":"missing parameter: categories"}The parameter is absent.
{"error":"parameter must be a JSON-encoded array: categories"}JSON decoding does not produce an array.

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 endpoint does not verify that the account or category IDs exist and does not de-duplicate repeated category IDs.
  • It returns success for an unknown account ID. Because the link table has no foreign keys, invalid IDs can create dangling rows.

Side effects

  • Replaces manymany rows with type_num=1, timestamps new links, and advances the account’s last_edited value.
  • The timestamp change makes the account eligible for the mobile/app incremental finance download.

See it in Fieldmotion

CRM1

Open Settings → Finance. CRM1 loads and edits the Chart of Accounts, Tax Types, and Tax Groups from this endpoint family; filter browser developer tools for the exact function name. Change an account’s Tax Type multi-select to send this endpoint immediately.

CRM2

CRM2 does not call the focused setter; Account_updateData replaces links while Save persists the whole page.

Related endpoints