Skip to content

API reference

Bonus plans

Bonus plans by a published formula (target % of base pay × company factor × individual factor from ratings and, when weighted, committed goals × share of the period worked, in cents), launch, managers' adjustments in %, HR approval under the pay approval rules, the equal-pay check by sex per category, release to payroll and letters. Pay stays in the app: API keys and AI assistants get plan names, dates and status only.

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

List bonus plans#

POST/v1/comp/bonus.plans.listRead

Bonus plans: name, status (draft, launching, open, releasing, released, cancelled), performance period and payout day. Owners, admins and HR see every plan (Manage → Bonus plans). In Me, a manager sees the open plans where they may adjust their reports' awards. API keys and AI assistants get names, dates and status only: never pay, people or awards. Part of the Salary reviews 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
Me key owner admin hr member
Keys and apps
Names, dates and status only: never pay, people or awards.
MCP tool
comp_bonus_plans_list on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • itemsobject[]required
    6 fields
    • idstringrequired
    • namestringrequired
    • status"draft" | "launching" | "open" | "releasing" | "released" | "cancelled"required
    • periodobjectrequired
      2 fields
      • fromstringrequired
      • tostringrequired
    • payout_onstringrequired
    • manager_adjust_pctintegerrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/bonus.plans.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "items": [
      {
        "id": "bp1",
        "name": "2026 bonus",
        "status": "open",
        "period": {
          "from": "2026-01-01",
          "to": "2026-12-31"
        },
        "payout_on": "2027-01-31",
        "manager_adjust_pct": 10
      }
    ]
  }
}

Get a bonus plan#

POST/v1/comp/bonus.plans.getRead

One bonus plan: its setup (period, payout day, population, eligibility, target %, company factor, the rating table, goals weight, cap, proration, manager adjustments), whether its formula is published to staff, awards by state, totals per currency (formula, awards, target), what a release would do now and how released awards are paid. Owners, admins and HR, in the app only (pay data). Part of the Salary reviews 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.

Web app only
Refused for API keys and connected apps. A plan's formula, totals and payouts hold pay: read in the app only.
MCP tool
comp_bonus_plans_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • plan_idstringrequired

Returns

20 fields
  • idstringrequired
  • namestringrequired
  • status"draft" | "launching" | "open" | "releasing" | "released" | "cancelled"required
  • periodobjectrequired
    2 fields
    • fromstringrequired
    • tostringrequired
  • payout_onstringrequired
  • populationobjectrequired
    5 fields (one of several shapes)

    Option 1

    • kind"company"required

    Option 2

    • kind"units"required
    • unit_idsstring[]required

      1–200 items.

    Option 3

    • kind"entities"required
    • entity_idsstring[]required

      1–50 items.

  • eligibilityobjectrequired
    2 fields
    • cutoff_datestringrequired
    • employment_typesstring[]required
  • targetobjectrequired
    3 fields
    • default_pctnumberrequired
    • by_titleobject[]required
      2 fields
      • titlestringrequired
      • pctnumberrequired
    • onstringrequired
  • company_factornumber | nullrequired
  • individualobjectrequired
    5 fields
    • rating_cycle_idstring | nullrequired
    • by_ratingobject[]required
      3 fields
      • valuenumberrequired
      • labelstringrequired
      • pctnumberrequired
    • no_rating_pctnumberrequired
    • goals_weightnumberrequired
    • capnumberrequired
  • prorationobjectrequired
    1 field
    • other_unpaid_leave"counted" | "not_counted"required
  • manager_adjust_pctintegerrequired
  • formulaobjectrequired
    2 fields
    • published_atstring | nullrequired
    • shared_otherwise_atstring | nullrequired
  • launchobject | nullrequired
    2 fields
    • doneintegerrequired
    • totalintegerrequired
  • countsobjectrequired
    5 fields
    • draftintegerrequired
    • approvedintegerrequired
    • skippedintegerrequired
    • releasedintegerrequired
    • adjustedintegerrequired
  • totalsobject[]required
    4 fields
    • currencystringrequired
    • formula_centsintegerrequired
    • award_centsintegerrequired
    • target_centsintegerrequired
  • releaseobjectrequired
    5 fields
    • payintegerrequired
    • zerointegerrequired
    • skipintegerrequired
    • doneintegerrequired
    • totalsobject[]required
      2 fields
      • currencystringrequired
      • centsintegerrequired
  • payoutsobjectrequired
    3 fields
    • in_payrollintegerrequired
    • by_handintegerrequired
    • paidintegerrequired
  • created_atstringrequired
  • released_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/bonus.plans.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan_id":"bp1"}'
Response
{
  "data": {
    "id": "bp1",
    "name": "2026 bonus",
    "status": "open",
    "period": {
      "from": "2026-01-01",
      "to": "2026-12-31"
    },
    "payout_on": "2027-01-31",
    "population": {
      "kind": "company"
    },
    "eligibility": {
      "cutoff_date": "2026-12-31",
      "employment_types": []
    },
    "target": {
      "default_pct": 10,
      "by_title": [
        {
          "title": "Engineering Lead",
          "pct": 15
        }
      ],
      "on": "2026-12-31"
    },
    "company_factor": 100,
    "individual": {
      "rating_cycle_id": "rc1",
      "by_rating": [
        {
          "value": 1,
          "label": "Well below expectations",
          "pct": 0
        },
        {
          "value": 2,
          "label": "Below expectations",
          "pct": 50
        },
        {
          "value": 3,
          "label": "Meets expectations",
          "pct": 100
        },
        {
          "value": 4,
          "label": "Exceeds expectations",
          "pct": 120
        },
        {
          "value": 5,
          "label": "Outstanding",
          "pct": 150
        }
      ],
      "no_rating_pct": 100,
      "goals_weight": 0,
      "cap": 200
    },
    "proration": {
      "other_unpaid_leave": "counted"
    },
    "manager_adjust_pct": 10,
    "formula": {
      "published_at": "2026-11-16T10:00:00.000Z",
      "shared_otherwise_at": null
    },
    "launch": null,
    "counts": {
      "draft": 3,
      "approved": 1,
      "skipped": 0,
      "released": 0,
      "adjusted": 1
    },
    "totals": [
      {
        "currency": "EUR",
        "formula_cents": 1910000,
        "award_cents": 1946000,
        "target_cents": 1910000
      }
    ],
    "release": {
      "pay": 1,
      "zero": 0,
      "skip": 3,
      "done": 0,
      "totals": [
        {
          "currency": "EUR",
          "cents": 432000
        }
      ]
    },
    "payouts": {
      "in_payroll": 0,
      "by_hand": 0,
      "paid": 0
    },
    "created_at": "2026-11-16T10:00:00.000Z",
    "released_at": null
  }
}

Create a bonus plan#

POST/v1/comp/bonus.plans.createWrite

