Fieldmotion API Getting started

Asset types

Import asset types

POST /a/AssetTypes_import

Create or update asset types from the current versioned import-widget row format.

When to use this endpoint

Use AssetTypes_import through the Asset Types import widget after mapping spreadsheet columns to Asset Type ID, name, Vehicle, or QR URL.

The route accepts a complete batch in one request and writes an import-log summary after processing every row.

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. Must integer-convert to 2 or higher.
mapJSON arrayYesColumn mappings such as [{"to":"id"},{"to":"name"},{"to":"url"},{"to":"vehicle"}]. Only those four destinations are recognized; others are ignored.
rowsJSON array of arraysYesInput rows whose positional values correspond to map. JSON structure and row widths are not validated before iteration.
filenameStringNoWhen nonblank, stored as import-log metadata for the source filename. It does not affect matching or row processing.

Example request

$result = FM_api('AssetTypes_import', [
	'v' => '2',
	'map' => json_encode([
		['to' => 'id'],
		['to' => 'name'],
		['to' => 'vehicle'],
		['to' => 'url'],
	]),
	'rows' => json_encode([
		['', 'Mobile Compressor', 'Yes', 'https://example.test/assets'],
	]),
	'filename' => 'asset-types.csv',
]);

Example response

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

errors contains pairs of [zeroBasedRowIndex, message] only for inserts the database reports as failed. Successful creates/updates and matched IDs are not returned.

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 less than 2.
{"error":"missing or invalid parameter: map"}The map key is absent.
{"error":"missing or invalid parameter: rows"}The rows key is absent.
Runtime warnings with a nominal success responsemap/rows is malformed JSON or rows do not contain mapped positions; decoded shapes are not validated.

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

Behaviour and edge cases

  • A positive mapped ID is the first identity choice. Without one, a nonblank mapped name is used to find an existing row. If neither resolves a row, a new type is inserted.
  • The mapped ID is never inserted as the new primary key. An unknown positive ID falls back to creating a new auto-numbered row using any other mapped values.
  • Database failures while updating matched rows are not checked or added to errors; only failed inserts are reported there.
  • Only exact Yes and No change attrs to 2 and 0. Other Vehicle values leave an existing mask unchanged or use the new row’s default.
  • Blank names can be inserted. Duplicate names can arise when no row is matched by the supplied identity. There is no paging or row-count limit.

Side effects

  • Creates and updates asset types row by row, refreshes each processed row’s last_edited, and invalidates the type cache.
  • Writes one imports_log summary with import type 3, current user, create/edit counts, and optional filename metadata. No generic per-field audit is written.

See it in Fieldmotion

CRM1

Open Assets → Setup Asset Types, choose Import Types, map columns, and run the import while filtering Network requests for AssetTypes_import.

CRM2

Open Asset Types, choose Import, map the same four fields, and inspect AssetTypes_import. Both clients send v=2 through the shared widget.

Related endpoints