API reference

Home and reminders

What needs attention today and the reminder emails before dates come up.

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

Home summary (what needs attention)#

POST/v1/org/home.summaryRead

What needs an HR person's attention today, as on Bizisy's Manage Home. headcount: people employed today and month-end headcount for the last 12 months (this month as of today). joining_this_month: employment periods starting this month. leaving_soon: last days in the next 60 days. invites: pending (open) invites of current people, and current people with neither a login nor an invite. needs: approvals (count of change requests waiting for your decision, which you approve in Bizisy; always first), first_day (someone starting within 60 days who has not been invited), probation_ends (within 60 days), offboard (last day within 60 days; count = people still reporting to them after it), move_roles (open roles that report to someone leaving or gone: count and position ids; move them with org_positions_update), no_manager (people hired into an open role who still have no manager: count and person ids), contract_ends (fixed-term and similar contracts ending within 90 days), invite_people (count and person ids), unit_heads (units without a team lead: count and unit ids), personal_details (how many current people have no emergency contact or home address; app only). Dated items come first, by date. coming: the next 60 days of starts, last days, probation and contract ends and scheduled job changes. positions: how many open positions are open, on hold and draft, and how many open ones are past their target start date (list them with org_positions_list). checklists: open onboarding, offboarding and custom checklists with their progress (done, skipped, total) and how many open tasks are overdue. tasks: your own checklist tasks (HR tasks included) due within 7 days or overdue; tick them with org_checklists_tasks_set_status. Other items disappear when the data changes; there is no done or snooze. Names and titles are public; job details follow the usual job tier; no private or pay data. Owners, admins and HR.

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

Input

No input: send {}.

Returns

10 fields

as_ofstringrequired
headcountobjectrequired
2 fields
- nowintegerrequired
- monthsobject[]required
  2 fields
  - monthstringrequired
  - headcountintegerrequired
joining_this_monthobject[]required
2 fields
- personobjectrequired
  4 fields
  - idstringrequired
  - namestringrequired
  - titlestring | nullrequired
  - photo_urlstring | nullrequired
- datestringrequired
leaving_soonobject[]required
2 fields
- personobjectrequired
  4 fields
  - idstringrequired
  - namestringrequired
  - titlestring | nullrequired
  - photo_urlstring | nullrequired
- datestringrequired
invitesobjectrequired
2 fields
- pendingintegerrequired
- not_invitedintegerrequired
needsobject[]required
7 fields
- kindstring (enum)required
  One of: approvals, first_day, probation_ends, offboard, move_roles, contract_ends, invite_people, unit_heads, personal_details, no_manager.
- datestring | nullrequired
- personobject | nullrequired
  4 fields
  - idstringrequired
  - namestringrequired
  - titlestring | nullrequired
  - photo_urlstring | nullrequired
- managerobject | nullrequired
  4 fields
  - idstringrequired
  - namestringrequired
  - titlestring | nullrequired
  - photo_urlstring | nullrequired
- countinteger | nullrequired
- idsstring[]required
- contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
comingobject[]required
5 fields
- kind"starts" | "last_day" | "probation_ends" | "contract_ends" | "job_change"required
- datestringrequired
- personobjectrequired
  4 fields
  - idstringrequired
  - namestringrequired
  - titlestring | nullrequired
  - photo_urlstring | nullrequired
- reasonstring | nullrequired
- titlestring | nullrequired
positionsobjectrequired
4 fields
- openintegerrequired
- on_holdintegerrequired
- draftintegerrequired
- past_targetintegerrequired
checklistsobjectrequired
3 fields
- openintegerrequired
- overdue_tasksintegerrequired
- runsobject[]required
  6 fields
  - idstringrequired
  - namestringrequired
  - kind"onboarding" | "offboarding" | "custom"required
  - personobjectrequired
    4 fields
    idstringrequired
    namestringrequired
    titlestring | nullrequired
    photo_urlstring | nullrequired
  - anchor_datestringrequired
  - progressobjectrequired
    3 fields
    doneintegerrequired
    skippedintegerrequired
    totalintegerrequired
tasksobject[]required
17 fields
- idstringrequired
- titlestringrequired
- descriptionstring | nullrequired
- link_urlstring | nullrequired
- assigneeobjectrequired
  2 fields
  - type"hr" | "manager" | "person" | "member"required
  - personobject | nullrequired
    4 fields
    idstringrequired
    namestringrequired
    titlestring | nullrequired
    photo_urlstring | nullrequired
