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_liston HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
itemsobject[]required6 fields
idstringrequirednamestringrequiredstatus"draft" | "launching" | "open" | "releasing" | "released" | "cancelled"requiredperiodobjectrequired2 fields
fromstringrequiredtostringrequired
payout_onstringrequiredmanager_adjust_pctintegerrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/comp/bonus.plans.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/comp/bonus.plans.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/comp/bonus.plans.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"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_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
plan_idstringrequired
Returns
20 fields
idstringrequirednamestringrequiredstatus"draft" | "launching" | "open" | "releasing" | "released" | "cancelled"requiredperiodobjectrequired2 fields
fromstringrequiredtostringrequired
payout_onstringrequiredpopulationobjectrequired5 fields (one of several shapes)
Option 1
kind"company"required
Option 2
kind"units"requiredunit_idsstring[]required1–200 items.
Option 3
kind"entities"requiredentity_idsstring[]required1–50 items.
eligibilityobjectrequired2 fields
cutoff_datestringrequiredemployment_typesstring[]required
targetobjectrequired3 fields
default_pctnumberrequiredby_titleobject[]required2 fields
titlestringrequiredpctnumberrequired
onstringrequired
company_factornumber | nullrequiredindividualobjectrequired5 fields
rating_cycle_idstring | nullrequiredby_ratingobject[]required3 fields
valuenumberrequiredlabelstringrequiredpctnumberrequired
no_rating_pctnumberrequiredgoals_weightnumberrequiredcapnumberrequired
prorationobjectrequired1 field
other_unpaid_leave"counted" | "not_counted"required
manager_adjust_pctintegerrequiredformulaobjectrequired2 fields
published_atstring | nullrequiredshared_otherwise_atstring | nullrequired
launchobject | nullrequired2 fields
doneintegerrequiredtotalintegerrequired
countsobjectrequired5 fields
draftintegerrequiredapprovedintegerrequiredskippedintegerrequiredreleasedintegerrequiredadjustedintegerrequired
totalsobject[]required4 fields
currencystringrequiredformula_centsintegerrequiredaward_centsintegerrequiredtarget_centsintegerrequired
releaseobjectrequired5 fields
payintegerrequiredzerointegerrequiredskipintegerrequireddoneintegerrequiredtotalsobject[]required2 fields
currencystringrequiredcentsintegerrequired
payoutsobjectrequired3 fields
in_payrollintegerrequiredby_handintegerrequiredpaidintegerrequired
created_atstringrequiredreleased_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/comp/bonus.plans.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"plan_id": "bp1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/comp/bonus.plans.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"plan_id": "bp1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_createon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
namestringrequired1–120 characters.
periodobjectrequiredThe performance period (inclusive).
2 fields
fromstringrequiredPattern
^\d{4}-\d{2}-\d{2}$.tostringrequiredPattern
^\d{4}-\d{2}-\d{2}$.
payout_onstringrequiredPayout day: the release runs that day from 08:00 company time; the payroll item is due then.
Pattern
^\d{4}-\d{2}-\d{2}$.populationobjectDefault
{"kind":"company"}.5 fields (one of several shapes)
Option 1
kind"company"required
Option 2
kind"units"requiredunit_idsstring[]required1–200 items.
Option 3
kind"entities"requiredentity_idsstring[]required1–50 items.
eligibilityobjectDefault
{}.2 fields
cutoff_datestringEmployed 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.
targetobjectDefault
{"default_pct":10}.3 fields
default_pctnumberrequiredTarget 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
titlestringrequired1–120 characters.
pctnumberrequiredFrom 0 to 200.
onstringThe day whose base pay counts (default the period's last day).
Pattern
^\d{4}-\d{2}-\d{2}$.
company_factornumber | null0–200 % (default 100); null: set it later (approving and paying wait for it).
From 0 to 200.
individualobjectDefault
{}.5 fields
rating_cycle_idstring | nullThe 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
valueintegerrequiredFrom -10 to 20.
labelstringrequired1–60 characters.
pctnumberrequiredFrom 0 to 200.
no_rating_pctnumberFactor % for people without a calibrated rating (default 100: never 0 for a missing rating).
From 0 to 200.
goals_weightnumberShare 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.
capnumberThe individual factor's maximum % (default 200).
From 0 to 200.
prorationobjectDefault
{"other_unpaid_leave":"counted"}.1 field
other_unpaid_leave"counted" | "not_counted"requiredOther 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_pctintegerManagers may move their reports' awards within ± this % of the formula (default 0: formula only).
From 0 to 50.
example_person_idstringShow the worked example for this person (default: the person with the middle base pay).
1–200 characters.
Returns
planobjectrequired20 fields
idstringrequirednamestringrequiredstatus"draft" | "launching" | "open" | "releasing" | "released" | "cancelled"requiredperiodobjectrequired2 fields
fromstringrequiredtostringrequired
payout_onstringrequiredpopulationobjectrequired5 fields (one of several shapes)
Option 1
kind"company"required
Option 2
kind"units"requiredunit_idsstring[]required1–200 items.
Option 3
kind"entities"requiredentity_idsstring[]required1–50 items.
eligibilityobjectrequired2 fields
cutoff_datestringrequiredemployment_typesstring[]required
targetobjectrequired3 fields
default_pctnumberrequiredby_titleobject[]required2 fields
titlestringrequiredpctnumberrequired
onstringrequired
company_factornumber | nullrequiredindividualobjectrequired5 fields
rating_cycle_idstring | nullrequiredby_ratingobject[]required3 fields
valuenumberrequiredlabelstringrequiredpctnumberrequired
no_rating_pctnumberrequiredgoals_weightnumberrequiredcapnumberrequired
prorationobjectrequired1 field
other_unpaid_leave"counted" | "not_counted"required
manager_adjust_pctintegerrequiredformulaobjectrequired2 fields
published_atstring | nullrequiredshared_otherwise_atstring | nullrequired
launchobject | nullrequired2 fields
doneintegerrequiredtotalintegerrequired
countsobjectrequired5 fields
draftintegerrequiredapprovedintegerrequiredskippedintegerrequiredreleasedintegerrequiredadjustedintegerrequired
totalsobject[]required4 fields
currencystringrequiredformula_centsintegerrequiredaward_centsintegerrequiredtarget_centsintegerrequired
releaseobjectrequired5 fields
payintegerrequiredzerointegerrequiredskipintegerrequireddoneintegerrequiredtotalsobject[]required2 fields
currencystringrequiredcentsintegerrequired
payoutsobjectrequired3 fields
in_payrollintegerrequiredby_handintegerrequiredpaidintegerrequired
created_atstringrequiredreleased_atstring | nullrequired
previewobjectrequired9 fields
eligibleintegerrequiredexcludedobjectrequired2 fields
not_employedintegerrequiredemployment_typeintegerrequired
no_payintegerrequiredprotected_leaveintegerrequiredpart_periodintegerrequiredno_ratingintegerrequiredtotalsobject[]requiredThe formula's total per currency (with a company factor of 100 % while it is not set).
2 fields
currencystringrequiredcentsintegerrequired
exampleobject | nullrequiredThe formula worked through for one real person (HR only).
16 fields
person_idstringrequirednamestringrequiredcurrencystringrequiredbase_centsintegerrequiredtarget_pctnumberrequiredcompany_pctnumberrequiredratingnumber | nullrequiredrating_labelstring | nullrequiredrating_pctnumberrequiredgoals_pctnumber | nullrequiredindividual_pctnumberrequireddaysintegerrequiredunpaid_daysintegerrequiredperiod_daysintegerrequiredprorationnumberrequiredcentsintegerrequired
peopleobject[]requiredWho the example can show (up to 200, by name).
2 fields
idstringrequirednamestringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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"
}'const res = await fetch('https://api.bizisy.com/v1/comp/bonus.plans.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"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"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/comp/bonus.plans.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"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": None,
"individual": {
"rating_cycle_id": "rc1",
"goals_weight": 20,
"cap": 150,
},
"proration": {
"other_unpaid_leave": "not_counted",
},
"manager_adjust_pct": 10,
"example_person_id": "p3",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
namestring1–120 characters.
periodobjectThe performance period (inclusive).
2 fields
fromstringrequiredPattern
^\d{4}-\d{2}-\d{2}$.tostringrequiredPattern
^\d{4}-\d{2}-\d{2}$.
payout_onstringPayout day: the release runs that day from 08:00 company time; the payroll item is due then.
Pattern
^\d{4}-\d{2}-\d{2}$.populationobjectDefault
{"kind":"company"}.5 fields (one of several shapes)
Option 1
kind"company"required
Option 2
kind"units"requiredunit_idsstring[]required1–200 items.
Option 3
kind"entities"requiredentity_idsstring[]required1–50 items.
eligibilityobjectDefault
{}.2 fields
cutoff_datestringEmployed 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.
targetobjectDefault
{"default_pct":10}.3 fields
default_pctnumberrequiredTarget 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
titlestringrequired1–120 characters.
pctnumberrequiredFrom 0 to 200.
onstringThe day whose base pay counts (default the period's last day).
Pattern
^\d{4}-\d{2}-\d{2}$.
company_factornumber | null0–200 % (default 100); null: set it later (approving and paying wait for it).
From 0 to 200.
individualobjectDefault
{}.5 fields
rating_cycle_idstring | nullThe 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
valueintegerrequiredFrom -10 to 20.
labelstringrequired1–60 characters.
pctnumberrequiredFrom 0 to 200.
no_rating_pctnumberFactor % for people without a calibrated rating (default 100: never 0 for a missing rating).
From 0 to 200.
goals_weightnumberShare 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.
capnumberThe individual factor's maximum % (default 200).
From 0 to 200.
prorationobjectDefault
{"other_unpaid_leave":"counted"}.1 field
other_unpaid_leave"counted" | "not_counted"requiredOther 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_pctintegerManagers may move their reports' awards within ± this % of the formula (default 0: formula only).
From 0 to 50.
example_person_idstringShow the worked example for this person (default: the person with the middle base pay).
1–200 characters.
plan_idstringrequired
Returns
planobjectrequired20 fields
idstringrequirednamestringrequiredstatus"draft" | "launching" | "open" | "releasing" | "released" | "cancelled"requiredperiodobjectrequired2 fields
fromstringrequiredtostringrequired
payout_onstringrequiredpopulationobjectrequired5 fields (one of several shapes)
Option 1
kind"company"required
Option 2
kind"units"requiredunit_idsstring[]required1–200 items.
Option 3
kind"entities"requiredentity_idsstring[]required1–50 items.
eligibilityobjectrequired2 fields
cutoff_datestringrequiredemployment_typesstring[]required
targetobjectrequired3 fields
default_pctnumberrequiredby_titleobject[]required2 fields
titlestringrequiredpctnumberrequired
onstringrequired
company_factornumber | nullrequiredindividualobjectrequired5 fields
rating_cycle_idstring | nullrequiredby_ratingobject[]required3 fields
valuenumberrequiredlabelstringrequiredpctnumberrequired
no_rating_pctnumberrequiredgoals_weightnumberrequiredcapnumberrequired
prorationobjectrequired1 field
other_unpaid_leave"counted" | "not_counted"required
manager_adjust_pctintegerrequiredformulaobjectrequired2 fields
published_atstring | nullrequiredshared_otherwise_atstring | nullrequired
launchobject | nullrequired2 fields
doneintegerrequiredtotalintegerrequired
countsobjectrequired5 fields
draftintegerrequiredapprovedintegerrequiredskippedintegerrequiredreleasedintegerrequiredadjustedintegerrequired
totalsobject[]required4 fields
currencystringrequiredformula_centsintegerrequiredaward_centsintegerrequiredtarget_centsintegerrequired
releaseobjectrequired5 fields
payintegerrequiredzerointegerrequiredskipintegerrequireddoneintegerrequiredtotalsobject[]required2 fields
currencystringrequiredcentsintegerrequired
payoutsobjectrequired3 fields
in_payrollintegerrequiredby_handintegerrequiredpaidintegerrequired
created_atstringrequiredreleased_atstring | nullrequired
previewobject | nullrequired9 fields
eligibleintegerrequiredexcludedobjectrequired2 fields
not_employedintegerrequiredemployment_typeintegerrequired
no_payintegerrequiredprotected_leaveintegerrequiredpart_periodintegerrequiredno_ratingintegerrequiredtotalsobject[]requiredThe formula's total per currency (with a company factor of 100 % while it is not set).
2 fields
currencystringrequiredcentsintegerrequired
exampleobject | nullrequiredThe formula worked through for one real person (HR only).
16 fields
person_idstringrequirednamestringrequiredcurrencystringrequiredbase_centsintegerrequiredtarget_pctnumberrequiredcompany_pctnumberrequiredratingnumber | nullrequiredrating_labelstring | nullrequiredrating_pctnumberrequiredgoals_pctnumber | nullrequiredindividual_pctnumberrequireddaysintegerrequiredunpaid_daysintegerrequiredperiod_daysintegerrequiredprorationnumberrequiredcentsintegerrequired
peopleobject[]requiredWho the example can show (up to 200, by name).
2 fields
idstringrequirednamestringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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}'const res = await fetch('https://api.bizisy.com/v1/comp/bonus.plans.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"plan_id": "bp1",
"target": {
"default_pct": 12
},
"manager_adjust_pct": 5
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/comp/bonus.plans.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"plan_id": "bp1",
"target": {
"default_pct": 12,
},
"manager_adjust_pct": 5,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_formulaon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
plan_idstringrequiredshared_otherwisebooleanunpublishboolean
Returns
20 fields
idstringrequirednamestringrequiredstatus"draft" | "launching" | "open" | "releasing" | "released" | "cancelled"requiredperiodobjectrequired2 fields
fromstringrequiredtostringrequired
payout_onstringrequiredpopulationobjectrequired5 fields (one of several shapes)
Option 1
kind"company"required
Option 2
kind"units"requiredunit_idsstring[]required1–200 items.
Option 3
kind"entities"requiredentity_idsstring[]required1–50 items.
eligibilityobjectrequired2 fields
cutoff_datestringrequiredemployment_typesstring[]required
targetobjectrequired3 fields
default_pctnumberrequiredby_titleobject[]required2 fields
titlestringrequiredpctnumberrequired
onstringrequired
company_factornumber | nullrequiredindividualobjectrequired5 fields
rating_cycle_idstring | nullrequiredby_ratingobject[]required3 fields
valuenumberrequiredlabelstringrequiredpctnumberrequired
no_rating_pctnumberrequiredgoals_weightnumberrequiredcapnumberrequired
prorationobjectrequired1 field
other_unpaid_leave"counted" | "not_counted"required
manager_adjust_pctintegerrequiredformulaobjectrequired2 fields
published_atstring | nullrequiredshared_otherwise_atstring | nullrequired
launchobject | nullrequired2 fields
doneintegerrequiredtotalintegerrequired
countsobjectrequired5 fields
draftintegerrequiredapprovedintegerrequiredskippedintegerrequiredreleasedintegerrequiredadjustedintegerrequired
totalsobject[]required4 fields
currencystringrequiredformula_centsintegerrequiredaward_centsintegerrequiredtarget_centsintegerrequired
releaseobjectrequired5 fields
payintegerrequiredzerointegerrequiredskipintegerrequireddoneintegerrequiredtotalsobject[]required2 fields
currencystringrequiredcentsintegerrequired
payoutsobjectrequired3 fields
in_payrollintegerrequiredby_handintegerrequiredpaidintegerrequired
created_atstringrequiredreleased_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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}'const res = await fetch('https://api.bizisy.com/v1/comp/bonus.plans.publish_formula', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"plan_id": "bp1",
"shared_otherwise": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/comp/bonus.plans.publish_formula",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"plan_id": "bp1",
"shared_otherwise": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_launchon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
plan_idstringrequired
Returns
planobjectrequired20 fields
idstringrequirednamestringrequiredstatus"draft" | "launching" | "open" | "releasing" | "released" | "cancelled"requiredperiodobjectrequired2 fields
fromstringrequiredtostringrequired
payout_onstringrequiredpopulationobjectrequired5 fields (one of several shapes)
Option 1
kind"company"required
Option 2
kind"units"requiredunit_idsstring[]required1–200 items.
Option 3
kind"entities"requiredentity_idsstring[]required1–50 items.
eligibilityobjectrequired2 fields
cutoff_datestringrequiredemployment_typesstring[]required
targetobjectrequired3 fields
default_pctnumberrequiredby_titleobject[]required2 fields
titlestringrequiredpctnumberrequired
onstringrequired
company_factornumber | nullrequiredindividualobjectrequired5 fields
rating_cycle_idstring | nullrequiredby_ratingobject[]required3 fields
valuenumberrequiredlabelstringrequiredpctnumberrequired
no_rating_pctnumberrequiredgoals_weightnumberrequiredcapnumberrequired
prorationobjectrequired1 field
other_unpaid_leave"counted" | "not_counted"required
manager_adjust_pctintegerrequiredformulaobjectrequired2 fields
published_atstring | nullrequiredshared_otherwise_atstring | nullrequired
launchobject | nullrequired2 fields
doneintegerrequiredtotalintegerrequired
countsobjectrequired5 fields
draftintegerrequiredapprovedintegerrequiredskippedintegerrequiredreleasedintegerrequiredadjustedintegerrequired
totalsobject[]required4 fields
currencystringrequiredformula_centsintegerrequiredaward_centsintegerrequiredtarget_centsintegerrequired
releaseobjectrequired5 fields
payintegerrequiredzerointegerrequiredskipintegerrequireddoneintegerrequiredtotalsobject[]required2 fields
currencystringrequiredcentsintegerrequired
payoutsobjectrequired3 fields
in_payrollintegerrequiredby_handintegerrequiredpaidintegerrequired
created_atstringrequiredreleased_atstring | nullrequired
previewobjectrequired9 fields
eligibleintegerrequiredexcludedobjectrequired2 fields
not_employedintegerrequiredemployment_typeintegerrequired
no_payintegerrequiredprotected_leaveintegerrequiredpart_periodintegerrequiredno_ratingintegerrequiredtotalsobject[]requiredThe formula's total per currency (with a company factor of 100 % while it is not set).
2 fields
currencystringrequiredcentsintegerrequired
exampleobject | nullrequiredThe formula worked through for one real person (HR only).
16 fields
person_idstringrequirednamestringrequiredcurrencystringrequiredbase_centsintegerrequiredtarget_pctnumberrequiredcompany_pctnumberrequiredratingnumber | nullrequiredrating_labelstring | nullrequiredrating_pctnumberrequiredgoals_pctnumber | nullrequiredindividual_pctnumberrequireddaysintegerrequiredunpaid_daysintegerrequiredperiod_daysintegerrequiredprorationnumberrequiredcentsintegerrequired
peopleobject[]requiredWho the example can show (up to 200, by name).
2 fields
idstringrequirednamestringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/comp/bonus.plans.launch', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"plan_id": "bp1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/comp/bonus.plans.launch",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"plan_id": "bp1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_stepon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
plan_idstringrequired
Returns
planobjectrequired20 fields
idstringrequirednamestringrequiredstatus"draft" | "launching" | "open" | "releasing" | "released" | "cancelled"requiredperiodobjectrequired2 fields
fromstringrequiredtostringrequired
payout_onstringrequiredpopulationobjectrequired5 fields (one of several shapes)
Option 1
kind"company"required
Option 2
kind"units"requiredunit_idsstring[]required1–200 items.
Option 3
kind"entities"requiredentity_idsstring[]required1–50 items.
eligibilityobjectrequired2 fields
cutoff_datestringrequiredemployment_typesstring[]required
targetobjectrequired3 fields
default_pctnumberrequiredby_titleobject[]required2 fields
titlestringrequiredpctnumberrequired
onstringrequired
company_factornumber | nullrequiredindividualobjectrequired5 fields
rating_cycle_idstring | nullrequiredby_ratingobject[]required3 fields
valuenumberrequiredlabelstringrequiredpctnumberrequired
no_rating_pctnumberrequiredgoals_weightnumberrequiredcapnumberrequired
prorationobjectrequired1 field
other_unpaid_leave"counted" | "not_counted"required
manager_adjust_pctintegerrequiredformulaobjectrequired2 fields
published_atstring | nullrequiredshared_otherwise_atstring | nullrequired
launchobject | nullrequired2 fields
doneintegerrequiredtotalintegerrequired
countsobjectrequired5 fields
draftintegerrequiredapprovedintegerrequiredskippedintegerrequiredreleasedintegerrequiredadjustedintegerrequired
totalsobject[]required4 fields
currencystringrequiredformula_centsintegerrequiredaward_centsintegerrequiredtarget_centsintegerrequired
releaseobjectrequired5 fields
payintegerrequiredzerointegerrequiredskipintegerrequireddoneintegerrequiredtotalsobject[]required2 fields
currencystringrequiredcentsintegerrequired
payoutsobjectrequired3 fields
in_payrollintegerrequiredby_handintegerrequiredpaidintegerrequired
created_atstringrequiredreleased_atstring | nullrequired
handledintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/comp/bonus.plans.step', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"plan_id": "bp1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/comp/bonus.plans.step",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"plan_id": "bp1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_cancelon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
plan_idstringrequired
Returns
20 fields
idstringrequirednamestringrequiredstatus"draft" | "launching" | "open" | "releasing" | "released" | "cancelled"requiredperiodobjectrequired2 fields
fromstringrequiredtostringrequired
payout_onstringrequiredpopulationobjectrequired5 fields (one of several shapes)
Option 1
kind"company"required
Option 2
kind"units"requiredunit_idsstring[]required1–200 items.
Option 3
kind"entities"requiredentity_idsstring[]required1–50 items.
eligibilityobjectrequired2 fields
cutoff_datestringrequiredemployment_typesstring[]required
targetobjectrequired3 fields
default_pctnumberrequiredby_titleobject[]required2 fields
titlestringrequiredpctnumberrequired
onstringrequired
company_factornumber | nullrequiredindividualobjectrequired5 fields
rating_cycle_idstring | nullrequiredby_ratingobject[]required3 fields
valuenumberrequiredlabelstringrequiredpctnumberrequired
no_rating_pctnumberrequiredgoals_weightnumberrequiredcapnumberrequired
prorationobjectrequired1 field
other_unpaid_leave"counted" | "not_counted"required
manager_adjust_pctintegerrequiredformulaobjectrequired2 fields
published_atstring | nullrequiredshared_otherwise_atstring | nullrequired
launchobject | nullrequired2 fields
doneintegerrequiredtotalintegerrequired
countsobjectrequired5 fields
draftintegerrequiredapprovedintegerrequiredskippedintegerrequiredreleasedintegerrequiredadjustedintegerrequired
totalsobject[]required4 fields
currencystringrequiredformula_centsintegerrequiredaward_centsintegerrequiredtarget_centsintegerrequired
releaseobjectrequired5 fields
payintegerrequiredzerointegerrequiredskipintegerrequireddoneintegerrequiredtotalsobject[]required2 fields
currencystringrequiredcentsintegerrequired
payoutsobjectrequired3 fields
in_payrollintegerrequiredby_handintegerrequiredpaidintegerrequired
created_atstringrequiredreleased_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/comp/bonus.plans.cancel', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"plan_id": "bp1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/comp/bonus.plans.cancel",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"plan_id": "bp1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_nowon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
plan_idstringrequired
Returns
planobjectrequired20 fields
idstringrequirednamestringrequiredstatus"draft" | "launching" | "open" | "releasing" | "released" | "cancelled"requiredperiodobjectrequired2 fields
fromstringrequiredtostringrequired
payout_onstringrequiredpopulationobjectrequired5 fields (one of several shapes)
Option 1
kind"company"required
Option 2
kind"units"requiredunit_idsstring[]required1–200 items.
Option 3
kind"entities"requiredentity_idsstring[]required1–50 items.
eligibilityobjectrequired2 fields
cutoff_datestringrequiredemployment_typesstring[]required
targetobjectrequired3 fields
default_pctnumberrequiredby_titleobject[]required2 fields
titlestringrequiredpctnumberrequired
onstringrequired
company_factornumber | nullrequiredindividualobjectrequired5 fields
rating_cycle_idstring | nullrequiredby_ratingobject[]required3 fields
valuenumberrequiredlabelstringrequiredpctnumberrequired
no_rating_pctnumberrequiredgoals_weightnumberrequiredcapnumberrequired
prorationobjectrequired1 field
other_unpaid_leave"counted" | "not_counted"required
manager_adjust_pctintegerrequiredformulaobjectrequired2 fields
published_atstring | nullrequiredshared_otherwise_atstring | nullrequired
launchobject | nullrequired2 fields
doneintegerrequiredtotalintegerrequired
countsobjectrequired5 fields
draftintegerrequiredapprovedintegerrequiredskippedintegerrequiredreleasedintegerrequiredadjustedintegerrequired
totalsobject[]required4 fields
currencystringrequiredformula_centsintegerrequiredaward_centsintegerrequiredtarget_centsintegerrequired
releaseobjectrequired5 fields
payintegerrequiredzerointegerrequiredskipintegerrequireddoneintegerrequiredtotalsobject[]required2 fields
currencystringrequiredcentsintegerrequired
payoutsobjectrequired3 fields
in_payrollintegerrequiredby_handintegerrequiredpaidintegerrequired
created_atstringrequiredreleased_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/comp/bonus.plans.release_now', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"plan_id": "bp1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/comp/bonus.plans.release_now",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"plan_id": "bp1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_liston HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
plan_idstringrequired
Returns
planobjectrequired6 fields
idstringrequirednamestringrequiredstatus"draft" | "launching" | "open" | "releasing" | "released" | "cancelled"requiredperiodobjectrequired2 fields
fromstringrequiredtostringrequired
payout_onstringrequiredmanager_adjust_pctintegerrequired
itemsobject[]required29 fields
idstringrequiredpersonobjectrequired3 fields
idstringrequirednamestringrequiredtitlestring | nullrequired
state"draft" | "approved" | "skipped" | "released"requiredmanagerobject | nullrequired2 fields
idstringrequirednamestringrequired
currencystring | nullrequiredbase_centsinteger | nullrequiredtarget_pctnumberrequiredtarget_overridebooleanrequiredratingnumber | nullrequiredrating_pctnumberrequiredgoals_pctnumber | nullrequiredindividual_pctnumberrequiredprorationnumberrequireddaysintegerrequiredperiod_daysintegerrequiredunpaid_daysintegerrequiredformula_centsinteger | nullrequiredaward_centsinteger | nullrequiredadjust_pctnumber | nullrequiredThe award vs the formula, % (+10 = 10 % above).
target_centsinteger | nullrequiredpayout_rationumber | nullrequiredAward ÷ target, % (B4).
reason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"requiredreason_textstring | nullrequiredcommentstring | nullrequiredflags"no_pay" | "protected_leave" | "part_period" | "no_rating" | "adjusted" | "outside_range"[]requiredcan_decidebooleanrequiredwhy_notstring | nullrequiredskipped_reasonstring | nullrequiredpayoutobject | nullrequired3 fields
via"payroll" | "by_hand"requiredpaidbooleanrequiredwhystring | nullrequired
mineobject[]required10 fields
idstringrequiredpersonobjectrequired3 fields
idstringrequirednamestringrequiredtitlestring | nullrequired
state"draft" | "approved" | "skipped" | "released"requiredrating_labelstring | nullrequiredadjust_pctnumberrequiredThe award vs the formula, % (0: the formula).
reason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"requiredreason_textstring | nullrequiredcommentstring | nullrequirededitablebooleanrequiredpart_periodbooleanrequired
adjust_pctintegerrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/comp/bonus.awards.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"plan_id": "bp1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/comp/bonus.awards.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"plan_id": "bp1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_adjuston HR Assistant, My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
award_idstringrequiredadjust_pctnumberFrom -100 to 100.
centsinteger | nullFrom 0 to 1000000000.
target_pctnumber | nullFrom 0 to 200.
reason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"reason_textstring | nullUp to 500 characters.
commentstring | nullUp to 1000 characters.
Returns
idstringrequiredstate"draft" | "approved" | "skipped" | "released"requiredadjust_pctnumber | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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"
}'const res = await fetch('https://api.bizisy.com/v1/comp/bonus.awards.adjust', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"award_id": "bp1:p3",
"cents": 450000,
"reason": "other",
"reason_text": "Led the migration alone"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/comp/bonus.awards.adjust",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"award_id": "bp1:p3",
"cents": 450000,
"reason": "other",
"reason_text": "Led the migration alone",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_decideon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
plan_idstringrequiredaward_idsstring[]required1–500 items.
decision"approve" | "reopen"Default
"approve".notestringUp to 500 characters.
Returns
donestring[]requiredrefusedobject[]required2 fields
idstringrequiredreasonstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/comp/bonus.awards.decide', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"plan_id": "bp1",
"award_ids": [
"bp1:p3"
],
"decision": "reopen"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/comp/bonus.awards.decide",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"plan_id": "bp1",
"award_ids": [
"bp1:p3",
],
"decision": "reopen",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_equityon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
plan_idstringrequired
Returns
min_groupintegerrequiredhiddenintegerrequiredflaggedintegerrequiredcategoriesobject[]required8 fields
idstringrequirednamestringrequiredcurrencystringrequiredwomenintegerrequiredmenintegerrequiredawardobjectrequired3 fields
womennumberrequiredmennumberrequiredgapnumber | nullrequired
ratioobjectrequired3 fields
womennumberrequiredmennumberrequiredgapnumber | nullrequired
flaggedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/comp/bonus.equity \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"plan_id":"bp1"}'const res = await fetch('https://api.bizisy.com/v1/comp/bonus.equity', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"plan_id": "bp1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/comp/bonus.equity",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"plan_id": "bp1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_paidon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
plan_idstringrequiredaward_idsstring[]required1–500 items.
Returns
donestring[]requiredrefusedobject[]required2 fields
idstringrequiredreasonstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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"]}'const res = await fetch('https://api.bizisy.com/v1/comp/bonus.awards.mark_paid', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"plan_id": "bp1",
"award_ids": [
"bp1:p3"
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/comp/bonus.awards.mark_paid",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"plan_id": "bp1",
"award_ids": [
"bp1:p3",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"done": [
"bp1:p3"
],
"refused": []
}
}Something missing or wrong on this page? Write to hello@bizisy.com.