Creates a bonus plan as a draft. Payout = annual base × target % × company factor × individual factor × proration, in cents, rounded once (half up). Defaults: target 10 % (other targets per job title), company factor 100 % (null: set it later), individual factor from the final calibrated rating of a performance cycle (0 / 50 / 100 / 120 / 150 % for a 1–5 scale; "No rating" 100 %), goals weight 0 % (only goals HR marked committed count when it is on), cap 200 %, proration by days employed in the period with maternity, paternity, birth, adoption and parental leave always counted as worked and other unpaid leave counted unless chosen otherwise, managers adjusting within ±0 % (formula only). The result's preview counts who takes part, the total per currency and works the formula through for one real person (example_person_id, default the middle base pay): use dry_run. At most 3 open plans. Owners, admins and HR, in the app only. Part of the Salary reviews 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. Bonus plans are set up in the app only.
MCP tool
comp_bonus_plans_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–120 characters.

  • periodobjectrequired

    The performance period (inclusive).

    2 fields
    • fromstringrequired

      Pattern ^\d{4}-\d{2}-\d{2}$.

    • tostringrequired

      Pattern ^\d{4}-\d{2}-\d{2}$.

  • payout_onstringrequired

    Payout day: the release runs that day from 08:00 company time; the payroll item is due then.

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • populationobject

    Default {"kind":"company"}.

    5 fields (one of several shapes)

    Option 1

    • kind"company"required

    Option 2

    • kind"units"required
    • unit_idsstring[]required

      1–200 items.

    Option 3

    • kind"entities"required
    • entity_idsstring[]required

      1–50 items.

  • eligibilityobject

    Default {}.

    2 fields
    • cutoff_datestring

      Employed on this day to take part (default the period's last day).

      Pattern ^\d{4}-\d{2}-\d{2}$.

    • employment_types"full_time" | "part_time" | "contractor" | "intern"[]

      Up to 4 items.

  • targetobject

    Default {"default_pct":10}.

    3 fields
    • default_pctnumberrequired

      Target bonus, % of the annual base (default 10).

      From 0 to 200.

    • by_titleobject[]

      Other targets for some job titles (exact title).

      Up to 100 items.

      2 fields
      • titlestringrequired

        1–120 characters.

      • pctnumberrequired

        From 0 to 200.

    • onstring

      The day whose base pay counts (default the period's last day).

      Pattern ^\d{4}-\d{2}-\d{2}$.

  • company_factornumber | null

    0–200 % (default 100); null: set it later (approving and paying wait for it).

    From 0 to 200.

  • individualobject

    Default {}.

    5 fields
    • rating_cycle_idstring | null

      The performance review cycle whose final, calibrated ratings pick the rating factor; null: everyone gets the "No rating" factor.

      1–200 characters.

    • by_ratingobject[]

      Factor % per rating level (default 0 / 50 / 100 / 120 / 150 for a 1–5 scale).

      1–9 items.

      3 fields
      • valueintegerrequired

        From -10 to 20.

      • labelstringrequired

        1–60 characters.

      • pctnumberrequired

        From 0 to 200.

    • no_rating_pctnumber

      Factor % for people without a calibrated rating (default 100: never 0 for a missing rating).

      From 0 to 200.

    • goals_weightnumber

      Share of the individual factor from committed goals (addendum B1: default 0; goals are OKRs, meant to be ambitious; only goals HR marked committed count).

      From 0 to 100.

    • capnumber

      The individual factor's maximum % (default 200).

      From 0 to 200.

  • prorationobject

    Default {"other_unpaid_leave":"counted"}.

    1 field
    • other_unpaid_leave"counted" | "not_counted"required

      Other unpaid leave (never maternity, paternity, birth, adoption or parental leave, which always count as worked): counted as worked (default) or not. National law may differ.

  • manager_adjust_pctinteger

    Managers may move their reports' awards within ± this % of the formula (default 0: formula only).

    From 0 to 50.

  • example_person_idstring

    Show the worked example for this person (default: the person with the middle base pay).

    1–200 characters.

Returns

  • planobjectrequired
    20 fields
    • idstringrequired
    • namestringrequired
    • status"draft" | "launching" | "open" | "releasing" | "released" | "cancelled"required
    • periodobjectrequired
      2 fields
      • fromstringrequired
      • tostringrequired
    • payout_onstringrequired
    • populationobjectrequired
      5 fields (one of several shapes)

      Option 1

      • kind"company"required

      Option 2

      • kind"units"required
      • unit_idsstring[]required

        1–200 items.

      Option 3

      • kind"entities"required
      • entity_idsstring[]required

        1–50 items.

    • eligibilityobjectrequired
      2 fields
      • cutoff_datestringrequired
      • employment_typesstring[]required
    • targetobjectrequired
      3 fields
      • default_pctnumberrequired
      • by_titleobject[]required
        2 fields
        • titlestringrequired
        • pctnumberrequired
      • onstringrequired
    • company_factornumber | nullrequired
    • individualobjectrequired
      5 fields
      • rating_cycle_idstring | nullrequired
      • by_ratingobject[]required
        3 fields
        • valuenumberrequired
        • labelstringrequired
        • pctnumberrequired
      • no_rating_pctnumberrequired
      • goals_weightnumberrequired
      • capnumberrequired
    • prorationobjectrequired
      1 field
      • other_unpaid_leave"counted" | "not_counted"required
    • manager_adjust_pctintegerrequired
    • formulaobjectrequired
      2 fields
      • published_atstring | nullrequired
      • shared_otherwise_atstring | nullrequired
    • launchobject | nullrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • countsobjectrequired
      5 fields
      • draftintegerrequired
      • approvedintegerrequired
      • skippedintegerrequired
      • releasedintegerrequired
      • adjustedintegerrequired
    • totalsobject[]required
      4 fields
      • currencystringrequired
      • formula_centsintegerrequired
      • award_centsintegerrequired
      • target_centsintegerrequired
    • releaseobjectrequired
      5 fields
      • payintegerrequired
      • zerointegerrequired
      • skipintegerrequired
      • doneintegerrequired
      • totalsobject[]required
        2 fields
        • currencystringrequired
        • centsintegerrequired
    • payoutsobjectrequired
      3 fields
      • in_payrollintegerrequired
      • by_handintegerrequired
      • paidintegerrequired
    • created_atstringrequired
    • released_atstring | nullrequired
  • previewobjectrequired
    9 fields
    • eligibleintegerrequired
    • excludedobjectrequired
      2 fields
      • not_employedintegerrequired
      • employment_typeintegerrequired
    • no_payintegerrequired
    • protected_leaveintegerrequired
    • part_periodintegerrequired
    • no_ratingintegerrequired
    • totalsobject[]required

      The formula's total per currency (with a company factor of 100 % while it is not set).

      2 fields
      • currencystringrequired
      • centsintegerrequired
    • exampleobject | nullrequired

      The formula worked through for one real person (HR only).

      16 fields
      • person_idstringrequired
      • namestringrequired
      • currencystringrequired
      • base_centsintegerrequired
      • target_pctnumberrequired
      • company_pctnumberrequired
      • ratingnumber | nullrequired
      • rating_labelstring | nullrequired
      • rating_pctnumberrequired
      • goals_pctnumber | nullrequired
      • individual_pctnumberrequired
      • daysintegerrequired
      • unpaid_daysintegerrequired
      • period_daysintegerrequired
      • prorationnumberrequired
      • centsintegerrequired
    • peopleobject[]required

      Who the example can show (up to 200, by name).

      2 fields
      • idstringrequired
      • namestringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/bonus.plans.create \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "2026 bonus",
  "period": {
    "from": "2026-01-01",
    "to": "2026-12-31"
  },
  "payout_on": "2027-01-31",
  "target": {
    "default_pct": 10,
    "by_title": [
      {
        "title": "Engineering Lead",
        "pct": 15
      }
    ]
  },
  "company_factor": null,
  "individual": {
    "rating_cycle_id": "rc1",
    "goals_weight": 20,
    "cap": 150
  },
  "proration": {
    "other_unpaid_leave": "not_counted"
  },
  "manager_adjust_pct": 10,
  "example_person_id": "p3"
}'
Response
{
  "data": {
    "plan": {
      "id": "bp1",
      "name": "2026 bonus",
      "status": "draft",
      "period": {
        "from": "2026-01-01",
        "to": "2026-12-31"
      },
      "payout_on": "2027-01-31",
      "population": {
        "kind": "company"
      },
      "eligibility": {
        "cutoff_date": "2026-12-31",
        "employment_types": []
      },
      "target": {
        "default_pct": 10,
        "by_title": [
          {
            "title": "Engineering Lead",
            "pct": 15
          }
        ],
        "on": "2026-12-31"
      },
      "company_factor": 100,
      "individual": {
        "rating_cycle_id": "rc1",
        "by_rating": [
          {
            "value": 1,
            "label": "Well below expectations",
            "pct": 0
          },
          {
            "value": 2,
            "label": "Below expectations",
            "pct": 50
          },
          {
            "value": 3,
            "label": "Meets expectations",
            "pct": 100
          },
          {
            "value": 4,
            "label": "Exceeds expectations",
            "pct": 120
          },
          {
            "value": 5,
            "label": "Outstanding",
            "pct": 150
          }
        ],
        "no_rating_pct": 100,
        "goals_weight": 0,
        "cap": 200
      },
      "proration": {
        "other_unpaid_leave": "counted"
      },
      "manager_adjust_pct": 10,
      "formula": {
        "published_at": null,
        "shared_otherwise_at": null
      },
      "launch": null,
      "counts": {
        "draft": 3,
        "approved": 1,
        "skipped": 0,
        "released": 0,
        "adjusted": 1
      },
      "totals": [
        {
          "currency": "EUR",
          "formula_cents": 1910000,
          "award_cents": 1946000,
          "target_cents": 1910000
        }
      ],
      "release": {
        "pay": 1,
        "zero": 0,
        "skip": 3,
        "done": 0,
        "totals": [
          {
            "currency": "EUR",
            "cents": 432000
          }
        ]
      },
      "payouts": {
        "in_payroll": 0,
        "by_hand": 0,
        "paid": 0
      },
      "created_at": "2026-11-16T10:00:00.000Z",
      "released_at": null
    },
    "preview": {
      "eligible": 5,
      "excluded": {
        "not_employed": 0,
        "employment_type": 0
      },
      "no_pay": 1,
      "protected_leave": 1,
      "part_period": 0,
      "no_rating": 1,
      "totals": [
        {
          "currency": "EUR",
          "cents": 1910000
        }
      ],
      "example": {
        "person_id": "p5",
        "name": "Eva Silva",
        "currency": "EUR",
        "base_cents": 4500000,
        "target_pct": 10,
        "company_pct": 100,
        "rating": 3,
        "rating_label": "Meets expectations",
        "rating_pct": 100,
        "goals_pct": null,
        "individual_pct": 100,
        "days": 365,
        "unpaid_days": 0,
        "period_days": 365,
        "proration": 1,
        "cents": 450000
      },
      "people": [
        {
          "id": "p3",
          "name": "Carl Silva"
        },
        {
          "id": "p5",
          "name": "Eva Silva"
        }
      ]
    }
  }
}

Change a bonus plan#

POST/v1/comp/bonus.plans.updateWrite

Changes a bonus plan (only what is given). Before launch anything; once open, the name, payout day, targets, company factor, rating table, goals weight, cap and manager adjustments (the period, population, eligibility, ratings cycle and proration are fixed at launch). Changing the formula of an open plan recomputes every award not released; approved awards whose amount changes go back to draft. The preview works the formula through again. Owners, admins and HR, in the app only. Part of the Salary reviews 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. Bonus plans are set up in the app only.
MCP tool
comp_bonus_plans_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

  • namestring

    1–120 characters.

  • periodobject

    The performance period (inclusive).

    2 fields
    • fromstringrequired

      Pattern ^\d{4}-\d{2}-\d{2}$.

    • tostringrequired

      Pattern ^\d{4}-\d{2}-\d{2}$.

  • payout_onstring

    Payout day: the release runs that day from 08:00 company time; the payroll item is due then.

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • populationobject

    Default {"kind":"company"}.

    5 fields (one of several shapes)

    Option 1

    • kind"company"required

    Option 2

    • kind"units"required
    • unit_idsstring[]required

      1–200 items.

    Option 3

    • kind"entities"required
    • entity_idsstring[]required

      1–50 items.

  • eligibilityobject

    Default {}.

    2 fields
    • cutoff_datestring

      Employed on this day to take part (default the period's last day).

      Pattern ^\d{4}-\d{2}-\d{2}$.

    • employment_types"full_time" | "part_time" | "contractor" | "intern"[]

      Up to 4 items.

  • targetobject

    Default {"default_pct":10}.

    3 fields
    • default_pctnumberrequired

      Target bonus, % of the annual base (default 10).

      From 0 to 200.

    • by_titleobject[]

      Other targets for some job titles (exact title).

      Up to 100 items.

      2 fields
      • titlestringrequired

        1–120 characters.

      • pctnumberrequired

        From 0 to 200.

    • onstring

      The day whose base pay counts (default the period's last day).

      Pattern ^\d{4}-\d{2}-\d{2}$.

  • company_factornumber | null

    0–200 % (default 100); null: set it later (approving and paying wait for it).

    From 0 to 200.

  • individualobject

    Default {}.

    5 fields
    • rating_cycle_idstring | null

      The performance review cycle whose final, calibrated ratings pick the rating factor; null: everyone gets the "No rating" factor.

      1–200 characters.

    • by_ratingobject[]

      Factor % per rating level (default 0 / 50 / 100 / 120 / 150 for a 1–5 scale).

      1–9 items.

      3 fields
      • valueintegerrequired

        From -10 to 20.

      • labelstringrequired

        1–60 characters.

      • pctnumberrequired

        From 0 to 200.

    • no_rating_pctnumber

      Factor % for people without a calibrated rating (default 100: never 0 for a missing rating).

      From 0 to 200.

    • goals_weightnumber

      Share of the individual factor from committed goals (addendum B1: default 0; goals are OKRs, meant to be ambitious; only goals HR marked committed count).

      From 0 to 100.

    • capnumber

      The individual factor's maximum % (default 200).

      From 0 to 200.

  • prorationobject

    Default {"other_unpaid_leave":"counted"}.

    1 field
    • other_unpaid_leave"counted" | "not_counted"required

      Other unpaid leave (never maternity, paternity, birth, adoption or parental leave, which always count as worked): counted as worked (default) or not. National law may differ.

  • manager_adjust_pctinteger

    Managers may move their reports' awards within ± this % of the formula (default 0: formula only).

    From 0 to 50.

  • example_person_idstring

    Show the worked example for this person (default: the person with the middle base pay).

    1–200 characters.

  • plan_idstringrequired

Returns

  • planobjectrequired
    20 fields
    • idstringrequired
    • namestringrequired
    • status"draft" | "launching" | "open" | "releasing" | "released" | "cancelled"required
    • periodobjectrequired
      2 fields
      • fromstringrequired
      • tostringrequired
    • payout_onstringrequired
    • populationobjectrequired
      5 fields (one of several shapes)

      Option 1

      • kind"company"required

      Option 2

      • kind"units"required
      • unit_idsstring[]required

        1–200 items.

      Option 3

      • kind"entities"required
      • entity_idsstring[]required

        1–50 items.

    • eligibilityobjectrequired
      2 fields
      • cutoff_datestringrequired
      • employment_typesstring[]required
    • targetobjectrequired
      3 fields
      • default_pctnumberrequired
      • by_titleobject[]required
        2 fields
        • titlestringrequired
        • pctnumberrequired
      • onstringrequired
    • company_factornumber | nullrequired
    • individualobjectrequired
      5 fields
      • rating_cycle_idstring | nullrequired
      • by_ratingobject[]required
        3 fields
        • valuenumberrequired
        • labelstringrequired
        • pctnumberrequired
      • no_rating_pctnumberrequired
      • goals_weightnumberrequired
      • capnumberrequired
    • prorationobjectrequired
      1 field
      • other_unpaid_leave"counted" | "not_counted"required
    • manager_adjust_pctintegerrequired
    • formulaobjectrequired
      2 fields
      • published_atstring | nullrequired
      • shared_otherwise_atstring | nullrequired
    • launchobject | nullrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • countsobjectrequired
      5 fields
      • draftintegerrequired
      • approvedintegerrequired
      • skippedintegerrequired
      • releasedintegerrequired
      • adjustedintegerrequired
    • totalsobject[]required
      4 fields
      • currencystringrequired
      • formula_centsintegerrequired
      • award_centsintegerrequired
      • target_centsintegerrequired
    • releaseobjectrequired
      5 fields
      • payintegerrequired
      • zerointegerrequired
      • skipintegerrequired
      • doneintegerrequired
      • totalsobject[]required
        2 fields
        • currencystringrequired
        • centsintegerrequired
    • payoutsobjectrequired
      3 fields
      • in_payrollintegerrequired
      • by_handintegerrequired
      • paidintegerrequired
    • created_atstringrequired
    • released_atstring | nullrequired
  • previewobject | nullrequired
    9 fields
    • eligibleintegerrequired
    • excludedobjectrequired
      2 fields
      • not_employedintegerrequired
      • employment_typeintegerrequired
    • no_payintegerrequired
    • protected_leaveintegerrequired
    • part_periodintegerrequired
    • no_ratingintegerrequired
    • totalsobject[]required

      The formula's total per currency (with a company factor of 100 % while it is not set).

      2 fields
      • currencystringrequired
      • centsintegerrequired
    • exampleobject | nullrequired

      The formula worked through for one real person (HR only).

      16 fields
      • person_idstringrequired
      • namestringrequired
      • currencystringrequired
      • base_centsintegerrequired
      • target_pctnumberrequired
      • company_pctnumberrequired
      • ratingnumber | nullrequired
      • rating_labelstring | nullrequired
      • rating_pctnumberrequired
      • goals_pctnumber | nullrequired
      • individual_pctnumberrequired
      • daysintegerrequired
      • unpaid_daysintegerrequired
      • period_daysintegerrequired
      • prorationnumberrequired
      • centsintegerrequired
    • peopleobject[]required

      Who the example can show (up to 200, by name).

      2 fields
      • idstringrequired
      • namestringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/bonus.plans.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"plan_id":"bp1","target":{"default_pct":12},"manager_adjust_pct":5}'
Response
{
  "data": {
    "plan": {
      "id": "bp1",
      "name": "2026 bonus",
      "status": "open",
      "period": {
        "from": "2026-01-01",
        "to": "2026-12-31"
      },
      "payout_on": "2027-01-31",
      "population": {
        "kind": "company"
      },
      "eligibility": {
        "cutoff_date": "2026-12-31",
        "employment_types": []
      },
      "target": {
        "default_pct": 10,
        "by_title": [
          {
            "title": "Engineering Lead",
            "pct": 15
          }
        ],
        "on": "2026-12-31"
      },
      "company_factor": 100,
      "individual": {
        "rating_cycle_id": "rc1",
        "by_rating": [
          {
            "value": 1,
            "label": "Well below expectations",
            "pct": 0
          },
          {
            "value": 2,
            "label": "Below expectations",
            "pct": 50
          },
          {
            "value": 3,
            "label": "Meets expectations",
            "pct": 100
          },
          {
            "value": 4,
            "label": "Exceeds expectations",
            "pct": 120
          },
          {
            "value": 5,
            "label": "Outstanding",
            "pct": 150
          }
        ],
        "no_rating_pct": 100,
        "goals_weight": 0,
        "cap": 200
      },
      "proration": {
        "other_unpaid_leave": "counted"
      },
      "manager_adjust_pct": 10,
      "formula": {
        "published_at": "2026-11-16T10:00:00.000Z",
        "shared_otherwise_at": null
      },
      "launch": null,
      "counts": {
        "draft": 3,
        "approved": 1,
        "skipped": 0,
        "released": 0,
        "adjusted": 1
      },
      "totals": [
        {
          "currency": "EUR",
          "formula_cents": 1910000,
          "award_cents": 1946000,
          "target_cents": 1910000
        }
      ],
      "release": {
        "pay": 1,
        "zero": 0,
        "skip": 3,
        "done": 0,
        "totals": [
          {
            "currency": "EUR",
            "cents": 432000
          }
        ]
      },
      "payouts": {
        "in_payroll": 0,
        "by_hand": 0,
        "paid": 0
      },
      "created_at": "2026-11-16T10:00:00.000Z",
      "released_at": null
    },
    "preview": null
  }
}

Publish a bonus plan's formula#

POST/v1/comp/bonus.plans.publish_formulaWrite

Publishes a bonus plan's formula to everyone (EU Pay Transparency Directive art. 6, addendum B3): the target % (and per title), the company factor, the rating table, the goals weight, the cap, how proration works and the rounding, as % only, never amounts. It shows in My workspace → Pay → "How pay progresses" (comp_me_bonus_criteria). Or, with shared_otherwise, records that it was shared with staff another way. A plan launches only after one of the two. Owners, admins and HR, in the app only. Part of the Salary reviews 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. The formula is published to staff in the app only.
MCP tool
comp_bonus_plans_publish_formula 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

  • plan_idstringrequired
  • shared_otherwiseboolean
  • unpublishboolean

Returns

20 fields
  • idstringrequired
  • namestringrequired
  • status"draft" | "launching" | "open" | "releasing" | "released" | "cancelled"required
  • periodobjectrequired
    2 fields
    • fromstringrequired
    • tostringrequired
  • payout_onstringrequired
  • populationobjectrequired
    5 fields (one of several shapes)

    Option 1

    • kind"company"required

    Option 2

    • kind"units"required
    • unit_idsstring[]required

      1–200 items.

    Option 3

    • kind"entities"required
    • entity_idsstring[]required

      1–50 items.

  • eligibilityobjectrequired
    2 fields
    • cutoff_datestringrequired
    • employment_typesstring[]required
  • targetobjectrequired
    3 fields
    • default_pctnumberrequired
    • by_titleobject[]required
      2 fields
      • titlestringrequired
      • pctnumberrequired
    • onstringrequired
  • company_factornumber | nullrequired
  • individualobjectrequired
    5 fields
    • rating_cycle_idstring | nullrequired
    • by_ratingobject[]required
      3 fields
      • valuenumberrequired
      • labelstringrequired
      • pctnumberrequired
    • no_rating_pctnumberrequired
    • goals_weightnumberrequired
    • capnumberrequired
  • prorationobjectrequired
    1 field
    • other_unpaid_leave"counted" | "not_counted"required
  • manager_adjust_pctintegerrequired
  • formulaobjectrequired
    2 fields
    • published_atstring | nullrequired
    • shared_otherwise_atstring | nullrequired
  • launchobject | nullrequired
    2 fields
    • doneintegerrequired
    • totalintegerrequired
  • countsobjectrequired
    5 fields
    • draftintegerrequired
    • approvedintegerrequired
    • skippedintegerrequired
    • releasedintegerrequired
    • adjustedintegerrequired
  • totalsobject[]required
    4 fields
    • currencystringrequired
    • formula_centsintegerrequired
    • award_centsintegerrequired
    • target_centsintegerrequired
  • releaseobjectrequired
    5 fields
    • payintegerrequired
    • zerointegerrequired
    • skipintegerrequired
    • doneintegerrequired
    • totalsobject[]required
      2 fields
      • currencystringrequired
      • centsintegerrequired
  • payoutsobjectrequired
    3 fields
    • in_payrollintegerrequired
    • by_handintegerrequired
    • paidintegerrequired
  • created_atstringrequired
  • released_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/bonus.plans.publish_formula \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"plan_id":"bp1","shared_otherwise":true}'
Response
{
  "data": {
    "id": "bp1",
    "name": "2026 bonus",
    "status": "open",
    "period": {
      "from": "2026-01-01",
      "to": "2026-12-31"
    },
    "payout_on": "2027-01-31",
    "population": {
      "kind": "company"
    },
    "eligibility": {
      "cutoff_date": "2026-12-31",
      "employment_types": []
    },
    "target": {
      "default_pct": 10,
      "by_title": [
        {
          "title": "Engineering Lead",
          "pct": 15
        }
      ],
      "on": "2026-12-31"
    },
    "company_factor": 100,
    "individual": {
      "rating_cycle_id": "rc1",
      "by_rating": [
        {
          "value": 1,
          "label": "Well below expectations",
          "pct": 0
        },
        {
          "value": 2,
          "label": "Below expectations",
          "pct": 50
        },
        {
          "value": 3,
          "label": "Meets expectations",
          "pct": 100
        },
        {
          "value": 4,
          "label": "Exceeds expectations",
          "pct": 120
        },
        {
          "value": 5,
          "label": "Outstanding",
          "pct": 150
        }
      ],
      "no_rating_pct": 100,
      "goals_weight": 0,
      "cap": 200
    },
    "proration": {
      "other_unpaid_leave": "counted"
    },
    "manager_adjust_pct": 10,
    "formula": {
      "published_at": "2026-11-16T10:00:00.000Z",
      "shared_otherwise_at": null
    },
    "launch": null,
    "counts": {
      "draft": 3,
      "approved": 1,
      "skipped": 0,
      "released": 0,
      "adjusted": 1
    },
    "totals": [
      {
        "currency": "EUR",
        "formula_cents": 1910000,
        "award_cents": 1946000,
        "target_cents": 1910000
      }
    ],
    "release": {
      "pay": 1,
      "zero": 0,
      "skip": 3,
      "done": 0,
      "totals": [
        {
          "currency": "EUR",
          "cents": 432000
        }
      ]
    },
    "payouts": {
      "in_payroll": 0,
      "by_hand": 0,
      "paid": 0
    },
    "created_at": "2026-11-16T10:00:00.000Z",
    "released_at": null
  }
}

Launch a bonus plan#

POST/v1/comp/bonus.plans.launchWrite

Launches a draft bonus plan: takes each eligible person's inputs (annual base on the target day, title, final rating, committed goals when weighted, days employed and unpaid leave in the period) and computes their award by the formula. Managers who may adjust (manager_adjust_pct > 0) get an email (no amounts). 100 people now, the rest from the plan page or within minutes. Needs the formula published to staff, or recorded as shared another way (addendum B3). Nobody is told their award. A dry run counts who takes part. Owners, admins and HR, in the app only. Part of the Salary reviews 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. A bonus plan is launched in the app only.
MCP tool
comp_bonus_plans_launch 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

  • plan_idstringrequired

Returns

  • planobjectrequired
    20 fields
    • idstringrequired
    • namestringrequired
    • status"draft" | "launching" | "open" | "releasing" | "released" | "cancelled"required
    • periodobjectrequired
      2 fields
      • fromstringrequired
      • tostringrequired
    • payout_onstringrequired
    • populationobjectrequired
      5 fields (one of several shapes)

      Option 1

      • kind"company"required

      Option 2

      • kind"units"required
      • unit_idsstring[]required

        1–200 items.

      Option 3

      • kind"entities"required
      • entity_idsstring[]required

        1–50 items.

    • eligibilityobjectrequired
      2 fields
      • cutoff_datestringrequired
      • employment_typesstring[]required
    • targetobjectrequired
      3 fields
      • default_pctnumberrequired
      • by_titleobject[]required
        2 fields
        • titlestringrequired
        • pctnumberrequired
      • onstringrequired
    • company_factornumber | nullrequired
    • individualobjectrequired
      5 fields
      • rating_cycle_idstring | nullrequired
      • by_ratingobject[]required
        3 fields
        • valuenumberrequired
        • labelstringrequired
        • pctnumberrequired
      • no_rating_pctnumberrequired
      • goals_weightnumberrequired
      • capnumberrequired
    • prorationobjectrequired
      1 field
      • other_unpaid_leave"counted" | "not_counted"required
    • manager_adjust_pctintegerrequired
    • formulaobjectrequired
      2 fields
      • published_atstring | nullrequired
      • shared_otherwise_atstring | nullrequired
    • launchobject | nullrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • countsobjectrequired
      5 fields
      • draftintegerrequired
      • approvedintegerrequired
      • skippedintegerrequired
      • releasedintegerrequired
      • adjustedintegerrequired
    • totalsobject[]required
      4 fields
      • currencystringrequired
      • formula_centsintegerrequired
      • award_centsintegerrequired
      • target_centsintegerrequired
    • releaseobjectrequired
      5 fields
      • payintegerrequired
      • zerointegerrequired
      • skipintegerrequired
      • doneintegerrequired
      • totalsobject[]required
        2 fields
        • currencystringrequired
        • centsintegerrequired
    • payoutsobjectrequired
      3 fields
      • in_payrollintegerrequired
      • by_handintegerrequired
      • paidintegerrequired
    • created_atstringrequired
    • released_atstring | nullrequired
  • previewobjectrequired
    9 fields
    • eligibleintegerrequired
    • excludedobjectrequired
      2 fields
      • not_employedintegerrequired
      • employment_typeintegerrequired
    • no_payintegerrequired
    • protected_leaveintegerrequired
    • part_periodintegerrequired
    • no_ratingintegerrequired
    • totalsobject[]required

      The formula's total per currency (with a company factor of 100 % while it is not set).

      2 fields
      • currencystringrequired
      • centsintegerrequired
    • exampleobject | nullrequired

      The formula worked through for one real person (HR only).

      16 fields
      • person_idstringrequired
      • namestringrequired
      • currencystringrequired
      • base_centsintegerrequired
      • target_pctnumberrequired
      • company_pctnumberrequired
      • ratingnumber | nullrequired
      • rating_labelstring | nullrequired
      • rating_pctnumberrequired
      • goals_pctnumber | nullrequired
      • individual_pctnumberrequired
      • daysintegerrequired
      • unpaid_daysintegerrequired
      • period_daysintegerrequired
      • prorationnumberrequired
      • centsintegerrequired
    • peopleobject[]required

      Who the example can show (up to 200, by name).

      2 fields
      • idstringrequired
      • namestringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/bonus.plans.launch \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"plan_id":"bp1"}'
