Skip to content

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

Input

No input: send {}.

Returns

  • itemsobject[]required
    7 fields
    • idstringrequired
    • namestringrequired
    • stagestring (enum)required

      One of: draft, launching, proposing, review, preview, releasing, released, cancelled.

    • effective_datestringrequired
    • datesobjectrequired
      4 fields
      • propose_bystringrequired
      • review_bystringrequired
      • manager_preview_onstringrequired
      • release_onstringrequired
    • worksheet"draft" | "submitted" | "returned"required
    • sign_off"waiting" | "signed" | "sent_back"required

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/cycles.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • cycle_idstringrequired

Returns

26 fields
  • idstringrequired
  • namestringrequired
  • statusstringrequired
  • stagestring (enum)required

    One of: draft, launching, proposing, review, preview, releasing, released, cancelled.

  • populationobjectrequired
    5 fields (one of several shapes)

    Option 1

    • kind"company"required

    Option 2

    • kind"units"required
    • unit_idsstring[]required

      1–200 items.

    Option 3

    • kind"entities"required
    • entity_idsstring[]required

      1–50 items.

  • eligibilityobjectrequired
    3 fields
    • cutoff_datestringrequired
    • employment_typesstring[]required
    • new_joiners"exclude" | "prorate"required
  • effective_datestringrequired
  • datesobjectrequired
    4 fields
    • propose_bystringrequired
    • review_bystringrequired
    • manager_preview_onstringrequired
    • release_onstringrequired
  • manager_view"percent" | "amounts"required
  • stepsobjectrequired
    2 fields
    • upper_reviewbooleanrequired

      A submitted worksheet goes to the manager's own manager before HR (D6).

    • final_sign_offbooleanrequired

      The release needs a final sign-off of the totals (D8).

  • sign_offobject | nullrequired

    The final sign-off: signed, or sent back to HR with a note; null: waiting (or not required).

    3 fields
    • state"signed" | "sent_back"required
    • atstringrequired
    • notestring | nullrequired
  • 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
  • poolsobjectrequired
    4 fields
    • merit_pctnumberrequired
    • overridesobject[]required
      2 fields
      • unit_idstringrequired
      • merit_pctnumberrequired
    • promotion_pctnumber | nullrequired
    • lump_sum_by_currencyobject | nullrequired
  • rating_cycle_idstring | nullrequired
  • no_change_lettersbooleanrequired
  • criteriaobjectrequired
    2 fields
    • published_atstring | nullrequired
    • shared_otherwise_atstring | nullrequired
  • launchobject | nullrequired
    2 fields
    • doneintegerrequired
    • totalintegerrequired
  • progressobjectrequired
    4 fields
    • participantsintegerrequired
    • releasedintegerrequired
    • skippedintegerrequired
    • staleintegerrequired
  • countsobjectrequired
    7 fields
    • draftintegerrequired
    • submittedintegerrequired
    • approvedintegerrequired
    • returnedintegerrequired
    • staleintegerrequired
    • skippedintegerrequired
    • releasedintegerrequired
  • worksheetsobjectrequired
    2 fields
    • totalintegerrequired
    • submittedintegerrequired
  • budgetsobject[]required
    9 fields
    • currencystringrequired
    • eligiblenumberrequired
    • budgetnumberrequired
    • spentnumberrequired
    • remainingnumberrequired
    • overbooleanrequired
    • used_pctnumberrequired
    • promotionobject | nullrequired

      The promotion pool (raises whose reason is promotion_pending), when the cycle has one.

      5 fields
      • budgetnumberrequired
      • spentnumberrequired
      • remainingnumberrequired
      • overbooleanrequired
      • used_pctnumberrequired
    • lumpobject | nullrequired

      The lump-sum pool (one-off payments), when the cycle has one for this currency.

      5 fields
      • budgetnumberrequired
      • spentnumberrequired
      • remainingnumberrequired
      • overbooleanrequired
      • used_pctnumberrequired
  • releaseobjectrequired
    6 fields
    • writeintegerrequired
    • no_changeintegerrequired
    • skipintegerrequired
    • staleintegerrequired
    • doneintegerrequired
    • lump_sumsintegerrequired
  • lump_sumsobject | nullrequired

    Lump 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
    • countintegerrequired
    • totalsobject[]required
      2 fields
      • currencystringrequired
      • amountnumberrequired
    • in_payrollintegerrequired
    • by_handintegerrequired
    • paidintegerrequired
  • lettersobject | nullrequired

    With 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
    • totalintegerrequired
    • in_documentsintegerrequired
    • waitingintegerrequired
    • blockedintegerrequired
  • created_atstringrequired
  • released_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

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

Input

  • namestringrequired

    1–120 characters.

  • populationobject

    Default {"kind":"company"}.

    5 fields (one of several shapes)

    Option 1

    • kind"company"required

    Option 2

    • kind"units"required
    • unit_idsstring[]required

      1–200 items.

    Option 3

    • kind"entities"required
    • entity_idsstring[]required

      1–50 items.

  • eligibilityobject

    Default {}.

    3 fields
    • cutoff_datestring

      Employed 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_datestringrequired

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

  • datesobjectrequired
    4 fields
    • propose_bystringrequired

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

    • review_bystringrequired

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

    • manager_preview_onstring

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

    • release_onstringrequired

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

  • guidelineobject
    6 fields
    • rating_levelsobject[]required

      1–9 items.

      2 fields
      • valueintegerrequired

        From -10 to 20.

      • labelstringrequired

        1–60 characters.

    • cr_boundsnumber[]required

      From 0.3 to 3. 1–6 items.

    • cellsobject[]required

      Up to 50 items.

      5 fields
      • rowstringrequired

        Pattern ^(r-?\d+|none)$.

      • colstringrequired

        Pattern ^(c\d+|nb)$.

      • minnumberrequired

        From 0 to 100.

      • targetnumberrequired

        From 0 to 100.

      • maxnumberrequired

        From 0 to 100.

    • bring_to_minbooleanrequired
    • lump_above_maxboolean

      Pay 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
  • poolsobject

    Default {"merit_pct":3}.

    4 fields
    • merit_pctnumberrequired

      The merit pool, % of the eligible annual base (e.g. 3).

      From 0 to 100.

    • overridesobject[]

      Up to 200 items.

      2 fields
      • unit_idstringrequired
      • merit_pctnumberrequired

        From 0 to 100.

    • promotion_pctnumber | null

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

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

    1–200 characters.

  • no_change_lettersboolean

    Default true.

  • stepsobject
    2 fields
    • upper_reviewboolean

      Upper-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_offboolean

      Final 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

  • cycleobjectrequired
    26 fields
    • idstringrequired
    • namestringrequired
    • statusstringrequired
    • stagestring (enum)required

      One of: draft, launching, proposing, review, preview, releasing, released, cancelled.

    • populationobjectrequired
      5 fields (one of several shapes)

      Option 1

      • kind"company"required

      Option 2

      • kind"units"required
      • unit_idsstring[]required

        1–200 items.

      Option 3

      • kind"entities"required
      • entity_idsstring[]required

        1–50 items.

    • eligibilityobjectrequired
      3 fields
      • cutoff_datestringrequired
      • employment_typesstring[]required
      • new_joiners"exclude" | "prorate"required
    • effective_datestringrequired
    • datesobjectrequired
      4 fields
      • propose_bystringrequired
      • review_bystringrequired
      • manager_preview_onstringrequired
      • release_onstringrequired
    • manager_view"percent" | "amounts"required
    • stepsobjectrequired
      2 fields
      • upper_reviewbooleanrequired

        A submitted worksheet goes to the manager's own manager before HR (D6).

      • final_sign_offbooleanrequired

        The release needs a final sign-off of the totals (D8).

    • sign_offobject | nullrequired

      The final sign-off: signed, or sent back to HR with a note; null: waiting (or not required).

      3 fields
      • state"signed" | "sent_back"required
      • atstringrequired
      • notestring | nullrequired
    • 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
    • poolsobjectrequired
      4 fields
      • merit_pctnumberrequired
      • overridesobject[]required
        2 fields
        • unit_idstringrequired
        • merit_pctnumberrequired
      • promotion_pctnumber | nullrequired
      • lump_sum_by_currencyobject | nullrequired
    • rating_cycle_idstring | nullrequired
    • no_change_lettersbooleanrequired
    • criteriaobjectrequired
      2 fields
      • published_atstring | nullrequired
      • shared_otherwise_atstring | nullrequired
    • launchobject | nullrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • progressobjectrequired
      4 fields
      • participantsintegerrequired
      • releasedintegerrequired
      • skippedintegerrequired
      • staleintegerrequired
    • countsobjectrequired
      7 fields
      • draftintegerrequired
      • submittedintegerrequired
      • approvedintegerrequired
      • returnedintegerrequired
      • staleintegerrequired
      • skippedintegerrequired
      • releasedintegerrequired
    • worksheetsobjectrequired
      2 fields
      • totalintegerrequired
      • submittedintegerrequired
    • budgetsobject[]required
      9 fields
      • currencystringrequired
      • eligiblenumberrequired
      • budgetnumberrequired
      • spentnumberrequired
      • remainingnumberrequired
      • overbooleanrequired
      • used_pctnumberrequired
      • promotionobject | nullrequired

        The promotion pool (raises whose reason is promotion_pending), when the cycle has one.

        5 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired
      • lumpobject | nullrequired

        The lump-sum pool (one-off payments), when the cycle has one for this currency.

        5 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired
    • releaseobjectrequired
      6 fields
      • writeintegerrequired
      • no_changeintegerrequired
      • skipintegerrequired
      • staleintegerrequired
      • doneintegerrequired
      • lump_sumsintegerrequired
    • lump_sumsobject | nullrequired

      Lump 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
      • countintegerrequired
      • totalsobject[]required
        2 fields
        • currencystringrequired
        • amountnumberrequired
      • in_payrollintegerrequired
      • by_handintegerrequired
      • paidintegerrequired
    • lettersobject | nullrequired

      With 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
      • totalintegerrequired
      • in_documentsintegerrequired
      • waitingintegerrequired
      • blockedintegerrequired
    • created_atstringrequired
    • released_atstring | nullrequired
  • previewobjectrequired
    5 fields
    • peopleintegerrequired
    • eligibleintegerrequired
    • excludedobjectrequired
      3 fields
      • not_employedintegerrequired
      • after_cutoffintegerrequired
      • employment_typeintegerrequired
    • flagsobjectrequired
      6 fields
      • no_payintegerrequired
      • no_bandintegerrequired
      • below_minintegerrequired
      • above_maxintegerrequired
      • new_joinerintegerrequired
      • other_currencyintegerrequired
    • budgetsobject[]required
      9 fields
      • currencystringrequired
      • eligiblenumberrequired
      • budgetnumberrequired
      • spentnumberrequired
      • remainingnumberrequired
      • overbooleanrequired
      • used_pctnumberrequired
      • promotionobject | nullrequired

        The promotion pool (raises whose reason is promotion_pending), when the cycle has one.

        5 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired
      • lumpobject | nullrequired

        The lump-sum pool (one-off payments), when the cycle has one for this currency.

        5 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

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

