Skip to content

API reference

My salary review

A manager's worksheet (proposals in %, never salaries), the team leads' worksheets their own manager checks before HR, a person's letters once released, and the criteria published to staff (in the app, except the criteria).

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

How pay progresses#

POST/v1/comp/me.criteriaRead

The criteria of salary reviews HR published to staff (EU Pay Transparency Directive art. 6): per cycle, its name and effective date, the merit matrix (rating levels × compa-ratio bands, each a min–max % range), the merit pool and any promotion pool as a % of base pay (never amounts), whether one-off lump sums are part of it, rounding and the reasons a proposal outside the guideline needs. Cycles published and not yet released (drafts too, once published), or released in the last year. For everyone at the company; an API key or AI app acting for you can read it too. 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
Me key owner admin hr member
MCP tool
comp_me_criteria on My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • itemsobject[]required
    8 fields
    • idstringrequired
    • namestringrequired
    • effective_datestringrequired
    • guidelineobjectrequired
      10 fields
      • versionintegerrequired
      • rating_levelsobject[]required
        2 fields
        • valuenumberrequired
        • labelstringrequired
      • cr_boundsnumber[]required
      • cellsobject[]required
        5 fields
        • rowstringrequired
        • colstringrequired
        • minnumberrequired
        • targetnumberrequired
        • maxnumberrequired
      • rowsstring[]required
      • colsstring[]required
      • bring_to_minbooleanrequired
      • lump_above_maxbooleanrequired
      • rounding"none" | numberrequired
      • changed_onstring | nullrequired
    • merit_pctnumberrequired
    • promotion_pctnumber | nullrequired
    • lump_sumsbooleanrequired
    • reasons"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"[]required

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/me.criteria \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "items": [
      {
        "id": "cy1",
        "name": "Spring review",
        "effective_date": "2027-01-01",
        "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
        },
        "merit_pct": 3,
        "promotion_pct": 1,
        "lump_sums": true,
        "reasons": [
          "market",
          "retention",
          "internal_equity",
          "promotion_pending",
          "skills",
          "other"
        ]
      }
    ]
  }
}

My salary review worksheet#

POST/v1/comp/worksheet.getRead

