GoliathDevelopersGet an API key
Guides / Notifications API

Notifications API

Read and manage your notification feed, decide Catch up cards, and tidy your Today list through the Goliath developer API

About

Read your in-app notifications (the bell feed), mark them read or delete them, and choose when notification emails go out — track what’s happening across your deals, contacts, and tasks without opening the CRM. The same domain carries the key owner’s Catch up deck (the cards Goliath deals for a decision) and their Today list.

All operations go through the developer API gateway — one endpoint, called by operationId. If you haven’t set up a key yet, start with the Developer API Overview.

Operations

Reading the feed (READ scope)

operationId What it does
listNotifications List your notifications, newest first. Optional filters: notificationTypeFilter, seen (true = read only, false = unread only, omitted = both), searchTerm. Cursor-paginated (limit defaults to 25, capped at 50); total + hasUnread mean nothing is silently truncated, and each row carries the related-record ids (contactId, dealId, noteId, replyId, taskId, callId) plus actionType/actionTargetId for deep-linking.
getNotificationCounts Unread and read counts for your feed (the badge numbers). Optional notificationTypeFilter. A cheap poll for “do I have anything new” before listing.
getAvailableNotificationTypes The catalog of notification types you can filter by — each notificationType is the exact string to pass as notificationTypeFilter. Call this first: the filter is a free string, so a typo silently returns an empty feed rather than an error.

Managing the feed (WRITE scope)

operationId What it does
markNotificationsRead Mark specific notifications read or unread by id. isSeen: true clears them from the unread badge; false marks them unread. notificationIds come from listNotifications. Only your own notifications are affected.
markAllNotificationsRead Mark your whole feed read (isSeen: true) or unread (false). userId must be your own (getMyProfile currentUser.id); any other is refused. Optional notificationTypeFilter narrows it to one type; notIncludedNotificationIds are left alone. Returns how many changed.
markContactNotificationsRead Mark your notifications about one contact (contactId) read.
deleteNotifications Delete notifications from your feed for good, by id. Only your own; another user’s id is skipped. Returns how many were deleted. No undo — to clear the badge, mark them read instead.
setEmailDigestCadence When your notification emails go out: AS_IT_HAPPENS (an email a few minutes after each notification) or DAILY (one email each morning at 8am in your timezone; AI hand-offs and workflow pages still arrive right away). Yours only.

Catch up (READ + WRITE scopes)

operationId Scope What it does
listCatchUpCards READ The key owner’s Catch up deck, ranked as the app deals it: each card’s id, kind, the sentence it asks (ask, else title), its rows (bundleRows, each with defaultChecked) and suggestionIds. limit defaults to 50; nextCursor continues the same ranking.
decideCatchUpCard WRITE Decide one card as the decision bar does: verb (ACCEPT or DISMISS), shownIds (every row the card showed), the ticked suggestionIds (an ACCEPT sets the unticked rows aside), and a reason on a DISMISS. An ACCEPT runs each row’s action — a record change, a merge, a skip trace, or a send. Returns remainingIds, the rows still on the card.
undoCatchUpDecision WRITE Take back a decideCatchUpCard: the same cardId and verb, suggestionIds the rows it decided, and for an ACCEPT setAsideIds (its unticked rows). Dismissals and set-asides come back; a row already applied (a merge, a spend, a send) stands and is counted in refused.

Today (WRITE scope)

These act on rows of the key owner’s Today list. subjectGrn is <Model>_<id> for what the row is about (TextConversation, EmailThread, Deal, Call or Task), and kind is TODAY.

operationId What it does
skipOnToday “Not now”: the row leaves Today until the key owner’s next local day, or sooner when something newer happens. anchorAt is when the row’s event happened.
clearOnToday “Dealt with”: the row leaves Today until something newer than anchorAt happens to it.
hideOnToday “Don’t show this again”, until unhideOnToday.
markWrongOnToday “This is wrong”: a hide with the person’s reason and an optional note (at most 280 characters).
hideTaskSourceOnToday Hide from Today every task one workflow (WorkflowGroup_<id>) or AI employee (Agent_<id>) made, by sourceGrn. The tasks stay in the task list.
unhideOnToday Show a row again — undoes a skip, hide or “this is wrong”. To undo hideTaskSourceOnToday, send that source’s GRN with kind: TODAY_TASKS.

Example

Fetch your unread notifications, then mark them read:

curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "listNotifications", "variables": { "seen": false } }'
curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "markNotificationsRead", "variables": { "notificationIds": ["NOTIFICATION_ID"], "isSeen": true } }'

Full variable schemas, response shapes, and worked examples for every operation are available from the discovery endpoint.