Resolve job types by name · Fieldmotion API

When to use this endpoint

Use JobTypes_listByNames during a mapped import that contains job-type names instead of IDs. Leave createIfNotExists disabled for lookup-only behavior.

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

Parameter	Type	Required	Description
`names`	JSON array of strings	Yes	Names to resolve. This route unconditionally JSON-decodes the value; pass JSON text, not a native array. Exact duplicate strings are removed without trimming or case normalization.
`createIfNotExists`	Integer string	No	When it integer-converts above `0`, creates each unresolved name. There is no administrator check.
`filename`	String	No	For a create operation only, nonblank text is stored in the import-log summary metadata. It does not affect matching.

Example request

$types = FM_api('JobTypes_listByNames', [
	'names' => json_encode(['Emergency repair', 'Inspection']),
	'createIfNotExists' => '1',
	'filename' => 'jobs.csv',
]);

Example response

[
  {"id": "42", "name": "Emergency repair"},
  {"name": "Inspection", "id": 43}
]

Existing database rows normally contain string IDs; newly appended rows contain the insert ID returned by the database layer, commonly a number. Existing matches precede newly created rows.

Errors and unusual responses

Response	Condition
`{"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 parameter: names"}`	The `names` key is absent.
`{"error":"invalid parameter: names"}`	The supplied JSON does not decode to an array.
`{"error":"invalid name string","name":1}`	An array member is not a string; `name` echoes the rejected value.
`Runtime type error`	A native array is supplied where the unconditional JSON decoder expects a string.

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

Behaviour and edge cases

Database name matching is exact SQL equality under the tenant table collation. Archived job types are eligible and are not unarchived.
An empty array still executes the legacy lookup shape and can match an existing blank-name row. There is no ordering, pagination, or limit.
New rows receive current last_edited and metadata containing the generated import ID. Other defaults come from the database schema.

Side effects

When creation is enabled, each missing row is inserted and the job-type cache marker is advanced.
If at least one row is created, one import-log row of type 4 records the create count, current user, timestamp-derived import ID, and optional filename. No field-level audit is written.

See it in Fieldmotion

CRM1

Run an import whose mapped Job Type column is translated by name. The shared import widget calls this route and may enable missing-type creation according to the import configuration.

CRM2

CRM2’s shared import widget performs the same name translation, sending JSON-encoded names, the source filename, and the configured create flag.

Related endpoints

JobTypes_list lists existing active choices without creating data.
JobType_new creates one duplicate-aware named type.