- manager_missingbooleanrequired
- offset_daysintegerrequired
- due_datestringrequired
- visible_fromstring | nullrequired
- status"open" | "done" | "skipped"required
- resolved_atstring | nullrequired
- resolved_byobject | nullrequired
  4 fields
  - idstringrequired
  - namestringrequired
  - titlestring | nullrequired
  - photo_urlstring | nullrequired
- skip_reasonstring | nullrequired
- commentsobject[]required
  4 fields
  - idstringrequired
  - authorobject | nullrequired
    4 fields
    idstringrequired
    namestringrequired
    titlestring | nullrequired
    photo_urlstring | nullrequired
  - textstringrequired
  - atstringrequired
- canobjectrequired
  4 fields
  - tickbooleanrequired
  - skipbooleanrequired
  - reassignbooleanrequired
  - commentbooleanrequired
- runobjectrequired
  5 fields
  - idstringrequired
  - namestringrequired
  - kind"onboarding" | "offboarding" | "custom"required
  - status"open" | "completed" | "cancelled"required
  - anchor_datestring | nullrequired
- personobjectrequired
  4 fields
  - idstringrequired
  - namestringrequired
  - titlestring | nullrequired
  - photo_urlstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl

curl https://api.bizisy.com/v1/org/home.summary \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Node

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

Python

import os
import requests

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

Response

