User accounts and profiles
Set one next-of-kin detail
/a/User_setNextOfKin
Merge one named emergency-contact detail into a tenant user profile.
When to use this endpoint
Use name, phone_mobile, phone_landline or address from the profile editor. Other saved next-of-kin fields remain present.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. Session requests use the dispatcher’s CSRF protection when configured; signed requests follow the API-key authentication flow.
Requires login and an owned tenant user. Ordinary self-profile edits are allowed; editing another user requires client administrator or explicit Users Edit permission. Protected membership fields require that permission even for self. Configured TeamAccess record scope and relationship checks remain in force.
The dispatcher applies configured TeamAccess user-record scope before the handler. An explicit target outside that scope returns an error; omitted targets use the current user for the scope check. Active/deleted filtering and additional target checks are described below.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer string | Yes | Target user ID in the authenticated tenant. Parsed with intval; this is a single-record operation, with no pagination or sort controls. |
name | String | Yes | Literal JSON subfield key. Must be present/non-null, but blank and unrecognized keys are not rejected. |
val | Scalar string | Yes | Present value; blank saves an empty value rather than removing the key. No phone/email/field-shape validation. |
Example request
$result = FM_api('User_setNextOfKin', [
'id'=>'1042',
'name'=>'name',
'val'=>'Sam Morgan',
]);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 omitted, null, or converts to an integer below 1. |
{"error": "missing or invalid parameter: name"} | name is omitted or null. |
{"error": "missing or invalid parameter: val"} | val is omitted or null. |
{"error": "user does not exist"} | No target user belongs to the authenticated account. |
{"error": "only client admins or users with Users edit permission can edit other users"} | Caller targets another user without explicit edit authority. |
{"error": "Unable to save user changes. Check the saved state before retrying."} | A checked write/transaction failed; inspect saved state before retrying, especially for separate global identity storage. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Reads and updates the tenant user constrained by ID/current parent, with no active/deleted filtering. A missing/empty saved next_of_kin value starts from {}.
- Next-of-kin is tenant-only profile data. The shared self/editor policy is enforced; the global identity row is not changed.
- An owned target must exist before any write or activity log. Unknown contact subfield names remain accepted for compatibility; blank values are saved rather than removing the key. Malformed saved JSON has no dedicated recovery contract.
- When department hierarchy and team access is enabled, the dispatcher wraps this User write in its access-relationship validation and can reject changes that would strand outstanding Jobs. This does not make file storage, session updates or separate global identity writes one atomic operation. Without that wrapper the handler itself has no enclosing transaction; read back saved state after an uncertain failure.
- No collection filtering, pagination, ordering or batch result is provided. Parameters on this page describe the supported scalar/encoded input; malformed nested values are not a supported contract.
Side effects
- Updates only tenant next_of_kin and user edit markers, invalidates employees cache and logs next_of_kin updated. Does not send a message to the contact.
See it in Fieldmotion
CRM1
Open User → Main → Next of kin in CRM1 and edit a detail. Filter User_setNextOfKin with id, the subfield name and val.
CRM2
No direct production caller was found in CRM2. Its User layouts use the generic getRequestedDetails/updateData flow instead; do not assume that flow has the same validation or permissions as this legacy route.
Related endpoints
User_setName— Update the user’s display name.User_setCustom— Use the custom_values namespace for configured profile fields.