Skip to content

API reference

Announcements

Company announcements with acknowledgement: drafts for HR (publishing, corrections and the report stay in the web app), each person's own announcements and whether they confirmed them, and who may post. Webhooks: announcement.published and announcement.acknowledged, ids only.

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

List announcements#

POST/v1/org/announcements.listRead

Announcements as their poster sees them: drafts, scheduled, published and withdrawn, newest first, with how many people they reach and how many saw and acknowledged them. Owners, admins and HR see all; a manager (when the company lets managers post) their own.

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

Input

  • status"draft" | "scheduled" | "published" | "withdrawn"

Returns

  • itemsobject[]required
    11 fields
    • idstringrequired
    • titlestringrequired
    • status"draft" | "scheduled" | "published" | "withdrawn"required
    • requires_ackbooleanrequired
    • ack_duestring | nullrequired
    • publish_atstring | nullrequired
    • published_atstring | nullrequired
    • authorobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • recipientsintegerrequired
    • acknowledgedintegerrequired
    • seenintegerrequired
  • can_postbooleanrequired
  • can_post_everyonebooleanrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/announcements.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"draft"}'
Response
{
  "data": {
    "items": [
      {
        "id": "an1",
        "title": "New expense policy",
        "status": "published",
        "requires_ack": true,
        "ack_due": "2026-10-31",
        "publish_at": null,
        "published_at": "2026-10-17T09:00:00.000Z",
        "author": {
          "id": "p1",
          "name": "Ana Ferreira",
          "title": "HR Manager",
          "photo_url": null
        },
        "recipients": 12,
        "acknowledged": 7,
        "seen": 10
      },
      {
        "id": "an2",
        "title": "New expense policy",
        "status": "draft",
        "requires_ack": true,
        "ack_due": "2026-10-31",
        "publish_at": null,
        "published_at": null,
        "author": {
          "id": "p1",
          "name": "Ana Ferreira",
          "title": "HR Manager",
          "photo_url": null
        },
        "recipients": 0,
        "acknowledged": 0,
        "seen": 0
      }
    ],
    "can_post": true,
    "can_post_everyone": true
  }
}

An announcement (as its poster)#

POST/v1/org/announcements.getRead

One announcement with its text, audience and counts, for owners, admins, HR and its author.

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

Input

  • idstringrequired

Returns

15 fields
  • idstringrequired
  • titlestringrequired
  • status"draft" | "scheduled" | "published" | "withdrawn"required
  • requires_ackbooleanrequired
  • ack_duestring | nullrequired
  • publish_atstring | nullrequired
  • published_atstring | nullrequired
  • authorobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • recipientsintegerrequired
  • acknowledgedintegerrequired
  • seenintegerrequired
  • bodystringrequired
  • audienceobjectrequired
    5 fields
    • everyonebooleanrequired
    • unit_idsstring[]required
    • location_idsstring[]required
    • group_idsstring[]required
    • include_startingbooleanrequired
  • editablebooleanrequired

    Its text can change (nobody acknowledged it yet).

  • urgent_reasonstring | nullrequired

    Marked urgent by HR (an emergency): sent at once, even outside people's working time; why.

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/announcements.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"an1"}'
Response
{
  "data": {
    "id": "an1",
    "title": "New expense policy",
    "status": "published",
    "requires_ack": true,
    "ack_due": "2026-10-31",
    "publish_at": null,
    "published_at": "2026-10-17T09:00:00.000Z",
    "author": {
      "id": "p1",
      "name": "Ana Ferreira",
      "title": "HR Manager",
      "photo_url": null
    },
    "recipients": 12,
    "acknowledged": 7,
    "seen": 10,
    "body": "From 1 November, expenses go through Bizisy.\n\n- Keep the **receipt**\n- Submit within 30 days",
    "audience": {
      "everyone": true,
      "unit_ids": [],
      "location_ids": [],
      "group_ids": [],
      "include_starting": false
    },
    "editable": false,
    "urgent_reason": null
  }
}

Who an announcement would reach#

POST/v1/org/announcements.preview_audienceRead

How many people an audience reaches today (and up to 20 names), before publishing. Owners, admins and HR; managers within their own line when allowed.

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

Input

  • audienceobjectrequired
    5 fields
    • everyoneboolean

      Everyone employed on the publish day (for a manager: everyone in their reporting line).

      Default false.

    • unit_idsstring[]

      Teams (with their sub-teams).

      Up to 50 items.

    • location_idsstring[]

      Up to 50 items.

    • group_idsstring[]

      Saved groups (org_groups_list).

      Up to 50 items.

    • include_startingboolean

      Also people starting later.

      Default false.