Input

  • cycle_idstringrequired
  • namestring

    1–120 characters.

  • populationobject
    5 fields (one of several shapes)

    Option 1

    • kind"company"required

    Option 2

    • kind"units"required
    • unit_idsstring[]required

      1–200 items.

    Option 3

    • kind"entities"required
    • entity_idsstring[]required

      1–50 items.

  • eligibilityobject
    3 fields
    • cutoff_datestring

      Employed 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_datestring

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

  • datesobject
    4 fields
    • propose_bystringrequired

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

    • review_bystringrequired

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

    • manager_preview_onstring

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

    • release_onstringrequired

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

  • guidelineobject
    6 fields
    • rating_levelsobject[]required

      1–9 items.

      2 fields
      • valueintegerrequired

        From -10 to 20.

      • labelstringrequired

        1–60 characters.

    • cr_boundsnumber[]required

      From 0.3 to 3. 1–6 items.

    • cellsobject[]required

      Up to 50 items.

      5 fields
      • rowstringrequired

        Pattern ^(r-?\d+|none)$.

      • colstringrequired

        Pattern ^(c\d+|nb)$.

      • minnumberrequired

        From 0 to 100.

      • targetnumberrequired

        From 0 to 100.

      • maxnumberrequired

        From 0 to 100.

    • bring_to_minbooleanrequired
    • lump_above_maxboolean

      Pay 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
  • poolsobject
    4 fields
    • merit_pctnumberrequired

      The merit pool, % of the eligible annual base (e.g. 3).

      From 0 to 100.

    • overridesobject[]

      Up to 200 items.

      2 fields
      • unit_idstringrequired
      • merit_pctnumberrequired

        From 0 to 100.

    • promotion_pctnumber | null

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

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

    1–200 characters.

  • no_change_lettersboolean
  • stepsobject
    2 fields
    • upper_reviewboolean

      Upper-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_offboolean

      Final 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

  • cycleobjectrequired
    26 fields
    • idstringrequired
    • namestringrequired
    • statusstringrequired
    • stagestring (enum)required

      One of: draft, launching, proposing, review, preview, releasing, released, cancelled.

    • populationobjectrequired
      5 fields (one of several shapes)

      Option 1

      • kind"company"required

      Option 2

      • kind"units"required
      • unit_idsstring[]required

        1–200 items.

      Option 3

      • kind"entities"required
      • entity_idsstring[]required

        1–50 items.

    • eligibilityobjectrequired
      3 fields
      • cutoff_datestringrequired
      • employment_typesstring[]required
      • new_joiners"exclude" | "prorate"required
    • effective_datestringrequired
    • datesobjectrequired
      4 fields
      • propose_bystringrequired
      • review_bystringrequired
      • manager_preview_onstringrequired
      • release_onstringrequired
    • manager_view"percent" | "amounts"required
    • stepsobjectrequired
      2 fields
      • upper_reviewbooleanrequired

        A submitted worksheet goes to the manager's own manager before HR (D6).

      • final_sign_offbooleanrequired

        The release needs a final sign-off of the totals (D8).

    • sign_offobject | nullrequired

      The final sign-off: signed, or sent back to HR with a note; null: waiting (or not required).

      3 fields
      • state"signed" | "sent_back"required
      • atstringrequired
      • notestring | nullrequired
    • 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
    • poolsobjectrequired
      4 fields
      • merit_pctnumberrequired
      • overridesobject[]required
        2 fields
        • unit_idstringrequired
        • merit_pctnumberrequired
      • promotion_pctnumber | nullrequired
      • lump_sum_by_currencyobject | nullrequired
    • rating_cycle_idstring | nullrequired
    • no_change_lettersbooleanrequired
    • criteriaobjectrequired
      2 fields
      • published_atstring | nullrequired
      • shared_otherwise_atstring | nullrequired
    • launchobject | nullrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • progressobjectrequired
      4 fields
      • participantsintegerrequired
      • releasedintegerrequired
      • skippedintegerrequired
      • staleintegerrequired
    • countsobjectrequired
      7 fields
      • draftintegerrequired
      • submittedintegerrequired
      • approvedintegerrequired
      • returnedintegerrequired
      • staleintegerrequired
      • skippedintegerrequired
      • releasedintegerrequired
    • worksheetsobjectrequired
      2 fields
      • totalintegerrequired
      • submittedintegerrequired
    • budgetsobject[]required
      9 fields
      • currencystringrequired
      • eligiblenumberrequired
      • budgetnumberrequired
      • spentnumberrequired
      • remainingnumberrequired
      • overbooleanrequired
      • used_pctnumberrequired
      • promotionobject | nullrequired

        The promotion pool (raises whose reason is promotion_pending), when the cycle has one.

        5 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired
      • lumpobject | nullrequired

        The lump-sum pool (one-off payments), when the cycle has one for this currency.

        5 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired
    • releaseobjectrequired
      6 fields
      • writeintegerrequired
      • no_changeintegerrequired
      • skipintegerrequired
      • staleintegerrequired
      • doneintegerrequired
      • lump_sumsintegerrequired
    • lump_sumsobject | nullrequired

      Lump 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
      • countintegerrequired
      • totalsobject[]required
        2 fields
        • currencystringrequired
        • amountnumberrequired
      • in_payrollintegerrequired
      • by_handintegerrequired
      • paidintegerrequired
    • lettersobject | nullrequired

      With 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
      • totalintegerrequired
      • in_documentsintegerrequired
      • waitingintegerrequired
      • blockedintegerrequired
    • created_atstringrequired
    • released_atstring | nullrequired
  • previewobject | nullrequired
    5 fields
    • peopleintegerrequired
    • eligibleintegerrequired
    • excludedobjectrequired
      3 fields
      • not_employedintegerrequired
      • after_cutoffintegerrequired
      • employment_typeintegerrequired
    • flagsobjectrequired
      6 fields
      • no_payintegerrequired
      • no_bandintegerrequired
      • below_minintegerrequired
      • above_maxintegerrequired
      • new_joinerintegerrequired
      • other_currencyintegerrequired
    • budgetsobject[]required
      9 fields
      • currencystringrequired
      • eligiblenumberrequired
      • budgetnumberrequired
      • spentnumberrequired
      • remainingnumberrequired
      • overbooleanrequired
      • used_pctnumberrequired
      • promotionobject | nullrequired

        The promotion pool (raises whose reason is promotion_pending), when the cycle has one.

        5 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired
      • lumpobject | nullrequired

        The lump-sum pool (one-off payments), when the cycle has one for this currency.

        5 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

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

Input

  • cycle_idstringrequired
  • shared_otherwiseboolean
  • unpublishboolean

Returns

