Skip to content

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
    20 fields
    • idstringrequired
    • kindstring (enum)required

      reminder (probation or contract ending, someone starting, a work anniversary, a document expiring, a company renewal or an occupational health check due, or review work of yours due in a performance cycle), task (a checklist task due), approval_request (a change waits for your decision), document_uploaded (someone added a document of their own), document_shared (HR added a document to your documents: href leads to My workspace → My documents), document_requested (HR asks you to add a document of a category, perhaps by date: href leads to My workspace → My documents, where you add it), timeoff (time off: a request waiting for your decision or a reminder of it, or your own request decided, recorded or cancelled by someone else; see time_off), time_clock (the time clock: a correction waiting for your decision or your confirmation, your correction decided, you are still clocked in after your day, or your month is ready to acknowledge; see time_clock), pay_rights (the yearly reminder that you can ask about pay levels: href leads to My workspace → Pay), pay_reply (HR answered your request about pay levels in writing: href leads to My workspace → Pay, where the answer is), bank_change (HR decided your bank account change: see bank), one_on_one (your 1:1s: see one_on_one), announcement (an announcement was published to you: see announcement; href opens it in My workspace), features (AI and API access or the plan's paid modules changed, or your API keys or AI apps stopped working because your company switched them off; see features), interview (Hiring: you were booked for an interview, it moved or it was cancelled, or HR thanked you for helping hire; see interview; href leads to My workspace → Interviewing), shifts (shift rotas: your week was published or changed, a colleague offered you a shift, or your swap or claim was decided; see shifts; href leads to My shifts), survey (a survey was sent to you, or a reminder while you haven't answered: see survey; href opens it in My workspace), or unavailable (it could not be loaded just now: try again later; nothing else is known).

      One of: reminder, task, approval_request, document_uploaded, document_shared, document_requested, timeoff, time_clock, pay_rights, pay_reply, features, bank_change, announcement, one_on_one, interview, shifts, survey, unavailable.

    • 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
      7 fields
      • kindstring (enum)required

        One of: probation_end, contract_end, start_soon, start_today, anniversary, document_expiry, renewal_due, health_check_due, tell_leaver, one_on_one, check_in_due, one_on_one_action, document_due, policy_ack, training_expiry, talent_due.

      • yearsinteger | nullrequired

        Anniversaries: years of service.

      • labelstring | nullrequired

        document_expiry: the document's category (never its title); renewal_due: the company renewal's name; policy_ack: the policy to acknowledge (href leads to My workspace → Documents → Policies); training_expiry: the course whose certificate expires; otherwise null.

      • selfbooleanrequired

        The reminder is about the reader (their own anniversary).

      • variant"decide" | "review"

        renewal_due: the date is its notice deadline (decide) or, renewing by itself, the last day to review it.

      • step"self" | "manager" | "peer" | "signoff"

        talent_due: review work of yours in a cycle (label: the cycle's name; date: when it is due) — your self-review, reviews of your team to write, feedback colleagues asked you for (never who), or reviews to sign off.

      • countinteger | null

        talent_due: how many are still open.

    • 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
    • bankobject | null

      bank_change: HR decided your bank account change (href leads to My profile → Personal).

      2 fields
      • decision"verified" | "rejected"required
      • notestring | nullrequired
    • interviewobject | null

      interview: an interview you give was booked, moved or cancelled: when, for which job and step (never the candidate); or thanks: HR thanked you for helping hire for that job.

      5 fields
      • event"booked" | "rescheduled" | "cancelled" | "thanks" | "internal"required
      • startstring | nullrequired
      • job_titlestringrequired
      • step_namestring | nullrequired
      • person_namestring | null
    • time_offobject | nullrequired
      11 fields
      • event"request" | "reminder" | "decided" | "booked_for_you" | "cancelled"required

        request/reminder: waits for your decision (person_name asked); decided: your request was approved or declined; booked_for_you: HR recorded time off for you; cancelled: someone else cancelled your time off.

      • startstringrequired
      • endstringrequired
      • start_part"full" | "am" | "pm" | "hours"required
      • end_part"full" | "am" | "pm" | "hours"required
      • minutesinteger | null

        hours: the minutes booked.

      • start_timestring | null
      • daysnumberrequired

        Working days (half-day precision).

      • type_namestring | nullrequired

        null: "time off" (you do not see the type of this request).

      • decision"approved" | "declined"required
      • returned_daysnumber | null

        booked_for_you: sick leave HR recorded over leave you had booked; these days went back to your balance.

    • time_clockobject | null
      4 fields
      • eventstring (enum)required

        correction_request: a correction waits for your decision (person_name asked); correction_confirm: your manager or HR corrected your records and asks you to confirm; correction_decided: a correction was decided or answered; clock_out: you are still clocked in; month_ready: your month is closed, acknowledge it; overtime_request: overtime (for person_name) waits for your decision; overtime_decided: overtime for you was approved, declined or withdrawn.

        One of: correction_request, correction_confirm, correction_decided, clock_out, month_ready, overtime_request, overtime_decided.

      • daystring | nullrequired
      • monthstring | nullrequired
      • decision"approved" | "declined" | "cancelled"required
    • announcementobject | null

      announcement: its title, and whether (and by when) it asks you to acknowledge it.

      3 fields
      • titlestringrequired
      • requires_ackbooleanrequired
      • ack_duestring | nullrequired
    • one_on_oneobject | null

      one_on_one: summary (a 1:1 summary is ready), assigned (an action item for you), skip_started (a skip-level with someone on your team), ask/remind (HR about your team's 1:1s), exemption_request (an exemption waits for your decision), exemption_decided (an exemption request was decided, or HR ended an exemption).

      5 fields
      • eventstring (enum)required

        One of: summary, assigned, skip_started, ask, remind, exemption_request, exemption_decided.

      • other_namestring | nullrequired
      • countinteger | nullrequired
      • decision"approved" | "declined" | "ended"required
      • titlestring | nullrequired
    • shiftsobject | null

      shifts: the rota, the ISO week and its Monday, how many shifts you have that week, and for requests their kind and decision.

      7 fields
      • event"published" | "changed" | "offered" | "decided"required
      • rotastringrequired
      • weekstringrequired
      • week_startstring | nullrequired
      • shiftsintegerrequired

        Your shifts that week now.

      • request"swap" | "give_away" | "claim"required
      • decision"approved" | "declined"required
    • surveyobject | null

      survey: its title, when it closes, whether this is a reminder, and whether it is confidential.

      5 fields
      • titlestringrequired
      • closes_onstring | nullrequired
      • reminderbooleanrequired
      • confidentialbooleanrequired
      • anonymousboolean
    • featuresobject | null
      4 fields
      • event"access_changed" | "access_stopped" | "plan_changed" | "addendum_requested"required

        addendum_requested: an admin or HR asks you, an owner, to accept the AI features addendum for an AI feature (on: the feature, e.g. insights; href: the feature's setup step); access_changed: another owner or admin switched AI assistants or API keys on or off (href: Settings → Modules); access_stopped: your API keys or connected AI apps stopped working because the company switched them off; plan_changed: another owner or admin switched paid modules on or off (href: Plan & billing).

      • onstring[]required

        Switched on: ai.manage, ai.me, api.manage, api.me, or paid module ids for plan_changed.

      • offstring[]required

        Switched off, as on.

      • disconnectedbooleanrequired

        access_stopped: they were also disconnected for good (connect them again once it is back on); otherwise kept.

  • 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
}'
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"
        },
        "time_off": null
      },
      {
        "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,
          "label": null
        },
        "task": null,
        "document": null,
        "approval": null,
        "time_off": 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,
        "time_off": 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"]}'
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 '{}'
Response
{
  "data": {
    "marked": 3,
    "unread": 0
  }
}

