API reference

Notifications

Your in-app notifications, and which optional notices the company also emails.

5 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.

List my notifications#

POST/v1/platform/notifications.listRead

Your Bizisy notifications, newest first: reminders (probation and fixed-term contracts ending, people starting, work anniversaries), checklist tasks due, changes waiting for your approval, and documents people added. You get the same ones you would get by email, whether or not your company emails them; each has an href to open it in Bizisy. Each is checked against what you may see now: one that no longer applies (the request was decided, the task done, the document deleted, or you no longer hold the role that earned it) disappears; one that cannot be checked right now comes back as kind unavailable. Over an API key or AI app, pay change requests are never listed. Kept 90 days. limit 1–50 (default 20; 0 returns only the unread count); before = the next value of the previous page; unread_only. Only your own notifications.

Who can call it: Manage key any Manage role
Me key anyone
MCP tool: platform_notifications_list on My Workplace, HR Assistant
Method: POST with a JSON body, or GET with the input as query parameters

Input

limitinteger
From 0 to 50. Default 20.
beforestring
Up to 200 characters.
unread_onlyboolean
Default false.

Returns

itemsobject[]required
11 fields
- idstringrequired
- kind"reminder" | "task" | "approval_request" | "document_uploaded" | "unavailable"required
  reminder (probation or contract ending, someone starting, a work anniversary), task (a checklist task due), approval_request (a change waits for your decision), document_uploaded (someone added a document of their own), or unavailable (it could not be loaded just now: try again later; nothing else is known).
- created_atstringrequired
- readbooleanrequired
- hrefstring | nullrequired
  Where it leads, on the company address: /manage/… opens Manage, any other path My workspace. null when unavailable.
- person_namestring | nullrequired
  Who it is about; null when unavailable.
- datestring | nullrequired
  YYYY-MM-DD: the reminder date, the task due date or the date the change takes effect.
- reminderobject | nullrequired
  3 fields
  - kind"probation_end" | "contract_end" | "start_soon" | "start_today" | "anniversary"required
  - yearsinteger | nullrequired
    Anniversaries: years of service.
  - selfbooleanrequired
    The reminder is about the reader (their own anniversary).
- taskobject | nullrequired
  3 fields
  - titlestringrequired
  - checkliststringrequired
  - ownbooleanrequired
    The task is in the reader's own checklist.
- approvalobject | nullrequired
  3 fields
  - change"job_change" | "termination" | "pay_change"required
    The kind of change (never a pay amount).
  - proposer_namestringrequired
  - as"manager" | "hr" | "lead"required
    Why the reader decides: as the person's manager, as HR, or as the lead of their team (when they have no manager).
- documentobject | nullrequired
  1 field
  - categorystringrequired
unreadintegerrequired
Unread notifications in total.
nextstring | nullrequired
Pass as before for the next page; null at the end.

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl

curl https://api.bizisy.com/v1/platform/notifications.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "limit": 20,
  "before": "MjAyNi0xMC0wNFQxMDowMDowMC4wMDBafG4x",
  "unread_only": true
}'

Node