26 fields
  • idstringrequired
  • namestringrequired
  • statusstringrequired
  • stagestring (enum)required

    One of: draft, launching, proposing, review, preview, releasing, released, cancelled.

  • populationobjectrequired
    5 fields (one of several shapes)

    Option 1

    • kind"company"required

    Option 2

    • kind"units"required
    • unit_idsstring[]required

      1–200 items.

    Option 3

    • kind"entities"required
    • entity_idsstring[]required

      1–50 items.

  • eligibilityobjectrequired
    3 fields
    • cutoff_datestringrequired
    • employment_typesstring[]required
    • new_joiners"exclude" | "prorate"required
  • effective_datestringrequired
  • datesobjectrequired
    4 fields
    • propose_bystringrequired
    • review_bystringrequired
    • manager_preview_onstringrequired
    • release_onstringrequired
  • manager_view"percent" | "amounts"required
  • stepsobjectrequired
    2 fields
    • upper_reviewbooleanrequired

      A submitted worksheet goes to the manager's own manager before HR (D6).

    • final_sign_offbooleanrequired

      The release needs a final sign-off of the totals (D8).

  • sign_offobject | nullrequired

    The final sign-off: signed, or sent back to HR with a note; null: waiting (or not required).

    3 fields
    • state"signed" | "sent_back"required
    • atstringrequired
    • notestring | nullrequired
  • 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
  • poolsobjectrequired
    4 fields
    • merit_pctnumberrequired
    • overridesobject[]required
      2 fields
      • unit_idstringrequired
      • merit_pctnumberrequired
    • promotion_pctnumber | nullrequired
    • lump_sum_by_currencyobject | nullrequired
  • rating_cycle_idstring | nullrequired
  • no_change_lettersbooleanrequired
  • criteriaobjectrequired
    2 fields
    • published_atstring | nullrequired
    • shared_otherwise_atstring | nullrequired
  • launchobject | nullrequired
    2 fields
    • doneintegerrequired
    • totalintegerrequired
  • progressobjectrequired
    4 fields
    • participantsintegerrequired
    • releasedintegerrequired
    • skippedintegerrequired
    • staleintegerrequired
  • countsobjectrequired
    7 fields
    • draftintegerrequired
    • submittedintegerrequired
    • approvedintegerrequired
    • returnedintegerrequired
    • staleintegerrequired
    • skippedintegerrequired
    • releasedintegerrequired
  • worksheetsobjectrequired
    2 fields
    • totalintegerrequired
    • submittedintegerrequired
  • budgetsobject[]required
    9 fields
    • currencystringrequired
    • eligiblenumberrequired
    • budgetnumberrequired
    • spentnumberrequired
    • remainingnumberrequired
    • overbooleanrequired
    • used_pctnumberrequired
    • promotionobject | nullrequired

      The promotion pool (raises whose reason is promotion_pending), when the cycle has one.

      5 fields
      • budgetnumberrequired
      • spentnumberrequired
      • remainingnumberrequired
      • overbooleanrequired
      • used_pctnumberrequired
    • lumpobject | nullrequired

      The lump-sum pool (one-off payments), when the cycle has one for this currency.

      5 fields
      • budgetnumberrequired
      • spentnumberrequired
      • remainingnumberrequired
      • overbooleanrequired
      • used_pctnumberrequired
  • releaseobjectrequired
    6 fields
    • writeintegerrequired
    • no_changeintegerrequired
    • skipintegerrequired
    • staleintegerrequired
    • doneintegerrequired
    • lump_sumsintegerrequired
  • lump_sumsobject | nullrequired

    Lump 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
    • countintegerrequired
    • totalsobject[]required
      2 fields
      • currencystringrequired
      • amountnumberrequired
    • in_payrollintegerrequired
    • by_handintegerrequired
    • paidintegerrequired
  • lettersobject | nullrequired

    With 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
    • totalintegerrequired
    • in_documentsintegerrequired
    • waitingintegerrequired
    • blockedintegerrequired
  • created_atstringrequired
  • released_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

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

Input

  • cycle_idstringrequired

Returns

  • cycleobjectrequired
    26 fields
    • idstringrequired
    • namestringrequired
    • statusstringrequired
    • stagestring (enum)required

      One of: draft, launching, proposing, review, preview, releasing, released, cancelled.

    • populationobjectrequired
      5 fields (one of several shapes)

      Option 1

      • kind"company"required

      Option 2

      • kind"units"required
      • unit_idsstring[]required

        1–200 items.

      Option 3

      • kind"entities"required
      • entity_idsstring[]required

        1–50 items.

    • eligibilityobjectrequired
      3 fields
      • cutoff_datestringrequired
      • employment_typesstring[]required
      • new_joiners"exclude" | "prorate"required
    • effective_datestringrequired
    • datesobjectrequired
      4 fields
      • propose_bystringrequired
      • review_bystringrequired
      • manager_preview_onstringrequired
      • release_onstringrequired
    • manager_view"percent" | "amounts"required
    • stepsobjectrequired
      2 fields
      • upper_reviewbooleanrequired

        A submitted worksheet goes to the manager's own manager before HR (D6).

      • final_sign_offbooleanrequired

        The release needs a final sign-off of the totals (D8).

    • sign_offobject | nullrequired

      The final sign-off: signed, or sent back to HR with a note; null: waiting (or not required).

      3 fields
      • state"signed" | "sent_back"required
      • atstringrequired
      • notestring | nullrequired
    • 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
    • poolsobjectrequired
      4 fields
      • merit_pctnumberrequired
      • overridesobject[]required
        2 fields
        • unit_idstringrequired
        • merit_pctnumberrequired
      • promotion_pctnumber | nullrequired
      • lump_sum_by_currencyobject | nullrequired
    • rating_cycle_idstring | nullrequired
    • no_change_lettersbooleanrequired
    • criteriaobjectrequired
      2 fields
      • published_atstring | nullrequired
      • shared_otherwise_atstring | nullrequired
    • launchobject | nullrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • progressobjectrequired
      4 fields
      • participantsintegerrequired
      • releasedintegerrequired
      • skippedintegerrequired
      • staleintegerrequired
    • countsobjectrequired
      7 fields
      • draftintegerrequired
      • submittedintegerrequired
      • approvedintegerrequired
      • returnedintegerrequired
      • staleintegerrequired
      • skippedintegerrequired
      • releasedintegerrequired
    • worksheetsobjectrequired
      2 fields
      • totalintegerrequired
      • submittedintegerrequired
    • budgetsobject[]required
      9 fields
      • currencystringrequired
      • eligiblenumberrequired
      • budgetnumberrequired
      • spentnumberrequired
      • remainingnumberrequired
      • overbooleanrequired
      • used_pctnumberrequired
      • promotionobject | nullrequired

        The promotion pool (raises whose reason is promotion_pending), when the cycle has one.

        5 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired
      • lumpobject | nullrequired

        The lump-sum pool (one-off payments), when the cycle has one for this currency.

        5 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired
    • releaseobjectrequired
      6 fields
      • writeintegerrequired
      • no_changeintegerrequired
      • skipintegerrequired
      • staleintegerrequired
      • doneintegerrequired
      • lump_sumsintegerrequired
    • lump_sumsobject | nullrequired

      Lump 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
      • countintegerrequired
      • totalsobject[]required
        2 fields
        • currencystringrequired
        • amountnumberrequired
      • in_payrollintegerrequired
      • by_handintegerrequired
      • paidintegerrequired
    • lettersobject | nullrequired

      With 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
      • totalintegerrequired
      • in_documentsintegerrequired
      • waitingintegerrequired
      • blockedintegerrequired
    • created_atstringrequired
    • released_atstring | nullrequired
  • previewobjectrequired
    5 fields
    • peopleintegerrequired
    • eligibleintegerrequired
    • excludedobjectrequired
      3 fields
      • not_employedintegerrequired
      • after_cutoffintegerrequired
      • employment_typeintegerrequired
    • flagsobjectrequired
      6 fields
      • no_payintegerrequired
      • no_bandintegerrequired
      • below_minintegerrequired
      • above_maxintegerrequired
      • new_joinerintegerrequired
      • other_currencyintegerrequired
    • budgetsobject[]required
      9 fields
      • currencystringrequired
      • eligiblenumberrequired
      • budgetnumberrequired
      • spentnumberrequired
      • remainingnumberrequired
      • overbooleanrequired
      • used_pctnumberrequired
      • promotionobject | nullrequired

        The promotion pool (raises whose reason is promotion_pending), when the cycle has one.

        5 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired
      • lumpobject | nullrequired

        The lump-sum pool (one-off payments), when the cycle has one for this currency.

        5 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

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

Input

  • cycle_idstringrequired

