Import supplier rows · Fieldmotion API

When to use this endpoint

Use Suppliers_import for the CRM spreadsheet import workflow. It accepts a column map and a whole batch of row arrays; it is not a substitute for validated single-record create/update calls.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler calls the normal login guard but performs no additional Suppliers-page, stock, purchasing, role, create, edit, or delete permission check.

All records are selected from the authenticated tenant. CRM1 and CRM2 hide some controls through client-side permissions, but these endpoints do not repeat those UI checks.

Parameters

Parameter	Type	Required	Description
`v`	Integer string	Yes	Import format version. It must be `2` or greater.
`map`	JSON array	Yes	Column descriptors. Each position may contain a `to` name; at least one must map to `name`.
`rows`	JSON array of arrays	Yes	Data rows using the map’s column positions. Values are trimmed.
`filename`	String	No	Nonblank source filename saved in import-log metadata.

Example request

$result = FM_api('Suppliers_import', [
	'v' => '2',
	'map' => json_encode([
		['from' => 'ID', 'to' => 'id'],
		['from' => 'Name', 'to' => 'name'],
		['from' => 'Email', 'to' => 'email'],
		['from' => 'Country', 'to' => 'country'],
	]),
	'rows' => json_encode([['', 'Northshore Components', 'orders@example.test', 'Ireland']]),
	'filename' => 'suppliers.csv',
]);

Example response

{"ok":1,"inserts":1,"updates":0}

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 or invalid parameter: v"}`	`v` is absent or below 2.
`{"error":"missing or invalid parameter: map"}`	`map` is absent or does not decode to an array.
`{"error":"missing or invalid parameter: rows"}`	`rows` is absent or does not decode to an array.
`{"error":"The import map is missing the \"name\" field."}`	No map entry targets `name`.
`Success with an errors array`	One or more positive IDs do not exist. Other rows continue and the response lists those update failures.

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

Behaviour and edge cases

Recognized targets are id, name, account_number, contact_name, phone, email, website, tax_id, notes, address fields, region, country, postcode, accounts_email, and accounts_contact. Unknown targets are ignored.
A row with a blank mapped name is silently skipped and is not counted as an error.
A positive ID updates any matching supplier, including a soft-deleted one, and does not restore it. A zero/blank ID inserts a new supplier.
All ordinary mapped columns are replaced with the row value, including blank values. Blank accounting email/contact values do not clear existing metadata keys.
county uses the mapped county when nonblank, otherwise mapped region. Country is written only for a three-character value or a recognized country name; an invalid nonblank country is omitted, preserving the existing value during updates.
Every accepted update advances last_edited. Inserts also set creation time. Email formats and field lengths are not validated here.

Side effects

A unique import ID is written into supplier metadata as created_by_import_id or edited_by_import_id.
One imports_log row of supplier import type 10 is written even when every row is skipped or rejected; it records counts, user ID, and optional filename.
Writes invalidate the supplier cache but do not fire Supplier_new/Supplier_edit.

See it in Fieldmotion

CRM1

Open Stock → Suppliers and start the spreadsheet import. The import widget submits mapped row batches to Suppliers_import.

CRM2

CRM2’s Supplier import flow calls the same endpoint with version 2 maps and row batches.

Related endpoints

Supplier_createData is the validated mapped single-create route.
Supplier_updateData updates one supplier with field validation and events.