Response
{
  "data": {
    "plan": {
      "id": "bp1",
      "name": "2026 bonus",
      "status": "launching",
      "period": {
        "from": "2026-01-01",
        "to": "2026-12-31"
      },
      "payout_on": "2027-01-31",
      "population": {
        "kind": "company"
      },
      "eligibility": {
        "cutoff_date": "2026-12-31",
        "employment_types": []
      },
      "target": {
        "default_pct": 10,
        "by_title": [
          {
            "title": "Engineering Lead",
            "pct": 15
          }
        ],
        "on": "2026-12-31"
      },
      "company_factor": 100,
      "individual": {
        "rating_cycle_id": "rc1",
        "by_rating": [
          {
            "value": 1,
            "label": "Well below expectations",
            "pct": 0
          },
          {
            "value": 2,
            "label": "Below expectations",
            "pct": 50
          },
          {
            "value": 3,
            "label": "Meets expectations",
            "pct": 100
          },
          {
            "value": 4,
            "label": "Exceeds expectations",
            "pct": 120
          },
          {
            "value": 5,
            "label": "Outstanding",
            "pct": 150
          }
        ],
        "no_rating_pct": 100,
        "goals_weight": 0,
        "cap": 200
      },
      "proration": {
        "other_unpaid_leave": "counted"
      },
      "manager_adjust_pct": 10,
      "formula": {
        "published_at": "2026-11-16T10:00:00.000Z",
        "shared_otherwise_at": null
      },
      "launch": {
        "done": 100,
        "total": 240
      },
      "counts": {
        "draft": 3,
        "approved": 1,
        "skipped": 0,
        "released": 0,
        "adjusted": 1
      },
      "totals": [
        {
          "currency": "EUR",
          "formula_cents": 1910000,
          "award_cents": 1946000,
          "target_cents": 1910000
        }
      ],
      "release": {
        "pay": 1,
        "zero": 0,
        "skip": 3,
        "done": 0,
        "totals": [
          {
            "currency": "EUR",
            "cents": 432000
          }
        ]
      },
      "payouts": {
        "in_payroll": 0,
        "by_hand": 0,
        "paid": 0
      },
      "created_at": "2026-11-16T10:00:00.000Z",
      "released_at": null
    },
    "preview": {
      "eligible": 5,
      "excluded": {
        "not_employed": 0,
        "employment_type": 0
      },
      "no_pay": 1,
      "protected_leave": 1,
      "part_period": 0,
      "no_rating": 1,
      "totals": [
        {
          "currency": "EUR",
          "cents": 1910000
        }
      ],
      "example": {
        "person_id": "p5",
        "name": "Eva Silva",
        "currency": "EUR",
        "base_cents": 4500000,
        "target_pct": 10,
        "company_pct": 100,
        "rating": 3,
        "rating_label": "Meets expectations",
        "rating_pct": 100,
        "goals_pct": null,
        "individual_pct": 100,
        "days": 365,
        "unpaid_days": 0,
        "period_days": 365,
        "proration": 1,
        "cents": 450000
      },
      "people": [
        {
          "id": "p3",
          "name": "Carl Silva"
        },
        {
          "id": "p5",
          "name": "Eva Silva"
        }
      ]
    }
  }
}

