Resolve customers by name

When to use this endpoint

Customers_listByNames supports spreadsheet imports whose rows refer to customers by name rather than Fieldmotion ID. Submit all distinct names in one call, build a name-to-ID map from the response, then continue importing the dependent jobs, assets, or other records.

For normal integrations, prefer maintaining Fieldmotion IDs after an initial match. Names are not guaranteed unique. Use Customers_search when you need pagination or additional filters, and use Customer_new for deliberate customer creation with validation and events.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler requires login after validating the names shape and performs no additional page or role-permission check.

Matching and optional creation occur only in the authenticated tenant. Soft-deleted customers are not matched; inactive customers are matched.

Parameters

Example request

$customers = FM_api('Customers_listByNames', [
	'names' => json_encode([
		'Northwind Service Centre',
		'Northwind Cork',
	]),
]);

Example response

[
  {
    "id": "1042",
    "name": "Northwind Service Centre"
  },
  {
    "id": "1088",
    "name": "Northwind Cork"
  }
]

Existing database IDs are normally JSON strings. IDs appended for newly inserted records can be JSON numbers. Match response entries by name; the query does not promise request order.

Errors and unusual responses

Behaviour and edge cases

• Name matching is case-insensitive, exact, and limited to non-deleted rows. It is not restricted to active customers.
• The response can contain multiple rows for one requested name when the tenant already has case-insensitive duplicates.
• Requested strings are deduplicated case-sensitively before lookup. The legacy missing-name calculation compares returned spelling case-sensitively, so enabling creation with different capitalization can create another customer even though the lookup found an existing case-insensitive match.
• There is no pagination or batch-size limit. Keep arrays moderate to avoid an oversized SQL IN clause.
• Blank names are never created, although blank strings can participate in the initial lookup.

Side effects

Lookup-only calls do not write data. With createIfNotExists enabled, each missing name is inserted with current cdate and last_edited values plus a shared created_by_import_id in metadata. One imports_log row records the batch and optional filename.

The direct insert invalidates the customer cache, but it does not fire Customer_new, create the usual customer-created integration hook, record created_by explicitly, or validate the final customer beyond its name being non-blank.

See it in Fieldmotion

CRM1

Start an import whose mapped rows depend on customer names. Open browser developer tools and filter Network requests for Customers_listByNames. CRM1 batches unresolved dependency names after parsing the file; import configurations that opt into customer creation add createIfNotExists=1.

CRM2

Use the equivalent spreadsheet import flow in CRM2 and filter for Customers_listByNames. CRM2 supplies the import filename as well as the name batch, allowing created-name batches to retain that filename in their import-log metadata.

Related endpoints

• Customers_search offers paginated lookup with parent, contact, and custom-field filters.
• Customer_new is the supported explicit creation path and applies customer validation and events.
• Customers_getById fetches authoritative records after names have been resolved to IDs.