Fieldmotion API Getting started

Accounts and tax types

Create a tax type

POST /a/AccountCategory_new

Create one tax type with a percentage and optional category-group ID.

When to use this endpoint

Use AccountCategory_new for the single-row creation controls in Finance settings. It does not link the new category to an account.

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
nameStringYesTrimmed nonempty name, maximum 64 characters.
tax_rateNumeric-compatibleNoConverted with floatval(); omission or invalid text becomes 0.
group_idInteger-compatibleNoCategory-group ID; defaults to 0. The referenced group is not validated.

Example request

$created = FM_api('AccountCategory_new', [
	'name' => 'Standard VAT',
	'tax_rate' => '20',
	'group_id' => 151003,
]);

Example response

{"ok":1,"id":271006}

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: name"}The name is absent or blank after trimming.
Maximum-length validation errorThe name exceeds 64 characters.

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

Behaviour and edge cases

  • Duplicate names, rates, and group combinations are allowed by both the endpoint and schema.
  • An unknown group ID is stored as-is and can leave the category without a resolvable group name.
  • cdate and last_edited are set to the current Unix timestamp.

Side effects

  • Inserts one tenant account_categories row and clears the category cache.

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. Add a Tax Type row or choose “add new” in Default Tax Settings to call this endpoint.

CRM2

Open Settings → Finance. CRM2 loads the three finance tables and saves them as complete snapshots; filter browser developer tools for the exact function name. The add-tax-type modal calls this endpoint; the page’s ordinary Save uses AccountCategory_updateData.

Related endpoints