API reference
Workforce planning
A forecast of headcount, FTE and cost per team and month, scenarios with planned hires, reductions and moves, comparing them, and the default assumptions.
13 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
Workforce forecast#
POST/v1/org/planning.forecastRead
A forecast of headcount, FTE and cost per team and month, from your data and assumptions (Reports → Planning). For each team (unit_ids, at most 50; default the top-level budgeted teams, else the teams under the company; a team covers every team below it) and each month of the horizon (horizon_from, this month or up to 12 months ahead; months 1–18, default 12): start (people on the first day; today for this month) + joiners_known (hires with a future start date — an accepted offer in Hiring becomes one — and transfers in) + joiners_open (open positions, never drafts or on hold, in the month of their target start date, else this month + time_to_fill) + hires_planned + moves_in − leavers_known (recorded last days and transfers out) − contract_ends (fixed-term contracts ending, unless a renewal or a permanent contract is recorded; with no decision yet, (1 − renewal_rate) of each) − leavers_expected (the monthly attrition rate × the people expected to stay; a decimal, never people) − reductions_planned − moves_out = end; fte_end; the budget in force (org_budgets_list), gap = budget − end, status over/on_budget/room; cost (monthly base pay of the people there at the month's end, open positions at their pay range midpoint, planned hires at their cost per head or the team's average, × (1 + on-cost %) × pay increases; main currency only, other currencies counted in not_costed). Rates default to each team's trailing 12-month history (teams under 5 people use the company's; contract ends are left out of the rate since they are counted from their dates). scenario_id: a scenario's assumptions and planned changes (default the baseline: company assumptions, no changes). To see the people behind a number, open Bizisy (org_planning_items is in the app only). Owners, admins and HR; never a custom role, a manager or a member. API keys, MCP and connected apps get headcount and FTE only: cost, on-cost and cost per head are left out (cost_hidden apps). Part of the Reports & analytics module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Headcount and FTE only: cost is left out (cost_hidden apps); the people behind a number are in the app.
- MCP tool
org_planning_forecaston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
unit_idsstring[]Up to 50 items.
horizon_fromstringPattern
^\d{4}-(0[1-9]|1[0-2])$.monthsintegerFrom 1 to 18.
scenario_idstring | null1–40 characters.
draftobjectUnsaved edits of scenario_id (or of the baseline) to preview before saving: assumptions (only the fields sent), by_unit and changes replace the stored ones. Nothing is written.
3 fields
assumptionsobject6 fields
vol_ratenumber | nullVoluntary leaving rate per month as a fraction (0.021 = 2.1 % a month); null: from your history (trailing 12 months).
From 0 to 0.5.
invol_ratenumber | nullInvoluntary leaving rate per month as a fraction; null: from your history.
From 0 to 0.5.
time_to_fillintegerMonths an open position without a target start date takes to fill (default 2).
From 0 to 24.
renewal_ratenumberShare (0–1) of fixed-term contract ends with no decision yet expected to be renewed (default 0: they end, as the law says).
From 0 to 1.
on_cost_pctnumber | nullEmployer on-cost on top of base pay in percent (social security, insurance); null: not entered. Pay tier: in the app only.
From 0 to 200.
pay_increasesobject[]Pay increases from a month, in percent (e.g. +3 from January).
Up to 12 items.
2 fields
from_monthstringrequiredPattern
^\d{4}-(0[1-9]|1[0-2])$.pctnumberrequiredFrom -50 to 100.
by_unitobjectchangesobject[]Up to 200 items.
8 fields
idstring1–40 characters.
unit_idstringrequiredmonthstringrequiredPattern
^\d{4}-(0[1-9]|1[0-2])$.kind"hire" | "reduce" | "move"requiredcountintegerrequiredFrom 1 to 500.
to_unit_idstring | nulltitle_idstring | nullcost_per_headobject | null3 fields
amountnumberrequiredFrom 0 to 10000000.
currencystringrequiredPattern
^[A-Z]{3}$.period"year" | "month" | "hour"required
Returns
12 fields
as_ofstringrequiredhorizon_fromstringrequiredmonthsstring[]requiredscenarioobject | nullrequirednull: the baseline (company default assumptions, no planned changes).
4 fields
idstringrequirednamestringrequiredstatus"draft" | "adopted" | "archived"requiredversionintegerrequired
currencystring | nullrequiredcost_hidden"apps" | "no_pay"requiredapps: cost is never given to API keys, MCP or connected apps; no_pay: no pay recorded in the main currency.
assumptionsobjectrequired6 fields
vol_ratenumber | nullrequiredinvol_ratenumber | nullrequiredtime_to_fillnumberrequiredrenewal_ratenumberrequiredon_cost_pctnumber | nullrequiredpay_increasesobject[]required2 fields
from_monthstringrequiredpctnumberrequired
historyobjectrequired3 fields
vol_ratenumberrequiredinvol_ratenumberrequiredpeopleintegerrequired
teamsobject[]required11 fields
unitobjectrequired4 fields
idstringrequirednamestringrequiredkindstringrequiredparent_idstring | nullrequired
ratesobjectrequired5 fields
vol_ratenumberrequiredinvol_ratenumberrequiredsource"set" | "team_history" | "company_history"requiredtime_to_fillnumberrequiredrenewal_ratenumberrequired
historyobject | nullrequired3 fields
vol_ratenumberrequiredinvol_ratenumberrequiredpeopleintegerrequired
monthsobject[]required18 fields
monthstringrequiredstartnumberrequiredjoiners_knownnumberrequiredjoiners_opennumberrequiredjoiners_requestednumberrequiredPositions waiting for approval to open, in the month they would start: shown apart, never counted in end.
hires_plannednumberrequiredmoves_innumberrequiredleavers_knownnumberrequiredcontract_endsnumberrequiredleavers_expectednumberrequiredreductions_plannednumberrequiredmoves_outnumberrequiredendnumberrequiredfte_endnumberrequiredbudgetinteger | nullrequiredgapnumber | nullrequiredstatus"over" | "over_with_open" | "on_budget" | "room"requiredcostnumber | nullrequired
months_overintegerrequiredpeak_gapnumber | nullrequiredendnumberrequiredfte_endnumberrequiredtotal_costnumber | nullrequiredaverage_costnumber | nullrequirednot_costedobject | nullrequired3 fields
no_payintegerrequiredother_currencyintegerrequiredcurrenciesstring[]required
totalsobjectrequired4 fields
monthsobject[]required7 fields
monthstringrequiredstartnumberrequiredendnumberrequiredfte_endnumberrequiredbudgetinteger | nullrequiredgapnumber | nullrequiredcostnumber | nullrequired
months_overintegerrequiredendnumberrequiredtotal_costnumber | nullrequired
default_teamsbooleanrequiredtrue: no unit_ids were given; the top-level budgeted teams (else the teams under the company) are shown.
truncatedbooleanrequiredtrue: more than 50 default teams; the first 50 by name are shown (pick teams with unit_ids).
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/planning.forecast \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"scenario_id": "ps1",
"draft": {
"assumptions": {
"renewal_rate": 0.5
},
"changes": [
{
"unit_id": "u2",
"month": "2027-01",
"kind": "hire",
"count": 3
}
]
}
}'const res = await fetch('https://api.bizisy.com/v1/org/planning.forecast', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"scenario_id": "ps1",
"draft": {
"assumptions": {
"renewal_rate": 0.5
},
"changes": [
{
"unit_id": "u2",
"month": "2027-01",
"kind": "hire",
"count": 3
}
]
}
}),
});
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/planning.forecast",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"scenario_id": "ps1",
"draft": {
"assumptions": {
"renewal_rate": 0.5,
},
"changes": [
{
"unit_id": "u2",
"month": "2027-01",
"kind": "hire",
"count": 3,
},
],
},
},
)
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",
"horizon_from": "2026-10",
"months": [
"2026-10"
],
"scenario": null,
"currency": "EUR",
"cost_hidden": null,
"assumptions": {
"vol_rate": null,
"invol_rate": null,
"time_to_fill": 2,
"renewal_rate": 0,
"on_cost_pct": 23.75,
"pay_increases": [
{
"from_month": "2027-01",
"pct": 3
}
]
},
"history": {
"vol_rate": 0.012,
"invol_rate": 0.003,
"people": 8
},
"teams": [
{
"unit": {
"id": "u2",
"name": "Engineering",
"kind": "department",
"parent_id": "u1"
},
"rates": {
"vol_rate": 0.012,
"invol_rate": 0.003,
"source": "team_history",
"time_to_fill": 2,
"renewal_rate": 0
},
"history": {
"vol_rate": 0.012,
"invol_rate": 0.003,
"people": 8
},
"months": [
{
"month": "2026-10",
"start": 8,
"joiners_known": 1,
"joiners_open": 1,
"joiners_requested": 1,
"hires_planned": 0,
"moves_in": 0,
"leavers_known": 0,
"contract_ends": 1,
"leavers_expected": 0.2,
"reductions_planned": 0,
"moves_out": 0,
"end": 8.8,
"fte_end": 8.3,
"budget": 8,
"gap": -0.8,
"status": "over",
"cost": 26400
}
],
"months_over": 1,
"peak_gap": -0.8,
"end": 8.8,
"fte_end": 8.3,
"total_cost": 26400,
"average_cost": 26400,
"not_costed": {
"no_pay": 0,
"other_currency": 0,
"currencies": []
}
}
],
"totals": {
"months": [
{
"month": "2026-10",
"start": 8,
"end": 8.8,
"fte_end": 8.3,
"budget": 8,
"gap": -0.8,
"cost": 26400
}
],
"months_over": 1,
"end": 8.8,
"total_cost": 26400
},
"default_teams": true,
"truncated": false
}
}People and positions behind a forecast number#
POST/v1/org/planning.itemsRead
The people, positions and offers behind one forecast number: a team (unit_id), a month and a component (joiners_known, joiners_open, leavers_known, contract_ends, leavers_expected), for the baseline or scenario_id. leavers_expected has no people: it returns the formula (people expected to stay × monthly rate). Names people with future last days, some not yet told: owners, admins and HR signed in to Bizisy only (never API keys, MCP or connected apps); never a custom role. Part of the Reports & analytics module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).
- Web app only
- Refused for API keys and connected apps. Names people with future last days: owners, admins and HR in the Bizisy app.
- MCP tool
org_planning_itemson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
unit_idstringrequiredmonthstringrequiredPattern
^\d{4}-(0[1-9]|1[0-2])$.component"joiners_known" | "joiners_open" | "leavers_known" | "contract_ends" | "leavers_expected"requiredscenario_idstring | null1–40 characters.
horizon_fromstringPattern
^\d{4}-(0[1-9]|1[0-2])$.monthsintegerFrom 1 to 18.
Returns
unitobjectrequired2 fields
idstringrequirednamestringrequired
monthstringrequiredcomponent"joiners_known" | "joiners_open" | "leavers_known" | "contract_ends" | "leavers_expected"requiredvaluenumberrequireditemsobject[]required9 fields
kindstring (enum)requiredOne of:
hire,transfer_in,transfer_out,termination,contract_end,contract_end_undecided,position.datestring | nullrequiredweightnumberrequiredpersonobject | nullrequired3 fields
idstringrequirednamestringrequiredtitlestring | nullrequired
positionobject | nullrequired2 fields
idstringrequiredtitlestringrequired
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
other_unitobject | nullrequired2 fields
idstringrequirednamestringrequired
toldboolean | nullrequiredTerminations: false while the person has not been told about their last day (keep it with HR).
placed"target" | "time_to_fill"required
expectedobject | nullrequired3 fields
basenumberrequiredratenumberrequiredvaluenumberrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/planning.items \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"unit_id": "u2",
"month": "2027-01",
"component": "leavers_expected",
"scenario_id": "ps1",
"months": 12
}'const res = await fetch('https://api.bizisy.com/v1/org/planning.items', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"unit_id": "u2",
"month": "2027-01",
"component": "leavers_expected",
"scenario_id": "ps1",
"months": 12
}),
});
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/planning.items",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"unit_id": "u2",
"month": "2027-01",
"component": "leavers_expected",
"scenario_id": "ps1",
"months": 12,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"unit": {
"id": "u2",
"name": "Engineering"
},
"month": "2027-01",
"component": "leavers_expected",
"value": 1,
"items": [
{
"kind": "contract_end_undecided",
"date": "2026-11-30",
"weight": 1,
"person": {
"id": "p3",
"name": "Rita Sousa",
"title": "Agent"
},
"position": null,
"unit": {
"id": "u2",
"name": "Engineering"
},
"other_unit": null,
"told": null,
"placed": null
}
],
"expected": null
}
}Planning scenarios#
POST/v1/org/planning.scenarios.listRead
The company's planning scenarios (at most 20, archived included), newest change first: name, status (draft, adopted, archived), horizon, assumptions and planned changes, version. include_archived (default false). Owners, admins and HR; never a custom role, a manager or a member. API keys, MCP and connected apps get headcount and FTE only: cost, on-cost and cost per head are left out (cost_hidden apps). Part of the Reports & analytics module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules); this read of stored data keeps working while it is off.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- On-cost and cost per head are left out.
- MCP tool
org_planning_scenarios_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
include_archivedbooleanDefault
false.
Returns
scenariosobject[]required12 fields
idstringrequirednamestringrequiredstatus"draft" | "adopted" | "archived"requiredhorizon_fromstringrequiredhorizon_monthsintegerrequiredassumptionsobjectrequired2 fields
defaultobjectrequired6 fields
vol_ratenumber | nullrequiredinvol_ratenumber | nullrequiredtime_to_fillnumberrequiredrenewal_ratenumberrequiredon_cost_pctnumber | nullrequiredpay_increasesobject[]required2 fields
from_monthstringrequiredpctnumberrequired
by_unitobjectrequired
changesobject[]required8 fields
idstringrequiredunit_idstringrequiredmonthstringrequiredkind"hire" | "reduce" | "move"requiredcountintegerrequiredto_unit_idstring | nullrequiredtitle_idstring | nullrequiredcost_per_headobject | nullrequired3 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
adopted_atstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredversionintegerrequiredcost_hidden"apps"requiredapps: on-cost and cost per head are left out for API keys, MCP and connected apps (open Bizisy).
countintegerrequiredlimitintegerrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/planning.scenarios.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"include_archived":true}'const res = await fetch('https://api.bizisy.com/v1/org/planning.scenarios.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"include_archived": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/planning.scenarios.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"include_archived": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"scenarios": [
{
"id": "ps1",
"name": "French ramp-up",
"status": "draft",
"horizon_from": "2026-10",
"horizon_months": 12,
"assumptions": {
"default": {
"vol_rate": null,
"invol_rate": null,
"time_to_fill": 2,
"renewal_rate": 0,
"on_cost_pct": 23.75,
"pay_increases": [
{
"from_month": "2027-01",
"pct": 3
}
]
},
"by_unit": {
"u2": {
"time_to_fill": 1
}
}
},
"changes": [
{
"id": "c1",
"unit_id": "u2",
"month": "2027-01",
"kind": "hire",
"count": 10,
"to_unit_id": null,
"title_id": null,
"cost_per_head": {
"amount": 1400,
"currency": "EUR",
"period": "month"
}
}
],
"adopted_at": null,
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:00:00.000Z",
"version": 2,
"cost_hidden": null
}
],
"count": 1,
"limit": 20
}
}A planning scenario#
POST/v1/org/planning.scenarios.getRead
One planning scenario by id: name, status, horizon, assumptions (company default copy and per-team overrides) and planned changes. Run org_planning_forecast with scenario_id for its numbers. Owners, admins and HR; never a custom role, a manager or a member. API keys, MCP and connected apps get headcount and FTE only: cost, on-cost and cost per head are left out (cost_hidden apps). Part of the Reports & analytics module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules); this read of stored data keeps working while it is off.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- On-cost and cost per head are left out.
- MCP tool
org_planning_scenarios_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
idstringrequired1–40 characters.
Returns
12 fields
idstringrequirednamestringrequiredstatus"draft" | "adopted" | "archived"requiredhorizon_fromstringrequiredhorizon_monthsintegerrequiredassumptionsobjectrequired2 fields
defaultobjectrequired6 fields
vol_ratenumber | nullrequiredinvol_ratenumber | nullrequiredtime_to_fillnumberrequiredrenewal_ratenumberrequiredon_cost_pctnumber | nullrequiredpay_increasesobject[]required2 fields
from_monthstringrequiredpctnumberrequired
by_unitobjectrequired
changesobject[]required8 fields
idstringrequiredunit_idstringrequiredmonthstringrequiredkind"hire" | "reduce" | "move"requiredcountintegerrequiredto_unit_idstring | nullrequiredtitle_idstring | nullrequiredcost_per_headobject | nullrequired3 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
adopted_atstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredversionintegerrequiredcost_hidden"apps"requiredapps: on-cost and cost per head are left out for API keys, MCP and connected apps (open Bizisy).
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/planning.scenarios.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"id":"ps1"}'const res = await fetch('https://api.bizisy.com/v1/org/planning.scenarios.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"id": "ps1"
}),
});
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/planning.scenarios.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"id": "ps1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "ps1",
"name": "French ramp-up",
"status": "draft",
"horizon_from": "2026-10",
"horizon_months": 12,
"assumptions": {
"default": {
"vol_rate": null,
"invol_rate": null,
"time_to_fill": 2,
"renewal_rate": 0,
"on_cost_pct": 23.75,
"pay_increases": [
{
"from_month": "2027-01",
"pct": 3
}
]
},
"by_unit": {
"u2": {
"time_to_fill": 1
}
}
},
"changes": [
{
"id": "c1",
"unit_id": "u2",
"month": "2027-01",
"kind": "hire",
"count": 10,
"to_unit_id": null,
"title_id": null,
"cost_per_head": {
"amount": 1400,
"currency": "EUR",
"period": "month"
}
}
],
"adopted_at": null,
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:00:00.000Z",
"version": 2,
"cost_hidden": null
}
}Create a planning scenario#
POST/v1/org/planning.scenarios.createWrite
Creates a draft planning scenario: name (at most 80 characters; shown wherever an adopted budget is shown, so keep reasons out of it), from_scenario_id (copy another scenario's horizon, assumptions and changes; default: the company's default assumptions and no changes), horizon_from (default this month), horizon_months (1–18, default 12), assumptions (vol_rate, invol_rate, time_to_fill, renewal_rate, on_cost_pct, pay_increases; any left out come from the copy), by_unit (per-team vol_rate, invol_rate, time_to_fill, renewal_rate) and changes (at most 200: {unit_id, month, kind hire|reduce|move, count 1–500, to_unit_id for move, title_id?, cost_per_head? {amount, currency, period} for hire}). Reductions are numbers per team, never named people: decisions about people go through Leaving, with your approval rules. At most 20 scenarios (archived count). Machines may create drafts but never send on-cost or cost per head ("Cost needs pay access"). Owners, admins and HR; never a custom role, a manager or a member. API keys, MCP and connected apps get headcount and FTE only: cost, on-cost and cost per head are left out (cost_hidden apps). Use dry_run first. Part of the Reports & analytics module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Drafts without on-cost or cost per head (refused if sent).
- MCP tool
org_planning_scenarios_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.
from_scenario_idstring1–40 characters.
horizon_fromstringPattern
^\d{4}-(0[1-9]|1[0-2])$.horizon_monthsintegerFrom 1 to 18.
assumptionsobject6 fields
vol_ratenumber | nullVoluntary leaving rate per month as a fraction (0.021 = 2.1 % a month); null: from your history (trailing 12 months).
From 0 to 0.5.
invol_ratenumber | nullInvoluntary leaving rate per month as a fraction; null: from your history.
From 0 to 0.5.
time_to_fillintegerMonths an open position without a target start date takes to fill (default 2).
From 0 to 24.
renewal_ratenumberShare (0–1) of fixed-term contract ends with no decision yet expected to be renewed (default 0: they end, as the law says).
From 0 to 1.
on_cost_pctnumber | nullEmployer on-cost on top of base pay in percent (social security, insurance); null: not entered. Pay tier: in the app only.
From 0 to 200.
pay_increasesobject[]Pay increases from a month, in percent (e.g. +3 from January).
Up to 12 items.
2 fields
from_monthstringrequiredPattern
^\d{4}-(0[1-9]|1[0-2])$.pctnumberrequiredFrom -50 to 100.
by_unitobjectchangesobject[]Up to 200 items.
8 fields
idstring1–40 characters.
unit_idstringrequiredmonthstringrequiredPattern
^\d{4}-(0[1-9]|1[0-2])$.kind"hire" | "reduce" | "move"requiredcountintegerrequiredFrom 1 to 500.
to_unit_idstring | nulltitle_idstring | nullcost_per_headobject | null3 fields
amountnumberrequiredFrom 0 to 10000000.
currencystringrequiredPattern
^[A-Z]{3}$.period"year" | "month" | "hour"required
Returns
12 fields
idstringrequirednamestringrequiredstatus"draft" | "adopted" | "archived"requiredhorizon_fromstringrequiredhorizon_monthsintegerrequiredassumptionsobjectrequired2 fields
defaultobjectrequired6 fields
vol_ratenumber | nullrequiredinvol_ratenumber | nullrequiredtime_to_fillnumberrequiredrenewal_ratenumberrequiredon_cost_pctnumber | nullrequiredpay_increasesobject[]required2 fields
from_monthstringrequiredpctnumberrequired
by_unitobjectrequired
changesobject[]required8 fields
idstringrequiredunit_idstringrequiredmonthstringrequiredkind"hire" | "reduce" | "move"requiredcountintegerrequiredto_unit_idstring | nullrequiredtitle_idstring | nullrequiredcost_per_headobject | nullrequired3 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
adopted_atstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredversionintegerrequiredcost_hidden"apps"requiredapps: on-cost and cost per head are left out for API keys, MCP and connected apps (open Bizisy).
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/planning.scenarios.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Copy",
"from_scenario_id": "ps1",
"horizon_from": "2026-11",
"horizon_months": 6,
"assumptions": {
"vol_rate": 0.02,
"on_cost_pct": 23.75
},
"by_unit": {
"u2": {
"time_to_fill": 1
}
},
"changes": [
{
"unit_id": "u2",
"month": "2027-01",
"kind": "hire",
"count": 10,
"cost_per_head": {
"amount": 1400,
"currency": "EUR",
"period": "month"
}
},
{
"unit_id": "u2",
"month": "2027-02",
"kind": "move",
"count": 2,
"to_unit_id": "u3"
}
]
}'const res = await fetch('https://api.bizisy.com/v1/org/planning.scenarios.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"name": "Copy",
"from_scenario_id": "ps1",
"horizon_from": "2026-11",
"horizon_months": 6,
"assumptions": {
"vol_rate": 0.02,
"on_cost_pct": 23.75
},
"by_unit": {
"u2": {
"time_to_fill": 1
}
},
"changes": [
{
"unit_id": "u2",
"month": "2027-01",
"kind": "hire",
"count": 10,
"cost_per_head": {
"amount": 1400,
"currency": "EUR",
"period": "month"
}
},
{
"unit_id": "u2",
"month": "2027-02",
"kind": "move",
"count": 2,
"to_unit_id": "u3"
}
]
}),
});
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/planning.scenarios.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "Copy",
"from_scenario_id": "ps1",
"horizon_from": "2026-11",
"horizon_months": 6,
"assumptions": {
"vol_rate": 0.02,
"on_cost_pct": 23.75,
},
"by_unit": {
"u2": {
"time_to_fill": 1,
},
},
"changes": [
{
"unit_id": "u2",
"month": "2027-01",
"kind": "hire",
"count": 10,
"cost_per_head": {
"amount": 1400,
"currency": "EUR",
"period": "month",
},
},
{
"unit_id": "u2",
"month": "2027-02",
"kind": "move",
"count": 2,
"to_unit_id": "u3",
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "ps1",
"name": "Copy",
"status": "draft",
"horizon_from": "2026-11",
"horizon_months": 6,
"assumptions": {
"default": {
"vol_rate": null,
"invol_rate": null,
"time_to_fill": 2,
"renewal_rate": 0,
"on_cost_pct": 23.75,
"pay_increases": [
{
"from_month": "2027-01",
"pct": 3
}
]
},
"by_unit": {
"u2": {
"time_to_fill": 1
}
}
},
"changes": [
{
"id": "c1",
"unit_id": "u2",
"month": "2027-01",
"kind": "hire",
"count": 10,
"to_unit_id": null,
"title_id": null,
"cost_per_head": {
"amount": 1400,
"currency": "EUR",
"period": "month"
}
}
],
"adopted_at": null,
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:00:00.000Z",
"version": 2,
"cost_hidden": null
}
}Change a planning scenario#
POST/v1/org/planning.scenarios.updateWrite
Changes a draft or adopted scenario: name, horizon_from, horizon_months, assumptions (only the fields sent change), by_unit (replaces the per-team overrides) and changes (replaces the list; keep each change's id). version: the version you read (a newer one is refused: "Someone else changed this scenario; reload"). An adopted scenario becomes a draft again once changed (its budget rows stay). Archived scenarios are restored first. Machines never send on-cost or cost per head; what HR entered is kept. Owners, admins and HR; never a custom role, a manager or a member. API keys, MCP and connected apps get headcount and FTE only: cost, on-cost and cost per head are left out (cost_hidden apps). Use dry_run first. Part of the Reports & analytics module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).
- Who can call it
- Manage key owner admin hr
- Keys and apps
- On-cost and cost per head are refused if sent; what HR entered is kept.
- MCP tool
org_planning_scenarios_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
idstringrequired1–40 characters.
versionintegerrequiredAt least 1.
namestring1–80 characters.
horizon_fromstringPattern
^\d{4}-(0[1-9]|1[0-2])$.horizon_monthsintegerFrom 1 to 18.
assumptionsobject6 fields
vol_ratenumber | nullVoluntary leaving rate per month as a fraction (0.021 = 2.1 % a month); null: from your history (trailing 12 months).
From 0 to 0.5.
invol_ratenumber | nullInvoluntary leaving rate per month as a fraction; null: from your history.
From 0 to 0.5.
time_to_fillintegerMonths an open position without a target start date takes to fill (default 2).
From 0 to 24.
renewal_ratenumberShare (0–1) of fixed-term contract ends with no decision yet expected to be renewed (default 0: they end, as the law says).
From 0 to 1.
on_cost_pctnumber | nullEmployer on-cost on top of base pay in percent (social security, insurance); null: not entered. Pay tier: in the app only.
From 0 to 200.
pay_increasesobject[]Pay increases from a month, in percent (e.g. +3 from January).
Up to 12 items.
2 fields
from_monthstringrequiredPattern
^\d{4}-(0[1-9]|1[0-2])$.pctnumberrequiredFrom -50 to 100.
by_unitobjectchangesobject[]Up to 200 items.
8 fields
idstring1–40 characters.
unit_idstringrequiredmonthstringrequiredPattern
^\d{4}-(0[1-9]|1[0-2])$.kind"hire" | "reduce" | "move"requiredcountintegerrequiredFrom 1 to 500.
to_unit_idstring | nulltitle_idstring | nullcost_per_headobject | null3 fields
amountnumberrequiredFrom 0 to 10000000.
currencystringrequiredPattern
^[A-Z]{3}$.period"year" | "month" | "hour"required
Returns
12 fields
idstringrequirednamestringrequiredstatus"draft" | "adopted" | "archived"requiredhorizon_fromstringrequiredhorizon_monthsintegerrequiredassumptionsobjectrequired2 fields
defaultobjectrequired6 fields
vol_ratenumber | nullrequiredinvol_ratenumber | nullrequiredtime_to_fillnumberrequiredrenewal_ratenumberrequiredon_cost_pctnumber | nullrequiredpay_increasesobject[]required2 fields
from_monthstringrequiredpctnumberrequired
by_unitobjectrequired
changesobject[]required8 fields
idstringrequiredunit_idstringrequiredmonthstringrequiredkind"hire" | "reduce" | "move"requiredcountintegerrequiredto_unit_idstring | nullrequiredtitle_idstring | nullrequiredcost_per_headobject | nullrequired3 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
adopted_atstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredversionintegerrequiredcost_hidden"apps"requiredapps: on-cost and cost per head are left out for API keys, MCP and connected apps (open Bizisy).
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/planning.scenarios.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"id": "ps1",
"version": 2,
"changes": [
{
"id": "c1",
"unit_id": "u2",
"month": "2027-01",
"kind": "reduce",
"count": 1
}
],
"assumptions": {
"renewal_rate": 0.6,
"pay_increases": [
{
"from_month": "2027-01",
"pct": 3
}
]
}
}'const res = await fetch('https://api.bizisy.com/v1/org/planning.scenarios.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"id": "ps1",
"version": 2,
"changes": [
{
"id": "c1",
"unit_id": "u2",
"month": "2027-01",
"kind": "reduce",
"count": 1
}
],
"assumptions": {
"renewal_rate": 0.6,
"pay_increases": [
{
"from_month": "2027-01",
"pct": 3
}
]
}
}),
});
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/planning.scenarios.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"id": "ps1",
"version": 2,
"changes": [
{
"id": "c1",
"unit_id": "u2",
"month": "2027-01",
"kind": "reduce",
"count": 1,
},
],
"assumptions": {
"renewal_rate": 0.6,
"pay_increases": [
{
"from_month": "2027-01",
"pct": 3,
},
],
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "ps1",
"name": "French ramp-up",
"status": "draft",
"horizon_from": "2026-10",
"horizon_months": 12,
"assumptions": {
"default": {
"vol_rate": null,
"invol_rate": null,
"time_to_fill": 2,
"renewal_rate": 0,
"on_cost_pct": 23.75,
"pay_increases": [
{
"from_month": "2027-01",
"pct": 3
}
]
},
"by_unit": {
"u2": {
"time_to_fill": 1
}
}
},
"changes": [
{
"id": "c1",
"unit_id": "u2",
"month": "2027-01",
"kind": "hire",
"count": 10,
"to_unit_id": null,
"title_id": null,
"cost_per_head": {
"amount": 1400,
"currency": "EUR",
"period": "month"
}
}
],
"adopted_at": null,
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:00:00.000Z",
"version": 2,
"cost_hidden": null
}
}Archive a planning scenario#
POST/v1/org/planning.scenarios.archiveWrite
Archives a scenario: it leaves the list (include_archived shows it) and still counts toward the 20. Budgets it wrote stay. Owners, admins and HR; never a custom role, a manager or a member. API keys, MCP and connected apps get headcount and FTE only: cost, on-cost and cost per head are left out (cost_hidden apps). Use dry_run first. Part of the Reports & analytics module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).
- Who can call it
- Manage key owner admin hr
- Keys and apps
- On-cost and cost per head are left out of the result.
- MCP tool
org_planning_scenarios_archiveon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
idstringrequired1–40 characters.
Returns
12 fields
idstringrequirednamestringrequiredstatus"draft" | "adopted" | "archived"requiredhorizon_fromstringrequiredhorizon_monthsintegerrequiredassumptionsobjectrequired2 fields
defaultobjectrequired6 fields
vol_ratenumber | nullrequiredinvol_ratenumber | nullrequiredtime_to_fillnumberrequiredrenewal_ratenumberrequiredon_cost_pctnumber | nullrequiredpay_increasesobject[]required2 fields
from_monthstringrequiredpctnumberrequired
by_unitobjectrequired
changesobject[]required8 fields
idstringrequiredunit_idstringrequiredmonthstringrequiredkind"hire" | "reduce" | "move"requiredcountintegerrequiredto_unit_idstring | nullrequiredtitle_idstring | nullrequiredcost_per_headobject | nullrequired3 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
adopted_atstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredversionintegerrequiredcost_hidden"apps"requiredapps: on-cost and cost per head are left out for API keys, MCP and connected apps (open Bizisy).
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/planning.scenarios.archive \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"id":"ps1"}'const res = await fetch('https://api.bizisy.com/v1/org/planning.scenarios.archive', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"id": "ps1"
}),
});
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/planning.scenarios.archive",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"id": "ps1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "ps1",
"name": "French ramp-up",
"status": "archived",
"horizon_from": "2026-10",
"horizon_months": 12,
"assumptions": {
"default": {
"vol_rate": null,
"invol_rate": null,
"time_to_fill": 2,
"renewal_rate": 0,
"on_cost_pct": 23.75,
"pay_increases": [
{
"from_month": "2027-01",
"pct": 3
}
]
},
"by_unit": {
"u2": {
"time_to_fill": 1
}
}
},
"changes": [
{
"id": "c1",
"unit_id": "u2",
"month": "2027-01",
"kind": "hire",
"count": 10,
"to_unit_id": null,
"title_id": null,
"cost_per_head": {
"amount": 1400,
"currency": "EUR",
"period": "month"
}
}
],
"adopted_at": null,
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:00:00.000Z",
"version": 3,
"cost_hidden": null
}
}Restore a planning scenario#
POST/v1/org/planning.scenarios.restoreWrite
Restores an archived scenario as a draft. Owners, admins and HR; never a custom role, a manager or a member. API keys, MCP and connected apps get headcount and FTE only: cost, on-cost and cost per head are left out (cost_hidden apps). Use dry_run first. Part of the Reports & analytics module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).
- Who can call it
- Manage key owner admin hr
- Keys and apps
- On-cost and cost per head are left out of the result.
- MCP tool
org_planning_scenarios_restoreon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
idstringrequired1–40 characters.
Returns
12 fields
idstringrequirednamestringrequiredstatus"draft" | "adopted" | "archived"requiredhorizon_fromstringrequiredhorizon_monthsintegerrequiredassumptionsobjectrequired2 fields
defaultobjectrequired6 fields
vol_ratenumber | nullrequiredinvol_ratenumber | nullrequiredtime_to_fillnumberrequiredrenewal_ratenumberrequiredon_cost_pctnumber | nullrequiredpay_increasesobject[]required2 fields
from_monthstringrequiredpctnumberrequired
by_unitobjectrequired
changesobject[]required8 fields
idstringrequiredunit_idstringrequiredmonthstringrequiredkind"hire" | "reduce" | "move"requiredcountintegerrequiredto_unit_idstring | nullrequiredtitle_idstring | nullrequiredcost_per_headobject | nullrequired3 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
adopted_atstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredversionintegerrequiredcost_hidden"apps"requiredapps: on-cost and cost per head are left out for API keys, MCP and connected apps (open Bizisy).
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/planning.scenarios.restore \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"id":"ps1"}'const res = await fetch('https://api.bizisy.com/v1/org/planning.scenarios.restore', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"id": "ps1"
}),
});
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/planning.scenarios.restore",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"id": "ps1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "ps1",
"name": "French ramp-up",
"status": "draft",
"horizon_from": "2026-10",
"horizon_months": 12,
"assumptions": {
"default": {
"vol_rate": null,
"invol_rate": null,
"time_to_fill": 2,
"renewal_rate": 0,
"on_cost_pct": 23.75,
"pay_increases": [
{
"from_month": "2027-01",
"pct": 3
}
]
},
"by_unit": {
"u2": {
"time_to_fill": 1
}
}
},
"changes": [
{
"id": "c1",
"unit_id": "u2",
"month": "2027-01",
"kind": "hire",
"count": 10,
"to_unit_id": null,
"title_id": null,
"cost_per_head": {
"amount": 1400,
"currency": "EUR",
"period": "month"
}
}
],
"adopted_at": null,
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:00:00.000Z",
"version": 4,
"cost_hidden": null
}
}Compare planning scenarios#
POST/v1/org/planning.scenarios.compareRead
Compares 2–4 scenarios side by side ("baseline" for the forecast with company assumptions and no changes) over one horizon (horizon_from, months; default this month and the longest of their horizons) and the same teams (unit_ids, default as org_planning_forecast): per scenario, totals and per team the end headcount, end FTE, average monthly cost, total cost over the horizon, months over budget and peak gap (the smallest budget − end; negative = over), and the month-by-month end headcount and cost of the total. Owners, admins and HR; never a custom role, a manager or a member. API keys, MCP and connected apps get headcount and FTE only: cost, on-cost and cost per head are left out (cost_hidden apps). Part of the Reports & analytics module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Headcount and FTE only: cost is left out.
- MCP tool
org_planning_scenarios_compareon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
idsstring[]required1–40 characters. 2–4 items.
unit_idsstring[]Up to 50 items.
horizon_fromstringPattern
^\d{4}-(0[1-9]|1[0-2])$.monthsintegerFrom 1 to 18.
Returns
monthsstring[]requiredcurrencystring | nullrequiredcost_hidden"apps" | "no_pay"requiredteamsobject[]required4 fields
idstringrequirednamestringrequiredkindstringrequiredparent_idstring | nullrequired
scenariosobject[]required6 fields
idstringrequirednamestringrequiredstatus"draft" | "adopted" | "archived" | "baseline"requiredtotalsobjectrequired6 fields
endnumberrequiredfte_endnumberrequiredaverage_costnumber | nullrequiredtotal_costnumber | nullrequiredmonths_overintegerrequiredpeak_gapnumber | nullrequired
monthsobject[]required4 fields
monthstringrequiredendnumberrequiredcostnumber | nullrequiredbudgetnumber | nullrequired
teamsobject[]required7 fields
unit_idstringrequiredendnumberrequiredfte_endnumberrequiredaverage_costnumber | nullrequiredtotal_costnumber | nullrequiredmonths_overintegerrequiredpeak_gapnumber | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/planning.scenarios.compare \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"ids": [
"baseline",
"ps1",
"ps2"
],
"unit_ids": [
"u2"
],
"horizon_from": "2026-10",
"months": 12
}'const res = await fetch('https://api.bizisy.com/v1/org/planning.scenarios.compare', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"ids": [
"baseline",
"ps1",
"ps2"
],
"unit_ids": [
"u2"
],
"horizon_from": "2026-10",
"months": 12
}),
});
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/planning.scenarios.compare",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"ids": [
"baseline",
"ps1",
"ps2",
],
"unit_ids": [
"u2",
],
"horizon_from": "2026-10",
"months": 12,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"months": [
"2026-10",
"2026-11"
],
"currency": "EUR",
"cost_hidden": null,
"teams": [
{
"id": "u2",
"name": "Engineering",
"kind": "department",
"parent_id": "u1"
}
],
"scenarios": [
{
"id": "baseline",
"name": "Baseline",
"status": "baseline",
"totals": {
"end": 8,
"fte_end": 7.5,
"average_cost": 24000,
"total_cost": 48000,
"months_over": 0,
"peak_gap": 0
},
"months": [
{
"month": "2026-10",
"end": 8,
"cost": 24000,
"budget": 8
},
{
"month": "2026-11",
"end": 8,
"cost": 24000,
"budget": 8
}
],
"teams": [
{
"unit_id": "u2",
"end": 8,
"fte_end": 7.5,
"average_cost": 24000,
"total_cost": 48000,
"months_over": 0,
"peak_gap": 0
}
]
},
{
"id": "ps1",
"name": "French ramp-up",
"status": "draft",
"totals": {
"end": 10,
"fte_end": 9.5,
"average_cost": 27000,
"total_cost": 54000,
"months_over": 1,
"peak_gap": -2
},
"months": [
{
"month": "2026-10",
"end": 8,
"cost": 24000,
"budget": 8
},
{
"month": "2026-11",
"end": 10,
"cost": 30000,
"budget": 8
}
],
"teams": [
{
"unit_id": "u2",
"end": 10,
"fte_end": 9.5,
"average_cost": 27000,
"total_cost": 54000,
"months_over": 1,
"peak_gap": -2
}
]
}
]
}
}Adopt a scenario as the headcount budget#
POST/v1/org/planning.scenarios.adoptWrite
Writes a scenario's forecast as headcount budgets: for each team (unit_ids, default as org_planning_forecast) and month of its horizon where the scenario's end headcount (rounded up) differs from the budget in force, one budget row (org_budgets_set's rules: live teams, at most 2,000 rows) with fte and the note "From scenario '<name>'". A dry run is the preview: rows lists every row it would write or replace; blocked says why it cannot run. The scenario becomes adopted (a scenario adopted before goes back to draft). It never creates positions, hires or terminations: people decide those. Owners, admins and HR signed in to Bizisy only (never API keys, MCP or connected apps); never a custom role. Use dry_run first and show the rows. Part of the Reports & analytics module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).
- Web app only
- Refused for API keys and connected apps. Adopting a scenario changes the budget: in the Bizisy app.
- MCP tool
org_planning_scenarios_adopton HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
idstringrequired1–40 characters.
versionintegerrequiredThe version you previewed: a newer one is refused ("Someone else changed this scenario; reload").
At least 1.
unit_idsstring[]Up to 50 items.
Returns
scenarioobjectrequired12 fields
idstringrequirednamestringrequiredstatus"draft" | "adopted" | "archived"requiredhorizon_fromstringrequiredhorizon_monthsintegerrequiredassumptionsobjectrequired2 fields
defaultobjectrequired6 fields
vol_ratenumber | nullrequiredinvol_ratenumber | nullrequiredtime_to_fillnumberrequiredrenewal_ratenumberrequiredon_cost_pctnumber | nullrequiredpay_increasesobject[]required2 fields
from_monthstringrequiredpctnumberrequired
by_unitobjectrequired
changesobject[]required8 fields
idstringrequiredunit_idstringrequiredmonthstringrequiredkind"hire" | "reduce" | "move"requiredcountintegerrequiredto_unit_idstring | nullrequiredtitle_idstring | nullrequiredcost_per_headobject | nullrequired3 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
adopted_atstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredversionintegerrequiredcost_hidden"apps"requiredapps: on-cost and cost per head are left out for API keys, MCP and connected apps (open Bizisy).
rowsobject[]required7 fields
unitobjectrequired2 fields
idstringrequirednamestringrequired
from_monthstringrequiredheadcountintegerrequiredftenumber | nullrequirednotestringrequiredreplacesinteger | nullrequiredThe headcount of the budget row for that team and month it replaces; null: a new row.
in_forceinteger | nullrequiredThe budget in force before (null: none).
writtenintegerrequiredblockedstring | nullrequiredpositions_to_createintegerrequiredPlanned hires and roles beyond the open positions: create them in Positions, one by one.
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/planning.scenarios.adopt \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"id":"ps1","version":2,"unit_ids":["u2"]}'const res = await fetch('https://api.bizisy.com/v1/org/planning.scenarios.adopt', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"id": "ps1",
"version": 2,
"unit_ids": [
"u2"
]
}),
});
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/planning.scenarios.adopt",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"id": "ps1",
"version": 2,
"unit_ids": [
"u2",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"scenario": {
"id": "ps1",
"name": "French ramp-up",
"status": "adopted",
"horizon_from": "2026-10",
"horizon_months": 12,
"assumptions": {
"default": {
"vol_rate": null,
"invol_rate": null,
"time_to_fill": 2,
"renewal_rate": 0,
"on_cost_pct": 23.75,
"pay_increases": [
{
"from_month": "2027-01",
"pct": 3
}
]
},
"by_unit": {
"u2": {
"time_to_fill": 1
}
}
},
"changes": [
{
"id": "c1",
"unit_id": "u2",
"month": "2027-01",
"kind": "hire",
"count": 10,
"to_unit_id": null,
"title_id": null,
"cost_per_head": {
"amount": 1400,
"currency": "EUR",
"period": "month"
}
}
],
"adopted_at": "2026-10-04T10:00:00.000Z",
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:00:00.000Z",
"version": 3,
"cost_hidden": null
},
"rows": [
{
"unit": {
"id": "u2",
"name": "Engineering"
},
"from_month": "2026-11",
"headcount": 10,
"fte": 9.5,
"note": "From scenario 'French ramp-up'",
"replaces": null,
"in_force": 8
}
],
"written": 1,
"blocked": null,
"positions_to_create": 2
}
}Planning assumptions#
POST/v1/org/planning.settings.getRead
The company's default planning assumptions (Settings → Planning; new scenarios and the baseline use them): vol_rate and invol_rate (monthly; null = from your history, shown in history), time_to_fill (months, default 2), renewal_rate (0–1, default 0), on_cost_pct (employer on-cost %, blank until entered: it differs by country), pay_increases. Owners, admins and HR; never a custom role, a manager or a member. API keys, MCP and connected apps get headcount and FTE only: cost, on-cost and cost per head are left out (cost_hidden apps). Part of the Reports & analytics module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules); this read of stored data keeps working while it is off.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- The on-cost is left out.
- MCP tool
org_planning_settings_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
assumptionsobjectrequired6 fields
vol_ratenumber | nullrequiredinvol_ratenumber | nullrequiredtime_to_fillnumberrequiredrenewal_ratenumberrequiredon_cost_pctnumber | nullrequiredpay_increasesobject[]required2 fields
from_monthstringrequiredpctnumberrequired
historyobjectrequired3 fields
vol_ratenumberrequiredinvol_ratenumberrequiredpeopleintegerrequired
updated_atstring | nullrequiredcost_hidden"apps"required
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/planning.settings.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/planning.settings.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/planning.settings.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"assumptions": {
"vol_rate": null,
"invol_rate": null,
"time_to_fill": 2,
"renewal_rate": 0,
"on_cost_pct": null,
"pay_increases": []
},
"history": {
"vol_rate": 0.012,
"invol_rate": 0.003,
"people": 8
},
"updated_at": null,
"cost_hidden": null
}
}Change the planning assumptions#
POST/v1/org/planning.settings.updateWrite
Changes the company's default planning assumptions (only the fields sent): vol_rate, invol_rate (null: from your history), time_to_fill, renewal_rate, on_cost_pct, pay_increases. Existing scenarios keep their own copy. Machines never send on_cost_pct ("Cost needs pay access"). Owners, admins and HR; never a custom role, a manager or a member. API keys, MCP and connected apps get headcount and FTE only: cost, on-cost and cost per head are left out (cost_hidden apps). Use dry_run first. Part of the Reports & analytics module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).
- Who can call it
- Manage key owner admin hr
- Keys and apps
- The on-cost is refused if sent.
- MCP tool
org_planning_settings_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
assumptionsobjectrequired6 fields
vol_ratenumber | nullVoluntary leaving rate per month as a fraction (0.021 = 2.1 % a month); null: from your history (trailing 12 months).
From 0 to 0.5.
invol_ratenumber | nullInvoluntary leaving rate per month as a fraction; null: from your history.
From 0 to 0.5.
time_to_fillintegerMonths an open position without a target start date takes to fill (default 2).
From 0 to 24.
renewal_ratenumberShare (0–1) of fixed-term contract ends with no decision yet expected to be renewed (default 0: they end, as the law says).
From 0 to 1.
on_cost_pctnumber | nullEmployer on-cost on top of base pay in percent (social security, insurance); null: not entered. Pay tier: in the app only.
From 0 to 200.
pay_increasesobject[]Pay increases from a month, in percent (e.g. +3 from January).
Up to 12 items.
2 fields
from_monthstringrequiredPattern
^\d{4}-(0[1-9]|1[0-2])$.pctnumberrequiredFrom -50 to 100.
Returns
assumptionsobjectrequired6 fields
vol_ratenumber | nullrequiredinvol_ratenumber | nullrequiredtime_to_fillnumberrequiredrenewal_ratenumberrequiredon_cost_pctnumber | nullrequiredpay_increasesobject[]required2 fields
from_monthstringrequiredpctnumberrequired
historyobjectrequired3 fields
vol_ratenumberrequiredinvol_ratenumberrequiredpeopleintegerrequired
updated_atstring | nullrequiredcost_hidden"apps"required
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/planning.settings.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"assumptions": {
"vol_rate": null,
"invol_rate": 0.004,
"time_to_fill": 3,
"renewal_rate": 0.5,
"pay_increases": []
}
}'const res = await fetch('https://api.bizisy.com/v1/org/planning.settings.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"assumptions": {
"vol_rate": null,
"invol_rate": 0.004,
"time_to_fill": 3,
"renewal_rate": 0.5,
"pay_increases": []
}
}),
});
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/planning.settings.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"assumptions": {
"vol_rate": None,
"invol_rate": 0.004,
"time_to_fill": 3,
"renewal_rate": 0.5,
"pay_increases": [],
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"assumptions": {
"vol_rate": null,
"invol_rate": null,
"time_to_fill": 2,
"renewal_rate": 0,
"on_cost_pct": 23.75,
"pay_increases": []
},
"history": {
"vol_rate": 0.012,
"invol_rate": 0.003,
"people": 8
},
"updated_at": "2026-10-04T10:00:00.000Z",
"cost_hidden": null
}
}Export a forecast or comparison#
POST/v1/org/planning.exportRead
A forecast (view forecast: one row per team and month with every component, the budget, gap and, for owners, admins and HR signed in to Bizisy, cost) or a comparison (view compare, ids: 2–4 scenarios or "baseline") as CSV, with a definitions section at the end saying how each column is calculated. Same inputs and rules as org_planning_forecast and org_planning_scenarios_compare: machines get headcount and FTE only, never cost. delimiter , or ; (default ,). Owners, admins and HR; never a custom role, a manager or a member. API keys, MCP and connected apps get headcount and FTE only: cost, on-cost and cost per head are left out (cost_hidden apps). Part of the Reports & analytics module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Headcount and FTE columns only: no cost.
- MCP tool
org_planning_exporton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
view"forecast" | "compare"Default
"forecast".scenario_idstring | null1–40 characters.
idsstring[]1–40 characters. 2–4 items.
unit_idsstring[]Up to 50 items.
horizon_fromstringPattern
^\d{4}-(0[1-9]|1[0-2])$.monthsintegerFrom 1 to 18.
delimiter"," | ";"Default
",".
Returns
filenamestringrequiredcsvstringrequiredrowsintegerrequiredcost_hidden"apps" | "no_pay"required
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/planning.export \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"view": "compare",
"ids": [
"baseline",
"ps1"
],
"unit_ids": [
"u2"
],
"months": 12,
"delimiter": ";"
}'const res = await fetch('https://api.bizisy.com/v1/org/planning.export', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"view": "compare",
"ids": [
"baseline",
"ps1"
],
"unit_ids": [
"u2"
],
"months": 12,
"delimiter": ";"
}),
});
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/planning.export",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"view": "compare",
"ids": [
"baseline",
"ps1",
],
"unit_ids": [
"u2",
],
"months": 12,
"delimiter": ";",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"filename": "bizisy-forecast-2026-10-04.csv",
"csv": "team,month,start\r\nEngineering,2026-10,8",
"rows": 1,
"cost_hidden": null
}
}Something missing or wrong on this page? Write to hello@bizisy.com.