Link a customer to a Fieldmotion account

When to use this endpoint

Use Customer_setFMClientId only for the cross-account temporary-user workflow used by Fieldmotion CRM screens.

The authenticated account and target account must both opt into that workflow. This is not a general customer-to-tenant migration or sharing endpoint.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The authenticated employer metadata must enable can_login_to_other_accounts_with_tmp_user.

The customer is read from the authenticated tenant. The target is read from the global employer table and must have the “Allow Tmp-user Logins” feature bit enabled.

Parameters

Parameter	Type	Required	Description
`id`	Integer string	Yes	Customer in the authenticated tenant; it must convert to a positive integer.
`fm_client_id`	Integer string	Yes	Target Fieldmotion employer/account ID; it must convert to a positive integer.

Example request

$result = FM_api('Customer_setFMClientId', [
	'id' => '1088',
	'fm_client_id' => '24680',
]);

Example response

{
  "ok": 1
}

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 or invalid parameter: id"}`	`id` is absent or invalid.
`{"error":"missing or invalid parameter: fm_client_id"}`	The target account ID is absent or invalid.
`{"error":"this account does not have rights to log into other accounts"}`	The authenticated employer metadata does not enable cross-account temporary-user login.
`{"error":"customer does not exist"}`	The customer does not exist in the authenticated tenant.
`{"error":"client account does not exist"}`	The target employer/account does not exist.
`{"error":"account does not have \"Allow Tmp-user Logins\" enabled - please ask an admin to set it"}`	The target account lacks the required feature bit.

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 customer lookup does not filter inactive or soft-deleted records.
The target account ID is stored as meta.fm_client_id. Existing object/array metadata is preserved; JSON false is explicitly replaced with an empty map, and null or invalid JSON becomes a map when the key is assigned.
Other valid JSON scalar metadata, such as true, a number, or a string, is not normalized and can cause a PHP runtime error when the handler assigns fm_client_id.
There is no no-change branch: a permitted request rewrites the metadata even when the same target is already stored.
This is a single-record mutation; it provides no list filtering or pagination.

Side effects

Only the customer meta column is updated. The handler does not update last_edited or edited_uuid, invalidate the customer cache, write an audit/change row, or fire Customer_edit.
The stored link is later consumed by the separate temporary-user-login workflow; this endpoint does not create or return a temporary user.

See it in Fieldmotion

CRM1

A job’s templated-view workflow can ask for a target client account and call Customer_setFMClientId before requesting a temporary login.

CRM2

The Jobs Timeline cross-account workflow calls this endpoint while preparing temporary access. Its current UI supplies a predetermined target account in that workflow; the endpoint itself still validates the authenticated and target account capabilities.

Related endpoints

Customer_getMeta exposes the encoded metadata containing fm_client_id.
Customer_getTmpUserLogin consumes the link in the subsequent login step; that endpoint is not yet documented here.