const res = await fetch('https://api.bizisy.com/v1/platform/notifications.list', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "limit": 20,
    "before": "MjAyNi0xMC0wNFQxMDowMDowMC4wMDBafG4x",
    "unread_only": true
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os
import requests

res = requests.post(
    "https://api.bizisy.com/v1/platform/notifications.list",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
    json={
        "limit": 20,
        "before": "MjAyNi0xMC0wNFQxMDowMDowMC4wMDBafG4x",
        "unread_only": True,
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

Response

{
  "data": {
    "items": [
      {
        "id": "n1",
        "kind": "approval_request",
        "created_at": "2026-10-04T10:00:00.000Z",
        "read": false,
        "href": "/manage/approvals/a1",
        "person_name": "Rui Costa",
        "date": "2026-11-01",
        "reminder": null,
        "task": null,
        "document": null,
        "approval": {
          "change": "job_change",
          "proposer_name": "Ana Ferreira",
          "as": "hr"
        }
      },
      {
        "id": "n2",
        "kind": "reminder",
        "created_at": "2026-10-04T10:00:00.000Z",
        "read": true,
        "href": "/manage/people/p2",
        "person_name": "Rui Costa",
        "date": "2026-11-01",
        "reminder": {
          "kind": "anniversary",
          "years": 3,
          "self": false
        },
        "task": null,
        "document": null,
        "approval": null
      },
      {
        "id": "n3",
        "kind": "unavailable",
        "created_at": "2026-10-04T10:00:00.000Z",
        "read": false,
        "href": null,
        "person_name": null,
        "date": null,
        "reminder": null,
        "task": null,
        "document": null,
        "approval": null
      }
    ],
    "unread": 2,
    "next": null
  }
}

Mark notifications as read#

POST/v1/platform/notifications.mark_readWrite

Marks some of your own notifications as read (ids from platform_notifications_list, 1–100). Ids that are not yours or already read are ignored: marked says how many changed. Not recorded in Activity (your own inbox only).

Who can call it: Manage key any Manage role
Me key anyone
MCP tool: platform_notifications_mark_read on My Workplace, HR Assistant
Preview: ?dry_run=true runs every check and saves nothing
Retries: An Idempotency-Key replays the first result

Input

idsstring[]required
1–100 characters. 1–100 items.

Returns

markedintegerrequired
unreadintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl

curl https://api.bizisy.com/v1/platform/notifications.mark_read \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"ids":["n1"]}'

Node

const res = await fetch('https://api.bizisy.com/v1/platform/notifications.mark_read', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "ids": [
      "n1"
    ]
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os, uuid
import requests

res = requests.post(
    "https://api.bizisy.com/v1/platform/notifications.mark_read",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "ids": [
            "n1",
        ],
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

Response

{
  "data": {
    "marked": 1,
    "unread": 0
  }
}

Mark all notifications as read#

POST/v1/platform/notifications.mark_all_readWrite

Marks every one of your own unread notifications as read (over an API key or AI app, those it can list). Not recorded in Activity (your own inbox only).

Who can call it: Manage key any Manage role
Me key anyone
MCP tool: platform_notifications_mark_all_read on My Workplace, HR Assistant
Preview: ?dry_run=true runs every check and saves nothing
Retries: An Idempotency-Key replays the first result

Input

No input: send {}.

Returns

markedintegerrequired
unreadintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl

curl https://api.bizisy.com/v1/platform/notifications.mark_all_read \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

Node

const res = await fetch('https://api.bizisy.com/v1/platform/notifications.mark_all_read', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os, uuid
import requests

res = requests.post(
    "https://api.bizisy.com/v1/platform/notifications.mark_all_read",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={},
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

Response

{
  "data": {
    "marked": 3,
    "unread": 0
  }
}

See notification settings#

POST/v1/platform/notifications.settings.getRead

Returns which optional emails the company sends, its monthly limit on extra emails, and this month's usage (sent, held by the limit, shown in the app because their email is off, the allowance, extra, blocks billed and the estimate). Owners and admins. Every optional notice (daily reminders and checklist tasks, approval requests, documents people added) always appears in the recipients' Bizisy notifications; this decides which are also emailed (email: { reminders, approval_request, document_uploaded }, all on by default) and an optional monthly limit on extra emails (extra_limit). 10 optional emails per active person per month are included, pooled across the company; above that they cost €1 per 1,000 (€0.10 per block of 100, rounded up), excluding VAT, billed with the monthly invoice once billing has started (included before, and in the uncharged first month). Sign-in, invite, security, billing and closure emails are always sent and never counted.

Who can call it: Manage key owner admin
MCP tool: platform_notifications_settings_get on HR Assistant
Method: POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

emailobjectrequired
Per optional type: true = emailed and in the app; false = in the app only.
3 fields
- remindersbooleanrequired
  The daily reminders email (probation and contracts ending, starters, anniversaries, and checklist tasks due): one digest per person per day.
- approval_requestbooleanrequired
  An email to each approver when a change waits for their decision.
- document_uploadedbooleanrequired
  An email to owners, admins and HR when someone adds a document of their own.
extra_limitinteger | nullrequired
At most this many optional emails a month above the included allowance; once reached, notices stay in the app only until next month. null = no limit.
usageobjectrequired
11 fields
- monthstringrequired
  The current month (YYYY-MM, UTC: billing months run 1st to 1st).
- sentintegerrequired
  Optional emails sent this month (a daily digest counts as one).
- heldintegerrequired
  Optional emails not sent this month because the limit was reached (they are in the app).
- in_app_onlyintegerrequired
  Optional notices not emailed this month because their email is off.
- active_peopleintegerrequired
- allowanceintegerrequired
  Included this month: 10 per active person, pooled.
- extraintegerrequired
  Sent above the allowance.
- billable_unitsintegerrequired
  Blocks of 100 emails above the allowance (rounded up), never more than the monthly limit allows.
- unit_sizeintegerrequired
- unit_price_centsintegerrequired
  €0.10 per block of 100, excluding VAT (= €1 per 1,000 emails).
- estimated_centsintegerrequired
  This month's optional emails so far, excluding VAT; billed with the monthly invoice.
billedbooleanrequired
Emails above the allowance are charged now (a paid subscription runs and the email price applies); false before billing starts, during the uncharged first month and until billing_from: they are included.
billing_fromstring | nullrequired
YYYY-MM-DD (a 1st): from when emails above the allowance are charged, at least 30 days after the company was told the price; null until it was told (nothing is charged).

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl

curl https://api.bizisy.com/v1/platform/notifications.settings.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Node

const res = await fetch('https://api.bizisy.com/v1/platform/notifications.settings.get', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os
import requests

res = requests.post(
    "https://api.bizisy.com/v1/platform/notifications.settings.get",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
    json={},
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

Response

{
  "data": {
    "email": {
      "reminders": true,
      "approval_request": true,
      "document_uploaded": false
    },
    "extra_limit": 500,
    "usage": {
      "month": "2026-10",
      "sent": 182,
      "held": 0,
      "in_app_only": 14,
      "active_people": 7,
      "allowance": 70,
      "extra": 112,
      "billable_units": 2,
      "unit_size": 100,
      "unit_price_cents": 10,
      "estimated_cents": 20
    },
    "billed": true,
    "billing_from": "2026-11-01"
  }
}

Change notification settings#

POST/v1/platform/notifications.settings.updateWrite

Changes which optional emails the company sends and the monthly limit on extra emails. Send only what changes: email (any of reminders, approval_request, document_uploaded: true or false) and/or extra_limit (0–100000, or null for no limit). Turning an email off keeps the notices in the app. Preview with dry_run. Owners and admins. Every optional notice (daily reminders and checklist tasks, approval requests, documents people added) always appears in the recipients' Bizisy notifications; this decides which are also emailed (email: { reminders, approval_request, document_uploaded }, all on by default) and an optional monthly limit on extra emails (extra_limit). 10 optional emails per active person per month are included, pooled across the company; above that they cost €1 per 1,000 (€0.10 per block of 100, rounded up), excluding VAT, billed with the monthly invoice once billing has started (included before, and in the uncharged first month). Sign-in, invite, security, billing and closure emails are always sent and never counted.

Who can call it: Manage key owner admin
MCP tool: platform_notifications_settings_update on HR Assistant
Preview: ?dry_run=true runs every check and saves nothing
Retries: An Idempotency-Key replays the first result

Input

emailobject
3 fields
- remindersboolean
- approval_requestboolean
- document_uploadedboolean
extra_limitinteger | null
From 0 to 100000.

Returns

emailobjectrequired
Per optional type: true = emailed and in the app; false = in the app only.
3 fields
- remindersbooleanrequired
  The daily reminders email (probation and contracts ending, starters, anniversaries, and checklist tasks due): one digest per person per day.
- approval_requestbooleanrequired
  An email to each approver when a change waits for their decision.
- document_uploadedbooleanrequired
  An email to owners, admins and HR when someone adds a document of their own.
extra_limitinteger | nullrequired
At most this many optional emails a month above the included allowance; once reached, notices stay in the app only until next month. null = no limit.
usageobjectrequired
11 fields
- monthstringrequired
  The current month (YYYY-MM, UTC: billing months run 1st to 1st).
- sentintegerrequired
  Optional emails sent this month (a daily digest counts as one).
- heldintegerrequired
  Optional emails not sent this month because the limit was reached (they are in the app).
- in_app_onlyintegerrequired
  Optional notices not emailed this month because their email is off.
- active_peopleintegerrequired
- allowanceintegerrequired
  Included this month: 10 per active person, pooled.
- extraintegerrequired
  Sent above the allowance.
- billable_unitsintegerrequired
  Blocks of 100 emails above the allowance (rounded up), never more than the monthly limit allows.
- unit_sizeintegerrequired
- unit_price_centsintegerrequired
  €0.10 per block of 100, excluding VAT (= €1 per 1,000 emails).
- estimated_centsintegerrequired
  This month's optional emails so far, excluding VAT; billed with the monthly invoice.
billedbooleanrequired
Emails above the allowance are charged now (a paid subscription runs and the email price applies); false before billing starts, during the uncharged first month and until billing_from: they are included.
billing_fromstring | nullrequired
YYYY-MM-DD (a 1st): from when emails above the allowance are charged, at least 30 days after the company was told the price; null until it was told (nothing is charged).
changedstring[]required
What changed, e.g. email.reminders, extra_limit.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl

curl https://api.bizisy.com/v1/platform/notifications.settings.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "email": {
    "reminders": true,
    "approval_request": false,
    "document_uploaded": true
  },
  "extra_limit": null
}'

Node

const res = await fetch('https://api.bizisy.com/v1/platform/notifications.settings.update', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "email": {
      "reminders": true,
      "approval_request": false,
      "document_uploaded": true
    },
    "extra_limit": null
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os, uuid
import requests

res = requests.post(
    "https://api.bizisy.com/v1/platform/notifications.settings.update",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "email": {
            "reminders": True,
            "approval_request": False,
            "document_uploaded": True,
        },
        "extra_limit": None,
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

Response

{
  "data": {
    "email": {
      "reminders": true,
      "approval_request": true,
      "document_uploaded": false
    },
    "extra_limit": null,
    "usage": {
      "month": "2026-10",
      "sent": 182,
      "held": 0,
      "in_app_only": 14,
      "active_people": 7,
      "allowance": 70,
      "extra": 112,
      "billable_units": 2,
      "unit_size": 100,
      "unit_price_cents": 10,
      "estimated_cents": 20
    },
    "billed": true,
    "billing_from": "2026-11-01",
    "changed": [
      "email.document_uploaded"
    ]
  }
}

Something missing or wrong on this page? Write to hello@bizisy.com.