User accounts and profiles
Read or assign a user’s background colour
/a/User_backgroundColourGet
Return a user’s stored display colour, creating one when the field is empty.
When to use this endpoint
Use when a display needs a stable per-user colour. This reader has a write side effect on the first call for an empty colour; it is not a colour setter.
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.
The handler requires an authenticated tenant and adds no administrator, Users page or self-only permission check. This describes this legacy route; permissions enforced by other User update routes do not automatically apply here.
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. |
Example request
$result = FM_api('User_backgroundColourGet', [
'id'=>'1042',
]);Example response
"52a7c9"The response is a JSON string, not an object with a colour property.
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": "user does not exist"} | Target tenant row is absent. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Looks up a single tenant user without active/deleted filtering. A truthy saved bgcolour is returned unchanged: there is no format validation or leading # insertion.
- An empty/falsy field triggers the legacy random calculation and stores its last six hexadecimal characters. Subsequent requests reuse that stored string. Concurrent first reads are not serialized.
- 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
- May update only bgcolour in the tenant users table. This write does not stamp last_edited/edited_uuid, invalidate a named cache, mirror the global row or create an activity log.
See it in Fieldmotion
CRM1
No direct production caller was found in CRM1. Colour displays also obtain bgcolour from loaded User records or the separate Users_backgroundColourGet collection route.
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_getMeta— Read one tenant metadata value.