Returns

  • cycleobjectrequired
    26 fields
    • idstringrequired
    • namestringrequired
    • statusstringrequired
    • stagestring (enum)required

      One of: draft, launching, proposing, review, preview, releasing, released, cancelled.

    • populationobjectrequired
      5 fields (one of several shapes)

      Option 1

      • kind"company"required

      Option 2

      • kind"units"required
      • unit_idsstring[]required

        1–200 items.

      Option 3

      • kind"entities"required
      • entity_idsstring[]required

        1–50 items.

    • eligibilityobjectrequired
      3 fields
      • cutoff_datestringrequired
      • employment_typesstring[]required
      • new_joiners"exclude" | "prorate"required
    • effective_datestringrequired
    • datesobjectrequired
      4 fields
      • propose_bystringrequired
      • review_bystringrequired
      • manager_preview_onstringrequired
      • release_onstringrequired
    • manager_view"percent" | "amounts"required
    • stepsobjectrequired
      2 fields
      • upper_reviewbooleanrequired

        A submitted worksheet goes to the manager's own manager before HR (D6).

      • final_sign_offbooleanrequired

        The release needs a final sign-off of the totals (D8).

    • sign_offobject | nullrequired

      The final sign-off: signed, or sent back to HR with a note; null: waiting (or not required).

      3 fields
      • state"signed" | "sent_back"required
      • atstringrequired
      • notestring | nullrequired
    • 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
    • poolsobjectrequired
      4 fields
      • merit_pctnumberrequired
      • overridesobject[]required
        2 fields
        • unit_idstringrequired
        • merit_pctnumberrequired
      • promotion_pctnumber | nullrequired
      • lump_sum_by_currencyobject | nullrequired
    • rating_cycle_idstring | nullrequired
    • no_change_lettersbooleanrequired
    • criteriaobjectrequired
      2 fields
      • published_atstring | nullrequired
      • shared_otherwise_atstring | nullrequired
    • launchobject | nullrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • progressobjectrequired
      4 fields
      • participantsintegerrequired
      • releasedintegerrequired
      • skippedintegerrequired
      • staleintegerrequired
    • countsobjectrequired
      7 fields
      • draftintegerrequired
      • submittedintegerrequired
      • approvedintegerrequired
      • returnedintegerrequired
      • staleintegerrequired
      • skippedintegerrequired
      • releasedintegerrequired
    • worksheetsobjectrequired
      2 fields
      • totalintegerrequired
      • submittedintegerrequired
    • budgetsobject[]required
      9 fields
      • currencystringrequired
      • eligiblenumberrequired
      • budgetnumberrequired
      • spentnumberrequired
      • remainingnumberrequired
      • overbooleanrequired
      • used_pctnumberrequired
      • promotionobject | nullrequired

        The promotion pool (raises whose reason is promotion_pending), when the cycle has one.

        5 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired
      • lumpobject | nullrequired

        The lump-sum pool (one-off payments), when the cycle has one for this currency.

        5 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired
    • releaseobjectrequired
      6 fields
      • writeintegerrequired
      • no_changeintegerrequired
      • skipintegerrequired
      • staleintegerrequired
      • doneintegerrequired
      • lump_sumsintegerrequired
    • lump_sumsobject | nullrequired

      Lump 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
      • countintegerrequired
      • totalsobject[]required
        2 fields
        • currencystringrequired
        • amountnumberrequired
      • in_payrollintegerrequired
      • by_handintegerrequired
      • paidintegerrequired
    • lettersobject | nullrequired

      With 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
      • totalintegerrequired
      • in_documentsintegerrequired
      • waitingintegerrequired
      • blockedintegerrequired
    • created_atstringrequired
    • released_atstring | nullrequired
  • handledintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/cycles.step \
  -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",
      "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_cancel on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • cycle_idstringrequired

Returns

26 fields
  • idstringrequired
  • namestringrequired
  • statusstringrequired
  • stagestring (enum)required

    One of: draft, launching, proposing, review, preview, releasing, released, cancelled.

  • populationobjectrequired
    5 fields (one of several shapes)

    Option 1

    • kind"company"required

    Option 2

    • kind"units"required
    • unit_idsstring[]required

      1–200 items.

    Option 3

    • kind"entities"required
    • entity_idsstring[]required

      1–50 items.

  • eligibilityobjectrequired
    3 fields
    • cutoff_datestringrequired
    • employment_typesstring[]required
    • new_joiners"exclude" | "prorate"required
  • effective_datestringrequired
  • datesobjectrequired
    4 fields
    • propose_bystringrequired
    • review_bystringrequired
    • manager_preview_onstringrequired
    • release_onstringrequired
  • manager_view"percent" | "amounts"required
  • stepsobjectrequired
    2 fields
    • upper_reviewbooleanrequired

      A submitted worksheet goes to the manager's own manager before HR (D6).

    • final_sign_offbooleanrequired

      The release needs a final sign-off of the totals (D8).

  • sign_offobject | nullrequired

    The final sign-off: signed, or sent back to HR with a note; null: waiting (or not required).

    3 fields
    • state"signed" | "sent_back"required
    • atstringrequired
    • notestring | nullrequired
  • 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
  • poolsobjectrequired
    4 fields
    • merit_pctnumberrequired
    • overridesobject[]required
      2 fields
      • unit_idstringrequired
      • merit_pctnumberrequired
    • promotion_pctnumber | nullrequired
    • lump_sum_by_currencyobject | nullrequired
  • rating_cycle_idstring | nullrequired
  • no_change_lettersbooleanrequired
  • criteriaobjectrequired
    2 fields
    • published_atstring | nullrequired
    • shared_otherwise_atstring | nullrequired
  • launchobject | nullrequired
    2 fields
    • doneintegerrequired
    • totalintegerrequired
  • progressobjectrequired
    4 fields
    • participantsintegerrequired
    • releasedintegerrequired
    • skippedintegerrequired
    • staleintegerrequired
  • countsobjectrequired
    7 fields
    • draftintegerrequired
    • submittedintegerrequired
    • approvedintegerrequired
    • returnedintegerrequired
    • staleintegerrequired
    • skippedintegerrequired
    • releasedintegerrequired
  • worksheetsobjectrequired
    2 fields
    • totalintegerrequired
    • submittedintegerrequired
  • budgetsobject[]required
    9 fields
    • currencystringrequired
    • eligiblenumberrequired
    • budgetnumberrequired
    • spentnumberrequired
    • remainingnumberrequired
    • overbooleanrequired
    • used_pctnumberrequired
    • promotionobject | nullrequired

      The promotion pool (raises whose reason is promotion_pending), when the cycle has one.

      5 fields
      • budgetnumberrequired
      • spentnumberrequired
      • remainingnumberrequired
      • overbooleanrequired
      • used_pctnumberrequired
    • lumpobject | nullrequired

      The lump-sum pool (one-off payments), when the cycle has one for this currency.

      5 fields
      • budgetnumberrequired
      • spentnumberrequired
      • remainingnumberrequired
      • overbooleanrequired
      • used_pctnumberrequired
  • releaseobjectrequired
    6 fields
    • writeintegerrequired
    • no_changeintegerrequired
    • skipintegerrequired
    • staleintegerrequired
    • doneintegerrequired
    • lump_sumsintegerrequired
  • lump_sumsobject | nullrequired

    Lump 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
    • countintegerrequired
    • totalsobject[]required
      2 fields
      • currencystringrequired
      • amountnumberrequired
    • in_payrollintegerrequired
    • by_handintegerrequired
    • paidintegerrequired
  • lettersobject | nullrequired

    With 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
    • totalintegerrequired
    • in_documentsintegerrequired
    • waitingintegerrequired
    • blockedintegerrequired
  • created_atstringrequired
  • released_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

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

Input

  • cycle_idstringrequired

Returns

  • cycleobjectrequired
    26 fields
    • idstringrequired
    • namestringrequired
    • statusstringrequired
    • stagestring (enum)required

      One of: draft, launching, proposing, review, preview, releasing, released, cancelled.

    • populationobjectrequired
      5 fields (one of several shapes)

      Option 1

      • kind"company"required

      Option 2

      • kind"units"required
      • unit_idsstring[]required

        1–200 items.

      Option 3

      • kind"entities"required
      • entity_idsstring[]required

        1–50 items.

    • eligibilityobjectrequired
      3 fields
      • cutoff_datestringrequired
      • employment_typesstring[]required
      • new_joiners"exclude" | "prorate"required
    • effective_datestringrequired
    • datesobjectrequired
      4 fields
      • propose_bystringrequired
      • review_bystringrequired
      • manager_preview_onstringrequired
      • release_onstringrequired
    • manager_view"percent" | "amounts"required
    • stepsobjectrequired
      2 fields
      • upper_reviewbooleanrequired

        A submitted worksheet goes to the manager's own manager before HR (D6).

      • final_sign_offbooleanrequired

        The release needs a final sign-off of the totals (D8).

    • sign_offobject | nullrequired

      The final sign-off: signed, or sent back to HR with a note; null: waiting (or not required).

      3 fields
      • state"signed" | "sent_back"required
      • atstringrequired
      • notestring | nullrequired
    • 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
    • poolsobjectrequired
      4 fields
      • merit_pctnumberrequired
      • overridesobject[]required
        2 fields
        • unit_idstringrequired
        • merit_pctnumberrequired
      • promotion_pctnumber | nullrequired
      • lump_sum_by_currencyobject | nullrequired
    • rating_cycle_idstring | nullrequired
    • no_change_lettersbooleanrequired
    • criteriaobjectrequired
      2 fields
      • published_atstring | nullrequired
      • shared_otherwise_atstring | nullrequired
    • launchobject | nullrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • progressobjectrequired
      4 fields
      • participantsintegerrequired
      • releasedintegerrequired
      • skippedintegerrequired
      • staleintegerrequired
    • countsobjectrequired
      7 fields
      • draftintegerrequired
      • submittedintegerrequired
      • approvedintegerrequired
      • returnedintegerrequired
      • staleintegerrequired
      • skippedintegerrequired
      • releasedintegerrequired
    • worksheetsobjectrequired
      2 fields
      • totalintegerrequired
      • submittedintegerrequired
    • budgetsobject[]required
      9 fields
      • currencystringrequired
      • eligiblenumberrequired
      • budgetnumberrequired
      • spentnumberrequired
      • remainingnumberrequired
      • overbooleanrequired
      • used_pctnumberrequired
      • promotionobject | nullrequired

        The promotion pool (raises whose reason is promotion_pending), when the cycle has one.

        5 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired
      • lumpobject | nullrequired

        The lump-sum pool (one-off payments), when the cycle has one for this currency.

        5 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired
    • releaseobjectrequired
      6 fields
      • writeintegerrequired
      • no_changeintegerrequired
      • skipintegerrequired
      • staleintegerrequired
      • doneintegerrequired
      • lump_sumsintegerrequired
    • lump_sumsobject | nullrequired

      Lump 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
      • countintegerrequired
      • totalsobject[]required
        2 fields
        • currencystringrequired
        • amountnumberrequired
      • in_payrollintegerrequired
      • by_handintegerrequired
      • paidintegerrequired
    • lettersobject | nullrequired

      With 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
      • totalintegerrequired
      • in_documentsintegerrequired
      • waitingintegerrequired
      • blockedintegerrequired
    • created_atstringrequired
    • released_atstring | nullrequired
  • planobjectrequired
    6 fields
    • writeintegerrequired
    • no_changeintegerrequired
    • skipintegerrequired
    • staleintegerrequired
    • doneintegerrequired
    • lump_sumsintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

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

