Skip to content

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_forecast on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • unit_idsstring[]

    Up to 50 items.

  • horizon_fromstring

    Pattern ^\d{4}-(0[1-9]|1[0-2])$.

  • monthsinteger

    From 1 to 18.

  • scenario_idstring | null

    1–40 characters.

  • draftobject

    Unsaved 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
    • assumptionsobject
      6 fields
      • vol_ratenumber | null

        Voluntary 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 | null

        Involuntary leaving rate per month as a fraction; null: from your history.

        From 0 to 0.5.

      • time_to_fillinteger

        Months an open position without a target start date takes to fill (default 2).

        From 0 to 24.

      • renewal_ratenumber

        Share (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 | null

        Employer 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_monthstringrequired

          Pattern ^\d{4}-(0[1-9]|1[0-2])$.

        • pctnumberrequired

          From -50 to 100.

    • by_unitobject
    • changesobject[]

      Up to 200 items.

      8 fields
      • idstring

        1–40 characters.

      • unit_idstringrequired
      • monthstringrequired

        Pattern ^\d{4}-(0[1-9]|1[0-2])$.

      • kind"hire" | "reduce" | "move"required
      • countintegerrequired

        From 1 to 500.

      • to_unit_idstring | null
      • title_idstring | null
      • cost_per_headobject | null
        3 fields
        • amountnumberrequired

          From 0 to 10000000.

        • currencystringrequired

          Pattern ^[A-Z]{3}$.

        • period"year" | "month" | "hour"required

Returns

12 fields
  • as_ofstringrequired
  • horizon_fromstringrequired
  • monthsstring[]required
  • scenarioobject | nullrequired

    null: the baseline (company default assumptions, no planned changes).

    4 fields
    • idstringrequired
    • namestringrequired
    • status"draft" | "adopted" | "archived"required
    • versionintegerrequired
  • currencystring | nullrequired
  • cost_hidden"apps" | "no_pay"required

    apps: cost is never given to API keys, MCP or connected apps; no_pay: no pay recorded in the main currency.

  • assumptionsobjectrequired
    6 fields
    • vol_ratenumber | nullrequired
    • invol_ratenumber | nullrequired
    • time_to_fillnumberrequired
    • renewal_ratenumberrequired
    • on_cost_pctnumber | nullrequired
    • pay_increasesobject[]required
      2 fields
      • from_monthstringrequired
      • pctnumberrequired
  • historyobjectrequired
    3 fields
    • vol_ratenumberrequired
    • invol_ratenumberrequired
    • peopleintegerrequired
  • teamsobject[]required
    11 fields
    • unitobjectrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • kindstringrequired
      • parent_idstring | nullrequired
    • ratesobjectrequired
      5 fields
      • vol_ratenumberrequired
      • invol_ratenumberrequired
      • source"set" | "team_history" | "company_history"required
      • time_to_fillnumberrequired
      • renewal_ratenumberrequired
    • historyobject | nullrequired
      3 fields
      • vol_ratenumberrequired
      • invol_ratenumberrequired
      • peopleintegerrequired
    • monthsobject[]required
      18 fields
      • monthstringrequired
      • startnumberrequired
      • joiners_knownnumberrequired
      • joiners_opennumberrequired
      • joiners_requestednumberrequired

        Positions waiting for approval to open, in the month they would start: shown apart, never counted in end.

      • hires_plannednumberrequired
      • moves_innumberrequired
      • leavers_knownnumberrequired
      • contract_endsnumberrequired
      • leavers_expectednumberrequired
      • reductions_plannednumberrequired
      • moves_outnumberrequired
      • endnumberrequired
      • fte_endnumberrequired
      • budgetinteger | nullrequired
      • gapnumber | nullrequired
      • status"over" | "over_with_open" | "on_budget" | "room"required
      • costnumber | nullrequired
    • months_overintegerrequired
    • peak_gapnumber | nullrequired
    • endnumberrequired
    • fte_endnumberrequired
    • total_costnumber | nullrequired
    • average_costnumber | nullrequired
    • not_costedobject | nullrequired
      3 fields
      • no_payintegerrequired
      • other_currencyintegerrequired
      • currenciesstring[]required
  • totalsobjectrequired
    4 fields
    • monthsobject[]required
      7 fields
      • monthstringrequired
      • startnumberrequired
      • endnumberrequired
      • fte_endnumberrequired
      • budgetinteger | nullrequired
      • gapnumber | nullrequired
      • costnumber | nullrequired
    • months_overintegerrequired
    • endnumberrequired
    • total_costnumber | nullrequired
  • default_teamsbooleanrequired

    true: no unit_ids were given; the top-level budgeted teams (else the teams under the company) are shown.

  • truncatedbooleanrequired

    true: 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
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
      }
    ]
  }
}'
Response
{
  "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_items on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • unit_idstringrequired
  • monthstringrequired

    Pattern ^\d{4}-(0[1-9]|1[0-2])$.

  • component"joiners_known" | "joiners_open" | "leavers_known" | "contract_ends" | "leavers_expected"required
  • scenario_idstring | null

    1–40 characters.

  • horizon_fromstring

    Pattern ^\d{4}-(0[1-9]|1[0-2])$.

  • monthsinteger

    From 1 to 18.

Returns

  • unitobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • monthstringrequired
  • component"joiners_known" | "joiners_open" | "leavers_known" | "contract_ends" | "leavers_expected"required
  • valuenumberrequired
  • itemsobject[]required
    9 fields
    • kindstring (enum)required

      One of: hire, transfer_in, transfer_out, termination, contract_end, contract_end_undecided, position.

    • datestring | nullrequired
    • weightnumberrequired
    • personobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
    • positionobject | nullrequired
      2 fields
      • idstringrequired
      • titlestringrequired
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • other_unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • toldboolean | nullrequired

      Terminations: false while the person has not been told about their last day (keep it with HR).

    • placed"target" | "time_to_fill"required
  • expectedobject | nullrequired
    3 fields
    • basenumberrequired
    • ratenumberrequired
    • valuenumberrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
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
}'
Response
{
  "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_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • include_archivedboolean

    Default false.

Returns

  • scenariosobject[]required
    12 fields
    • idstringrequired
    • namestringrequired
    • status"draft" | "adopted" | "archived"required
    • horizon_fromstringrequired
    • horizon_monthsintegerrequired
    • assumptionsobjectrequired
      2 fields
      • defaultobjectrequired
        6 fields
        • vol_ratenumber | nullrequired
        • invol_ratenumber | nullrequired
        • time_to_fillnumberrequired
        • renewal_ratenumberrequired
        • on_cost_pctnumber | nullrequired
        • pay_increasesobject[]required
          2 fields
          • from_monthstringrequired
          • pctnumberrequired
      • by_unitobjectrequired
    • changesobject[]required
      8 fields
      • idstringrequired
      • unit_idstringrequired
      • monthstringrequired
      • kind"hire" | "reduce" | "move"required
      • countintegerrequired
      • to_unit_idstring | nullrequired
      • title_idstring | nullrequired
      • cost_per_headobject | nullrequired
        3 fields
        • amountnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
    • adopted_atstring | nullrequired
    • created_atstringrequired
    • updated_atstringrequired
    • versionintegerrequired
    • cost_hidden"apps"required

      apps: on-cost and cost per head are left out for API keys, MCP and connected apps (open Bizisy).

  • countintegerrequired
  • limitintegerrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
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}'
Response
{
  "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_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • idstringrequired

    1–40 characters.

Returns

12 fields
  • idstringrequired
  • namestringrequired
  • status"draft" | "adopted" | "archived"required
  • horizon_fromstringrequired
  • horizon_monthsintegerrequired
  • assumptionsobjectrequired
    2 fields
    • defaultobjectrequired
      6 fields
      • vol_ratenumber | nullrequired
      • invol_ratenumber | nullrequired
      • time_to_fillnumberrequired
      • renewal_ratenumberrequired
      • on_cost_pctnumber | nullrequired
      • pay_increasesobject[]required
        2 fields
        • from_monthstringrequired
        • pctnumberrequired
    • by_unitobjectrequired
  • changesobject[]required
    8 fields
    • idstringrequired
    • unit_idstringrequired
    • monthstringrequired
    • kind"hire" | "reduce" | "move"required
    • countintegerrequired
    • to_unit_idstring | nullrequired
    • title_idstring | nullrequired
    • cost_per_headobject | nullrequired
      3 fields
      • amountnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
  • adopted_atstring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired
  • versionintegerrequired
  • cost_hidden"apps"required

    apps: 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
curl https://api.bizisy.com/v1/org/planning.scenarios.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"ps1"}'
Response
{
  "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_create on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • namestringrequired

    1–80 characters.

  • from_scenario_idstring

    1–40 characters.

  • horizon_fromstring

    Pattern ^\d{4}-(0[1-9]|1[0-2])$.

  • horizon_monthsinteger

    From 1 to 18.

  • assumptionsobject
    6 fields
    • vol_ratenumber | null

      Voluntary 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 | null

      Involuntary leaving rate per month as a fraction; null: from your history.

      From 0 to 0.5.

    • time_to_fillinteger

      Months an open position without a target start date takes to fill (default 2).

      From 0 to 24.

    • renewal_ratenumber

      Share (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 | null

      Employer 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_monthstringrequired

        Pattern ^\d{4}-(0[1-9]|1[0-2])$.

      • pctnumberrequired

        From -50 to 100.

  • by_unitobject
  • changesobject[]

    Up to 200 items.

    8 fields
    • idstring

      1–40 characters.

    • unit_idstringrequired
    • monthstringrequired

      Pattern ^\d{4}-(0[1-9]|1[0-2])$.

    • kind"hire" | "reduce" | "move"required
    • countintegerrequired

      From 1 to 500.

    • to_unit_idstring | null
    • title_idstring | null
    • cost_per_headobject | null
      3 fields
      • amountnumberrequired

        From 0 to 10000000.

      • currencystringrequired

        Pattern ^[A-Z]{3}$.

      • period"year" | "month" | "hour"required

Returns

12 fields
  • idstringrequired
  • namestringrequired
  • status"draft" | "adopted" | "archived"required
  • horizon_fromstringrequired
  • horizon_monthsintegerrequired
  • assumptionsobjectrequired
    2 fields
    • defaultobjectrequired
      6 fields
      • vol_ratenumber | nullrequired
      • invol_ratenumber | nullrequired
      • time_to_fillnumberrequired
      • renewal_ratenumberrequired
      • on_cost_pctnumber | nullrequired
      • pay_increasesobject[]required
        2 fields
        • from_monthstringrequired
        • pctnumberrequired
    • by_unitobjectrequired
  • changesobject[]required
    8 fields
    • idstringrequired
    • unit_idstringrequired
    • monthstringrequired
    • kind"hire" | "reduce" | "move"required
    • countintegerrequired
    • to_unit_idstring | nullrequired
    • title_idstring | nullrequired
    • cost_per_headobject | nullrequired
      3 fields
      • amountnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
  • adopted_atstring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired
  • versionintegerrequired
  • cost_hidden"apps"required

    apps: 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
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"
    }
  ]
}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • idstringrequired

    1–40 characters.

  • versionintegerrequired

    At least 1.

  • namestring

    1–80 characters.

  • horizon_fromstring

    Pattern ^\d{4}-(0[1-9]|1[0-2])$.

  • horizon_monthsinteger

    From 1 to 18.

  • assumptionsobject
    6 fields
    • vol_ratenumber | null

      Voluntary 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 | null

      Involuntary leaving rate per month as a fraction; null: from your history.

      From 0 to 0.5.

    • time_to_fillinteger

      Months an open position without a target start date takes to fill (default 2).

      From 0 to 24.

    • renewal_ratenumber

      Share (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 | null

      Employer 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_monthstringrequired

        Pattern ^\d{4}-(0[1-9]|1[0-2])$.

      • pctnumberrequired

        From -50 to 100.

  • by_unitobject
  • changesobject[]

    Up to 200 items.

    8 fields
    • idstring

      1–40 characters.

    • unit_idstringrequired
    • monthstringrequired

      Pattern ^\d{4}-(0[1-9]|1[0-2])$.

    • kind"hire" | "reduce" | "move"required
    • countintegerrequired

      From 1 to 500.

    • to_unit_idstring | null
    • title_idstring | null
    • cost_per_headobject | null
      3 fields
      • amountnumberrequired

        From 0 to 10000000.

      • currencystringrequired

        Pattern ^[A-Z]{3}$.

      • period"year" | "month" | "hour"required

Returns

12 fields
  • idstringrequired
  • namestringrequired
  • status"draft" | "adopted" | "archived"required
  • horizon_fromstringrequired
  • horizon_monthsintegerrequired
  • assumptionsobjectrequired
    2 fields
    • defaultobjectrequired
      6 fields
      • vol_ratenumber | nullrequired
      • invol_ratenumber | nullrequired
      • time_to_fillnumberrequired
      • renewal_ratenumberrequired
      • on_cost_pctnumber | nullrequired
      • pay_increasesobject[]required
        2 fields
        • from_monthstringrequired
        • pctnumberrequired
    • by_unitobjectrequired
  • changesobject[]required
    8 fields
    • idstringrequired
    • unit_idstringrequired
    • monthstringrequired
    • kind"hire" | "reduce" | "move"required
    • countintegerrequired
    • to_unit_idstring | nullrequired
    • title_idstring | nullrequired
    • cost_per_headobject | nullrequired
      3 fields
      • amountnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
  • adopted_atstring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired
  • versionintegerrequired
  • cost_hidden"apps"required

    apps: 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
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
      }
    ]
  }
}'
Response
{
  "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_archive on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • idstringrequired

    1–40 characters.

Returns

12 fields
  • idstringrequired
  • namestringrequired
  • status"draft" | "adopted" | "archived"required
  • horizon_fromstringrequired
  • horizon_monthsintegerrequired
  • assumptionsobjectrequired
    2 fields
    • defaultobjectrequired
      6 fields
      • vol_ratenumber | nullrequired
      • invol_ratenumber | nullrequired
      • time_to_fillnumberrequired
      • renewal_ratenumberrequired
      • on_cost_pctnumber | nullrequired
      • pay_increasesobject[]required
        2 fields
        • from_monthstringrequired
        • pctnumberrequired
    • by_unitobjectrequired
  • changesobject[]required
    8 fields
    • idstringrequired
    • unit_idstringrequired
    • monthstringrequired
    • kind"hire" | "reduce" | "move"required
    • countintegerrequired
    • to_unit_idstring | nullrequired
    • title_idstring | nullrequired
    • cost_per_headobject | nullrequired
      3 fields
      • amountnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
  • adopted_atstring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired
  • versionintegerrequired
  • cost_hidden"apps"required

    apps: 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
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"}'
Response
{
  "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_restore on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • idstringrequired

    1–40 characters.

Returns

12 fields
  • idstringrequired
  • namestringrequired
  • status"draft" | "adopted" | "archived"required
  • horizon_fromstringrequired
  • horizon_monthsintegerrequired
  • assumptionsobjectrequired
    2 fields
    • defaultobjectrequired
      6 fields
      • vol_ratenumber | nullrequired
      • invol_ratenumber | nullrequired
      • time_to_fillnumberrequired
      • renewal_ratenumberrequired
      • on_cost_pctnumber | nullrequired
      • pay_increasesobject[]required
        2 fields
        • from_monthstringrequired
        • pctnumberrequired
    • by_unitobjectrequired
  • changesobject[]required
    8 fields
    • idstringrequired
    • unit_idstringrequired
    • monthstringrequired
    • kind"hire" | "reduce" | "move"required
    • countintegerrequired
    • to_unit_idstring | nullrequired
    • title_idstring | nullrequired
    • cost_per_headobject | nullrequired
      3 fields
      • amountnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
  • adopted_atstring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired
  • versionintegerrequired
  • cost_hidden"apps"required

    apps: 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
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"}'
Response
{
  "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_compare on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • idsstring[]required

    1–40 characters. 2–4 items.

  • unit_idsstring[]

    Up to 50 items.

  • horizon_fromstring

    Pattern ^\d{4}-(0[1-9]|1[0-2])$.

  • monthsinteger

    From 1 to 18.

Returns

  • monthsstring[]required
  • currencystring | nullrequired
  • cost_hidden"apps" | "no_pay"required
  • teamsobject[]required
    4 fields
    • idstringrequired
    • namestringrequired
    • kindstringrequired
    • parent_idstring | nullrequired
  • scenariosobject[]required
    6 fields
    • idstringrequired
    • namestringrequired
    • status"draft" | "adopted" | "archived" | "baseline"required
    • totalsobjectrequired
      6 fields
      • endnumberrequired
      • fte_endnumberrequired
      • average_costnumber | nullrequired
      • total_costnumber | nullrequired
      • months_overintegerrequired
      • peak_gapnumber | nullrequired
    • monthsobject[]required
      4 fields
      • monthstringrequired
      • endnumberrequired
      • costnumber | nullrequired
      • budgetnumber | nullrequired
    • teamsobject[]required
      7 fields
      • unit_idstringrequired
      • endnumberrequired
      • fte_endnumberrequired
      • average_costnumber | nullrequired
      • total_costnumber | nullrequired
      • months_overintegerrequired
      • peak_gapnumber | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
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
}'
Response
{
  "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_adopt on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • idstringrequired

    1–40 characters.

  • versionintegerrequired

    The version you previewed: a newer one is refused ("Someone else changed this scenario; reload").

    At least 1.

  • unit_idsstring[]

    Up to 50 items.

Returns

  • scenarioobjectrequired
    12 fields
    • idstringrequired
    • namestringrequired
    • status"draft" | "adopted" | "archived"required
    • horizon_fromstringrequired
    • horizon_monthsintegerrequired
    • assumptionsobjectrequired
      2 fields
      • defaultobjectrequired
        6 fields
        • vol_ratenumber | nullrequired
        • invol_ratenumber | nullrequired
        • time_to_fillnumberrequired
        • renewal_ratenumberrequired
        • on_cost_pctnumber | nullrequired
        • pay_increasesobject[]required
          2 fields
          • from_monthstringrequired
          • pctnumberrequired
      • by_unitobjectrequired
    • changesobject[]required
      8 fields
      • idstringrequired
      • unit_idstringrequired
      • monthstringrequired
      • kind"hire" | "reduce" | "move"required
      • countintegerrequired
      • to_unit_idstring | nullrequired
      • title_idstring | nullrequired
      • cost_per_headobject | nullrequired
        3 fields
        • amountnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
    • adopted_atstring | nullrequired
    • created_atstringrequired
    • updated_atstringrequired
    • versionintegerrequired
    • cost_hidden"apps"required

      apps: on-cost and cost per head are left out for API keys, MCP and connected apps (open Bizisy).

  • rowsobject[]required
    7 fields
    • unitobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • from_monthstringrequired
    • headcountintegerrequired
    • ftenumber | nullrequired
    • notestringrequired
    • replacesinteger | nullrequired

      The headcount of the budget row for that team and month it replaces; null: a new row.

    • in_forceinteger | nullrequired

      The budget in force before (null: none).

  • writtenintegerrequired
  • blockedstring | nullrequired
  • positions_to_createintegerrequired

    Planned 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
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"]}'
Response
{
  "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_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • assumptionsobjectrequired
    6 fields
    • vol_ratenumber | nullrequired
    • invol_ratenumber | nullrequired
    • time_to_fillnumberrequired
    • renewal_ratenumberrequired
    • on_cost_pctnumber | nullrequired
    • pay_increasesobject[]required
      2 fields
      • from_monthstringrequired
      • pctnumberrequired
  • historyobjectrequired
    3 fields
    • vol_ratenumberrequired
    • invol_ratenumberrequired
    • peopleintegerrequired
  • updated_atstring | nullrequired
  • cost_hidden"apps"required

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/planning.settings.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • assumptionsobjectrequired
    6 fields
    • vol_ratenumber | null

      Voluntary 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 | null

      Involuntary leaving rate per month as a fraction; null: from your history.

      From 0 to 0.5.

    • time_to_fillinteger

      Months an open position without a target start date takes to fill (default 2).

      From 0 to 24.

    • renewal_ratenumber

      Share (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 | null

      Employer 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_monthstringrequired

        Pattern ^\d{4}-(0[1-9]|1[0-2])$.

      • pctnumberrequired

        From -50 to 100.

Returns

  • assumptionsobjectrequired
    6 fields
    • vol_ratenumber | nullrequired
    • invol_ratenumber | nullrequired
    • time_to_fillnumberrequired
    • renewal_ratenumberrequired
    • on_cost_pctnumber | nullrequired
    • pay_increasesobject[]required
      2 fields
      • from_monthstringrequired
      • pctnumberrequired
  • historyobjectrequired
    3 fields
    • vol_ratenumberrequired
    • invol_ratenumberrequired
    • peopleintegerrequired
  • updated_atstring | nullrequired
  • cost_hidden"apps"required

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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": []
  }
}'
Response
{
  "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_export on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • view"forecast" | "compare"

    Default "forecast".

  • scenario_idstring | null

    1–40 characters.

  • idsstring[]

    1–40 characters. 2–4 items.

  • unit_idsstring[]

    Up to 50 items.

  • horizon_fromstring

    Pattern ^\d{4}-(0[1-9]|1[0-2])$.

  • monthsinteger

    From 1 to 18.

  • delimiter"," | ";"

    Default ",".

Returns

  • filenamestringrequired
  • csvstringrequired
  • rowsintegerrequired
  • cost_hidden"apps" | "no_pay"required

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
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": ";"
}'
Response
{
  "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.

Developer docs