{
  "data": {
    "as_of": "2026-10-04",
    "headcount": {
      "now": 11,
      "months": [
        {
          "month": "2026-09",
          "headcount": 11
        },
        {
          "month": "2026-10",
          "headcount": 11
        }
      ]
    },
    "joining_this_month": [
      {
        "person": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "date": "2026-10-20"
      }
    ],
    "leaving_soon": [
      {
        "person": {
          "id": "p3",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "date": "2026-11-30"
      }
    ],
    "invites": {
      "pending": 1,
      "not_invited": 3
    },
    "needs": [
      {
        "kind": "first_day",
        "date": "2026-10-20",
        "person": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "manager": {
          "id": "p1",
          "name": "Ana Ferreira",
          "title": "CEO",
          "photo_url": null
        },
        "count": null,
        "ids": [],
        "contract_type": null
      },
      {
        "kind": "contract_ends",
        "date": "2026-12-15",
        "person": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "manager": null,
        "count": null,
        "ids": [],
        "contract_type": "fixed_term"
      },
      {
        "kind": "unit_heads",
        "date": null,
        "person": null,
        "manager": null,
        "count": 1,
        "ids": [
          "u2"
        ],
        "contract_type": null
      },
      {
        "kind": "move_roles",
        "date": "2026-11-30",
        "person": {
          "id": "p3",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "manager": null,
        "count": 1,
        "ids": [
          "pos1"
        ],
        "contract_type": null
      },
      {
        "kind": "no_manager",
        "date": null,
        "person": null,
        "manager": null,
        "count": 1,
        "ids": [
          "p9"
        ],
        "contract_type": null
      }
    ],
    "coming": [
      {
        "kind": "job_change",
        "date": "2026-11-01",
        "person": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "reason": "promotion",
        "title": "Senior Engineer"
      }
    ],
    "positions": {
      "open": 3,
      "on_hold": 1,
      "draft": 2,
      "past_target": 1
    },
    "checklists": {
      "open": 1,
      "overdue_tasks": 0,
      "runs": [
        {
          "id": "r1",
          "name": "Onboarding",
          "kind": "onboarding",
          "person": {
            "id": "p2",
            "name": "Rui Costa",
            "title": "CTO",
            "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
          },
          "anchor_date": "2026-10-20",
          "progress": {
            "done": 1,
            "skipped": 0,
            "total": 10
          }
        }
      ]
    },
    "tasks": [
      {
        "id": "t1",
        "title": "Prepare the employment contract",
        "description": "Send it for signature before the first day.",
        "link_url": null,
        "assignee": {
          "type": "manager",
          "person": {
            "id": "p1",
            "name": "Ana Ferreira",
            "title": "CEO",
            "photo_url": null
          }
        },
        "manager_missing": false,
        "offset_days": -10,
        "due_date": "2026-10-10",
        "visible_from": null,
        "status": "done",
        "resolved_at": "2026-10-04T10:00:00.000Z",
        "resolved_by": {
          "id": "p1",
          "name": "Ana Ferreira",
          "title": "CEO",
          "photo_url": null
        },
        "skip_reason": null,
        "comments": [
          {
            "id": "c1",
            "author": {
              "id": "p1",
              "name": "Ana Ferreira",
              "title": "CEO",
              "photo_url": null
            },
            "text": "Sent for signature",
            "at": "2026-10-04T10:00:00.000Z"
          }
        ],
        "can": {
          "tick": true,
          "skip": true,
          "reassign": true,
          "comment": true
        },
        "run": {
          "id": "r1",
          "name": "Onboarding",
          "kind": "onboarding",
          "status": "open",
          "anchor_date": "2026-10-20"
        },
        "person": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        }
      }
    ]
  }
}

Get reminder settings#

POST/v1/org/reminders.getRead

Returns the HR reminder email settings: probation ending (lead_days before the probation end date), fixed-term contract ending (lead_days before the contract end date), upcoming starters (lead_days before the first day, plus on_first_day) and work anniversaries (on the day). Each has enabled and its recipients: notify_hr (every owner, admin and HR member), notify_manager (the person's manager), and for anniversaries notify_person. Defaults: probation 14 days, contracts 30, starters 7 plus the first day, all on and to HR and the manager; anniversaries off. Emails go out once a day. Owners, admins and HR only.

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

Input

No input: send {}.

Returns

probationobjectrequired
4 fields
- enabledbooleanrequired
- lead_daysintegerrequired
  From 0 to 90.
- notify_hrbooleanrequired
- notify_managerbooleanrequired
contract_endobjectrequired
4 fields
- enabledbooleanrequired
- lead_daysintegerrequired
  From 0 to 180.
- notify_hrbooleanrequired
- notify_managerbooleanrequired
startersobjectrequired
5 fields
- enabledbooleanrequired
- lead_daysintegerrequired
  From 1 to 60.
- on_first_daybooleanrequired
- notify_hrbooleanrequired
- notify_managerbooleanrequired
anniversariesobjectrequired
4 fields
- enabledbooleanrequired
- notify_hrbooleanrequired
- notify_managerbooleanrequired
- notify_personbooleanrequired
updated_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl

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

Node

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

Python

import os
import requests

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

Response

{
  "data": {
    "probation": {
      "enabled": true,
      "lead_days": 14,
      "notify_hr": true,
      "notify_manager": true
    },
    "contract_end": {
      "enabled": true,
      "lead_days": 30,
      "notify_hr": true,
      "notify_manager": true
    },
    "starters": {
      "enabled": true,
      "lead_days": 7,
      "on_first_day": true,
      "notify_hr": true,
      "notify_manager": true
    },
    "anniversaries": {
      "enabled": false,
      "notify_hr": true,
      "notify_manager": true,
      "notify_person": false
    },
    "updated_at": null
  }
}

Change reminder settings#

POST/v1/org/reminders.updateWrite

Changes the HR reminder email settings (see org_reminders_get). Send only what changes, per reminder: probation, contract_end, starters and anniversaries, each with enabled, lead_days (probation 0–90, contract_end 0–180, starters 1–60; anniversaries have none), on_first_day (starters), notify_hr, notify_manager and notify_person (anniversaries). A reminder that is on must go to at least one recipient. Changes apply from the next daily run. The company must be set up first (org_setup_init). Use dry_run first. Owners, admins and HR only.

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

Input

probationobject
4 fields
- enabledboolean
- lead_daysinteger
  From 0 to 90.
- notify_hrboolean
- notify_managerboolean
contract_endobject
4 fields
- enabledboolean
- lead_daysinteger
  From 0 to 180.
- notify_hrboolean
- notify_managerboolean
startersobject
5 fields
- enabledboolean
- lead_daysinteger
  From 1 to 60.
- on_first_dayboolean
- notify_hrboolean
- notify_managerboolean
anniversariesobject
4 fields
- enabledboolean
- notify_hrboolean
- notify_managerboolean
- notify_personboolean

Returns

probationobjectrequired
4 fields
- enabledbooleanrequired
- lead_daysintegerrequired
  From 0 to 90.
- notify_hrbooleanrequired
- notify_managerbooleanrequired
contract_endobjectrequired
4 fields
- enabledbooleanrequired
- lead_daysintegerrequired
  From 0 to 180.
- notify_hrbooleanrequired
- notify_managerbooleanrequired
startersobjectrequired
5 fields
- enabledbooleanrequired
- lead_daysintegerrequired
  From 1 to 60.
- on_first_daybooleanrequired
- notify_hrbooleanrequired
- notify_managerbooleanrequired
anniversariesobjectrequired
4 fields
- enabledbooleanrequired
- notify_hrbooleanrequired
- notify_managerbooleanrequired
- notify_personbooleanrequired
updated_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl

curl https://api.bizisy.com/v1/org/reminders.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "probation": {
    "enabled": true,
    "lead_days": 14,
    "notify_hr": true,
    "notify_manager": false
  },
  "contract_end": {
    "enabled": false
  },
  "starters": {
    "lead_days": 5,
    "on_first_day": false
  },
  "anniversaries": {
    "enabled": true,
    "notify_person": true
  }
}'