Returns

  • countintegerrequired
  • sampleobject[]required
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • over_limitbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/announcements.preview_audience \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audience":{"unit_ids":["u1"],"include_starting":true}}'
Response
{
  "data": {
    "count": 12,
    "sample": [
      {
        "id": "p1",
        "name": "Ana Ferreira",
        "title": "HR Manager",
        "photo_url": null
      },
      {
        "id": "p3",
        "name": "Sofia Costa",
        "title": "Product Designer",
        "photo_url": null
      }
    ],
    "over_limit": false
  }
}

Draft an announcement#

POST/v1/org/announcements.createWrite

Saves a draft announcement: title (≤ 120), body (Markdown-lite, ≤ 10000 characters), audience (everyone, teams, locations, saved groups; a manager's audience is only ever people in their reporting line, and everyone means all of it), whether each person must acknowledge it (with an optional due date), and an optional publish_at. Nothing goes out until it is published in the app. Up to 50 drafts each. Never put health or other sensitive personal details in an announcement.

Who can call it
Manage key any Manage role
Me key anyone
MCP tool
org_announcements_create on HR Assistant, My Workplace
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • titlestringrequired

    1–120 characters.

  • bodystringrequired

    Markdown-lite: paragraphs, - lists, **bold**, *italic*; no links or HTML.

    1–10000 characters.

  • requires_ackboolean

    Each person confirms they read it (evidence: time, channel and a fingerprint of the text).

    Default false.

  • ack_duestring | null

    With requires_ack: by when (reminders 3 days before, on the day, then weekly).

  • audienceobjectrequired
    5 fields
    • everyoneboolean

      Everyone employed on the publish day (for a manager: everyone in their reporting line).

      Default false.

    • unit_idsstring[]

      Teams (with their sub-teams).

      Up to 50 items.

    • location_idsstring[]

      Up to 50 items.

    • group_idsstring[]

      Saved groups (org_groups_list).

      Up to 50 items.

    • include_startingboolean

      Also people starting later.

      Default false.

  • publish_atdate-time | null

    ISO 8601 date and time (UTC).

Returns

15 fields
  • idstringrequired
  • titlestringrequired
  • status"draft" | "scheduled" | "published" | "withdrawn"required
  • requires_ackbooleanrequired
  • ack_duestring | nullrequired
  • publish_atstring | nullrequired
  • published_atstring | nullrequired
  • authorobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • recipientsintegerrequired
  • acknowledgedintegerrequired
  • seenintegerrequired
  • bodystringrequired
  • audienceobjectrequired
    5 fields
    • everyonebooleanrequired
    • unit_idsstring[]required
    • location_idsstring[]required
    • group_idsstring[]required
    • include_startingbooleanrequired
  • editablebooleanrequired

    Its text can change (nobody acknowledged it yet).

  • urgent_reasonstring | nullrequired

    Marked urgent by HR (an emergency): sent at once, even outside people's working time; why.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/announcements.create \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "title": "New expense policy",
  "body": "From 1 November, expenses go through Bizisy.\n\n- Keep the **receipt**\n- Submit within 30 days",
  "audience": {
    "everyone": true
  }
}'
Response
{
  "data": {
    "id": "an2",
    "title": "New expense policy",
    "status": "draft",
    "requires_ack": true,
    "ack_due": "2026-10-31",
    "publish_at": null,
    "published_at": null,
    "author": {
      "id": "p1",
      "name": "Ana Ferreira",
      "title": "HR Manager",
      "photo_url": null
    },
    "recipients": 0,
    "acknowledged": 0,
    "seen": 0,
    "body": "From 1 November, expenses go through Bizisy.\n\n- Keep the **receipt**\n- Submit within 30 days",
    "audience": {
      "everyone": true,
      "unit_ids": [],
      "location_ids": [],
      "group_ids": [],
      "include_starting": false
    },
    "editable": true,
    "urgent_reason": null
  }
}

Change an announcement#

POST/v1/org/announcements.updateWrite

Changes a draft or scheduled announcement (any field), or the text of a published one while nobody has acknowledged it (a correction after that is a new announcement). The author or owners, admins and HR. Over an API key or AI app, drafts only: scheduled and published ones change in the app.

