Ir al contenido
BenchKey Ayuda

Notifications

Esta página aún no está disponible en tu idioma.

Notifications are the in-app inbox events that BenchKey generates for your shop, new tickets, mail-ins, SLA breaches, assignment changes, and more. The API exposes two scopes:

  • global (default), tenant-wide system events, not addressed to any one teammate. This is the natural feed for integrations and automation.
  • user, events addressed to a specific teammate’s personal inbox. Requires ?scope=user&user_email=<email>.

An API key acts for the tenant (not a human user), so global is the scope to use unless you are explicitly managing a teammate’s inbox.

The notification object

Section titled “The notification object”
{
  "object": "notification",
  "id": 5501,
  "scope": "global",
  "type": "new_ticket",
  "message": "New ticket TK-10055 from Jane Smith",
  "ticket_id": "TK-10055",
  "from_email": "jane.smith@example.com",
  "read": false,
  "archived": false,
  "archived_at": null,
  "details": { "customer_name": "Jane Smith", "device": "iPhone 15 Pro" },
  "created_at": "2025-11-05T14:22:00.000Z"
}
FieldTypeDescription
idintegerNotification ID
scopestring"global" or "user"
typestring|nullEvent type (e.g. new_ticket, mail_in, sla_breach)
messagestring|nullHuman-readable notification text
ticket_idstring|nullAssociated ticket ID, or null
from_emailstring|nullOriginating email address, if applicable
readbooleanWhether the notification has been read
archivedbooleanWhether the notification has been archived (dismissed)
archived_atstring|nullISO-8601 timestamp when archived, or null
detailsobject|nullParsed JSON metadata specific to the event type
created_atstring|nullISO-8601 creation timestamp

Visibility note: Notifications tied to hidden or soft-deleted tickets are automatically excluded from all responses, the same privacy boundary the BenchKey app enforces.

List notifications

Section titled “List notifications”
GET /api/v1/notifications

Returns a keyset-paginated list of notifications. Defaults to the tenant-wide global inbox, sorted newest first.

Scope required: notifications.read

Query parameters

Section titled “Query parameters”
ParameterTypeDescription
scopestring"global" (default) or "user"
user_emailstringRequired when scope=user, the teammate’s inbox to read
unreadbooleanOnly return unread notifications (ignored when archived=true)
archivedbooleanReturn archived notifications instead of the active inbox
limitintegerPage size, 1–100 (default: 25)
cursorstringOpaque cursor from a previous response’s next_cursor

curl

Section titled “curl”
Terminal window
curl "https://app.benchkey.com/api/v1/notifications?scope=global&unread=true&limit=10" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Node.js

