User accounts and profiles
Change a user’s name
/a/User_setName
Save a display name in the tenant user and global login identity.
When to use this endpoint
Use when renaming an existing user. This does not change login email, user ID or related-record assignment.
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. |
val | String | Yes | Trimmed name. Empty/whitespace and the string 0 are rejected by the truthiness check; no explicit length limit or uniqueness check. |
Example request
$result = FM_api('User_setName', [
'id'=>'1042',
'val'=>'Alex 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: val"} | val is omitted or null. |
{"error": "no name supplied"} | Trimmed val is empty or falsy. |
{"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
- Verifies an owned tenant user and matching global identity before writing. It does not filter by active status or change related-record assignments. A missing target is an explicit error; checked persistence failures are not acknowledged as success.
- Uses the shared User self/editor policy. The display name is not explicitly refreshed in an already-open target session.
- 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 the global identity row and the tenant user row, with last_edited and an operation-specific edited_uuid; invalidates the employees cache. Both updates are limited by user ID and the authenticated parent account.
- Writes an entry in tenant user activity logs. It does not send an email, notification or password-reset message.
See it in Fieldmotion
CRM1
On the CRM1 Users list, edit the name cell. Filter User_setName; the inline editor sends id 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_setEmail— Update the unique login email.User_setNextOfKin— Update tenant-only emergency-contact details.