Who can call it
Manage key any Manage role
Me key anyone
Keys and apps
Drafts and scheduled ones only; a published announcement changes in the app.
MCP tool
org_announcements_update on HR Assistant, My Workplace
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • idstringrequired
  • titlestring

    1–120 characters.

  • bodystring

    Markdown-lite: paragraphs, - lists, **bold**, *italic*; no links or HTML.

    1–10000 characters.

  • audienceobject
    5 fields
    • everyoneboolean

      Everyone employed on the publish day (for a manager: everyone in their reporting line).

      Default false.

    • unit_idsstring[]

      Teams (with their sub-teams).

      Up to 50 items.

    • location_idsstring[]

      Up to 50 items.

    • group_idsstring[]

      Saved groups (org_groups_list).

      Up to 50 items.

    • include_startingboolean

      Also people starting later.

      Default false.

  • requires_ackboolean
  • ack_duestring | null
  • publish_atdate-time | null

    ISO 8601 date and time (UTC).

Returns

15 fields
  • idstringrequired
  • titlestringrequired
  • status"draft" | "scheduled" | "published" | "withdrawn"required
  • requires_ackbooleanrequired
  • ack_duestring | nullrequired
  • publish_atstring | nullrequired
  • published_atstring | nullrequired
  • authorobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • recipientsintegerrequired
  • acknowledgedintegerrequired
  • seenintegerrequired
  • bodystringrequired
  • audienceobjectrequired
    5 fields
    • everyonebooleanrequired
    • unit_idsstring[]required
    • location_idsstring[]required
    • group_idsstring[]required
    • include_startingbooleanrequired
  • editablebooleanrequired

    Its text can change (nobody acknowledged it yet).

  • urgent_reasonstring | nullrequired

    Marked urgent by HR (an emergency): sent at once, even outside people's working time; why.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/announcements.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "id": "an2",
  "audience": {
    "location_ids": [
      "l1"
    ]
  },
  "requires_ack": false,
  "ack_due": null
}'
Response
{
  "data": {
    "id": "an2",
    "title": "New expense policy",
    "status": "draft",
    "requires_ack": false,
    "ack_due": null,
    "publish_at": null,
    "published_at": null,
    "author": {
      "id": "p1",
      "name": "Ana Ferreira",
      "title": "HR Manager",
      "photo_url": null
    },
    "recipients": 0,
    "acknowledged": 0,
    "seen": 0,
    "body": "From 1 November, expenses go through Bizisy.\n\n- Keep the **receipt**\n- Submit within 30 days",
    "audience": {
      "everyone": true,
      "unit_ids": [],
      "location_ids": [],
      "group_ids": [],
      "include_starting": false
    },
    "editable": true,
    "urgent_reason": null
  }
}

Publish an announcement#

POST/v1/org/announcements.publishWrite

Publishes a draft now (its audience is fixed to the people it reaches today), or schedules it for publish_at (it goes out within the hour after). People see it in My workspace at once; notices, push and email follow within the hour, and the company chat channel too for everyone-audience posts. Up to 20 a day per company (3 per manager), 10000 people each. In the app only.

Web app only
Refused for API keys and connected apps. Publishing stays in the Bizisy app; machines may draft.
MCP tool
org_announcements_publish on HR Assistant, My Workplace
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • idstringrequired
  • publish_atdate-time | null

    ISO 8601 date and time (UTC).

  • urgent_reasonstring

    HR only, for an emergency: why it can't wait. Its email and push then go out at once, even outside people's working time (right to disconnect); without it they wait for each person's next working period where quiet hours apply.

    3–300 characters.

Returns

15 fields
  • idstringrequired
  • titlestringrequired
  • status"draft" | "scheduled" | "published" | "withdrawn"required
  • requires_ackbooleanrequired
  • ack_duestring | nullrequired
  • publish_atstring | nullrequired
  • published_atstring | nullrequired
  • authorobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • recipientsintegerrequired
  • acknowledgedintegerrequired
  • seenintegerrequired
  • bodystringrequired
  • audienceobjectrequired
    5 fields
    • everyonebooleanrequired
    • unit_idsstring[]required
    • location_idsstring[]required
    • group_idsstring[]required
    • include_startingbooleanrequired
  • editablebooleanrequired

    Its text can change (nobody acknowledged it yet).

  • urgent_reasonstring | nullrequired

    Marked urgent by HR (an emergency): sent at once, even outside people's working time; why.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/announcements.publish \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"an2","urgent_reason":"Office closed today: flood"}'
