Fieldmotion API Getting started

Forms

Find forms by exact names

POST /a/Forms_listByNames

Resolve exact form names to local IDs for import translation and other name-based matching.

When to use this endpoint

Use this when incoming data contains form names rather than IDs. Do not use it for fuzzy search; Forms_searchByName performs substring matching.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session and is scoped to the authenticated tenant.

The handler performs no form, department, owner, or page-permission check unless the page below says otherwise. CRM navigation may impose additional UI-only access rules.

Parameters

ParameterTypeRequiredDescription
namesJSON array stringYesJSON array whose elements must all be strings. Native arrays are not supported. An empty array is accepted and normally returns no rows.

Example request

$forms = FM_api('Forms_listByNames', [
	'names' => json_encode(['Service visit', 'Installation']),
]);

Example response

[{"id":"1048","name":"Installation"},{"id":"1042","name":"Service visit"}]

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 parameter: names"}Names are absent.
{"error":"invalid parameter: names"}The value does not decode to an array.
{"error":"invalid name string","name":1}An array element is not a string; the invalid value is echoed.

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

Behaviour and edge cases

  • Matching is exact under the tenant database collation. Missing names are omitted and duplicate database names can return multiple rows.
  • Archived forms and every form type are eligible.
  • Rows are ordered by stored name, not by request order.

See it in Fieldmotion

CRM1

The Jobs import widget uses this endpoint when translating a Form-name column.

CRM2

The import widget uses the same translation step.

Related endpoints