Customers
Change a customer parent
/a/Customer_setParentId
Assign or clear the parent of one customer while recording the relationship change and refreshing history and job parent caches.
When to use this endpoint
Use Customer_setParentId when an integration deliberately changes where a customer sits in the customer hierarchy. The parent relationship affects parent-aware selection, historical address rendering, job caches, and workflows that bill or report through a parent.
Obtain and validate the intended IDs first. The endpoint prevents only a direct self-parent; it does not prove that another positive parent exists or prevent a longer hierarchy cycle.
Authentication and permissions
The request must authenticate with signed API-key fields or a logged-in CRM session. The handler requires login but performs no additional page or role-permission check.
The customer lookup and update use the authenticated tenant. The handler does not filter the target customer or proposed parent by active/deleted state.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer string | Yes | Customer to update. It must convert to an integer of at least 1. |
val | Integer string | Yes | New parent customer ID. Zero, blank, non-numeric, and negative values are normalized to 0, which clears the parent. The target customer itself is rejected. |
Example request
$result = FM_api('Customer_setParentId', [
'id' => '1088',
'val' => '1001',
]);Example response
{
"ok": 1
}When the stored parent already equals the requested value, the successful response also contains "warning":"no change necessary".
Errors and unusual responses
| Response | Condition |
|---|---|
{"error":"missing or invalid parameter: id"} | id is absent or does not convert to a positive integer. |
{"error":"missing or invalid parameter: val"} | val was omitted. A present blank value clears the parent. |
{"error":"customer cannot be its own parent"} | val resolves to the same ID as the customer. |
{"error":"customer does not exist"} | The customer being updated was not found. |
Behaviour and edge cases
- Values are converted with integer semantics; a present non-numeric value silently becomes
0and clears the parent. - The endpoint can update inactive or soft-deleted customer rows because its target lookup has no state filter.
- A no-change request returns before writing history, caches, logs, timestamps, or events.
- The response does not include the parent name. Fetch the customer afterward when the stored relationship must be confirmed.
Side effects
A real change updates parent_id, last_edited, and edited_uuid; invalidates the customer cache; inserts a customer_changes row containing the old and new IDs; records or backfills address/parent history; refreshes cached parent details on affected jobs; writes a customer audit entry; and fires Customer_edit.
See it in Fieldmotion
CRM1
No direct production CRM1 caller of Customer_setParentId was found. Current edit flows save customer layouts through broader update endpoints. Use a signed request to inspect this focused setter.
CRM2
No direct production CRM2 caller was found. CRM2's customer edit layout uses its mapped update contract rather than this endpoint.
Related endpoints
Customer_getAddressreturns current or historical parent/address context; its legacyparent_idparameter internally calls this setter.Customer_getretrieves the storedparent_idafter the change.Customers_getByIdcan return bothparent_idand a derivedparent_name.