Fieldmotion API Getting started

Communications

Advance the notice polling checkpoint

POST /a/Notices_markSeen

Advance the current user’s notice polling checkpoint without changing any notice row.

When to use this endpoint

Use Notices_markSeen after the CRM1 notice widget has loaded its list, so later polling can tell whether a newer notice exists. Do not use it to mark notices read.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler requires login and performs no additional page or role-permission check.

The read or write is limited to the authenticated tenant. Notice endpoints that say “current user” use the authenticated session user ID within that tenant.

Parameters

ParameterTypeRequiredDescription
latestFloat-compatible Unix timestampNoCandidate checkpoint. Missing, blank, zero, or nonnumeric input performs no update. A positive value is written only when it exceeds the checkpoint in session metadata.

Example request

$result = FM_api('Notices_markSeen', [
	'latest' => '1790848200.25',
]);

Example response

{"ok":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.

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

Behaviour and edge cases

  • The database update uses the greater of the stored value and submitted value, so an older concurrent checkpoint cannot move it backwards.
  • The comparison first uses the session’s decoded user metadata. When no increase is needed, the endpoint skips the database write.
  • No notice status value is changed. Unread counts therefore remain based on row status, independently of this checkpoint.
  • The caller can submit a future timestamp; the endpoint applies no upper bound or server-time normalization.

Side effects

  • When the candidate is newer, updates users.meta.notices_seen and mirrors that value into the current session metadata.

See it in Fieldmotion

CRM1

Open the taskbar notice widget. After Notices_list returns, CRM1 submits the browser’s current Unix time through this endpoint.

CRM2

No direct CRM2 caller was found. CRM2’s polling checkpoint is advanced inside Notice_checkNew when initial=false.

Related endpoints