Fieldmotion API Getting started

Assets

List assets by name

POST /a/Assets_listByNames

Resolve exact asset names to IDs and optionally create missing names for an import translation step.

When to use this endpoint

Use Assets_listByNames while translating imported relationship names. Keep createIfNotExists off for a read-only lookup.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler requires login or an established tenant database context and performs no additional Asset-page or role-permission check unless the page says otherwise.

Every query and write uses the authenticated tenant’s tables. CRM1 and CRM2 may hide actions through client-side permissions that these collection routes do not repeat.

Parameters

ParameterTypeRequiredDescription
namesJSON array stringYesExact case/collation-dependent names. Duplicate input strings are removed. Every decoded value must be a string.
createIfNotExistsInteger-compatibleNoWhen greater than zero, inserts a minimal asset for every missing distinct name. Type, owner, whereabouts, and other fields use database defaults.

Example request

$assets = FM_api('Assets_listByNames', [
	'names' => json_encode(['Compressor 4', 'Compressor 8']),
]);

Example response

[
  {"id": "4821", "name": "Compressor 4"}
]

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"}The key is absent.
{"error":"invalid parameter: names"}The JSON does not decode to an array.
{"error":"invalid name string","name":42}Any decoded element is not 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

  • Lookup rows exclude soft-deleted assets but include archived and inactive assets. Multiple existing assets with the same name are all returned.
  • Result order is not defined. Newly inserted rows are appended after database results.

Side effects

  • With createIfNotExists>0, inserts minimal asset rows with current cdate and last_edited. The legacy cache tag says customers, not assets.

See it in Fieldmotion

CRM1

The generic import widget calls this route when a mapped relationship may name an asset.

CRM2

CRM2’s import widget uses the same exact-name translation sequence before sending import rows.

Related endpoints