Continue launching or releasing a bonus plan#

POST/v1/comp/bonus.plans.stepWrite

Runs the next part (100 people) of a bonus plan that is launching or releasing. The plan page calls it while open; the sweep does it every few minutes otherwise. Owners, admins and HR, in the app only. Part of the Salary reviews 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. Large launches and releases continue in the app (or by the sweep).
MCP tool
comp_bonus_plans_step 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

  • plan_idstringrequired

Returns

  • planobjectrequired
    20 fields
    • idstringrequired
    • namestringrequired
    • status"draft" | "launching" | "open" | "releasing" | "released" | "cancelled"required
    • periodobjectrequired
      2 fields
      • fromstringrequired
      • tostringrequired
    • payout_onstringrequired
    • populationobjectrequired
      5 fields (one of several shapes)

      Option 1

      • kind"company"required

      Option 2

      • kind"units"required
      • unit_idsstring[]required

        1–200 items.

      Option 3

      • kind"entities"required
      • entity_idsstring[]required

        1–50 items.

    • eligibilityobjectrequired
      2 fields
      • cutoff_datestringrequired
      • employment_typesstring[]required
    • targetobjectrequired
      3 fields
      • default_pctnumberrequired
      • by_titleobject[]required
        2 fields
        • titlestringrequired
        • pctnumberrequired
      • onstringrequired
    • company_factornumber | nullrequired
    • individualobjectrequired
      5 fields
      • rating_cycle_idstring | nullrequired
      • by_ratingobject[]required
        3 fields
        • valuenumberrequired
        • labelstringrequired
        • pctnumberrequired
      • no_rating_pctnumberrequired
      • goals_weightnumberrequired
      • capnumberrequired
    • prorationobjectrequired
      1 field
      • other_unpaid_leave"counted" | "not_counted"required
    • manager_adjust_pctintegerrequired
    • formulaobjectrequired
      2 fields
      • published_atstring | nullrequired
      • shared_otherwise_atstring | nullrequired
    • launchobject | nullrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • countsobjectrequired
      5 fields
      • draftintegerrequired
      • approvedintegerrequired
      • skippedintegerrequired
      • releasedintegerrequired
      • adjustedintegerrequired
    • totalsobject[]required
      4 fields
      • currencystringrequired
      • formula_centsintegerrequired
      • award_centsintegerrequired
      • target_centsintegerrequired
    • releaseobjectrequired
      5 fields
      • payintegerrequired
      • zerointegerrequired
      • skipintegerrequired
      • doneintegerrequired
      • totalsobject[]required
        2 fields
        • currencystringrequired
        • centsintegerrequired
    • payoutsobjectrequired
      3 fields
      • in_payrollintegerrequired
      • by_handintegerrequired
      • paidintegerrequired
    • created_atstringrequired
    • released_atstring | nullrequired
  • handledintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/bonus.plans.step \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"plan_id":"bp1"}'
