Fieldmotion API Getting started

Communications

Check for new CRM notices

POST /a/Notice_checkNew

Return the five newest CRM-visible notices and the current user’s unread CRM notice count.

When to use this endpoint

Use Notice_checkNew for the CRM2 header bell. Make an initial request to render the current state, then send exact string false during periodic checks so unchanged polling can return early.

Authentication and permissions

The handler requires an authenticated tenant context through Core_requireLogin(1). It does not perform an additional page or role-permission check.

Rows and user metadata are scoped to the authenticated tenant and session user ID.

Parameters

ParameterTypeRequiredDescription
initialString/boolean-compatibleNoOnly the exact decoded value "false" enables checkpoint comparison and update. Omission, boolean true, and all other values perform an unconditional read.

Example request

$bell = FM_api('Notice_checkNew', [
	'initial' => 'false',
]);

Example response

{
  "data": [{
    "id": "49018",
    "subject": "Mentioned you in Job 1842",
    "status": "0",
    "meta": "{\"createdBy\":19,\"link\":\"#pageJob&id=1842\"}",
    "cdate": "1790848200",
    "platform": "CRM"
  }],
  "notifCount": "1"
}

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.
{"warning":"no new data"}initial is exact string false and the user metadata checkpoint notices_latest is not greater than notices_seen. No data or notifCount keys are returned.

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

Behaviour and edge cases

  • Rows are ordered by cdate descending and limited to five. There is no caller-controlled pagination or filter.
  • Notices whose metadata contains source="push" are excluded from both the rows and unread count. Other notices receive derived platform="CRM".
  • The unread count covers every unread CRM-visible notice for the user, not only the five returned rows.
  • On a non-initial check with new data, the endpoint sets the user’s notices_seen checkpoint to server time before reading the rows. It does not mark individual notice status as read.

Side effects

  • Exact initial=false polling can update users.meta.notices_seen. Other request forms are read-only.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found; CRM1’s notice widget loads Notices_list and advances its checkpoint with Notices_markSeen.

CRM2

Open CRM2 and inspect the header bell. The menu makes one initial request and repeats Notice_checkNew every 60 seconds; clicking a row then calls Notice_markSeen.

Related endpoints