Fieldmotion API Getting started

Saved views and configuration

Create a configurable picklist choice

POST /a/CommonList_createData

Add a named tenant picklist option with an automatically allocated business value.

When to use this endpoint

Use when a settings screen needs another contact type, job sub-status or other CommonList choice. Keep both returned identifiers: id is the storage row, while value is the ID used by business records and pickers.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. The handler requires login, without an additional list-management/page/role permission check. Lists belong to the authenticated tenant, not an individual user.

Parameters

ParameterTypeRequiredDescription
typeStringYesList namespace, for example contactType, jobIncompleteSubStatus, purchaseStatus or contractStages. It must be nonempty but is not allowlisted.
nameStringYesNonempty display label. No handler maximum is configured; the representative tenant column is varchar(100).
valueInteger stringIgnoredAlways overwritten with max(value) for this type plus 1, with a minimum new value of 10001.
requiredInteger stringNoDefaults to the schema default 0 when omitted. Supplying 1 makes the option protected from normal deletion; the map does not enforce a boolean range.
meta / metaColor / metaOrgNameJSON value / stringsNometa accepts native structures or encoded JSON text; color/orgName aliases set those keys. Aliases are applied after the root meta value.
cdate / lastEditedUnix seconds or datetime stringsNoCreation defaults to current Unix seconds; last-edited is supplied automatically unless explicitly provided. The map’s readonly/hidden layout flags do not enforce write protection.

Example request

$choice = FM_api('CommonList_createData', ['type' => 'contactType', 'name' => 'Site contact']);

Example response

{"ok":1,"id":1042,"value":10001}

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":"invalid parameter: type"}Type not supplied at all.
{"error":"missing or invalid parameter: type"}Type supplied blank; missing/blank name has the corresponding name error.
{"error":"Unable to create record"}Insert fails, including schema/JSON errors.

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 next value calculation includes all rows of the requested type, and reserves values up to 10000 for built-in choices. Values can repeat in different types; always retain the type alongside a business choice ID.
  • Allocation uses an unlocked maximum query; concurrent creates can assign the same value. Names/values are not deduplicated or protected by a unique constraint in the representative schema.
  • Only mapped keys are stored. Hidden/readonly are UI hints, not permission checks; required and timestamps can be supplied explicitly.
  • The API does not rewrite existing customers/jobs or set a default choice. No feature flag changes the allocation rule.

Side effects

  • Inserts the list row, supplies creation/last-edited Unix timestamps, requests the common_lists cache marker and adds generic field-creation history.
  • The mobile intermediary downloads contactType and jobIncompleteSubStatus rows incrementally by last_edited, with a short server safety delay. No notification/email is sent.

See it in Fieldmotion

CRM1

No direct CRM1 caller to this CommonList route was found in the source search. CRM2 uses these generic list endpoints for configurable customer contact types, job sub-statuses, purchase statuses and contract stages.

CRM2

Open CRM2 customer settings → Contact Types. pageSettingsContactTypes.js uses CommonList/CommonLists widget prefixes and shared create/detail/edit helpers. Filter the Network panel for this endpoint. Choose Create and enter a name; the screen sends type=contactType and relies on the generated value.

Related endpoints