Response
{
  "data": {
    "plan": {
      "id": "bp1",
      "name": "2026 bonus",
      "status": "open",
      "period": {
        "from": "2026-01-01",
        "to": "2026-12-31"
      },
      "payout_on": "2027-01-31",
      "population": {
        "kind": "company"
      },
      "eligibility": {
        "cutoff_date": "2026-12-31",
        "employment_types": []
      },
      "target": {
        "default_pct": 10,
        "by_title": [
          {
            "title": "Engineering Lead",
            "pct": 15
          }
        ],
        "on": "2026-12-31"
      },
      "company_factor": 100,
      "individual": {
        "rating_cycle_id": "rc1",
        "by_rating": [
          {
            "value": 1,
            "label": "Well below expectations",
            "pct": 0
          },
          {
            "value": 2,
            "label": "Below expectations",
            "pct": 50
          },
          {
            "value": 3,
            "label": "Meets expectations",
            "pct": 100
          },
          {
            "value": 4,
            "label": "Exceeds expectations",
            "pct": 120
          },
          {
            "value": 5,
            "label": "Outstanding",
            "pct": 150
          }
        ],
        "no_rating_pct": 100,
        "goals_weight": 0,
        "cap": 200
      },
      "proration": {
        "other_unpaid_leave": "counted"
      },
      "manager_adjust_pct": 10,
      "formula": {
        "published_at": "2026-11-16T10:00:00.000Z",
        "shared_otherwise_at": null
      },
      "launch": null,
      "counts": {
        "draft": 3,
        "approved": 1,
        "skipped": 0,
        "released": 0,
        "adjusted": 1
      },
      "totals": [
        {
          "currency": "EUR",
          "formula_cents": 1910000,
          "award_cents": 1946000,
          "target_cents": 1910000
        }
      ],
      "release": {
        "pay": 1,
        "zero": 0,
        "skip": 3,
        "done": 0,
        "totals": [
          {
            "currency": "EUR",
            "cents": 432000
          }
        ]
      },
      "payouts": {
        "in_payroll": 0,
        "by_hand": 0,
        "paid": 0
      },
      "created_at": "2026-11-16T10:00:00.000Z",
      "released_at": null
    },
    "handled": 100
  }
}

