Notifications

A notification tells a user that something involving them happened: a task or deal was assigned to them, a colleague shared a record or mentioned them in a comment, an agent made a proposal. Use this resource to read the notifications of your key’s user and to mark them read, unread, or dismissed.

Each notification has three independent states for its recipient. It is new until the user next opens their notifications in Carom. It is unread until it is marked read. It stays in the list until it is dismissed, and undismissing it puts it back.

#The notification object

Returned by List notifications, by the endpoints that mark a single notification read or unread, and by Undismiss a notification. The state fields describe the notification for your key’s user.

Attributes

  • idstring · uuid

    Unique identifier for the notification.

  • eventstring · nullable

    What happened, such as task_assigned, comment_mentioned, or contact_shared. Every event is listed under slice on List notifications.

  • payloadobject · nullable

    The record the notification is about, as it was when the notification was created: its id, its record_type (such as task, contact, or deal), and a few identifying fields such as name or subject. When the notification is about a comment or a share on that record, the comment or share is nested under its own key, comment or share. A draft_failed payload is about a draft and carries its subject and last_error, an object with a code and a message you can show the user, as on the draft itself.

  • prompting_user_idstring · uuid · nullable

    The user whose action caused the notification. Null when Carom or an agent caused it.

  • newboolean

    True when the notification arrived after the user last opened their notifications in Carom.

  • read_atstring · date-time · nullable

    When the notification was marked read. Null while it is unread.

  • dismissed_atstring · date-time · nullable

    When the notification was dismissed. Dismissed notifications aren’t listed, so this is null in list responses.

  • created_atstring · date-time · nullable
The notification object 
{
  "id": "c433e00a-df4a-4cd7-a89f-4431d8aa07e8",
  "payload": {
    "id": "1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41",
    "record_type": "contact",
    "name": "Priya Natarajan",
    "email_address": "priya@wildgrove.example",
    "comment": {
      "id": "a9b8c7d6-e5f4-4a3b-9c2d-1e0f9a8b7c6d",
      "text": "@Dana Whitfield can you send Priya the renewal numbers before the 15th?"
    }
  },
  "event": "comment_mentioned",
  "prompting_user_id": "44c3f6da-393b-4664-9bfa-3c14e76b8cb8",
  "created_at": "2026-09-03T18:44:12.507Z",
  "dismissed_at": null,
  "read_at": null,
  "new": true
}
get/notifications Read key

#List notifications

Returns the notifications of your key’s user, newest first, 50 per page unless you set limit. Dismissed notifications are left out. Filter by event or to unread notifications only, and page forward with a cursor.

Query parameters

  • slicestring

    Comma-separated events. Only notifications for these events are returned.

    task_assignedtask_shareddeal_assigneddeal_wondeal_stage_moveddeal_sharedcomment_addedcomment_mentionedinteraction_share_requestedmilestone_sharedfile_sharedthread_sharedcontact_sharedorganization_sharedcalendar_event_sharedspace_sharedmailbox_shareddraft_failedmailbox_lockedmailbox_unlockedproposal_createdproposal_applied
  • statusstring

    Set to unread to return only unread notifications. Omit to include read ones.

    unread
  • limitintegerdefault 50

    Page size, at most 100.

  • next_cursorstring

    Opaque token from the previous page’s page_info.next_cursor. Omit to start from the newest notification. See Pagination.

Returns

  • collectionobject

    A page of notifications and the cursor to the next one.

    Show 4 child attributesHide child attributes
    • recordsarray of notifications
    • page_infopage info

      Where this page sits in the full list. Pass next_cursor back to fetch the next page while has_more_after is true.

    • slice_keystring · nullable

      The slice you sent, echoed back.

    • filtersobject · nullable

      The status filter, echoed back.

Errors

  • 400invalid_requestslice names an event not in the list above, or status isn’t unread.
  • 400invalid_cursorThe cursor is unreadable, or came from another list or sort.
  • 400unsupported_cursor_directionA prev_cursor was sent. This list pages forward only.
get/notifications 
curl "https://api.carom.io/notifications?status=unread&limit=20" \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{
  "collection": {
    "slice_key": null,
    "filters": { "status": "unread" },
    "page_info": {
      "limit": 20,
      "next_cursor": "q7Rn2Kx9vTf4LmWc8HdZ",
      "prev_cursor": null,
      "has_more_after": true,
      "has_more_before": false
    },
    "records": [
      {
        "id": "c433e00a-df4a-4cd7-a89f-4431d8aa07e8",
        "event": "comment_mentioned",
        "prompting_user_id": "44c3f6da-393b-4664-9bfa-3c14e76b8cb8",
        "created_at": "2026-09-03T18:44:12.507Z",
        "read_at": null,
        "new": true,
        …
      },
      {
        "id": "f9152af0-797b-47d9-9588-285e43241ac2",
        "event": "deal_won",
        "payload": {
          "id": "7e64838f-be70-4490-9284-e526155e1dac",
          "record_type": "deal",
          "name": "Wildgrove portfolio renewal"
        },
        "prompting_user_id": "722d227f-631b-4a8a-8579-629fd96250a5",
        "created_at": "2026-09-02T21:05:40.118Z",
        "read_at": null,
        "new": false,
        …
      }
    ]
  }
}
get/notifications/count Read key

