Preview customer import normalization

When to use this endpoint

Use Customers_checkData before a customer import when you want to show how Fieldmotion will clean names, countries, telephone numbers, cities, and address lines. Each input row produces one result at the same array position.

This is a preview only. It neither checks whether a customer already exists nor calls a create or update endpoint.

Authentication and permissions

The handler itself does not require a logged-in user, API key, or tenant database context. The common API dispatcher still applies its normal IP restrictions and accepts authenticated requests.

No tenant settings or tenant records are read. Country and telephone normalization use repository data files and the bundled telephone-number library.

Parameters

Parameter	Type	Required	Description
`customers`	JSON array string	Yes	Array of customer-shaped objects. The handler always JSON-decodes this value; a native form array is not accepted. Each non-empty item must be an object/associative array.

Example request

$checked = FM_api('Customers_checkData', [
	'customers' => json_encode([[
		'name' => '  Northwind Cork  ',
		'country' => 'ie',
		'landline' => '00 353 (0)21 555 0100',
		'city' => '  CORK ',
		'street_address_1' => '  14 Harbour Road  ',
	]]),
]);

Example response

[
  {
    "customer": {
      "name": "Northwind Cork",
      "country": "IRL",
      "landline": "+3530215550100",
      "city": "Cork",
      "street_address_1": "14 Harbour Road"
    },
    "corrections": ["name", "country", "landline", "city", "street_address_1"],
    "errors": []
  }
]

customer contains the submitted keys after normalization. corrections contains unique field names changed by the helper, and errors contains unique validation messages.

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: customers"}`	`customers` is absent, malformed JSON, or does not decode to an array.
`Entry-specific <code>errors</code>`	A non-empty row contains a country the normalizer cannot resolve or an international telephone number the telephone library cannot parse.
`Server-side type error`	An element of `customers` is a scalar instead of an object/associative array.

Validation problems are returned inside each row and do not fail the whole batch. Dispatcher-level errors can still use the legacy HTTP 200 response convention.

Behaviour and edge cases

An empty object produces {"customer":[],"corrections":[],"errors":[]}. A non-empty object with no name is given the literal legacy value MISSING NAME and reports a name correction; this is not a required-field error.
Country values are trimmed and uppercased. Known two-letter codes and country names become three-letter codes; NORTHERN IRELAND becomes GBR. Any three-character value is accepted without checking it against the country list.
Telephone normalization strips characters other than digits and +, converts a leading 00 to +, may infer the country from an international number, and may add the country dialling prefix to a national number.
City text is trimmed and title-cased. If the country is blank, a known city can supply a country code.
Address lines are trimmed and internal whitespace is collapsed. Duplicate address/town lines are removed; a lone second address line moves to the first; and a first line containing two or three comma-separated parts may be split across address and town fields.
For GBR, a postcode embedded in county, town, or either street line may be moved into postcode. This legacy branch changes the returned data without adding those changed field names to corrections.
The private transport key _poll is removed. Other unknown keys pass through unchanged. Email addresses and database uniqueness are not validated.
The helper repeatedly applies one correction at a time until the row stabilizes. There is no pagination or batch-size limit.

See it in Fieldmotion

CRM1

Open the CRM1 customer import tool and use Check CSV. Filter Network requests for Customers_checkData; the importer submits adaptive batches and writes the returned corrections and errors into a preview CSV.

CRM2

Open the CRM2 customer import tool and run its CSV check. Filter Network requests for Customers_checkData; CRM2 uses the same batch-preview workflow.

Related endpoints

Customer_new creates one customer after the caller has accepted any previewed corrections.
Customers_listInvalidEmails checks stored customer email values, which this normalizer does not validate.