Cancel a bonus plan#

POST/v1/comp/bonus.plans.cancelDestructive

Cancels a bonus plan before its release: nothing is paid and nobody is told. Its awards are kept (read-only) for HR. Not possible once releasing. Owners, admins and HR, in the app only.

Web app only
Refused for API keys and connected apps. A bonus plan is cancelled in the app only.
MCP tool
comp_bonus_plans_cancel 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

  • plan_idstringrequired

Returns

20 fields
  • idstringrequired
  • namestringrequired
  • status"draft" | "launching" | "open" | "releasing" | "released" | "cancelled"required
  • periodobjectrequired
    2 fields
    • fromstringrequired
    • tostringrequired
  • payout_onstringrequired
  • populationobjectrequired
    5 fields (one of several shapes)

    Option 1

    • kind"company"required

    Option 2

    • kind"units"required
    • unit_idsstring[]required

      1–200 items.

    Option 3

    • kind"entities"required
    • entity_idsstring[]required

      1–50 items.

  • eligibilityobjectrequired
    2 fields
    • cutoff_datestringrequired
    • employment_typesstring[]required
  • targetobjectrequired
    3 fields
    • default_pctnumberrequired
    • by_titleobject[]required
      2 fields
      • titlestringrequired
      • pctnumberrequired
    • onstringrequired
  • company_factornumber | nullrequired
  • individualobjectrequired
    5 fields
    • rating_cycle_idstring | nullrequired
    • by_ratingobject[]required
      3 fields
      • valuenumberrequired
      • labelstringrequired
      • pctnumberrequired
    • no_rating_pctnumberrequired
    • goals_weightnumberrequired
    • capnumberrequired
  • prorationobjectrequired
    1 field
    • other_unpaid_leave"counted" | "not_counted"required
  • manager_adjust_pctintegerrequired
  • formulaobjectrequired
    2 fields
    • published_atstring | nullrequired
    • shared_otherwise_atstring | nullrequired
  • launchobject | nullrequired
    2 fields
    • doneintegerrequired
    • totalintegerrequired
  • countsobjectrequired
    5 fields
    • draftintegerrequired
    • approvedintegerrequired
    • skippedintegerrequired
    • releasedintegerrequired
    • adjustedintegerrequired
  • totalsobject[]required
    4 fields
    • currencystringrequired
    • formula_centsintegerrequired
    • award_centsintegerrequired
    • target_centsintegerrequired
  • releaseobjectrequired
    5 fields
    • payintegerrequired
    • zerointegerrequired
    • skipintegerrequired
    • doneintegerrequired
    • totalsobject[]required
      2 fields
      • currencystringrequired
      • centsintegerrequired
  • payoutsobjectrequired
    3 fields
    • in_payrollintegerrequired
    • by_handintegerrequired
    • paidintegerrequired
  • created_atstringrequired
  • released_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/bonus.plans.cancel \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"plan_id":"bp1"}'
