Fieldmotion API Getting started

User accounts and profiles

Read or generate all user colours

POST /a/Users_backgroundColourGet

Return an ID-keyed colour map, persisting missing display colours.

When to use this endpoint

Use for legacy Job, Task and Asset calendar colours. The singular User_backgroundColourGet reads one user; this call processes the account’s whole user collection.

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.

Configured TeamAccess row scope is applied in the queries. Ordinary collection requests do not need artificial record IDs. Explicit IDs still pass dispatcher record authorization; unavailable IDs can be rejected there rather than silently omitted.

Login is required. No additional page permission is imposed by this handler.

Parameters

This endpoint has no operation-specific parameters.

Example request

$result = FM_api('Users_backgroundColourGet', [
]);

Example response

{
  "1042": "52a7c9"
}

Errors and unusual responses

ResponseCondition
{"error":"not logged in"}No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

  • Selects visible tenant users whose parent matches the current account, including inactive and temporary users. No user-ID filter, ordering, pagination or cap is applied. Generating a missing display colour remains part of this login-only rendering helper.
  • Truthy stored colours are returned unchanged. Missing/falsy colours are generated with the legacy six-hex-character random calculation and persisted. Returned values omit #.
  • A nonempty result serializes as an ID-keyed object; with no rows PHP returns an empty array. This differs from a list of user records.

Side effects

  • Updates missing bgcolour, last_edited and edited_uuid=Users_backgroundColourGet in tenant users, invalidating users cache. No global mirror, activity log or message is produced.

See it in Fieldmotion

CRM1

Open a CRM1 Jobs, Tasks or Assets calendar. The colour helper loads Users_backgroundColourGet and caches the map client-side.

CRM2

No direct production caller was found in CRM2. Current User layouts use the mapped getRequestedDetails/getDataTable flow; do not assume those contracts match this legacy reader.

Related endpoints