Node

const res = await fetch('https://api.bizisy.com/v1/org/reminders.update', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "probation": {
      "enabled": true,
      "lead_days": 14,
      "notify_hr": true,
      "notify_manager": false
    },
    "contract_end": {
      "enabled": false
    },
    "starters": {
      "lead_days": 5,
      "on_first_day": false
    },
    "anniversaries": {
      "enabled": true,
      "notify_person": true
    }
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os, uuid
import requests

res = requests.post(
    "https://api.bizisy.com/v1/org/reminders.update",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "probation": {
            "enabled": True,
            "lead_days": 14,
            "notify_hr": True,
            "notify_manager": False,
        },
        "contract_end": {
            "enabled": False,
        },
        "starters": {
            "lead_days": 5,
            "on_first_day": False,
        },
        "anniversaries": {
            "enabled": True,
            "notify_person": True,
        },
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

Response

{
  "data": {
    "probation": {
      "enabled": true,
      "lead_days": 14,
      "notify_hr": true,
      "notify_manager": true
    },
    "contract_end": {
      "enabled": true,
      "lead_days": 30,
      "notify_hr": true,
      "notify_manager": true
    },
    "starters": {
      "enabled": true,
      "lead_days": 7,
      "on_first_day": true,
      "notify_hr": true,
      "notify_manager": true
    },
    "anniversaries": {
      "enabled": true,
      "notify_hr": true,
      "notify_manager": true,
      "notify_person": false
    },
    "updated_at": "2026-10-04T10:00:00.000Z"
  }
}

List upcoming reminders#

POST/v1/org/reminders.upcomingRead

Lists what the enabled HR reminders cover in the next days (default 30, at most 90), soonest first: probation endings, fixed-term contract endings, people starting (start_soon, or start_today on their first day) and work anniversaries (with years). Each item has the date, remind_on (the day the email goes out, or today if it is already due), the person (name, title) and their manager. Owners, admins and HR only. Use it to answer "what is coming up" or to check the reminder settings do what the user expects.

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

Input

daysinteger
From 1 to 90. Default 30.

Returns

todaystringrequired
daysintegerrequired
itemsobject[]required
6 fields
- kind"probation_end" | "contract_end" | "start_soon" | "start_today" | "anniversary"required
- datestringrequired
- remind_onstringrequired
- yearsinteger | nullrequired
- personobjectrequired
  4 fields
  - idstringrequired
  - namestringrequired
  - titlestring | nullrequired
  - photo_urlstring | nullrequired
- managerobject | nullrequired
  4 fields
  - idstringrequired
  - namestringrequired
  - titlestring | nullrequired
  - photo_urlstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl

curl https://api.bizisy.com/v1/org/reminders.upcoming \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"days":60}'

Node

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

Python

import os
import requests

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

Response

{
  "data": {
    "today": "2026-10-04",
    "days": 60,
    "items": [
      {
        "kind": "start_soon",
        "date": "2026-10-11",
        "remind_on": "2026-10-04",
        "years": null,
        "person": {
          "id": "p5",
          "name": "Inês Martins",
          "title": "Account Executive",
          "photo_url": null
        },
        "manager": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        }
      },
      {
        "kind": "probation_end",
        "date": "2026-10-18",
        "remind_on": "2026-10-04",
        "years": null,
        "person": {
          "id": "p1",
          "name": "Ana Ferreira",
          "title": "Engineer",
          "photo_url": null
        },
        "manager": null
      },
      {
        "kind": "anniversary",
        "date": "2026-10-20",
        "remind_on": "2026-10-20",
        "years": 3,
        "person": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "manager": null
      }
    ]
  }
}

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