Input

  • cycle_idstringrequired

Returns

  • filenamestringrequired
  • csvstringrequired
  • rowsintegerrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/cycles.export \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cycle_id":"cy1"}'
Response
{
  "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_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • cycle_idstringrequired

Returns

11 fields
  • cycleobjectrequired
    5 fields
    • idstringrequired
    • namestringrequired
    • stagestringrequired
    • effective_datestringrequired
    • release_onstringrequired
  • requiredbooleanrequired

    The review needs its final sign-off before the release (steps.final_sign_off).

  • state"waiting" | "signed" | "sent_back"required
  • bystring | nullrequired

    Who signed off or sent it back.

  • atstring | nullrequired
  • notestring | nullrequired
  • can_signbooleanrequired
  • why_notstring | nullrequired
  • totalsobject[]required
    8 fields
    • currencystringrequired
    • eligiblenumberrequired
    • budgetnumberrequired

      Merit and promotion budgets, annual.

    • approvednumberrequired

      Annual cost of the approved raises.

    • lump_sumsnumberrequired

      Approved one-off lump sums.

    • lump_budgetnumber | nullrequired
    • approved_rowsintegerrequired
    • waitingintegerrequired

      Rows with pay not approved yet (left out at the release unless approved).

  • teamsobject[]required
    6 fields
    • namestringrequired
    • currencystringrequired
    • budgetnumberrequired
    • approvednumberrequired
    • lump_sumsnumberrequired
    • overbooleanrequired
  • equityobjectrequired

    Pay 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
    • flaggedintegerrequired
    • checkedintegerrequired
    • hiddenintegerrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/signoff.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": "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_off on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • cycle_idstringrequired
  • notestring

    Up to 500 characters.

Returns

11 fields
  • cycleobjectrequired
    5 fields
    • idstringrequired
    • namestringrequired
    • stagestringrequired
    • effective_datestringrequired
    • release_onstringrequired
  • requiredbooleanrequired

    The review needs its final sign-off before the release (steps.final_sign_off).

  • state"waiting" | "signed" | "sent_back"required
  • bystring | nullrequired

    Who signed off or sent it back.

  • atstring | nullrequired
  • notestring | nullrequired
  • can_signbooleanrequired
  • why_notstring | nullrequired
  • totalsobject[]required
    8 fields
    • currencystringrequired
    • eligiblenumberrequired
    • budgetnumberrequired

      Merit and promotion budgets, annual.

    • approvednumberrequired

      Annual cost of the approved raises.

    • lump_sumsnumberrequired

      Approved one-off lump sums.

    • lump_budgetnumber | nullrequired
    • approved_rowsintegerrequired
    • waitingintegerrequired

      Rows with pay not approved yet (left out at the release unless approved).

  • teamsobject[]required
    6 fields
    • namestringrequired
    • currencystringrequired
    • budgetnumberrequired
    • approvednumberrequired
    • lump_sumsnumberrequired
    • overbooleanrequired
  • equityobjectrequired

    Pay 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
    • flaggedintegerrequired
    • checkedintegerrequired
    • hiddenintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

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

Input

  • cycle_idstringrequired
  • notestringrequired

    1–500 characters.

Returns

11 fields
  • cycleobjectrequired
    5 fields
    • idstringrequired
    • namestringrequired
    • stagestringrequired
    • effective_datestringrequired
    • release_onstringrequired
  • requiredbooleanrequired

    The review needs its final sign-off before the release (steps.final_sign_off).

  • state"waiting" | "signed" | "sent_back"required
  • bystring | nullrequired

    Who signed off or sent it back.

  • atstring | nullrequired
  • notestring | nullrequired
  • can_signbooleanrequired
  • why_notstring | nullrequired
  • totalsobject[]required
    8 fields
    • currencystringrequired
    • eligiblenumberrequired
    • budgetnumberrequired

      Merit and promotion budgets, annual.

    • approvednumberrequired

      Annual cost of the approved raises.

    • lump_sumsnumberrequired

      Approved one-off lump sums.

    • lump_budgetnumber | nullrequired
    • approved_rowsintegerrequired
    • waitingintegerrequired

      Rows with pay not approved yet (left out at the release unless approved).

  • teamsobject[]required
    6 fields
    • namestringrequired
    • currencystringrequired
    • budgetnumberrequired
    • approvednumberrequired
    • lump_sumsnumberrequired
    • overbooleanrequired
  • equityobjectrequired

    Pay 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
    • flaggedintegerrequired
    • checkedintegerrequired
    • hiddenintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

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

Input

  • cycle_idstringrequired

Returns

  • cycleobjectrequired
    5 fields
    • idstringrequired
    • namestringrequired
    • stagestringrequired
    • effective_datestringrequired
    • rounding"none" | numberrequired
  • rowsobject[]required
    26 fields
    • idstringrequired
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • titlestring | nullrequired
    • teamstring | nullrequired
    • proposerobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • baseobject | nullrequired
      3 fields
      • amountnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
    • annualnumber | nullrequired
    • compa_rationumber | nullrequired
    • range_posnumber | nullrequired
    • bandobject | nullrequired
      5 fields
      • minnumberrequired
      • maxnumberrequired
      • midnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
    • ratingnumber | nullrequired
    • proratenumberrequired
    • guidelineobjectrequired
      5 fields
      • minnumberrequired
      • targetnumberrequired
      • maxnumberrequired
      • to_minbooleanrequired
      • lumpbooleanrequired
    • proposalobject | nullrequired
      9 fields
      • pctnumberrequired
      • new_amountnumberrequired
      • reason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"required
      • reason_textstring | nullrequired
      • commentstring | nullrequired
      • atstringrequired
      • lump_sum_pctnumber | nullrequired
      • lump_sumnumber | nullrequired

        The one-off lump sum in the base's currency (from lump_sum_pct of the annual base).

      • promotionbooleanrequired

        The raise draws on the promotion budget (reason promotion_pending, the cycle has one).

    • lump_okbooleanrequired
    • payoutobject | nullrequired
      6 fields
      • amountnumberrequired
      • currencystringrequired
      • state"in_payroll" | "by_hand" | "paid"required
      • why"payroll_off" | "refused" | "removed"required

        Why 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 | nullrequired
        2 fields
        • startstringrequired
        • endstringrequired
      • paid_atstring | nullrequired
    • outsidebooleanrequired
    • statestring (enum)required

      One of: draft, submitted, approved, returned, stale, skipped, released.

    • flagsstring (enum)[]required

      One of: no_pay, no_band, below_min, above_max, other_currency, new_joiner, leaving, pay_scheduled, protected_leave.

    • protected_floornumber | nullrequired

      protected_leave rows: the lowest raise % as if at work (null for others).

    • below_floorbooleanrequired

      The proposal is below protected_floor without an objective reason: it can't be approved.

    • objective_reasonobject | nullrequired

      HR's objective reason for a raise below protected_floor (comp_review_edit objective_reason).

      2 fields
      • textstringrequired
      • atstringrequired
    • skipped_reason"hr" | "not_approved" | "not_employed" | "leaving" | "no_pay"required
    • decisionsobject[]required
      3 fields
      • bystringrequired
      • atstringrequired
      • notestring | nullrequired
    • can_decidebooleanrequired
    • why_notstring | nullrequired
  • worksheetsobject[]required
    9 fields
    • proposerobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • state"draft" | "submitted" | "returned" | "upper"required

      upper: submitted, waiting for the manager's own manager (the upper-manager step) before HR.

    • submitted_atstring | nullrequired
    • upperobject | nullrequired

      Who checks it before HR (the upper-manager step), while it waits for them.

      2 fields
      • idstringrequired
      • namestringrequired
    • over_budget_reasonstring | nullrequired
    • return_notestring | nullrequired
    • rowsintegerrequired
    • promotionsintegerrequired

      Raises this manager put on the promotion budget (reason promotion_pending, the cycle has one): check each is a real promotion.

    • budgetsobject[]required
      9 fields
      • currencystringrequired
      • eligiblenumberrequired
      • budgetnumberrequired
      • spentnumberrequired
      • remainingnumberrequired
      • overbooleanrequired
      • used_pctnumberrequired
      • promotionobject | nullrequired

        The promotion pool (raises whose reason is promotion_pending), when the cycle has one.

        5 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired
      • lumpobject | nullrequired

        The lump-sum pool (one-off payments), when the cycle has one for this currency.

        5 fields
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired
  • own_hiddenbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/review.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": "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_decide on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • cycle_idstringrequired
  • row_idsstring[]required

    1–500 items.

  • decision"approve" | "reopen"

    Default "approve".

  • notestring

    Up to 500 characters.

Returns

  • reviewobjectrequired
    4 fields
    • cycleobjectrequired
      5 fields
      • idstringrequired
      • namestringrequired
      • stagestringrequired
      • effective_datestringrequired
      • rounding"none" | numberrequired
    • rowsobject[]required
      26 fields
      • idstringrequired
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • titlestring | nullrequired
      • teamstring | nullrequired
      • proposerobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • baseobject | nullrequired
        3 fields
        • amountnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
      • annualnumber | nullrequired
      • compa_rationumber | nullrequired
      • range_posnumber | nullrequired
      • bandobject | nullrequired
        5 fields
        • minnumberrequired
        • maxnumberrequired
        • midnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
      • ratingnumber | nullrequired
      • proratenumberrequired
      • guidelineobjectrequired
        5 fields
        • minnumberrequired
        • targetnumberrequired
        • maxnumberrequired
        • to_minbooleanrequired
        • lumpbooleanrequired
      • proposalobject | nullrequired
        9 fields
        • pctnumberrequired
        • new_amountnumberrequired
        • reason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"required
        • reason_textstring | nullrequired
        • commentstring | nullrequired
        • atstringrequired
        • lump_sum_pctnumber | nullrequired
        • lump_sumnumber | nullrequired

          The one-off lump sum in the base's currency (from lump_sum_pct of the annual base).

        • promotionbooleanrequired

          The raise draws on the promotion budget (reason promotion_pending, the cycle has one).

      • lump_okbooleanrequired
      • payoutobject | nullrequired
        6 fields
        • amountnumberrequired
        • currencystringrequired
        • state"in_payroll" | "by_hand" | "paid"required
        • why"payroll_off" | "refused" | "removed"required

          Why 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 | nullrequired
          2 fields
          • startstringrequired
          • endstringrequired
        • paid_atstring | nullrequired
      • outsidebooleanrequired
      • statestring (enum)required

        One of: draft, submitted, approved, returned, stale, skipped, released.

      • flagsstring (enum)[]required

        One of: no_pay, no_band, below_min, above_max, other_currency, new_joiner, leaving, pay_scheduled, protected_leave.

      • protected_floornumber | nullrequired

        protected_leave rows: the lowest raise % as if at work (null for others).

      • below_floorbooleanrequired

        The proposal is below protected_floor without an objective reason: it can't be approved.

      • objective_reasonobject | nullrequired

        HR's objective reason for a raise below protected_floor (comp_review_edit objective_reason).

        2 fields
        • textstringrequired
        • atstringrequired
      • skipped_reason"hr" | "not_approved" | "not_employed" | "leaving" | "no_pay"required
      • decisionsobject[]required
        3 fields
        • bystringrequired
        • atstringrequired
        • notestring | nullrequired
      • can_decidebooleanrequired
      • why_notstring | nullrequired
    • worksheetsobject[]required
      9 fields
      • proposerobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • state"draft" | "submitted" | "returned" | "upper"required

        upper: submitted, waiting for the manager's own manager (the upper-manager step) before HR.

      • submitted_atstring | nullrequired
      • upperobject | nullrequired

        Who checks it before HR (the upper-manager step), while it waits for them.

        2 fields
        • idstringrequired
        • namestringrequired
      • over_budget_reasonstring | nullrequired
      • return_notestring | nullrequired
      • rowsintegerrequired
      • promotionsintegerrequired

        Raises this manager put on the promotion budget (reason promotion_pending, the cycle has one): check each is a real promotion.

      • budgetsobject[]required
        9 fields
        • currencystringrequired
        • eligiblenumberrequired
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired
        • promotionobject | nullrequired

          The promotion pool (raises whose reason is promotion_pending), when the cycle has one.

          5 fields
          • budgetnumberrequired
          • spentnumberrequired
          • remainingnumberrequired
          • overbooleanrequired
          • used_pctnumberrequired
        • lumpobject | nullrequired

          The lump-sum pool (one-off payments), when the cycle has one for this currency.

          5 fields
          • budgetnumberrequired
          • spentnumberrequired
          • remainingnumberrequired
          • overbooleanrequired
          • used_pctnumberrequired
    • own_hiddenbooleanrequired
  • donestring[]required
  • refusedobject[]required
    2 fields
    • idstringrequired
    • reasonstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

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

Input

  • cycle_idstringrequired
  • row_idstringrequired
  • pctnumberrequired

    From 0 to 100.

  • lump_sum_pctnumber | null

    From 0 to 100.

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

    Up to 500 characters.

  • notestring

    Up to 500 characters.

  • objective_reasonstring | null

    Protected 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

  • reviewobjectrequired
    4 fields
    • cycleobjectrequired
      5 fields
      • idstringrequired
      • namestringrequired
      • stagestringrequired
      • effective_datestringrequired
      • rounding"none" | numberrequired
    • rowsobject[]required
      26 fields
      • idstringrequired
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • titlestring | nullrequired
      • teamstring | nullrequired
      • proposerobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • baseobject | nullrequired
        3 fields
        • amountnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
      • annualnumber | nullrequired
      • compa_rationumber | nullrequired
      • range_posnumber | nullrequired
      • bandobject | nullrequired
        5 fields
        • minnumberrequired
        • maxnumberrequired
        • midnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
      • ratingnumber | nullrequired
      • proratenumberrequired
      • guidelineobjectrequired
        5 fields
        • minnumberrequired
        • targetnumberrequired
        • maxnumberrequired
        • to_minbooleanrequired
        • lumpbooleanrequired
      • proposalobject | nullrequired
        9 fields
        • pctnumberrequired
        • new_amountnumberrequired
        • reason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"required
        • reason_textstring | nullrequired
        • commentstring | nullrequired
        • atstringrequired
        • lump_sum_pctnumber | nullrequired
        • lump_sumnumber | nullrequired

          The one-off lump sum in the base's currency (from lump_sum_pct of the annual base).

        • promotionbooleanrequired

          The raise draws on the promotion budget (reason promotion_pending, the cycle has one).

      • lump_okbooleanrequired
      • payoutobject | nullrequired
        6 fields
        • amountnumberrequired
        • currencystringrequired
        • state"in_payroll" | "by_hand" | "paid"required
        • why"payroll_off" | "refused" | "removed"required

          Why 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 | nullrequired
          2 fields
          • startstringrequired
          • endstringrequired
        • paid_atstring | nullrequired
      • outsidebooleanrequired
      • statestring (enum)required

        One of: draft, submitted, approved, returned, stale, skipped, released.

      • flagsstring (enum)[]required

        One of: no_pay, no_band, below_min, above_max, other_currency, new_joiner, leaving, pay_scheduled, protected_leave.

      • protected_floornumber | nullrequired

        protected_leave rows: the lowest raise % as if at work (null for others).

      • below_floorbooleanrequired

        The proposal is below protected_floor without an objective reason: it can't be approved.

      • objective_reasonobject | nullrequired

        HR's objective reason for a raise below protected_floor (comp_review_edit objective_reason).

        2 fields
        • textstringrequired
        • atstringrequired
      • skipped_reason"hr" | "not_approved" | "not_employed" | "leaving" | "no_pay"required
      • decisionsobject[]required
        3 fields
        • bystringrequired
        • atstringrequired
        • notestring | nullrequired
      • can_decidebooleanrequired
      • why_notstring | nullrequired
    • worksheetsobject[]required
      9 fields
      • proposerobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • state"draft" | "submitted" | "returned" | "upper"required

        upper: submitted, waiting for the manager's own manager (the upper-manager step) before HR.

      • submitted_atstring | nullrequired
      • upperobject | nullrequired

        Who checks it before HR (the upper-manager step), while it waits for them.

        2 fields
        • idstringrequired
        • namestringrequired
      • over_budget_reasonstring | nullrequired
      • return_notestring | nullrequired
      • rowsintegerrequired
      • promotionsintegerrequired

        Raises this manager put on the promotion budget (reason promotion_pending, the cycle has one): check each is a real promotion.

      • budgetsobject[]required
        9 fields
        • currencystringrequired
        • eligiblenumberrequired
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired
        • promotionobject | nullrequired

          The promotion pool (raises whose reason is promotion_pending), when the cycle has one.

          5 fields
          • budgetnumberrequired
          • spentnumberrequired
          • remainingnumberrequired
          • overbooleanrequired
          • used_pctnumberrequired
        • lumpobject | nullrequired

          The lump-sum pool (one-off payments), when the cycle has one for this currency.

          5 fields
          • budgetnumberrequired
          • spentnumberrequired
          • remainingnumberrequired
          • overbooleanrequired
          • used_pctnumberrequired
    • own_hiddenbooleanrequired
  • donestring[]required
  • refusedobject[]required
    2 fields
    • idstringrequired
    • reasonstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

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

Input

  • cycle_idstringrequired
  • proposer_person_idstringrequired
  • notestringrequired

    1–500 characters.

Returns

  • reviewobjectrequired
    4 fields
    • cycleobjectrequired
      5 fields
      • idstringrequired
      • namestringrequired
      • stagestringrequired
      • effective_datestringrequired
      • rounding"none" | numberrequired
    • rowsobject[]required
      26 fields
      • idstringrequired
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • titlestring | nullrequired
      • teamstring | nullrequired
      • proposerobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • baseobject | nullrequired
        3 fields
        • amountnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
      • annualnumber | nullrequired
      • compa_rationumber | nullrequired
      • range_posnumber | nullrequired
      • bandobject | nullrequired
        5 fields
        • minnumberrequired
        • maxnumberrequired
        • midnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
      • ratingnumber | nullrequired
      • proratenumberrequired
      • guidelineobjectrequired
        5 fields
        • minnumberrequired
        • targetnumberrequired
        • maxnumberrequired
        • to_minbooleanrequired
        • lumpbooleanrequired
      • proposalobject | nullrequired
        9 fields
        • pctnumberrequired
        • new_amountnumberrequired
        • reason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"required
        • reason_textstring | nullrequired
        • commentstring | nullrequired
        • atstringrequired
        • lump_sum_pctnumber | nullrequired
        • lump_sumnumber | nullrequired

          The one-off lump sum in the base's currency (from lump_sum_pct of the annual base).

        • promotionbooleanrequired

          The raise draws on the promotion budget (reason promotion_pending, the cycle has one).

      • lump_okbooleanrequired
      • payoutobject | nullrequired
        6 fields
        • amountnumberrequired
        • currencystringrequired
        • state"in_payroll" | "by_hand" | "paid"required
        • why"payroll_off" | "refused" | "removed"required

          Why 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 | nullrequired
          2 fields
          • startstringrequired
          • endstringrequired
        • paid_atstring | nullrequired
      • outsidebooleanrequired
      • statestring (enum)required

        One of: draft, submitted, approved, returned, stale, skipped, released.

      • flagsstring (enum)[]required

        One of: no_pay, no_band, below_min, above_max, other_currency, new_joiner, leaving, pay_scheduled, protected_leave.

      • protected_floornumber | nullrequired

        protected_leave rows: the lowest raise % as if at work (null for others).

      • below_floorbooleanrequired

        The proposal is below protected_floor without an objective reason: it can't be approved.

      • objective_reasonobject | nullrequired

        HR's objective reason for a raise below protected_floor (comp_review_edit objective_reason).

        2 fields
        • textstringrequired
        • atstringrequired
      • skipped_reason"hr" | "not_approved" | "not_employed" | "leaving" | "no_pay"required
      • decisionsobject[]required
        3 fields
        • bystringrequired
        • atstringrequired
        • notestring | nullrequired
      • can_decidebooleanrequired
      • why_notstring | nullrequired
    • worksheetsobject[]required
      9 fields
      • proposerobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • state"draft" | "submitted" | "returned" | "upper"required

        upper: submitted, waiting for the manager's own manager (the upper-manager step) before HR.

      • submitted_atstring | nullrequired
      • upperobject | nullrequired

        Who checks it before HR (the upper-manager step), while it waits for them.

        2 fields
        • idstringrequired
        • namestringrequired
      • over_budget_reasonstring | nullrequired
      • return_notestring | nullrequired
      • rowsintegerrequired
      • promotionsintegerrequired

        Raises this manager put on the promotion budget (reason promotion_pending, the cycle has one): check each is a real promotion.

      • budgetsobject[]required
        9 fields
        • currencystringrequired
        • eligiblenumberrequired
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired
        • promotionobject | nullrequired

          The promotion pool (raises whose reason is promotion_pending), when the cycle has one.

          5 fields
          • budgetnumberrequired
          • spentnumberrequired
          • remainingnumberrequired
          • overbooleanrequired
          • used_pctnumberrequired
        • lumpobject | nullrequired

          The lump-sum pool (one-off payments), when the cycle has one for this currency.

          5 fields
          • budgetnumberrequired
          • spentnumberrequired
          • remainingnumberrequired
          • overbooleanrequired
          • used_pctnumberrequired
    • own_hiddenbooleanrequired
  • donestring[]required
  • refusedobject[]required
    2 fields
    • idstringrequired
    • reasonstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

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

Input

  • cycle_idstringrequired
  • row_idsstring[]required

    1–100 items.

Returns

  • reviewobjectrequired
    4 fields
    • cycleobjectrequired
      5 fields
      • idstringrequired
      • namestringrequired
      • stagestringrequired
      • effective_datestringrequired
      • rounding"none" | numberrequired
    • rowsobject[]required
      26 fields
      • idstringrequired
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • titlestring | nullrequired
      • teamstring | nullrequired
      • proposerobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • baseobject | nullrequired
        3 fields
        • amountnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
      • annualnumber | nullrequired
      • compa_rationumber | nullrequired
      • range_posnumber | nullrequired
      • bandobject | nullrequired
        5 fields
        • minnumberrequired
        • maxnumberrequired
        • midnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
      • ratingnumber | nullrequired
      • proratenumberrequired
      • guidelineobjectrequired
        5 fields
        • minnumberrequired
        • targetnumberrequired
        • maxnumberrequired
        • to_minbooleanrequired
        • lumpbooleanrequired
      • proposalobject | nullrequired
        9 fields
        • pctnumberrequired
        • new_amountnumberrequired
        • reason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"required
        • reason_textstring | nullrequired
        • commentstring | nullrequired
        • atstringrequired
        • lump_sum_pctnumber | nullrequired
        • lump_sumnumber | nullrequired

          The one-off lump sum in the base's currency (from lump_sum_pct of the annual base).

        • promotionbooleanrequired

          The raise draws on the promotion budget (reason promotion_pending, the cycle has one).

      • lump_okbooleanrequired
      • payoutobject | nullrequired
        6 fields
        • amountnumberrequired
        • currencystringrequired
        • state"in_payroll" | "by_hand" | "paid"required
        • why"payroll_off" | "refused" | "removed"required

          Why 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 | nullrequired
          2 fields
          • startstringrequired
          • endstringrequired
        • paid_atstring | nullrequired
      • outsidebooleanrequired
      • statestring (enum)required

        One of: draft, submitted, approved, returned, stale, skipped, released.

      • flagsstring (enum)[]required

        One of: no_pay, no_band, below_min, above_max, other_currency, new_joiner, leaving, pay_scheduled, protected_leave.

      • protected_floornumber | nullrequired

        protected_leave rows: the lowest raise % as if at work (null for others).

      • below_floorbooleanrequired

        The proposal is below protected_floor without an objective reason: it can't be approved.

      • objective_reasonobject | nullrequired

        HR's objective reason for a raise below protected_floor (comp_review_edit objective_reason).

        2 fields
        • textstringrequired
        • atstringrequired
      • skipped_reason"hr" | "not_approved" | "not_employed" | "leaving" | "no_pay"required
      • decisionsobject[]required
        3 fields
        • bystringrequired
        • atstringrequired
        • notestring | nullrequired
      • can_decidebooleanrequired
      • why_notstring | nullrequired
    • worksheetsobject[]required
      9 fields
      • proposerobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • state"draft" | "submitted" | "returned" | "upper"required

        upper: submitted, waiting for the manager's own manager (the upper-manager step) before HR.

      • submitted_atstring | nullrequired
      • upperobject | nullrequired

        Who checks it before HR (the upper-manager step), while it waits for them.

        2 fields
        • idstringrequired
        • namestringrequired
      • over_budget_reasonstring | nullrequired
      • return_notestring | nullrequired
      • rowsintegerrequired
      • promotionsintegerrequired

        Raises this manager put on the promotion budget (reason promotion_pending, the cycle has one): check each is a real promotion.

      • budgetsobject[]required
        9 fields
        • currencystringrequired
        • eligiblenumberrequired
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired
        • promotionobject | nullrequired

          The promotion pool (raises whose reason is promotion_pending), when the cycle has one.

          5 fields
          • budgetnumberrequired
          • spentnumberrequired
          • remainingnumberrequired
          • overbooleanrequired
          • used_pctnumberrequired
        • lumpobject | nullrequired

          The lump-sum pool (one-off payments), when the cycle has one for this currency.

          5 fields
          • budgetnumberrequired
          • spentnumberrequired
          • remainingnumberrequired
          • overbooleanrequired
          • used_pctnumberrequired
    • own_hiddenbooleanrequired
  • donestring[]required
  • refusedobject[]required
    2 fields
    • idstringrequired
    • reasonstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

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

Input

  • cycle_idstringrequired
  • row_idsstring[]required

    1–500 items.

  • includeboolean

    Default false.

Returns

  • reviewobjectrequired
    4 fields
    • cycleobjectrequired
      5 fields
      • idstringrequired
      • namestringrequired
      • stagestringrequired
      • effective_datestringrequired
      • rounding"none" | numberrequired
    • rowsobject[]required
      26 fields
      • idstringrequired
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • titlestring | nullrequired
      • teamstring | nullrequired
      • proposerobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • baseobject | nullrequired
        3 fields
        • amountnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
      • annualnumber | nullrequired
      • compa_rationumber | nullrequired
      • range_posnumber | nullrequired
      • bandobject | nullrequired
        5 fields
        • minnumberrequired
        • maxnumberrequired
        • midnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
      • ratingnumber | nullrequired
      • proratenumberrequired
      • guidelineobjectrequired
        5 fields
        • minnumberrequired
        • targetnumberrequired
        • maxnumberrequired
        • to_minbooleanrequired
        • lumpbooleanrequired
      • proposalobject | nullrequired
        9 fields
        • pctnumberrequired
        • new_amountnumberrequired
        • reason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"required
        • reason_textstring | nullrequired
        • commentstring | nullrequired
        • atstringrequired
        • lump_sum_pctnumber | nullrequired
        • lump_sumnumber | nullrequired

          The one-off lump sum in the base's currency (from lump_sum_pct of the annual base).

        • promotionbooleanrequired

          The raise draws on the promotion budget (reason promotion_pending, the cycle has one).

      • lump_okbooleanrequired
      • payoutobject | nullrequired
        6 fields
        • amountnumberrequired
        • currencystringrequired
        • state"in_payroll" | "by_hand" | "paid"required
        • why"payroll_off" | "refused" | "removed"required

          Why 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 | nullrequired
          2 fields
          • startstringrequired
          • endstringrequired
        • paid_atstring | nullrequired
      • outsidebooleanrequired
      • statestring (enum)required

        One of: draft, submitted, approved, returned, stale, skipped, released.

      • flagsstring (enum)[]required

        One of: no_pay, no_band, below_min, above_max, other_currency, new_joiner, leaving, pay_scheduled, protected_leave.

      • protected_floornumber | nullrequired

        protected_leave rows: the lowest raise % as if at work (null for others).

      • below_floorbooleanrequired

        The proposal is below protected_floor without an objective reason: it can't be approved.

      • objective_reasonobject | nullrequired

        HR's objective reason for a raise below protected_floor (comp_review_edit objective_reason).

        2 fields
        • textstringrequired
        • atstringrequired
      • skipped_reason"hr" | "not_approved" | "not_employed" | "leaving" | "no_pay"required
      • decisionsobject[]required
        3 fields
        • bystringrequired
        • atstringrequired
        • notestring | nullrequired
      • can_decidebooleanrequired
      • why_notstring | nullrequired
    • worksheetsobject[]required
      9 fields
      • proposerobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • state"draft" | "submitted" | "returned" | "upper"required

        upper: submitted, waiting for the manager's own manager (the upper-manager step) before HR.

      • submitted_atstring | nullrequired
      • upperobject | nullrequired

        Who checks it before HR (the upper-manager step), while it waits for them.

        2 fields
        • idstringrequired
        • namestringrequired
      • over_budget_reasonstring | nullrequired
      • return_notestring | nullrequired
      • rowsintegerrequired
      • promotionsintegerrequired

        Raises this manager put on the promotion budget (reason promotion_pending, the cycle has one): check each is a real promotion.

      • budgetsobject[]required
        9 fields
        • currencystringrequired
        • eligiblenumberrequired
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired
        • promotionobject | nullrequired

          The promotion pool (raises whose reason is promotion_pending), when the cycle has one.

          5 fields
          • budgetnumberrequired
          • spentnumberrequired
          • remainingnumberrequired
          • overbooleanrequired
          • used_pctnumberrequired
        • lumpobject | nullrequired

          The lump-sum pool (one-off payments), when the cycle has one for this currency.

          5 fields
          • budgetnumberrequired
          • spentnumberrequired
          • remainingnumberrequired
          • overbooleanrequired
          • used_pctnumberrequired
    • own_hiddenbooleanrequired
  • donestring[]required
  • refusedobject[]required
    2 fields
    • idstringrequired
    • reasonstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/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}'
