Fieldmotion API Getting started

Job types

Create a job type

POST /a/JobType_new

Create a single named job type for CRM1, reusing an existing exact-name row instead of inserting a duplicate.

When to use this endpoint

Use JobType_new for CRM1’s create dialog or its inline “Add Type” action in the job editor. CRM2’s configurable create form uses JobType_createData.

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
nameStringYesName after trimming leading/trailing whitespace. It must be nonblank. Existing names are matched exactly under the tenant database collation.
priorityInteger stringNoInitial priority. It is written only when integer conversion is nonzero; omitted, zero, or nonnumeric input leaves the nullable database default. The tenant priority choices are not checked.

Example request

$created = FM_api('JobType_new', [
	'name' => 'Emergency repair',
	'priority' => '4',
]);

Example response

{
  "ok": 1,
  "id": 42,
  "name": "Emergency repair"
}

When the trimmed name already exists, the response is {"id":"42","warning":"that type already exists"}; ok and name are omitted and no row changes.

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 key is absent.
{"error":"no name entered"}The trimmed name is empty, including input "0" under PHP truthiness.

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 matching follows the tenant table collation. The first matching ID is returned if duplicate rows already exist.
  • Only name, optional nonzero priority, and current last_edited are written. Other defaults remain null/database defaults.
  • There is no filtering or pagination.

Side effects

  • On insert, creates one tenant row and advances the job-type cache marker.
  • This legacy route does not write the generic field-level audit entries used by JobType_createData, and it does not change jobs.

See it in Fieldmotion

CRM1

Open Settings → Job Types and choose Create, or select “Add Type” while editing a job. Both actions call this endpoint.

CRM2

No direct production CRM2 caller was found; CRM2’s Job Types module derives JobType_createData instead.

Related endpoints