See notification settings#

POST/v1/platform/notifications.settings.getRead

Returns which optional emails the company sends and this month's usage (sent, not sent because none were left, shown in the app because their email is off, included, included left and bought left). Owners and admins. Every optional notice (daily reminders and checklist tasks, approval requests, documents people added, documents HR shared with someone, time off requests and decisions, announcements, 1:1s, shift rotas, surveys) always appears in the recipients' Bizisy notifications; this decides which are also emailed (email: { reminders, approval_request, document_uploaded, document_shared, timeoff, announcement, one_on_one, shifts, survey }, all on by default). Each month includes optional emails (20 on Free, then 10 per active person, pooled; they reset on the 1st); bought emails (1,000 for €1, excluding VAT, in Settings → Plan & billing) carry over and are used after them. With none left, notices reach people in the app only. 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.

    9 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.

    • document_sharedbooleanrequired

      An email to a person when HR adds a document they can see to their documents (HR can leave a document unannounced).

    • timeoffbooleanrequired

      Time off emails: to approvers when a request waits for them (and a reminder after 2 working days), and to a person when their request is decided, or HR records or cancels time off for them.

    • announcementbooleanrequired

      An email to each person an announcement is published to (its title and a link; the text stays in the app).

    • one_on_onebooleanrequired

      1:1s: HR asking or reminding managers about their team's 1:1s, and 1:1 exemption requests and decisions.

    • shiftsbooleanrequired

      Shift rotas: an email to each person when their week is published or changed, a colleague offers them a shift, or their swap or claim is decided (people can also turn them off for themselves).

    • surveybooleanrequired

      Surveys: an email to each person a survey is sent to, and up to 2 reminders while they haven't answered (the survey is always in My workspace).

  • usageobjectrequired
    8 fields
    • monthstringrequired

      The current month (YYYY-MM, UTC).

    • sentintegerrequired

      Optional emails sent this month (a daily digest counts as one).

    • heldintegerrequired

      Optional emails not sent this month because none were left (their notices are in the app).

    • in_app_onlyintegerrequired

      Optional notices not emailed this month because their email is off.

    • includedintegerrequired

      Included this month (spec 2026-10-20 C7): 20 on Free, then 10 per active person, pooled.

    • included_leftintegerrequired

      Included emails left this month (they reset on the 1st).

    • boughtintegerrequired

      Bought emails left: they carry over and are used once the included ones run out.

    • unlimitedbooleanrequired

      A developer sandbox: emails are not counted.

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 '{}'
Response
{
  "data": {
    "email": {
      "reminders": true,
      "approval_request": true,
      "document_uploaded": false,
      "document_shared": true,
      "timeoff": true,
      "announcement": true,
      "one_on_one": true,
      "shifts": true,
      "survey": true
    },
    "usage": {
      "month": "2026-10",
      "sent": 312,
      "held": 0,
      "in_app_only": 14,
      "included": 230,
      "included_left": 0,
      "bought": 918,
      "unlimited": false
    }
  }
}