Response
{
  "data": {
    "id": "an2",
    "title": "New expense policy",
    "status": "published",
    "requires_ack": true,
    "ack_due": "2026-10-31",
    "publish_at": null,
    "published_at": "2026-10-17T09:00:00.000Z",
    "author": {
      "id": "p1",
      "name": "Ana Ferreira",
      "title": "HR Manager",
      "photo_url": null
    },
    "recipients": 12,
    "acknowledged": 7,
    "seen": 10,
    "body": "From 1 November, expenses go through Bizisy.\n\n- Keep the **receipt**\n- Submit within 30 days",
    "audience": {
      "everyone": true,
      "unit_ids": [],
      "location_ids": [],
      "group_ids": [],
      "include_starting": false
    },
    "editable": false,
    "urgent_reason": "Office closed today: flood"
  }
}

Withdraw an announcement#

POST/v1/org/announcements.withdrawWrite

Takes a published or scheduled announcement down: it leaves people's feeds, no more reminders go out, and its receipts stay as a record for HR. The author or owners, admins and HR, in the app.

Who can call it
Manage key any Manage role
Me key anyone
MCP tool
org_announcements_withdraw on HR Assistant, My Workplace
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • idstringrequired

Returns

15 fields
  • idstringrequired
  • titlestringrequired
  • status"draft" | "scheduled" | "published" | "withdrawn"required
  • requires_ackbooleanrequired
  • ack_duestring | nullrequired
  • publish_atstring | nullrequired
  • published_atstring | nullrequired
  • authorobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • recipientsintegerrequired
  • acknowledgedintegerrequired
  • seenintegerrequired
  • bodystringrequired
  • audienceobjectrequired
    5 fields
    • everyonebooleanrequired
    • unit_idsstring[]required
    • location_idsstring[]required
    • group_idsstring[]required
    • include_startingbooleanrequired
  • editablebooleanrequired

    Its text can change (nobody acknowledged it yet).

  • urgent_reasonstring | nullrequired

    Marked urgent by HR (an emergency): sent at once, even outside people's working time; why.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/announcements.withdraw \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"an1"}'
Response
{
  "data": {
    "id": "an1",
    "title": "New expense policy",
    "status": "withdrawn",
    "requires_ack": true,
    "ack_due": "2026-10-31",
    "publish_at": null,
    "published_at": "2026-10-17T09:00:00.000Z",
    "author": {
      "id": "p1",
      "name": "Ana Ferreira",
      "title": "HR Manager",
      "photo_url": null
    },
    "recipients": 12,
    "acknowledged": 7,
    "seen": 10,
    "body": "From 1 November, expenses go through Bizisy.\n\n- Keep the **receipt**\n- Submit within 30 days",
    "audience": {
      "everyone": true,
      "unit_ids": [],
      "location_ids": [],
      "group_ids": [],
      "include_starting": false
    },
    "editable": false,
    "urgent_reason": null
  }
}

Delete a draft announcement#

POST/v1/org/announcements.deleteWrite

Deletes a draft or scheduled announcement (published ones are withdrawn instead, keeping their record). The author or owners, admins and HR.

Who can call it
Manage key any Manage role
Me key anyone
MCP tool
org_announcements_delete on HR Assistant, My Workplace
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • idstringrequired

Returns

  • deletedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/announcements.delete \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"an2"}'
Response
{
  "data": {
    "deleted": true
  }
}

Who read and acknowledged an announcement#

POST/v1/org/announcements.reportRead

For each person it was published to: when they saw it and acknowledged it, how (app or kiosk), and the fingerprint (SHA-256) of the exact title and text they acknowledged; format csv gives a file to keep as evidence. Owners, admins, HR and the author, in the app.

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

Input

  • idstringrequired
  • format"json" | "csv"

Returns

  • fingerprintstringrequired
  • rowsobject[]required
    7 fields
    • personobjectrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • teamstring | nullrequired
    • leftbooleanrequired

      No longer works here (HR only).

    • seen_atstring | nullrequired
    • acknowledged_atstring | nullrequired
    • via"app" | "kiosk"required
    • fingerprintstring | nullrequired
  • csvstring | nullrequired
  • filenamestringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/announcements.report \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"an1","format":"csv"}'