Response
{
  "data": {
    "id": "bp1",
    "name": "2026 bonus",
    "status": "cancelled",
    "period": {
      "from": "2026-01-01",
      "to": "2026-12-31"
    },
    "payout_on": "2027-01-31",
    "population": {
      "kind": "company"
    },
    "eligibility": {
      "cutoff_date": "2026-12-31",
      "employment_types": []
    },
    "target": {
      "default_pct": 10,
      "by_title": [
        {
          "title": "Engineering Lead",
          "pct": 15
        }
      ],
      "on": "2026-12-31"
    },
    "company_factor": 100,
    "individual": {
      "rating_cycle_id": "rc1",
      "by_rating": [
        {
          "value": 1,
          "label": "Well below expectations",
          "pct": 0
        },
        {
          "value": 2,
          "label": "Below expectations",
          "pct": 50
        },
        {
          "value": 3,
          "label": "Meets expectations",
          "pct": 100
        },
        {
          "value": 4,
          "label": "Exceeds expectations",
          "pct": 120
        },
        {
          "value": 5,
          "label": "Outstanding",
          "pct": 150
        }
      ],
      "no_rating_pct": 100,
      "goals_weight": 0,
      "cap": 200
    },
    "proration": {
      "other_unpaid_leave": "counted"
    },
    "manager_adjust_pct": 10,
    "formula": {
      "published_at": "2026-11-16T10:00:00.000Z",
      "shared_otherwise_at": null
    },
    "launch": null,
    "counts": {
      "draft": 3,
      "approved": 1,
      "skipped": 0,
      "released": 0,
      "adjusted": 1
    },
    "totals": [
      {
        "currency": "EUR",
        "formula_cents": 1910000,
        "award_cents": 1946000,
        "target_cents": 1910000
      }
    ],
    "release": {
      "pay": 1,
      "zero": 0,
      "skip": 3,
      "done": 0,
      "totals": [
        {
          "currency": "EUR",
          "cents": 432000
        }
      ]
    },
    "payouts": {
      "in_payroll": 0,
      "by_hand": 0,
      "paid": 0
    },
    "created_at": "2026-11-16T10:00:00.000Z",
    "released_at": null
  }
}

Release a bonus plan now#

POST/v1/comp/bonus.plans.release_nowWrite

Releases an open bonus plan now instead of on its payout day: each approved award is re-checked (still employed with no termination recorded; the approver may still decide it, else the plan goes back to open with that award in draft), paid through Payroll as a "Bonus" item in the pay period covering the payout day (once per award, also when retried) or, without Payroll or when it refuses one, left to HR to pay by hand and mark paid; each person gets a letter in Bizisy (amount and how it was worked out) and an email with no amount. Awards not approved are left out (reasons for HR only). Needs the company factor. 100 now, the rest within minutes. The dry run lists what would be paid, sent at zero and left out, with totals per currency. Owners, admins and HR, in the app only. Part of the Salary reviews 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. A bonus plan is released in the app only: it pays and sends letters.
MCP tool
comp_bonus_plans_release_now 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

  • plan_idstringrequired

Returns

  • planobjectrequired
    20 fields
    • idstringrequired
    • namestringrequired
    • status"draft" | "launching" | "open" | "releasing" | "released" | "cancelled"required
    • periodobjectrequired
      2 fields
      • fromstringrequired
      • tostringrequired
    • payout_onstringrequired
    • populationobjectrequired
      5 fields (one of several shapes)

      Option 1

      • kind"company"required

      Option 2

      • kind"units"required
      • unit_idsstring[]required

        1–200 items.

      Option 3

      • kind"entities"required
      • entity_idsstring[]required

        1–50 items.

    • eligibilityobjectrequired
      2 fields
      • cutoff_datestringrequired
      • employment_typesstring[]required
    • targetobjectrequired
      3 fields
      • default_pctnumberrequired
      • by_titleobject[]required
        2 fields
        • titlestringrequired
        • pctnumberrequired
      • onstringrequired
    • company_factornumber | nullrequired
    • individualobjectrequired
      5 fields
      • rating_cycle_idstring | nullrequired
      • by_ratingobject[]required
        3 fields
        • valuenumberrequired
        • labelstringrequired
        • pctnumberrequired
      • no_rating_pctnumberrequired
      • goals_weightnumberrequired
      • capnumberrequired
    • prorationobjectrequired
      1 field
      • other_unpaid_leave"counted" | "not_counted"required
    • manager_adjust_pctintegerrequired
    • formulaobjectrequired
      2 fields
      • published_atstring | nullrequired
      • shared_otherwise_atstring | nullrequired
    • launchobject | nullrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • countsobjectrequired
      5 fields
      • draftintegerrequired
      • approvedintegerrequired
      • skippedintegerrequired
      • releasedintegerrequired
      • adjustedintegerrequired
    • totalsobject[]required
      4 fields
      • currencystringrequired
      • formula_centsintegerrequired
      • award_centsintegerrequired
      • target_centsintegerrequired
    • releaseobjectrequired
      5 fields
      • payintegerrequired
      • zerointegerrequired
      • skipintegerrequired
      • doneintegerrequired
      • totalsobject[]required
        2 fields
        • currencystringrequired
        • centsintegerrequired
    • payoutsobjectrequired
      3 fields
      • in_payrollintegerrequired
      • by_handintegerrequired
      • paidintegerrequired
    • created_atstringrequired
    • released_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/bonus.plans.release_now \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"plan_id":"bp1"}'
Response
{
  "data": {
    "plan": {
      "id": "bp1",
      "name": "2026 bonus",
      "status": "released",
      "period": {
        "from": "2026-01-01",
        "to": "2026-12-31"
      },
      "payout_on": "2027-01-31",
      "population": {
        "kind": "company"
      },
      "eligibility": {
        "cutoff_date": "2026-12-31",
        "employment_types": []
      },
      "target": {
        "default_pct": 10,
        "by_title": [
          {
            "title": "Engineering Lead",
            "pct": 15
          }
        ],
        "on": "2026-12-31"
      },
      "company_factor": 100,
      "individual": {
        "rating_cycle_id": "rc1",
        "by_rating": [
          {
            "value": 1,
            "label": "Well below expectations",
            "pct": 0
          },
          {
            "value": 2,
            "label": "Below expectations",
            "pct": 50
          },
          {
            "value": 3,
            "label": "Meets expectations",
            "pct": 100
          },
          {
            "value": 4,
            "label": "Exceeds expectations",
            "pct": 120
          },
          {
            "value": 5,
            "label": "Outstanding",
            "pct": 150
          }
        ],
        "no_rating_pct": 100,
        "goals_weight": 0,
        "cap": 200
      },
      "proration": {
        "other_unpaid_leave": "counted"
      },
      "manager_adjust_pct": 10,
      "formula": {
        "published_at": "2026-11-16T10:00:00.000Z",
        "shared_otherwise_at": null
      },
      "launch": null,
      "counts": {
        "draft": 3,
        "approved": 1,
        "skipped": 0,
        "released": 0,
        "adjusted": 1
      },
      "totals": [
        {
          "currency": "EUR",
          "formula_cents": 1910000,
          "award_cents": 1946000,
          "target_cents": 1910000
        }
      ],
      "release": {
        "pay": 1,
        "zero": 0,
        "skip": 3,
        "done": 0,
        "totals": [
          {
            "currency": "EUR",
            "cents": 432000
          }
        ]
      },
      "payouts": {
        "in_payroll": 4,
        "by_hand": 0,
        "paid": 0
      },
      "created_at": "2026-11-16T10:00:00.000Z",
      "released_at": "2027-01-31T08:00:00.000Z"
    }
  }
}

Bonus awards#

POST/v1/comp/bonus.awards.listRead

A bonus plan's awards. Owners, admins and HR (Manage): every award with the formula's inputs (annual base, target %, rating factor, committed goals, proration, days), the formula amount, the award, how far it is from the formula, flags (no pay, protected leave, part of the period, no rating, adjusted) and whether you may approve it (never your own). In Me, a manager: their reports' awards as % of the formula (never amounts or pay), editable while the plan is open. In the app only. Part of the Salary reviews 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.

Web app only
Refused for API keys and connected apps. Awards hold pay: read in the app only.
MCP tool
comp_bonus_awards_list on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • plan_idstringrequired

