Book a demo

set_my_notification

Set one of my notifications

act entity tenant-private since 2026-10-01

Adds a notice for the caller alone, or takes back one they added, emailed to their sign-in address. Only a kind their role can already see (notice_not_visible otherwise). A notice fixed in code or required by the org's notification settings cannot be turned off (notice_required). Report updates is on by default: on false turns it off. cadence is the audit log digest's (hourly or daily) and Report updates' (immediately, daily or weekly) alone. The same call again changes nothing.

Contract

shape
entity
authority
act
evidence
none
subscription
false
permission
any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first
idempotency
natural
emits
notification_preference.changed
MCP tool
set_my_notification
decision_set
approve, reject
REST
POST https://api.containertradehq.com/v1/cap/set_my_notification

Through MCP this call returns an approval request first; see Approvals.

Idempotency: keyed by the contract's own inputs: the same inputs replay the first call's result

Inputs

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org the caller is a member of.
kindone_ofrequiredone of audit_digest, admin_alerts, access_request, break_glass, deletion, announcement, report_updates
The notice kind.
onbooleanrequired
true adds it for the caller (or turns Report updates back on); false takes back one they added (or turns Report updates off).
cadenceone_ofoptionalone of hourly, daily, immediately, weekly
The audit log digest: hourly or daily (hourly at first). Report updates: immediately, daily or weekly (immediately at first). Kept as it is when absent.

Response

  • kind · string · The notice kind.
  • title · string · Its name, as the page shows it.
  • sent · string · When it is sent.
  • state · string · fixed: sent to the caller by code (an org admin's notices). required: the org's notification settings names them. opted_in: they added it themselves. on: sent to them by default until they turn it off (Report updates). available: they may add it, or turn it back on.
  • cadence · stringnull · How often the caller receives it: the audit digest hourly or daily (hourly until they choose); Report updates immediately, daily or weekly (immediately until they choose); null for every other kind.
  • email · value · The sign-in address a notice is emailed to.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "audit_digest",
        "admin_alerts",
        "access_request",
        "break_glass",
        "deletion",
        "announcement",
        "report_updates"
      ],
      "description": "The notice kind.",
      "x-data-class": "operational"
    },
    "title": {
      "type": "string",
      "description": "Its name, as the page shows it.",
      "x-data-class": "operational"
    },
    "sent": {
      "type": "string",
      "description": "When it is sent.",
      "x-data-class": "operational"
    },
    "state": {
      "type": "string",
      "enum": [
        "fixed",
        "required",
        "opted_in",
        "on",
        "available"
      ],
      "description": "fixed: sent to the caller by code (an org admin's notices). required: the org's notification settings names them. opted_in: they added it themselves. on: sent to them by default until they turn it off (Report updates). available: they may add it, or turn it back on.",
      "x-data-class": "operational"
    },
    "cadence": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "hourly",
        "daily",
        "immediately",
        "weekly",
        null
      ],
      "description": "How often the caller receives it: the audit digest hourly or daily (hourly until they choose); Report updates immediately, daily or weekly (immediately until they choose); null for every other kind.",
      "x-data-class": "operational"
    },
    "email": {
      "anyOf": [
        {
          "type": [
            "string",
            "null"
          ]
        },
        {
          "const": "•••",
          "description": "Masked by the caller's data policy."
        },
        {
          "type": "null",
          "description": "Denied by the caller's data policy."
        }
      ],
      "description": "The sign-in address a notice is emailed to.",
      "x-data-class": "personal"
    }
  },
  "required": [
    "kind",
    "title",
    "sent",
    "state",
    "cadence",
    "email"
  ],
  "additionalProperties": false
}

Refusals

  • notice_required · 422 · the notice reaches the caller whatever they choose: fixed in code for an org admin, or required by the org's notification settings
  • notice_not_visible · 422 · the caller's role cannot see what this notice is about, so it cannot be added
  • cadence_is_digest_only · 422 · a cadence was sent for a notice kind that is not sent on a schedule: only the audit log digest and Report updates are
  • cadence_not_offered · 422 · the cadence is not one this kind is sent on: hourly or daily for the audit log digest; immediately, daily or weekly for Report updates

The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.

Surfaces

DesktopF
MobileF
APIF
MCPF*
VoiceD2
PushF
OneBoxN
OutboundN
  • MCP: approval required
  • Voice: degraded: confirmation
  • OneBox: no document originates a person's notices
  • Outbound: crosses to no counterparty

Events

Related

list_role_templates, set_notification_policy, subscribe_audit