User accounts and profiles
Set one custom user profile value
/a/User_setCustom
Merge one named value into a user’s custom_values metadata.
When to use this endpoint
Use for configured user custom fields; name is the stored field key and value is the submitted scalar. Other custom fields are retained.
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 | Nonempty, truthy key; not trimmed or checked against configured custom fields. The string 0 fails the truthiness check. |
value | Scalar string | Yes | Present value, including an empty string, is stored directly. This handler does not enforce custom-field type, required status or option values. |
Example request
$result = FM_api('User_setCustom', [
'id'=>'1042',
'name'=>'badge',
'value'=>'ENG-1042',
]);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/null/falsy. |
{"error": "missing parameter: value"} | value is omitted or null. |
{"error": "user does not exist"} | No matching tenant-parent user. |
{"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
- Checks a tenant user with the current parent but no active/deleted condition. It merges custom_values[name] into tenant metadata, creating a custom_values object when missing.
- Merges only custom_values[name] independently into tenant and global metadata, preserving keys unique to each store and nested JSON arrays. Invalid stored metadata is normalized to an empty map; existing valid JSON structures are retained.
- Uses the shared User self/editor policy. Blank values remain stored values, not key removal. No configured-field type/option validation is added.
- 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
- Checks and locks the owned target, writes independent metadata merges with edit markers, invalidates employees/users caches and records custom_values history.
- Tenant history and tenant metadata commit together. Global identity storage may be on another host; failure returns an explicit error with no automatic replay rather than promising distributed rollback. Current session metadata is not replaced.
See it in Fieldmotion
CRM1
Open a User’s Custom fields page in CRM1 and edit a field. User_setCustom receives id, the custom key and value; checkbox fields submit the UI’s checked value.
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_getMeta— Read one tenant metadata value.User_setMeta— Merge one ordinary preference into both identity stores.