Response
{
  "data": {
    "fingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "filename": "announcement-2026-10-17.csv",
    "csv": null,
    "rows": [
      {
        "person": {
          "id": "p3",
          "name": "Sofia Costa",
          "title": "Product Designer",
          "photo_url": null
        },
        "team": "Product",
        "left": false,
        "seen_at": "2026-10-17T09:30:00.000Z",
        "acknowledged_at": "2026-10-17T09:31:00.000Z",
        "via": "app",
        "fingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
      }
    ]
  }
}

My announcements#

POST/v1/org/announcements.feedRead

Announcements published to you, newest first (up to 50): title, text, who posted, whether you saw it and, when it asks for one, whether you acknowledged it and by when. to_acknowledge counts those still waiting for you. Yours only.

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

Input

No input: send {}.

Returns

  • itemsobject[]required
    10 fields
    • idstringrequired
    • titlestringrequired
    • bodystringrequired
    • published_atstringrequired
    • authorobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • requires_ackbooleanrequired
    • ack_duestring | nullrequired
    • acknowledged_atstring | nullrequired
    • seenbooleanrequired
    • overduebooleanrequired
  • to_acknowledgeintegerrequired
  • unseenintegerrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/announcements.feed \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "items": [
      {
        "id": "an1",
        "title": "New expense policy",
        "body": "From 1 November, expenses go through Bizisy.\n\n- Keep the **receipt**\n- Submit within 30 days",
        "published_at": "2026-10-17T09:00:00.000Z",
        "author": {
          "id": "p1",
          "name": "Ana Ferreira",
          "title": "HR Manager",
          "photo_url": null
        },
        "requires_ack": true,
        "ack_due": "2026-10-31",
        "acknowledged_at": null,
        "seen": true,
        "overdue": false
      }
    ],
    "to_acknowledge": 1,
    "unseen": 0
  }
}

Read an announcement#

POST/v1/org/announcements.readRead

One announcement published to you, with whether you acknowledged it. Yours only.

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

Input

  • idstringrequired

Returns

10 fields
  • idstringrequired
  • titlestringrequired
  • bodystringrequired
  • published_atstringrequired
  • authorobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • requires_ackbooleanrequired
  • ack_duestring | nullrequired
  • acknowledged_atstring | nullrequired
  • seenbooleanrequired
  • overduebooleanrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/announcements.read \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"an1"}'
Response
{
  "data": {
    "id": "an1",
    "title": "New expense policy",
    "body": "From 1 November, expenses go through Bizisy.\n\n- Keep the **receipt**\n- Submit within 30 days",
    "published_at": "2026-10-17T09:00:00.000Z",
    "author": {
      "id": "p1",
      "name": "Ana Ferreira",
      "title": "HR Manager",
      "photo_url": null
    },
    "requires_ack": true,
    "ack_due": "2026-10-31",
    "acknowledged_at": null,
    "seen": true,
    "overdue": false
  }
}

Mark an announcement seen#

POST/v1/org/announcements.seenWrite

Records that you opened an announcement published to you (the read receipt HR sees). The app calls it when you open one.

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

Input

  • idstringrequired

Returns

  • seenbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/announcements.seen \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"an1"}'
Response
{
  "data": {
    "seen": true
  }
}

Acknowledge an announcement#

POST/v1/org/announcements.acknowledgeWrite

Confirms you read an announcement that asks for it: the time, the channel and a fingerprint of the exact text are kept as the record. Once. Yours only, in the app (never through an API key or AI app).

Web app only
Refused for API keys and connected apps. Each person confirms in the Bizisy app or at the time clock kiosk.
MCP tool
org_announcements_acknowledge on My Workplace, HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • idstringrequired

Returns

  • acknowledged_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/announcements.acknowledge \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"an1"}'
Response
{
  "data": {
    "acknowledged_at": "2026-10-17T09:31:00.000Z"
  }
}

Announcement settings#

POST/v1/org/announcements.settings.getRead

Whether managers may post announcements to their own reporting line (off by default).

Who can call it
Manage key any Manage role
MCP tool
org_announcements_settings_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • managers_postbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/announcements.settings.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "managers_post": false
  }
}

Change announcement settings#

POST/v1/org/announcements.settings.updateWrite

Lets managers post announcements to their own reporting line, or not. Owners, admins and HR.

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

Input

  • managers_postbooleanrequired

Returns

  • managers_postbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/announcements.settings.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"managers_post":true}'
Response
{
  "data": {
    "managers_post": true
  }
}

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

Developer docs