Fieldmotion API Getting started

Customers

List all customer descendants

POST /a/Customer_getChildrenDT

Return a paged, searchable table of every descendant in a customer hierarchy, not only direct subsidiaries.

When to use this endpoint

Use Customer_getChildrenDT for the CRM1 Subsidiaries panel when the complete descendant tree should be flattened into one table.

Use Customer_getSubsidiaries when only immediate children are wanted.

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
customer_idInteger stringYesRoot customer ID. Presence is validated; positivity and customer existence are not.
startInteger stringYesZero-based row offset.
lengthInteger stringYesPage size.
drawInteger stringYesDataTables counter copied to the response.
order[0][dir]StringYesExact desc selects descending; other values select ascending.
order[0][column]Integer stringNo0 customer ID, 1 name, 2 street line 1, or 3 activity state; defaults to name.
search[value]StringNoCase-insensitive substring match on name, either street line, postcode, or county.

Example request

$children = FM_api('Customer_getChildrenDT', [
	'customer_id' => '1001',
	'start' => '0',
	'length' => '25',
	'draw' => '11',
	'order' => [['column' => '1', 'dir' => 'asc']],
	'search' => ['value' => 'Belfast'],
]);

Example response

{
  "draw": 11,
  "recordsTotal": 2,
  "recordsFiltered": "1",
  "data": [
    ["1088", "Northwind Belfast", ["14 Harbour Road","","County Antrim","BT1 1AA"], "1", ""]
  ]
}

Each row is customer ID, name, [street line 1, street line 2, county, postcode], activity flag, and a blank action placeholder. recordsTotal is the number of discovered descendants before search.

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: start"}start is absent.
{"error":"missing or invalid parameter: length"}length is absent.
{"error":"missing or invalid parameter: customer_id"}customer_id is absent.
{"error":"missing or invalid parameter: [order][0][dir]"}The sort direction is absent.
{"error":"missing or invalid parameter: draw"}draw is absent.

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

Behaviour and edge cases

  • The helper repeatedly follows customers.parent_id until no unseen child IDs remain. Direct children, grandchildren, and deeper descendants are all included; the requested root is normally excluded.
  • Hierarchy discovery does not filter deleted or inactive customers. Those descendants remain eligible and their activity flag is returned.
  • A missing or non-positive root finds no descendants and returns an empty page rather than a not-found error.
  • The visited-ID set prevents endless traversal of ordinary hierarchy cycles. In a malformed cycle that points back to the root, the root itself can be discovered as a descendant.

See it in Fieldmotion

CRM1

Open a customer and select Subsidiaries. Filter Network requests for Customer_getChildrenDT; searching, paging, and sorting reload the flattened descendant table.

CRM2

A source search found no CRM2 caller for this endpoint.

Related endpoints