Fieldmotion API Getting started

Accounts and tax types

Create a nominal account

POST /a/Account_new

Create one nominal account from the CRM1 Chart of Accounts editor.

When to use this endpoint

Use Account_new for the CRM1 single-row creation flow. CRM2 creates accounts through the full snapshot endpoint instead.

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
nominal_codeStringYesTrimmed nonempty account code, maximum 10 characters. It must not exactly match an existing code.
account_nameStringNoTrimmed account name, maximum 128 characters. Omission stores an empty name and display name.

Example request

$created = FM_api('Account_new', [
	'nominal_code' => '4000',
	'account_name' => 'Sales',
]);

Example response

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

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_code"}The code is absent or blank after trimming.
{"error":"parameter too long: nominal_code. max length 10 characters"}The code exceeds its maximum length.
{"error":"parameter too long: account_name. max length 128 characters"}The optional name exceeds its maximum length.
{"error":"duplicate nominal code"}An account already has the exact code.

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

Behaviour and edge cases

  • No tax types are linked and the new row is not made the default account.
  • name and display_name receive the same value. cdate and last_edited receive the current Unix timestamp.
  • The schema does not enforce code uniqueness; this endpoint performs its own pre-insert check.

Side effects

  • Inserts one row into the tenant accounts table and clears its account 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. Enter a code in the blank Chart of Accounts row to send Account_new.

CRM2

CRM2 does not call this endpoint. Its Save action submits new rows with accountID=0 to Account_updateData.

Related endpoints