Resolve price-band names to IDs

When to use this endpoint

Use when an import maps names to existing IDs. Band names are not unique, so resolving a name can return several rows.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session; all normal calls use that tenant. These handlers do not enforce an additional role or finance-page permission.

Use strings for signed numeric values, including values inside native arrays. Only JSON-encode parameters explicitly described as JSON text; see Getting started.

Parameters

Parameter	Type	Required	Description
`names`	JSON array text of strings	Yes	Must be JSON-encoded text, not a native array. Every member must be a string. No trimming or explicit case normalization is applied; database collation determines equality.

Example request

$bands = FM_api('PriceBands_listByNames', ['names'=>json_encode(['Trade', 'Retail'])]);

Example response

[{"id":"1042","name":"Trade"}]

Raw IDs remain strings. Unknown names are omitted; there is no input-order guarantee.

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 parameter: names"}`	names omitted before login.
`{"error":"invalid parameter: names"}`	Decoded JSON is not an array, including null.
`{"error":"invalid name string","name":12}`	A decoded member is not a string; the offending value is returned as name.
`false`	Database query fails.

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

Behaviour and edge cases

Presence/JSON-shape checks happen before login; member-string checks happen afterwards.
An empty JSON array constructs a lookup for the empty string, so it can return bands with blank names instead of necessarily returning [].
Repeated inputs do not duplicate a database row; duplicate stored names can return multiple distinct IDs. No pagination, ordering, timestamps or mode/multiplier fields.
The mobile app has no direct caller for this endpoint in the searched JavaScript or m/www intermediary. It downloads price bands through syncDownloads into its local priceBands table.

Side effects

Read-only; no history, timestamp update, pricing recalculation or cache invalidation.

See it in Fieldmotion

CRM1

Run a stock/customer import mapped to a Price Band name. Filter PriceBands_listByNames; the import widget resolves names and can create missing bands using PriceBand_new.

CRM2

Run the corresponding mapped stock/customer import and filter PriceBands_listByNames. It likewise resolves JSON-encoded names and creates missing named bands separately.

Related endpoints

PriceBand_new creates a missing named band but does not guarantee name uniqueness.
PriceBands_import imports price-band configuration itself.