Fieldmotion API Getting started

Asset tables

Import Asset Table rows

POST /a/AssetTable_import

Append Asset Table rows from the version-2 import-widget format.

When to use this endpoint

Use AssetTable_import after mapping spreadsheet columns to configured data.<field-id> destinations. Rows may target one fixed asset or carry an aid column for cross-asset imports.

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
vInteger stringYesImport protocol version. Its value must compare equal to 2.
mapJSON arrayYesNonempty positional mappings. Destinations beginning data. become row JSON keys; exact aid selects the asset from that input column. Other destinations are ignored after a server-log message.
rowsJSON array of arraysYesNonempty source rows corresponding positionally to map. Row widths and value types are not validated.
tidInteger stringYesPositive table ID stored on every inserted row. The definition is not validated.
aidInteger stringConditionallyA positive fixed asset ID. If absent, zero, or invalid, map must contain an aid destination and each row supplies its own ID. References are not checked.

Example request

$result = FM_api('AssetTable_import', [
	'v' => '2',
	'tid' => '1700000000123',
	'aid' => '418',
	'map' => json_encode([
		['to' => 'data.1'],
		['to' => 'data.2'],
	]),
	'rows' => json_encode([
		['8.2', 'passed'],
		['8.0', 'passed'],
	]),
]);

Example response

{
  "ok": 1,
  "errors": []
}

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: v"}v is absent or does not compare equal to 2.
{"error":"missing or invalid parameter: map"}The map key is absent.
{"error":"empty or invalid JSON array: map"}The decoded map is invalid, empty, or not an array.
{"error":"missing or invalid parameter: rows"}The rows key is absent.
{"error":"missing or invalid parameter: aid"}No positive fixed aid is supplied and map has no exact aid destination.
{"error":"empty or invalid JSON array: rows"}The decoded rows value is invalid, empty, or not an array.
{"error":"missing or invalid parameter: tid"}tid is absent or not positive.

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

Behaviour and edge cases

  • When an aid column is mapped, its integer-converted value is used separately for each input row. Unknown and zero IDs are still inserted.
  • Every row receives current server cdate and last_edited values. There is no row-count limit.
  • Failed inserts are collected as strings in errors. The legacy message includes the generated SQL text and may echo imported values; do not expose it to untrusted users.

Side effects

  • Inserts rows and invalidates the Asset Table cache. It writes no import summary, audit entry, or deletion-poll record.

See it in Fieldmotion

CRM1

Open an asset’s Tables tab, choose Import, map configured fields, and inspect AssetTable_import. CRM1 sends one fixed asset ID. The legacy migration tool also imports Classification rows this way.

CRM2

An individual table’s Import button sends a fixed asset ID. The Assets list import can instead send aid=0 with a mapped Asset ID column to distribute rows across assets.

Related endpoints