API reference
Home, reminders and renewals
What needs attention today, the reminder emails before dates come up, company renewals and occupational health-check dates.
19 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 and time off requests waiting for your decision, which you approve in Bizisy; always first), change_drafts (count of change sets saved for review with org_changes_draft, applied in Bizisy), 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), titles_review (job titles added by an AI, an import or an API key that HR has not looked at: count and title ids; mark them reviewed with org_titles_update), titles_duplicates (job titles that look like the same job: count and title ids; see org_titles_suggestions, then merge or keep them apart), pay_gap_assessment (a final pay gap report with categories whose gap of 5% or more is not justified by objective factors or whose remedy date passed, so a joint pay assessment may be due: count of categories, report {id, year, legal_entity}; app only), pay_requests (requests about pay levels waiting for HR's written answer: count, request ids, date = the earliest due date; answer them in Bizisy, Pay equity → Requests; app only), pay_report_due (a legal entity whose Art. 9 pay gap report on last year is due, from 1 March until a final report exists: due_report {legal_entity_id, legal_entity, year}, date = the due date, count = its average workers; app only), outsider_access (owners and admins: an outsider's access ends within 14 days; date = its end, person = their contact card; extend it in Bizisy, Members), saved_drafts (count of processes saved for later that you may carry on, in Bizisy: People → Saved for later), structure_failed (team changes scheduled for a day that has come that could not apply in the last 14 days: count; see org_units_changes with status all), directory_confirm (Google Workspace / Microsoft Entra account changes waiting for a person to confirm: new accounts, reactivations, and suspensions held as the first change since a link or as many at once: count; see org_directory_preview), directory_failed (directory changes that could not be sent, or a directory connection that stopped working: count), okta_confirm (Okta account changes waiting for a person to confirm, as directory_confirm: count; see org_okta_preview), okta_failed (Okta account changes that could not be sent: count), hires_review (candidates hired in Teamtailor or Greenhouse waiting for HR to add, link or dismiss: count; see org_ats_hires_list), chat_failed (Slack or Teams announcements that could not be posted and wait for Try again, or a connection that stopped working, including Bizisy removed from the Slack workspace: count; see org_chat_status and org_chat_preview), integration_failing (connected tools whose access stopped working or that keep failing: count and connector ids; see integrations_connections_list; an owner or admin fixes them in Integrations), country_notices (statutory hire and leave notices due, overdue or refused: count, date = the earliest due date; see country_notices_list with open true), country_report_due (a yearly statutory report in its window, e.g. Portugal's Relatório Único: due_report {legal_entity_id, legal_entity, year}, date = its due date), spend_people (spend tools — Pleo, Moss, Payhawk, Spendesk — with changes waiting for a person, changes that failed, or things to do in the tool itself such as deactivating a leaver: count and connector ids; see org_spend_preview), link_requests (logins without a person record that asked to be linked: count; link them with platform_members_link_person, in Bizisy Members), invited_waiting (people invited by email who are still waiting for their details: count and person ids; fill them in with org_people_set_details), invited_stale (the same, invited more than 30 days ago: remind them or withdraw with org_people_withdraw), equipment_return (owners, admins and HR: people whose last day is within 14 days or passed in the last 30 who still hold equipment from the register: count, person ids, date = the earliest last day; see assets_list with person_id and take items back with assets_return), devices_review (synced devices from Jamf Pro, Intune, Kandji or Workwize to look at — a user no one has, someone else holding it in Bizisy, or gone from the tool: count; assets_list with review true), role_requests (roles managers asked for from My workspace, still draft positions: count and position ids; open them with org_positions_update status open to approve, or cancel to decline), imports (owners, admins and HR: the most recent import run that is working, ready to apply, stopped, or has rows to fix: import_run {id, name, status, done, total, error}, count = rows to fix or to apply; follow it with org_imports_get), moves (owners, admins and HR: the most recent move from another HR tool that is working, stopped, checked, read or imported with rows to fix: move_run {id, tool, status, done, total, problems, error}, count = rows to fix; follow it with migration_get), payroll_lock (a pay period that ended and is not locked: period {id, legal_entity, start, end}, date = its last day; lock it with payroll_periods_lock; app only), payslips_unmatched (payslips uploaded for a locked period that are not matched to a person yet: count; assign them in Bizisy, Payroll; app only), accountant_access (owners: partner firms — accountants, HR consultants, implementation partners — asking for partner access: count and grant ids; an owner approves or declines in Bizisy, Settings → Partner access; app only), credits_low (owners and admins, in the app: emails or AI credits at 80% or 100% of this month's included amount with nothing bought left, or storage 90% or 100% full: credit {resource email, ai or storage, level, left (credits; bytes for storage), path}; buy in Bizisy, Settings → Plan & billing; see platform_usage_get), plan_limit (owners and admins: the company has 8 or 9 active people, close to the Free plan's limit of 9: count = active people; from 10, Core is charged per active person; nothing is blocked; see platform_plan_get), dpa_due (owners: the current data processing agreement is not accepted yet; an owner accepts it in Bizisy, Settings → Data & privacy; see platform_dpa_get; app only), candidates_overdue (Hiring on: candidates past the answer promise in the jobs you are on the hiring team of: count, job ids, date = the oldest date passed; see hiring_applications_list with overdue true), referral_bonuses_due (Hiring on: referral bonuses due to pay: count; see hiring_referrals_list with bonus due; app only), interviews_to_rebook (Hiring on: interviews to arrange again in the jobs you are on the hiring team of — offers nobody picked within 48 hours, candidates who asked for other times or cancelled: count and job ids; see hiring_interviews_list), feedback_overdue (Hiring on: interview feedback past its due time in the jobs you are on the hiring team of — interviewers who have not sent theirs: count and job ids; see hiring_applications_get feedback_by_step), finish_hire (Hiring on, owners, admins and HR: candidates who accepted an offer but could not be added to People by themselves: count and offer ids; finish the hire in Bizisy from hiring_applications_hire_draft; app only), offers_awaiting_approval (Hiring on: job offers waiting for your approval: count and offer ids; see hiring_offers_list with waiting_for_me true; approve in Bizisy), offers_expiring (Hiring on: sent job offers ending within 2 days in the jobs you are on the hiring team of: count, offer ids, date = the earliest last day), documents_prepared (Documents on, owners, admins and HR: written statements and change notices Bizisy prepared that wait for HR, with a legal deadline: count, date = the earliest deadline, overdue when it passed; see documents_prepared_list), training_reports (Training on, owners, admins and HR: training people reported themselves, waiting to be confirmed or declined: count; see training_records_list with status pending), training_below (Training on, from 1 October: people below their training hours for the year where a country rule applies, e.g. Portugal's 40 hours: count and person ids; see training_balance_summary), training_below carries training {year}; training_overdue (Training on, owners, admins and HR: people with mandatory training past its due date: count and person ids, date = the earliest due date, teams = the teams with the most of them; see training_compliance_list with status overdue), training_share (Training on, from 1 October: fewer people trained this year than the legal minimum share, e.g. 10% in Portugal: count = people trained, training {year, trained, people, min_share}; see training_balance_summary), shifts_publish_by (Shifts on, for rotas you plan: rota weeks not published yet, date = the day to publish the first by so it goes out with the notice, count = weeks, ids = rota ids, shift {rota_id, rota, week, overdue}; publish in Bizisy), shifts_open (Shifts on: open shifts in the next 14 days on rotas you plan, including those opened by approved leave: count; see shifts_week_get and shifts_suggest), shifts_over_48 (Shifts on: people planned over 48 hours in a week, this week or the next 3: count; see shifts_week_check), assistant_allowance (Ask HR, early access: this month's share of AI credits for Ask HR is used up, so people can't ask until credits are bought or the share is raised in Settings → Ask HR; see assistant_usage_get), assistant_handoffs (owners, admins and HR: questions people chose to hand to HR after Ask HR routed them as sensitive — harassment, discrimination, a crisis, safety: count only; read them in Bizisy, Manage → Ask HR; app only), talent_reviews_to_write (Performance and talent on, managers: reviews of your reports waiting for you: count and review ids; write them in Bizisy), talent_signoffs (managers: reviews waiting for your second-level sign-off: count and review ids), talent_nominations (managers: peer nominations of your reports to approve: count and review ids), talent_potential (managers: reports whose potential the cycle asks for: count and person ids), talent_reviews_overdue (HR: active review cycles with reviews past a due date: count and cycle ids; see talent_cycles_get), talent_cycles_launching (HR: cycles still creating their reviews: count and cycle ids), talent_sessions_lock (HR and facilitators: calibration sessions open past the calibrate-by date: count and session ids), talent_positions_uncovered (HR: key positions with high impact and high risk and no ready-now successor: count and position ids), talent_successors_left (HR: key positions whose successor left: count and position ids), module_setup (owners, admins and HR: a switched-on module whose setup is unfinished (count = steps left) or waits on someone outside HR (count = how many): setup {module, path, steps_done, steps_total, done, waiting}; see platform_setup_get). Items of a module (payroll, pay equity, recruiting tools, spend tools) show only while the company has it switched on (Settings → Modules; every module is included). 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_summaryon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
10 fields
as_ofstringrequiredheadcountobjectrequired2 fields
nowintegerrequiredmonthsobject[]required2 fields
monthstringrequiredheadcountintegerrequired
joining_this_monthobject[]required2 fields
personobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
datestringrequired
leaving_soonobject[]required2 fields
personobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
datestringrequired
invitesobjectrequired2 fields
pendingintegerrequirednot_invitedintegerrequired
needsobject[]required17 fields
kindstring (enum)requiredOne of:
documents_expiring,renewals_due,health_checks_due,approvals,change_drafts,first_day,probation_ends,offboard,move_roles,contract_ends,invite_people,unit_heads,personal_details,no_manager,titles_review,titles_duplicates,pay_gap_assessment,pay_requests,pay_report_due,outsider_access,saved_drafts,imports,moves,invited_waiting,invited_stale,structure_failed,link_requests,directory_confirm,directory_failed,chat_failed,integration_failing,spend_people,role_requests,equipment_return,devices_review,payroll_lock,payslips_unmatched,country_notices,country_report_due,vacation_map_due,vacation_map_changed,okta_confirm,okta_failed,hires_review,plan_limit,dpa_due,accountant_access,tell_leaver,bank_review,one_on_one_exemptions,candidates_overdue,referral_bonuses_due,interviews_to_rebook,feedback_overdue,offers_awaiting_approval,offers_expiring,finish_hire,documents_prepared,credits_low,training_reports,training_below,training_share,training_overdue,shifts_publish_by,shifts_open,shifts_over_48,assistant_allowance,assistant_handoffs,talent_reviews_overdue,talent_cycles_launching,talent_reviews_to_write,talent_signoffs,talent_nominations,talent_sessions_lock,talent_positions_uncovered,talent_successors_left,talent_potential,comp_proposals_due,comp_to_review,comp_stale,comp_launching,comp_sign_off,comp_sent_back,comp_bonus_to_approve,comp_bonus_adjust,insights_high_unreviewed,insights_explanations,insights_objections,insights_backtest,module_setup.datestring | nullrequiredpersonobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
countinteger | nullrequiredidsstring[]requiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredreportobject3 fields
idstringrequiredyearintegerrequiredlegal_entitystringrequired
due_reportobject3 fields
legal_entity_idstringrequiredlegal_entitystringrequiredyearintegerrequired
import_runobject6 fields
idstringrequirednamestringrequiredstatusstring (enum)requiredOne of:
reading,mapping,checking,checked,applying,done,cancelled,failed.doneintegerrequiredtotalintegerrequirederrorstring | nullrequired
move_runobject7 fields
idstringrequiredtoolstringrequiredstatusstringrequireddoneintegerrequiredtotalintegerrequiredproblemsintegerrequirederrorstring | nullrequired
periodobject4 fields
idstringrequiredlegal_entitystringrequiredstartstringrequiredendstringrequired
creditobject4 fields
resource"email" | "ai" | "storage"requiredlevelintegerrequiredleftintegerrequiredpathstringrequired
trainingobject4 fields
yearintegerrequiredtrainedinteger | nullrequiredpeopleinteger | nullrequiredmin_sharenumber | nullrequired
teamsobject[]3 fields
idstring | nullrequirednamestringrequiredcountintegerrequired
shiftobject4 fields
rota_idstringrequiredrotastringrequiredweekstringrequiredoverduebooleanrequired
setupobject6 fields
modulestringrequiredpathstringrequiredsteps_doneintegerrequiredsteps_totalintegerrequireddonebooleanrequiredwaitingstring[]required
comingobject[]required5 fields
kind"starts" | "last_day" | "probation_ends" | "contract_ends" | "job_change"requireddatestringrequiredpersonobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
reasonstring | nullrequiredtitlestring | nullrequired
positionsobjectrequired4 fields
openintegerrequiredon_holdintegerrequireddraftintegerrequiredpast_targetintegerrequired
checklistsobjectrequired3 fields
openintegerrequiredoverdue_tasksintegerrequiredrunsobject[]required6 fields
idstringrequirednamestringrequiredkind"onboarding" | "offboarding" | "custom"requiredpersonobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
anchor_datestringrequiredprogressobjectrequired3 fields
doneintegerrequiredskippedintegerrequiredtotalintegerrequired
tasksobject[]required19 fields
idstringrequiredtitlestringrequireddescriptionstring | nullrequiredlink_urlstring | nullrequiredassigneeobjectrequired2 fields
type"hr" | "manager" | "person" | "member"requiredpersonobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
manager_missingbooleanrequireddone_when"profile" | "payroll" | "photo" | "invited" | "work_account" | "equipment" | stringrequiredoffset_daysintegerrequireddue_datestringrequiredvisible_fromstring | nullrequiredstatus"open" | "done" | "skipped"requiredresolved_atstring | nullrequiredresolved_byobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
skip_reasonstring | nullrequiredcommentsobject[]required4 fields
idstringrequiredauthorobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
textstringrequiredatstringrequired
canobjectrequired4 fields
tickbooleanrequiredskipbooleanrequiredreassignbooleanrequiredcommentbooleanrequired
externalobject | nullrequired12 fields
toolstring (enum)requiredOne of:
jira,linear,asana,monday,clickup,microsoft_todo,microsoft_planner,trello,notion,freshservice,zendesk,servicenow,talentlms,learning360,docebo,moodle,linkedin_learning.tool_namestringrequiredstate"sending" | "scheduled" | "not_connected" | "linked" | "error" | "not_sent"requiredkeystring | nullrequiredurlstring | nullrequiredstatus"open" | "done" | "skipped"requiredstatus_namestring | nullrequiredsynced_atstring | nullrequirederrorstring | nullrequiredwarningstring | nullrequiredsend_onstring | nullrequiredwherestringrequired
runobjectrequired5 fields
idstringrequirednamestringrequiredkind"onboarding" | "offboarding" | "custom"requiredstatus"open" | "completed" | "cancelled"requiredanchor_datestring | nullrequired
personobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/home.summary \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'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);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"]){
"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
},
{
"kind": "pay_gap_assessment",
"date": null,
"person": null,
"manager": null,
"count": 2,
"ids": [
"pr1"
],
"contract_type": null,
"report": {
"id": "pr1",
"year": 2025,
"legal_entity": "Acme Lda"
}
}
],
"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,
"done_when": null,
"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
},
"external": {
"tool": "jira",
"tool_name": "Jira",
"state": "linked",
"key": "IT-42",
"url": "https://acme.atlassian.net/browse/IT-42",
"status": "done",
"status_name": "Done",
"synced_at": "2026-10-04T10:00:00.000Z",
"error": null,
"warning": null,
"send_on": null,
"where": "IT · Task"
},
"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"
}
}
]
}
}Which Home I open on#
POST/v1/org/home.getRead
Which Home each Bizisy app opens on for you: manage (Overview = how the company is doing; To do = what needs HR's attention) and me (My team = your reporting line; Me = your own things). view is the one shown, chosen whether you picked it (else it is inferred: Overview for owners, admins and HR at the top of the org chart when someone else does HR; My team for anyone with direct reports), options the views you may use. manage is null without access to Manage. Change it with org_home_set.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
org_home_geton My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
manageobject | nullrequired3 fields
view"overview" | "todo"requiredchosenbooleanrequiredoptions"overview" | "todo"[]required
meobjectrequired3 fields
view"team" | "me"requiredchosenbooleanrequiredoptions"team" | "me"[]required
pinsobjectrequired2 fields
managestring[]requiredmestring[]required
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/home.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/home.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/home.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": {
"manage": {
"view": "overview",
"chosen": false,
"options": [
"overview",
"todo"
]
},
"me": {
"view": "team",
"chosen": false,
"options": [
"team",
"me"
]
},
"pins": {
"manage": [
"page:/approvals"
],
"me": []
}
}
}Choose which Home I open on#
POST/v1/org/home.setWrite
Saves which Home an app opens on for you: app manage with view overview or todo (overview needs the owner, admin or HR role), app me with view team or me (team needs direct reports). For you only, for this company. Refused (forbidden) for a view you can't use. Returns the result of org_home_get.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
org_home_seton My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
app"manage" | "me"requiredview"overview" | "todo" | "team" | "me"required
Returns
manageobject | nullrequired3 fields
view"overview" | "todo"requiredchosenbooleanrequiredoptions"overview" | "todo"[]required
meobjectrequired3 fields
view"team" | "me"requiredchosenbooleanrequiredoptions"team" | "me"[]required
pinsobjectrequired2 fields
managestring[]requiredmestring[]required
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/home.set \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"app":"manage","view":"overview"}'const res = await fetch('https://api.bizisy.com/v1/org/home.set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"app": "manage",
"view": "overview"
}),
});
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/home.set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"app": "manage",
"view": "overview",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"manage": {
"view": "todo",
"chosen": true,
"options": [
"overview",
"todo"
]
},
"me": {
"view": "team",
"chosen": false,
"options": [
"team",
"me"
]
},
"pins": {
"manage": [],
"me": []
}
}
}Set my pinned pages and actions#
POST/v1/org/home.pins.setWrite
Saves the pages and actions pinned at the top of your sidebar (favourites) in one app: app manage or me, pins = the whole list in the order shown (at most 8; an empty list clears it). To pin, unpin or reorder, read the current list (org_home_get pins), then send it changed: e.g. to move a pin to the top, send the same ids with it first. Each id is page:/<path in the app> (e.g. page:/approvals, page:/settings/billing) or cmd:<command id> (e.g. cmd:act:add-person). Pinning never grants anything: the app shows only pins your role can still use. For you only, for this company. Returns the result of org_home_get.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
org_home_pins_seton My Workplace, HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
app"manage" | "me"requiredpinsstring[]requiredUp to 90 characters. Up to 16 items.
Returns
manageobject | nullrequired3 fields
view"overview" | "todo"requiredchosenbooleanrequiredoptions"overview" | "todo"[]required
meobjectrequired3 fields
view"team" | "me"requiredchosenbooleanrequiredoptions"team" | "me"[]required
pinsobjectrequired2 fields
managestring[]requiredmestring[]required
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/home.pins.set \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"app":"manage","pins":["page:/approvals","cmd:act:add-person"]}'const res = await fetch('https://api.bizisy.com/v1/org/home.pins.set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"app": "manage",
"pins": [
"page:/approvals",
"cmd:act:add-person"
]
}),
});
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/home.pins.set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"app": "manage",
"pins": [
"page:/approvals",
"cmd:act:add-person",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"manage": {
"view": "todo",
"chosen": true,
"options": [
"overview",
"todo"
]
},
"me": {
"view": "team",
"chosen": false,
"options": [
"team",
"me"
]
},
"pins": {
"manage": [
"page:/approvals",
"cmd:act:add-person"
],
"me": []
}
}
}Company overview#
POST/v1/org/home.overviewRead
How the company is doing, as on Bizisy's Manage Overview. headcount: employed today, on 1 January and at the end of each of the last 12 months (this month as of today; the same numbers as org_reports_headcount). year: joiners, leavers and starts this month for this calendar year. turnover: leavers ÷ average headcount over the last 12 months and the 12 before (null under one person). positions: open ones and those past their target start. pay: gross pay this month (yearly pay ÷ 12, monthly as is; hourly pay is left out and counted) per currency, only for currencies with at least 5 people and compared with the end of last month; status hidden over an API key or AI assistant and for anyone but owners, admins and HR, too_few when no currency reaches 5 people. It is an estimate of salaries only: no employer costs, bonuses or taxes. teams: people per top-level unit today (sub-teams roll up) and the change since 1 January. approvals_waiting: everything waiting for your decision (change requests and time off requests), the same count as org_approvals_list's waiting_for_me. leadership: your direct reports with how many people work under each. coming: starts and last days in the next 60 days. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_home_overviewon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
10 fields
as_ofstringrequiredheadcountobjectrequired3 fields
nowintegerrequiredstart_of_yearintegerrequiredmonthsobject[]required2 fields
monthstringrequiredheadcountintegerrequired
yearobjectrequired3 fields
joinersintegerrequiredleaversintegerrequiredstarting_this_monthintegerrequired
turnoverobjectrequired2 fields
last_12number | nullrequiredprevious_12number | nullrequired
positionsobjectrequired2 fields
openintegerrequiredpast_targetintegerrequired
payobjectrequired4 fields
status"ok" | "hidden" | "too_few"requiredhourly_excludedintegerrequiredother_currenciesintegerrequiredtotalsobject[]required4 fields
currencystringrequiredpeopleintegerrequiredmonthnumberrequiredprevious_monthnumber | nullrequired
teamsobject[]required3 fields
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
countintegerrequiredchangeintegerrequired
approvals_waitingintegerrequiredleadershipobject[]required4 fields
personobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
people_underintegerrequiredstartsstring | nullrequiredprobation_endstring | nullrequired
comingobject[]required5 fields
kind"starts" | "last_day" | "probation_ends" | "contract_ends" | "job_change"requireddatestringrequiredpersonobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
reasonstring | nullrequiredtitlestring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/home.overview \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/home.overview', {
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/home.overview",
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": {
"as_of": "2026-10-04",
"headcount": {
"now": 42,
"start_of_year": 37,
"months": [
{
"month": "2026-09",
"headcount": 41
},
{
"month": "2026-10",
"headcount": 42
}
]
},
"year": {
"joiners": 9,
"leavers": 3,
"starting_this_month": 2
},
"turnover": {
"last_12": 0.074,
"previous_12": 0.091
},
"positions": {
"open": 3,
"past_target": 1
},
"pay": {
"status": "ok",
"hourly_excluded": 0,
"other_currencies": 1,
"totals": [
{
"currency": "EUR",
"people": 41,
"month": 148000,
"previous_month": 142300
}
]
},
"teams": [
{
"unit": {
"id": "u2",
"name": "Engineering"
},
"count": 18,
"change": 3
},
{
"unit": null,
"count": 1,
"change": 0
}
],
"approvals_waiting": 2,
"leadership": [
{
"person": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"people_under": 9,
"starts": null,
"probation_end": null
}
],
"coming": [
{
"kind": "starts",
"date": "2026-10-15",
"person": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"reason": null,
"title": null
}
]
}
}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), work anniversaries (on the day) and leavers (lead_days before the last day of someone who has not been told about it yet). 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, leavers 7, 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_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
9 fields
probationobjectrequired4 fields
enabledbooleanrequiredlead_daysintegerrequiredFrom 0 to 90.
notify_hrbooleanrequirednotify_managerbooleanrequired
contract_endobjectrequired4 fields
enabledbooleanrequiredlead_daysintegerrequiredFrom 0 to 180.
notify_hrbooleanrequirednotify_managerbooleanrequired
startersobjectrequired5 fields
enabledbooleanrequiredlead_daysintegerrequiredFrom 1 to 60.
on_first_daybooleanrequirednotify_hrbooleanrequirednotify_managerbooleanrequired
anniversariesobjectrequired4 fields
enabledbooleanrequirednotify_hrbooleanrequirednotify_managerbooleanrequirednotify_personbooleanrequired
documentsobjectrequired4 fields
enabledbooleanrequiredlead_daysintegerrequiredFrom 0 to 180.
notify_hrbooleanrequirednotify_managerbooleanrequired
renewalsobjectrequired3 fields
enabledbooleanrequiredlead_daysintegerrequiredFrom 0 to 180.
notify_hrtruerequired
leaversobjectrequired4 fields
enabledbooleanrequiredlead_daysintegerrequiredFrom 0 to 60.
notify_hrbooleanrequirednotify_managerbooleanrequired
health_checksobjectrequired4 fields
enabledbooleanrequiredlead_daysintegerrequiredFrom 0 to 180.
notify_hrtruerequiredinterval_monthsinteger | nullrequiredFrom 1 to 120.
updated_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/reminders.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'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);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"]){
"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
},
"leavers": {
"enabled": true,
"lead_days": 7,
"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
},
"documents": {
"enabled": true,
"lead_days": 30,
"notify_hr": true,
"notify_manager": false
},
"renewals": {
"enabled": true,
"lead_days": 30,
"notify_hr": true
},
"health_checks": {
"enabled": false,
"lead_days": 30,
"notify_hr": true,
"interval_months": null
},
"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, anniversaries and leavers, each with enabled, lead_days (probation 0–90, contract_end 0–180, starters 1–60, leavers 0–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_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
probationobject4 fields
enabledbooleanlead_daysintegerFrom 0 to 90.
notify_hrbooleannotify_managerboolean
contract_endobject4 fields
enabledbooleanlead_daysintegerFrom 0 to 180.
notify_hrbooleannotify_managerboolean
startersobject5 fields
enabledbooleanlead_daysintegerFrom 1 to 60.
on_first_daybooleannotify_hrbooleannotify_managerboolean
anniversariesobject4 fields
enabledbooleannotify_hrbooleannotify_managerbooleannotify_personboolean
documentsobject4 fields
enabledbooleanlead_daysintegerFrom 0 to 180.
notify_hrbooleannotify_managerboolean
renewalsobject2 fields
enabledbooleanlead_daysintegerFrom 0 to 180.
health_checksobject3 fields
enabledbooleanlead_daysintegerFrom 0 to 180.
interval_monthsinteger | nullFrom 1 to 120.
leaversobject4 fields
enabledbooleanlead_daysintegerFrom 0 to 60.
notify_hrbooleannotify_managerboolean
Returns
9 fields
probationobjectrequired4 fields
enabledbooleanrequiredlead_daysintegerrequiredFrom 0 to 90.
notify_hrbooleanrequirednotify_managerbooleanrequired
contract_endobjectrequired4 fields
enabledbooleanrequiredlead_daysintegerrequiredFrom 0 to 180.
notify_hrbooleanrequirednotify_managerbooleanrequired
startersobjectrequired5 fields
enabledbooleanrequiredlead_daysintegerrequiredFrom 1 to 60.
on_first_daybooleanrequirednotify_hrbooleanrequirednotify_managerbooleanrequired
anniversariesobjectrequired4 fields
enabledbooleanrequirednotify_hrbooleanrequirednotify_managerbooleanrequirednotify_personbooleanrequired
documentsobjectrequired4 fields
enabledbooleanrequiredlead_daysintegerrequiredFrom 0 to 180.
notify_hrbooleanrequirednotify_managerbooleanrequired
renewalsobjectrequired3 fields
enabledbooleanrequiredlead_daysintegerrequiredFrom 0 to 180.
notify_hrtruerequired
leaversobjectrequired4 fields
enabledbooleanrequiredlead_daysintegerrequiredFrom 0 to 60.
notify_hrbooleanrequirednotify_managerbooleanrequired
health_checksobjectrequired4 fields
enabledbooleanrequiredlead_daysintegerrequiredFrom 0 to 180.
notify_hrtruerequiredinterval_monthsinteger | nullrequiredFrom 1 to 120.
updated_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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
}
}'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);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"]){
"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
},
"leavers": {
"enabled": true,
"lead_days": 7,
"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
},
"documents": {
"enabled": true,
"lead_days": 30,
"notify_hr": true,
"notify_manager": false
},
"renewals": {
"enabled": true,
"lead_days": 30,
"notify_hr": true
},
"health_checks": {
"enabled": false,
"lead_days": 30,
"notify_hr": true,
"interval_months": null
},
"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), work anniversaries (with years) and people to tell about their last day (tell_leaver: the date is the last day; never shown to the person themselves). 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_upcomingon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
daysintegerFrom 1 to 90. Default
30.
Returns
todaystringrequireddaysintegerrequireditemsobject[]required10 fields
kindstring (enum)requiredOne of:
probation_end,contract_end,start_soon,start_today,anniversary,document_expiry,renewal_due,health_check_due,tell_leaver,one_on_one,check_in_due,one_on_one_action,document_due,policy_ack,training_expiry,talent_due.datestringrequiredremind_onstringrequiredyearsinteger | nullrequiredoverduebooleanrequiredRenewals and health checks whose date has passed (they stay listed until done).
personobject | nullrequiredNull for company items (a renewal, a company document).
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
documentobject | nullrequireddocument_expiry: the document (its category, never its title).
2 fields
idstringrequiredcategorystringrequired
trainingobject | nulltraining_expiry: the training record whose certificate expires, and its course's title.
2 fields
idstringrequiredtitlestringrequired
renewalobject | nullrequiredrenewal_due: the company renewal.
6 fields
idstringrequirednamestringrequiredevery_monthsintegerrequiredIts cycle (0: once), for Mark renewed.
renews_onstringrequiredThe renewal date (date is the notice deadline when decide).
decidebooleanrequireddate is the notice deadline: the last day to cancel or renegotiate.
mode"auto" | "manual" | "once"required
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/reminders.upcoming \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"days":60}'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);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"]){
"data": {
"today": "2026-10-04",
"days": 60,
"items": [
{
"kind": "start_soon",
"date": "2026-10-11",
"remind_on": "2026-10-04",
"years": null,
"overdue": false,
"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"
},
"document": null,
"renewal": null
},
{
"kind": "probation_end",
"date": "2026-10-18",
"remind_on": "2026-10-04",
"years": null,
"overdue": false,
"person": {
"id": "p1",
"name": "Ana Ferreira",
"title": "Engineer",
"photo_url": null
},
"manager": null,
"document": null,
"renewal": null
},
{
"kind": "anniversary",
"date": "2026-10-20",
"remind_on": "2026-10-20",
"years": 3,
"overdue": false,
"person": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"manager": null,
"document": null,
"renewal": null
},
{
"kind": "document_expiry",
"date": "2026-10-25",
"remind_on": "2026-10-04",
"years": null,
"overdue": false,
"person": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"manager": null,
"document": {
"id": "d1",
"category": "ID"
},
"renewal": null
},
{
"kind": "renewal_due",
"date": "2026-10-01",
"remind_on": "2026-10-04",
"years": null,
"overdue": true,
"person": null,
"manager": null,
"document": null,
"renewal": {
"id": "rn1",
"name": "Work-accident insurance",
"every_months": 12,
"renews_on": "2026-10-31",
"decide": true,
"mode": "manual"
}
}
]
}
}List company renewals#
POST/v1/org/renewals.listRead
Company renewals are dated company obligations such as work-accident insurance, health insurance, a lease, a licence or a certification: kind, name, optional provider, the next renewal date (renews_on), how often it renews (every_months: 12 for yearly, 0 for once), how it ends (mode: auto renews by itself, manual ends unless renewed, once), the notice period in days (its decision date, decide_on, is the last day to cancel or renegotiate), the cost (amount in cents, currency, per year, month or term), an owner (a person with an owner, admin or HR login, who gets the reminders), a reference (policy or contract number), notes (never personal data), its history and its company documents. Lists them by the next date to act on (decision or renewal), with each one's status and totals per currency (a year, and what renews in the next 90 days). The owner and HR are reminded before each decision (Settings → Reminders). The page is Manage → Renewals. Owners, admins and HR, while the Renewals module is on (Settings → Modules).
- Who can call it
- Manage key owner admin hr
- MCP tool
org_renewals_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
todaystringrequiredrenewalsobject[]required22 fields
idstringrequirednamestringrequiredproviderstring | nullrequiredrenews_onstringrequiredevery_monthsintegerrequired0: once; 12: yearly.
notesstring | nullrequiredlast_renewed_onstring | nullrequiredoverduebooleanrequiredThe date has passed and it was not marked renewed.
updated_atstringrequiredkind"insurance" | "lease" | "licence" | "certification" | "other"requiredmode"auto" | "manual" | "once"requiredauto: renews by itself; manual: ends unless renewed; once: a single date.
notice_daysintegerrequireddecide_onstring | nullrequiredThe notice deadline: the last day to cancel or renegotiate.
status"confirm" | "overdue" | "decide" | "later"requiredconfirm: renewed by itself, record the new term; overdue: the date passed; decide: a decision or the date is within 30 days; later.
costobject | nullrequired3 fields
amountintegerrequiredMinor units (cents): 625000 = 6,250.00.
currencystringrequiredISO 4217, e.g. EUR.
per"year" | "month" | "term"requiredyear, month, or term (one cycle).
annual_costinteger | nullrequiredMinor units per year, in cost.currency.
cost_changenumber | nullrequiredThe last recorded change, as a fraction (0.064 = +6.4%).
ownerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
owner_activebooleanrequiredfalse: the owner no longer has an owner, admin or HR login, so gets no reminders (pick a new one).
referencestring | nullrequiredhistoryobject[]required7 fields
atstringrequiredbyobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
from_onstringrequiredto_onstringrequiredcost_beforeobject | nullrequired3 fields
amountintegerrequiredMinor units (cents): 625000 = 6,250.00.
currencystringrequiredISO 4217, e.g. EUR.
per"year" | "month" | "term"requiredyear, month, or term (one cycle).
cost_afterobject | nullrequired3 fields
amountintegerrequiredMinor units (cents): 625000 = 6,250.00.
currencystringrequiredISO 4217, e.g. EUR.
per"year" | "month" | "term"requiredyear, month, or term (one cycle).
notestring | nullrequired
document_idsstring[]required
totalsobjectrequired5 fields
annualobject[]requiredAll of them, a year, per currency.
2 fields
currencystringrequiredamountintegerrequired
next_90_daysobject[]requiredWhat renews in the next 90 days: its cost a year.
2 fields
currencystringrequiredamountintegerrequired
autointegerrequiredmanualintegerrequiredonceintegerrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/renewals.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/renewals.list', {
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/renewals.list",
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": {
"today": "2026-10-04",
"renewals": [
{
"id": "rn1",
"name": "Work-accident insurance",
"provider": "Fidelidade",
"renews_on": "2026-12-31",
"every_months": 12,
"notes": null,
"last_renewed_on": null,
"overdue": false,
"updated_at": "2026-10-04T10:00:00.000Z",
"kind": "insurance",
"mode": "manual",
"notice_days": 30,
"decide_on": "2026-12-01",
"status": "later",
"cost": {
"amount": 625000,
"currency": "EUR",
"per": "year"
},
"annual_cost": 625000,
"cost_change": 0.064,
"owner": {
"id": "p1",
"name": "Ana Ferreira",
"title": "Head of People",
"photo_url": null
},
"owner_active": true,
"reference": "AT-2026-0417",
"history": [
{
"at": "2025-12-02T10:00:00.000Z",
"by": {
"id": "p1",
"name": "Ana Ferreira",
"title": "Head of People",
"photo_url": null
},
"from_on": "2025-12-31",
"to_on": "2026-12-31",
"cost_before": {
"amount": 587500,
"currency": "EUR",
"per": "year"
},
"cost_after": {
"amount": 625000,
"currency": "EUR",
"per": "year"
},
"note": "Broker negotiated"
}
],
"document_ids": [
"d1"
]
},
{
"id": "rn2",
"name": "Health insurance",
"provider": null,
"renews_on": "2026-09-30",
"every_months": 12,
"notes": null,
"last_renewed_on": null,
"overdue": true,
"updated_at": "2026-10-04T10:00:00.000Z",
"kind": "insurance",
"mode": "auto",
"notice_days": 0,
"decide_on": null,
"status": "confirm",
"cost": null,
"annual_cost": null,
"cost_change": null,
"owner": null,
"owner_active": true,
"reference": "AT-2026-0417",
"history": [],
"document_ids": []
}
],
"totals": {
"annual": [
{
"currency": "EUR",
"amount": 625000
}
],
"next_90_days": [],
"auto": 1,
"manual": 1,
"once": 0
}
}
}Add a company renewal#
POST/v1/org/renewals.createWrite
Company renewals are dated company obligations such as work-accident insurance, health insurance, a lease, a licence or a certification: kind, name, optional provider, the next renewal date (renews_on), how often it renews (every_months: 12 for yearly, 0 for once), how it ends (mode: auto renews by itself, manual ends unless renewed, once), the notice period in days (its decision date, decide_on, is the last day to cancel or renegotiate), the cost (amount in cents, currency, per year, month or term), an owner (a person with an owner, admin or HR login, who gets the reminders), a reference (policy or contract number), notes (never personal data), its history and its company documents. Adds one (at most 100 per company). Use dry_run first. Owners, admins and HR, while the Renewals module is on (Settings → Modules).
- Who can call it
- Manage key owner admin hr
- MCP tool
org_renewals_createon HR Assistant- 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
namestringrequired1–80 characters.
providerstring | nullUp to 80 characters.
renews_onstringrequiredevery_monthsintegerFrom 0 to 120. Default
12.notesstring | nullUp to 500 characters.
kind"insurance" | "lease" | "licence" | "certification" | "other"Default
"other".mode"auto" | "manual" | "once"Default: once when every_months is 0, else manual.
notice_daysintegerFrom 0 to 365. Default
0.costobject | null3 fields
amountintegerrequiredFrom 0 to 10000000000.
currencystringrequiredPattern
^[A-Z]{3}$.per"year" | "month" | "term"required
owner_person_idstring | nullreferencestring | nullUp to 80 characters.
document_idsstring[]1–64 characters. Up to 20 items.
Returns
22 fields
idstringrequirednamestringrequiredproviderstring | nullrequiredrenews_onstringrequiredevery_monthsintegerrequired0: once; 12: yearly.
notesstring | nullrequiredlast_renewed_onstring | nullrequiredoverduebooleanrequiredThe date has passed and it was not marked renewed.
updated_atstringrequiredkind"insurance" | "lease" | "licence" | "certification" | "other"requiredmode"auto" | "manual" | "once"requiredauto: renews by itself; manual: ends unless renewed; once: a single date.
notice_daysintegerrequireddecide_onstring | nullrequiredThe notice deadline: the last day to cancel or renegotiate.
status"confirm" | "overdue" | "decide" | "later"requiredconfirm: renewed by itself, record the new term; overdue: the date passed; decide: a decision or the date is within 30 days; later.
costobject | nullrequired3 fields
amountintegerrequiredMinor units (cents): 625000 = 6,250.00.
currencystringrequiredISO 4217, e.g. EUR.
per"year" | "month" | "term"requiredyear, month, or term (one cycle).
annual_costinteger | nullrequiredMinor units per year, in cost.currency.
cost_changenumber | nullrequiredThe last recorded change, as a fraction (0.064 = +6.4%).
ownerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
owner_activebooleanrequiredfalse: the owner no longer has an owner, admin or HR login, so gets no reminders (pick a new one).
referencestring | nullrequiredhistoryobject[]required7 fields
atstringrequiredbyobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
from_onstringrequiredto_onstringrequiredcost_beforeobject | nullrequired3 fields
amountintegerrequiredMinor units (cents): 625000 = 6,250.00.
currencystringrequiredISO 4217, e.g. EUR.
per"year" | "month" | "term"requiredyear, month, or term (one cycle).
cost_afterobject | nullrequired3 fields
amountintegerrequiredMinor units (cents): 625000 = 6,250.00.
currencystringrequiredISO 4217, e.g. EUR.
per"year" | "month" | "term"requiredyear, month, or term (one cycle).
notestring | nullrequired
document_idsstring[]required
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/renewals.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Office lease",
"provider": "Lisbon Offices",
"renews_on": "2027-03-01",
"every_months": 36,
"notes": "Notice 90 days before"
}'const res = await fetch('https://api.bizisy.com/v1/org/renewals.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"name": "Office lease",
"provider": "Lisbon Offices",
"renews_on": "2027-03-01",
"every_months": 36,
"notes": "Notice 90 days before"
}),
});
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/renewals.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "Office lease",
"provider": "Lisbon Offices",
"renews_on": "2027-03-01",
"every_months": 36,
"notes": "Notice 90 days before",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "rn1",
"name": "Office lease",
"provider": "Lisbon Offices",
"renews_on": "2027-03-01",
"every_months": 36,
"notes": "Notice 90 days before",
"last_renewed_on": null,
"overdue": false,
"updated_at": "2026-10-04T10:00:00.000Z",
"kind": "insurance",
"mode": "manual",
"notice_days": 30,
"decide_on": "2026-12-01",
"status": "later",
"cost": {
"amount": 625000,
"currency": "EUR",
"per": "year"
},
"annual_cost": 625000,
"cost_change": 0.064,
"owner": {
"id": "p1",
"name": "Ana Ferreira",
"title": "Head of People",
"photo_url": null
},
"owner_active": true,
"reference": "AT-2026-0417",
"history": [
{
"at": "2025-12-02T10:00:00.000Z",
"by": {
"id": "p1",
"name": "Ana Ferreira",
"title": "Head of People",
"photo_url": null
},
"from_on": "2025-12-31",
"to_on": "2026-12-31",
"cost_before": {
"amount": 587500,
"currency": "EUR",
"per": "year"
},
"cost_after": {
"amount": 625000,
"currency": "EUR",
"per": "year"
},
"note": "Broker negotiated"
}
],
"document_ids": [
"d1"
]
}
}Change a company renewal#
POST/v1/org/renewals.updateWrite
Changes a renewal: any of name, provider, renews_on, every_months, notes, kind, mode, notice_days, cost, owner_person_id, reference, document_ids (the whole list); send only what changes (null clears provider, notes, cost, owner or reference). To record a renewal use org_renewals_renew instead, which keeps its history. Use dry_run first. Owners, admins and HR, while the Renewals module is on (Settings → Modules).
- Who can call it
- Manage key owner admin hr
- MCP tool
org_renewals_updateon HR Assistant- 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
renewal_idstringrequirednamestring1–80 characters.
providerstring | nullUp to 80 characters.
renews_onstringevery_monthsintegerFrom 0 to 120.
notesstring | nullUp to 500 characters.
kind"insurance" | "lease" | "licence" | "certification" | "other"mode"auto" | "manual" | "once"notice_daysintegerFrom 0 to 365.
costobject | null3 fields
amountintegerrequiredFrom 0 to 10000000000.
currencystringrequiredPattern
^[A-Z]{3}$.per"year" | "month" | "term"required
owner_person_idstring | nullreferencestring | nullUp to 80 characters.
document_idsstring[]1–64 characters. Up to 20 items.
Returns
22 fields
idstringrequirednamestringrequiredproviderstring | nullrequiredrenews_onstringrequiredevery_monthsintegerrequired0: once; 12: yearly.
notesstring | nullrequiredlast_renewed_onstring | nullrequiredoverduebooleanrequiredThe date has passed and it was not marked renewed.
updated_atstringrequiredkind"insurance" | "lease" | "licence" | "certification" | "other"requiredmode"auto" | "manual" | "once"requiredauto: renews by itself; manual: ends unless renewed; once: a single date.
notice_daysintegerrequireddecide_onstring | nullrequiredThe notice deadline: the last day to cancel or renegotiate.
status"confirm" | "overdue" | "decide" | "later"requiredconfirm: renewed by itself, record the new term; overdue: the date passed; decide: a decision or the date is within 30 days; later.
costobject | nullrequired3 fields
amountintegerrequiredMinor units (cents): 625000 = 6,250.00.
currencystringrequiredISO 4217, e.g. EUR.
per"year" | "month" | "term"requiredyear, month, or term (one cycle).
annual_costinteger | nullrequiredMinor units per year, in cost.currency.
cost_changenumber | nullrequiredThe last recorded change, as a fraction (0.064 = +6.4%).
ownerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
owner_activebooleanrequiredfalse: the owner no longer has an owner, admin or HR login, so gets no reminders (pick a new one).
referencestring | nullrequiredhistoryobject[]required7 fields
atstringrequiredbyobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
from_onstringrequiredto_onstringrequiredcost_beforeobject | nullrequired3 fields
amountintegerrequiredMinor units (cents): 625000 = 6,250.00.
currencystringrequiredISO 4217, e.g. EUR.
per"year" | "month" | "term"requiredyear, month, or term (one cycle).
cost_afterobject | nullrequired3 fields
amountintegerrequiredMinor units (cents): 625000 = 6,250.00.
currencystringrequiredISO 4217, e.g. EUR.
per"year" | "month" | "term"requiredyear, month, or term (one cycle).
notestring | nullrequired
document_idsstring[]required
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/renewals.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"renewal_id": "rn1",
"kind": "lease",
"mode": "auto",
"notice_days": 90,
"cost": {
"amount": 4800000,
"currency": "EUR",
"per": "year"
},
"owner_person_id": "p1",
"reference": "L-77",
"document_ids": [
"d1",
"d2"
]
}'const res = await fetch('https://api.bizisy.com/v1/org/renewals.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"renewal_id": "rn1",
"kind": "lease",
"mode": "auto",
"notice_days": 90,
"cost": {
"amount": 4800000,
"currency": "EUR",
"per": "year"
},
"owner_person_id": "p1",
"reference": "L-77",
"document_ids": [
"d1",
"d2"
]
}),
});
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/renewals.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"renewal_id": "rn1",
"kind": "lease",
"mode": "auto",
"notice_days": 90,
"cost": {
"amount": 4800000,
"currency": "EUR",
"per": "year",
},
"owner_person_id": "p1",
"reference": "L-77",
"document_ids": [
"d1",
"d2",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "rn1",
"name": "Work-accident insurance",
"provider": null,
"renews_on": "2026-12-31",
"every_months": 12,
"notes": null,
"last_renewed_on": null,
"overdue": false,
"updated_at": "2026-10-04T10:00:00.000Z",
"kind": "lease",
"mode": "auto",
"notice_days": 90,
"decide_on": "2026-12-01",
"status": "later",
"cost": {
"amount": 625000,
"currency": "EUR",
"per": "year"
},
"annual_cost": 625000,
"cost_change": 0.064,
"owner": {
"id": "p1",
"name": "Ana Ferreira",
"title": "Head of People",
"photo_url": null
},
"owner_active": true,
"reference": "L-77",
"history": [
{
"at": "2025-12-02T10:00:00.000Z",
"by": {
"id": "p1",
"name": "Ana Ferreira",
"title": "Head of People",
"photo_url": null
},
"from_on": "2025-12-31",
"to_on": "2026-12-31",
"cost_before": {
"amount": 587500,
"currency": "EUR",
"per": "year"
},
"cost_after": {
"amount": 625000,
"currency": "EUR",
"per": "year"
},
"note": "Broker negotiated"
}
],
"document_ids": [
"d1"
]
}
}Mark a company renewal as renewed#
POST/v1/org/renewals.renewWrite
Records that a renewal was done (or, for one that renews by itself, confirms the new term): its next date moves forward by its cycle (every_months), or to renews_on when given; optionally the new cost, a note on what changed (never personal data) and the new contract's company document. Kept in its history (at most 50). A one-off (every_months 0) needs renews_on, or is deleted with org_renewals_delete instead. Use dry_run first. Owners, admins and HR, while the Renewals module is on (Settings → Modules).
- Who can call it
- Manage key owner admin hr
- MCP tool
org_renewals_renewon HR Assistant- 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
renewal_idstringrequiredrenews_onstringcostobject | null3 fields
amountintegerrequiredFrom 0 to 10000000000.
currencystringrequiredPattern
^[A-Z]{3}$.per"year" | "month" | "term"required
notestring | nullUp to 500 characters.
document_idstring1–64 characters.
Returns
22 fields
idstringrequirednamestringrequiredproviderstring | nullrequiredrenews_onstringrequiredevery_monthsintegerrequired0: once; 12: yearly.
notesstring | nullrequiredlast_renewed_onstring | nullrequiredoverduebooleanrequiredThe date has passed and it was not marked renewed.
updated_atstringrequiredkind"insurance" | "lease" | "licence" | "certification" | "other"requiredmode"auto" | "manual" | "once"requiredauto: renews by itself; manual: ends unless renewed; once: a single date.
notice_daysintegerrequireddecide_onstring | nullrequiredThe notice deadline: the last day to cancel or renegotiate.
status"confirm" | "overdue" | "decide" | "later"requiredconfirm: renewed by itself, record the new term; overdue: the date passed; decide: a decision or the date is within 30 days; later.
costobject | nullrequired3 fields
amountintegerrequiredMinor units (cents): 625000 = 6,250.00.
currencystringrequiredISO 4217, e.g. EUR.
per"year" | "month" | "term"requiredyear, month, or term (one cycle).
annual_costinteger | nullrequiredMinor units per year, in cost.currency.
cost_changenumber | nullrequiredThe last recorded change, as a fraction (0.064 = +6.4%).
ownerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
owner_activebooleanrequiredfalse: the owner no longer has an owner, admin or HR login, so gets no reminders (pick a new one).
referencestring | nullrequiredhistoryobject[]required7 fields
atstringrequiredbyobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
from_onstringrequiredto_onstringrequiredcost_beforeobject | nullrequired3 fields
amountintegerrequiredMinor units (cents): 625000 = 6,250.00.
currencystringrequiredISO 4217, e.g. EUR.
per"year" | "month" | "term"requiredyear, month, or term (one cycle).
cost_afterobject | nullrequired3 fields
amountintegerrequiredMinor units (cents): 625000 = 6,250.00.
currencystringrequiredISO 4217, e.g. EUR.
per"year" | "month" | "term"requiredyear, month, or term (one cycle).
notestring | nullrequired
document_idsstring[]required
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/renewals.renew \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"renewal_id": "rn1",
"renews_on": "2027-12-31",
"cost": {
"amount": 664000,
"currency": "EUR",
"per": "year"
},
"note": "Premium up after two claims",
"document_id": "d3"
}'const res = await fetch('https://api.bizisy.com/v1/org/renewals.renew', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"renewal_id": "rn1",
"renews_on": "2027-12-31",
"cost": {
"amount": 664000,
"currency": "EUR",
"per": "year"
},
"note": "Premium up after two claims",
"document_id": "d3"
}),
});
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/renewals.renew",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"renewal_id": "rn1",
"renews_on": "2027-12-31",
"cost": {
"amount": 664000,
"currency": "EUR",
"per": "year",
},
"note": "Premium up after two claims",
"document_id": "d3",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "rn1",
"name": "Work-accident insurance",
"provider": "Fidelidade",
"renews_on": "2027-12-31",
"every_months": 12,
"notes": null,
"last_renewed_on": "2026-10-04",
"overdue": false,
"updated_at": "2026-10-04T10:00:00.000Z",
"kind": "insurance",
"mode": "manual",
"notice_days": 30,
"decide_on": "2026-12-01",
"status": "later",
"cost": {
"amount": 625000,
"currency": "EUR",
"per": "year"
},
"annual_cost": 625000,
"cost_change": 0.064,
"owner": {
"id": "p1",
"name": "Ana Ferreira",
"title": "Head of People",
"photo_url": null
},
"owner_active": true,
"reference": "AT-2026-0417",
"history": [
{
"at": "2025-12-02T10:00:00.000Z",
"by": {
"id": "p1",
"name": "Ana Ferreira",
"title": "Head of People",
"photo_url": null
},
"from_on": "2025-12-31",
"to_on": "2026-12-31",
"cost_before": {
"amount": 587500,
"currency": "EUR",
"per": "year"
},
"cost_after": {
"amount": 625000,
"currency": "EUR",
"per": "year"
},
"note": "Broker negotiated"
}
],
"document_ids": [
"d1"
]
}
}Delete a company renewal#
POST/v1/org/renewals.deleteWrite
Deletes a renewal, its history and its reminders (its documents stay in Documents). Use dry_run first. Owners, admins and HR, while the Renewals module is on (Settings → Modules).
- Who can call it
- Manage key owner admin hr
- MCP tool
org_renewals_deleteon HR Assistant- 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
renewal_idstringrequired
Returns
deletedtruerequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/renewals.delete \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"renewal_id":"rn1"}'const res = await fetch('https://api.bizisy.com/v1/org/renewals.delete', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"renewal_id": "rn1"
}),
});
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/renewals.delete",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"renewal_id": "rn1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"deleted": true
}
}List occupational health checks#
POST/v1/org/health_checks.listRead
Occupational health checks keep dates only (the last check and the next one due), never a result or anything medical. Lists everyone employed or about to start: last check, next due (the company's interval in Settings → Reminders, else the country's: Portugal every 2 years and yearly under 18 or from 50, France at most every 5 years; elsewhere none until the company sets one), whether HR set the date by hand, and overdue. Owners, admins and HR signed in to Bizisy (and custom roles that cover private details); never managers, and never over an API key or AI app unless the company allowed sensitive access.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Lists nobody unless the company allowed sensitive details for this key or app.
- MCP tool
org_health_checks_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
todaystringrequireditemsobject[]required7 fields
personobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
last_onstring | nullrequirednext_duestring | nullrequirednext_due_setbooleanrequiredTrue when HR set the next date by hand.
interval_monthsinteger | nullrequiredinterval_source"company" | "pt" | "pt_age" | "fr"requiredcompany (Settings → Reminders), pt (Portugal, every 2 years), pt_age (Portugal, yearly under 18 or from 50), fr (France, at most 5 years), or null: no interval set.
overduebooleanrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/health_checks.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/health_checks.list', {
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/health_checks.list",
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": {
"today": "2026-10-04",
"items": [
{
"person": {
"id": "p1",
"name": "Ana Ferreira",
"title": "Engineer",
"photo_url": null
},
"last_on": "2026-10-01",
"next_due": "2028-10-01",
"next_due_set": false,
"interval_months": 24,
"interval_source": "pt",
"overdue": false
},
{
"person": {
"id": "p2",
"name": "Tomás Silva",
"title": "Designer",
"photo_url": null
},
"last_on": null,
"next_due": null,
"next_due_set": false,
"interval_months": 12,
"interval_source": "pt_age",
"overdue": false
}
]
}
}Record an occupational health check#
POST/v1/org/health_checks.recordWrite
Occupational health checks keep dates only (the last check and the next one due), never a result or anything medical. Records that the person had their check on done_on (today or earlier); the next one is due after the interval, and a date set by hand is cleared. Never send results. Use dry_run first. Owners, admins and HR signed in to Bizisy (and custom roles that cover private details); never managers, and never over an API key or AI app unless the company allowed sensitive access.
- Web app only
- Refused for API keys and connected apps. Health-check dates are changed by owners, admins and HR signed in to Bizisy (or a role allowed sensitive details).
- MCP tool
org_health_checks_recordon HR Assistant- 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
person_idstringrequireddone_onstringrequired
Returns
7 fields
personobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
last_onstring | nullrequirednext_duestring | nullrequirednext_due_setbooleanrequiredTrue when HR set the next date by hand.
interval_monthsinteger | nullrequiredinterval_source"company" | "pt" | "pt_age" | "fr"requiredcompany (Settings → Reminders), pt (Portugal, every 2 years), pt_age (Portugal, yearly under 18 or from 50), fr (France, at most 5 years), or null: no interval set.
overduebooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/health_checks.record \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"person_id":"p1","done_on":"2026-10-01"}'const res = await fetch('https://api.bizisy.com/v1/org/health_checks.record', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p1",
"done_on": "2026-10-01"
}),
});
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/health_checks.record",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p1",
"done_on": "2026-10-01",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person": {
"id": "p1",
"name": "Ana Ferreira",
"title": "Engineer",
"photo_url": null
},
"last_on": "2026-10-01",
"next_due": "2028-10-01",
"next_due_set": false,
"interval_months": 24,
"interval_source": "pt",
"overdue": false
}
}Set the next occupational health check#
POST/v1/org/health_checks.set_dueWrite
Occupational health checks keep dates only (the last check and the next one due), never a result or anything medical. Sets the next check's date by hand (when the occupational doctor asked for an earlier or later one), or null to go back to the interval. Use dry_run first. Owners, admins and HR signed in to Bizisy (and custom roles that cover private details); never managers, and never over an API key or AI app unless the company allowed sensitive access.
- Web app only
- Refused for API keys and connected apps. Health-check dates are changed by owners, admins and HR signed in to Bizisy (or a role allowed sensitive details).
- MCP tool
org_health_checks_set_dueon HR Assistant- 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
person_idstringrequirednext_duestring | nullrequired
Returns
7 fields
personobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
last_onstring | nullrequirednext_duestring | nullrequirednext_due_setbooleanrequiredTrue when HR set the next date by hand.
interval_monthsinteger | nullrequiredinterval_source"company" | "pt" | "pt_age" | "fr"requiredcompany (Settings → Reminders), pt (Portugal, every 2 years), pt_age (Portugal, yearly under 18 or from 50), fr (France, at most 5 years), or null: no interval set.
overduebooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/health_checks.set_due \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"person_id":"p1","next_due":"2027-04-01"}'const res = await fetch('https://api.bizisy.com/v1/org/health_checks.set_due', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p1",
"next_due": "2027-04-01"
}),
});
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/health_checks.set_due",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p1",
"next_due": "2027-04-01",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person": {
"id": "p1",
"name": "Ana Ferreira",
"title": "Engineer",
"photo_url": null
},
"last_on": "2026-10-01",
"next_due": "2027-04-01",
"next_due_set": true,
"interval_months": 24,
"interval_source": "pt",
"overdue": false
}
}My occupational health check#
POST/v1/org/health_checks.mineRead
Occupational health checks keep dates only (the last check and the next one due), never a result or anything medical. Your own: the last check and the next one due, when your company keeps them (Settings → Reminders → Health checks). Only you and HR see them.
- Who can call it
- Me key anyone
- MCP tool
org_health_checks_mineon My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
trackedbooleanrequiredlast_onstring | nullrequirednext_duestring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/health_checks.mine \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/health_checks.mine', {
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/health_checks.mine",
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": {
"tracked": true,
"last_on": "2026-10-01",
"next_due": "2028-10-01"
}
}Start reading a document for a renewal#
POST/v1/org/renewals.read.startWrite
Step 1 of 2 of adding a renewal from its document: an insurance policy, lease, licence or other contract as PDF, PNG, JPEG, WebP or a text file. Returns a signed upload (PUT the bytes within 15 minutes), then call org_renewals_read_finish with file_id. Nothing is saved as a renewal. ai_credits_left: the company's AI credits left (null when unlimited). Reading a PDF or picture uses 1 AI credit (a text file uses none); with none left the read answers no_credits (people: fill in the form by hand, or an owner or admin buys AI credits in Settings → Plan & billing) and API keys and AI apps get credits_exhausted (402). At most 40 documents a company and 20 a person each day (each started upload counts), 10 MB each; PDFs are read up to page 10. Owners, admins and HR, while the Renewals module is on (Settings → Modules).
- Who can call it
- Manage key owner admin hr
- MCP tool
org_renewals_read_starton HR Assistant- 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
namestringrequired1–200 characters.
sizeintegerrequiredAt least 1.
content_typestringrequiredsha256stringrequiredPattern
^[0-9a-f]{64}$.
Returns
file_idstringrequireduploadobject | nullrequired4 fields
urlstringrequiredmethod"PUT"requiredheadersobjectrequiredresumablefalserequired
expires_atstringrequiredreads_left_todayintegerrequiredHow many more this login may start today.
ai_credits_leftinteger | nullrequiredAI credits the company has left now (reading a PDF or picture uses 1); null when unlimited.
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/renewals.read.start \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "apolice.pdf",
"size": 48211,
"content_type": "application/pdf",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}'const res = await fetch('https://api.bizisy.com/v1/org/renewals.read.start', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"name": "apolice.pdf",
"size": 48211,
"content_type": "application/pdf",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}),
});
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/renewals.read.start",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "apolice.pdf",
"size": 48211,
"content_type": "application/pdf",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"file_id": "f1",
"upload": {
"url": "https://storage.googleapis.com/upload",
"method": "PUT",
"headers": {
"content-type": "application/pdf"
},
"resumable": false
},
"expires_at": "2026-10-04T10:15:00.000Z",
"reads_left_today": 19,
"ai_credits_left": 12
}
}Read a document for a renewal#
POST/v1/org/renewals.read.finishWrite
Step 2 of 2: reads the document uploaded with org_renewals_read_start (Google Cloud Document AI in the EU reads PDFs and pictures; Google keeps nothing) and returns what a renewal needs: kind, name, provider, renews_on, every_months, mode (auto: renews by itself; manual: ends unless renewed), notice_days, cost (cents, currency, per) and reference. Each field carries the text it came from, and check true when it is a guess: show the person every field and its source, and save only what they confirm, with org_renewals_create. Fields not found are absent, never invented. outcome: read, nothing_found (no field), unreadable (no text), or no_credits (no AI credits left: nothing was read; offer the form by hand or buying AI credits). ai_credits: what this read used and what is left. The file is deleted in this call and the text is never kept; to keep the document, upload it as a company document (documents_upload_start) and link it with document_ids. Once per upload; a dry run reads nothing and says the cost. Reading a PDF or picture uses 1 AI credit (a text file uses none); with none left the read answers no_credits (people: fill in the form by hand, or an owner or admin buys AI credits in Settings → Plan & billing) and API keys and AI apps get credits_exhausted (402). At most 40 documents a company and 20 a person each day (each started upload counts), 10 MB each; PDFs are read up to page 10. Owners, admins and HR, while the Renewals module is on (Settings → Modules).
- Who can call it
- Manage key owner admin hr
- MCP tool
org_renewals_read_finishon HR Assistant- 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
file_idstringrequired1–64 characters.
Returns
outcome"read" | "nothing_found" | "unreadable" | "no_credits"requiredfieldsobjectrequired9 fields
kindobject4 fields
value"insurance" | "lease" | "licence" | "certification" | "other"requiredsourcestringrequiredThe text it was read from (at most 160 characters).
checkbooleanrequiredtrue: a guess; ask the person to check it (e.g. "renovável" can mean either way).
atinteger[]requiredIndexes in lines of the text it was read from.
nameobject4 fields
valuestringrequiredsourcestringrequiredThe text it was read from (at most 160 characters).
checkbooleanrequiredtrue: a guess; ask the person to check it (e.g. "renovável" can mean either way).
atinteger[]requiredIndexes in lines of the text it was read from.
providerobject4 fields
valuestringrequiredsourcestringrequiredThe text it was read from (at most 160 characters).
checkbooleanrequiredtrue: a guess; ask the person to check it (e.g. "renovável" can mean either way).
atinteger[]requiredIndexes in lines of the text it was read from.
renews_onobject4 fields
valuestringrequiredsourcestringrequiredThe text it was read from (at most 160 characters).
checkbooleanrequiredtrue: a guess; ask the person to check it (e.g. "renovável" can mean either way).
atinteger[]requiredIndexes in lines of the text it was read from.
every_monthsobject4 fields
valueintegerrequiredsourcestringrequiredThe text it was read from (at most 160 characters).
checkbooleanrequiredtrue: a guess; ask the person to check it (e.g. "renovável" can mean either way).
atinteger[]requiredIndexes in lines of the text it was read from.
modeobject4 fields
value"auto" | "manual" | "once"requiredsourcestringrequiredThe text it was read from (at most 160 characters).
checkbooleanrequiredtrue: a guess; ask the person to check it (e.g. "renovável" can mean either way).
atinteger[]requiredIndexes in lines of the text it was read from.
notice_daysobject4 fields
valueintegerrequiredsourcestringrequiredThe text it was read from (at most 160 characters).
checkbooleanrequiredtrue: a guess; ask the person to check it (e.g. "renovável" can mean either way).
atinteger[]requiredIndexes in lines of the text it was read from.
costobject4 fields
valueobjectrequired3 fields
amountintegerrequiredcurrencystringrequiredper"year" | "month" | "term"required
sourcestringrequiredThe text it was read from (at most 160 characters).
checkbooleanrequiredtrue: a guess; ask the person to check it (e.g. "renovável" can mean either way).
atinteger[]requiredIndexes in lines of the text it was read from.
referenceobject4 fields
valuestringrequiredsourcestringrequiredThe text it was read from (at most 160 characters).
checkbooleanrequiredtrue: a guess; ask the person to check it (e.g. "renovável" can mean either way).
atinteger[]requiredIndexes in lines of the text it was read from.
linesstring[]requiredThe document's text as read, line by line (at most 400 lines), for showing where each field came from; empty for API keys and AI apps (use each field's source). Never stored.
truncatedbooleanrequiredThe text was longer than lines holds.
ai_creditsobjectrequired3 fields
costintegerrequiredAI credits this read used (0 for a text file or a read that failed; on a dry run, what a PDF or picture uses).
leftinteger | nullrequiredAI credits the company has left; null when unlimited.
notestringrequiredThe same in words, e.g. "Used 1 AI credit (12 left)".
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/renewals.read.finish \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"file_id":"f1"}'const res = await fetch('https://api.bizisy.com/v1/org/renewals.read.finish', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"file_id": "f1"
}),
});
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/renewals.read.finish",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"file_id": "f1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"outcome": "read",
"truncated": false,
"ai_credits": {
"cost": 1,
"left": 11,
"note": "Used 1 AI credit (11 left)"
},
"lines": [
"FIDELIDADE - Companhia de Seguros, S.A.",
"Apólice n.º AT-2026-0417",
"Termo: 28/11/2026",
"Duração: um ano, renovável",
"Prémio total anual: 6 250,00 €"
],
"fields": {
"kind": {
"value": "insurance",
"source": "Apólice n.º AT-2026-0417",
"check": false,
"at": [
1
]
},
"provider": {
"value": "Fidelidade",
"source": "FIDELIDADE - Companhia de Seguros, S.A.",
"check": false,
"at": [
0
]
},
"renews_on": {
"value": "2026-11-28",
"source": "Termo: 28/11/2026",
"check": false,
"at": [
2
]
},
"mode": {
"value": "auto",
"source": "Duração: um ano, renovável",
"check": true,
"at": [
3
]
},
"cost": {
"value": {
"amount": 625000,
"currency": "EUR",
"per": "year"
},
"source": "Prémio total anual: 6 250,00 €",
"check": false,
"at": [
4
]
},
"reference": {
"value": "AT-2026-0417",
"source": "Apólice n.º AT-2026-0417",
"check": false,
"at": [
1
]
}
}
}
}Something missing or wrong on this page? Write to hello@bizisy.com.