Fieldmotion API Getting started

Job types

Set a job type’s tax settings

POST /a/JobType_setTaxSettings

Replace the JSON tax and nominal defaults used for job line-item categories of this type.

When to use this endpoint

Use JobType_setTaxSettings from either Job Types settings screen when saving per-type finance defaults.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler performs no additional page or role-permission check.

The lookup and any write use the authenticated tenant; an ID from another tenant cannot be addressed through this call.

Parameters

ParameterTypeRequiredDescription
idInteger stringYesExisting positive job-type ID.
valueJSON-compatible valueYesComplete replacement value. The handler always JSON-encodes it. CRM sends an object with stock_*, labour_*, mileage_*, rates_*, and misc_* nominal, tax-type, and tax-rate keys.

Example request

$result = FM_api('JobType_setTaxSettings', [
	'id' => '42',
	'value' => [
		'misc_nominal' => '4000',
		'misc_taxtype' => 'Standard',
		'misc_taxrate' => '20',
	],
]);

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"}The ID integer-converts below one.
{"error":"missing or invalid parameter: value"}The value key is absent or null.
{"error":"job type does not exist"}No type matches the ID.

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 validates neither the keys nor referenced nominal/tax choices. Unknown and partial objects are accepted.
  • Comparison is against the newly encoded text; identical encoded data is a no-op.
  • The settings can override general finance defaults for applicable job line items. Existing invoice rows are not rewritten.

Side effects

  • On change, replaces tax_settings, updates last_edited, and advances the job-type cache marker.
  • This focused setter writes no generic field-level audit entry.

See it in Fieldmotion

CRM1

Open Settings → Job Types, choose View under Tax Settings, and change a nominal or tax type. CRM1 calls this route after each change.

CRM2

Open Settings → Job Types and edit Tax Settings. CRM2 builds the complete value and calls this route directly.

Related endpoints