API reference
Salary reviews
Salary review cycles: the population, dates, the merit matrix (rating × compa-ratio) and budgets, launch, HR review under the pay approval rules, the equity check, release and the payroll file. Pay stays in the app: API keys and AI assistants get cycle names, dates and stage only.
22 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
List salary reviews#
POST/v1/comp/cycles.listRead
Salary review cycles: name, stage (draft, launching, proposing, review, preview, releasing, released, cancelled), effective date and dates. Owners, admins and HR see every cycle (Manage → Salary reviews). In Me, a manager sees the cycles they propose in while open and for 30 days after release (worksheet: draft, submitted or returned). API keys and AI assistants get names, dates and stage only: never pay, people or proposals. 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 stage only: never pay, people or proposals.
- MCP tool
comp_cycles_liston HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
itemsobject[]required7 fields
idstringrequirednamestringrequiredstagestring (enum)requiredOne of:
draft,launching,proposing,review,preview,releasing,released,cancelled.effective_datestringrequireddatesobjectrequired4 fields
propose_bystringrequiredreview_bystringrequiredmanager_preview_onstringrequiredrelease_onstringrequired
worksheet"draft" | "submitted" | "returned"requiredsign_off"waiting" | "signed" | "sent_back"required
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/comp/cycles.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/comp/cycles.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/cycles.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": "cy1",
"name": "Spring review",
"stage": "proposing",
"effective_date": "2027-01-01",
"dates": {
"propose_by": "2026-11-27",
"review_by": "2026-12-04",
"manager_preview_on": "2026-12-11",
"release_on": "2026-12-15"
},
"worksheet": "draft",
"sign_off": null
}
]
}
}Get a salary review#
POST/v1/comp/cycles.getRead
One salary review cycle with its setup (population, eligibility, effective date, dates, the merit matrix with rating rows and compa-ratio columns, the pools: merit %, promotion %, lump-sum amount per currency), progress (participants by state, worksheets submitted), budgets per currency and pool, what a release would do now and the lump sums (after the release: in payroll, to pay by hand, 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 cycle's setup, budgets and progress hold pay: read in the app only.
- MCP tool
comp_cycles_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
cycle_idstringrequired
Returns
26 fields
idstringrequirednamestringrequiredstatusstringrequiredstagestring (enum)requiredOne of:
draft,launching,proposing,review,preview,releasing,released,cancelled.populationobjectrequired5 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.
eligibilityobjectrequired3 fields
cutoff_datestringrequiredemployment_typesstring[]requirednew_joiners"exclude" | "prorate"required
effective_datestringrequireddatesobjectrequired4 fields
propose_bystringrequiredreview_bystringrequiredmanager_preview_onstringrequiredrelease_onstringrequired
manager_view"percent" | "amounts"requiredstepsobjectrequired2 fields
upper_reviewbooleanrequiredA submitted worksheet goes to the manager's own manager before HR (D6).
final_sign_offbooleanrequiredThe release needs a final sign-off of the totals (D8).
sign_offobject | nullrequiredThe final sign-off: signed, or sent back to HR with a note; null: waiting (or not required).
3 fields
state"signed" | "sent_back"requiredatstringrequirednotestring | nullrequired
guidelineobjectrequired10 fields
versionintegerrequiredrating_levelsobject[]required2 fields
valuenumberrequiredlabelstringrequired
cr_boundsnumber[]requiredcellsobject[]required5 fields
rowstringrequiredcolstringrequiredminnumberrequiredtargetnumberrequiredmaxnumberrequired
rowsstring[]requiredcolsstring[]requiredbring_to_minbooleanrequiredlump_above_maxbooleanrequiredrounding"none" | numberrequiredchanged_onstring | nullrequired
poolsobjectrequired4 fields
merit_pctnumberrequiredoverridesobject[]required2 fields
unit_idstringrequiredmerit_pctnumberrequired
promotion_pctnumber | nullrequiredlump_sum_by_currencyobject | nullrequired
rating_cycle_idstring | nullrequiredno_change_lettersbooleanrequiredcriteriaobjectrequired2 fields
published_atstring | nullrequiredshared_otherwise_atstring | nullrequired
launchobject | nullrequired2 fields
doneintegerrequiredtotalintegerrequired
progressobjectrequired4 fields
participantsintegerrequiredreleasedintegerrequiredskippedintegerrequiredstaleintegerrequired
countsobjectrequired7 fields
draftintegerrequiredsubmittedintegerrequiredapprovedintegerrequiredreturnedintegerrequiredstaleintegerrequiredskippedintegerrequiredreleasedintegerrequired
worksheetsobjectrequired2 fields
totalintegerrequiredsubmittedintegerrequired
budgetsobject[]required9 fields
currencystringrequiredeligiblenumberrequiredbudgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequiredpromotionobject | nullrequiredThe promotion pool (raises whose reason is promotion_pending), when the cycle has one.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
lumpobject | nullrequiredThe lump-sum pool (one-off payments), when the cycle has one for this currency.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
releaseobjectrequired6 fields
writeintegerrequiredno_changeintegerrequiredskipintegerrequiredstaleintegerrequireddoneintegerrequiredlump_sumsintegerrequired
lump_sumsobject | nullrequiredLump sums approved (before the release) or released (after), with totals per currency; after the release, how many went to payroll, wait to be paid by hand, or were marked paid. Null: none.
5 fields
countintegerrequiredtotalsobject[]required2 fields
currencystringrequiredamountnumberrequired
in_payrollintegerrequiredby_handintegerrequiredpaidintegerrequired
lettersobject | nullrequiredWith Documents on at release: letters made as documents (total), already in people's My documents, still to send (waiting) and waiting for HR in Documents → Prepared (blocked: a value missing, on paper). Null: letters are in My workspace → Pay only.
4 fields
totalintegerrequiredin_documentsintegerrequiredwaitingintegerrequiredblockedintegerrequired
created_atstringrequiredreleased_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/comp/cycles.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"cycle_id":"cy1"}'const res = await fetch('https://api.bizisy.com/v1/comp/cycles.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"cycle_id": "cy1"
}),
});
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/cycles.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"cycle_id": "cy1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "cy1",
"name": "Spring review",
"status": "open",
"stage": "proposing",
"population": {
"kind": "company"
},
"eligibility": {
"cutoff_date": "2026-10-01",
"employment_types": [],
"new_joiners": "exclude"
},
"effective_date": "2027-01-01",
"dates": {
"propose_by": "2026-11-27",
"review_by": "2026-12-04",
"manager_preview_on": "2026-12-11",
"release_on": "2026-12-15"
},
"manager_view": "percent",
"steps": {
"upper_review": false,
"final_sign_off": false
},
"sign_off": null,
"guideline": {
"version": 1,
"rating_levels": [
{
"value": 3,
"label": "Meets expectations"
}
],
"cr_bounds": [
0.9,
1,
1.1
],
"cells": [
{
"row": "r3",
"col": "c2",
"min": 2,
"target": 3,
"max": 4
}
],
"rows": [
"r3",
"none"
],
"cols": [
"c0",
"c1",
"c2",
"c3",
"nb"
],
"bring_to_min": true,
"lump_above_max": true,
"rounding": "none",
"changed_on": null
},
"pools": {
"merit_pct": 3,
"overrides": [],
"promotion_pct": 1,
"lump_sum_by_currency": {
"EUR": 20000
}
},
"rating_cycle_id": null,
"no_change_letters": true,
"criteria": {
"published_at": "2026-11-16T10:00:00.000Z",
"shared_otherwise_at": null
},
"launch": null,
"progress": {
"participants": 5,
"released": 0,
"skipped": 0,
"stale": 0
},
"counts": {
"draft": 3,
"submitted": 2,
"approved": 0,
"returned": 0,
"stale": 0,
"skipped": 0,
"released": 0
},
"worksheets": {
"total": 2,
"submitted": 1
},
"budgets": [
{
"currency": "EUR",
"eligible": 191000,
"budget": 5730,
"spent": 1500,
"remaining": 4230,
"over": false,
"used_pct": 26.2,
"promotion": {
"budget": 1910,
"spent": 0,
"remaining": 1910,
"over": false,
"used_pct": 0
},
"lump": {
"budget": 20000,
"spent": 2400,
"remaining": 17600,
"over": false,
"used_pct": 12
}
}
],
"release": {
"write": 0,
"no_change": 0,
"skip": 5,
"stale": 0,
"done": 0,
"lump_sums": 0
},
"letters": null,
"lump_sums": {
"count": 1,
"totals": [
{
"currency": "EUR",
"amount": 2400
}
],
"in_payroll": 0,
"by_hand": 0,
"paid": 0
},
"created_at": "2026-11-16T10:00:00.000Z",
"released_at": null
}
}Create a salary review#
POST/v1/comp/cycles.createWrite
Creates a salary review cycle as a draft: name; population (whole company, teams with the teams below them, or legal entities); eligibility (employed on the cut-off date, default 3 months before the effective date; employment types; joiners after the cut-off left out or pro-rated); effective_date (the new pay's start, may be before the release); dates (proposals due, HR review by, managers preview — default 2 days before release — and release); the merit matrix (default 5 rating levels plus "No rating" × compa-ratio bands < 0.90, 0.90–0.99, 1.00–1.09, ≥ 1.10 plus "No band", each cell min/target/max %); the merit pool as % of eligible annual base (default 3 %, overridable per team); optional pools: promotion_pct (raises with the reason promotion_pending draw on it) and lump_sum_by_currency (an amount per currency, e.g. {"EUR": 20000}, which turns on one-off lump sums; with it, pay above the band maximum gets its guideline raise suggested as a lump sum, guideline.lump_above_max, default on); the talent review cycle whose final ratings feed the matrix; letters for people with no change (default on); steps.upper_review (default off): a manager's submitted worksheet goes to their own manager before HR. The result's preview counts the population and the pool per currency: use dry_run first. At most 3 open cycles. 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. Salary reviews are set up in the app only.
- MCP tool
comp_cycles_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.
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
{}.3 fields
cutoff_datestringEmployed on this day to take part (default: 3 months before the effective date).
Pattern
^\d{4}-\d{2}-\d{2}$.employment_types"full_time" | "part_time" | "contractor" | "intern"[]Up to 4 items.
new_joiners"exclude" | "prorate"People who started after the cut-off: left out (default) or in, pro-rated by months.
effective_datestringrequiredPattern
^\d{4}-\d{2}-\d{2}$.datesobjectrequired4 fields
propose_bystringrequiredPattern
^\d{4}-\d{2}-\d{2}$.review_bystringrequiredPattern
^\d{4}-\d{2}-\d{2}$.manager_preview_onstringPattern
^\d{4}-\d{2}-\d{2}$.release_onstringrequiredPattern
^\d{4}-\d{2}-\d{2}$.
guidelineobject6 fields
rating_levelsobject[]required1–9 items.
2 fields
valueintegerrequiredFrom -10 to 20.
labelstringrequired1–60 characters.
cr_boundsnumber[]requiredFrom 0.3 to 3. 1–6 items.
cellsobject[]requiredUp to 50 items.
5 fields
rowstringrequiredPattern
^(r-?\d+|none)$.colstringrequiredPattern
^(c\d+|nb)$.minnumberrequiredFrom 0 to 100.
targetnumberrequiredFrom 0 to 100.
maxnumberrequiredFrom 0 to 100.
bring_to_minbooleanrequiredlump_above_maxbooleanPay above the band maximum: suggest the guideline's raise as a one-off lump sum instead of a base increase (default on; only where the cycle has a lump-sum budget).
rounding"none" | 1 | 5 | 10 | 50required
poolsobjectDefault
{"merit_pct":3}.4 fields
merit_pctnumberrequiredThe merit pool, % of the eligible annual base (e.g. 3).
From 0 to 100.
overridesobject[]Up to 200 items.
2 fields
unit_idstringrequiredmerit_pctnumberrequiredFrom 0 to 100.
promotion_pctnumber | nullAn optional separate promotion pool, % of the eligible annual base: raises with the reason promotion_pending draw on it instead of merit. null: none (left out on an update: kept).
From 0 to 100.
lump_sum_by_currencyobject | nullAn optional lump-sum pool: an amount per currency, e.g. {"EUR": 20000}; it turns on one-off lump sums (proposed as % of base). null: lump sums off (left out on an update: kept).
rating_cycle_idstring | null1–200 characters.
no_change_lettersbooleanDefault
true.stepsobject2 fields
upper_reviewbooleanUpper-manager step (D6, default off): a manager's submitted worksheet goes to their own manager, who reads it in %, may adjust it and sends it on to HR or back. Fixed at launch.
final_sign_offbooleanFinal sign-off (D8, default off): owners, or a custom role with Pay at Approve covering everyone, sign off the totals before the release (comp_cycles_sign_off). Fixed at launch.
manager_view"percent" | "amounts"What managers see on their worksheets (D15): percent (default: compa-ratio, position in the band, % budget, never salaries) or amounts (also current and new base pay and the money budget, while the review is open, each view recorded in Activity). Fixed at launch.
Returns
cycleobjectrequired26 fields
idstringrequirednamestringrequiredstatusstringrequiredstagestring (enum)requiredOne of:
draft,launching,proposing,review,preview,releasing,released,cancelled.populationobjectrequired5 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.
eligibilityobjectrequired3 fields
cutoff_datestringrequiredemployment_typesstring[]requirednew_joiners"exclude" | "prorate"required
effective_datestringrequireddatesobjectrequired4 fields
propose_bystringrequiredreview_bystringrequiredmanager_preview_onstringrequiredrelease_onstringrequired
manager_view"percent" | "amounts"requiredstepsobjectrequired2 fields
upper_reviewbooleanrequiredA submitted worksheet goes to the manager's own manager before HR (D6).
final_sign_offbooleanrequiredThe release needs a final sign-off of the totals (D8).
sign_offobject | nullrequiredThe final sign-off: signed, or sent back to HR with a note; null: waiting (or not required).
3 fields
state"signed" | "sent_back"requiredatstringrequirednotestring | nullrequired
guidelineobjectrequired10 fields
versionintegerrequiredrating_levelsobject[]required2 fields
valuenumberrequiredlabelstringrequired
cr_boundsnumber[]requiredcellsobject[]required5 fields
rowstringrequiredcolstringrequiredminnumberrequiredtargetnumberrequiredmaxnumberrequired
rowsstring[]requiredcolsstring[]requiredbring_to_minbooleanrequiredlump_above_maxbooleanrequiredrounding"none" | numberrequiredchanged_onstring | nullrequired
poolsobjectrequired4 fields
merit_pctnumberrequiredoverridesobject[]required2 fields
unit_idstringrequiredmerit_pctnumberrequired
promotion_pctnumber | nullrequiredlump_sum_by_currencyobject | nullrequired
rating_cycle_idstring | nullrequiredno_change_lettersbooleanrequiredcriteriaobjectrequired2 fields
published_atstring | nullrequiredshared_otherwise_atstring | nullrequired
launchobject | nullrequired2 fields
doneintegerrequiredtotalintegerrequired
progressobjectrequired4 fields
participantsintegerrequiredreleasedintegerrequiredskippedintegerrequiredstaleintegerrequired
countsobjectrequired7 fields
draftintegerrequiredsubmittedintegerrequiredapprovedintegerrequiredreturnedintegerrequiredstaleintegerrequiredskippedintegerrequiredreleasedintegerrequired
worksheetsobjectrequired2 fields
totalintegerrequiredsubmittedintegerrequired
budgetsobject[]required9 fields
currencystringrequiredeligiblenumberrequiredbudgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequiredpromotionobject | nullrequiredThe promotion pool (raises whose reason is promotion_pending), when the cycle has one.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
lumpobject | nullrequiredThe lump-sum pool (one-off payments), when the cycle has one for this currency.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
releaseobjectrequired6 fields
writeintegerrequiredno_changeintegerrequiredskipintegerrequiredstaleintegerrequireddoneintegerrequiredlump_sumsintegerrequired
lump_sumsobject | nullrequiredLump sums approved (before the release) or released (after), with totals per currency; after the release, how many went to payroll, wait to be paid by hand, or were marked paid. Null: none.
5 fields
countintegerrequiredtotalsobject[]required2 fields
currencystringrequiredamountnumberrequired
in_payrollintegerrequiredby_handintegerrequiredpaidintegerrequired
lettersobject | nullrequiredWith Documents on at release: letters made as documents (total), already in people's My documents, still to send (waiting) and waiting for HR in Documents → Prepared (blocked: a value missing, on paper). Null: letters are in My workspace → Pay only.
4 fields
totalintegerrequiredin_documentsintegerrequiredwaitingintegerrequiredblockedintegerrequired
created_atstringrequiredreleased_atstring | nullrequired
previewobjectrequired5 fields
peopleintegerrequiredeligibleintegerrequiredexcludedobjectrequired3 fields
not_employedintegerrequiredafter_cutoffintegerrequiredemployment_typeintegerrequired
flagsobjectrequired6 fields
no_payintegerrequiredno_bandintegerrequiredbelow_minintegerrequiredabove_maxintegerrequirednew_joinerintegerrequiredother_currencyintegerrequired
budgetsobject[]required9 fields
currencystringrequiredeligiblenumberrequiredbudgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequiredpromotionobject | nullrequiredThe promotion pool (raises whose reason is promotion_pending), when the cycle has one.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
lumpobject | nullrequiredThe lump-sum pool (one-off payments), when the cycle has one for this currency.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/comp/cycles.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Spring review",
"effective_date": "2027-01-01",
"dates": {
"propose_by": "2026-11-27",
"review_by": "2026-12-04",
"release_on": "2026-12-15"
},
"population": {
"kind": "units",
"unit_ids": [
"u1"
]
},
"eligibility": {
"cutoff_date": "2026-10-01",
"new_joiners": "prorate"
},
"pools": {
"merit_pct": 3.5,
"overrides": [
{
"unit_id": "u1",
"merit_pct": 4
}
],
"promotion_pct": 1,
"lump_sum_by_currency": {
"EUR": 20000
}
},
"no_change_letters": false,
"rating_cycle_id": "tc1",
"guideline": {
"rating_levels": [
{
"value": 3,
"label": "Meets"
}
],
"cr_bounds": [
0.9,
1,
1.1
],
"cells": [
{
"row": "r3",
"col": "c2",
"min": 2,
"target": 3,
"max": 4
}
],
"bring_to_min": true,
"rounding": 10
}
}'const res = await fetch('https://api.bizisy.com/v1/comp/cycles.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"name": "Spring review",
"effective_date": "2027-01-01",
"dates": {
"propose_by": "2026-11-27",
"review_by": "2026-12-04",
"release_on": "2026-12-15"
},
"population": {
"kind": "units",
"unit_ids": [
"u1"
]
},
"eligibility": {
"cutoff_date": "2026-10-01",
"new_joiners": "prorate"
},
"pools": {
"merit_pct": 3.5,
"overrides": [
{
"unit_id": "u1",
"merit_pct": 4
}
],
"promotion_pct": 1,
"lump_sum_by_currency": {
"EUR": 20000
}
},
"no_change_letters": false,
"rating_cycle_id": "tc1",
"guideline": {
"rating_levels": [
{
"value": 3,
"label": "Meets"
}
],
"cr_bounds": [
0.9,
1,
1.1
],
"cells": [
{
"row": "r3",
"col": "c2",
"min": 2,
"target": 3,
"max": 4
}
],
"bring_to_min": true,
"rounding": 10
}
}),
});
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/cycles.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "Spring review",
"effective_date": "2027-01-01",
"dates": {
"propose_by": "2026-11-27",
"review_by": "2026-12-04",
"release_on": "2026-12-15",
},
"population": {
"kind": "units",
"unit_ids": [
"u1",
],
},
"eligibility": {
"cutoff_date": "2026-10-01",
"new_joiners": "prorate",
},
"pools": {
"merit_pct": 3.5,
"overrides": [
{
"unit_id": "u1",
"merit_pct": 4,
},
],
"promotion_pct": 1,
"lump_sum_by_currency": {
"EUR": 20000,
},
},
"no_change_letters": False,
"rating_cycle_id": "tc1",
"guideline": {
"rating_levels": [
{
"value": 3,
"label": "Meets",
},
],
"cr_bounds": [
0.9,
1,
1.1,
],
"cells": [
{
"row": "r3",
"col": "c2",
"min": 2,
"target": 3,
"max": 4,
},
],
"bring_to_min": True,
"rounding": 10,
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"cycle": {
"id": "cy1",
"name": "Spring review",
"status": "draft",
"stage": "draft",
"population": {
"kind": "company"
},
"eligibility": {
"cutoff_date": "2026-10-01",
"employment_types": [],
"new_joiners": "exclude"
},
"effective_date": "2027-01-01",
"dates": {
"propose_by": "2026-11-27",
"review_by": "2026-12-04",
"manager_preview_on": "2026-12-11",
"release_on": "2026-12-15"
},
"manager_view": "percent",
"steps": {
"upper_review": false,
"final_sign_off": false
},
"sign_off": null,
"guideline": {
"version": 1,
"rating_levels": [
{
"value": 3,
"label": "Meets expectations"
}
],
"cr_bounds": [
0.9,
1,
1.1
],
"cells": [
{
"row": "r3",
"col": "c2",
"min": 2,
"target": 3,
"max": 4
}
],
"rows": [
"r3",
"none"
],
"cols": [
"c0",
"c1",
"c2",
"c3",
"nb"
],
"bring_to_min": true,
"lump_above_max": true,
"rounding": "none",
"changed_on": null
},
"pools": {
"merit_pct": 3,
"overrides": [],
"promotion_pct": 1,
"lump_sum_by_currency": {
"EUR": 20000
}
},
"rating_cycle_id": null,
"no_change_letters": true,
"criteria": {
"published_at": "2026-11-16T10:00:00.000Z",
"shared_otherwise_at": null
},
"launch": null,
"progress": {
"participants": 5,
"released": 0,
"skipped": 0,
"stale": 0
},
"counts": {
"draft": 3,
"submitted": 2,
"approved": 0,
"returned": 0,
"stale": 0,
"skipped": 0,
"released": 0
},
"worksheets": {
"total": 2,
"submitted": 1
},
"budgets": [
{
"currency": "EUR",
"eligible": 191000,
"budget": 5730,
"spent": 1500,
"remaining": 4230,
"over": false,
"used_pct": 26.2,
"promotion": {
"budget": 1910,
"spent": 0,
"remaining": 1910,
"over": false,
"used_pct": 0
},
"lump": {
"budget": 20000,
"spent": 2400,
"remaining": 17600,
"over": false,
"used_pct": 12
}
}
],
"release": {
"write": 0,
"no_change": 0,
"skip": 5,
"stale": 0,
"done": 0,
"lump_sums": 0
},
"letters": null,
"lump_sums": {
"count": 1,
"totals": [
{
"currency": "EUR",
"amount": 2400
}
],
"in_payroll": 0,
"by_hand": 0,
"paid": 0
},
"created_at": "2026-11-16T10:00:00.000Z",
"released_at": null
},
"preview": {
"people": 5,
"eligible": 5,
"excluded": {
"not_employed": 0,
"after_cutoff": 0,
"employment_type": 0
},
"flags": {
"no_pay": 1,
"no_band": 2,
"below_min": 1,
"above_max": 0,
"new_joiner": 0,
"other_currency": 0
},
"budgets": [
{
"currency": "EUR",
"eligible": 191000,
"budget": 5730,
"spent": 1500,
"remaining": 4230,
"over": false,
"used_pct": 26.2,
"promotion": {
"budget": 1910,
"spent": 0,
"remaining": 1910,
"over": false,
"used_pct": 0
},
"lump": {
"budget": 20000,
"spent": 2400,
"remaining": 17600,
"over": false,
"used_pct": 12
}
}
]
}
}
}Change a salary review#
POST/v1/comp/cycles.updateWrite
Changes a salary review. A draft: anything. After launch: the name, dates (before the release), the merit matrix (a new version; managers see "guidelines changed on …"; worksheets keep their proposals and re-check reasons on save), the pools (merit %, promotion %, lump-sum amounts per currency; pools.promotion_pct and pools.lump_sum_by_currency left out are kept) and letters for no change; never the population, eligibility or effective date (cancel and create a new one). Not once releasing. 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. Salary reviews are set up in the app only.
- MCP tool
comp_cycles_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
cycle_idstringrequirednamestring1–120 characters.
populationobject5 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.
eligibilityobject3 fields
cutoff_datestringEmployed on this day to take part (default: 3 months before the effective date).
Pattern
^\d{4}-\d{2}-\d{2}$.employment_types"full_time" | "part_time" | "contractor" | "intern"[]Up to 4 items.
new_joiners"exclude" | "prorate"People who started after the cut-off: left out (default) or in, pro-rated by months.
effective_datestringPattern
^\d{4}-\d{2}-\d{2}$.datesobject4 fields
propose_bystringrequiredPattern
^\d{4}-\d{2}-\d{2}$.review_bystringrequiredPattern
^\d{4}-\d{2}-\d{2}$.manager_preview_onstringPattern
^\d{4}-\d{2}-\d{2}$.release_onstringrequiredPattern
^\d{4}-\d{2}-\d{2}$.
guidelineobject6 fields
rating_levelsobject[]required1–9 items.
2 fields
valueintegerrequiredFrom -10 to 20.
labelstringrequired1–60 characters.
cr_boundsnumber[]requiredFrom 0.3 to 3. 1–6 items.
cellsobject[]requiredUp to 50 items.
5 fields
rowstringrequiredPattern
^(r-?\d+|none)$.colstringrequiredPattern
^(c\d+|nb)$.minnumberrequiredFrom 0 to 100.
targetnumberrequiredFrom 0 to 100.
maxnumberrequiredFrom 0 to 100.
bring_to_minbooleanrequiredlump_above_maxbooleanPay above the band maximum: suggest the guideline's raise as a one-off lump sum instead of a base increase (default on; only where the cycle has a lump-sum budget).
rounding"none" | 1 | 5 | 10 | 50required
poolsobject4 fields
merit_pctnumberrequiredThe merit pool, % of the eligible annual base (e.g. 3).
From 0 to 100.
overridesobject[]Up to 200 items.
2 fields
unit_idstringrequiredmerit_pctnumberrequiredFrom 0 to 100.
promotion_pctnumber | nullAn optional separate promotion pool, % of the eligible annual base: raises with the reason promotion_pending draw on it instead of merit. null: none (left out on an update: kept).
From 0 to 100.
lump_sum_by_currencyobject | nullAn optional lump-sum pool: an amount per currency, e.g. {"EUR": 20000}; it turns on one-off lump sums (proposed as % of base). null: lump sums off (left out on an update: kept).
rating_cycle_idstring | null1–200 characters.
no_change_lettersbooleanstepsobject2 fields
upper_reviewbooleanUpper-manager step (D6, default off): a manager's submitted worksheet goes to their own manager, who reads it in %, may adjust it and sends it on to HR or back. Fixed at launch.
final_sign_offbooleanFinal sign-off (D8, default off): owners, or a custom role with Pay at Approve covering everyone, sign off the totals before the release (comp_cycles_sign_off). Fixed at launch.
manager_view"percent" | "amounts"What managers see on their worksheets (D15): percent (default: compa-ratio, position in the band, % budget, never salaries) or amounts (also current and new base pay and the money budget, while the review is open, each view recorded in Activity). Fixed at launch.
Returns
cycleobjectrequired26 fields
idstringrequirednamestringrequiredstatusstringrequiredstagestring (enum)requiredOne of:
draft,launching,proposing,review,preview,releasing,released,cancelled.populationobjectrequired5 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.
eligibilityobjectrequired3 fields
cutoff_datestringrequiredemployment_typesstring[]requirednew_joiners"exclude" | "prorate"required
effective_datestringrequireddatesobjectrequired4 fields
propose_bystringrequiredreview_bystringrequiredmanager_preview_onstringrequiredrelease_onstringrequired
manager_view"percent" | "amounts"requiredstepsobjectrequired2 fields
upper_reviewbooleanrequiredA submitted worksheet goes to the manager's own manager before HR (D6).
final_sign_offbooleanrequiredThe release needs a final sign-off of the totals (D8).
sign_offobject | nullrequiredThe final sign-off: signed, or sent back to HR with a note; null: waiting (or not required).
3 fields
state"signed" | "sent_back"requiredatstringrequirednotestring | nullrequired
guidelineobjectrequired10 fields
versionintegerrequiredrating_levelsobject[]required2 fields
valuenumberrequiredlabelstringrequired
cr_boundsnumber[]requiredcellsobject[]required5 fields
rowstringrequiredcolstringrequiredminnumberrequiredtargetnumberrequiredmaxnumberrequired
rowsstring[]requiredcolsstring[]requiredbring_to_minbooleanrequiredlump_above_maxbooleanrequiredrounding"none" | numberrequiredchanged_onstring | nullrequired
poolsobjectrequired4 fields
merit_pctnumberrequiredoverridesobject[]required2 fields
unit_idstringrequiredmerit_pctnumberrequired
promotion_pctnumber | nullrequiredlump_sum_by_currencyobject | nullrequired
rating_cycle_idstring | nullrequiredno_change_lettersbooleanrequiredcriteriaobjectrequired2 fields
published_atstring | nullrequiredshared_otherwise_atstring | nullrequired
launchobject | nullrequired2 fields
doneintegerrequiredtotalintegerrequired
progressobjectrequired4 fields
participantsintegerrequiredreleasedintegerrequiredskippedintegerrequiredstaleintegerrequired
countsobjectrequired7 fields
draftintegerrequiredsubmittedintegerrequiredapprovedintegerrequiredreturnedintegerrequiredstaleintegerrequiredskippedintegerrequiredreleasedintegerrequired
worksheetsobjectrequired2 fields
totalintegerrequiredsubmittedintegerrequired
budgetsobject[]required9 fields
currencystringrequiredeligiblenumberrequiredbudgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequiredpromotionobject | nullrequiredThe promotion pool (raises whose reason is promotion_pending), when the cycle has one.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
lumpobject | nullrequiredThe lump-sum pool (one-off payments), when the cycle has one for this currency.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
releaseobjectrequired6 fields
writeintegerrequiredno_changeintegerrequiredskipintegerrequiredstaleintegerrequireddoneintegerrequiredlump_sumsintegerrequired
lump_sumsobject | nullrequiredLump sums approved (before the release) or released (after), with totals per currency; after the release, how many went to payroll, wait to be paid by hand, or were marked paid. Null: none.
5 fields
countintegerrequiredtotalsobject[]required2 fields
currencystringrequiredamountnumberrequired
in_payrollintegerrequiredby_handintegerrequiredpaidintegerrequired
lettersobject | nullrequiredWith Documents on at release: letters made as documents (total), already in people's My documents, still to send (waiting) and waiting for HR in Documents → Prepared (blocked: a value missing, on paper). Null: letters are in My workspace → Pay only.
4 fields
totalintegerrequiredin_documentsintegerrequiredwaitingintegerrequiredblockedintegerrequired
created_atstringrequiredreleased_atstring | nullrequired
previewobject | nullrequired5 fields
peopleintegerrequiredeligibleintegerrequiredexcludedobjectrequired3 fields
not_employedintegerrequiredafter_cutoffintegerrequiredemployment_typeintegerrequired
flagsobjectrequired6 fields
no_payintegerrequiredno_bandintegerrequiredbelow_minintegerrequiredabove_maxintegerrequirednew_joinerintegerrequiredother_currencyintegerrequired
budgetsobject[]required9 fields
currencystringrequiredeligiblenumberrequiredbudgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequiredpromotionobject | nullrequiredThe promotion pool (raises whose reason is promotion_pending), when the cycle has one.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
lumpobject | nullrequiredThe lump-sum pool (one-off payments), when the cycle has one for this currency.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/comp/cycles.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"cycle_id":"cy1","steps":{"final_sign_off":true}}'const res = await fetch('https://api.bizisy.com/v1/comp/cycles.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"cycle_id": "cy1",
"steps": {
"final_sign_off": 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/cycles.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"cycle_id": "cy1",
"steps": {
"final_sign_off": True,
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"cycle": {
"id": "cy1",
"name": "Spring review",
"status": "open",
"stage": "proposing",
"population": {
"kind": "company"
},
"eligibility": {
"cutoff_date": "2026-10-01",
"employment_types": [],
"new_joiners": "exclude"
},
"effective_date": "2027-01-01",
"dates": {
"propose_by": "2026-11-27",
"review_by": "2026-12-04",
"manager_preview_on": "2026-12-11",
"release_on": "2026-12-15"
},
"manager_view": "percent",
"steps": {
"upper_review": false,
"final_sign_off": false
},
"sign_off": null,
"guideline": {
"version": 1,
"rating_levels": [
{
"value": 3,
"label": "Meets expectations"
}
],
"cr_bounds": [
0.9,
1,
1.1
],
"cells": [
{
"row": "r3",
"col": "c2",
"min": 2,
"target": 3,
"max": 4
}
],
"rows": [
"r3",
"none"
],
"cols": [
"c0",
"c1",
"c2",
"c3",
"nb"
],
"bring_to_min": true,
"lump_above_max": true,
"rounding": "none",
"changed_on": null
},
"pools": {
"merit_pct": 3,
"overrides": [],
"promotion_pct": 1,
"lump_sum_by_currency": {
"EUR": 20000
}
},
"rating_cycle_id": null,
"no_change_letters": true,
"criteria": {
"published_at": "2026-11-16T10:00:00.000Z",
"shared_otherwise_at": null
},
"launch": null,
"progress": {
"participants": 5,
"released": 0,
"skipped": 0,
"stale": 0
},
"counts": {
"draft": 3,
"submitted": 2,
"approved": 0,
"returned": 0,
"stale": 0,
"skipped": 0,
"released": 0
},
"worksheets": {
"total": 2,
"submitted": 1
},
"budgets": [
{
"currency": "EUR",
"eligible": 191000,
"budget": 5730,
"spent": 1500,
"remaining": 4230,
"over": false,
"used_pct": 26.2,
"promotion": {
"budget": 1910,
"spent": 0,
"remaining": 1910,
"over": false,
"used_pct": 0
},
"lump": {
"budget": 20000,
"spent": 2400,
"remaining": 17600,
"over": false,
"used_pct": 12
}
}
],
"release": {
"write": 0,
"no_change": 0,
"skip": 5,
"stale": 0,
"done": 0,
"lump_sums": 0
},
"letters": null,
"lump_sums": {
"count": 1,
"totals": [
{
"currency": "EUR",
"amount": 2400
}
],
"in_payroll": 0,
"by_hand": 0,
"paid": 0
},
"created_at": "2026-11-16T10:00:00.000Z",
"released_at": null
},
"preview": null
}
}Publish a salary review's criteria#
POST/v1/comp/cycles.publish_criteriaWrite
Publishes the criteria of a salary review to everyone (EU Pay Transparency Directive art. 6): the merit matrix (rating × compa-ratio, % ranges), the merit pool as a % (never amounts), rounding and the reasons a proposal outside the guideline needs. They show in My workspace → Pay → "How pay progresses" (comp_me_criteria). Or, with shared_otherwise, records that the criteria were shared with staff another way. A cycle 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. Criteria are published to staff in the app only.
- MCP tool
comp_cycles_publish_criteriaon 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
cycle_idstringrequiredshared_otherwisebooleanunpublishboolean
Returns
26 fields
idstringrequirednamestringrequiredstatusstringrequiredstagestring (enum)requiredOne of:
draft,launching,proposing,review,preview,releasing,released,cancelled.populationobjectrequired5 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.
eligibilityobjectrequired3 fields
cutoff_datestringrequiredemployment_typesstring[]requirednew_joiners"exclude" | "prorate"required
effective_datestringrequireddatesobjectrequired4 fields
propose_bystringrequiredreview_bystringrequiredmanager_preview_onstringrequiredrelease_onstringrequired
manager_view"percent" | "amounts"requiredstepsobjectrequired2 fields
upper_reviewbooleanrequiredA submitted worksheet goes to the manager's own manager before HR (D6).
final_sign_offbooleanrequiredThe release needs a final sign-off of the totals (D8).
sign_offobject | nullrequiredThe final sign-off: signed, or sent back to HR with a note; null: waiting (or not required).
3 fields
state"signed" | "sent_back"requiredatstringrequirednotestring | nullrequired
guidelineobjectrequired10 fields
versionintegerrequiredrating_levelsobject[]required2 fields
valuenumberrequiredlabelstringrequired
cr_boundsnumber[]requiredcellsobject[]required5 fields
rowstringrequiredcolstringrequiredminnumberrequiredtargetnumberrequiredmaxnumberrequired
rowsstring[]requiredcolsstring[]requiredbring_to_minbooleanrequiredlump_above_maxbooleanrequiredrounding"none" | numberrequiredchanged_onstring | nullrequired
poolsobjectrequired4 fields
merit_pctnumberrequiredoverridesobject[]required2 fields
unit_idstringrequiredmerit_pctnumberrequired
promotion_pctnumber | nullrequiredlump_sum_by_currencyobject | nullrequired
rating_cycle_idstring | nullrequiredno_change_lettersbooleanrequiredcriteriaobjectrequired2 fields
published_atstring | nullrequiredshared_otherwise_atstring | nullrequired
launchobject | nullrequired2 fields
doneintegerrequiredtotalintegerrequired
progressobjectrequired4 fields
participantsintegerrequiredreleasedintegerrequiredskippedintegerrequiredstaleintegerrequired
countsobjectrequired7 fields
draftintegerrequiredsubmittedintegerrequiredapprovedintegerrequiredreturnedintegerrequiredstaleintegerrequiredskippedintegerrequiredreleasedintegerrequired
worksheetsobjectrequired2 fields
totalintegerrequiredsubmittedintegerrequired
budgetsobject[]required9 fields
currencystringrequiredeligiblenumberrequiredbudgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequiredpromotionobject | nullrequiredThe promotion pool (raises whose reason is promotion_pending), when the cycle has one.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
lumpobject | nullrequiredThe lump-sum pool (one-off payments), when the cycle has one for this currency.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
releaseobjectrequired6 fields
writeintegerrequiredno_changeintegerrequiredskipintegerrequiredstaleintegerrequireddoneintegerrequiredlump_sumsintegerrequired
lump_sumsobject | nullrequiredLump sums approved (before the release) or released (after), with totals per currency; after the release, how many went to payroll, wait to be paid by hand, or were marked paid. Null: none.
5 fields
countintegerrequiredtotalsobject[]required2 fields
currencystringrequiredamountnumberrequired
in_payrollintegerrequiredby_handintegerrequiredpaidintegerrequired
lettersobject | nullrequiredWith Documents on at release: letters made as documents (total), already in people's My documents, still to send (waiting) and waiting for HR in Documents → Prepared (blocked: a value missing, on paper). Null: letters are in My workspace → Pay only.
4 fields
totalintegerrequiredin_documentsintegerrequiredwaitingintegerrequiredblockedintegerrequired
created_atstringrequiredreleased_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/comp/cycles.publish_criteria \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"cycle_id":"cy1","shared_otherwise":true}'const res = await fetch('https://api.bizisy.com/v1/comp/cycles.publish_criteria', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"cycle_id": "cy1",
"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/cycles.publish_criteria",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"cycle_id": "cy1",
"shared_otherwise": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "cy1",
"name": "Spring review",
"status": "open",
"stage": "proposing",
"population": {
"kind": "company"
},
"eligibility": {
"cutoff_date": "2026-10-01",
"employment_types": [],
"new_joiners": "exclude"
},
"effective_date": "2027-01-01",
"dates": {
"propose_by": "2026-11-27",
"review_by": "2026-12-04",
"manager_preview_on": "2026-12-11",
"release_on": "2026-12-15"
},
"manager_view": "percent",
"steps": {
"upper_review": false,
"final_sign_off": false
},
"sign_off": null,
"guideline": {
"version": 1,
"rating_levels": [
{
"value": 3,
"label": "Meets expectations"
}
],
"cr_bounds": [
0.9,
1,
1.1
],
"cells": [
{
"row": "r3",
"col": "c2",
"min": 2,
"target": 3,
"max": 4
}
],
"rows": [
"r3",
"none"
],
"cols": [
"c0",
"c1",
"c2",
"c3",
"nb"
],
"bring_to_min": true,
"lump_above_max": true,
"rounding": "none",
"changed_on": null
},
"pools": {
"merit_pct": 3,
"overrides": [],
"promotion_pct": 1,
"lump_sum_by_currency": {
"EUR": 20000
}
},
"rating_cycle_id": null,
"no_change_letters": true,
"criteria": {
"published_at": "2026-11-16T10:00:00.000Z",
"shared_otherwise_at": null
},
"launch": null,
"progress": {
"participants": 5,
"released": 0,
"skipped": 0,
"stale": 0
},
"counts": {
"draft": 3,
"submitted": 2,
"approved": 0,
"returned": 0,
"stale": 0,
"skipped": 0,
"released": 0
},
"worksheets": {
"total": 2,
"submitted": 1
},
"budgets": [
{
"currency": "EUR",
"eligible": 191000,
"budget": 5730,
"spent": 1500,
"remaining": 4230,
"over": false,
"used_pct": 26.2,
"promotion": {
"budget": 1910,
"spent": 0,
"remaining": 1910,
"over": false,
"used_pct": 0
},
"lump": {
"budget": 20000,
"spent": 2400,
"remaining": 17600,
"over": false,
"used_pct": 12
}
}
],
"release": {
"write": 0,
"no_change": 0,
"skip": 5,
"stale": 0,
"done": 0,
"lump_sums": 0
},
"letters": null,
"lump_sums": {
"count": 1,
"totals": [
{
"currency": "EUR",
"amount": 2400
}
],
"in_payroll": 0,
"by_hand": 0,
"paid": 0
},
"created_at": "2026-11-16T10:00:00.000Z",
"released_at": null
}
}Launch a salary review#
POST/v1/comp/cycles.launchWrite
Launches a draft salary review: snapshots each eligible person's pay on the effective date (base, annualised, band, compa-ratio, the final rating from the talent review cycle when set, flags) and gives each manager a worksheet of their direct reports (proposals in %, never salaries). Large populations are snapshotted 100 people at a time: the first part now, the rest from the cycle page or within minutes. Needs the criteria published to staff, or recorded as shared another way (Directive art. 6). The participant learns nothing. A dry run counts who would take 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 salary review is launched in the app only.
- MCP tool
comp_cycles_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
cycle_idstringrequired
Returns
cycleobjectrequired26 fields
idstringrequirednamestringrequiredstatusstringrequiredstagestring (enum)requiredOne of:
draft,launching,proposing,review,preview,releasing,released,cancelled.populationobjectrequired5 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.
eligibilityobjectrequired3 fields
cutoff_datestringrequiredemployment_typesstring[]requirednew_joiners"exclude" | "prorate"required
effective_datestringrequireddatesobjectrequired4 fields
propose_bystringrequiredreview_bystringrequiredmanager_preview_onstringrequiredrelease_onstringrequired
manager_view"percent" | "amounts"requiredstepsobjectrequired2 fields
upper_reviewbooleanrequiredA submitted worksheet goes to the manager's own manager before HR (D6).
final_sign_offbooleanrequiredThe release needs a final sign-off of the totals (D8).
sign_offobject | nullrequiredThe final sign-off: signed, or sent back to HR with a note; null: waiting (or not required).
3 fields
state"signed" | "sent_back"requiredatstringrequirednotestring | nullrequired
guidelineobjectrequired10 fields
versionintegerrequiredrating_levelsobject[]required2 fields
valuenumberrequiredlabelstringrequired
cr_boundsnumber[]requiredcellsobject[]required5 fields
rowstringrequiredcolstringrequiredminnumberrequiredtargetnumberrequiredmaxnumberrequired
rowsstring[]requiredcolsstring[]requiredbring_to_minbooleanrequiredlump_above_maxbooleanrequiredrounding"none" | numberrequiredchanged_onstring | nullrequired
poolsobjectrequired4 fields
merit_pctnumberrequiredoverridesobject[]required2 fields
unit_idstringrequiredmerit_pctnumberrequired
promotion_pctnumber | nullrequiredlump_sum_by_currencyobject | nullrequired
rating_cycle_idstring | nullrequiredno_change_lettersbooleanrequiredcriteriaobjectrequired2 fields
published_atstring | nullrequiredshared_otherwise_atstring | nullrequired
launchobject | nullrequired2 fields
doneintegerrequiredtotalintegerrequired
progressobjectrequired4 fields
participantsintegerrequiredreleasedintegerrequiredskippedintegerrequiredstaleintegerrequired
countsobjectrequired7 fields
draftintegerrequiredsubmittedintegerrequiredapprovedintegerrequiredreturnedintegerrequiredstaleintegerrequiredskippedintegerrequiredreleasedintegerrequired
worksheetsobjectrequired2 fields
totalintegerrequiredsubmittedintegerrequired
budgetsobject[]required9 fields
currencystringrequiredeligiblenumberrequiredbudgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequiredpromotionobject | nullrequiredThe promotion pool (raises whose reason is promotion_pending), when the cycle has one.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
lumpobject | nullrequiredThe lump-sum pool (one-off payments), when the cycle has one for this currency.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
releaseobjectrequired6 fields
writeintegerrequiredno_changeintegerrequiredskipintegerrequiredstaleintegerrequireddoneintegerrequiredlump_sumsintegerrequired
lump_sumsobject | nullrequiredLump sums approved (before the release) or released (after), with totals per currency; after the release, how many went to payroll, wait to be paid by hand, or were marked paid. Null: none.
5 fields
countintegerrequiredtotalsobject[]required2 fields
currencystringrequiredamountnumberrequired
in_payrollintegerrequiredby_handintegerrequiredpaidintegerrequired
lettersobject | nullrequiredWith Documents on at release: letters made as documents (total), already in people's My documents, still to send (waiting) and waiting for HR in Documents → Prepared (blocked: a value missing, on paper). Null: letters are in My workspace → Pay only.
4 fields
totalintegerrequiredin_documentsintegerrequiredwaitingintegerrequiredblockedintegerrequired
created_atstringrequiredreleased_atstring | nullrequired
previewobjectrequired5 fields
peopleintegerrequiredeligibleintegerrequiredexcludedobjectrequired3 fields
not_employedintegerrequiredafter_cutoffintegerrequiredemployment_typeintegerrequired
flagsobjectrequired6 fields
no_payintegerrequiredno_bandintegerrequiredbelow_minintegerrequiredabove_maxintegerrequirednew_joinerintegerrequiredother_currencyintegerrequired
budgetsobject[]required9 fields
currencystringrequiredeligiblenumberrequiredbudgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequiredpromotionobject | nullrequiredThe promotion pool (raises whose reason is promotion_pending), when the cycle has one.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
lumpobject | nullrequiredThe lump-sum pool (one-off payments), when the cycle has one for this currency.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/comp/cycles.launch \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"cycle_id":"cy1"}'const res = await fetch('https://api.bizisy.com/v1/comp/cycles.launch', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"cycle_id": "cy1"
}),
});
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/cycles.launch",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"cycle_id": "cy1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"cycle": {
"id": "cy1",
"name": "Spring review",
"status": "open",
"stage": "proposing",
"population": {
"kind": "company"
},
"eligibility": {
"cutoff_date": "2026-10-01",
"employment_types": [],
"new_joiners": "exclude"
},
"effective_date": "2027-01-01",
"dates": {
"propose_by": "2026-11-27",
"review_by": "2026-12-04",
"manager_preview_on": "2026-12-11",
"release_on": "2026-12-15"
},
"manager_view": "percent",
"steps": {
"upper_review": false,
"final_sign_off": false
},
"sign_off": null,
"guideline": {
"version": 1,
"rating_levels": [
{
"value": 3,
"label": "Meets expectations"
}
],
"cr_bounds": [
0.9,
1,
1.1
],
"cells": [
{
"row": "r3",
"col": "c2",
"min": 2,
"target": 3,
"max": 4
}
],
"rows": [
"r3",
"none"
],
"cols": [
"c0",
"c1",
"c2",
"c3",
"nb"
],
"bring_to_min": true,
"lump_above_max": true,
"rounding": "none",
"changed_on": null
},
"pools": {
"merit_pct": 3,
"overrides": [],
"promotion_pct": 1,
"lump_sum_by_currency": {
"EUR": 20000
}
},
"rating_cycle_id": null,
"no_change_letters": true,
"criteria": {
"published_at": "2026-11-16T10:00:00.000Z",
"shared_otherwise_at": null
},
"launch": null,
"progress": {
"participants": 5,
"released": 0,
"skipped": 0,
"stale": 0
},
"counts": {
"draft": 3,
"submitted": 2,
"approved": 0,
"returned": 0,
"stale": 0,
"skipped": 0,
"released": 0
},
"worksheets": {
"total": 2,
"submitted": 1
},
"budgets": [
{
"currency": "EUR",
"eligible": 191000,
"budget": 5730,
"spent": 1500,
"remaining": 4230,
"over": false,
"used_pct": 26.2,
"promotion": {
"budget": 1910,
"spent": 0,
"remaining": 1910,
"over": false,
"used_pct": 0
},
"lump": {
"budget": 20000,
"spent": 2400,
"remaining": 17600,
"over": false,
"used_pct": 12
}
}
],
"release": {
"write": 0,
"no_change": 0,
"skip": 5,
"stale": 0,
"done": 0,
"lump_sums": 0
},
"letters": null,
"lump_sums": {
"count": 1,
"totals": [
{
"currency": "EUR",
"amount": 2400
}
],
"in_payroll": 0,
"by_hand": 0,
"paid": 0
},
"created_at": "2026-11-16T10:00:00.000Z",
"released_at": null
},
"preview": {
"people": 5,
"eligible": 5,
"excluded": {
"not_employed": 0,
"after_cutoff": 0,
"employment_type": 0
},
"flags": {
"no_pay": 1,
"no_band": 2,
"below_min": 1,
"above_max": 0,
"new_joiner": 0,
"other_currency": 0
},
"budgets": [
{
"currency": "EUR",
"eligible": 191000,
"budget": 5730,
"spent": 1500,
"remaining": 4230,
"over": false,
"used_pct": 26.2,
"promotion": {
"budget": 1910,
"spent": 0,
"remaining": 1910,
"over": false,
"used_pct": 0
},
"lump": {
"budget": 20000,
"spent": 2400,
"remaining": 17600,
"over": false,
"used_pct": 12
}
}
]
}
}
}Continue launching or releasing a salary review#
POST/v1/comp/cycles.stepWrite
Runs the next part (100 people) of a salary review that is launching or releasing; once released, with Documents on, sends the next letters to people's My documents (a few at a time). The cycle page calls it while open, and the sweep does it every few minutes otherwise. Nothing to do: returns the cycle as it is. 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_cycles_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
cycle_idstringrequired
Returns
cycleobjectrequired26 fields
idstringrequirednamestringrequiredstatusstringrequiredstagestring (enum)requiredOne of:
draft,launching,proposing,review,preview,releasing,released,cancelled.populationobjectrequired5 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.
eligibilityobjectrequired3 fields
cutoff_datestringrequiredemployment_typesstring[]requirednew_joiners"exclude" | "prorate"required
effective_datestringrequireddatesobjectrequired4 fields
propose_bystringrequiredreview_bystringrequiredmanager_preview_onstringrequiredrelease_onstringrequired
manager_view"percent" | "amounts"requiredstepsobjectrequired2 fields
upper_reviewbooleanrequiredA submitted worksheet goes to the manager's own manager before HR (D6).
final_sign_offbooleanrequiredThe release needs a final sign-off of the totals (D8).
sign_offobject | nullrequiredThe final sign-off: signed, or sent back to HR with a note; null: waiting (or not required).
3 fields
state"signed" | "sent_back"requiredatstringrequirednotestring | nullrequired
guidelineobjectrequired10 fields
versionintegerrequiredrating_levelsobject[]required2 fields
valuenumberrequiredlabelstringrequired
cr_boundsnumber[]requiredcellsobject[]required5 fields
rowstringrequiredcolstringrequiredminnumberrequiredtargetnumberrequiredmaxnumberrequired
rowsstring[]requiredcolsstring[]requiredbring_to_minbooleanrequiredlump_above_maxbooleanrequiredrounding"none" | numberrequiredchanged_onstring | nullrequired
poolsobjectrequired4 fields
merit_pctnumberrequiredoverridesobject[]required2 fields
unit_idstringrequiredmerit_pctnumberrequired
promotion_pctnumber | nullrequiredlump_sum_by_currencyobject | nullrequired
rating_cycle_idstring | nullrequiredno_change_lettersbooleanrequiredcriteriaobjectrequired2 fields
published_atstring | nullrequiredshared_otherwise_atstring | nullrequired
launchobject | nullrequired2 fields
doneintegerrequiredtotalintegerrequired
progressobjectrequired4 fields
participantsintegerrequiredreleasedintegerrequiredskippedintegerrequiredstaleintegerrequired
countsobjectrequired7 fields
draftintegerrequiredsubmittedintegerrequiredapprovedintegerrequiredreturnedintegerrequiredstaleintegerrequiredskippedintegerrequiredreleasedintegerrequired
worksheetsobjectrequired2 fields
totalintegerrequiredsubmittedintegerrequired
budgetsobject[]required9 fields
currencystringrequiredeligiblenumberrequiredbudgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequiredpromotionobject | nullrequiredThe promotion pool (raises whose reason is promotion_pending), when the cycle has one.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
lumpobject | nullrequiredThe lump-sum pool (one-off payments), when the cycle has one for this currency.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
releaseobjectrequired6 fields
writeintegerrequiredno_changeintegerrequiredskipintegerrequiredstaleintegerrequireddoneintegerrequiredlump_sumsintegerrequired
lump_sumsobject | nullrequiredLump sums approved (before the release) or released (after), with totals per currency; after the release, how many went to payroll, wait to be paid by hand, or were marked paid. Null: none.
5 fields
countintegerrequiredtotalsobject[]required2 fields
currencystringrequiredamountnumberrequired
in_payrollintegerrequiredby_handintegerrequiredpaidintegerrequired
lettersobject | nullrequiredWith Documents on at release: letters made as documents (total), already in people's My documents, still to send (waiting) and waiting for HR in Documents → Prepared (blocked: a value missing, on paper). Null: letters are in My workspace → Pay only.
4 fields
totalintegerrequiredin_documentsintegerrequiredwaitingintegerrequiredblockedintegerrequired
created_atstringrequiredreleased_atstring | nullrequired
handledintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/comp/cycles.step \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"cycle_id":"cy1"}'const res = await fetch('https://api.bizisy.com/v1/comp/cycles.step', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"cycle_id": "cy1"
}),
});
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/cycles.step",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"cycle_id": "cy1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"cycle": {
"id": "cy1",
"name": "Spring review",
"status": "open",
"stage": "proposing",
"population": {
"kind": "company"
},
"eligibility": {
"cutoff_date": "2026-10-01",
"employment_types": [],
"new_joiners": "exclude"
},
"effective_date": "2027-01-01",
"dates": {
"propose_by": "2026-11-27",
"review_by": "2026-12-04",
"manager_preview_on": "2026-12-11",
"release_on": "2026-12-15"
},
"manager_view": "percent",
"steps": {
"upper_review": false,
"final_sign_off": false
},
"sign_off": null,
"guideline": {
"version": 1,
"rating_levels": [
{
"value": 3,
"label": "Meets expectations"
}
],
"cr_bounds": [
0.9,
1,
1.1
],
"cells": [
{
"row": "r3",
"col": "c2",
"min": 2,
"target": 3,
"max": 4
}
],
"rows": [
"r3",
"none"
],
"cols": [
"c0",
"c1",
"c2",
"c3",
"nb"
],
"bring_to_min": true,
"lump_above_max": true,
"rounding": "none",
"changed_on": null
},
"pools": {
"merit_pct": 3,
"overrides": [],
"promotion_pct": 1,
"lump_sum_by_currency": {
"EUR": 20000
}
},
"rating_cycle_id": null,
"no_change_letters": true,
"criteria": {
"published_at": "2026-11-16T10:00:00.000Z",
"shared_otherwise_at": null
},
"launch": null,
"progress": {
"participants": 5,
"released": 0,
"skipped": 0,
"stale": 0
},
"counts": {
"draft": 3,
"submitted": 2,
"approved": 0,
"returned": 0,
"stale": 0,
"skipped": 0,
"released": 0
},
"worksheets": {
"total": 2,
"submitted": 1
},
"budgets": [
{
"currency": "EUR",
"eligible": 191000,
"budget": 5730,
"spent": 1500,
"remaining": 4230,
"over": false,
"used_pct": 26.2,
"promotion": {
"budget": 1910,
"spent": 0,
"remaining": 1910,
"over": false,
"used_pct": 0
},
"lump": {
"budget": 20000,
"spent": 2400,
"remaining": 17600,
"over": false,
"used_pct": 12
}
}
],
"release": {
"write": 0,
"no_change": 0,
"skip": 5,
"stale": 0,
"done": 0,
"lump_sums": 0
},
"letters": null,
"lump_sums": {
"count": 1,
"totals": [
{
"currency": "EUR",
"amount": 2400
}
],
"in_payroll": 0,
"by_hand": 0,
"paid": 0
},
"created_at": "2026-11-16T10:00:00.000Z",
"released_at": null
},
"handled": 100
}
}Cancel a salary review#
POST/v1/comp/cycles.cancelDestructive
Cancels a salary review before its release: worksheets close, nothing is written to anyone's pay and nobody is told. Its rows are kept (read-only) for HR. Not possible once releasing (changes after release go through a normal pay change). Owners, admins and HR, in the app only.
- Web app only
- Refused for API keys and connected apps. A salary review is cancelled in the app only.
- MCP tool
comp_cycles_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
cycle_idstringrequired
Returns
26 fields
idstringrequirednamestringrequiredstatusstringrequiredstagestring (enum)requiredOne of:
draft,launching,proposing,review,preview,releasing,released,cancelled.populationobjectrequired5 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.
eligibilityobjectrequired3 fields
cutoff_datestringrequiredemployment_typesstring[]requirednew_joiners"exclude" | "prorate"required
effective_datestringrequireddatesobjectrequired4 fields
propose_bystringrequiredreview_bystringrequiredmanager_preview_onstringrequiredrelease_onstringrequired
manager_view"percent" | "amounts"requiredstepsobjectrequired2 fields
upper_reviewbooleanrequiredA submitted worksheet goes to the manager's own manager before HR (D6).
final_sign_offbooleanrequiredThe release needs a final sign-off of the totals (D8).
sign_offobject | nullrequiredThe final sign-off: signed, or sent back to HR with a note; null: waiting (or not required).
3 fields
state"signed" | "sent_back"requiredatstringrequirednotestring | nullrequired
guidelineobjectrequired10 fields
versionintegerrequiredrating_levelsobject[]required2 fields
valuenumberrequiredlabelstringrequired
cr_boundsnumber[]requiredcellsobject[]required5 fields
rowstringrequiredcolstringrequiredminnumberrequiredtargetnumberrequiredmaxnumberrequired
rowsstring[]requiredcolsstring[]requiredbring_to_minbooleanrequiredlump_above_maxbooleanrequiredrounding"none" | numberrequiredchanged_onstring | nullrequired
poolsobjectrequired4 fields
merit_pctnumberrequiredoverridesobject[]required2 fields
unit_idstringrequiredmerit_pctnumberrequired
promotion_pctnumber | nullrequiredlump_sum_by_currencyobject | nullrequired
rating_cycle_idstring | nullrequiredno_change_lettersbooleanrequiredcriteriaobjectrequired2 fields
published_atstring | nullrequiredshared_otherwise_atstring | nullrequired
launchobject | nullrequired2 fields
doneintegerrequiredtotalintegerrequired
progressobjectrequired4 fields
participantsintegerrequiredreleasedintegerrequiredskippedintegerrequiredstaleintegerrequired
countsobjectrequired7 fields
draftintegerrequiredsubmittedintegerrequiredapprovedintegerrequiredreturnedintegerrequiredstaleintegerrequiredskippedintegerrequiredreleasedintegerrequired
worksheetsobjectrequired2 fields
totalintegerrequiredsubmittedintegerrequired
budgetsobject[]required9 fields
currencystringrequiredeligiblenumberrequiredbudgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequiredpromotionobject | nullrequiredThe promotion pool (raises whose reason is promotion_pending), when the cycle has one.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
lumpobject | nullrequiredThe lump-sum pool (one-off payments), when the cycle has one for this currency.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
releaseobjectrequired6 fields
writeintegerrequiredno_changeintegerrequiredskipintegerrequiredstaleintegerrequireddoneintegerrequiredlump_sumsintegerrequired
lump_sumsobject | nullrequiredLump sums approved (before the release) or released (after), with totals per currency; after the release, how many went to payroll, wait to be paid by hand, or were marked paid. Null: none.
5 fields
countintegerrequiredtotalsobject[]required2 fields
currencystringrequiredamountnumberrequired
in_payrollintegerrequiredby_handintegerrequiredpaidintegerrequired
lettersobject | nullrequiredWith Documents on at release: letters made as documents (total), already in people's My documents, still to send (waiting) and waiting for HR in Documents → Prepared (blocked: a value missing, on paper). Null: letters are in My workspace → Pay only.
4 fields
totalintegerrequiredin_documentsintegerrequiredwaitingintegerrequiredblockedintegerrequired
created_atstringrequiredreleased_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/comp/cycles.cancel \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"cycle_id":"cy1"}'const res = await fetch('https://api.bizisy.com/v1/comp/cycles.cancel', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"cycle_id": "cy1"
}),
});
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/cycles.cancel",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"cycle_id": "cy1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "cy1",
"name": "Spring review",
"status": "cancelled",
"stage": "cancelled",
"population": {
"kind": "company"
},
"eligibility": {
"cutoff_date": "2026-10-01",
"employment_types": [],
"new_joiners": "exclude"
},
"effective_date": "2027-01-01",
"dates": {
"propose_by": "2026-11-27",
"review_by": "2026-12-04",
"manager_preview_on": "2026-12-11",
"release_on": "2026-12-15"
},
"manager_view": "percent",
"steps": {
"upper_review": false,
"final_sign_off": false
},
"sign_off": null,
"guideline": {
"version": 1,
"rating_levels": [
{
"value": 3,
"label": "Meets expectations"
}
],
"cr_bounds": [
0.9,
1,
1.1
],
"cells": [
{
"row": "r3",
"col": "c2",
"min": 2,
"target": 3,
"max": 4
}
],
"rows": [
"r3",
"none"
],
"cols": [
"c0",
"c1",
"c2",
"c3",
"nb"
],
"bring_to_min": true,
"lump_above_max": true,
"rounding": "none",
"changed_on": null
},
"pools": {
"merit_pct": 3,
"overrides": [],
"promotion_pct": 1,
"lump_sum_by_currency": {
"EUR": 20000
}
},
"rating_cycle_id": null,
"no_change_letters": true,
"criteria": {
"published_at": "2026-11-16T10:00:00.000Z",
"shared_otherwise_at": null
},
"launch": null,
"progress": {
"participants": 5,
"released": 0,
"skipped": 0,
"stale": 0
},
"counts": {
"draft": 3,
"submitted": 2,
"approved": 0,
"returned": 0,
"stale": 0,
"skipped": 0,
"released": 0
},
"worksheets": {
"total": 2,
"submitted": 1
},
"budgets": [
{
"currency": "EUR",
"eligible": 191000,
"budget": 5730,
"spent": 1500,
"remaining": 4230,
"over": false,
"used_pct": 26.2,
"promotion": {
"budget": 1910,
"spent": 0,
"remaining": 1910,
"over": false,
"used_pct": 0
},
"lump": {
"budget": 20000,
"spent": 2400,
"remaining": 17600,
"over": false,
"used_pct": 12
}
}
],
"release": {
"write": 0,
"no_change": 0,
"skip": 5,
"stale": 0,
"done": 0,
"lump_sums": 0
},
"letters": null,
"lump_sums": {
"count": 1,
"totals": [
{
"currency": "EUR",
"amount": 2400
}
],
"in_payroll": 0,
"by_hand": 0,
"paid": 0
},
"created_at": "2026-11-16T10:00:00.000Z",
"released_at": null
}
}Release a salary review now#
POST/v1/comp/cycles.release_nowWrite
Releases a launched salary review now instead of on its release date: approved raises are written to pay from the effective date (re-checked: still employed with no termination recorded, pay unchanged since the snapshot — else back to HR as stale — and the approver may still decide), letters go to each person in Bizisy with an email that holds no amounts, and rows not approved are left out (reasons for HR only). Approved lump sums go to Payroll as a "Salary review lump sum" item in the pay period covering the effective date (once per row, also when a release is retried); without Payroll, or when Payroll refuses one (no pay schedule for the person), HR pays it by hand and marks it paid (comp_review_mark_paid). Letters show the lump sum; emails never hold amounts. 100 people now, the rest within minutes. The dry run lists what would be written, sent without change, skipped and stale, and the lump sums. 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 salary review is released in the app only: it writes pay and sends letters.
- MCP tool
comp_cycles_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
cycle_idstringrequired
Returns
cycleobjectrequired26 fields
idstringrequirednamestringrequiredstatusstringrequiredstagestring (enum)requiredOne of:
draft,launching,proposing,review,preview,releasing,released,cancelled.populationobjectrequired5 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.
eligibilityobjectrequired3 fields
cutoff_datestringrequiredemployment_typesstring[]requirednew_joiners"exclude" | "prorate"required
effective_datestringrequireddatesobjectrequired4 fields
propose_bystringrequiredreview_bystringrequiredmanager_preview_onstringrequiredrelease_onstringrequired
manager_view"percent" | "amounts"requiredstepsobjectrequired2 fields
upper_reviewbooleanrequiredA submitted worksheet goes to the manager's own manager before HR (D6).
final_sign_offbooleanrequiredThe release needs a final sign-off of the totals (D8).
sign_offobject | nullrequiredThe final sign-off: signed, or sent back to HR with a note; null: waiting (or not required).
3 fields
state"signed" | "sent_back"requiredatstringrequirednotestring | nullrequired
guidelineobjectrequired10 fields
versionintegerrequiredrating_levelsobject[]required2 fields
valuenumberrequiredlabelstringrequired
cr_boundsnumber[]requiredcellsobject[]required5 fields
rowstringrequiredcolstringrequiredminnumberrequiredtargetnumberrequiredmaxnumberrequired
rowsstring[]requiredcolsstring[]requiredbring_to_minbooleanrequiredlump_above_maxbooleanrequiredrounding"none" | numberrequiredchanged_onstring | nullrequired
poolsobjectrequired4 fields
merit_pctnumberrequiredoverridesobject[]required2 fields
unit_idstringrequiredmerit_pctnumberrequired
promotion_pctnumber | nullrequiredlump_sum_by_currencyobject | nullrequired
rating_cycle_idstring | nullrequiredno_change_lettersbooleanrequiredcriteriaobjectrequired2 fields
published_atstring | nullrequiredshared_otherwise_atstring | nullrequired
launchobject | nullrequired2 fields
doneintegerrequiredtotalintegerrequired
progressobjectrequired4 fields
participantsintegerrequiredreleasedintegerrequiredskippedintegerrequiredstaleintegerrequired
countsobjectrequired7 fields
draftintegerrequiredsubmittedintegerrequiredapprovedintegerrequiredreturnedintegerrequiredstaleintegerrequiredskippedintegerrequiredreleasedintegerrequired
worksheetsobjectrequired2 fields
totalintegerrequiredsubmittedintegerrequired
budgetsobject[]required9 fields
currencystringrequiredeligiblenumberrequiredbudgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequiredpromotionobject | nullrequiredThe promotion pool (raises whose reason is promotion_pending), when the cycle has one.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
lumpobject | nullrequiredThe lump-sum pool (one-off payments), when the cycle has one for this currency.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
releaseobjectrequired6 fields
writeintegerrequiredno_changeintegerrequiredskipintegerrequiredstaleintegerrequireddoneintegerrequiredlump_sumsintegerrequired
lump_sumsobject | nullrequiredLump sums approved (before the release) or released (after), with totals per currency; after the release, how many went to payroll, wait to be paid by hand, or were marked paid. Null: none.
5 fields
countintegerrequiredtotalsobject[]required2 fields
currencystringrequiredamountnumberrequired
in_payrollintegerrequiredby_handintegerrequiredpaidintegerrequired
lettersobject | nullrequiredWith Documents on at release: letters made as documents (total), already in people's My documents, still to send (waiting) and waiting for HR in Documents → Prepared (blocked: a value missing, on paper). Null: letters are in My workspace → Pay only.
4 fields
totalintegerrequiredin_documentsintegerrequiredwaitingintegerrequiredblockedintegerrequired
created_atstringrequiredreleased_atstring | nullrequired
planobjectrequired6 fields
writeintegerrequiredno_changeintegerrequiredskipintegerrequiredstaleintegerrequireddoneintegerrequiredlump_sumsintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/comp/cycles.release_now \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"cycle_id":"cy1"}'const res = await fetch('https://api.bizisy.com/v1/comp/cycles.release_now', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"cycle_id": "cy1"
}),
});
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/cycles.release_now",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"cycle_id": "cy1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"cycle": {
"id": "cy1",
"name": "Spring review",
"status": "released",
"stage": "released",
"population": {
"kind": "company"
},
"eligibility": {
"cutoff_date": "2026-10-01",
"employment_types": [],
"new_joiners": "exclude"
},
"effective_date": "2027-01-01",
"dates": {
"propose_by": "2026-11-27",
"review_by": "2026-12-04",
"manager_preview_on": "2026-12-11",
"release_on": "2026-12-15"
},
"manager_view": "percent",
"steps": {
"upper_review": false,
"final_sign_off": false
},
"sign_off": null,
"guideline": {
"version": 1,
"rating_levels": [
{
"value": 3,
"label": "Meets expectations"
}
],
"cr_bounds": [
0.9,
1,
1.1
],
"cells": [
{
"row": "r3",
"col": "c2",
"min": 2,
"target": 3,
"max": 4
}
],
"rows": [
"r3",
"none"
],
"cols": [
"c0",
"c1",
"c2",
"c3",
"nb"
],
"bring_to_min": true,
"lump_above_max": true,
"rounding": "none",
"changed_on": null
},
"pools": {
"merit_pct": 3,
"overrides": [],
"promotion_pct": 1,
"lump_sum_by_currency": {
"EUR": 20000
}
},
"rating_cycle_id": null,
"no_change_letters": true,
"criteria": {
"published_at": "2026-11-16T10:00:00.000Z",
"shared_otherwise_at": null
},
"launch": null,
"progress": {
"participants": 5,
"released": 0,
"skipped": 0,
"stale": 0
},
"counts": {
"draft": 3,
"submitted": 2,
"approved": 0,
"returned": 0,
"stale": 0,
"skipped": 0,
"released": 0
},
"worksheets": {
"total": 2,
"submitted": 1
},
"budgets": [
{
"currency": "EUR",
"eligible": 191000,
"budget": 5730,
"spent": 1500,
"remaining": 4230,
"over": false,
"used_pct": 26.2,
"promotion": {
"budget": 1910,
"spent": 0,
"remaining": 1910,
"over": false,
"used_pct": 0
},
"lump": {
"budget": 20000,
"spent": 2400,
"remaining": 17600,
"over": false,
"used_pct": 12
}
}
],
"release": {
"write": 0,
"no_change": 0,
"skip": 5,
"stale": 0,
"done": 0,
"lump_sums": 0
},
"letters": null,
"lump_sums": {
"count": 1,
"totals": [
{
"currency": "EUR",
"amount": 2400
}
],
"in_payroll": 0,
"by_hand": 0,
"paid": 0
},
"created_at": "2026-11-16T10:00:00.000Z",
"released_at": null
},
"plan": {
"write": 2,
"no_change": 1,
"skip": 2,
"stale": 0,
"done": 0,
"lump_sums": 1
}
}
}Salary review payroll file#
POST/v1/comp/cycles.exportRead
A CSV of a salary review for payroll systems Bizisy doesn't push to: one line per approved or released row with a change (person id, name, effective date, old and new base pay, currency, period, % change, one-off lump sum and, after the release, how it is paid: payroll, by_hand — to pay by hand — or paid). Its base total equals the pay rows the release writes; its lump-sum total equals the payroll items written plus the lump sums paid by hand. At most 20,000 lines. 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. The payroll file holds pay: exported in the app only.
- MCP tool
comp_cycles_exporton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
cycle_idstringrequired
Returns
filenamestringrequiredcsvstringrequiredrowsintegerrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/comp/cycles.export \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"cycle_id":"cy1"}'const res = await fetch('https://api.bizisy.com/v1/comp/cycles.export', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"cycle_id": "cy1"
}),
});
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/cycles.export",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"cycle_id": "cy1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"filename": "salary-review-2027-01-01.csv",
"csv": "person_id,name,effective_date,old_base,new_base,currency,period,pct,lump_sum,lump_sum_payment\r\np3,Dina Silva,2027-01-01,50000.00,51500.00,EUR,year,3.00,1000.00,payroll\r\n",
"rows": 1
}
}A salary review's final sign-off#
POST/v1/comp/signoff.getRead
The final sign-off of a salary review (when the cycle has one): totals per currency and per team against the budget (annual cost of the approved raises, lump sums, rows not approved yet), the equity check (pay categories flagged after the raises), and whether you may sign it off. Owners and a role with Pay at Approve over everyone in the review sign; HR reads it. 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. The final sign-off holds pay totals: in the app only.
- MCP tool
comp_signoff_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
cycle_idstringrequired
Returns
11 fields
cycleobjectrequired5 fields
idstringrequirednamestringrequiredstagestringrequiredeffective_datestringrequiredrelease_onstringrequired
requiredbooleanrequiredThe review needs its final sign-off before the release (steps.final_sign_off).
state"waiting" | "signed" | "sent_back"requiredbystring | nullrequiredWho signed off or sent it back.
atstring | nullrequirednotestring | nullrequiredcan_signbooleanrequiredwhy_notstring | nullrequiredtotalsobject[]required8 fields
currencystringrequiredeligiblenumberrequiredbudgetnumberrequiredMerit and promotion budgets, annual.
approvednumberrequiredAnnual cost of the approved raises.
lump_sumsnumberrequiredApproved one-off lump sums.
lump_budgetnumber | nullrequiredapproved_rowsintegerrequiredwaitingintegerrequiredRows with pay not approved yet (left out at the release unless approved).
teamsobject[]required6 fields
namestringrequiredcurrencystringrequiredbudgetnumberrequiredapprovednumberrequiredlump_sumsnumberrequiredoverbooleanrequired
equityobjectrequiredPay categories flagged after the approved raises (a gap of 5 % or more, or widened by a point), checked and hidden (too few women or men).
3 fields
flaggedintegerrequiredcheckedintegerrequiredhiddenintegerrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/comp/signoff.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"cycle_id":"cy1"}'const res = await fetch('https://api.bizisy.com/v1/comp/signoff.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"cycle_id": "cy1"
}),
});
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/signoff.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"cycle_id": "cy1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"cycle": {
"id": "cy1",
"name": "Spring review",
"stage": "review",
"effective_date": "2027-01-01",
"release_on": "2026-12-15"
},
"required": true,
"state": "waiting",
"by": null,
"at": null,
"note": null,
"can_sign": true,
"why_not": null,
"totals": [
{
"currency": "EUR",
"eligible": 191000,
"budget": 5730,
"approved": 5503.2,
"lump_sums": 0,
"lump_budget": null,
"approved_rows": 2,
"waiting": 2
}
],
"teams": [
{
"name": "Bea Silva",
"currency": "EUR",
"budget": 2580,
"approved": 5503.2,
"lump_sums": 0,
"over": true
}
],
"equity": {
"flagged": 0,
"checked": 1,
"hidden": 0
}
}
}Sign off a salary review#
POST/v1/comp/cycles.sign_offWrite
Signs off the totals of a salary review (the final sign-off): the release may then go ahead. Owners, or a role with Pay at Approve over everyone in it; never with a raise of your own in it. A later change to an approved row, the budget or the guideline needs a new sign-off. 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. Salary reviews are signed off in the app only.
- MCP tool
comp_cycles_sign_offon 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
cycle_idstringrequirednotestringUp to 500 characters.
Returns
11 fields
cycleobjectrequired5 fields
idstringrequirednamestringrequiredstagestringrequiredeffective_datestringrequiredrelease_onstringrequired
requiredbooleanrequiredThe review needs its final sign-off before the release (steps.final_sign_off).
state"waiting" | "signed" | "sent_back"requiredbystring | nullrequiredWho signed off or sent it back.
atstring | nullrequirednotestring | nullrequiredcan_signbooleanrequiredwhy_notstring | nullrequiredtotalsobject[]required8 fields
currencystringrequiredeligiblenumberrequiredbudgetnumberrequiredMerit and promotion budgets, annual.
approvednumberrequiredAnnual cost of the approved raises.
lump_sumsnumberrequiredApproved one-off lump sums.
lump_budgetnumber | nullrequiredapproved_rowsintegerrequiredwaitingintegerrequiredRows with pay not approved yet (left out at the release unless approved).
teamsobject[]required6 fields
namestringrequiredcurrencystringrequiredbudgetnumberrequiredapprovednumberrequiredlump_sumsnumberrequiredoverbooleanrequired
equityobjectrequiredPay categories flagged after the approved raises (a gap of 5 % or more, or widened by a point), checked and hidden (too few women or men).
3 fields
flaggedintegerrequiredcheckedintegerrequiredhiddenintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/comp/cycles.sign_off \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"cycle_id":"cy1","note":"Within the year’s plan"}'const res = await fetch('https://api.bizisy.com/v1/comp/cycles.sign_off', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"cycle_id": "cy1",
"note": "Within the year’s plan"
}),
});
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/cycles.sign_off",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"cycle_id": "cy1",
"note": "Within the year’s plan",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"cycle": {
"id": "cy1",
"name": "Spring review",
"stage": "review",
"effective_date": "2027-01-01",
"release_on": "2026-12-15"
},
"required": true,
"state": "signed",
"by": "Ana Costa",
"at": "2026-12-05T10:00:00.000Z",
"note": "Within the year’s plan",
"can_sign": true,
"why_not": null,
"totals": [
{
"currency": "EUR",
"eligible": 191000,
"budget": 5730,
"approved": 5503.2,
"lump_sums": 0,
"lump_budget": null,
"approved_rows": 2,
"waiting": 2
}
],
"teams": [
{
"name": "Bea Silva",
"currency": "EUR",
"budget": 2580,
"approved": 5503.2,
"lump_sums": 0,
"over": true
}
],
"equity": {
"flagged": 0,
"checked": 1,
"hidden": 0
}
}
}Send a salary review back to HR#
POST/v1/comp/cycles.send_backWrite
Sends a salary review back to HR from the final sign-off, with a note (what to change); the release waits for a new sign-off. Owners, or a role with Pay at Approve over everyone in it. 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. Salary reviews are sent back in the app only.
- MCP tool
comp_cycles_send_backon 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
cycle_idstringrequirednotestringrequired1–500 characters.
Returns
11 fields
cycleobjectrequired5 fields
idstringrequirednamestringrequiredstagestringrequiredeffective_datestringrequiredrelease_onstringrequired
requiredbooleanrequiredThe review needs its final sign-off before the release (steps.final_sign_off).
state"waiting" | "signed" | "sent_back"requiredbystring | nullrequiredWho signed off or sent it back.
atstring | nullrequirednotestring | nullrequiredcan_signbooleanrequiredwhy_notstring | nullrequiredtotalsobject[]required8 fields
currencystringrequiredeligiblenumberrequiredbudgetnumberrequiredMerit and promotion budgets, annual.
approvednumberrequiredAnnual cost of the approved raises.
lump_sumsnumberrequiredApproved one-off lump sums.
lump_budgetnumber | nullrequiredapproved_rowsintegerrequiredwaitingintegerrequiredRows with pay not approved yet (left out at the release unless approved).
teamsobject[]required6 fields
namestringrequiredcurrencystringrequiredbudgetnumberrequiredapprovednumberrequiredlump_sumsnumberrequiredoverbooleanrequired
equityobjectrequiredPay categories flagged after the approved raises (a gap of 5 % or more, or widened by a point), checked and hidden (too few women or men).
3 fields
flaggedintegerrequiredcheckedintegerrequiredhiddenintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/comp/cycles.send_back \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"cycle_id":"cy1","note":"Engineering is over its budget"}'const res = await fetch('https://api.bizisy.com/v1/comp/cycles.send_back', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"cycle_id": "cy1",
"note": "Engineering is over its budget"
}),
});
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/cycles.send_back",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"cycle_id": "cy1",
"note": "Engineering is over its budget",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"cycle": {
"id": "cy1",
"name": "Spring review",
"stage": "review",
"effective_date": "2027-01-01",
"release_on": "2026-12-15"
},
"required": true,
"state": "sent_back",
"by": "Ana Costa",
"at": "2026-12-05T10:00:00.000Z",
"note": "Engineering is over its budget",
"can_sign": true,
"why_not": null,
"totals": [
{
"currency": "EUR",
"eligible": 191000,
"budget": 5730,
"approved": 5503.2,
"lump_sums": 0,
"lump_budget": null,
"approved_rows": 2,
"waiting": 2
}
],
"teams": [
{
"name": "Bea Silva",
"currency": "EUR",
"budget": 2580,
"approved": 5503.2,
"lump_sums": 0,
"over": true
}
],
"equity": {
"flagged": 0,
"checked": 1,
"hidden": 0
}
}
}Review salary review proposals#
POST/v1/comp/review.getRead
HR's review of a salary review: every row (except your own) with the person, team, proposer, base pay, compa-ratio and band, rating, the guideline range, the proposal (% and new amount, reason, the manager's comment), state, flags (no pay, no band, below or above the band, new joiner, termination recorded, protected_leave: maternity, paternity, parental or adoption leave in the review period, never which), protected_floor and below_floor (people on protected leave get the raise as if at work: below it needs HR's objective_reason) and whether you may approve it; each worksheet with its state and budget 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); this read of stored data keeps working while it is off.
- Web app only
- Refused for API keys and connected apps. HR reviews proposals in the app only.
- MCP tool
comp_review_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
cycle_idstringrequired
Returns
cycleobjectrequired5 fields
idstringrequirednamestringrequiredstagestringrequiredeffective_datestringrequiredrounding"none" | numberrequired
rowsobject[]required26 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
titlestring | nullrequiredteamstring | nullrequiredproposerobject | nullrequired2 fields
idstringrequirednamestringrequired
baseobject | nullrequired3 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
annualnumber | nullrequiredcompa_rationumber | nullrequiredrange_posnumber | nullrequiredbandobject | nullrequired5 fields
minnumberrequiredmaxnumberrequiredmidnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
ratingnumber | nullrequiredproratenumberrequiredguidelineobjectrequired5 fields
minnumberrequiredtargetnumberrequiredmaxnumberrequiredto_minbooleanrequiredlumpbooleanrequired
proposalobject | nullrequired9 fields
pctnumberrequirednew_amountnumberrequiredreason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"requiredreason_textstring | nullrequiredcommentstring | nullrequiredatstringrequiredlump_sum_pctnumber | nullrequiredlump_sumnumber | nullrequiredThe one-off lump sum in the base's currency (from lump_sum_pct of the annual base).
promotionbooleanrequiredThe raise draws on the promotion budget (reason promotion_pending, the cycle has one).
lump_okbooleanrequiredpayoutobject | nullrequired6 fields
amountnumberrequiredcurrencystringrequiredstate"in_payroll" | "by_hand" | "paid"requiredwhy"payroll_off" | "refused" | "removed"requiredWhy by hand: Payroll off, Payroll refused it (no pay schedule for the person, item archived, period full), or HR removed the item in payroll.
periodobject | nullrequired2 fields
startstringrequiredendstringrequired
paid_atstring | nullrequired
outsidebooleanrequiredstatestring (enum)requiredOne of:
draft,submitted,approved,returned,stale,skipped,released.flagsstring (enum)[]requiredOne of:
no_pay,no_band,below_min,above_max,other_currency,new_joiner,leaving,pay_scheduled,protected_leave.protected_floornumber | nullrequiredprotected_leave rows: the lowest raise % as if at work (null for others).
below_floorbooleanrequiredThe proposal is below protected_floor without an objective reason: it can't be approved.
objective_reasonobject | nullrequiredHR's objective reason for a raise below protected_floor (comp_review_edit objective_reason).
2 fields
textstringrequiredatstringrequired
skipped_reason"hr" | "not_approved" | "not_employed" | "leaving" | "no_pay"requireddecisionsobject[]required3 fields
bystringrequiredatstringrequirednotestring | nullrequired
can_decidebooleanrequiredwhy_notstring | nullrequired
worksheetsobject[]required9 fields
proposerobjectrequired2 fields
idstringrequirednamestringrequired
state"draft" | "submitted" | "returned" | "upper"requiredupper: submitted, waiting for the manager's own manager (the upper-manager step) before HR.
submitted_atstring | nullrequiredupperobject | nullrequiredWho checks it before HR (the upper-manager step), while it waits for them.
2 fields
idstringrequirednamestringrequired
over_budget_reasonstring | nullrequiredreturn_notestring | nullrequiredrowsintegerrequiredpromotionsintegerrequiredRaises this manager put on the promotion budget (reason promotion_pending, the cycle has one): check each is a real promotion.
budgetsobject[]required9 fields
currencystringrequiredeligiblenumberrequiredbudgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequiredpromotionobject | nullrequiredThe promotion pool (raises whose reason is promotion_pending), when the cycle has one.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
lumpobject | nullrequiredThe lump-sum pool (one-off payments), when the cycle has one for this currency.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
own_hiddenbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/comp/review.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"cycle_id":"cy1"}'const res = await fetch('https://api.bizisy.com/v1/comp/review.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"cycle_id": "cy1"
}),
});
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/review.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"cycle_id": "cy1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"cycle": {
"id": "cy1",
"name": "Spring review",
"stage": "review",
"effective_date": "2027-01-01",
"rounding": "none"
},
"rows": [
{
"id": "cy1:p3",
"person": {
"id": "p3",
"name": "Dina Silva"
},
"title": "Engineer",
"team": "Engineering",
"proposer": {
"id": "p2",
"name": "Bea Silva"
},
"base": {
"amount": 50000,
"currency": "EUR",
"period": "year"
},
"annual": 50000,
"compa_ratio": 1,
"range_pos": 50,
"band": {
"min": 40000,
"max": 60000,
"mid": 50000,
"currency": "EUR",
"period": "year"
},
"rating": 3,
"prorate": 1,
"guideline": {
"min": 2,
"target": 3,
"max": 4,
"to_min": false,
"lump": false
},
"proposal": {
"pct": 3,
"new_amount": 51500,
"reason": null,
"reason_text": null,
"comment": null,
"at": "2026-11-20T10:00:00.000Z",
"lump_sum_pct": 2,
"lump_sum": 1000,
"promotion": false
},
"lump_ok": true,
"payout": null,
"outside": false,
"state": "submitted",
"flags": [],
"skipped_reason": null,
"protected_floor": null,
"below_floor": false,
"objective_reason": null,
"decisions": [],
"can_decide": true,
"why_not": null
}
],
"worksheets": [
{
"proposer": {
"id": "p2",
"name": "Bea Silva"
},
"state": "submitted",
"upper": null,
"submitted_at": "2026-11-20T10:00:00.000Z",
"over_budget_reason": null,
"return_note": null,
"rows": 2,
"promotions": 0,
"budgets": [
{
"currency": "EUR",
"eligible": 191000,
"budget": 5730,
"spent": 1500,
"remaining": 4230,
"over": false,
"used_pct": 26.2,
"promotion": {
"budget": 1910,
"spent": 0,
"remaining": 1910,
"over": false,
"used_pct": 0
},
"lump": {
"budget": 20000,
"spent": 2400,
"remaining": 17600,
"over": false,
"used_pct": 12
}
}
]
}
],
"own_hidden": false
}
}Approve salary review proposals#
POST/v1/comp/review.decideWrite
Approves submitted rows (approve) or takes approval back (reopen), each with its raise and its one-off lump sum, if any. Each row is checked on its own against the pay approval rules: owners, admins and HR; an HR member's row only owners and admins; an owner's row only another owner; never your own row, never a row you proposed. Rows you can't decide are refused with the reason, the others are decided. Approved rows are held until the release: nothing is written to pay before. A dry run says which would be decided and refused. 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. Proposals are approved in the app only.
- MCP tool
comp_review_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
cycle_idstringrequiredrow_idsstring[]required1–500 items.
decision"approve" | "reopen"Default
"approve".notestringUp to 500 characters.
Returns
reviewobjectrequired4 fields
cycleobjectrequired5 fields
idstringrequirednamestringrequiredstagestringrequiredeffective_datestringrequiredrounding"none" | numberrequired
rowsobject[]required26 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
titlestring | nullrequiredteamstring | nullrequiredproposerobject | nullrequired2 fields
idstringrequirednamestringrequired
baseobject | nullrequired3 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
annualnumber | nullrequiredcompa_rationumber | nullrequiredrange_posnumber | nullrequiredbandobject | nullrequired5 fields
minnumberrequiredmaxnumberrequiredmidnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
ratingnumber | nullrequiredproratenumberrequiredguidelineobjectrequired5 fields
minnumberrequiredtargetnumberrequiredmaxnumberrequiredto_minbooleanrequiredlumpbooleanrequired
proposalobject | nullrequired9 fields
pctnumberrequirednew_amountnumberrequiredreason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"requiredreason_textstring | nullrequiredcommentstring | nullrequiredatstringrequiredlump_sum_pctnumber | nullrequiredlump_sumnumber | nullrequiredThe one-off lump sum in the base's currency (from lump_sum_pct of the annual base).
promotionbooleanrequiredThe raise draws on the promotion budget (reason promotion_pending, the cycle has one).
lump_okbooleanrequiredpayoutobject | nullrequired6 fields
amountnumberrequiredcurrencystringrequiredstate"in_payroll" | "by_hand" | "paid"requiredwhy"payroll_off" | "refused" | "removed"requiredWhy by hand: Payroll off, Payroll refused it (no pay schedule for the person, item archived, period full), or HR removed the item in payroll.
periodobject | nullrequired2 fields
startstringrequiredendstringrequired
paid_atstring | nullrequired
outsidebooleanrequiredstatestring (enum)requiredOne of:
draft,submitted,approved,returned,stale,skipped,released.flagsstring (enum)[]requiredOne of:
no_pay,no_band,below_min,above_max,other_currency,new_joiner,leaving,pay_scheduled,protected_leave.protected_floornumber | nullrequiredprotected_leave rows: the lowest raise % as if at work (null for others).
below_floorbooleanrequiredThe proposal is below protected_floor without an objective reason: it can't be approved.
objective_reasonobject | nullrequiredHR's objective reason for a raise below protected_floor (comp_review_edit objective_reason).
2 fields
textstringrequiredatstringrequired
skipped_reason"hr" | "not_approved" | "not_employed" | "leaving" | "no_pay"requireddecisionsobject[]required3 fields
bystringrequiredatstringrequirednotestring | nullrequired
can_decidebooleanrequiredwhy_notstring | nullrequired
worksheetsobject[]required9 fields
proposerobjectrequired2 fields
idstringrequirednamestringrequired
state"draft" | "submitted" | "returned" | "upper"requiredupper: submitted, waiting for the manager's own manager (the upper-manager step) before HR.
submitted_atstring | nullrequiredupperobject | nullrequiredWho checks it before HR (the upper-manager step), while it waits for them.
2 fields
idstringrequirednamestringrequired
over_budget_reasonstring | nullrequiredreturn_notestring | nullrequiredrowsintegerrequiredpromotionsintegerrequiredRaises this manager put on the promotion budget (reason promotion_pending, the cycle has one): check each is a real promotion.
budgetsobject[]required9 fields
currencystringrequiredeligiblenumberrequiredbudgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequiredpromotionobject | nullrequiredThe promotion pool (raises whose reason is promotion_pending), when the cycle has one.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
lumpobject | nullrequiredThe lump-sum pool (one-off payments), when the cycle has one for this currency.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
own_hiddenbooleanrequired
donestring[]requiredrefusedobject[]required2 fields
idstringrequiredreasonstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/comp/review.decide \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"cycle_id": "cy1",
"row_ids": [
"cy1:p3"
],
"decision": "reopen",
"note": "Check market data"
}'const res = await fetch('https://api.bizisy.com/v1/comp/review.decide', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"cycle_id": "cy1",
"row_ids": [
"cy1:p3"
],
"decision": "reopen",
"note": "Check market data"
}),
});
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/review.decide",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"cycle_id": "cy1",
"row_ids": [
"cy1:p3",
],
"decision": "reopen",
"note": "Check market data",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"review": {
"cycle": {
"id": "cy1",
"name": "Spring review",
"stage": "review",
"effective_date": "2027-01-01",
"rounding": "none"
},
"rows": [
{
"id": "cy1:p3",
"person": {
"id": "p3",
"name": "Dina Silva"
},
"title": "Engineer",
"team": "Engineering",
"proposer": {
"id": "p2",
"name": "Bea Silva"
},
"base": {
"amount": 50000,
"currency": "EUR",
"period": "year"
},
"annual": 50000,
"compa_ratio": 1,
"range_pos": 50,
"band": {
"min": 40000,
"max": 60000,
"mid": 50000,
"currency": "EUR",
"period": "year"
},
"rating": 3,
"prorate": 1,
"guideline": {
"min": 2,
"target": 3,
"max": 4,
"to_min": false,
"lump": false
},
"proposal": {
"pct": 3,
"new_amount": 51500,
"reason": null,
"reason_text": null,
"comment": null,
"at": "2026-11-20T10:00:00.000Z",
"lump_sum_pct": 2,
"lump_sum": 1000,
"promotion": false
},
"lump_ok": true,
"payout": null,
"outside": false,
"state": "submitted",
"flags": [],
"skipped_reason": null,
"protected_floor": null,
"below_floor": false,
"objective_reason": null,
"decisions": [],
"can_decide": true,
"why_not": null
}
],
"worksheets": [
{
"proposer": {
"id": "p2",
"name": "Bea Silva"
},
"state": "submitted",
"upper": null,
"submitted_at": "2026-11-20T10:00:00.000Z",
"over_budget_reason": null,
"return_note": null,
"rows": 2,
"promotions": 0,
"budgets": [
{
"currency": "EUR",
"eligible": 191000,
"budget": 5730,
"spent": 1500,
"remaining": 4230,
"over": false,
"used_pct": 26.2,
"promotion": {
"budget": 1910,
"spent": 0,
"remaining": 1910,
"over": false,
"used_pct": 0
},
"lump": {
"budget": 20000,
"spent": 2400,
"remaining": 17600,
"over": false,
"used_pct": 12
}
}
]
}
],
"own_hidden": false
},
"done": [
"cy1:p3"
],
"refused": []
}
}Change a salary review proposal#
POST/v1/comp/review.editWrite
HR changes or makes the proposal of one row: the increase in % (0 = no change), a one-off lump sum as % of the annual base (lump_sum_pct; only when the cycle has a lump-sum budget for the person's currency; null removes it, left out keeps it; the result shows its amount), a reason when outside the guideline (other: at least 20 characters; promotion_pending draws on the promotion budget when there is one) and a note. For a row on protected leave (flag protected_leave) a raise below protected_floor needs objective_reason: an objective reason unrelated to the leave (EU Dir. 2006/54 art. 15). Same rules as approving it (never your own row; an HR member's row only owners and admins; an owner's only another owner). The row is then submitted and needs approval; the manager sees HR's change only from the preview day. 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. HR changes proposals in the app only.
- MCP tool
comp_review_editon 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
cycle_idstringrequiredrow_idstringrequiredpctnumberrequiredFrom 0 to 100.
lump_sum_pctnumber | nullFrom 0 to 100.
reason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"reason_textstring | nullUp to 500 characters.
notestringUp to 500 characters.
objective_reasonstring | nullProtected leave only: the objective reason, unrelated to the leave, for a raise below the protected floor (20–500 characters; null removes it). Kept for HR and in the person's data export after release.
20–500 characters.
Returns
reviewobjectrequired4 fields
cycleobjectrequired5 fields
idstringrequirednamestringrequiredstagestringrequiredeffective_datestringrequiredrounding"none" | numberrequired
rowsobject[]required26 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
titlestring | nullrequiredteamstring | nullrequiredproposerobject | nullrequired2 fields
idstringrequirednamestringrequired
baseobject | nullrequired3 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
annualnumber | nullrequiredcompa_rationumber | nullrequiredrange_posnumber | nullrequiredbandobject | nullrequired5 fields
minnumberrequiredmaxnumberrequiredmidnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
ratingnumber | nullrequiredproratenumberrequiredguidelineobjectrequired5 fields
minnumberrequiredtargetnumberrequiredmaxnumberrequiredto_minbooleanrequiredlumpbooleanrequired
proposalobject | nullrequired9 fields
pctnumberrequirednew_amountnumberrequiredreason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"requiredreason_textstring | nullrequiredcommentstring | nullrequiredatstringrequiredlump_sum_pctnumber | nullrequiredlump_sumnumber | nullrequiredThe one-off lump sum in the base's currency (from lump_sum_pct of the annual base).
promotionbooleanrequiredThe raise draws on the promotion budget (reason promotion_pending, the cycle has one).
lump_okbooleanrequiredpayoutobject | nullrequired6 fields
amountnumberrequiredcurrencystringrequiredstate"in_payroll" | "by_hand" | "paid"requiredwhy"payroll_off" | "refused" | "removed"requiredWhy by hand: Payroll off, Payroll refused it (no pay schedule for the person, item archived, period full), or HR removed the item in payroll.
periodobject | nullrequired2 fields
startstringrequiredendstringrequired
paid_atstring | nullrequired
outsidebooleanrequiredstatestring (enum)requiredOne of:
draft,submitted,approved,returned,stale,skipped,released.flagsstring (enum)[]requiredOne of:
no_pay,no_band,below_min,above_max,other_currency,new_joiner,leaving,pay_scheduled,protected_leave.protected_floornumber | nullrequiredprotected_leave rows: the lowest raise % as if at work (null for others).
below_floorbooleanrequiredThe proposal is below protected_floor without an objective reason: it can't be approved.
objective_reasonobject | nullrequiredHR's objective reason for a raise below protected_floor (comp_review_edit objective_reason).
2 fields
textstringrequiredatstringrequired
skipped_reason"hr" | "not_approved" | "not_employed" | "leaving" | "no_pay"requireddecisionsobject[]required3 fields
bystringrequiredatstringrequirednotestring | nullrequired
can_decidebooleanrequiredwhy_notstring | nullrequired
worksheetsobject[]required9 fields
proposerobjectrequired2 fields
idstringrequirednamestringrequired
state"draft" | "submitted" | "returned" | "upper"requiredupper: submitted, waiting for the manager's own manager (the upper-manager step) before HR.
submitted_atstring | nullrequiredupperobject | nullrequiredWho checks it before HR (the upper-manager step), while it waits for them.
2 fields
idstringrequirednamestringrequired
over_budget_reasonstring | nullrequiredreturn_notestring | nullrequiredrowsintegerrequiredpromotionsintegerrequiredRaises this manager put on the promotion budget (reason promotion_pending, the cycle has one): check each is a real promotion.
budgetsobject[]required9 fields
currencystringrequiredeligiblenumberrequiredbudgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequiredpromotionobject | nullrequiredThe promotion pool (raises whose reason is promotion_pending), when the cycle has one.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
lumpobject | nullrequiredThe lump-sum pool (one-off payments), when the cycle has one for this currency.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
own_hiddenbooleanrequired
donestring[]requiredrefusedobject[]required2 fields
idstringrequiredreasonstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/comp/review.edit \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"cycle_id":"cy1","row_id":"cy1:p3","pct":8,"reason":"market"}'const res = await fetch('https://api.bizisy.com/v1/comp/review.edit', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"cycle_id": "cy1",
"row_id": "cy1:p3",
"pct": 8,
"reason": "market"
}),
});
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/review.edit",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"cycle_id": "cy1",
"row_id": "cy1:p3",
"pct": 8,
"reason": "market",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"review": {
"cycle": {
"id": "cy1",
"name": "Spring review",
"stage": "review",
"effective_date": "2027-01-01",
"rounding": "none"
},
"rows": [
{
"id": "cy1:p3",
"person": {
"id": "p3",
"name": "Dina Silva"
},
"title": "Engineer",
"team": "Engineering",
"proposer": {
"id": "p2",
"name": "Bea Silva"
},
"base": {
"amount": 50000,
"currency": "EUR",
"period": "year"
},
"annual": 50000,
"compa_ratio": 1,
"range_pos": 50,
"band": {
"min": 40000,
"max": 60000,
"mid": 50000,
"currency": "EUR",
"period": "year"
},
"rating": 3,
"prorate": 1,
"guideline": {
"min": 2,
"target": 3,
"max": 4,
"to_min": false,
"lump": false
},
"proposal": {
"pct": 3,
"new_amount": 51500,
"reason": null,
"reason_text": null,
"comment": null,
"at": "2026-11-20T10:00:00.000Z",
"lump_sum_pct": 2,
"lump_sum": 1000,
"promotion": false
},
"lump_ok": true,
"payout": null,
"outside": false,
"state": "submitted",
"flags": [],
"skipped_reason": null,
"protected_floor": null,
"below_floor": false,
"objective_reason": null,
"decisions": [],
"can_decide": true,
"why_not": null
}
],
"worksheets": [
{
"proposer": {
"id": "p2",
"name": "Bea Silva"
},
"state": "submitted",
"upper": null,
"submitted_at": "2026-11-20T10:00:00.000Z",
"over_budget_reason": null,
"return_note": null,
"rows": 2,
"promotions": 0,
"budgets": [
{
"currency": "EUR",
"eligible": 191000,
"budget": 5730,
"spent": 1500,
"remaining": 4230,
"over": false,
"used_pct": 26.2,
"promotion": {
"budget": 1910,
"spent": 0,
"remaining": 1910,
"over": false,
"used_pct": 0
},
"lump": {
"budget": 20000,
"spent": 2400,
"remaining": 17600,
"over": false,
"used_pct": 12
}
}
]
}
],
"own_hidden": false
},
"done": [
"cy1:p3"
],
"refused": []
}
}Send a worksheet back to its manager#
POST/v1/comp/review.returnWrite
Sends a manager's submitted worksheet back with a note: its rows (approved ones too) go back to them to change and submit again, and they get an email (no amounts). 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. Worksheets are sent back in the app only.
- MCP tool
comp_review_returnon 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
cycle_idstringrequiredproposer_person_idstringrequirednotestringrequired1–500 characters.
Returns
reviewobjectrequired4 fields
cycleobjectrequired5 fields
idstringrequirednamestringrequiredstagestringrequiredeffective_datestringrequiredrounding"none" | numberrequired
rowsobject[]required26 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
titlestring | nullrequiredteamstring | nullrequiredproposerobject | nullrequired2 fields
idstringrequirednamestringrequired
baseobject | nullrequired3 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
annualnumber | nullrequiredcompa_rationumber | nullrequiredrange_posnumber | nullrequiredbandobject | nullrequired5 fields
minnumberrequiredmaxnumberrequiredmidnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
ratingnumber | nullrequiredproratenumberrequiredguidelineobjectrequired5 fields
minnumberrequiredtargetnumberrequiredmaxnumberrequiredto_minbooleanrequiredlumpbooleanrequired
proposalobject | nullrequired9 fields
pctnumberrequirednew_amountnumberrequiredreason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"requiredreason_textstring | nullrequiredcommentstring | nullrequiredatstringrequiredlump_sum_pctnumber | nullrequiredlump_sumnumber | nullrequiredThe one-off lump sum in the base's currency (from lump_sum_pct of the annual base).
promotionbooleanrequiredThe raise draws on the promotion budget (reason promotion_pending, the cycle has one).
lump_okbooleanrequiredpayoutobject | nullrequired6 fields
amountnumberrequiredcurrencystringrequiredstate"in_payroll" | "by_hand" | "paid"requiredwhy"payroll_off" | "refused" | "removed"requiredWhy by hand: Payroll off, Payroll refused it (no pay schedule for the person, item archived, period full), or HR removed the item in payroll.
periodobject | nullrequired2 fields
startstringrequiredendstringrequired
paid_atstring | nullrequired
outsidebooleanrequiredstatestring (enum)requiredOne of:
draft,submitted,approved,returned,stale,skipped,released.flagsstring (enum)[]requiredOne of:
no_pay,no_band,below_min,above_max,other_currency,new_joiner,leaving,pay_scheduled,protected_leave.protected_floornumber | nullrequiredprotected_leave rows: the lowest raise % as if at work (null for others).
below_floorbooleanrequiredThe proposal is below protected_floor without an objective reason: it can't be approved.
objective_reasonobject | nullrequiredHR's objective reason for a raise below protected_floor (comp_review_edit objective_reason).
2 fields
textstringrequiredatstringrequired
skipped_reason"hr" | "not_approved" | "not_employed" | "leaving" | "no_pay"requireddecisionsobject[]required3 fields
bystringrequiredatstringrequirednotestring | nullrequired
can_decidebooleanrequiredwhy_notstring | nullrequired
worksheetsobject[]required9 fields
proposerobjectrequired2 fields
idstringrequirednamestringrequired
state"draft" | "submitted" | "returned" | "upper"requiredupper: submitted, waiting for the manager's own manager (the upper-manager step) before HR.
submitted_atstring | nullrequiredupperobject | nullrequiredWho checks it before HR (the upper-manager step), while it waits for them.
2 fields
idstringrequirednamestringrequired
over_budget_reasonstring | nullrequiredreturn_notestring | nullrequiredrowsintegerrequiredpromotionsintegerrequiredRaises this manager put on the promotion budget (reason promotion_pending, the cycle has one): check each is a real promotion.
budgetsobject[]required9 fields
currencystringrequiredeligiblenumberrequiredbudgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequiredpromotionobject | nullrequiredThe promotion pool (raises whose reason is promotion_pending), when the cycle has one.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
lumpobject | nullrequiredThe lump-sum pool (one-off payments), when the cycle has one for this currency.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
own_hiddenbooleanrequired
donestring[]requiredrefusedobject[]required2 fields
idstringrequiredreasonstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/comp/review.return \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"cycle_id": "cy1",
"proposer_person_id": "p2",
"note": "Please give Dina a reason"
}'const res = await fetch('https://api.bizisy.com/v1/comp/review.return', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"cycle_id": "cy1",
"proposer_person_id": "p2",
"note": "Please give Dina a reason"
}),
});
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/review.return",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"cycle_id": "cy1",
"proposer_person_id": "p2",
"note": "Please give Dina a reason",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"review": {
"cycle": {
"id": "cy1",
"name": "Spring review",
"stage": "review",
"effective_date": "2027-01-01",
"rounding": "none"
},
"rows": [
{
"id": "cy1:p3",
"person": {
"id": "p3",
"name": "Dina Silva"
},
"title": "Engineer",
"team": "Engineering",
"proposer": {
"id": "p2",
"name": "Bea Silva"
},
"base": {
"amount": 50000,
"currency": "EUR",
"period": "year"
},
"annual": 50000,
"compa_ratio": 1,
"range_pos": 50,
"band": {
"min": 40000,
"max": 60000,
"mid": 50000,
"currency": "EUR",
"period": "year"
},
"rating": 3,
"prorate": 1,
"guideline": {
"min": 2,
"target": 3,
"max": 4,
"to_min": false,
"lump": false
},
"proposal": {
"pct": 3,
"new_amount": 51500,
"reason": null,
"reason_text": null,
"comment": null,
"at": "2026-11-20T10:00:00.000Z",
"lump_sum_pct": 2,
"lump_sum": 1000,
"promotion": false
},
"lump_ok": true,
"payout": null,
"outside": false,
"state": "submitted",
"flags": [],
"skipped_reason": null,
"protected_floor": null,
"below_floor": false,
"objective_reason": null,
"decisions": [],
"can_decide": true,
"why_not": null
}
],
"worksheets": [
{
"proposer": {
"id": "p2",
"name": "Bea Silva"
},
"state": "submitted",
"upper": null,
"submitted_at": "2026-11-20T10:00:00.000Z",
"over_budget_reason": null,
"return_note": null,
"rows": 2,
"promotions": 0,
"budgets": [
{
"currency": "EUR",
"eligible": 191000,
"budget": 5730,
"spent": 1500,
"remaining": 4230,
"over": false,
"used_pct": 26.2,
"promotion": {
"budget": 1910,
"spent": 0,
"remaining": 1910,
"over": false,
"used_pct": 0
},
"lump": {
"budget": 20000,
"spent": 2400,
"remaining": 17600,
"over": false,
"used_pct": 12
}
}
]
}
],
"own_hidden": false
},
"done": [
"cy1:p3"
],
"refused": []
}
}Refresh salary review rows#
POST/v1/comp/review.refreshWrite
Takes a new pay snapshot for rows whose pay changed since launch (stale), or whose job changed: base, band, compa-ratio and flags are read again and the proposal's % kept (its new amount and its lump sum's amount recomputed from the new base). A refreshed row with a proposal is submitted again and needs approval. 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. Rows are refreshed in the app only.
- MCP tool
comp_review_refreshon 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
cycle_idstringrequiredrow_idsstring[]required1–100 items.
Returns
reviewobjectrequired4 fields
cycleobjectrequired5 fields
idstringrequirednamestringrequiredstagestringrequiredeffective_datestringrequiredrounding"none" | numberrequired
rowsobject[]required26 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
titlestring | nullrequiredteamstring | nullrequiredproposerobject | nullrequired2 fields
idstringrequirednamestringrequired
baseobject | nullrequired3 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
annualnumber | nullrequiredcompa_rationumber | nullrequiredrange_posnumber | nullrequiredbandobject | nullrequired5 fields
minnumberrequiredmaxnumberrequiredmidnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
ratingnumber | nullrequiredproratenumberrequiredguidelineobjectrequired5 fields
minnumberrequiredtargetnumberrequiredmaxnumberrequiredto_minbooleanrequiredlumpbooleanrequired
proposalobject | nullrequired9 fields
pctnumberrequirednew_amountnumberrequiredreason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"requiredreason_textstring | nullrequiredcommentstring | nullrequiredatstringrequiredlump_sum_pctnumber | nullrequiredlump_sumnumber | nullrequiredThe one-off lump sum in the base's currency (from lump_sum_pct of the annual base).
promotionbooleanrequiredThe raise draws on the promotion budget (reason promotion_pending, the cycle has one).
lump_okbooleanrequiredpayoutobject | nullrequired6 fields
amountnumberrequiredcurrencystringrequiredstate"in_payroll" | "by_hand" | "paid"requiredwhy"payroll_off" | "refused" | "removed"requiredWhy by hand: Payroll off, Payroll refused it (no pay schedule for the person, item archived, period full), or HR removed the item in payroll.
periodobject | nullrequired2 fields
startstringrequiredendstringrequired
paid_atstring | nullrequired
outsidebooleanrequiredstatestring (enum)requiredOne of:
draft,submitted,approved,returned,stale,skipped,released.flagsstring (enum)[]requiredOne of:
no_pay,no_band,below_min,above_max,other_currency,new_joiner,leaving,pay_scheduled,protected_leave.protected_floornumber | nullrequiredprotected_leave rows: the lowest raise % as if at work (null for others).
below_floorbooleanrequiredThe proposal is below protected_floor without an objective reason: it can't be approved.
objective_reasonobject | nullrequiredHR's objective reason for a raise below protected_floor (comp_review_edit objective_reason).
2 fields
textstringrequiredatstringrequired
skipped_reason"hr" | "not_approved" | "not_employed" | "leaving" | "no_pay"requireddecisionsobject[]required3 fields
bystringrequiredatstringrequirednotestring | nullrequired
can_decidebooleanrequiredwhy_notstring | nullrequired
worksheetsobject[]required9 fields
proposerobjectrequired2 fields
idstringrequirednamestringrequired
state"draft" | "submitted" | "returned" | "upper"requiredupper: submitted, waiting for the manager's own manager (the upper-manager step) before HR.
submitted_atstring | nullrequiredupperobject | nullrequiredWho checks it before HR (the upper-manager step), while it waits for them.
2 fields
idstringrequirednamestringrequired
over_budget_reasonstring | nullrequiredreturn_notestring | nullrequiredrowsintegerrequiredpromotionsintegerrequiredRaises this manager put on the promotion budget (reason promotion_pending, the cycle has one): check each is a real promotion.
budgetsobject[]required9 fields
currencystringrequiredeligiblenumberrequiredbudgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequiredpromotionobject | nullrequiredThe promotion pool (raises whose reason is promotion_pending), when the cycle has one.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
lumpobject | nullrequiredThe lump-sum pool (one-off payments), when the cycle has one for this currency.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
own_hiddenbooleanrequired
donestring[]requiredrefusedobject[]required2 fields
idstringrequiredreasonstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/comp/review.refresh \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"cycle_id":"cy1","row_ids":["cy1:p3"]}'const res = await fetch('https://api.bizisy.com/v1/comp/review.refresh', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"cycle_id": "cy1",
"row_ids": [
"cy1: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/review.refresh",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"cycle_id": "cy1",
"row_ids": [
"cy1:p3",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"review": {
"cycle": {
"id": "cy1",
"name": "Spring review",
"stage": "review",
"effective_date": "2027-01-01",
"rounding": "none"
},
"rows": [
{
"id": "cy1:p3",
"person": {
"id": "p3",
"name": "Dina Silva"
},
"title": "Engineer",
"team": "Engineering",
"proposer": {
"id": "p2",
"name": "Bea Silva"
},
"base": {
"amount": 50000,
"currency": "EUR",
"period": "year"
},
"annual": 50000,
"compa_ratio": 1,
"range_pos": 50,
"band": {
"min": 40000,
"max": 60000,
"mid": 50000,
"currency": "EUR",
"period": "year"
},
"rating": 3,
"prorate": 1,
"guideline": {
"min": 2,
"target": 3,
"max": 4,
"to_min": false,
"lump": false
},
"proposal": {
"pct": 3,
"new_amount": 51500,
"reason": null,
"reason_text": null,
"comment": null,
"at": "2026-11-20T10:00:00.000Z",
"lump_sum_pct": 2,
"lump_sum": 1000,
"promotion": false
},
"lump_ok": true,
"payout": null,
"outside": false,
"state": "submitted",
"flags": [],
"skipped_reason": null,
"protected_floor": null,
"below_floor": false,
"objective_reason": null,
"decisions": [],
"can_decide": true,
"why_not": null
}
],
"worksheets": [
{
"proposer": {
"id": "p2",
"name": "Bea Silva"
},
"state": "submitted",
"upper": null,
"submitted_at": "2026-11-20T10:00:00.000Z",
"over_budget_reason": null,
"return_note": null,
"rows": 2,
"promotions": 0,
"budgets": [
{
"currency": "EUR",
"eligible": 191000,
"budget": 5730,
"spent": 1500,
"remaining": 4230,
"over": false,
"used_pct": 26.2,
"promotion": {
"budget": 1910,
"spent": 0,
"remaining": 1910,
"over": false,
"used_pct": 0
},
"lump": {
"budget": 20000,
"spent": 2400,
"remaining": 17600,
"over": false,
"used_pct": 12
}
}
]
}
],
"own_hidden": false
},
"done": [
"cy1:p3"
],
"refused": []
}
}Leave rows out of a salary review#
POST/v1/comp/review.skipWrite
Leaves rows out of the release (include: false) or brings them back (include: true). The reason is for HR only; the manager sees "not included" from the preview day. 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. Rows are skipped in the app only.
- MCP tool
comp_review_skipon 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
cycle_idstringrequiredrow_idsstring[]required1–500 items.
includebooleanDefault
false.
Returns
reviewobjectrequired4 fields
cycleobjectrequired5 fields
idstringrequirednamestringrequiredstagestringrequiredeffective_datestringrequiredrounding"none" | numberrequired
rowsobject[]required26 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
titlestring | nullrequiredteamstring | nullrequiredproposerobject | nullrequired2 fields
idstringrequirednamestringrequired
baseobject | nullrequired3 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
annualnumber | nullrequiredcompa_rationumber | nullrequiredrange_posnumber | nullrequiredbandobject | nullrequired5 fields
minnumberrequiredmaxnumberrequiredmidnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
ratingnumber | nullrequiredproratenumberrequiredguidelineobjectrequired5 fields
minnumberrequiredtargetnumberrequiredmaxnumberrequiredto_minbooleanrequiredlumpbooleanrequired
proposalobject | nullrequired9 fields
pctnumberrequirednew_amountnumberrequiredreason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"requiredreason_textstring | nullrequiredcommentstring | nullrequiredatstringrequiredlump_sum_pctnumber | nullrequiredlump_sumnumber | nullrequiredThe one-off lump sum in the base's currency (from lump_sum_pct of the annual base).
promotionbooleanrequiredThe raise draws on the promotion budget (reason promotion_pending, the cycle has one).
lump_okbooleanrequiredpayoutobject | nullrequired6 fields
amountnumberrequiredcurrencystringrequiredstate"in_payroll" | "by_hand" | "paid"requiredwhy"payroll_off" | "refused" | "removed"requiredWhy by hand: Payroll off, Payroll refused it (no pay schedule for the person, item archived, period full), or HR removed the item in payroll.
periodobject | nullrequired2 fields
startstringrequiredendstringrequired
paid_atstring | nullrequired
outsidebooleanrequiredstatestring (enum)requiredOne of:
draft,submitted,approved,returned,stale,skipped,released.flagsstring (enum)[]requiredOne of:
no_pay,no_band,below_min,above_max,other_currency,new_joiner,leaving,pay_scheduled,protected_leave.protected_floornumber | nullrequiredprotected_leave rows: the lowest raise % as if at work (null for others).
below_floorbooleanrequiredThe proposal is below protected_floor without an objective reason: it can't be approved.
objective_reasonobject | nullrequiredHR's objective reason for a raise below protected_floor (comp_review_edit objective_reason).
2 fields
textstringrequiredatstringrequired
skipped_reason"hr" | "not_approved" | "not_employed" | "leaving" | "no_pay"requireddecisionsobject[]required3 fields
bystringrequiredatstringrequirednotestring | nullrequired
can_decidebooleanrequiredwhy_notstring | nullrequired
worksheetsobject[]required9 fields
proposerobjectrequired2 fields
idstringrequirednamestringrequired
state"draft" | "submitted" | "returned" | "upper"requiredupper: submitted, waiting for the manager's own manager (the upper-manager step) before HR.
submitted_atstring | nullrequiredupperobject | nullrequiredWho checks it before HR (the upper-manager step), while it waits for them.
2 fields
idstringrequirednamestringrequired
over_budget_reasonstring | nullrequiredreturn_notestring | nullrequiredrowsintegerrequiredpromotionsintegerrequiredRaises this manager put on the promotion budget (reason promotion_pending, the cycle has one): check each is a real promotion.
budgetsobject[]required9 fields
currencystringrequiredeligiblenumberrequiredbudgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequiredpromotionobject | nullrequiredThe promotion pool (raises whose reason is promotion_pending), when the cycle has one.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
lumpobject | nullrequiredThe lump-sum pool (one-off payments), when the cycle has one for this currency.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
own_hiddenbooleanrequired
donestring[]requiredrefusedobject[]required2 fields
idstringrequiredreasonstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/comp/review.skip \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"cycle_id":"cy1","row_ids":["cy1:p3"],"include":true}'const res = await fetch('https://api.bizisy.com/v1/comp/review.skip', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"cycle_id": "cy1",
"row_ids": [
"cy1:p3"
],
"include": 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/review.skip",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"cycle_id": "cy1",
"row_ids": [
"cy1:p3",
],
"include": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"review": {
"cycle": {
"id": "cy1",
"name": "Spring review",
"stage": "review",
"effective_date": "2027-01-01",
"rounding": "none"
},
"rows": [
{
"id": "cy1:p3",
"person": {
"id": "p3",
"name": "Dina Silva"
},
"title": "Engineer",
"team": "Engineering",
"proposer": {
"id": "p2",
"name": "Bea Silva"
},
"base": {
"amount": 50000,
"currency": "EUR",
"period": "year"
},
"annual": 50000,
"compa_ratio": 1,
"range_pos": 50,
"band": {
"min": 40000,
"max": 60000,
"mid": 50000,
"currency": "EUR",
"period": "year"
},
"rating": 3,
"prorate": 1,
"guideline": {
"min": 2,
"target": 3,
"max": 4,
"to_min": false,
"lump": false
},
"proposal": {
"pct": 3,
"new_amount": 51500,
"reason": null,
"reason_text": null,
"comment": null,
"at": "2026-11-20T10:00:00.000Z",
"lump_sum_pct": 2,
"lump_sum": 1000,
"promotion": false
},
"lump_ok": true,
"payout": null,
"outside": false,
"state": "submitted",
"flags": [],
"skipped_reason": null,
"protected_floor": null,
"below_floor": false,
"objective_reason": null,
"decisions": [],
"can_decide": true,
"why_not": null
}
],
"worksheets": [
{
"proposer": {
"id": "p2",
"name": "Bea Silva"
},
"state": "submitted",
"upper": null,
"submitted_at": "2026-11-20T10:00:00.000Z",
"over_budget_reason": null,
"return_note": null,
"rows": 2,
"promotions": 0,
"budgets": [
{
"currency": "EUR",
"eligible": 191000,
"budget": 5730,
"spent": 1500,
"remaining": 4230,
"over": false,
"used_pct": 26.2,
"promotion": {
"budget": 1910,
"spent": 0,
"remaining": 1910,
"over": false,
"used_pct": 0
},
"lump": {
"budget": 20000,
"spent": 2400,
"remaining": 17600,
"over": false,
"used_pct": 12
}
}
]
}
],
"own_hidden": false
},
"done": [
"cy1:p3"
],
"refused": []
}
}Equity check of a salary review#
POST/v1/comp/review.equityRead
The pay-equity check before approval (EU Pay Transparency Directive arts. 9, 10): per pay category, the mean and median gap between women and men on hourly base pay before the review and after its proposals (submitted, approved or released), only for categories with enough women and men (min_group; the others are counted in hidden). One-off lump sums are pay too (art. 3(1)(a)): they are not mixed into the base gap (they are not base pay and are paid once) but measured as their own variable-pay gap (variable_after). A category is flagged at 5 % or more after the review on base or on lump sums, or when the base gap widens by a point or more, with the rows in it and their recorded reasons. 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 equity check is read in the app only.
- MCP tool
comp_review_equityon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
cycle_idstringrequired
Returns
cycle_idstringrequiredmin_groupintegerrequiredhiddenintegerrequiredcategoriesobject[]required9 fields
idstringrequirednamestringrequiredwomenintegerrequiredmenintegerrequiredbeforeobjectrequired2 fields
meannumber | nullrequiredmediannumber | nullrequired
afterobjectrequired2 fields
meannumber | nullrequiredmediannumber | nullrequired
flaggedbooleanrequiredvariable_afterobject | nullrequiredThe gap on the review's one-off lump sums (variable pay, Directive art. 3(1)(a) and 9), when any are proposed in the category.
2 fields
meannumber | nullrequiredmediannumber | nullrequired
rowsobject[]required5 fields
idstringrequirednamestringrequiredpctnumberrequiredlump_sum_pctnumber | nullrequiredreason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"required
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/comp/review.equity \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"cycle_id":"cy1"}'const res = await fetch('https://api.bizisy.com/v1/comp/review.equity', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"cycle_id": "cy1"
}),
});
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/review.equity",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"cycle_id": "cy1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"cycle_id": "cy1",
"min_group": 3,
"hidden": 1,
"categories": [
{
"id": "pc1",
"name": "Engineering",
"women": 3,
"men": 3,
"before": {
"mean": 0,
"median": 0
},
"after": {
"mean": 7.1,
"median": 10.7
},
"flagged": true,
"variable_after": null,
"rows": [
{
"id": "cy1:p4",
"name": "Lukas Weber",
"pct": 12,
"lump_sum_pct": null,
"reason": "market"
}
]
}
]
}
}Mark salary review lump sums paid#
POST/v1/comp/review.mark_paidWrite
After the release: marks released lump sums HR paid by hand as paid (payout by_hand: Payroll off, Payroll refused it, or the item was removed in payroll). Lump sums in payroll are paid with their pay period. Each row follows the pay approval rules (never your own; an HR member's only owners and admins; an owner's only another owner); the others are refused with the reason. 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. Lump sums are marked paid in the app only.
- MCP tool
comp_review_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
cycle_idstringrequiredrow_idsstring[]required1–500 items.
Returns
reviewobjectrequired4 fields
cycleobjectrequired5 fields
idstringrequirednamestringrequiredstagestringrequiredeffective_datestringrequiredrounding"none" | numberrequired
rowsobject[]required26 fields
idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
titlestring | nullrequiredteamstring | nullrequiredproposerobject | nullrequired2 fields
idstringrequirednamestringrequired
baseobject | nullrequired3 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
annualnumber | nullrequiredcompa_rationumber | nullrequiredrange_posnumber | nullrequiredbandobject | nullrequired5 fields
minnumberrequiredmaxnumberrequiredmidnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
ratingnumber | nullrequiredproratenumberrequiredguidelineobjectrequired5 fields
minnumberrequiredtargetnumberrequiredmaxnumberrequiredto_minbooleanrequiredlumpbooleanrequired
proposalobject | nullrequired9 fields
pctnumberrequirednew_amountnumberrequiredreason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"requiredreason_textstring | nullrequiredcommentstring | nullrequiredatstringrequiredlump_sum_pctnumber | nullrequiredlump_sumnumber | nullrequiredThe one-off lump sum in the base's currency (from lump_sum_pct of the annual base).
promotionbooleanrequiredThe raise draws on the promotion budget (reason promotion_pending, the cycle has one).
lump_okbooleanrequiredpayoutobject | nullrequired6 fields
amountnumberrequiredcurrencystringrequiredstate"in_payroll" | "by_hand" | "paid"requiredwhy"payroll_off" | "refused" | "removed"requiredWhy by hand: Payroll off, Payroll refused it (no pay schedule for the person, item archived, period full), or HR removed the item in payroll.
periodobject | nullrequired2 fields
startstringrequiredendstringrequired
paid_atstring | nullrequired
outsidebooleanrequiredstatestring (enum)requiredOne of:
draft,submitted,approved,returned,stale,skipped,released.flagsstring (enum)[]requiredOne of:
no_pay,no_band,below_min,above_max,other_currency,new_joiner,leaving,pay_scheduled,protected_leave.protected_floornumber | nullrequiredprotected_leave rows: the lowest raise % as if at work (null for others).
below_floorbooleanrequiredThe proposal is below protected_floor without an objective reason: it can't be approved.
objective_reasonobject | nullrequiredHR's objective reason for a raise below protected_floor (comp_review_edit objective_reason).
2 fields
textstringrequiredatstringrequired
skipped_reason"hr" | "not_approved" | "not_employed" | "leaving" | "no_pay"requireddecisionsobject[]required3 fields
bystringrequiredatstringrequirednotestring | nullrequired
can_decidebooleanrequiredwhy_notstring | nullrequired
worksheetsobject[]required9 fields
proposerobjectrequired2 fields
idstringrequirednamestringrequired
state"draft" | "submitted" | "returned" | "upper"requiredupper: submitted, waiting for the manager's own manager (the upper-manager step) before HR.
submitted_atstring | nullrequiredupperobject | nullrequiredWho checks it before HR (the upper-manager step), while it waits for them.
2 fields
idstringrequirednamestringrequired
over_budget_reasonstring | nullrequiredreturn_notestring | nullrequiredrowsintegerrequiredpromotionsintegerrequiredRaises this manager put on the promotion budget (reason promotion_pending, the cycle has one): check each is a real promotion.
budgetsobject[]required9 fields
currencystringrequiredeligiblenumberrequiredbudgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequiredpromotionobject | nullrequiredThe promotion pool (raises whose reason is promotion_pending), when the cycle has one.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
lumpobject | nullrequiredThe lump-sum pool (one-off payments), when the cycle has one for this currency.
5 fields
budgetnumberrequiredspentnumberrequiredremainingnumberrequiredoverbooleanrequiredused_pctnumberrequired
own_hiddenbooleanrequired
donestring[]requiredrefusedobject[]required2 fields
idstringrequiredreasonstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/comp/review.mark_paid \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"cycle_id":"cy1","row_ids":["cy1:p3"]}'const res = await fetch('https://api.bizisy.com/v1/comp/review.mark_paid', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"cycle_id": "cy1",
"row_ids": [
"cy1: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/review.mark_paid",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"cycle_id": "cy1",
"row_ids": [
"cy1:p3",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"review": {
"cycle": {
"id": "cy1",
"name": "Spring review",
"stage": "review",
"effective_date": "2027-01-01",
"rounding": "none"
},
"rows": [
{
"id": "cy1:p3",
"person": {
"id": "p3",
"name": "Dina Silva"
},
"title": "Engineer",
"team": "Engineering",
"proposer": {
"id": "p2",
"name": "Bea Silva"
},
"base": {
"amount": 50000,
"currency": "EUR",
"period": "year"
},
"annual": 50000,
"compa_ratio": 1,
"range_pos": 50,
"band": {
"min": 40000,
"max": 60000,
"mid": 50000,
"currency": "EUR",
"period": "year"
},
"rating": 3,
"prorate": 1,
"guideline": {
"min": 2,
"target": 3,
"max": 4,
"to_min": false,
"lump": false
},
"proposal": {
"pct": 3,
"new_amount": 51500,
"reason": null,
"reason_text": null,
"comment": null,
"at": "2026-11-20T10:00:00.000Z",
"lump_sum_pct": 2,
"lump_sum": 1000,
"promotion": false
},
"lump_ok": true,
"payout": null,
"outside": false,
"state": "submitted",
"flags": [],
"skipped_reason": null,
"protected_floor": null,
"below_floor": false,
"objective_reason": null,
"decisions": [],
"can_decide": true,
"why_not": null
}
],
"worksheets": [
{
"proposer": {
"id": "p2",
"name": "Bea Silva"
},
"state": "submitted",
"upper": null,
"submitted_at": "2026-11-20T10:00:00.000Z",
"over_budget_reason": null,
"return_note": null,
"rows": 2,
"promotions": 0,
"budgets": [
{
"currency": "EUR",
"eligible": 191000,
"budget": 5730,
"spent": 1500,
"remaining": 4230,
"over": false,
"used_pct": 26.2,
"promotion": {
"budget": 1910,
"spent": 0,
"remaining": 1910,
"over": false,
"used_pct": 0
},
"lump": {
"budget": 20000,
"spent": 2400,
"remaining": 17600,
"over": false,
"used_pct": 12
}
}
]
}
],
"own_hidden": false
},
"done": [
"cy1:p3"
],
"refused": []
}
}Check ratings and raises by sex#
POST/v1/comp/review.rating_checkWrite
Before a salary review is released (cycle_id): how the ratings feeding the merit matrix and the proposed raises (submitted, approved or released) are spread between women and men: share per rating, mean rating and gap, top and bottom ratings, mean raise % per rating and the raise gap at equal rating. Flags (a reason to look, not proof of bias): a women-to-men ratio outside 0.8–1.25, a mean rating gap of 5 % of the scale's range or more, a raise gap of 0.5 points or more. Hidden with fewer than 5 women or men. Uses sex recorded for equal-pay reporting; totals only. Owners, admins and HR, in the app only; never managers; each run is recorded in Activity; nothing is stored. 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. Ratings and raises by sex are checked in the app only.
- MCP tool
comp_review_rating_checkon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
cycle_idstringrequired
Returns
9 fields
cycle_idstringrequiredrating_cycle_idstring | nullrequiredThe review cycle whose ratings feed the matrix: its own check (talent_cycles_sex_check) adds potential and calibration moves.
levelsobject[]required2 fields
valueintegerrequiredlabelstringrequired
recordedobjectrequired3 fields
womenintegerrequiredmenintegerrequirednot_includedintegerrequired
min_groupintegerrequiredsuppressedbooleanrequiredratingobject | nullrequired7 fields
levelsobject[]required3 fields
valueintegerrequiredwomen_pctnumberrequiredmen_pctnumberrequired
women_meannumberrequiredmen_meannumberrequiredgap_pointsnumberrequiredgap_pct_of_rangenumberrequiredtopobjectrequired3 fields
women_pctnumberrequiredmen_pctnumberrequiredrationumber | nullrequired
bottomobjectrequired3 fields
women_pctnumberrequiredmen_pctnumberrequiredrationumber | nullrequired
raiseobject | nullrequired2 fields
levelsobject[]required3 fields
valueinteger | nullrequiredwomen_meannumber | nullrequiredmen_meannumber | nullrequired
gap_ppnumber | nullrequiredMen's mean raise − women's at the same rating, weighted by people (percentage points); flagged from 0.5.
flagsstring (enum)[]requiredOne of:
rating_gap,top_rating,bottom_rating,high_potential,rating_up,rating_down,potential_up,potential_down,raise_gap.
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/comp/review.rating_check \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"cycle_id":"cy1"}'const res = await fetch('https://api.bizisy.com/v1/comp/review.rating_check', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"cycle_id": "cy1"
}),
});
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/review.rating_check",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"cycle_id": "cy1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"cycle_id": "cy1",
"rating_cycle_id": "tc1",
"levels": [
{
"value": 1,
"label": "Well below"
},
{
"value": 2,
"label": "Below"
},
{
"value": 3,
"label": "Meets"
},
{
"value": 4,
"label": "Exceeds"
},
{
"value": 5,
"label": "Outstanding"
}
],
"recorded": {
"women": 12,
"men": 14,
"not_included": 2
},
"min_group": 5,
"suppressed": false,
"rating": {
"levels": [
{
"value": 1,
"women_pct": 0,
"men_pct": 0
},
{
"value": 2,
"women_pct": 16.7,
"men_pct": 7.1
},
{
"value": 3,
"women_pct": 58.3,
"men_pct": 50
},
{
"value": 4,
"women_pct": 25,
"men_pct": 35.7
},
{
"value": 5,
"women_pct": 0,
"men_pct": 7.1
}
],
"women_mean": 3.08,
"men_mean": 3.43,
"gap_points": 0.35,
"gap_pct_of_range": 8.8,
"top": {
"women_pct": 25,
"men_pct": 42.9,
"ratio": 0.583
},
"bottom": {
"women_pct": 16.7,
"men_pct": 7.1,
"ratio": null
}
},
"raise": {
"levels": [
{
"value": 3,
"women_mean": 2.8,
"men_mean": 3.1
},
{
"value": 4,
"women_mean": null,
"men_mean": null
}
],
"gap_pp": 0.3
},
"flags": [
"rating_gap",
"top_rating"
]
}
}Something missing or wrong on this page? Write to hello@bizisy.com.