Fieldmotion API Getting started

Customers

List customer-specific Schedule of Rates prices

POST /a/Customer_sorsGetDT

List Schedule of Rates rows whose metadata contains a customer-specific price for one customer.

When to use this endpoint

Use Customer_sorsGetDT to populate the customer’s Schedule of Rates pricing tab, where the tenant-wide default cost is shown beside the price stored for that customer.

The customer-specific price lives inside each SOR row’s metadata; this endpoint does not calculate a price from the customer 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
cidInteger stringYesCustomer ID; must convert to a positive integer. The customer itself is not checked for existence.
startInteger stringNoZero-based row offset; defaults to 0.
lengthInteger stringNoPage size; defaults to 10.
drawInteger stringNoDataTables counter copied to the response; defaults to 0.
order[0][column]Integer stringNo0 sorts by name, 1 by code, and 2 by description; defaults to code.
order[0][dir]StringNoLegacy inverted direction: requesting desc produces ascending SQL order; any other or omitted value produces descending order.
nameStringNoSubstring filter on SOR name. Percent and underscore retain SQL wildcard meaning.
codeStringNoSubstring filter on SOR code. Percent and underscore retain SQL wildcard meaning.
descriptionStringNoSubstring filter on SOR description. Percent and underscore retain SQL wildcard meaning.

Example request

$prices = FM_api('Customer_sorsGetDT', [
	'cid' => '1088',
	'start' => '0',
	'length' => '25',
	'draw' => '6',
	'order' => [['column' => '1', 'dir' => 'desc']],
	'code' => 'SERV',
]);

Example response

{
  "draw": 6,
  "recordsTotal": "140",
  "recordsFiltered": "2",
  "data": [
    ["Standard service", "SERV-01", "On-site service visit", ["45.00", "62.50"], "4000", "23", "S", ""]
  ]
}

Each row is name, code, description, [default cost, customer price], nominal code, tax rate, tax type, and a blank action placeholder.

The count values are returned as database strings.

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: cid"}cid is absent, zero, negative, or non-numeric.

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

Behaviour and edge cases

  • recordsTotal is the count of every SOR row in the tenant. The endpoint does not apply a deleted or archived-state filter.
  • The nominal code comes from metadata key nominal_code, falling back to legacy key nominal. Missing tax and nominal fields become blank strings.
  • The legacy text filters are not escaped by the implementation. External integrations should send trusted plain text and should not expose these values directly to untrusted users.

See it in Fieldmotion

CRM1

Open a customer and select Schedule of Rates. Filter Network requests for Customer_sorsGetDT. Editing a customer-specific price changes the metadata this table reads.

CRM2

A source search found no CRM2 caller for this customer-specific SOR data table.

Related endpoints