Fieldmotion API Getting started

Communications

Create user notices

POST /a/Notice_createNotice

Create an unread in-CRM notice for one or more tenant users, with optional email notification.

When to use this endpoint

Use Notice_createNotice to notify users about a CRM object or event. CRM2’s notes mention workflow calls it after resolving tagged names from note content.

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
subjectStringYesNotice text. A present blank value is accepted; the route applies no trim or length validation.
userIDInteger-compatible or native arrayConditionallyRecipient ID or IDs. This takes precedence over userName. Values are integer-converted when written; recipient existence and active state are not validated.
userNameString or native arrayConditionallyExact tenant user name or names used only when userID is absent. Nonbreaking spaces are normalized to ordinary spaces. Every matching user receives a notice; unmatched names are silently omitted.
linkStringNoStored in meta.link; defaults to blank. CRM callers use hash-style links such as #pageJob&id=1842.

Example request

$result = FM_api('Notice_createNotice', [
	'subject' => 'Mentioned you in Job 1842',
	'userID' => ['31', '44'],
	'link' => '#pageJob&id=1842',
]);

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.
{"error":"missing or invalid parameter: subject"}subject is absent.
{"error":"missing or invalid parameter: userID"}Neither userID nor userName is present.
{"error":"Email Not Sent: Email not found"}Email notification is enabled for the recipient and the recipient lookup does not supply an email key.
{"error":"Email Not Sent: Link not found"}Email notification is enabled and the recipient lookup does not supply a server key.

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

Behaviour and edge cases

  • Duplicate input values are removed before integer conversion. Different textual IDs that convert to the same integer can still produce duplicate recipient iterations.
  • Each notice stores status=0, current Unix time in cdate, and metadata containing the creating user ID plus the link. The body column is not populated by this endpoint.
  • When names match no user, the endpoint creates nothing and still returns success.
  • Optional email behavior is controlled independently by each recipient’s pageNotifications / enableEmailNotification setting. The email body is the subject followed by the recipient server’s client/ URL and the supplied link.

Side effects

  • Inserts one notice per resolved recipient and sets each recipient’s users.meta.notices_latest to server time.
  • When a recipient’s notification setting is truthy, queues one type-2 email for that recipient through Core_mail. No generic history event is written.

See it in Fieldmotion

CRM1

No direct CRM1 production caller was found.

CRM2

Add a note that tags one or more users on a supported CRM2 record. The shared notes helper calls Notice_createNotice with the tagged names, subject, and object link.

Related endpoints