Change notification settings#

POST/v1/platform/notifications.settings.updateWrite

Changes which optional emails the company sends. Send only what changes: email (any of reminders, approval_request, document_uploaded, document_shared, timeoff, announcement, one_on_one, shifts, survey: true or false). 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, documents HR shared with someone, time off requests and decisions, announcements, 1:1s, shift rotas, surveys) always appears in the recipients' Bizisy notifications; this decides which are also emailed (email: { reminders, approval_request, document_uploaded, document_shared, timeoff, announcement, one_on_one, shifts, survey }, all on by default). Each month includes optional emails (20 on Free, then 10 per active person, pooled; they reset on the 1st); bought emails (1,000 for €1, excluding VAT, in Settings → Plan & billing) carry over and are used after them. With none left, notices reach people in the app only. 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
    9 fields
    • remindersboolean
    • approval_requestboolean
    • document_uploadedboolean
    • document_sharedboolean
    • timeoffboolean
    • announcementboolean
    • one_on_oneboolean
    • shiftsboolean
    • surveyboolean

Returns

  • emailobjectrequired

    Per optional type: true = emailed and in the app; false = in the app only.

    9 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.

    • document_sharedbooleanrequired

      An email to a person when HR adds a document they can see to their documents (HR can leave a document unannounced).

    • timeoffbooleanrequired

      Time off emails: to approvers when a request waits for them (and a reminder after 2 working days), and to a person when their request is decided, or HR records or cancels time off for them.

    • announcementbooleanrequired

      An email to each person an announcement is published to (its title and a link; the text stays in the app).

    • one_on_onebooleanrequired

      1:1s: HR asking or reminding managers about their team's 1:1s, and 1:1 exemption requests and decisions.

    • shiftsbooleanrequired

      Shift rotas: an email to each person when their week is published or changed, a colleague offers them a shift, or their swap or claim is decided (people can also turn them off for themselves).

    • surveybooleanrequired

      Surveys: an email to each person a survey is sent to, and up to 2 reminders while they haven't answered (the survey is always in My workspace).

  • usageobjectrequired
    8 fields
    • monthstringrequired

      The current month (YYYY-MM, UTC).

    • sentintegerrequired

      Optional emails sent this month (a daily digest counts as one).

    • heldintegerrequired

      Optional emails not sent this month because none were left (their notices are in the app).

    • in_app_onlyintegerrequired

      Optional notices not emailed this month because their email is off.

    • includedintegerrequired

      Included this month (spec 2026-10-20 C7): 20 on Free, then 10 per active person, pooled.

    • included_leftintegerrequired

      Included emails left this month (they reset on the 1st).

    • boughtintegerrequired

      Bought emails left: they carry over and are used once the included ones run out.

    • unlimitedbooleanrequired

      A developer sandbox: emails are not counted.

  • changedstring[]required

    What changed, e.g. email.reminders.

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
  }
}'
Response
{
  "data": {
    "email": {
      "reminders": true,
      "approval_request": true,
      "document_uploaded": false,
      "document_shared": true,
      "timeoff": true,
      "announcement": true,
      "one_on_one": true,
      "shifts": true,
      "survey": true
    },
    "usage": {
      "month": "2026-10",
      "sent": 312,
      "held": 0,
      "in_app_only": 14,
      "included": 230,
      "included_left": 0,
      "bought": 918,
      "unlimited": false
    },
    "changed": [
      "email.document_uploaded"
    ]
  }
}

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

Developer docs