Response
{
  "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_equity on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • cycle_idstringrequired

Returns

  • cycle_idstringrequired
  • min_groupintegerrequired
  • hiddenintegerrequired
  • categoriesobject[]required
    9 fields
    • idstringrequired
    • namestringrequired
    • womenintegerrequired
    • menintegerrequired
    • beforeobjectrequired
      2 fields
      • meannumber | nullrequired
      • mediannumber | nullrequired
    • afterobjectrequired
      2 fields
      • meannumber | nullrequired
      • mediannumber | nullrequired
    • flaggedbooleanrequired
    • variable_afterobject | nullrequired

      The 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 | nullrequired
      • mediannumber | nullrequired
    • rowsobject[]required
      5 fields
      • idstringrequired
      • namestringrequired
      • pctnumberrequired
      • lump_sum_pctnumber | nullrequired
      • reason"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/review.equity \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cycle_id":"cy1"}'
Response
{
  "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_paid on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • cycle_idstringrequired
  • row_idsstring[]required

    1–500 items.

Returns

  • reviewobjectrequired
    4 fields
    • cycleobjectrequired
      5 fields
      • idstringrequired
      • namestringrequired
      • stagestringrequired
      • effective_datestringrequired
      • rounding"none" | numberrequired
    • rowsobject[]required
      26 fields
      • idstringrequired
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • titlestring | nullrequired
      • teamstring | nullrequired
      • proposerobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • baseobject | nullrequired
        3 fields
        • amountnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
      • annualnumber | nullrequired
      • compa_rationumber | nullrequired
      • range_posnumber | nullrequired
      • bandobject | nullrequired
        5 fields
        • minnumberrequired
        • maxnumberrequired
        • midnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
      • ratingnumber | nullrequired
      • proratenumberrequired
      • guidelineobjectrequired
        5 fields
        • minnumberrequired
        • targetnumberrequired
        • maxnumberrequired
        • to_minbooleanrequired
        • lumpbooleanrequired
      • proposalobject | nullrequired
        9 fields
        • pctnumberrequired
        • new_amountnumberrequired
        • reason"market" | "retention" | "internal_equity" | "promotion_pending" | "skills" | "other"required
        • reason_textstring | nullrequired
        • commentstring | nullrequired
        • atstringrequired
        • lump_sum_pctnumber | nullrequired
        • lump_sumnumber | nullrequired

          The one-off lump sum in the base's currency (from lump_sum_pct of the annual base).

        • promotionbooleanrequired

          The raise draws on the promotion budget (reason promotion_pending, the cycle has one).

      • lump_okbooleanrequired
      • payoutobject | nullrequired
        6 fields
        • amountnumberrequired
        • currencystringrequired
        • state"in_payroll" | "by_hand" | "paid"required
        • why"payroll_off" | "refused" | "removed"required

          Why 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 | nullrequired
          2 fields
          • startstringrequired
          • endstringrequired
        • paid_atstring | nullrequired
      • outsidebooleanrequired
      • statestring (enum)required

        One of: draft, submitted, approved, returned, stale, skipped, released.

      • flagsstring (enum)[]required

        One of: no_pay, no_band, below_min, above_max, other_currency, new_joiner, leaving, pay_scheduled, protected_leave.

      • protected_floornumber | nullrequired

        protected_leave rows: the lowest raise % as if at work (null for others).

      • below_floorbooleanrequired

        The proposal is below protected_floor without an objective reason: it can't be approved.

      • objective_reasonobject | nullrequired

        HR's objective reason for a raise below protected_floor (comp_review_edit objective_reason).

        2 fields
        • textstringrequired
        • atstringrequired
      • skipped_reason"hr" | "not_approved" | "not_employed" | "leaving" | "no_pay"required
      • decisionsobject[]required
        3 fields
        • bystringrequired
        • atstringrequired
        • notestring | nullrequired
      • can_decidebooleanrequired
      • why_notstring | nullrequired
    • worksheetsobject[]required
      9 fields
      • proposerobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • state"draft" | "submitted" | "returned" | "upper"required

        upper: submitted, waiting for the manager's own manager (the upper-manager step) before HR.

      • submitted_atstring | nullrequired
      • upperobject | nullrequired

        Who checks it before HR (the upper-manager step), while it waits for them.

        2 fields
        • idstringrequired
        • namestringrequired
      • over_budget_reasonstring | nullrequired
      • return_notestring | nullrequired
      • rowsintegerrequired
      • promotionsintegerrequired

        Raises this manager put on the promotion budget (reason promotion_pending, the cycle has one): check each is a real promotion.

      • budgetsobject[]required
        9 fields
        • currencystringrequired
        • eligiblenumberrequired
        • budgetnumberrequired
        • spentnumberrequired
        • remainingnumberrequired
        • overbooleanrequired
        • used_pctnumberrequired
        • promotionobject | nullrequired

          The promotion pool (raises whose reason is promotion_pending), when the cycle has one.

          5 fields
          • budgetnumberrequired
          • spentnumberrequired
          • remainingnumberrequired
          • overbooleanrequired
          • used_pctnumberrequired
        • lumpobject | nullrequired

          The lump-sum pool (one-off payments), when the cycle has one for this currency.

          5 fields
          • budgetnumberrequired
          • spentnumberrequired
          • remainingnumberrequired
          • overbooleanrequired
          • used_pctnumberrequired
    • own_hiddenbooleanrequired
  • donestring[]required
  • refusedobject[]required
    2 fields
    • idstringrequired
    • reasonstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/comp/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"]}'
Response
{
  "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_check on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • cycle_idstringrequired

Returns

9 fields
  • cycle_idstringrequired
  • rating_cycle_idstring | nullrequired

    The review cycle whose ratings feed the matrix: its own check (talent_cycles_sex_check) adds potential and calibration moves.

  • levelsobject[]required
    2 fields
    • valueintegerrequired
    • labelstringrequired
  • recordedobjectrequired
    3 fields
    • womenintegerrequired
    • menintegerrequired
    • not_includedintegerrequired
  • min_groupintegerrequired
  • suppressedbooleanrequired
  • ratingobject | nullrequired
    7 fields
    • levelsobject[]required
      3 fields
      • valueintegerrequired
      • women_pctnumberrequired
      • men_pctnumberrequired
    • women_meannumberrequired
    • men_meannumberrequired
    • gap_pointsnumberrequired
    • gap_pct_of_rangenumberrequired
    • topobjectrequired
      3 fields
      • women_pctnumberrequired
      • men_pctnumberrequired
      • rationumber | nullrequired
    • bottomobjectrequired
      3 fields
      • women_pctnumberrequired
      • men_pctnumberrequired
      • rationumber | nullrequired
  • raiseobject | nullrequired
    2 fields
    • levelsobject[]required
      3 fields
      • valueinteger | nullrequired
      • women_meannumber | nullrequired
      • men_meannumber | nullrequired
    • gap_ppnumber | nullrequired

      Men's mean raise − women's at the same rating, weighted by people (percentage points); flagged from 0.5.

  • flagsstring (enum)[]required

    One 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
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"}'
Response
{
  "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.

Developer docs