Fieldmotion API Getting started

Contracts

Import contracts from CSV

POST /a/Contracts_import

Create or overwrite contracts row by row from CRM’s mapped CSV-import payload and record an import-history batch.

When to use this endpoint

Use Contracts_import only through Fieldmotion’s Contracts import widget after the user maps CSV columns.

For controlled integrations, create/update contracts individually so validation failures can be handled per record.

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
mapJSON array stringYesColumn mappings; each item’s to determines the parameter copied from the same row index. The handler does not validate the decoded shape before iterating.
rowsJSON array stringYesCSV rows as arrays. Blank/nonpositive mapped ID creates; a positive ID calls the legacy edit path. There is no documented row limit or transaction.
filenameStringNoNonblank source name added to import-log metadata when the current tenant schema supports it.

Example request

$result = FM_api('Contracts_import', [
	'map' => json_encode([
		['to' => 'id'],
		['to' => 'name'],
		['to' => 'notes'],
		['to' => 'budget'],
		['to' => 'type'],
	]),
	'rows' => json_encode([
		['', 'North Region Service Contract', 'Imported', '25000', 'Planned service'],
	]),
	'filename' => 'contracts.csv',
]);

Example response

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

ids follows input row order and can contain 0 for a failed create. The current implementation never appends to 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: map"}The map key is omitted.
{"error":"missing or invalid parameter: rows"}The rows key is omitted.
Server error/runtime warningEither JSON value is malformed/non-array, a row is shorter than its map, or a map item lacks the expected keys.

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 map targets are id, active, address, budget, cost, date_completed, date_started, expiry, customer_id, name, notes, price_net, profit, tax, and type.
  • Of those, legacy create/edit actually persist name, address, budget, lifecycle dates, expiry, notes, and resolved type. Active, customer, cost, net, profit, and tax are copied but ignored by the called contract handlers. CRM2’s offered Number and Manager columns are not recognized by this switch.
  • Type names are matched exactly against contract types. A missing type name is created through ContractTypes_new before the contract row continues.
  • New rows call Contract_new and then Contract_edit; existing positive IDs call only Contract_edit. The edit route’s replacement and metadata-loss behavior therefore applies.

Side effects

  • Tags successful creates with created_by_import_id and all successful writes with edited_by_import_id, preserving prior metadata where possible.
  • Creates an imports_log entry with type 5, created/edited counts, user, and a time/random import ID. Later import-history deletion can use those metadata tags to soft-delete created rows.
  • The row writes, type creation, metadata tags, and import log are not transactional.

See it in Fieldmotion

CRM1

On Contracts, choose Import, upload a CSV, map fields, and filter Network requests for Contracts_import.

CRM2

The CRM2 Contracts module uses the same import endpoint from its Import action and sends the mapped rows produced by widgetImport.

Related endpoints