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_liston HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
status"draft" | "scheduled" | "published" | "withdrawn"
Returns
itemsobject[]required11 fields
idstringrequiredtitlestringrequiredstatus"draft" | "scheduled" | "published" | "withdrawn"requiredrequires_ackbooleanrequiredack_duestring | nullrequiredpublish_atstring | nullrequiredpublished_atstring | nullrequiredauthorobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
recipientsintegerrequiredacknowledgedintegerrequiredseenintegerrequired
can_postbooleanrequiredcan_post_everyonebooleanrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/announcements.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status":"draft"}'const res = await fetch('https://api.bizisy.com/v1/org/announcements.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"status": "draft"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/announcements.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"status": "draft",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_geton HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
idstringrequired
Returns
15 fields
idstringrequiredtitlestringrequiredstatus"draft" | "scheduled" | "published" | "withdrawn"requiredrequires_ackbooleanrequiredack_duestring | nullrequiredpublish_atstring | nullrequiredpublished_atstring | nullrequiredauthorobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
recipientsintegerrequiredacknowledgedintegerrequiredseenintegerrequiredbodystringrequiredaudienceobjectrequired5 fields
everyonebooleanrequiredunit_idsstring[]requiredlocation_idsstring[]requiredgroup_idsstring[]requiredinclude_startingbooleanrequired
editablebooleanrequiredIts text can change (nobody acknowledged it yet).
urgent_reasonstring | nullrequiredMarked 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 https://api.bizisy.com/v1/org/announcements.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"id":"an1"}'const res = await fetch('https://api.bizisy.com/v1/org/announcements.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"id": "an1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/announcements.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"id": "an1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_audienceon HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
audienceobjectrequired5 fields
everyonebooleanEveryone 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_startingbooleanAlso people starting later.
Default
false.
Returns
countintegerrequiredsampleobject[]required4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
over_limitbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
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}}'const res = await fetch('https://api.bizisy.com/v1/org/announcements.preview_audience', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"audience": {
"unit_ids": [
"u1"
],
"include_starting": true
}
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/announcements.preview_audience",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"audience": {
"unit_ids": [
"u1",
],
"include_starting": True,
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_createon HR Assistant, My Workplace- Preview
?dry_run=trueruns 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
titlestringrequired1–120 characters.
bodystringrequiredMarkdown-lite: paragraphs, - lists, **bold**, *italic*; no links or HTML.
1–10000 characters.
requires_ackbooleanEach person confirms they read it (evidence: time, channel and a fingerprint of the text).
Default
false.ack_duestring | nullWith requires_ack: by when (reminders 3 days before, on the day, then weekly).
audienceobjectrequired5 fields
everyonebooleanEveryone 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_startingbooleanAlso people starting later.
Default
false.
publish_atdate-time | nullISO 8601 date and time (UTC).
Returns
15 fields
idstringrequiredtitlestringrequiredstatus"draft" | "scheduled" | "published" | "withdrawn"requiredrequires_ackbooleanrequiredack_duestring | nullrequiredpublish_atstring | nullrequiredpublished_atstring | nullrequiredauthorobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
recipientsintegerrequiredacknowledgedintegerrequiredseenintegerrequiredbodystringrequiredaudienceobjectrequired5 fields
everyonebooleanrequiredunit_idsstring[]requiredlocation_idsstring[]requiredgroup_idsstring[]requiredinclude_startingbooleanrequired
editablebooleanrequiredIts text can change (nobody acknowledged it yet).
urgent_reasonstring | nullrequiredMarked 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 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
}
}'const res = await fetch('https://api.bizisy.com/v1/org/announcements.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"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
}
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/announcements.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"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,
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_updateon HR Assistant, My Workplace- Preview
?dry_run=trueruns 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
idstringrequiredtitlestring1–120 characters.
bodystringMarkdown-lite: paragraphs, - lists, **bold**, *italic*; no links or HTML.
1–10000 characters.
audienceobject5 fields
everyonebooleanEveryone 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_startingbooleanAlso people starting later.
Default
false.
requires_ackbooleanack_duestring | nullpublish_atdate-time | nullISO 8601 date and time (UTC).
Returns
15 fields
idstringrequiredtitlestringrequiredstatus"draft" | "scheduled" | "published" | "withdrawn"requiredrequires_ackbooleanrequiredack_duestring | nullrequiredpublish_atstring | nullrequiredpublished_atstring | nullrequiredauthorobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
recipientsintegerrequiredacknowledgedintegerrequiredseenintegerrequiredbodystringrequiredaudienceobjectrequired5 fields
everyonebooleanrequiredunit_idsstring[]requiredlocation_idsstring[]requiredgroup_idsstring[]requiredinclude_startingbooleanrequired
editablebooleanrequiredIts text can change (nobody acknowledged it yet).
urgent_reasonstring | nullrequiredMarked 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 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
}'const res = await fetch('https://api.bizisy.com/v1/org/announcements.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"id": "an2",
"audience": {
"location_ids": [
"l1"
]
},
"requires_ack": false,
"ack_due": null
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/announcements.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"id": "an2",
"audience": {
"location_ids": [
"l1",
],
},
"requires_ack": False,
"ack_due": None,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_publishon HR Assistant, My Workplace- Preview
?dry_run=trueruns 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
idstringrequiredpublish_atdate-time | nullISO 8601 date and time (UTC).
urgent_reasonstringHR 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
idstringrequiredtitlestringrequiredstatus"draft" | "scheduled" | "published" | "withdrawn"requiredrequires_ackbooleanrequiredack_duestring | nullrequiredpublish_atstring | nullrequiredpublished_atstring | nullrequiredauthorobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
recipientsintegerrequiredacknowledgedintegerrequiredseenintegerrequiredbodystringrequiredaudienceobjectrequired5 fields
everyonebooleanrequiredunit_idsstring[]requiredlocation_idsstring[]requiredgroup_idsstring[]requiredinclude_startingbooleanrequired
editablebooleanrequiredIts text can change (nobody acknowledged it yet).
urgent_reasonstring | nullrequiredMarked 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 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"}'const res = await fetch('https://api.bizisy.com/v1/org/announcements.publish', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"id": "an2",
"urgent_reason": "Office closed today: flood"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/announcements.publish",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"id": "an2",
"urgent_reason": "Office closed today: flood",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_withdrawon HR Assistant, My Workplace- Preview
?dry_run=trueruns 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
idstringrequiredtitlestringrequiredstatus"draft" | "scheduled" | "published" | "withdrawn"requiredrequires_ackbooleanrequiredack_duestring | nullrequiredpublish_atstring | nullrequiredpublished_atstring | nullrequiredauthorobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
recipientsintegerrequiredacknowledgedintegerrequiredseenintegerrequiredbodystringrequiredaudienceobjectrequired5 fields
everyonebooleanrequiredunit_idsstring[]requiredlocation_idsstring[]requiredgroup_idsstring[]requiredinclude_startingbooleanrequired
editablebooleanrequiredIts text can change (nobody acknowledged it yet).
urgent_reasonstring | nullrequiredMarked 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 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"}'const res = await fetch('https://api.bizisy.com/v1/org/announcements.withdraw', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"id": "an1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/announcements.withdraw",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"id": "an1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_deleteon HR Assistant, My Workplace- Preview
?dry_run=trueruns 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 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"}'const res = await fetch('https://api.bizisy.com/v1/org/announcements.delete', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"id": "an2"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/announcements.delete",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"id": "an2",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_reporton HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
idstringrequiredformat"json" | "csv"
Returns
fingerprintstringrequiredrowsobject[]required7 fields
personobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
teamstring | nullrequiredleftbooleanrequiredNo longer works here (HR only).
seen_atstring | nullrequiredacknowledged_atstring | nullrequiredvia"app" | "kiosk"requiredfingerprintstring | nullrequired
csvstring | nullrequiredfilenamestringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/org/announcements.report', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"id": "an1",
"format": "csv"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/announcements.report",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"id": "an1",
"format": "csv",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_feedon My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
itemsobject[]required10 fields
idstringrequiredtitlestringrequiredbodystringrequiredpublished_atstringrequiredauthorobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
requires_ackbooleanrequiredack_duestring | nullrequiredacknowledged_atstring | nullrequiredseenbooleanrequiredoverduebooleanrequired
to_acknowledgeintegerrequiredunseenintegerrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/announcements.feed \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/announcements.feed', {
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);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/announcements.feed",
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"]){
"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_readon My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
idstringrequired
Returns
10 fields
idstringrequiredtitlestringrequiredbodystringrequiredpublished_atstringrequiredauthorobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
requires_ackbooleanrequiredack_duestring | nullrequiredacknowledged_atstring | nullrequiredseenbooleanrequiredoverduebooleanrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/announcements.read \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"id":"an1"}'const res = await fetch('https://api.bizisy.com/v1/org/announcements.read', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"id": "an1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/announcements.read",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"id": "an1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_seenon My Workplace, HR Assistant- Preview
?dry_run=trueruns 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 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"}'const res = await fetch('https://api.bizisy.com/v1/org/announcements.seen', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"id": "an1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/announcements.seen",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"id": "an1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_acknowledgeon My Workplace, HR Assistant- Preview
?dry_run=trueruns 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 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"}'const res = await fetch('https://api.bizisy.com/v1/org/announcements.acknowledge', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"id": "an1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/announcements.acknowledge",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"id": "an1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
managers_postbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/announcements.settings.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/announcements.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);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/announcements.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"]){
"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_updateon HR Assistant- Preview
?dry_run=trueruns 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 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}'const res = await fetch('https://api.bizisy.com/v1/org/announcements.settings.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"managers_post": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/announcements.settings.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"managers_post": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"managers_post": true
}
}Something missing or wrong on this page? Write to hello@bizisy.com.