#Count notifications

Counts the notifications that List notifications would return for the same filters, without fetching them.

Query parameters

Returns

The count object, wrapped in count. Notifications are always counted exactly, so exact is true and cap is null.

Errors

  • 400invalid_requestslice names an unknown event, or status isn’t unread.
get/notifications/count 
curl "https://api.carom.io/notifications/count?status=unread&slice=comment_mentioned,task_assigned" \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{
  "count": {
    "total": 3,
    "exact": true,
    "capped": false,
    "cap": null
  }
}
post/notifications/read Write key

#Mark all notifications read

Marks every unread notification of the user read, not only those on a page you have loaded, and clears new on all of them. Returns the recalculated counts.

Returns

  • new_countinteger

    Notifications with new set. Zero after this call.

  • unread_countinteger

    Unread notifications. Zero after this call.

  • unread_countsobject

    Unread notifications per event, keyed by event. Events with none are omitted, so this is empty after this call.

post/notifications/read 
curl -X POST https://api.carom.io/notifications/read \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{
  "new_count": 0,
  "unread_counts": {},
  "unread_count": 0
}
post/notifications/{id}/read Write key

#Mark a notification read

Marks one notification read and returns it with its new read_at.

Path parameters

  • idstring · uuidrequired

    The notification’s id.

Returns

The notification object, wrapped in notification.

Errors

  • 404record_not_foundYour key’s user isn’t a recipient of a notification with that id.
post/notifications/{id}/read 
curl -X POST https://api.carom.io/notifications/c433e00a-df4a-4cd7-a89f-4431d8aa07e8/read \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{
  "notification": {
    "id": "c433e00a-df4a-4cd7-a89f-4431d8aa07e8",
    "event": "comment_mentioned",
    "read_at": "2026-09-18T15:02:33.810Z",
    "dismissed_at": null,
    "new": false,
    …
  }
}
post/notifications/{id}/unread Write key

#Mark a notification unread

Clears a notification’s read_at so it counts as unread again, and returns it.

Path parameters

  • idstring · uuidrequired

    The notification’s id.

Returns

The notification object, wrapped in notification.

Errors

  • 404record_not_foundYour key’s user isn’t a recipient of a notification with that id.
post/notifications/{id}/unread 
curl -X POST https://api.carom.io/notifications/c433e00a-df4a-4cd7-a89f-4431d8aa07e8/unread \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{
  "notification": {
    "id": "c433e00a-df4a-4cd7-a89f-4431d8aa07e8",
    "event": "comment_mentioned",
    "read_at": null,
    "dismissed_at": null,
    "new": false,
    …
  }
}
post/notifications/{id}/dismiss Write key

#Dismiss a notification

Removes one notification from the user’s list and counts. To dismiss several at once, use Dismiss notifications.

Path parameters

  • idstring · uuidrequired

    The notification’s id.

Returns

The ok object, {"ok": "ok"}.

Errors

  • 404record_not_foundYour key’s user isn’t a recipient of a notification with that id.
post/notifications/{id}/dismiss 
curl -X POST https://api.carom.io/notifications/c433e00a-df4a-4cd7-a89f-4431d8aa07e8/dismiss \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{
  "ok": "ok"
}
post/notifications/dismiss Write key

#Dismiss notifications

Dismisses several notifications at once: a list of ids, every notification for some events, or all of them. Send one of ids, slice, or global. If you send more than one, global wins over slice, and slice wins over ids. Ids the user isn’t a recipient of are ignored. To dismiss one notification, use Dismiss a notification.

Request body application/json

  • idsarray of strings · uuid

    The notifications to dismiss.

  • slicestring

    Comma-separated events, such as task_assigned, from the list on List notifications. Dismisses every notification of the user for those events.

  • globalboolean

    true dismisses every notification of the user.

Returns

The ok object, {"ok": "ok"}.

Errors

  • 400invalid_requestids isn’t an array of UUIDs, slice names an event not in the list, or global isn’t a boolean.
post/notifications/dismiss 
curl https://api.carom.io/notifications/dismiss \
  -H "Authorization: Bearer $CAROM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "c433e00a-df4a-4cd7-a89f-4431d8aa07e8",
      "f9152af0-797b-47d9-9588-285e43241ac2"
    ]
  }'
Response200 
{
  "ok": "ok"
}
post/notifications/{id}/undismiss Write key

#Undismiss a notification

Clears a notification’s dismissed_at, which puts it back in the user’s list and counts, and returns it. Its read state is unchanged. Undismissing a notification that isn’t dismissed changes nothing and still returns it.

Path parameters

  • idstring · uuidrequired

    The notification’s id.

Returns

The notification object, wrapped in notification.

Errors

  • 404record_not_foundYour key’s user isn’t a recipient of a notification with that id.
post/notifications/{id}/undismiss 
curl -X POST https://api.carom.io/notifications/c433e00a-df4a-4cd7-a89f-4431d8aa07e8/undismiss \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{
  "notification": {
    "id": "c433e00a-df4a-4cd7-a89f-4431d8aa07e8",
    "event": "comment_mentioned",
    "read_at": "2026-09-18T15:02:33.810Z",
    "dismissed_at": null,
    "new": false,
    …
  }
}