Returns

  • planobjectrequired
    6 fields
    • idstringrequired
    • namestringrequired
    • status"draft" | "launching" | "open" | "releasing" | "released" | "cancelled"required
    • periodobjectrequired
      2 fields
      • fromstringrequired
      • tostringrequired
    • payout_onstringrequired
    • manager_adjust_pctintegerrequired
  • itemsobject[]required
    29 fields
    • idstringrequired
    • personobjectrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
    • state"draft" | "approved" | "skipped" | "released"required
    • managerobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • currencystring | nullrequired
    • base_centsinteger | nullrequired
    • target_pctnumberrequired
    • target_overridebooleanrequired
    • ratingnumber | nullrequired
    • rating_pctnumberrequired
    • goals_pctnumber | nullrequired
    • individual_pctnumberrequired
    • prorationnumberrequired
    • daysintegerrequired
    • period_daysintegerrequired
    • unpaid_daysintegerrequired
    • formula_centsinteger | nullrequired
    • award_centsinteger | nullrequired
    • adjust_pctnumber | nullrequired

      The award vs the formula, % (+10 = 10 % above).

    • target_centsinteger | nullrequired
    • payout_rationumber | nullrequired

      Award ÷ target, % (B4).

    • reason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"required
    • reason_textstring | nullrequired
    • commentstring | nullrequired
    • flags"no_pay" | "protected_leave" | "part_period" | "no_rating" | "adjusted" | "outside_range"[]required
    • can_decidebooleanrequired
    • why_notstring | nullrequired
    • skipped_reasonstring | nullrequired
    • payoutobject | nullrequired
      3 fields
      • via"payroll" | "by_hand"required
      • paidbooleanrequired
      • whystring | nullrequired
  • mineobject[]required
    10 fields
    • idstringrequired
    • personobjectrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
    • state"draft" | "approved" | "skipped" | "released"required
    • rating_labelstring | nullrequired
    • adjust_pctnumberrequired

      The award vs the formula, % (0: the formula).

    • reason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"required
    • reason_textstring | nullrequired
    • commentstring | nullrequired
    • editablebooleanrequired
    • part_periodbooleanrequired
  • adjust_pctintegerrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/bonus.awards.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan_id":"bp1"}'
Response
{
  "data": {
    "plan": {
      "id": "bp1",
      "name": "2026 bonus",
      "status": "open",
      "period": {
        "from": "2026-01-01",
        "to": "2026-12-31"
      },
      "payout_on": "2027-01-31",
      "manager_adjust_pct": 10
    },
    "items": [
      {
        "id": "bp1:p3",
        "person": {
          "id": "p3",
          "name": "Carl Silva",
          "title": "Engineer"
        },
        "state": "draft",
        "manager": {
          "id": "p2",
          "name": "Bea Silva"
        },
        "currency": "EUR",
        "base_cents": 3600000,
        "target_pct": 10,
        "target_override": false,
        "rating": 4,
        "rating_pct": 120,
        "goals_pct": null,
        "individual_pct": 120,
        "proration": 1,
        "days": 365,
        "period_days": 365,
        "unpaid_days": 0,
        "formula_cents": 432000,
        "award_cents": 475200,
        "adjust_pct": 10,
        "target_cents": 360000,
        "payout_ratio": 132,
        "reason": "retention",
        "reason_text": null,
        "comment": null,
        "flags": [
          "adjusted"
        ],
        "can_decide": true,
        "why_not": null,
        "skipped_reason": null,
        "payout": null
      }
    ],
    "mine": [],
    "adjust_pct": 10
  }
}

Adjust a bonus award#

POST/v1/comp/bonus.awards.adjustWrite

Changes one award of an open plan. A manager (in Me, their reports only, never their own): adjust_pct, the award vs the formula in % within ± the plan's manager_adjust_pct (0: back to the formula), with a reason from the fixed list when not 0 (other: at least 20 characters) and an optional comment for HR. HR (in Manage): cents (any amount from 0; null: back to the formula) with a reason when it differs, and/or target_pct (this person's target %, null: the plan's). Never your own award; HR within the pay approval rules. An approved award goes back to draft. Pay stays in the app. Part of the Salary reviews 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. Awards are adjusted in the app only.
MCP tool
comp_bonus_awards_adjust on HR Assistant, My Workplace
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

  • award_idstringrequired
  • adjust_pctnumber

    From -100 to 100.

  • centsinteger | null

    From 0 to 1000000000.

  • target_pctnumber | null

    From 0 to 200.

  • reason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"
  • reason_textstring | null

    Up to 500 characters.

  • commentstring | null

    Up to 1000 characters.

Returns

  • idstringrequired
  • state"draft" | "approved" | "skipped" | "released"required
  • adjust_pctnumber | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/bonus.awards.adjust \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "award_id": "bp1:p3",
  "cents": 450000,
  "reason": "other",
  "reason_text": "Led the migration alone"
}'
Response
{
  "data": {
    "id": "bp1:p3",
    "state": "draft",
    "adjust_pct": 10
  }
}

Approve bonus awards#

POST/v1/comp/bonus.awards.decideWrite

Approves awards (approve) or takes approval back (reopen). Each award is checked on its own against the pay approval rules: owners, admins and HR; an HR member's only owners and admins; an owner's only another owner; never your own, never one you changed. Needs the company factor set. Awards you can't decide are refused with the reason. Approved awards are held until the release: nothing is paid before. Check the equal-pay view first (comp_bonus_equity). Owners, admins and HR, in the app only. Part of the Salary reviews 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. Awards are approved in the app only.
MCP tool
comp_bonus_awards_decide 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

  • plan_idstringrequired
  • award_idsstring[]required

    1–500 items.

  • decision"approve" | "reopen"

    Default "approve".

  • notestring

    Up to 500 characters.

Returns

  • donestring[]required
  • refusedobject[]required
    2 fields
    • idstringrequired
    • reasonstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/bonus.awards.decide \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"plan_id":"bp1","award_ids":["bp1:p3"],"decision":"reopen"}'
Response
{
  "data": {
    "done": [
      "bp1:p3"
    ],
    "refused": [
      {
        "id": "bp1:p1",
        "reason": "You can't decide your own pay."
      }
    ]
  }
}

Equal-pay check of a bonus plan#

POST/v1/comp/bonus.equityRead

Before approving (addendum B4, Directive 2023/970 arts. 9–10): per category of workers (Pay equity), the average award and the average payout ratio (award ÷ target) of women and of men, and the gap on each (% of the men's; negative: women get more), for categories with at least the company's smallest group of women and of men; a gap of 5 % or more is flagged, with the reminder that an unjustified gap of 5 % may lead to a joint pay assessment with workers' representatives. Owners, admins and HR, in the app only; never shown to managers. Part of the Salary reviews 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.

Web app only
Refused for API keys and connected apps. The equal-pay check is read in the app only.
MCP tool
comp_bonus_equity on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • plan_idstringrequired

Returns

  • min_groupintegerrequired
  • hiddenintegerrequired
  • flaggedintegerrequired
  • categoriesobject[]required
    8 fields
    • idstringrequired
    • namestringrequired
    • currencystringrequired
    • womenintegerrequired
    • menintegerrequired
    • awardobjectrequired
      3 fields
      • womennumberrequired
      • mennumberrequired
      • gapnumber | nullrequired
    • ratioobjectrequired
      3 fields
      • womennumberrequired
      • mennumberrequired
      • gapnumber | nullrequired
    • flaggedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/bonus.equity \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan_id":"bp1"}'
Response
{
  "data": {
    "min_group": 2,
    "hidden": 1,
    "flagged": 1,
    "categories": [
      {
        "id": "cat1",
        "name": "Engineering",
        "currency": "EUR",
        "women": 3,
        "men": 4,
        "award": {
          "women": 410000,
          "men": 450000,
          "gap": 8.9
        },
        "ratio": {
          "women": 98,
          "men": 104,
          "gap": 5.8
        },
        "flagged": true
      }
    ]
  }
}

Mark bonus awards paid#

POST/v1/comp/bonus.awards.mark_paidWrite

After the release: marks awards HR pays by hand (Payroll off, or Payroll refused them) as paid. Each follows the pay approval rules (never your own). Owners, admins and HR, in the app only. Part of the Salary reviews 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. Awards are marked paid in the app only.
MCP tool
comp_bonus_awards_mark_paid 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

  • plan_idstringrequired
  • award_idsstring[]required

    1–500 items.

Returns

  • donestring[]required
  • refusedobject[]required
    2 fields
    • idstringrequired
    • reasonstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/bonus.awards.mark_paid \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"plan_id":"bp1","award_ids":["bp1:p3"]}'
Response
{
  "data": {
    "done": [
      "bp1:p3"
    ],
    "refused": []
  }
}

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

Developer docs