Your worksheet in a salary review, as the manager proposing for your team: each person's rating (when you see it), compa-ratio band and where their pay sits in the band, the guideline % range, your proposal and whether it needs a reason, and the budget as % of the pool used. Never salaries. From the managers' preview day: the final % HR approved, to prepare conversations. In the app only (API keys and AI assistants can't read it). 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 manager's worksheet is read in the app only.
MCP tool
comp_worksheet_get on My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • cycle_idstringrequired

Returns

11 fields
  • cycleobjectrequired
    8 fields
    • idstringrequired
    • namestringrequired
    • stagestringrequired
    • effective_datestringrequired
    • propose_bystringrequired
    • release_onstringrequired
    • manager_preview_onstringrequired
    • guidelines_changed_onstring | nullrequired
  • state"draft" | "submitted" | "returned"required
  • submitted_atstring | nullrequired
  • return_notestring | nullrequired
  • editablebooleanrequired
  • why_notstring | nullrequired
  • manager_view"percent" | "amounts"required

    What this review shows managers (D15): percent (default), or amounts — then pay comes only from comp_worksheet_amounts (each view recorded in Activity) and saves.

  • amounts_shownbooleanrequired

    This answer carries amounts (rows[].amounts, budget[].money).

  • budgetobject[]required
    7 fields
    • currencystringrequired
    • used_pctnumberrequired
    • overbooleanrequired
    • pool_pctnumberrequired
    • moneyobject | nullrequired
      3 fields
      • budgetnumberrequired
      • spentnumberrequired
      • remainingnumberrequired
    • promotionobject | nullrequired
      4 fields
      • used_pctnumberrequired
      • overbooleanrequired
      • pool_pctnumberrequired
      • moneyobject | nullrequired
        3 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
    • lumpobject | nullrequired
      3 fields
      • used_pctnumberrequired
      • overbooleanrequired
      • moneyobject | nullrequired
        3 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
  • rowsobject[]required
    17 fields
    • idstringrequired
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • titlestring | nullrequired
    • teamstring | nullrequired
    • ratingobject | nullrequired
      2 fields
      • valuenumberrequired
      • labelstringrequired
    • cr_bandobjectrequired
      2 fields
      • colstringrequired
      • labelstringrequired
    • range_posnumber | nullrequired

      Where pay sits in the band, in tenths: 0 = minimum, 100 = maximum (can be below 0 or above 100).

    • flags"no_pay" | "no_band" | "below_min" | "above_max" | "new_joiner" | "protected_leave"[]required
    • guidelineobjectrequired
      5 fields
      • minnumberrequired
      • targetnumberrequired
      • maxnumberrequired
      • to_minbooleanrequired
      • lumpbooleanrequired

        Pay above the band maximum: the guideline's raise is suggested as a one-off lump sum (lump_sum_pct) instead of a base increase; base and lump sum together are checked against the range.

    • proposalobject | nullrequired
      5 fields
      • pctnumberrequired
      • reason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"required
      • reason_textstring | nullrequired
      • commentstring | nullrequired
      • lump_sum_pctnumber | nullrequired
    • protected_floornumber | nullrequired

      On protected leave (maternity, paternity, parental, adoption) in the review period: the lowest % you can propose, the raise as if they had been at work; only HR can record an objective reason for less. Null for everyone else.

    • lump_okbooleanrequired
    • needs_reasonstring | nullrequired
    • state"draft" | "submitted" | "returned"required
    • outcomeobject | nullrequired
      3 fields
      • pctnumber | nullrequired
      • lump_sum_pctnumber | nullrequired
      • includedbooleanrequired
    • summarystringrequired
    • amountsobject | nullrequired

      Only in a review that shows managers amounts (manager_view amounts), from comp_worksheet_amounts or a save: current base pay, the new base pay proposed (as the server computes it, with the cycle's rounding) and the lump sum. Otherwise null.

      3 fields
      • baseobjectrequired
        3 fields
        • amountnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
      • newobject | nullrequired
        3 fields
        • amountnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
      • lump_sumnumber | nullrequired
  • missingintegerrequired

    Rows with pay and no proposal yet (Submit needs one per row; 0 % is a proposal).

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/worksheet.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cycle_id":"cy1"}'
Response
{
  "data": {
    "cycle": {
      "id": "cy1",
      "name": "Spring review",
      "stage": "proposing",
      "effective_date": "2027-01-01",
      "propose_by": "2026-11-27",
      "release_on": "2026-12-15",
      "manager_preview_on": "2026-12-11",
      "guidelines_changed_on": null
    },
    "state": "draft",
    "submitted_at": null,
    "return_note": null,
    "editable": true,
    "why_not": null,
    "manager_view": "percent",
    "amounts_shown": false,
    "budget": [
      {
        "currency": "EUR",
        "used_pct": 65,
        "over": false,
        "pool_pct": 3,
        "money": null,
        "promotion": {
          "used_pct": 0,
          "over": false,
          "pool_pct": 1,
          "money": null
        },
        "lump": {
          "used_pct": 10,
          "over": false,
          "money": null
        }
      }
    ],
    "rows": [
      {
        "id": "cy1:p3",
        "person": {
          "id": "p3",
          "name": "Dina Silva"
        },
        "title": "Engineer",
        "team": "Engineering",
        "rating": {
          "value": 3,
          "label": "Meets expectations"
        },
        "cr_band": {
          "col": "c2",
          "label": "1.00–1.09"
        },
        "range_pos": 50,
        "flags": [],
        "guideline": {
          "min": 2,
          "target": 3,
          "max": 4,
          "to_min": false,
          "lump": false
        },
        "protected_floor": null,
        "proposal": {
          "pct": 3,
          "reason": null,
          "reason_text": null,
          "comment": null,
          "lump_sum_pct": null
        },
        "lump_ok": true,
        "needs_reason": null,
        "state": "draft",
        "outcome": null,
        "summary": "Dina Silva, compa-ratio band 1.00–1.09, guideline 2 to 4 %, proposed 3 %",
        "amounts": null
      }
    ],
    "missing": 0
  }
}

Save salary review proposals#

POST/v1/comp/worksheet.saveWrite

Saves proposals on your worksheet as a draft: per row the increase in % (0 = no change), an optional one-off lump sum as % of base pay (lump_sum_pct, when the row's lump_ok), a reason when it is outside the guideline (market, retention, internal_equity, promotion_pending, skills, or other with at least 20 characters) and an optional private comment to HR. A raise whose reason is promotion_pending draws on the promotion budget when the cycle has one. For a row whose guideline is a lump sum (pay above the band maximum), base and lump sum together are checked against the range. A row flagged protected_leave can't go below its protected_floor (the raise as if at work; refused): only HR can record an objective reason for less. A dry run returns the worksheet as it would be (the effective % after the cycle's rounding, the budget used). Only your participants, never your own row; while proposals are open and the worksheet is not submitted. At most 30 saves a minute. 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 made in the app only.
MCP tool
comp_worksheet_save on My Workplace
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • cycle_idstringrequired
  • rowsobject[]required

    1–500 items.

    6 fields
    • row_idstringrequired
    • pctnumber | nullrequired

      Proposed increase in % of base pay (0 = no change); null clears it.

      From 0 to 100.

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

      Up to 500 characters.

    • commentstring | null

      A private note to HR.

      Up to 1000 characters.

    • lump_sum_pctnumber | null

      A one-off lump sum as % of the annual base (only when the cycle has a lump-sum budget for the person's currency, lump_ok); null or 0 removes it; left out: kept as saved.

      From 0 to 100.

Returns

11 fields
  • cycleobjectrequired
    8 fields
    • idstringrequired
    • namestringrequired
    • stagestringrequired
    • effective_datestringrequired
    • propose_bystringrequired
    • release_onstringrequired
    • manager_preview_onstringrequired
    • guidelines_changed_onstring | nullrequired
  • state"draft" | "submitted" | "returned"required
  • submitted_atstring | nullrequired
  • return_notestring | nullrequired
  • editablebooleanrequired
  • why_notstring | nullrequired
  • manager_view"percent" | "amounts"required

    What this review shows managers (D15): percent (default), or amounts — then pay comes only from comp_worksheet_amounts (each view recorded in Activity) and saves.

  • amounts_shownbooleanrequired

    This answer carries amounts (rows[].amounts, budget[].money).

  • budgetobject[]required
    7 fields
    • currencystringrequired
    • used_pctnumberrequired
    • overbooleanrequired
    • pool_pctnumberrequired
    • moneyobject | nullrequired
      3 fields
      • budgetnumberrequired
      • spentnumberrequired
      • remainingnumberrequired
    • promotionobject | nullrequired
      4 fields
      • used_pctnumberrequired
      • overbooleanrequired
      • pool_pctnumberrequired
      • moneyobject | nullrequired
        3 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
    • lumpobject | nullrequired
      3 fields
      • used_pctnumberrequired
      • overbooleanrequired
      • moneyobject | nullrequired
        3 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
  • rowsobject[]required
    17 fields
    • idstringrequired
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • titlestring | nullrequired
    • teamstring | nullrequired
    • ratingobject | nullrequired
      2 fields
      • valuenumberrequired
      • labelstringrequired
    • cr_bandobjectrequired
      2 fields
      • colstringrequired
      • labelstringrequired
    • range_posnumber | nullrequired

      Where pay sits in the band, in tenths: 0 = minimum, 100 = maximum (can be below 0 or above 100).

    • flags"no_pay" | "no_band" | "below_min" | "above_max" | "new_joiner" | "protected_leave"[]required
    • guidelineobjectrequired
      5 fields
      • minnumberrequired
      • targetnumberrequired
      • maxnumberrequired
      • to_minbooleanrequired
      • lumpbooleanrequired

        Pay above the band maximum: the guideline's raise is suggested as a one-off lump sum (lump_sum_pct) instead of a base increase; base and lump sum together are checked against the range.

    • proposalobject | nullrequired
      5 fields
      • pctnumberrequired
      • reason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"required
      • reason_textstring | nullrequired
      • commentstring | nullrequired
      • lump_sum_pctnumber | nullrequired
    • protected_floornumber | nullrequired

      On protected leave (maternity, paternity, parental, adoption) in the review period: the lowest % you can propose, the raise as if they had been at work; only HR can record an objective reason for less. Null for everyone else.

    • lump_okbooleanrequired
    • needs_reasonstring | nullrequired
    • state"draft" | "submitted" | "returned"required
    • outcomeobject | nullrequired
      3 fields
      • pctnumber | nullrequired
      • lump_sum_pctnumber | nullrequired
      • includedbooleanrequired
    • summarystringrequired
    • amountsobject | nullrequired

      Only in a review that shows managers amounts (manager_view amounts), from comp_worksheet_amounts or a save: current base pay, the new base pay proposed (as the server computes it, with the cycle's rounding) and the lump sum. Otherwise null.

      3 fields
      • baseobjectrequired
        3 fields
        • amountnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
      • newobject | nullrequired
        3 fields
        • amountnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
      • lump_sumnumber | nullrequired
  • missingintegerrequired

    Rows with pay and no proposal yet (Submit needs one per row; 0 % is a proposal).

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/worksheet.save \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "cycle_id": "cy1",
  "rows": [
    {
      "row_id": "cy1:p3",
      "pct": 3,
      "lump_sum_pct": 2
    },
    {
      "row_id": "cy1:p4",
      "pct": 6,
      "reason": "other",
      "reason_text": "Took over the team lead role in June",
      "comment": "Ready for promotion"
    }
  ]
}'
Response
{
  "data": {
    "cycle": {
      "id": "cy1",
      "name": "Spring review",
      "stage": "proposing",
      "effective_date": "2027-01-01",
      "propose_by": "2026-11-27",
      "release_on": "2026-12-15",
      "manager_preview_on": "2026-12-11",
      "guidelines_changed_on": null
    },
    "state": "draft",
    "submitted_at": null,
    "return_note": null,
    "editable": true,
    "why_not": null,
    "manager_view": "percent",
    "amounts_shown": false,
    "budget": [
      {
        "currency": "EUR",
        "used_pct": 65,
        "over": false,
        "pool_pct": 3,
        "money": null,
        "promotion": {
          "used_pct": 0,
          "over": false,
          "pool_pct": 1,
          "money": null
        },
        "lump": {
          "used_pct": 10,
          "over": false,
          "money": null
        }
      }
    ],
    "rows": [
      {
        "id": "cy1:p3",
        "person": {
          "id": "p3",
          "name": "Dina Silva"
        },
        "title": "Engineer",
        "team": "Engineering",
        "rating": {
          "value": 3,
          "label": "Meets expectations"
        },
        "cr_band": {
          "col": "c2",
          "label": "1.00–1.09"
        },
        "range_pos": 50,
        "flags": [],
        "guideline": {
          "min": 2,
          "target": 3,
          "max": 4,
          "to_min": false,
          "lump": false
        },
        "protected_floor": null,
        "proposal": {
          "pct": 3,
          "reason": null,
          "reason_text": null,
          "comment": null,
          "lump_sum_pct": null
        },
        "lump_ok": true,
        "needs_reason": null,
        "state": "draft",
        "outcome": null,
        "summary": "Dina Silva, compa-ratio band 1.00–1.09, guideline 2 to 4 %, proposed 3 %",
        "amounts": null
      }
    ],
    "missing": 0
  }
}

Submit my salary review worksheet#

POST/v1/comp/worksheet.submitWrite

Sends your whole worksheet to HR for review: every row with pay needs a proposal (0 % is one) and every proposal outside the guideline a reason. Over budget (merit, promotion or lump sums): allowed with over_budget_reason (HR sees it flagged and decides). Read-only afterwards until HR sends it back. 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 submitted in the app only.
MCP tool
comp_worksheet_submit on My Workplace
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • cycle_idstringrequired
  • over_budget_reasonstring

    1–500 characters.

Returns

11 fields
  • cycleobjectrequired
    8 fields
    • idstringrequired
    • namestringrequired
    • stagestringrequired
    • effective_datestringrequired
    • propose_bystringrequired
    • release_onstringrequired
    • manager_preview_onstringrequired
    • guidelines_changed_onstring | nullrequired
  • state"draft" | "submitted" | "returned"required
  • submitted_atstring | nullrequired
  • return_notestring | nullrequired
  • editablebooleanrequired
  • why_notstring | nullrequired
  • manager_view"percent" | "amounts"required

    What this review shows managers (D15): percent (default), or amounts — then pay comes only from comp_worksheet_amounts (each view recorded in Activity) and saves.

  • amounts_shownbooleanrequired

    This answer carries amounts (rows[].amounts, budget[].money).

  • budgetobject[]required
    7 fields
    • currencystringrequired
    • used_pctnumberrequired
    • overbooleanrequired
    • pool_pctnumberrequired
    • moneyobject | nullrequired
      3 fields
      • budgetnumberrequired
      • spentnumberrequired
      • remainingnumberrequired
    • promotionobject | nullrequired
      4 fields
      • used_pctnumberrequired
      • overbooleanrequired
      • pool_pctnumberrequired
      • moneyobject | nullrequired
        3 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
    • lumpobject | nullrequired
      3 fields
      • used_pctnumberrequired
      • overbooleanrequired
      • moneyobject | nullrequired
        3 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
  • rowsobject[]required
    17 fields
    • idstringrequired
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • titlestring | nullrequired
    • teamstring | nullrequired
    • ratingobject | nullrequired
      2 fields
      • valuenumberrequired
      • labelstringrequired
    • cr_bandobjectrequired
      2 fields
      • colstringrequired
      • labelstringrequired
    • range_posnumber | nullrequired

      Where pay sits in the band, in tenths: 0 = minimum, 100 = maximum (can be below 0 or above 100).

    • flags"no_pay" | "no_band" | "below_min" | "above_max" | "new_joiner" | "protected_leave"[]required
    • guidelineobjectrequired
      5 fields
      • minnumberrequired
      • targetnumberrequired
      • maxnumberrequired
      • to_minbooleanrequired
      • lumpbooleanrequired

        Pay above the band maximum: the guideline's raise is suggested as a one-off lump sum (lump_sum_pct) instead of a base increase; base and lump sum together are checked against the range.

    • proposalobject | nullrequired
      5 fields
      • pctnumberrequired
      • reason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"required
      • reason_textstring | nullrequired
      • commentstring | nullrequired
      • lump_sum_pctnumber | nullrequired
    • protected_floornumber | nullrequired

      On protected leave (maternity, paternity, parental, adoption) in the review period: the lowest % you can propose, the raise as if they had been at work; only HR can record an objective reason for less. Null for everyone else.

    • lump_okbooleanrequired
    • needs_reasonstring | nullrequired
    • state"draft" | "submitted" | "returned"required
    • outcomeobject | nullrequired
      3 fields
      • pctnumber | nullrequired
      • lump_sum_pctnumber | nullrequired
      • includedbooleanrequired
    • summarystringrequired
    • amountsobject | nullrequired

      Only in a review that shows managers amounts (manager_view amounts), from comp_worksheet_amounts or a save: current base pay, the new base pay proposed (as the server computes it, with the cycle's rounding) and the lump sum. Otherwise null.

      3 fields
      • baseobjectrequired
        3 fields
        • amountnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
      • newobject | nullrequired
        3 fields
        • amountnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
      • lump_sumnumber | nullrequired
  • missingintegerrequired

    Rows with pay and no proposal yet (Submit needs one per row; 0 % is a proposal).

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/worksheet.submit \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"cycle_id":"cy1","over_budget_reason":"Two retention cases"}'
Response
{
  "data": {
    "cycle": {
      "id": "cy1",
      "name": "Spring review",
      "stage": "proposing",
      "effective_date": "2027-01-01",
      "propose_by": "2026-11-27",
      "release_on": "2026-12-15",
      "manager_preview_on": "2026-12-11",
      "guidelines_changed_on": null
    },
    "state": "submitted",
    "submitted_at": "2026-11-20T10:00:00.000Z",
    "return_note": null,
    "editable": false,
    "why_not": "Submitted to HR: HR can send it back if something needs a change.",
    "manager_view": "percent",
    "amounts_shown": false,
    "budget": [
      {
        "currency": "EUR",
        "used_pct": 65,
        "over": false,
        "pool_pct": 3,
        "money": null,
        "promotion": {
          "used_pct": 0,
          "over": false,
          "pool_pct": 1,
          "money": null
        },
        "lump": {
          "used_pct": 10,
          "over": false,
          "money": null
        }
      }
    ],
    "rows": [
      {
        "id": "cy1:p3",
        "person": {
          "id": "p3",
          "name": "Dina Silva"
        },
        "title": "Engineer",
        "team": "Engineering",
        "rating": {
          "value": 3,
          "label": "Meets expectations"
        },
        "cr_band": {
          "col": "c2",
          "label": "1.00–1.09"
        },
        "range_pos": 50,
        "flags": [],
        "guideline": {
          "min": 2,
          "target": 3,
          "max": 4,
          "to_min": false,
          "lump": false
        },
        "protected_floor": null,
        "proposal": {
          "pct": 3,
          "reason": null,
          "reason_text": null,
          "comment": null,
          "lump_sum_pct": null
        },
        "lump_ok": true,
        "needs_reason": null,
        "state": "draft",
        "outcome": null,
        "summary": "Dina Silva, compa-ratio band 1.00–1.09, guideline 2 to 4 %, proposed 3 %",
        "amounts": null
      }
    ],
    "missing": 0
  }
}

See pay on my salary review worksheet#

POST/v1/comp/worksheet.amountsWrite

In a salary review that shows managers amounts (a cycle setting, off by default): your worksheet with each person's current base pay, the new base pay proposed and any lump sum, and the budget in money. Each view is recorded in Activity (no names or amounts). Only while the review is open (proposals, HR review, managers preview), only your participants, never your own pay. 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. Pay on a worksheet shows in the app only.
MCP tool
comp_worksheet_amounts on My Workplace
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • cycle_idstringrequired

Returns

11 fields
  • cycleobjectrequired
    8 fields
    • idstringrequired
    • namestringrequired
    • stagestringrequired
    • effective_datestringrequired
    • propose_bystringrequired
    • release_onstringrequired
    • manager_preview_onstringrequired
    • guidelines_changed_onstring | nullrequired
  • state"draft" | "submitted" | "returned"required
  • submitted_atstring | nullrequired
  • return_notestring | nullrequired
  • editablebooleanrequired
  • why_notstring | nullrequired
  • manager_view"percent" | "amounts"required

    What this review shows managers (D15): percent (default), or amounts — then pay comes only from comp_worksheet_amounts (each view recorded in Activity) and saves.

  • amounts_shownbooleanrequired

    This answer carries amounts (rows[].amounts, budget[].money).

  • budgetobject[]required
    7 fields
    • currencystringrequired
    • used_pctnumberrequired
    • overbooleanrequired
    • pool_pctnumberrequired
    • moneyobject | nullrequired
      3 fields
      • budgetnumberrequired
      • spentnumberrequired
      • remainingnumberrequired
    • promotionobject | nullrequired
      4 fields
      • used_pctnumberrequired
      • overbooleanrequired
      • pool_pctnumberrequired
      • moneyobject | nullrequired
        3 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
    • lumpobject | nullrequired
      3 fields
      • used_pctnumberrequired
      • overbooleanrequired
      • moneyobject | nullrequired
        3 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
  • rowsobject[]required
    17 fields
    • idstringrequired
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • titlestring | nullrequired
    • teamstring | nullrequired
    • ratingobject | nullrequired
      2 fields
      • valuenumberrequired
      • labelstringrequired
    • cr_bandobjectrequired
      2 fields
      • colstringrequired
      • labelstringrequired
    • range_posnumber | nullrequired

      Where pay sits in the band, in tenths: 0 = minimum, 100 = maximum (can be below 0 or above 100).

    • flags"no_pay" | "no_band" | "below_min" | "above_max" | "new_joiner" | "protected_leave"[]required
    • guidelineobjectrequired
      5 fields
      • minnumberrequired
      • targetnumberrequired
      • maxnumberrequired
      • to_minbooleanrequired
      • lumpbooleanrequired

        Pay above the band maximum: the guideline's raise is suggested as a one-off lump sum (lump_sum_pct) instead of a base increase; base and lump sum together are checked against the range.

    • proposalobject | nullrequired
      5 fields
      • pctnumberrequired
      • reason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"required
      • reason_textstring | nullrequired
      • commentstring | nullrequired
      • lump_sum_pctnumber | nullrequired
    • protected_floornumber | nullrequired

      On protected leave (maternity, paternity, parental, adoption) in the review period: the lowest % you can propose, the raise as if they had been at work; only HR can record an objective reason for less. Null for everyone else.

    • lump_okbooleanrequired
    • needs_reasonstring | nullrequired
    • state"draft" | "submitted" | "returned"required
    • outcomeobject | nullrequired
      3 fields
      • pctnumber | nullrequired
      • lump_sum_pctnumber | nullrequired
      • includedbooleanrequired
    • summarystringrequired
    • amountsobject | nullrequired

      Only in a review that shows managers amounts (manager_view amounts), from comp_worksheet_amounts or a save: current base pay, the new base pay proposed (as the server computes it, with the cycle's rounding) and the lump sum. Otherwise null.

      3 fields
      • baseobjectrequired
        3 fields
        • amountnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
      • newobject | nullrequired
        3 fields
        • amountnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
      • lump_sumnumber | nullrequired
  • missingintegerrequired

    Rows with pay and no proposal yet (Submit needs one per row; 0 % is a proposal).

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/worksheet.amounts \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"cycle_id":"cy1"}'
Response
{
  "data": {
    "cycle": {
      "id": "cy1",
      "name": "Spring review",
      "stage": "proposing",
      "effective_date": "2027-01-01",
      "propose_by": "2026-11-27",
      "release_on": "2026-12-15",
      "manager_preview_on": "2026-12-11",
      "guidelines_changed_on": null
    },
    "state": "draft",
    "submitted_at": null,
    "return_note": null,
    "editable": true,
    "why_not": null,
    "manager_view": "amounts",
    "amounts_shown": true,
    "budget": [
      {
        "currency": "EUR",
        "used_pct": 64.3,
        "over": false,
        "pool_pct": 3,
        "money": {
          "budget": 2580,
          "spent": 1659,
          "remaining": 921
        },
        "promotion": null,
        "lump": null
      }
    ],
    "rows": [
      {
        "id": "cy1:p3",
        "person": {
          "id": "p3",
          "name": "Dina Silva"
        },
        "title": "Engineer",
        "team": "Engineering",
        "rating": {
          "value": 3,
          "label": "Meets expectations"
        },
        "cr_band": {
          "col": "c2",
          "label": "1.00–1.09"
        },
        "range_pos": 50,
        "flags": [],
        "guideline": {
          "min": 2,
          "target": 3,
          "max": 4,
          "to_min": false,
          "lump": false
        },
        "protected_floor": null,
        "proposal": {
          "pct": 3,
          "reason": null,
          "reason_text": null,
          "comment": null,
          "lump_sum_pct": null
        },
        "lump_ok": true,
        "needs_reason": null,
        "state": "draft",
        "outcome": null,
        "summary": "Dina Silva, compa-ratio band 1.00–1.09, guideline 2 to 4 %, proposed 3 %",
        "amounts": {
          "base": {
            "amount": 50000,
            "currency": "EUR",
            "period": "year"
          },
          "new": {
            "amount": 51500,
            "currency": "EUR",
            "period": "year"
          },
          "lump_sum": null
        }
      }
    ],
    "missing": 0
  }
}

Worksheets from my team to check#

POST/v1/comp/upper.getRead

With the upper-manager step on (a cycle setting, off by default): the worksheets of managers who report to you, as they see them — each person's compa-ratio band, where pay sits in the band, the guideline % and the proposal, the budget as % used; never salaries. waiting: for you to check (send on to HR, change a proposal, or send back). Empty when nothing is yours. 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. Team worksheets are checked in the app only.
MCP tool
comp_upper_get on My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • cycle_idstringrequired

Returns

  • cycleobjectrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • stagestringrequired
    • review_bystringrequired
  • sheetsobject[]required
    4 fields
    • proposerobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • state"waiting" | "sent" | "returned" | "open"required

      waiting: for you to check; sent: sent on to HR; returned: back with its manager; open: not submitted yet.

    • over_budget_reasonstring | nullrequired
    • viewobjectrequired

      The worksheet as its manager sees it: % only, never salaries.

      11 fields
      • cycleobjectrequired
        8 fields
        • idstringrequired
        • namestringrequired
        • stagestringrequired
        • effective_datestringrequired
        • propose_bystringrequired
        • release_onstringrequired
        • manager_preview_onstringrequired
        • guidelines_changed_onstring | nullrequired
      • state"draft" | "submitted" | "returned"required
      • submitted_atstring | nullrequired
      • return_notestring | nullrequired
      • editablebooleanrequired
      • why_notstring | nullrequired
      • manager_view"percent" | "amounts"required

        What this review shows managers (D15): percent (default), or amounts — then pay comes only from comp_worksheet_amounts (each view recorded in Activity) and saves.

      • amounts_shownbooleanrequired

        This answer carries amounts (rows[].amounts, budget[].money).

      • budgetobject[]required
        7 fields
        • currencystringrequired
        • used_pctnumberrequired
        • overbooleanrequired
        • pool_pctnumberrequired
        • moneyobject | nullrequired
          3 fields
          • budgetnumberrequired
          • spentnumberrequired
          • remainingnumberrequired
        • promotionobject | nullrequired
          4 fields
          • used_pctnumberrequired
          • overbooleanrequired
          • pool_pctnumberrequired
          • moneyobject | nullrequired
        • lumpobject | nullrequired
          3 fields
          • used_pctnumberrequired
          • overbooleanrequired
          • moneyobject | nullrequired
      • rowsobject[]required
        17 fields
        • idstringrequired
        • personobjectrequired
          2 fields
          • idstringrequired
          • namestringrequired
        • titlestring | nullrequired
        • teamstring | nullrequired
        • ratingobject | nullrequired
          2 fields
          • valuenumberrequired
          • labelstringrequired
        • cr_bandobjectrequired
          2 fields
          • colstringrequired
          • labelstringrequired
        • range_posnumber | nullrequired

          Where pay sits in the band, in tenths: 0 = minimum, 100 = maximum (can be below 0 or above 100).

        • flags"no_pay" | "no_band" | "below_min" | "above_max" | "new_joiner" | "protected_leave"[]required
        • guidelineobjectrequired
          5 fields
          • minnumberrequired
          • targetnumberrequired
          • maxnumberrequired
          • to_minbooleanrequired
          • lumpbooleanrequired

            Pay above the band maximum: the guideline's raise is suggested as a one-off lump sum (lump_sum_pct) instead of a base increase; base and lump sum together are checked against the range.

        • proposalobject | nullrequired
          5 fields
          • pctnumberrequired
          • reason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"required
          • reason_textstring | nullrequired
          • commentstring | nullrequired
          • lump_sum_pctnumber | nullrequired
        • protected_floornumber | nullrequired

          On protected leave (maternity, paternity, parental, adoption) in the review period: the lowest % you can propose, the raise as if they had been at work; only HR can record an objective reason for less. Null for everyone else.

        • lump_okbooleanrequired
        • needs_reasonstring | nullrequired
        • state"draft" | "submitted" | "returned"required
        • outcomeobject | nullrequired
          3 fields
          • pctnumber | nullrequired
          • lump_sum_pctnumber | nullrequired
          • includedbooleanrequired
        • summarystringrequired
        • amountsobject | nullrequired

          Only in a review that shows managers amounts (manager_view amounts), from comp_worksheet_amounts or a save: current base pay, the new base pay proposed (as the server computes it, with the cycle's rounding) and the lump sum. Otherwise null.

          3 fields
          • baseobjectrequired
          • newobject | nullrequired
          • lump_sumnumber | nullrequired
      • missingintegerrequired

        Rows with pay and no proposal yet (Submit needs one per row; 0 % is a proposal).

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/upper.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cycle_id":"cy1"}'
Response
{
  "data": {
    "cycle": {
      "id": "cy1",
      "name": "Spring review",
      "stage": "proposing",
      "review_by": "2026-12-04"
    },
    "sheets": [
      {
        "proposer": {
          "id": "p2",
          "name": "Bea Silva"
        },
        "state": "waiting",
        "over_budget_reason": null,
        "view": {
          "cycle": {
            "id": "cy1",
            "name": "Spring review",
            "stage": "proposing",
            "effective_date": "2027-01-01",
            "propose_by": "2026-11-27",
            "release_on": "2026-12-15",
            "manager_preview_on": "2026-12-11",
            "guidelines_changed_on": null
          },
          "state": "submitted",
          "submitted_at": null,
          "return_note": null,
          "editable": true,
          "why_not": null,
          "manager_view": "percent",
          "amounts_shown": false,
          "budget": [
            {
              "currency": "EUR",
              "used_pct": 65,
              "over": false,
              "pool_pct": 3,
              "money": null,
              "promotion": {
                "used_pct": 0,
                "over": false,
                "pool_pct": 1,
                "money": null
              },
              "lump": {
                "used_pct": 10,
                "over": false,
                "money": null
              }
            }
          ],
          "rows": [
            {
              "id": "cy1:p3",
              "person": {
                "id": "p3",
                "name": "Dina Silva"
              },
              "title": "Engineer",
              "team": "Engineering",
              "rating": {
                "value": 3,
                "label": "Meets expectations"
              },
              "cr_band": {
                "col": "c2",
                "label": "1.00–1.09"
              },
              "range_pos": 50,
              "flags": [],
              "guideline": {
                "min": 2,
                "target": 3,
                "max": 4,
                "to_min": false,
                "lump": false
              },
              "protected_floor": null,
              "proposal": {
                "pct": 3,
                "reason": null,
                "reason_text": null,
                "comment": null,
                "lump_sum_pct": null
              },
              "lump_ok": true,
              "needs_reason": null,
              "state": "draft",
              "outcome": null,
              "summary": "Dina Silva, compa-ratio band 1.00–1.09, guideline 2 to 4 %, proposed 3 %",
              "amounts": null
            }
          ],
          "missing": 0
        }
      }
    ]
  }
}

Change proposals on a worksheet from my team#

POST/v1/comp/upper.saveWrite

Changes proposals on a worksheet waiting for you (the upper-manager step): per row the increase in %, a reason when outside the guideline (other: at least 20 characters) and a lump sum as % when the cycle has them. You become the row's editor, so someone else approves it. The worksheet still waits for you: send it on with comp_upper_submit. 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. Team worksheets are checked in the app only.
MCP tool
comp_upper_save on My Workplace
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • cycle_idstringrequired
  • proposer_person_idstringrequired
  • rowsobject[]required

    1–500 items.

    5 fields
    • row_idstringrequired
    • pctnumberrequired

      The increase in % of base pay (0 = no change).

      From 0 to 100.

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

      Up to 500 characters.

    • lump_sum_pctnumber | null

      A one-off lump sum as % of base (when the row's lump_ok); null or 0 removes it; left out: kept.

      From 0 to 100.

Returns

  • cycleobjectrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • stagestringrequired
    • review_bystringrequired
  • sheetsobject[]required
    4 fields
    • proposerobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • state"waiting" | "sent" | "returned" | "open"required

      waiting: for you to check; sent: sent on to HR; returned: back with its manager; open: not submitted yet.

    • over_budget_reasonstring | nullrequired
    • viewobjectrequired

      The worksheet as its manager sees it: % only, never salaries.

      11 fields
      • cycleobjectrequired
        8 fields
        • idstringrequired
        • namestringrequired
        • stagestringrequired
        • effective_datestringrequired
        • propose_bystringrequired
        • release_onstringrequired
        • manager_preview_onstringrequired
        • guidelines_changed_onstring | nullrequired
      • state"draft" | "submitted" | "returned"required
      • submitted_atstring | nullrequired
      • return_notestring | nullrequired
      • editablebooleanrequired
      • why_notstring | nullrequired
      • manager_view"percent" | "amounts"required

        What this review shows managers (D15): percent (default), or amounts — then pay comes only from comp_worksheet_amounts (each view recorded in Activity) and saves.

      • amounts_shownbooleanrequired

        This answer carries amounts (rows[].amounts, budget[].money).

      • budgetobject[]required
        7 fields
        • currencystringrequired
        • used_pctnumberrequired
        • overbooleanrequired
        • pool_pctnumberrequired
        • moneyobject | nullrequired
          3 fields
          • budgetnumberrequired
          • spentnumberrequired
          • remainingnumberrequired
        • promotionobject | nullrequired
          4 fields
          • used_pctnumberrequired
          • overbooleanrequired
          • pool_pctnumberrequired
          • moneyobject | nullrequired
        • lumpobject | nullrequired
          3 fields
          • used_pctnumberrequired
          • overbooleanrequired
          • moneyobject | nullrequired
      • rowsobject[]required
        17 fields
        • idstringrequired
        • personobjectrequired
          2 fields
          • idstringrequired
          • namestringrequired
        • titlestring | nullrequired
        • teamstring | nullrequired
        • ratingobject | nullrequired
          2 fields
          • valuenumberrequired
          • labelstringrequired
        • cr_bandobjectrequired
          2 fields
          • colstringrequired
          • labelstringrequired
        • range_posnumber | nullrequired

          Where pay sits in the band, in tenths: 0 = minimum, 100 = maximum (can be below 0 or above 100).

        • flags"no_pay" | "no_band" | "below_min" | "above_max" | "new_joiner" | "protected_leave"[]required
        • guidelineobjectrequired
          5 fields
          • minnumberrequired
          • targetnumberrequired
          • maxnumberrequired
          • to_minbooleanrequired
          • lumpbooleanrequired

            Pay above the band maximum: the guideline's raise is suggested as a one-off lump sum (lump_sum_pct) instead of a base increase; base and lump sum together are checked against the range.

        • proposalobject | nullrequired
          5 fields
          • pctnumberrequired
          • reason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"required
          • reason_textstring | nullrequired
          • commentstring | nullrequired
          • lump_sum_pctnumber | nullrequired
        • protected_floornumber | nullrequired

          On protected leave (maternity, paternity, parental, adoption) in the review period: the lowest % you can propose, the raise as if they had been at work; only HR can record an objective reason for less. Null for everyone else.

        • lump_okbooleanrequired
        • needs_reasonstring | nullrequired
        • state"draft" | "submitted" | "returned"required
        • outcomeobject | nullrequired
          3 fields
          • pctnumber | nullrequired
          • lump_sum_pctnumber | nullrequired
          • includedbooleanrequired
        • summarystringrequired
        • amountsobject | nullrequired

          Only in a review that shows managers amounts (manager_view amounts), from comp_worksheet_amounts or a save: current base pay, the new base pay proposed (as the server computes it, with the cycle's rounding) and the lump sum. Otherwise null.

          3 fields
          • baseobjectrequired
          • newobject | nullrequired
          • lump_sumnumber | nullrequired
      • missingintegerrequired

        Rows with pay and no proposal yet (Submit needs one per row; 0 % is a proposal).

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/upper.save \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "cycle_id": "cy1",
  "proposer_person_id": "p2",
  "rows": [
    {
      "row_id": "cy1:p3",
      "pct": 3.5
    },
    {
      "row_id": "cy1:p4",
      "pct": 6,
      "reason": "market"
    }
  ]
}'
Response
{
  "data": {
    "cycle": {
      "id": "cy1",
      "name": "Spring review",
      "stage": "proposing",
      "review_by": "2026-12-04"
    },
    "sheets": [
      {
        "proposer": {
          "id": "p2",
          "name": "Bea Silva"
        },
        "state": "waiting",
        "over_budget_reason": null,
        "view": {
          "cycle": {
            "id": "cy1",
            "name": "Spring review",
            "stage": "proposing",
            "effective_date": "2027-01-01",
            "propose_by": "2026-11-27",
            "release_on": "2026-12-15",
            "manager_preview_on": "2026-12-11",
            "guidelines_changed_on": null
          },
          "state": "submitted",
          "submitted_at": null,
          "return_note": null,
          "editable": true,
          "why_not": null,
          "manager_view": "percent",
          "amounts_shown": false,
          "budget": [
            {
              "currency": "EUR",
              "used_pct": 65,
              "over": false,
              "pool_pct": 3,
              "money": null,
              "promotion": {
                "used_pct": 0,
                "over": false,
                "pool_pct": 1,
                "money": null
              },
              "lump": {
                "used_pct": 10,
                "over": false,
                "money": null
              }
            }
          ],
          "rows": [
            {
              "id": "cy1:p3",
              "person": {
                "id": "p3",
                "name": "Dina Silva"
              },
              "title": "Engineer",
              "team": "Engineering",
              "rating": {
                "value": 3,
                "label": "Meets expectations"
              },
              "cr_band": {
                "col": "c2",
                "label": "1.00–1.09"
              },
              "range_pos": 50,
              "flags": [],
              "guideline": {
                "min": 2,
                "target": 3,
                "max": 4,
                "to_min": false,
                "lump": false
              },
              "protected_floor": null,
              "proposal": {
                "pct": 3,
                "reason": null,
                "reason_text": null,
                "comment": null,
                "lump_sum_pct": null
              },
              "lump_ok": true,
              "needs_reason": null,
              "state": "draft",
              "outcome": null,
              "summary": "Dina Silva, compa-ratio band 1.00–1.09, guideline 2 to 4 %, proposed 3 %",
              "amounts": null
            }
          ],
          "missing": 0
        }
      }
    ]
  }
}

Send a worksheet from my team to HR#

POST/v1/comp/upper.submitWrite

Sends a worksheet waiting for you (the upper-manager step) on to HR, as it is or after your changes: every proposal outside the guideline needs its reason first. HR may also do this in Manage when the manager's manager can't. 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. Team worksheets are checked in the app only.
MCP tool
comp_upper_submit on My Workplace, HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • cycle_idstringrequired
  • proposer_person_idstringrequired
  • over_budget_reasonstring

    Needed when your changes put the worksheet over budget and its manager gave no reason.

    1–500 characters.

Returns

  • cycleobjectrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • stagestringrequired
    • review_bystringrequired
  • sheetsobject[]required
    4 fields
    • proposerobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • state"waiting" | "sent" | "returned" | "open"required

      waiting: for you to check; sent: sent on to HR; returned: back with its manager; open: not submitted yet.

    • over_budget_reasonstring | nullrequired
    • viewobjectrequired

      The worksheet as its manager sees it: % only, never salaries.

      11 fields
      • cycleobjectrequired
        8 fields
        • idstringrequired
        • namestringrequired
        • stagestringrequired
        • effective_datestringrequired
        • propose_bystringrequired
        • release_onstringrequired
        • manager_preview_onstringrequired
        • guidelines_changed_onstring | nullrequired
      • state"draft" | "submitted" | "returned"required
      • submitted_atstring | nullrequired
      • return_notestring | nullrequired
      • editablebooleanrequired
      • why_notstring | nullrequired
      • manager_view"percent" | "amounts"required

        What this review shows managers (D15): percent (default), or amounts — then pay comes only from comp_worksheet_amounts (each view recorded in Activity) and saves.

      • amounts_shownbooleanrequired

        This answer carries amounts (rows[].amounts, budget[].money).

      • budgetobject[]required
        7 fields
        • currencystringrequired
        • used_pctnumberrequired
        • overbooleanrequired
        • pool_pctnumberrequired
        • moneyobject | nullrequired
          3 fields
          • budgetnumberrequired
          • spentnumberrequired
          • remainingnumberrequired
        • promotionobject | nullrequired
          4 fields
          • used_pctnumberrequired
          • overbooleanrequired
          • pool_pctnumberrequired
          • moneyobject | nullrequired
        • lumpobject | nullrequired
          3 fields
          • used_pctnumberrequired
          • overbooleanrequired
          • moneyobject | nullrequired
      • rowsobject[]required
        17 fields
        • idstringrequired
        • personobjectrequired
          2 fields
          • idstringrequired
          • namestringrequired
        • titlestring | nullrequired
        • teamstring | nullrequired
        • ratingobject | nullrequired
          2 fields
          • valuenumberrequired
          • labelstringrequired
        • cr_bandobjectrequired
          2 fields
          • colstringrequired
          • labelstringrequired
        • range_posnumber | nullrequired

          Where pay sits in the band, in tenths: 0 = minimum, 100 = maximum (can be below 0 or above 100).

        • flags"no_pay" | "no_band" | "below_min" | "above_max" | "new_joiner" | "protected_leave"[]required
        • guidelineobjectrequired
          5 fields
          • minnumberrequired
          • targetnumberrequired
          • maxnumberrequired
          • to_minbooleanrequired
          • lumpbooleanrequired

            Pay above the band maximum: the guideline's raise is suggested as a one-off lump sum (lump_sum_pct) instead of a base increase; base and lump sum together are checked against the range.

        • proposalobject | nullrequired
          5 fields
          • pctnumberrequired
          • reason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"required
          • reason_textstring | nullrequired
          • commentstring | nullrequired
          • lump_sum_pctnumber | nullrequired
        • protected_floornumber | nullrequired

          On protected leave (maternity, paternity, parental, adoption) in the review period: the lowest % you can propose, the raise as if they had been at work; only HR can record an objective reason for less. Null for everyone else.

        • lump_okbooleanrequired
        • needs_reasonstring | nullrequired
        • state"draft" | "submitted" | "returned"required
        • outcomeobject | nullrequired
          3 fields
          • pctnumber | nullrequired
          • lump_sum_pctnumber | nullrequired
          • includedbooleanrequired
        • summarystringrequired
        • amountsobject | nullrequired

          Only in a review that shows managers amounts (manager_view amounts), from comp_worksheet_amounts or a save: current base pay, the new base pay proposed (as the server computes it, with the cycle's rounding) and the lump sum. Otherwise null.

          3 fields
          • baseobjectrequired
          • newobject | nullrequired
          • lump_sumnumber | nullrequired
      • missingintegerrequired

        Rows with pay and no proposal yet (Submit needs one per row; 0 % is a proposal).

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/upper.submit \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"cycle_id":"cy1","proposer_person_id":"p2"}'
Response
{
  "data": {
    "cycle": {
      "id": "cy1",
      "name": "Spring review",
      "stage": "proposing",
      "review_by": "2026-12-04"
    },
    "sheets": [
      {
        "proposer": {
          "id": "p2",
          "name": "Bea Silva"
        },
        "state": "sent",
        "over_budget_reason": null,
        "view": {
          "cycle": {
            "id": "cy1",
            "name": "Spring review",
            "stage": "proposing",
            "effective_date": "2027-01-01",
            "propose_by": "2026-11-27",
            "release_on": "2026-12-15",
            "manager_preview_on": "2026-12-11",
            "guidelines_changed_on": null
          },
          "state": "submitted",
          "submitted_at": null,
          "return_note": null,
          "editable": false,
          "why_not": "Submitted to HR: HR can send it back if something needs a change.",
          "manager_view": "percent",
          "amounts_shown": false,
          "budget": [
            {
              "currency": "EUR",
              "used_pct": 65,
              "over": false,
              "pool_pct": 3,
              "money": null,
              "promotion": {
                "used_pct": 0,
                "over": false,
                "pool_pct": 1,
                "money": null
              },
              "lump": {
                "used_pct": 10,
                "over": false,
                "money": null
              }
            }
          ],
          "rows": [
            {
              "id": "cy1:p3",
              "person": {
                "id": "p3",
                "name": "Dina Silva"
              },
              "title": "Engineer",
              "team": "Engineering",
              "rating": {
                "value": 3,
                "label": "Meets expectations"
              },
              "cr_band": {
                "col": "c2",
                "label": "1.00–1.09"
              },
              "range_pos": 50,
              "flags": [],
              "guideline": {
                "min": 2,
                "target": 3,
                "max": 4,
                "to_min": false,
                "lump": false
              },
              "protected_floor": null,
              "proposal": {
                "pct": 3,
                "reason": null,
                "reason_text": null,
                "comment": null,
                "lump_sum_pct": null
              },
              "lump_ok": true,
              "needs_reason": null,
              "state": "draft",
              "outcome": null,
              "summary": "Dina Silva, compa-ratio band 1.00–1.09, guideline 2 to 4 %, proposed 3 %",
              "amounts": null
            }
          ],
          "missing": 0
        }
      }
    ]
  }
}

Send a worksheet back to its manager#

POST/v1/comp/upper.returnWrite

Sends a worksheet waiting for you (the upper-manager step) back to its manager with a note: they change it and submit it again (it comes back to you). They get an email without amounts. 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. Team worksheets are checked in the app only.
MCP tool
comp_upper_return on My Workplace
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • cycle_idstringrequired
  • proposer_person_idstringrequired
  • notestringrequired

    1–500 characters.

Returns

  • cycleobjectrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • stagestringrequired
    • review_bystringrequired
  • sheetsobject[]required
    4 fields
    • proposerobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • state"waiting" | "sent" | "returned" | "open"required

      waiting: for you to check; sent: sent on to HR; returned: back with its manager; open: not submitted yet.

    • over_budget_reasonstring | nullrequired
    • viewobjectrequired

      The worksheet as its manager sees it: % only, never salaries.

      11 fields
      • cycleobjectrequired
        8 fields
        • idstringrequired
        • namestringrequired
        • stagestringrequired
        • effective_datestringrequired
        • propose_bystringrequired
        • release_onstringrequired
        • manager_preview_onstringrequired
        • guidelines_changed_onstring | nullrequired
      • state"draft" | "submitted" | "returned"required
      • submitted_atstring | nullrequired
      • return_notestring | nullrequired
      • editablebooleanrequired
      • why_notstring | nullrequired
      • manager_view"percent" | "amounts"required

        What this review shows managers (D15): percent (default), or amounts — then pay comes only from comp_worksheet_amounts (each view recorded in Activity) and saves.

      • amounts_shownbooleanrequired

        This answer carries amounts (rows[].amounts, budget[].money).

      • budgetobject[]required
        7 fields
        • currencystringrequired
        • used_pctnumberrequired
        • overbooleanrequired
        • pool_pctnumberrequired
        • moneyobject | nullrequired
          3 fields
          • budgetnumberrequired
          • spentnumberrequired
          • remainingnumberrequired
        • promotionobject | nullrequired
          4 fields
          • used_pctnumberrequired
          • overbooleanrequired
          • pool_pctnumberrequired
          • moneyobject | nullrequired
        • lumpobject | nullrequired
          3 fields
          • used_pctnumberrequired
          • overbooleanrequired
          • moneyobject | nullrequired
      • rowsobject[]required
        17 fields
        • idstringrequired
        • personobjectrequired
          2 fields
          • idstringrequired
          • namestringrequired
        • titlestring | nullrequired
        • teamstring | nullrequired
        • ratingobject | nullrequired
          2 fields
          • valuenumberrequired
          • labelstringrequired
        • cr_bandobjectrequired
          2 fields
          • colstringrequired
          • labelstringrequired
        • range_posnumber | nullrequired

          Where pay sits in the band, in tenths: 0 = minimum, 100 = maximum (can be below 0 or above 100).

        • flags"no_pay" | "no_band" | "below_min" | "above_max" | "new_joiner" | "protected_leave"[]required
        • guidelineobjectrequired
          5 fields
          • minnumberrequired
          • targetnumberrequired
          • maxnumberrequired
          • to_minbooleanrequired
          • lumpbooleanrequired

            Pay above the band maximum: the guideline's raise is suggested as a one-off lump sum (lump_sum_pct) instead of a base increase; base and lump sum together are checked against the range.

        • proposalobject | nullrequired
          5 fields
          • pctnumberrequired
          • reason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"required
          • reason_textstring | nullrequired
          • commentstring | nullrequired
          • lump_sum_pctnumber | nullrequired
        • protected_floornumber | nullrequired

          On protected leave (maternity, paternity, parental, adoption) in the review period: the lowest % you can propose, the raise as if they had been at work; only HR can record an objective reason for less. Null for everyone else.

        • lump_okbooleanrequired
        • needs_reasonstring | nullrequired
        • state"draft" | "submitted" | "returned"required
        • outcomeobject | nullrequired
          3 fields
          • pctnumber | nullrequired
          • lump_sum_pctnumber | nullrequired
          • includedbooleanrequired
        • summarystringrequired
        • amountsobject | nullrequired

          Only in a review that shows managers amounts (manager_view amounts), from comp_worksheet_amounts or a save: current base pay, the new base pay proposed (as the server computes it, with the cycle's rounding) and the lump sum. Otherwise null.

          3 fields
          • baseobjectrequired
          • newobject | nullrequired
          • lump_sumnumber | nullrequired
      • missingintegerrequired

        Rows with pay and no proposal yet (Submit needs one per row; 0 % is a proposal).

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/upper.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": "Check Dina against her peers"
}'
Response
{
  "data": {
    "cycle": {
      "id": "cy1",
      "name": "Spring review",
      "stage": "proposing",
      "review_by": "2026-12-04"
    },
    "sheets": [
      {
        "proposer": {
          "id": "p2",
          "name": "Bea Silva"
        },
        "state": "returned",
        "over_budget_reason": null,
        "view": {
          "cycle": {
            "id": "cy1",
            "name": "Spring review",
            "stage": "proposing",
            "effective_date": "2027-01-01",
            "propose_by": "2026-11-27",
            "release_on": "2026-12-15",
            "manager_preview_on": "2026-12-11",
            "guidelines_changed_on": null
          },
          "state": "returned",
          "submitted_at": null,
          "return_note": null,
          "editable": false,
          "why_not": "Your team lead is still working on it.",
          "manager_view": "percent",
          "amounts_shown": false,
          "budget": [
            {
              "currency": "EUR",
              "used_pct": 65,
              "over": false,
              "pool_pct": 3,
              "money": null,
              "promotion": {
                "used_pct": 0,
                "over": false,
                "pool_pct": 1,
                "money": null
              },
              "lump": {
                "used_pct": 10,
                "over": false,
                "money": null
              }
            }
          ],
          "rows": [
            {
              "id": "cy1:p3",
              "person": {
                "id": "p3",
                "name": "Dina Silva"
              },
              "title": "Engineer",
              "team": "Engineering",
              "rating": {
                "value": 3,
                "label": "Meets expectations"
              },
              "cr_band": {
                "col": "c2",
                "label": "1.00–1.09"
              },
              "range_pos": 50,
              "flags": [],
              "guideline": {
                "min": 2,
                "target": 3,
                "max": 4,
                "to_min": false,
                "lump": false
              },
              "protected_floor": null,
              "proposal": {
                "pct": 3,
                "reason": null,
                "reason_text": null,
                "comment": null,
                "lump_sum_pct": null
              },
              "lump_ok": true,
              "needs_reason": null,
              "state": "draft",
              "outcome": null,
              "summary": "Dina Silva, compa-ratio band 1.00–1.09, guideline 2 to 4 %, proposed 3 %",
              "amounts": null
            }
          ],
          "missing": 0
        }
      }
    ]
  }
}

My pay letters#

POST/v1/comp/letters.mineRead

Your pay letters, once released: salary review letters (the review's name, when it was released, the effective date and whether your pay changed) and bonus letters (the plan's name, the payout day, whether a bonus is paid). Open one with comp_letters_get. In the app only (they hold pay). 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. Letters hold pay: read in the app only.
MCP tool
comp_letters_mine on My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • itemsobject[]required
    6 fields
    • idstringrequired
    • kind"salary" | "bonus"required

      A salary review letter, or a bonus plan's award letter.

    • cyclestringrequired

      The salary review's or the bonus plan's name.

    • released_onstringrequired
    • effective_datestringrequired

      Salary review: when the new pay applies. Bonus: the payout day.

    • changebooleanrequired

      Base pay changes, or a one-off amount (lump sum or bonus) is paid.

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/letters.mine \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "items": [
      {
        "id": "bp1:p3",
        "kind": "bonus",
        "cycle": "2026 bonus",
        "released_on": "2027-01-31",
        "effective_date": "2027-01-31",
        "change": true
      },
      {
        "id": "cy1:p3",
        "kind": "salary",
        "cycle": "Spring review",
        "released_on": "2026-12-15",
        "effective_date": "2027-01-01",
        "change": true
      }
    ]
  }
}

Read a pay letter#

POST/v1/comp/letters.getRead

One of your pay letters. A salary review letter: your base pay before and after (in its own period, e.g. a month), the % change, any one-off lump sum, the effective date and your manager's name; or no change this year; with Documents on, also the letter as a PDF in My documents (document). A bonus letter (kind bonus): the gross bonus, the payout day, how it is paid and how the formula worked it out (target %, company factor, rating factor, goals, share of the period). Yours only, 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. Letters hold pay: read in the app only.
MCP tool
comp_letters_get on My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • idstringrequired

Returns

13 fields
  • idstringrequired
  • kind"salary" | "bonus"required

    A salary review letter, or a bonus plan's award letter.

  • cyclestringrequired

    The salary review's or the bonus plan's name.

  • released_onstringrequired
  • effective_datestringrequired

    Salary review: when the new pay applies. Bonus: the payout day.

  • changebooleanrequired

    Base pay changes, or a one-off amount (lump sum or bonus) is paid.

  • oldobject | nullrequired
    3 fields
    • amountnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
  • newobject | nullrequired
    3 fields
    • amountnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
  • pctnumberrequired
  • manager_namestring | nullrequired
  • lump_sumobject | nullrequired

    A one-off payment (gross) with this review, paid once through payroll.

    2 fields
    • amountnumberrequired
    • currencystringrequired
  • bonusobject | nullrequired

    A bonus plan's award letter (kind bonus); null for a salary review letter.

    6 fields
    • amountnumberrequired

      Gross bonus, in its currency (0: no bonus this time).

    • currencystringrequired
    • periodobjectrequired
      2 fields
      • fromstringrequired
      • tostringrequired
    • payout_onstringrequired
    • paid"payroll" | "by_hand"required

      With your pay (payroll) or paid separately (by_hand); null at 0.

    • workingobjectrequired

      How it was worked out: % of your annual base, the company and individual factors, the share of the period, and whether it was adjusted from the formula.

      11 fields
      • target_pctnumberrequired
      • company_pctnumberrequired
      • rating_labelstring | nullrequired
      • rating_pctnumberrequired
      • goals_pctnumber | nullrequired
      • goals_weightnumberrequired
      • individual_pctnumberrequired
      • daysintegerrequired
      • period_daysintegerrequired
      • prorationnumberrequired
      • adjustedbooleanrequired
  • documentobject | nullrequired

    With Documents on: the letter as a PDF in My documents (ready, with its document id to download it with documents_me_download), or still being prepared. Null: in-app only.

    2 fields
    • status"ready" | "preparing"required
    • document_idstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/letters.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"cy1:p3"}'
Response
{
  "data": {
    "id": "cy1:p3",
    "kind": "salary",
    "cycle": "Spring review",
    "released_on": "2026-12-15",
    "effective_date": "2027-01-01",
    "change": true,
    "old": {
      "amount": 50000,
      "currency": "EUR",
      "period": "year"
    },
    "new": {
      "amount": 51500,
      "currency": "EUR",
      "period": "year"
    },
    "pct": 3,
    "manager_name": "Bea Silva",
    "lump_sum": {
      "amount": 1000,
      "currency": "EUR"
    },
    "document": {
      "status": "ready",
      "document_id": "doc1"
    },
    "bonus": null
  }
}

How bonuses are worked out#

POST/v1/comp/me.bonus_criteriaRead

The formulas of bonus plans HR published to staff (EU Pay Transparency Directive art. 6, addendum B3): per plan, its name, period and payout day, the target % (and per job title), the company factor (null: not set yet), the factor per rating level and without a rating, the goals weight (committed goals only), the cap, how proration works and the rounding, as % only: never amounts. Plans published and not yet released, or released in the last year. For everyone at the company. 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
Me key owner admin hr member
MCP tool
comp_me_bonus_criteria on My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • itemsobject[]required
    11 fields
    • idstringrequired
    • namestringrequired
    • periodobjectrequired
      2 fields
      • fromstringrequired
      • tostringrequired
    • payout_onstringrequired
    • targetobjectrequired
      2 fields
      • default_pctnumberrequired
      • by_titleobject[]required
        2 fields
        • titlestringrequired
        • pctnumberrequired
    • company_factornumber | nullrequired
    • by_ratingobject[]required
      2 fields
      • labelstringrequired
      • pctnumberrequired
    • no_rating_pctnumberrequired
    • goals_weightnumberrequired
    • capnumberrequired
    • other_unpaid_leave"counted" | "not_counted"required

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/me.bonus_criteria \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "items": [
      {
        "id": "bp1",
        "name": "2026 bonus",
        "period": {
          "from": "2026-01-01",
          "to": "2026-12-31"
        },
        "payout_on": "2027-01-31",
        "target": {
          "default_pct": 10,
          "by_title": []
        },
        "company_factor": 100,
        "by_rating": [
          {
            "label": "Well below expectations",
            "pct": 0
          },
          {
            "label": "Below expectations",
            "pct": 50
          },
          {
            "label": "Meets expectations",
            "pct": 100
          },
          {
            "label": "Exceeds expectations",
            "pct": 120
          },
          {
            "label": "Outstanding",
            "pct": 150
          }
        ],
        "no_rating_pct": 100,
        "goals_weight": 0,
        "cap": 200,
        "other_unpaid_leave": "counted"
      }
    ]
  }
}

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

Developer docs