Section titled “Node.js”
const params = new URLSearchParams({ scope: "global", unread: "true", limit: "10" });
const res = await fetch(
  `https://app.benchkey.com/api/v1/notifications?${params}`,
  { headers: { Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" } }
);
const { data, has_more, next_cursor } = await res.json();

Response

Section titled “Response”
{
  "object": "list",
  "data": [
    {
      "object": "notification",
      "id": 5501,
      "scope": "global",
      "type": "new_ticket",
      "message": "New ticket TK-10055 from Jane Smith",
      "ticket_id": "TK-10055",
      "from_email": "jane.smith@example.com",
      "read": false,
      "archived": false,
      "archived_at": null,
      "details": { "customer_name": "Jane Smith", "device": "iPhone 15 Pro" },
      "created_at": "2025-11-05T14:22:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

See Pagination for how to page through results.

Count unread notifications

Section titled “Count unread notifications”
GET /api/v1/notifications/count

Returns the exact count of unread, non-archived notifications for the given scope. Useful for driving badge counts in an integration UI.

Scope required: notifications.read

Query parameters

Section titled “Query parameters”
ParameterTypeDescription
scopestring"global" (default) or "user"
user_emailstringRequired when scope=user

curl

Section titled “curl”
Terminal window
curl "https://app.benchkey.com/api/v1/notifications/count" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Node.js

Section titled “Node.js”
const res = await fetch(
  "https://app.benchkey.com/api/v1/notifications/count",
  { headers: { Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" } }
);
const { scope, unread } = await res.json();

Response

Section titled “Response”
{
  "object": "notification_count",
  "scope": "global",
  "unread": 7
}

Retrieve a notification

Section titled “Retrieve a notification”
GET /api/v1/notifications/:id

Returns a single notification. By default, only global-scope notifications are reachable by ID. To retrieve a user-scoped notification, add ?scope=user&user_email=<email>, the row must belong to that teammate.

Scope required: notifications.read

curl

Section titled “curl”
Terminal window
curl "https://app.benchkey.com/api/v1/notifications/5501" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Node.js

Section titled “Node.js”
const res = await fetch(
  "https://app.benchkey.com/api/v1/notifications/5501",
  { headers: { Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" } }
);
const notification = await res.json();

Response

Section titled “Response”

Returns the notification object. Returns 404 if not found or not in the requested scope.

Mark a notification read

Section titled “Mark a notification read”
POST /api/v1/notifications/:id/read

Marks the notification as read. Returns the updated notification object.

Scope required: notifications.write

curl

Section titled “curl”
Terminal window
curl -X POST "https://app.benchkey.com/api/v1/notifications/5501/read" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Node.js

Section titled “Node.js”
const res = await fetch(
  "https://app.benchkey.com/api/v1/notifications/5501/read",
  { method: "POST", headers: { Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" } }
);
const notification = await res.json();

Mark a notification unread

Section titled “Mark a notification unread”
POST /api/v1/notifications/:id/unread

Flips the notification back to unread. Returns the updated notification object.

Scope required: notifications.write

curl

Section titled “curl”
Terminal window
curl -X POST "https://app.benchkey.com/api/v1/notifications/5501/unread" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Node.js

Section titled “Node.js”
const res = await fetch(
  "https://app.benchkey.com/api/v1/notifications/5501/unread",
  { method: "POST", headers: { Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" } }
);
const notification = await res.json();

Archive a notification

Section titled “Archive a notification”
POST /api/v1/notifications/:id/archive

Soft-archives (dismisses) the notification and marks it read. Archived notifications no longer appear in the active inbox but are recoverable via ?archived=true in the list.

Scope required: notifications.write

curl

Section titled “curl”
Terminal window
curl -X POST "https://app.benchkey.com/api/v1/notifications/5501/archive" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Node.js

Section titled “Node.js”
const res = await fetch(
  "https://app.benchkey.com/api/v1/notifications/5501/archive",
  { method: "POST", headers: { Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" } }
);
const notification = await res.json();

Restore an archived notification

Section titled “Restore an archived notification”
POST /api/v1/notifications/:id/unarchive

Moves the notification back to the active inbox.

Scope required: notifications.write

curl

Section titled “curl”
Terminal window
curl -X POST "https://app.benchkey.com/api/v1/notifications/5501/unarchive" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Node.js

Section titled “Node.js”
const res = await fetch(
  "https://app.benchkey.com/api/v1/notifications/5501/unarchive",
  { method: "POST", headers: { Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" } }
);
const notification = await res.json();

Bulk-archive the global inbox

Section titled “Bulk-archive the global inbox”
POST /api/v1/notifications/archive-read

Archives every already-read notification in the tenant-wide global inbox. This is the “Archive all read” action. Pass ?all=true to also archive unread notifications, emptying the entire global feed (notifications are still recoverable via ?archived=true).

Visibility parity: Only notifications linked to tickets that are visible (not hidden or soft-deleted) are considered. Notifications tied to hidden-ticket rows are never touched, and archived_count reflects only the visible set.

This endpoint operates on the global scope only. User-scope bulk archive requires a human caller and is not exposed via the API.

Scope required: notifications.write

Query parameters

Section titled “Query parameters”
ParameterTypeDescription
allbooleanAlso archive unread notifications (default: false). Must be a scalar boolean (true/false) or 1/0; array/object values return 400 invalid_query

curl

Section titled “curl”
Terminal window
# Archive all read notifications
curl -X POST "https://app.benchkey.com/api/v1/notifications/archive-read" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"


# Clear the entire global inbox (read + unread)
curl -X POST "https://app.benchkey.com/api/v1/notifications/archive-read?all=true" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Node.js

Section titled “Node.js”
const res = await fetch(
  "https://app.benchkey.com/api/v1/notifications/archive-read",
  { method: "POST", headers: { Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" } }
);
const result = await res.json();

Response

Section titled “Response”
{
  "object": "notification_archive_result",
  "scope": "global",
  "cleared_all": false,
  "archived_count": 14
}

Error codes

Section titled “Error codes”
HTTP statusCodeMeaning
400invalid_id:id is not a valid positive integer
400invalid_queryA list filter parameter was supplied as an array or object instead of a single scalar value
400invalid_scopescope is not "global" or "user"
400missing_user_emailscope=user was requested without user_email
400invalid_cursorcursor is malformed
403insufficient_scopeAPI key lacks notifications.read or notifications.write
403user_scope_read_onlyWrite operations (/read, /unread, /archive, /unarchive) are not permitted on user-scoped notifications via an API key
404not_foundNotification not found, or not in the requested scope

See Errors for the full error envelope format.
Estado del sistema