Skip to content

API reference

Pay bands and pay equity

Pay bands, job evaluations, categories of workers, the pay gap, Art. 9 reports and answering Art. 7 pay requests (EU Pay Transparency Directive). Bands, gaps, reports and requests are pay data: the web app only, except your own band and your own requests.

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

List pay bands#

POST/v1/org/pay_bands.listRead

The company's pay bands: one row per target (a catalog title, or a family + level that covers every title of that family at that level) per start date, each applying until the next row for the same target. A person's band is their title's own band, else their title's family + level band. For rows in force today, people counts who has that band by where their pay sits (below, in or above; pay is converted to the band's period and scaled to full time). Owners, admins and HR, in the app only (pay data: never over an API key or MCP). At most 1,000 rows.

Web app only
Refused for API keys and connected apps. Pay bands are pay data: read in the app only.
MCP tool
org_pay_bands_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • itemsobject[]required
    11 fields
    • idstringrequired
    • targetobjectrequired
      5 fields
      • kind"title" | "level"required
      • title_idstring | nullrequired
      • family_idstring | nullrequired
      • level_idstring | nullrequired
      • namestringrequired

        The title's name, or "Family · Level".

    • valid_fromstringrequired
    • valid_tostring | nullrequired

      When the next row for the same target starts (exclusive); null = open-ended.

    • in_forcebooleanrequired

      The row that applies today for its target.

    • minnumberrequired
    • maxnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
    • notestring | nullrequired
    • peopleobject | nullrequired

      People whose band today is this row, by where their pay sits (null for rows not in force).

      4 fields
      • belowintegerrequired
      • inintegerrequired
      • aboveintegerrequired
      • not_comparedintegerrequired

        Pay in another currency or period, or no pay recorded.

  • limitintegerrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_bands.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "items": [
      {
        "id": "b1",
        "target": {
          "kind": "title",
          "title_id": "t1",
          "family_id": null,
          "level_id": null,
          "name": "Back-end Engineer"
        },
        "valid_from": "2026-01-01",
        "valid_to": null,
        "in_force": true,
        "min": 30000,
        "max": 45000,
        "currency": "EUR",
        "period": "year",
        "note": null,
        "people": {
          "below": 1,
          "in": 4,
          "above": 0,
          "not_compared": 1
        }
      }
    ],
    "limit": 1000
  }
}

Set a pay band#

POST/v1/org/pay_bands.setWrite

Sets the pay band of a target from valid_from (YYYY-MM-DD, default today; may be in the future): target {kind: "title", title_id} or {kind: "level", family_id, level_id}, min ≤ max (gross, at most 2 decimals), currency (ISO code) and period (year, month or hour), optional note. A row for the same target and date is replaced; otherwise a new row is added and the earlier one applies until it starts. preview.summary says how many people have this band from that day and where their pay sits ("12 people: 3 below, 8 in, 1 above"). Owners, admins and HR, in the app only (never over an API key or MCP). At most 1,000 rows per company. Use dry_run first.

Web app only
Refused for API keys and connected apps. Pay bands are set in the app only.
MCP tool
org_pay_bands_set 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

  • targetobjectrequired
    5 fields (one of several shapes)

    Option 1

    • kind"title"required
    • title_idstringrequired

    Option 2

    • kind"level"required
    • family_idstringrequired
    • level_idstringrequired
  • valid_fromstring
  • minnumberrequired

    From 0 to 100000000.

  • maxnumberrequired

    From 0 to 100000000.

  • currencyanyrequired
  • period"year" | "month" | "hour"required
  • notestring | null

    Up to 200 characters.

Returns

  • bandobjectrequired
    11 fields
    • idstringrequired
    • targetobjectrequired
      5 fields
      • kind"title" | "level"required
      • title_idstring | nullrequired
      • family_idstring | nullrequired
      • level_idstring | nullrequired
      • namestringrequired

        The title's name, or "Family · Level".

    • valid_fromstringrequired
    • valid_tostring | nullrequired

      When the next row for the same target starts (exclusive); null = open-ended.

    • in_forcebooleanrequired

      The row that applies today for its target.

    • minnumberrequired
    • maxnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
    • notestring | nullrequired
    • peopleobject | nullrequired

      People whose band today is this row, by where their pay sits (null for rows not in force).

      4 fields
      • belowintegerrequired
      • inintegerrequired
      • aboveintegerrequired
      • not_comparedintegerrequired

        Pay in another currency or period, or no pay recorded.

  • createdbooleanrequired
  • previewobjectrequired
    5 fields
    • belowintegerrequired
    • inintegerrequired
    • aboveintegerrequired
    • not_comparedintegerrequired

      Pay in another currency or period, or no pay recorded.

    • summarystringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_bands.set \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "target": {
    "kind": "level",
    "family_id": "f1",
    "level_id": "l2"
  },
  "valid_from": "2027-01-01",
  "min": 2500,
  "max": 3500,
  "currency": "EUR",
  "period": "month",
  "note": "Market review 2026"
}'
Response
{
  "data": {
    "band": {
      "id": "b1",
      "target": {
        "kind": "title",
        "title_id": "t1",
        "family_id": null,
        "level_id": null,
        "name": "Back-end Engineer"
      },
      "valid_from": "2026-01-01",
      "valid_to": null,
      "in_force": true,
      "min": 30000,
      "max": 45000,
      "currency": "EUR",
      "period": "year",
      "note": null,
      "people": {
        "below": 1,
        "in": 4,
        "above": 0,
        "not_compared": 1
      }
    },
    "created": true,
    "preview": {
      "below": 1,
      "in": 4,
      "above": 0,
      "not_compared": 0,
      "summary": "5 people: 1 below, 4 in, 0 above."
    }
  }
}

Remove a pay band row#

POST/v1/org/pay_bands.removeDestructive

Deletes one pay band row (band_id from org_pay_bands_list); for its target the previous row then applies until the next one. Owners, admins and HR, in the app only (never over an API key or MCP).

Web app only
Refused for API keys and connected apps. Pay bands are changed in the app only.
MCP tool
org_pay_bands_remove on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • band_idstringrequired

Returns

  • idstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_bands.remove \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"band_id":"b1"}'
Response
{
  "data": {
    "id": "b1"
  }
}

Where pay sits in the band#

POST/v1/org/pay_bands.positionRead

For a person (person_id) on a day (as_of, default today): their band (their title's own band, else its family + level band), their pay in force, and where it sits: status below, in or above (pct: 0 = the minimum, 100 = the maximum; outside the band below 0 or above 100), other_currency or other_period (an hourly pay against a salary band, or the other way round: not compared). Yearly and monthly pay is converted to the band's period and scaled to full time (0.5 FTE at 20,000 a year compares as 40,000). proposed {amount, currency, period} checks a new pay instead (e.g. a raise), and title_id another title (e.g. a promotion). Owners, admins and HR signed in to Bizisy for anyone; a person for themself (their band today, without title_id or as_of) only when the company shows bands to people (Pay equity → Settings), also over an API key or MCP; never for someone else over an API key or MCP.

Who can call it
Manage key any Manage role
Me key anyone
Keys and apps
Only your own band, and only when the company shows bands to people.
MCP tool
org_pay_bands_position on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • person_idstringrequired
  • as_ofstring
  • title_idstring
  • proposedobject
    3 fields
    • amountnumberrequired

      From 0 to 100000000.

    • currencyanyrequired
    • period"year" | "month" | "hour"required

Returns

8 fields
  • person_idstringrequired
  • as_ofstringrequired
  • bandobject | nullrequired
    8 fields
    • idstringrequired
    • targetobjectrequired
      5 fields
      • kind"title" | "level"required
      • title_idstring | nullrequired
      • family_idstring | nullrequired
      • level_idstring | nullrequired
      • namestringrequired

        The title's name, or "Family · Level".

    • valid_fromstringrequired
    • minnumberrequired
    • maxnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
    • source"title" | "level"required

      "title": the title's own band; "level": the band of its family and level.

  • payobject | nullrequired
    4 fields
    • amountnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
    • proposedbooleanrequired
  • ftenumber | nullrequired
  • comparednumber | nullrequired

    The pay as the band counts it (its period, full time).

  • pctnumber | nullrequired
  • status"below" | "in" | "above" | "other_currency" | "other_period"required

    Null when there is no band or no pay.

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_bands.position \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "person_id": "p1",
  "as_of": "2026-11-01",
  "title_id": "t1",
  "proposed": {
    "amount": 42000,
    "currency": "EUR",
    "period": "year"
  }
}'
Response
{
  "data": {
    "person_id": "p1",
    "as_of": "2026-11-01",
    "band": {
      "id": "b1",
      "target": {
        "kind": "title",
        "title_id": "t1",
        "family_id": null,
        "level_id": null,
        "name": "Back-end Engineer"
      },
      "valid_from": "2026-01-01",
      "min": 30000,
      "max": 45000,
      "currency": "EUR",
      "period": "year",
      "source": "title"
    },
    "pay": {
      "amount": 39300,
      "currency": "EUR",
      "period": "year",
      "proposed": false
    },
    "fte": 1,
    "compared": 39300,
    "pct": 62,
    "status": "in"
  }
}

List job evaluations#

POST/v1/org/title_evaluations.listRead

Every active catalog title with its job evaluation (or null when not evaluated yet), how many people hold it today and its pay category. An evaluation scores the job on skills, effort, responsibility and working conditions (EU Pay Transparency Directive Art. 4(4)), 1 = basic to 5 = expert or very high, plus up to 3 other factors; score is the weighted score 20–100 with the company's weights. status filters: all (default), none (not evaluated), draft or approved. Owners, admins, HR and viewers; no pay is included. Part of the Pay equity 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 any Manage role
MCP tool
org_title_evaluations_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • status"all" | "none" | "draft" | "approved"

    Default "all".

Returns

An array of objects:

  • titleobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • familystring | nullrequired
  • levelstring | nullrequired
  • peopleintegerrequired
  • evaluationobject | nullrequired
    12 fields
    • idstringrequired
    • title_idstringrequired
    • factorsobjectrequired
      4 fields
      • skillsintegerrequired
      • effortintegerrequired
      • responsibilityintegerrequired
      • working_conditionsintegerrequired
    • otherobject[]required
      2 fields
      • namestringrequired
      • scoreintegerrequired
    • rationalestringrequired
    • status"draft" | "approved"required
    • source"hr" | "ai"required
    • scorenumber | nullrequired

      Weighted score 20–100 with the company's weights; null when every weight used is 0.

    • updated_bystringrequired
    • updated_atstringrequired
    • approved_bystring | nullrequired
    • approved_atstring | nullrequired
  • categoryobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/title_evaluations.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"draft"}'
Response
{
  "data": [
    {
      "title": {
        "id": "t1",
        "name": "Back-end Engineer"
      },
      "family": "Technology › Engineering",
      "level": "Mid",
      "people": 6,
      "evaluation": {
        "id": "ev1",
        "title_id": "t1",
        "factors": {
          "skills": 4,
          "effort": 3,
          "responsibility": 4,
          "working_conditions": 2
        },
        "other": [],
        "rationale": "Designs and builds services; owns their quality.",
        "status": "approved",
        "source": "hr",
        "score": 65,
        "updated_by": "u1",
        "updated_at": "2026-10-01T10:00:00.000Z",
        "approved_by": "u1",
        "approved_at": "2026-10-02T10:00:00.000Z"
      },
      "category": {
        "id": "c1",
        "name": "Engineering"
      }
    },
    {
      "title": {
        "id": "t3",
        "name": "Office Manager"
      },
      "family": null,
      "level": null,
      "people": 1,
      "evaluation": null,
      "category": null
    }
  ]
}

Evaluate a job title#

POST/v1/org/title_evaluations.setWrite

Records the job evaluation of a catalog title (title_id): factors {skills, effort, responsibility, working_conditions}, each an integer 1–5 (1 = basic, 3 = substantial, 5 = expert or very high; soft skills such as communication, care and coordination count under skills and responsibility), up to 3 other factors [{name, score}], and a rationale (10–2000 characters: why these scores, in gender-neutral terms). Saving always makes it a draft (an approved evaluation that changes needs approving again, org_title_evaluations_approve, in the app). Owners, admins and HR; an API key or AI assistant may write drafts (marked source "ai") for HR to approve, but never change an approved evaluation. Part of the Pay equity module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

Who can call it
Manage key owner admin hr
Keys and apps
Drafts only (source "ai") for HR to approve; an approved evaluation is refused.
MCP tool
org_title_evaluations_set on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • title_idstringrequired
  • factorsobjectrequired
    4 fields
    • skillsintegerrequired

      From 1 to 5.

    • effortintegerrequired

      From 1 to 5.

    • responsibilityintegerrequired

      From 1 to 5.

    • working_conditionsintegerrequired

      From 1 to 5.

  • otherobject[]

    Up to 3 items.

    2 fields
    • namestringrequired

      1–60 characters.

    • scoreintegerrequired

      From 1 to 5.

  • rationalestringrequired

    10–2000 characters.

Returns

12 fields
  • idstringrequired
  • title_idstringrequired
  • factorsobjectrequired
    4 fields
    • skillsintegerrequired
    • effortintegerrequired
    • responsibilityintegerrequired
    • working_conditionsintegerrequired
  • otherobject[]required
    2 fields
    • namestringrequired
    • scoreintegerrequired
  • rationalestringrequired
  • status"draft" | "approved"required
  • source"hr" | "ai"required
  • scorenumber | nullrequired

    Weighted score 20–100 with the company's weights; null when every weight used is 0.

  • updated_bystringrequired
  • updated_atstringrequired
  • approved_bystring | nullrequired
  • approved_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/title_evaluations.set \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "title_id": "t1",
  "factors": {
    "skills": 4,
    "effort": 3,
    "responsibility": 4,
    "working_conditions": 2
  },
  "other": [
    {
      "name": "Travel",
      "score": 3
    }
  ],
  "rationale": "Designs and builds services; owns their quality."
}'
Response
{
  "data": {
    "id": "ev1",
    "title_id": "t1",
    "factors": {
      "skills": 4,
      "effort": 3,
      "responsibility": 4,
      "working_conditions": 2
    },
    "other": [],
    "rationale": "Designs and builds services; owns their quality.",
    "status": "draft",
    "source": "hr",
    "score": 65,
    "updated_by": "u1",
    "updated_at": "2026-10-01T10:00:00.000Z",
    "approved_by": null,
    "approved_at": null
  }
}

Approve job evaluations#

POST/v1/org/title_evaluations.approveWrite

Approves the draft evaluations of titles (title_ids, 1–200): only approved evaluations may be placed in a pay category. Every title must have an evaluation (refused with the title named). Owners, admins and HR, in the app only (never over an API key or MCP). Part of the Pay equity 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. Approving evaluations needs a person signed in to Bizisy.
MCP tool
org_title_evaluations_approve on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • title_idsstring[]required

    1–200 items.

Returns

An array of objects with 12 fields

An array of objects:

  • idstringrequired
  • title_idstringrequired
  • factorsobjectrequired
    4 fields
    • skillsintegerrequired
    • effortintegerrequired
    • responsibilityintegerrequired
    • working_conditionsintegerrequired
  • otherobject[]required
    2 fields
    • namestringrequired
    • scoreintegerrequired
  • rationalestringrequired
  • status"draft" | "approved"required
  • source"hr" | "ai"required
  • scorenumber | nullrequired

    Weighted score 20–100 with the company's weights; null when every weight used is 0.

  • updated_bystringrequired
  • updated_atstringrequired
  • approved_bystring | nullrequired
  • approved_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/title_evaluations.approve \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title_ids":["t1","t2"]}'
Response
{
  "data": [
    {
      "id": "ev1",
      "title_id": "t1",
      "factors": {
        "skills": 4,
        "effort": 3,
        "responsibility": 4,
        "working_conditions": 2
      },
      "other": [],
      "rationale": "Designs and builds services; owns their quality.",
      "status": "approved",
      "source": "hr",
      "score": 65,
      "updated_by": "u1",
      "updated_at": "2026-10-01T10:00:00.000Z",
      "approved_by": "u1",
      "approved_at": "2026-10-02T10:00:00.000Z"
    }
  ]
}

List pay categories#

POST/v1/org/pay_categories.listRead

The categories of workers (people doing the same work or work of equal value, EU Pay Transparency Directive Art. 3(1)(h)): name, rationale, titles with their evaluation scores, and how many people hold them today. unplaced lists titles with an approved evaluation that are in no category yet. Owners, admins, HR and viewers; no pay is included. Part of the Pay equity 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 any Manage role
MCP tool
org_pay_categories_list on HR Assistant
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
    • rationalestringrequired
    • titlesobject[]required
      5 fields
      • idstringrequired
      • namestringrequired
      • scorenumber | nullrequired
      • approvedbooleanrequired

        False when its evaluation was edited since (back to draft): approve it again.

      • peopleintegerrequired
    • peopleintegerrequired
    • created_atstringrequired
    • updated_atstringrequired
  • unplacedobject[]required
    5 fields
    • idstringrequired
    • namestringrequired
    • scorenumber | nullrequired
    • approvedbooleanrequired

      False when its evaluation was edited since (back to draft): approve it again.

    • peopleintegerrequired
  • limitintegerrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_categories.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "items": [
      {
        "id": "c1",
        "name": "Engineering",
        "rationale": "Same engineering work, equal evaluation scores.",
        "titles": [
          {
            "id": "t1",
            "name": "Back-end Engineer",
            "score": 65,
            "approved": true,
            "people": 6
          }
        ],
        "people": 6,
        "created_at": "2026-10-02T10:00:00.000Z",
        "updated_at": "2026-10-02T10:00:00.000Z"
      }
    ],
    "unplaced": [
      {
        "id": "t4",
        "name": "Data Analyst",
        "score": 60,
        "approved": true,
        "people": 2
      }
    ],
    "limit": 200
  }
}

Suggest pay categories#

POST/v1/org/pay_categories.suggestRead

Proposes categories of workers from the approved job evaluations (nothing is written): titles whose weighted scores lie within spread (default 5, 0–50) of their group's lowest score form one group, named after the title most people hold. Each title says which category it is in now, if any. Apply a group with org_pay_categories_set (in the app). Titles without an approved evaluation are left out (not_evaluated counts them). Owners, admins, HR and viewers. Part of the Pay equity module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

Who can call it
Manage key any Manage role
MCP tool
org_pay_categories_suggest on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • spreadnumber

    From 0 to 50. Default 5.

Returns

  • groupsobject[]required
    5 fields
    • namestringrequired
    • min_scorenumberrequired
    • max_scorenumberrequired
    • title_idsstring[]required
    • titlesobject[]required
      5 fields
      • idstringrequired
      • namestringrequired
      • scorenumberrequired
      • peopleintegerrequired
      • categoryobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
  • spreadnumberrequired
  • not_evaluatedintegerrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_categories.suggest \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spread":8}'
Response
{
  "data": {
    "groups": [
      {
        "name": "Back-end Engineer",
        "min_score": 62.5,
        "max_score": 65,
        "title_ids": [
          "t1",
          "t4"
        ],
        "titles": [
          {
            "id": "t4",
            "name": "Data Analyst",
            "score": 62.5,
            "people": 2,
            "category": null
          },
          {
            "id": "t1",
            "name": "Back-end Engineer",
            "score": 65,
            "people": 6,
            "category": {
              "id": "c1",
              "name": "Engineering"
            }
          }
        ]
      }
    ],
    "spread": 8,
    "not_evaluated": 3
  }
}

Save a pay category#

POST/v1/org/pay_categories.setWrite

Creates a category of workers (no category_id) or replaces one (category_id): name (1–80, unique), title_ids (1–500) and rationale (10–2000 characters: why these jobs are the same work or work of equal value). Only titles with an approved job evaluation may be placed, and a title is in at most one category (refused with the title named). Owners, admins and HR, in the app only (never over an API key or MCP). At most 200 categories. Part of the Pay equity 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. Categories of workers are set in the app only.
MCP tool
org_pay_categories_set on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • category_idstring
  • namestringrequired

    1–80 characters.

  • title_idsstring[]required

    1–500 items.

  • rationalestringrequired

    10–2000 characters.

Returns

8 fields
  • idstringrequired
  • namestringrequired
  • rationalestringrequired
  • titlesobject[]required
    5 fields
    • idstringrequired
    • namestringrequired
    • scorenumber | nullrequired
    • approvedbooleanrequired

      False when its evaluation was edited since (back to draft): approve it again.

    • peopleintegerrequired
  • peopleintegerrequired
  • created_atstringrequired
  • updated_atstringrequired
  • createdbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_categories.set \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "category_id": "c1",
  "name": "Engineering",
  "title_ids": [
    "t1"
  ],
  "rationale": "Same engineering work, equal evaluation scores."
}'
Response
{
  "data": {
    "id": "c1",
    "name": "Engineering",
    "rationale": "Same engineering work, equal evaluation scores.",
    "titles": [
      {
        "id": "t1",
        "name": "Back-end Engineer",
        "score": 65,
        "approved": true,
        "people": 6
      }
    ],
    "people": 6,
    "created_at": "2026-10-02T10:00:00.000Z",
    "updated_at": "2026-10-02T10:00:00.000Z",
    "created": true
  }
}

Remove a pay category#

POST/v1/org/pay_categories.removeDestructive

Deletes a pay category (category_id); its titles become unplaced. Evaluations stay. Owners, admins and HR, in the app only (never over an API key or MCP). Part of the Pay equity 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. Categories of workers are changed in the app only.
MCP tool
org_pay_categories_remove on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • category_idstringrequired

Returns

  • idstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_categories.remove \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"category_id":"c1"}'
Response
{
  "data": {
    "id": "c1"
  }
}

Get pay equity settings#

POST/v1/org/pay_equity.settings.getRead

The company's pay equity settings: factor weights for job evaluations (sum 100; default 25 each, other 0), workers' representatives (exist, when they agreed the criteria, note), the standard full-time week (hours), the pay policy text shown to everyone (Art. 6), whether people see their own band, the month of the yearly pay-rights reminder, and the smallest group shown in answers to pay questions. Owners, admins and HR. Part of the Pay equity 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
MCP tool
org_pay_equity_settings_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

8 fields
  • weightsobjectrequired
    5 fields
    • skillsnumberrequired
    • effortnumberrequired
    • responsibilitynumberrequired
    • working_conditionsnumberrequired
    • othernumberrequired
  • representativesobjectrequired
    3 fields
    • existbooleanrequired
    • criteria_agreed_onstring | nullrequired
    • notestring | nullrequired
  • standard_week_hoursnumberrequired
  • pay_policystring | nullrequired
  • show_bands_to_peoplebooleanrequired
  • reminder_monthintegerrequired
  • min_groupintegerrequired
  • updated_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_equity.settings.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "weights": {
      "skills": 25,
      "effort": 25,
      "responsibility": 25,
      "working_conditions": 25,
      "other": 0
    },
    "representatives": {
      "exist": false,
      "criteria_agreed_on": null,
      "note": null
    },
    "standard_week_hours": 40,
    "pay_policy": null,
    "show_bands_to_people": false,
    "reminder_month": 1,
    "min_group": 3,
    "updated_at": null
  }
}

Change pay equity settings#

POST/v1/org/pay_equity.settings.updateWrite

Changes pay equity settings (see org_pay_equity_settings_get); send only what changes. weights must be five integers adding up to 100 (scores of every evaluation follow at once). Owners and admins only, and only in the app: never over an API key or MCP. Part of the Pay equity module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

Web app only
Refused for API keys and connected apps. Pay equity settings are changed in the app only.
MCP tool
org_pay_equity_settings_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • weightsobject

    Factor weights in %, integers adding up to 100. "other" weighs the average of any other factors an evaluation names.

    5 fields
    • skillsintegerrequired

      From 0 to 100.

    • effortintegerrequired

      From 0 to 100.

    • responsibilityintegerrequired

      From 0 to 100.

    • working_conditionsintegerrequired

      From 0 to 100.

    • otherintegerrequired

      From 0 to 100.

  • representativesobject

    Whether workers' representatives exist, when they agreed the evaluation criteria (Art. 4(4)), and a note.

    3 fields
    • existbooleanrequired
    • criteria_agreed_onstring | nullrequired
    • notestring | nullrequired

      Up to 500 characters.

  • standard_week_hoursnumber

    A full-time week, for hourly pay levels when a job has no weekly hours.

    From 1 to 60.

  • pay_policystring | null

    How pay, pay levels and progression are set (Art. 6), shown to everyone.

    Up to 10000 characters.

  • show_bands_to_peopleboolean

    Whether people see their own band and where they sit in it.

  • reminder_monthinteger

    The month everyone is reminded of their right to ask about pay levels.

    From 1 to 12.

  • min_groupinteger

    The fewest people of each sex in a category before averages are shown to someone asking.

    From 3 to 10.

Returns

8 fields
  • weightsobjectrequired
    5 fields
    • skillsnumberrequired
    • effortnumberrequired
    • responsibilitynumberrequired
    • working_conditionsnumberrequired
    • othernumberrequired
  • representativesobjectrequired
    3 fields
    • existbooleanrequired
    • criteria_agreed_onstring | nullrequired
    • notestring | nullrequired
  • standard_week_hoursnumberrequired
  • pay_policystring | nullrequired
  • show_bands_to_peoplebooleanrequired
  • reminder_monthintegerrequired
  • min_groupintegerrequired
  • updated_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_equity.settings.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "weights": {
    "skills": 30,
    "effort": 20,
    "responsibility": 30,
    "working_conditions": 20,
    "other": 0
  },
  "representatives": {
    "exist": true,
    "criteria_agreed_on": "2026-09-01",
    "note": null
  },
  "standard_week_hours": 40,
  "pay_policy": "Pay follows the band of your job.",
  "reminder_month": 3,
  "min_group": 5
}'
Response
{
  "data": {
    "weights": {
      "skills": 25,
      "effort": 25,
      "responsibility": 25,
      "working_conditions": 25,
      "other": 0
    },
    "representatives": {
      "exist": false,
      "criteria_agreed_on": null,
      "note": null
    },
    "standard_week_hours": 40,
    "pay_policy": "Pay follows the band of your job.",
    "show_bands_to_people": true,
    "reminder_month": 3,
    "min_group": 5,
    "updated_at": "2026-10-04T10:00:00.000Z"
  }
}

Pay gap overview (live)#

POST/v1/org/pay_equity.overviewRead

The live gender pay gap of a legal entity (legal_entity_id, default the first active one) for the year to date (from 1 January of as_of's year to as_of, default today), on base pay recorded in Bizisy (no variable pay: that comes in with a report). Per category of workers: women, men, not included (another, undisclosed or not recorded), mean and median gap on hourly pay (% of the men's; negative: women are paid more), flagged when the mean gap is 5% or more either way, and people below or above their band. Entity-wide: the Art. 9 indicators (mean and median gaps on hourly and annual pay, pay quartiles). attention lists what weakens the numbers, each with ids to fix: titles not evaluated, people whose title is in no category, people with no sex recorded, no pay, or pay in another currency (left out). Hourly pay = pay over the paid days ÷ hours (weekly hours of the job, else FTE × the standard week in Pay equity → Settings). Owners, admins and HR, in the app only (pay data: never over an API key or MCP). Part of the Pay equity module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

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

Input

  • legal_entity_idstring
  • as_ofstring

Returns

15 fields
  • legal_entityobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • entitiesobject[]required

    Active legal entities: pass one as legal_entity_id to switch.

    2 fields
    • idstringrequired
    • namestringrequired
  • periodobjectrequired
    2 fields
    • fromstringrequired
    • tostringrequired
  • currencystring | nullrequired
  • other_currenciesstring[]required
  • populationintegerrequired
  • includedintegerrequired
  • excludedobjectrequired
    2 fields
    • no_payintegerrequired
    • other_currencyintegerrequired
  • indicatorsobjectrequired
    13 fields
    • womenintegerrequired
    • menintegerrequired
    • not_includedintegerrequired

      Included in pay but recorded as another, undisclosed or not recorded: counted, not compared.

    • mean_gapnumber | nullrequired

      Mean gender pay gap on gross hourly pay, % of the men's mean (Art. 9(1)(a)); negative: women are paid more. Null when either sex has nobody.

    • median_gapnumber | nullrequired

      Median gap on gross hourly pay (Art. 9(1)(c)).

    • annual_mean_gapnumber | nullrequired
    • annual_median_gapnumber | nullrequired
    • variable_mean_gapnumber | nullrequired

      Mean gap in variable components among all workers of each sex (Art. 9(1)(b)); null without variable pay.

    • variable_median_gapnumber | nullrequired
    • women_receiving_variable_pctnumber | nullrequired
    • men_receiving_variable_pctnumber | nullrequired
    • quartilesobject[]required

      Four groups by hourly pay, lowest first (Art. 9(1)(f)); n mod 4 extra people go to the first groups.

      6 fields
      • quartileintegerrequired
      • peopleintegerrequired
      • womenintegerrequired
      • menintegerrequired
      • women_pctnumber | nullrequired
      • men_pctnumber | nullrequired
    • componentsobject[]

      Reports only: each complementary or variable component (bonus, allowances, in kind) with its total, the share of women and men receiving it and its mean and median gap among all workers of each sex.

      6 fields
      • component"bonus" | "allowances" | "in_kind"required
      • totalnumberrequired
      • women_receiving_pctnumber | nullrequired
      • men_receiving_pctnumber | nullrequired
      • mean_gapnumber | nullrequired
      • median_gapnumber | nullrequired
  • categoriesobject[]required
    11 fields
    • idstringrequired
    • namestringrequired
    • womenintegerrequired
    • menintegerrequired
    • not_includedintegerrequired
    • mean_gapnumber | nullrequired
    • median_gapnumber | nullrequired
    • flaggedbooleanrequired

      Mean gap of 5% or more either way, in a category that is not small_group.

    • small_groupbooleanrequired

      Fewer than the company's minimum (min_group, default 3) of women or of men: too few to compare, never flagged here (a report still flags it).

    • below_bandintegerrequired

      People in the category on the period's last day whose pay is below their band.

    • above_bandintegerrequired
  • uncategorisedintegerrequired
  • thresholdnumberrequired
  • min_groupintegerrequired
  • dutyobjectrequired
    2 fields
    • last_yearobjectrequired

      The Art. 9 reporting duty from last year's average workers: due_by is when a report on last year is due, null when none is.

      12 fields
      • bandstringrequired

        e.g. "250+", "150-249", "under-100".

      • minintegerrequired
      • maxinteger | nullrequired
      • every_yearsinteger | nullrequired

        How often this band reports; null: no duty.

      • first_dueinteger | nullrequired

        The year the first report of this band is due (7 June).

      • sourcestringrequired
      • source_labelstringrequired

        The law the thresholds come from.

      • enactedbooleanrequired
      • notestring | nullrequired

        What else matters under that law (English), e.g. a different report period or who prepares the report.

      • due_bystring | nullrequired

        When a report on this year is due (7 June of the next year); null when this band reports no such year.

      • yearintegerrequired
      • workersintegerrequired
    • this_yearobjectrequired

      Average workers so far this year, as a hint of next year's duty (due_by: a report on this year).

      12 fields
      • bandstringrequired

        e.g. "250+", "150-249", "under-100".

      • minintegerrequired
      • maxinteger | nullrequired
      • every_yearsinteger | nullrequired

        How often this band reports; null: no duty.

      • first_dueinteger | nullrequired

        The year the first report of this band is due (7 June).

      • sourcestringrequired
      • source_labelstringrequired

        The law the thresholds come from.

      • enactedbooleanrequired
      • notestring | nullrequired

        What else matters under that law (English), e.g. a different report period or who prepares the report.

      • due_bystring | nullrequired

        When a report on this year is due (7 June of the next year); null when this band reports no such year.

      • yearintegerrequired
      • workersintegerrequired
  • attentionobject[]required
    3 fields
    • kind"titles_not_evaluated" | "no_category" | "no_sex" | "no_pay" | "other_currency"required

      titles_not_evaluated (title ids: evaluate and approve them), no_category (person ids whose title is in no category), no_sex (person ids with no sex recorded), no_pay (person ids with no pay in the period), other_currency (person ids paid in another currency).

    • countintegerrequired
    • idsstring[]required

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_equity.overview \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"legal_entity_id":"e1","as_of":"2026-06-30"}'
Response
{
  "data": {
    "legal_entity": {
      "id": "e1",
      "name": "Acme Lda"
    },
    "entities": [
      {
        "id": "e1",
        "name": "Acme Lda"
      }
    ],
    "period": {
      "from": "2026-01-01",
      "to": "2026-10-04"
    },
    "currency": "EUR",
    "other_currencies": [],
    "population": 22,
    "included": 21,
    "excluded": {
      "no_pay": 1,
      "other_currency": 0
    },
    "indicators": {
      "women": 9,
      "men": 11,
      "not_included": 1,
      "mean_gap": 6.2,
      "median_gap": 4.8,
      "annual_mean_gap": 9.1,
      "annual_median_gap": 7.5,
      "variable_mean_gap": null,
      "variable_median_gap": null,
      "women_receiving_variable_pct": 0,
      "men_receiving_variable_pct": 0,
      "quartiles": [
        {
          "quartile": 1,
          "people": 5,
          "women": 3,
          "men": 2,
          "women_pct": 60,
          "men_pct": 40
        },
        {
          "quartile": 2,
          "people": 5,
          "women": 3,
          "men": 2,
          "women_pct": 60,
          "men_pct": 40
        },
        {
          "quartile": 3,
          "people": 5,
          "women": 2,
          "men": 3,
          "women_pct": 40,
          "men_pct": 60
        },
        {
          "quartile": 4,
          "people": 5,
          "women": 1,
          "men": 4,
          "women_pct": 20,
          "men_pct": 80
        }
      ]
    },
    "categories": [
      {
        "id": "c1",
        "name": "Engineering",
        "women": 3,
        "men": 5,
        "not_included": 0,
        "mean_gap": 6.8,
        "median_gap": 5.1,
        "flagged": true,
        "small_group": false,
        "below_band": 1,
        "above_band": 0
      }
    ],
    "uncategorised": 2,
    "threshold": 5,
    "min_group": 3,
    "attention": [
      {
        "kind": "no_sex",
        "count": 1,
        "ids": [
          "p7"
        ]
      },
      {
        "kind": "titles_not_evaluated",
        "count": 2,
        "ids": [
          "t3",
          "t4"
        ]
      }
    ],
    "duty": {
      "last_year": {
        "band": "under-50",
        "min": 0,
        "max": 49,
        "every_years": null,
        "first_due": null,
        "source": "pt-draft-2026-08",
        "source_label": "PT: Lei 60/2018 amendment (5 Aug 2026) (draft, not yet in force)",
        "enacted": false,
        "note": null,
        "due_by": null,
        "year": 2025,
        "workers": 21
      },
      "this_year": {
        "band": "under-50",
        "min": 0,
        "max": 49,
        "every_years": null,
        "first_due": null,
        "source": "pt-draft-2026-08",
        "source_label": "PT: Lei 60/2018 amendment (5 Aug 2026) (draft, not yet in force)",
        "enacted": false,
        "note": null,
        "due_by": null,
        "year": 2026,
        "workers": 22
      }
    }
  }
}

List pay gap reports#

POST/v1/org/pay_reports.listRead

The company's Art. 9 pay gap reports (EU Pay Transparency Directive), newest year first: legal entity, year, draft or final, average workers and the reporting duty (by the entity's country: its own law where Bizisy has it, else the Directive's minimum), how many categories have a mean gap of 5% or more (flagged), how many of those have no justification, and on final reports how many may need a joint pay assessment (Art. 10). Owners, admins and HR, in the app only (never over an API key or MCP). Part of the Pay equity 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. Pay gap reports are pay data: read in the app only.
MCP tool
org_pay_reports_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • legal_entity_idstring

Returns

  • itemsobject[]required
    14 fields
    • idstringrequired
    • legal_entityobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • yearintegerrequired
    • status"draft" | "final"required
    • headcountintegerrequired
    • dutyobjectrequired

      By the legal entity's country and its average workers (Σ days employed ÷ days in the year). Countries without their own law in Bizisy follow the Directive's minimum (source eu-directive; a country may set lower thresholds): 250+ report every year from 7 June 2027, 150–249 every three years from 2027, 100–149 every three years from 7 June 2031, under 100 no duty. Countries with a law or draft of their own use it (source names it; enacted false = a draft not yet in force).

      10 fields
      • bandstringrequired

        e.g. "250+", "150-249", "under-100".

      • minintegerrequired
      • maxinteger | nullrequired
      • every_yearsinteger | nullrequired

        How often this band reports; null: no duty.

      • first_dueinteger | nullrequired

        The year the first report of this band is due (7 June).

      • sourcestringrequired
      • source_labelstringrequired

        The law the thresholds come from.

      • enactedbooleanrequired
      • notestring | nullrequired

        What else matters under that law (English), e.g. a different report period or who prepares the report.

      • due_bystring | nullrequired

        When a report on this year is due (7 June of the next year); null when this band reports no such year.

    • flaggedintegerrequired

      Categories with a mean gap of 5% or more.

    • unjustifiedintegerrequired

      Flagged categories with no justification yet.

    • assessment_dueintegerrequired
    • inputs_countintegerrequired
    • created_atstringrequired
    • updated_atstringrequired
    • finalised_atstring | nullrequired
    • submitted_onstring | nullrequired
  • dutiesobject[]required

    Each active legal entity's duty for last year (by its country's law and last year's average workers): due_by is when a report on last year is due, null when none is required.

    14 fields
    • bandstringrequired

      e.g. "250+", "150-249", "under-100".

    • minintegerrequired
    • maxinteger | nullrequired
    • every_yearsinteger | nullrequired

      How often this band reports; null: no duty.

    • first_dueinteger | nullrequired

      The year the first report of this band is due (7 June).

    • sourcestringrequired
    • source_labelstringrequired

      The law the thresholds come from.

    • enactedbooleanrequired
    • notestring | nullrequired

      What else matters under that law (English), e.g. a different report period or who prepares the report.

    • due_bystring | nullrequired

      When a report on this year is due (7 June of the next year); null when this band reports no such year.

    • legal_entityobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • yearintegerrequired
    • workersintegerrequired
    • report_idstring | nullrequired

      That year's report, when one exists.

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_reports.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"legal_entity_id":"e1"}'
Response
{
  "data": {
    "items": [
      {
        "id": "pr1",
        "legal_entity": {
          "id": "e1",
          "name": "Acme Lda"
        },
        "year": 2025,
        "status": "draft",
        "headcount": 21,
        "duty": {
          "band": "under-50",
          "min": 0,
          "max": 49,
          "every_years": null,
          "first_due": null,
          "source": "pt-draft-2026-08",
          "source_label": "PT: Lei 60/2018 amendment (5 Aug 2026) (draft, not yet in force)",
          "enacted": false,
          "note": null,
          "due_by": null
        },
        "flagged": 1,
        "unjustified": 0,
        "assessment_due": 0,
        "inputs_count": 18,
        "created_at": "2026-02-01T10:00:00.000Z",
        "updated_at": "2026-02-03T10:00:00.000Z",
        "finalised_at": null,
        "submitted_on": null
      }
    ],
    "duties": [
      {
        "band": "under-50",
        "min": 0,
        "max": 49,
        "every_years": null,
        "first_due": null,
        "source": "pt-draft-2026-08",
        "source_label": "PT: Lei 60/2018 amendment (5 Aug 2026) (draft, not yet in force)",
        "enacted": false,
        "note": null,
        "due_by": null,
        "legal_entity": {
          "id": "e1",
          "name": "Acme Lda"
        },
        "year": 2025,
        "workers": 21,
        "report_id": "pr1"
      }
    ]
  }
}

Get a pay gap report#

POST/v1/org/pay_reports.getRead

One pay gap report (report_id) with everything Art. 9 asks for: the population (people with a job in the entity on at least one day of the year), who was left out (no pay, another currency), the indicators (mean and median gaps on hourly and annual pay, the same on variable components, the share of women and men receiving variable pay, pay quartiles) and per category of workers the gaps on basic pay, variable pay and in total, each with its justification. A category whose mean gap is 5% or more is flagged; on a final report assessment_due says a joint pay assessment with workers' representatives may be due (not justified by objective factors, or the remedy date passed; Art. 10). Gaps are % of the men's pay; negative: women are paid more. Owners, admins and HR, in the app only. Part of the Pay equity 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. Pay gap reports are pay data: read in the app only.
MCP tool
org_pay_reports_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • report_idstringrequired

Returns

23 fields
  • idstringrequired
  • legal_entityobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • yearintegerrequired
  • status"draft" | "final"required
  • headcountintegerrequired
  • dutyobjectrequired

    By the legal entity's country and its average workers (Σ days employed ÷ days in the year). Countries without their own law in Bizisy follow the Directive's minimum (source eu-directive; a country may set lower thresholds): 250+ report every year from 7 June 2027, 150–249 every three years from 2027, 100–149 every three years from 7 June 2031, under 100 no duty. Countries with a law or draft of their own use it (source names it; enacted false = a draft not yet in force).

    10 fields
    • bandstringrequired

      e.g. "250+", "150-249", "under-100".

    • minintegerrequired
    • maxinteger | nullrequired
    • every_yearsinteger | nullrequired

      How often this band reports; null: no duty.

    • first_dueinteger | nullrequired

      The year the first report of this band is due (7 June).

    • sourcestringrequired
    • source_labelstringrequired

      The law the thresholds come from.

    • enactedbooleanrequired
    • notestring | nullrequired

      What else matters under that law (English), e.g. a different report period or who prepares the report.

    • due_bystring | nullrequired

      When a report on this year is due (7 June of the next year); null when this band reports no such year.

  • flaggedintegerrequired

    Categories with a mean gap of 5% or more.

  • unjustifiedintegerrequired

    Flagged categories with no justification yet.

  • assessment_dueintegerrequired
  • inputs_countintegerrequired
  • created_atstringrequired
  • updated_atstringrequired
  • finalised_atstring | nullrequired
  • submitted_onstring | nullrequired
  • currencystring | nullrequired
  • populationintegerrequired
  • excludedobjectrequired

    People in the population left out of the gaps: no pay recorded, or pay in another currency than the entity's main one.

    2 fields
    • no_payintegerrequired
    • other_currencyintegerrequired
  • indicatorsobjectrequired
    13 fields
    • womenintegerrequired
    • menintegerrequired
    • not_includedintegerrequired

      Included in pay but recorded as another, undisclosed or not recorded: counted, not compared.

    • mean_gapnumber | nullrequired

      Mean gender pay gap on gross hourly pay, % of the men's mean (Art. 9(1)(a)); negative: women are paid more. Null when either sex has nobody.

    • median_gapnumber | nullrequired

      Median gap on gross hourly pay (Art. 9(1)(c)).

    • annual_mean_gapnumber | nullrequired
    • annual_median_gapnumber | nullrequired
    • variable_mean_gapnumber | nullrequired

      Mean gap in variable components among all workers of each sex (Art. 9(1)(b)); null without variable pay.

    • variable_median_gapnumber | nullrequired
    • women_receiving_variable_pctnumber | nullrequired
    • men_receiving_variable_pctnumber | nullrequired
    • quartilesobject[]required

      Four groups by hourly pay, lowest first (Art. 9(1)(f)); n mod 4 extra people go to the first groups.

      6 fields
      • quartileintegerrequired
      • peopleintegerrequired
      • womenintegerrequired
      • menintegerrequired
      • women_pctnumber | nullrequired
      • men_pctnumber | nullrequired
    • componentsobject[]

      Reports only: each complementary or variable component (bonus, allowances, in kind) with its total, the share of women and men receiving it and its mean and median gap among all workers of each sex.

      6 fields
      • component"bonus" | "allowances" | "in_kind"required
      • totalnumberrequired
      • women_receiving_pctnumber | nullrequired
      • men_receiving_pctnumber | nullrequired
      • mean_gapnumber | nullrequired
      • median_gapnumber | nullrequired
  • categoriesobject[]required
    15 fields
    • idstringrequired
    • namestringrequired
    • womenintegerrequired
    • menintegerrequired
    • not_includedintegerrequired
    • base_mean_gapnumber | nullrequired
    • base_median_gapnumber | nullrequired
    • variable_mean_gapnumber | nullrequired
    • variable_median_gapnumber | nullrequired
    • total_mean_gapnumber | nullrequired
    • total_median_gapnumber | nullrequired
    • flaggedbooleanrequired

      |total_mean_gap| ≥ 5%: needs a justification by objective, gender-neutral factors or a remedy (Art. 10).

    • small_groupbooleanrequired

      Fewer than the company's minimum (min_group) of women or of men: the figures may reveal individual pay and say little; still flagged at the threshold, as the law sets it for every category.

    • assessment_duebooleanrequired

      Final report only: flagged and not justified by objective factors, or its remedy date has passed: a joint pay assessment with workers' representatives may be due.

    • justificationobject | nullrequired
      6 fields
      • reasonstringrequired
      • objective_factorsstring[]required
      • remedystring | nullrequired
      • remedy_bystring | nullrequired
      • updated_bystringrequired
      • updated_atstringrequired
  • uncategorisedintegerrequired

    Included people whose job title is in no pay category.

  • variable_sourcesobject | nullrequired

    Where the variable pay came from (totals only); null on reports made before it was read from Bizisy.

    4 fields
    • payrollobjectrequired
      4 fields
      • onbooleanrequired

        Payroll is on: its pay items in money count.

      • itemsobject[]required
        6 fields
        • idstringrequired
        • namestringrequired
        • component"bonus" | "allowances" | "not_pay"required
        • changedbooleanrequired

          HR changed it from the default.

        • totalnumber | nullrequired

          null when fewer than min_group people received it (it would show their pay).

        • peopleintegerrequired
      • not_in_moneyintegerrequired

        Earnings in hours or days: not counted (no amount).

      • other_currencyintegerrequired

        Amounts in another currency than the report's: not counted.

    • benefitsobjectrequired
      4 fields
      • onbooleanrequired
      • in_kindnumber | nullrequired
      • allowancesnumber | nullrequired

        Cash meal allowances. Both null when fewer than min_group people received benefits.

      • peopleintegerrequired
    • fileobjectrequired
      2 fields
      • peopleintegerrequired
      • columns"bonus" | "allowances" | "in_kind"[]required

        For these columns, the file's amount replaces Bizisy's for the people in it.

    • bonusesobject

      Bonus plans' awards paid by hand (awards paid through Payroll are its Bonus items).

      3 fields
      • onbooleanrequired
      • totalnumber | nullrequired

        null when fewer than min_group people received one.

      • peopleintegerrequired
  • finalised_bystring | nullrequired
  • follow_upobjectrequired
    3 fields
    • remedy_window_endsstring | nullrequired

      Six months after finalising (Art. 10(1)(c)): gaps not justified or remedied by then call for a joint pay assessment.

    • assessment_within_daysinteger | nullrequired

      Days to carry out a joint pay assessment once due, when the entity's national law sets it; null otherwise.

    • authoritystring | nullrequired

      Who receives the report, when national law names it; null otherwise.

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_reports.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"report_id":"pr1"}'
Response
{
  "data": {
    "id": "pr1",
    "legal_entity": {
      "id": "e1",
      "name": "Acme Lda"
    },
    "year": 2025,
    "status": "draft",
    "headcount": 21,
    "duty": {
      "band": "under-50",
      "min": 0,
      "max": 49,
      "every_years": null,
      "first_due": null,
      "source": "pt-draft-2026-08",
      "source_label": "PT: Lei 60/2018 amendment (5 Aug 2026) (draft, not yet in force)",
      "enacted": false,
      "note": null,
      "due_by": null
    },
    "flagged": 1,
    "unjustified": 0,
    "assessment_due": 0,
    "inputs_count": 18,
    "created_at": "2026-02-01T10:00:00.000Z",
    "updated_at": "2026-02-03T10:00:00.000Z",
    "finalised_at": null,
    "submitted_on": null,
    "currency": "EUR",
    "population": 22,
    "excluded": {
      "no_pay": 1,
      "other_currency": 0
    },
    "uncategorised": 2,
    "finalised_by": null,
    "indicators": {
      "women": 9,
      "men": 11,
      "not_included": 1,
      "mean_gap": 6.2,
      "median_gap": 4.8,
      "annual_mean_gap": 9.1,
      "annual_median_gap": 7.5,
      "variable_mean_gap": 22.4,
      "variable_median_gap": null,
      "women_receiving_variable_pct": 33.3,
      "men_receiving_variable_pct": 45.5,
      "quartiles": [
        {
          "quartile": 1,
          "people": 5,
          "women": 3,
          "men": 2,
          "women_pct": 60,
          "men_pct": 40
        },
        {
          "quartile": 2,
          "people": 5,
          "women": 3,
          "men": 2,
          "women_pct": 60,
          "men_pct": 40
        },
        {
          "quartile": 3,
          "people": 5,
          "women": 2,
          "men": 3,
          "women_pct": 40,
          "men_pct": 60
        },
        {
          "quartile": 4,
          "people": 5,
          "women": 1,
          "men": 4,
          "women_pct": 20,
          "men_pct": 80
        }
      ],
      "components": [
        {
          "component": "bonus",
          "total": 48200,
          "women_receiving_pct": 41.7,
          "men_receiving_pct": 60,
          "mean_gap": 22.4,
          "median_gap": 18
        },
        {
          "component": "allowances",
          "total": 9600,
          "women_receiving_pct": 100,
          "men_receiving_pct": 100,
          "mean_gap": 1.2,
          "median_gap": 0
        },
        {
          "component": "in_kind",
          "total": 26400,
          "women_receiving_pct": 91.7,
          "men_receiving_pct": 90,
          "mean_gap": -2.5,
          "median_gap": 0
        }
      ]
    },
    "variable_sources": {
      "payroll": {
        "on": true,
        "items": [
          {
            "id": "it1",
            "name": "Annual bonus",
            "component": "bonus",
            "changed": false,
            "total": 48200,
            "people": 11
          },
          {
            "id": "it2",
            "name": "Salary advance",
            "component": "not_pay",
            "changed": false,
            "total": 3000,
            "people": 2
          }
        ],
        "not_in_money": 4,
        "other_currency": 0
      },
      "benefits": {
        "on": true,
        "in_kind": 26400,
        "allowances": 9600,
        "people": 22
      },
      "file": {
        "people": 0,
        "columns": []
      }
    },
    "categories": [
      {
        "id": "c1",
        "name": "Engineering",
        "women": 3,
        "men": 5,
        "not_included": 0,
        "base_mean_gap": 6.8,
        "base_median_gap": 5.1,
        "variable_mean_gap": 18,
        "variable_median_gap": 12.5,
        "total_mean_gap": 7.4,
        "total_median_gap": 5.9,
        "flagged": true,
        "small_group": false,
        "assessment_due": false,
        "justification": {
          "reason": "Two engineers joined in 2025 with ten or more years in the role.",
          "objective_factors": [
            "Years of relevant experience"
          ],
          "remedy": null,
          "remedy_by": null,
          "updated_by": "u1",
          "updated_at": "2026-02-03T10:00:00.000Z"
        }
      }
    ],
    "follow_up": {
      "remedy_window_ends": null,
      "assessment_within_days": 45,
      "authority": null
    }
  }
}

Create a pay gap report#

POST/v1/org/pay_reports.createWrite

Creates the Art. 9 pay gap report of a legal entity (legal_entity_id) for a past calendar year (year, before the current one) as a draft, computed from the pay and jobs recorded in Bizisy for that year. One report per entity and year: calling it again for a draft recomputes it (variable pay uploaded and justifications are kept); a final report is refused. Then upload variable pay (org_pay_reports_upload_variable), justify categories with a gap of 5% or more (org_pay_reports_justify) and finalise (org_pay_reports_finalise). Owners, admins and HR, in the app only. Use dry_run to preview the numbers. Part of the Pay equity module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

Web app only
Refused for API keys and connected apps. Pay gap reports are made in the app only.
MCP tool
org_pay_reports_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

  • legal_entity_idstringrequired
  • yearintegerrequired

    From 2000 to 2100.

Returns

24 fields
  • idstringrequired
  • legal_entityobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • yearintegerrequired
  • status"draft" | "final"required
  • headcountintegerrequired
  • dutyobjectrequired

    By the legal entity's country and its average workers (Σ days employed ÷ days in the year). Countries without their own law in Bizisy follow the Directive's minimum (source eu-directive; a country may set lower thresholds): 250+ report every year from 7 June 2027, 150–249 every three years from 2027, 100–149 every three years from 7 June 2031, under 100 no duty. Countries with a law or draft of their own use it (source names it; enacted false = a draft not yet in force).

    10 fields
    • bandstringrequired

      e.g. "250+", "150-249", "under-100".

    • minintegerrequired
    • maxinteger | nullrequired
    • every_yearsinteger | nullrequired

      How often this band reports; null: no duty.

    • first_dueinteger | nullrequired

      The year the first report of this band is due (7 June).

    • sourcestringrequired
    • source_labelstringrequired

      The law the thresholds come from.

    • enactedbooleanrequired
    • notestring | nullrequired

      What else matters under that law (English), e.g. a different report period or who prepares the report.

    • due_bystring | nullrequired

      When a report on this year is due (7 June of the next year); null when this band reports no such year.

  • flaggedintegerrequired

    Categories with a mean gap of 5% or more.

  • unjustifiedintegerrequired

    Flagged categories with no justification yet.

  • assessment_dueintegerrequired
  • inputs_countintegerrequired
  • created_atstringrequired
  • updated_atstringrequired
  • finalised_atstring | nullrequired
  • submitted_onstring | nullrequired
  • currencystring | nullrequired
  • populationintegerrequired
  • excludedobjectrequired

    People in the population left out of the gaps: no pay recorded, or pay in another currency than the entity's main one.

    2 fields
    • no_payintegerrequired
    • other_currencyintegerrequired
  • indicatorsobjectrequired
    13 fields
    • womenintegerrequired
    • menintegerrequired
    • not_includedintegerrequired

      Included in pay but recorded as another, undisclosed or not recorded: counted, not compared.

    • mean_gapnumber | nullrequired

      Mean gender pay gap on gross hourly pay, % of the men's mean (Art. 9(1)(a)); negative: women are paid more. Null when either sex has nobody.

    • median_gapnumber | nullrequired

      Median gap on gross hourly pay (Art. 9(1)(c)).

    • annual_mean_gapnumber | nullrequired
    • annual_median_gapnumber | nullrequired
    • variable_mean_gapnumber | nullrequired

      Mean gap in variable components among all workers of each sex (Art. 9(1)(b)); null without variable pay.

    • variable_median_gapnumber | nullrequired
    • women_receiving_variable_pctnumber | nullrequired
    • men_receiving_variable_pctnumber | nullrequired
    • quartilesobject[]required

      Four groups by hourly pay, lowest first (Art. 9(1)(f)); n mod 4 extra people go to the first groups.

      6 fields
      • quartileintegerrequired
      • peopleintegerrequired
      • womenintegerrequired
      • menintegerrequired
      • women_pctnumber | nullrequired
      • men_pctnumber | nullrequired
    • componentsobject[]

      Reports only: each complementary or variable component (bonus, allowances, in kind) with its total, the share of women and men receiving it and its mean and median gap among all workers of each sex.

      6 fields
      • component"bonus" | "allowances" | "in_kind"required
      • totalnumberrequired
      • women_receiving_pctnumber | nullrequired
      • men_receiving_pctnumber | nullrequired
      • mean_gapnumber | nullrequired
      • median_gapnumber | nullrequired
  • categoriesobject[]required
    15 fields
    • idstringrequired
    • namestringrequired
    • womenintegerrequired
    • menintegerrequired
    • not_includedintegerrequired
    • base_mean_gapnumber | nullrequired
    • base_median_gapnumber | nullrequired
    • variable_mean_gapnumber | nullrequired
    • variable_median_gapnumber | nullrequired
    • total_mean_gapnumber | nullrequired
    • total_median_gapnumber | nullrequired
    • flaggedbooleanrequired

      |total_mean_gap| ≥ 5%: needs a justification by objective, gender-neutral factors or a remedy (Art. 10).

    • small_groupbooleanrequired

      Fewer than the company's minimum (min_group) of women or of men: the figures may reveal individual pay and say little; still flagged at the threshold, as the law sets it for every category.

    • assessment_duebooleanrequired

      Final report only: flagged and not justified by objective factors, or its remedy date has passed: a joint pay assessment with workers' representatives may be due.

    • justificationobject | nullrequired
      6 fields
      • reasonstringrequired
      • objective_factorsstring[]required
      • remedystring | nullrequired
      • remedy_bystring | nullrequired
      • updated_bystringrequired
      • updated_atstringrequired
  • uncategorisedintegerrequired

    Included people whose job title is in no pay category.

  • variable_sourcesobject | nullrequired

    Where the variable pay came from (totals only); null on reports made before it was read from Bizisy.

    4 fields
    • payrollobjectrequired
      4 fields
      • onbooleanrequired

        Payroll is on: its pay items in money count.

      • itemsobject[]required
        6 fields
        • idstringrequired
        • namestringrequired
        • component"bonus" | "allowances" | "not_pay"required
        • changedbooleanrequired

          HR changed it from the default.

        • totalnumber | nullrequired

          null when fewer than min_group people received it (it would show their pay).

        • peopleintegerrequired
      • not_in_moneyintegerrequired

        Earnings in hours or days: not counted (no amount).

      • other_currencyintegerrequired

        Amounts in another currency than the report's: not counted.

    • benefitsobjectrequired
      4 fields
      • onbooleanrequired
      • in_kindnumber | nullrequired
      • allowancesnumber | nullrequired

        Cash meal allowances. Both null when fewer than min_group people received benefits.

      • peopleintegerrequired
    • fileobjectrequired
      2 fields
      • peopleintegerrequired
      • columns"bonus" | "allowances" | "in_kind"[]required

        For these columns, the file's amount replaces Bizisy's for the people in it.

    • bonusesobject

      Bonus plans' awards paid by hand (awards paid through Payroll are its Bonus items).

      3 fields
      • onbooleanrequired
      • totalnumber | nullrequired

        null when fewer than min_group people received one.

      • peopleintegerrequired
  • finalised_bystring | nullrequired
  • follow_upobjectrequired
    3 fields
    • remedy_window_endsstring | nullrequired

      Six months after finalising (Art. 10(1)(c)): gaps not justified or remedied by then call for a joint pay assessment.

    • assessment_within_daysinteger | nullrequired

      Days to carry out a joint pay assessment once due, when the entity's national law sets it; null otherwise.

    • authoritystring | nullrequired

      Who receives the report, when national law names it; null otherwise.

  • createdbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_reports.create \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"legal_entity_id":"e1","year":2025}'
Response
{
  "data": {
    "id": "pr1",
    "legal_entity": {
      "id": "e1",
      "name": "Acme Lda"
    },
    "year": 2025,
    "status": "draft",
    "headcount": 21,
    "duty": {
      "band": "under-50",
      "min": 0,
      "max": 49,
      "every_years": null,
      "first_due": null,
      "source": "pt-draft-2026-08",
      "source_label": "PT: Lei 60/2018 amendment (5 Aug 2026) (draft, not yet in force)",
      "enacted": false,
      "note": null,
      "due_by": null
    },
    "flagged": 1,
    "unjustified": 0,
    "assessment_due": 0,
    "inputs_count": 18,
    "created_at": "2026-02-01T10:00:00.000Z",
    "updated_at": "2026-02-03T10:00:00.000Z",
    "finalised_at": null,
    "submitted_on": null,
    "currency": "EUR",
    "population": 22,
    "excluded": {
      "no_pay": 1,
      "other_currency": 0
    },
    "uncategorised": 2,
    "finalised_by": null,
    "indicators": {
      "women": 9,
      "men": 11,
      "not_included": 1,
      "mean_gap": 6.2,
      "median_gap": 4.8,
      "annual_mean_gap": 9.1,
      "annual_median_gap": 7.5,
      "variable_mean_gap": 22.4,
      "variable_median_gap": null,
      "women_receiving_variable_pct": 33.3,
      "men_receiving_variable_pct": 45.5,
      "quartiles": [
        {
          "quartile": 1,
          "people": 5,
          "women": 3,
          "men": 2,
          "women_pct": 60,
          "men_pct": 40
        },
        {
          "quartile": 2,
          "people": 5,
          "women": 3,
          "men": 2,
          "women_pct": 60,
          "men_pct": 40
        },
        {
          "quartile": 3,
          "people": 5,
          "women": 2,
          "men": 3,
          "women_pct": 40,
          "men_pct": 60
        },
        {
          "quartile": 4,
          "people": 5,
          "women": 1,
          "men": 4,
          "women_pct": 20,
          "men_pct": 80
        }
      ],
      "components": [
        {
          "component": "bonus",
          "total": 48200,
          "women_receiving_pct": 41.7,
          "men_receiving_pct": 60,
          "mean_gap": 22.4,
          "median_gap": 18
        },
        {
          "component": "allowances",
          "total": 9600,
          "women_receiving_pct": 100,
          "men_receiving_pct": 100,
          "mean_gap": 1.2,
          "median_gap": 0
        },
        {
          "component": "in_kind",
          "total": 26400,
          "women_receiving_pct": 91.7,
          "men_receiving_pct": 90,
          "mean_gap": -2.5,
          "median_gap": 0
        }
      ]
    },
    "variable_sources": {
      "payroll": {
        "on": true,
        "items": [
          {
            "id": "it1",
            "name": "Annual bonus",
            "component": "bonus",
            "changed": false,
            "total": 48200,
            "people": 11
          },
          {
            "id": "it2",
            "name": "Salary advance",
            "component": "not_pay",
            "changed": false,
            "total": 3000,
            "people": 2
          }
        ],
        "not_in_money": 4,
        "other_currency": 0
      },
      "benefits": {
        "on": true,
        "in_kind": 26400,
        "allowances": 9600,
        "people": 22
      },
      "file": {
        "people": 0,
        "columns": []
      }
    },
    "categories": [
      {
        "id": "c1",
        "name": "Engineering",
        "women": 3,
        "men": 5,
        "not_included": 0,
        "base_mean_gap": 6.8,
        "base_median_gap": 5.1,
        "variable_mean_gap": 18,
        "variable_median_gap": 12.5,
        "total_mean_gap": 7.4,
        "total_median_gap": 5.9,
        "flagged": true,
        "small_group": false,
        "assessment_due": false,
        "justification": {
          "reason": "Two engineers joined in 2025 with ten or more years in the role.",
          "objective_factors": [
            "Years of relevant experience"
          ],
          "remedy": null,
          "remedy_by": null,
          "updated_by": "u1",
          "updated_at": "2026-02-03T10:00:00.000Z"
        }
      }
    ],
    "follow_up": {
      "remedy_window_ends": null,
      "assessment_within_days": 45,
      "authority": null
    },
    "created": true
  }
}

Upload variable pay for a report#

POST/v1/org/pay_reports.upload_variableWrite

Uploads the year's variable pay of a draft report (report_id) as CSV text from payroll (comma or semicolon separated, first row = header, at most 1 MB and 250 rows): work_email (or employee, the work email), and any of bonus, allowances and in_kind (gross totals for the year in the report's currency, 0 or more; empty = 0; decimal comma or point). Rows of the same person are added together (listed in duplicates). Unknown emails and people outside the report's population (no job in the entity that year) are listed and skipped. With row_errors nothing is saved. The upload replaces the report's earlier variable pay; append: true adds to it instead (a person in the file replaces their earlier row), for files bigger than 250 rows. The report is recomputed. Per-person values are deleted when the report is finalised; only totals stay. Owners, admins and HR, in the app only. Use dry_run first. Part of the Pay equity 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. Variable pay is uploaded in the app only.
MCP tool
org_pay_reports_upload_variable 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

  • report_idstringrequired
  • csvstringrequired

    1–1000000 characters.

  • appendboolean

    Default false.

Returns

7 fields
  • reportobjectrequired
    23 fields
    • idstringrequired
    • legal_entityobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • yearintegerrequired
    • status"draft" | "final"required
    • headcountintegerrequired
    • dutyobjectrequired

      By the legal entity's country and its average workers (Σ days employed ÷ days in the year). Countries without their own law in Bizisy follow the Directive's minimum (source eu-directive; a country may set lower thresholds): 250+ report every year from 7 June 2027, 150–249 every three years from 2027, 100–149 every three years from 7 June 2031, under 100 no duty. Countries with a law or draft of their own use it (source names it; enacted false = a draft not yet in force).

      10 fields
      • bandstringrequired

        e.g. "250+", "150-249", "under-100".

      • minintegerrequired
      • maxinteger | nullrequired
      • every_yearsinteger | nullrequired

        How often this band reports; null: no duty.

      • first_dueinteger | nullrequired

        The year the first report of this band is due (7 June).

      • sourcestringrequired
      • source_labelstringrequired

        The law the thresholds come from.

      • enactedbooleanrequired
      • notestring | nullrequired

        What else matters under that law (English), e.g. a different report period or who prepares the report.

      • due_bystring | nullrequired

        When a report on this year is due (7 June of the next year); null when this band reports no such year.

    • flaggedintegerrequired

      Categories with a mean gap of 5% or more.

    • unjustifiedintegerrequired

      Flagged categories with no justification yet.

    • assessment_dueintegerrequired
    • inputs_countintegerrequired
    • created_atstringrequired
    • updated_atstringrequired
    • finalised_atstring | nullrequired
    • submitted_onstring | nullrequired
    • currencystring | nullrequired
    • populationintegerrequired
    • excludedobjectrequired

      People in the population left out of the gaps: no pay recorded, or pay in another currency than the entity's main one.

      2 fields
      • no_payintegerrequired
      • other_currencyintegerrequired
    • indicatorsobjectrequired
      13 fields
      • womenintegerrequired
      • menintegerrequired
      • not_includedintegerrequired

        Included in pay but recorded as another, undisclosed or not recorded: counted, not compared.

      • mean_gapnumber | nullrequired

        Mean gender pay gap on gross hourly pay, % of the men's mean (Art. 9(1)(a)); negative: women are paid more. Null when either sex has nobody.

      • median_gapnumber | nullrequired

        Median gap on gross hourly pay (Art. 9(1)(c)).

      • annual_mean_gapnumber | nullrequired
      • annual_median_gapnumber | nullrequired
      • variable_mean_gapnumber | nullrequired

        Mean gap in variable components among all workers of each sex (Art. 9(1)(b)); null without variable pay.

      • variable_median_gapnumber | nullrequired
      • women_receiving_variable_pctnumber | nullrequired
      • men_receiving_variable_pctnumber | nullrequired
      • quartilesobject[]required

        Four groups by hourly pay, lowest first (Art. 9(1)(f)); n mod 4 extra people go to the first groups.

        6 fields
        • quartileintegerrequired
        • peopleintegerrequired
        • womenintegerrequired
        • menintegerrequired
        • women_pctnumber | nullrequired
        • men_pctnumber | nullrequired
      • componentsobject[]

        Reports only: each complementary or variable component (bonus, allowances, in kind) with its total, the share of women and men receiving it and its mean and median gap among all workers of each sex.

        6 fields
        • component"bonus" | "allowances" | "in_kind"required
        • totalnumberrequired
        • women_receiving_pctnumber | nullrequired
        • men_receiving_pctnumber | nullrequired
        • mean_gapnumber | nullrequired
        • median_gapnumber | nullrequired
    • categoriesobject[]required
      15 fields
      • idstringrequired
      • namestringrequired
      • womenintegerrequired
      • menintegerrequired
      • not_includedintegerrequired
      • base_mean_gapnumber | nullrequired
      • base_median_gapnumber | nullrequired
      • variable_mean_gapnumber | nullrequired
      • variable_median_gapnumber | nullrequired
      • total_mean_gapnumber | nullrequired
      • total_median_gapnumber | nullrequired
      • flaggedbooleanrequired

        |total_mean_gap| ≥ 5%: needs a justification by objective, gender-neutral factors or a remedy (Art. 10).

      • small_groupbooleanrequired

        Fewer than the company's minimum (min_group) of women or of men: the figures may reveal individual pay and say little; still flagged at the threshold, as the law sets it for every category.

      • assessment_duebooleanrequired

        Final report only: flagged and not justified by objective factors, or its remedy date has passed: a joint pay assessment with workers' representatives may be due.

      • justificationobject | nullrequired
        6 fields
        • reasonstringrequired
        • objective_factorsstring[]required
        • remedystring | nullrequired
        • remedy_bystring | nullrequired
        • updated_bystringrequired
        • updated_atstringrequired
    • uncategorisedintegerrequired

      Included people whose job title is in no pay category.

    • variable_sourcesobject | nullrequired

      Where the variable pay came from (totals only); null on reports made before it was read from Bizisy.

      4 fields
      • payrollobjectrequired
        4 fields
        • onbooleanrequired

          Payroll is on: its pay items in money count.

        • itemsobject[]required
          6 fields
          • idstringrequired
          • namestringrequired
          • component"bonus" | "allowances" | "not_pay"required
          • changedbooleanrequired

            HR changed it from the default.

          • totalnumber | nullrequired

            null when fewer than min_group people received it (it would show their pay).

          • peopleintegerrequired
        • not_in_moneyintegerrequired

          Earnings in hours or days: not counted (no amount).

        • other_currencyintegerrequired

          Amounts in another currency than the report's: not counted.

      • benefitsobjectrequired
        4 fields
        • onbooleanrequired
        • in_kindnumber | nullrequired
        • allowancesnumber | nullrequired

          Cash meal allowances. Both null when fewer than min_group people received benefits.

        • peopleintegerrequired
      • fileobjectrequired
        2 fields
        • peopleintegerrequired
        • columns"bonus" | "allowances" | "in_kind"[]required

          For these columns, the file's amount replaces Bizisy's for the people in it.

      • bonusesobject

        Bonus plans' awards paid by hand (awards paid through Payroll are its Bonus items).

        3 fields
        • onbooleanrequired
        • totalnumber | nullrequired

          null when fewer than min_group people received one.

        • peopleintegerrequired
    • finalised_bystring | nullrequired
    • follow_upobjectrequired
      3 fields
      • remedy_window_endsstring | nullrequired

        Six months after finalising (Art. 10(1)(c)): gaps not justified or remedied by then call for a joint pay assessment.

      • assessment_within_daysinteger | nullrequired

        Days to carry out a joint pay assessment once due, when the entity's national law sets it; null otherwise.

      • authoritystring | nullrequired

        Who receives the report, when national law names it; null otherwise.

  • appliedbooleanrequired

    False when row_errors stopped the upload.

  • matchedintegerrequired

    People whose variable pay was read.

  • unknownobject[]required
    2 fields
    • rowintegerrequired
    • emailstringrequired
  • outsideobject[]required

    People with no job in the entity that year.

    2 fields
    • rowintegerrequired
    • emailstringrequired
  • duplicatesobject[]required

    Further rows of a person already in the file: added to their first row.

    2 fields
    • rowintegerrequired
    • emailstringrequired
  • row_errorsobject[]required
    2 fields
    • rowintegerrequired
    • messagestringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_reports.upload_variable \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "report_id": "pr1",
  "csv": "work_email,bonus,allowances,in_kind\nana@acme.test,1500,0,0\n"
}'
Response
{
  "data": {
    "report": {
      "id": "pr1",
      "legal_entity": {
        "id": "e1",
        "name": "Acme Lda"
      },
      "year": 2025,
      "status": "draft",
      "headcount": 21,
      "duty": {
        "band": "under-50",
        "min": 0,
        "max": 49,
        "every_years": null,
        "first_due": null,
        "source": "pt-draft-2026-08",
        "source_label": "PT: Lei 60/2018 amendment (5 Aug 2026) (draft, not yet in force)",
        "enacted": false,
        "note": null,
        "due_by": null
      },
      "flagged": 1,
      "unjustified": 0,
      "assessment_due": 0,
      "inputs_count": 18,
      "created_at": "2026-02-01T10:00:00.000Z",
      "updated_at": "2026-02-03T10:00:00.000Z",
      "finalised_at": null,
      "submitted_on": null,
      "currency": "EUR",
      "population": 22,
      "excluded": {
        "no_pay": 1,
        "other_currency": 0
      },
      "uncategorised": 2,
      "finalised_by": null,
      "indicators": {
        "women": 9,
        "men": 11,
        "not_included": 1,
        "mean_gap": 6.2,
        "median_gap": 4.8,
        "annual_mean_gap": 9.1,
        "annual_median_gap": 7.5,
        "variable_mean_gap": 22.4,
        "variable_median_gap": null,
        "women_receiving_variable_pct": 33.3,
        "men_receiving_variable_pct": 45.5,
        "quartiles": [
          {
            "quartile": 1,
            "people": 5,
            "women": 3,
            "men": 2,
            "women_pct": 60,
            "men_pct": 40
          },
          {
            "quartile": 2,
            "people": 5,
            "women": 3,
            "men": 2,
            "women_pct": 60,
            "men_pct": 40
          },
          {
            "quartile": 3,
            "people": 5,
            "women": 2,
            "men": 3,
            "women_pct": 40,
            "men_pct": 60
          },
          {
            "quartile": 4,
            "people": 5,
            "women": 1,
            "men": 4,
            "women_pct": 20,
            "men_pct": 80
          }
        ],
        "components": [
          {
            "component": "bonus",
            "total": 48200,
            "women_receiving_pct": 41.7,
            "men_receiving_pct": 60,
            "mean_gap": 22.4,
            "median_gap": 18
          },
          {
            "component": "allowances",
            "total": 9600,
            "women_receiving_pct": 100,
            "men_receiving_pct": 100,
            "mean_gap": 1.2,
            "median_gap": 0
          },
          {
            "component": "in_kind",
            "total": 26400,
            "women_receiving_pct": 91.7,
            "men_receiving_pct": 90,
            "mean_gap": -2.5,
            "median_gap": 0
          }
        ]
      },
      "variable_sources": {
        "payroll": {
          "on": true,
          "items": [
            {
              "id": "it1",
              "name": "Annual bonus",
              "component": "bonus",
              "changed": false,
              "total": 48200,
              "people": 11
            },
            {
              "id": "it2",
              "name": "Salary advance",
              "component": "not_pay",
              "changed": false,
              "total": 3000,
              "people": 2
            }
          ],
          "not_in_money": 4,
          "other_currency": 0
        },
        "benefits": {
          "on": true,
          "in_kind": 26400,
          "allowances": 9600,
          "people": 22
        },
        "file": {
          "people": 0,
          "columns": []
        }
      },
      "categories": [
        {
          "id": "c1",
          "name": "Engineering",
          "women": 3,
          "men": 5,
          "not_included": 0,
          "base_mean_gap": 6.8,
          "base_median_gap": 5.1,
          "variable_mean_gap": 18,
          "variable_median_gap": 12.5,
          "total_mean_gap": 7.4,
          "total_median_gap": 5.9,
          "flagged": true,
          "small_group": false,
          "assessment_due": false,
          "justification": {
            "reason": "Two engineers joined in 2025 with ten or more years in the role.",
            "objective_factors": [
              "Years of relevant experience"
            ],
            "remedy": null,
            "remedy_by": null,
            "updated_by": "u1",
            "updated_at": "2026-02-03T10:00:00.000Z"
          }
        }
      ],
      "follow_up": {
        "remedy_window_ends": null,
        "assessment_within_days": 45,
        "authority": null
      }
    },
    "applied": true,
    "matched": 18,
    "unknown": [
      {
        "row": 7,
        "email": "old@acme.test"
      }
    ],
    "outside": [],
    "duplicates": [
      {
        "row": 12,
        "email": "ana@acme.test"
      }
    ],
    "row_errors": []
  }
}

Choose how pay items count in a report#

POST/v1/org/pay_reports.componentsWrite

For a draft report (report_id): how each Payroll pay item counts as variable pay (items: item id → bonus, allowances, not_pay for an advance or a reimbursement, or default to go back to Bizisy's choice from its name). Bizisy reads the year's pay items in money from Payroll and the company-funded benefits from Benefits by itself; this only changes the component. The report is recomputed. Owners, admins and HR, in the app only. Use dry_run to preview. Part of the Pay equity 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. How pay items count in a report is chosen in the app only.
MCP tool
org_pay_reports_components on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • report_idstringrequired
  • itemsobjectrequired

Returns

23 fields
  • idstringrequired
  • legal_entityobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • yearintegerrequired
  • status"draft" | "final"required
  • headcountintegerrequired
  • dutyobjectrequired

    By the legal entity's country and its average workers (Σ days employed ÷ days in the year). Countries without their own law in Bizisy follow the Directive's minimum (source eu-directive; a country may set lower thresholds): 250+ report every year from 7 June 2027, 150–249 every three years from 2027, 100–149 every three years from 7 June 2031, under 100 no duty. Countries with a law or draft of their own use it (source names it; enacted false = a draft not yet in force).

    10 fields
    • bandstringrequired

      e.g. "250+", "150-249", "under-100".

    • minintegerrequired
    • maxinteger | nullrequired
    • every_yearsinteger | nullrequired

      How often this band reports; null: no duty.

    • first_dueinteger | nullrequired

      The year the first report of this band is due (7 June).

    • sourcestringrequired
    • source_labelstringrequired

      The law the thresholds come from.

    • enactedbooleanrequired
    • notestring | nullrequired

      What else matters under that law (English), e.g. a different report period or who prepares the report.

    • due_bystring | nullrequired

      When a report on this year is due (7 June of the next year); null when this band reports no such year.

  • flaggedintegerrequired

    Categories with a mean gap of 5% or more.

  • unjustifiedintegerrequired

    Flagged categories with no justification yet.

  • assessment_dueintegerrequired
  • inputs_countintegerrequired
  • created_atstringrequired
  • updated_atstringrequired
  • finalised_atstring | nullrequired
  • submitted_onstring | nullrequired
  • currencystring | nullrequired
  • populationintegerrequired
  • excludedobjectrequired

    People in the population left out of the gaps: no pay recorded, or pay in another currency than the entity's main one.

    2 fields
    • no_payintegerrequired
    • other_currencyintegerrequired
  • indicatorsobjectrequired
    13 fields
    • womenintegerrequired
    • menintegerrequired
    • not_includedintegerrequired

      Included in pay but recorded as another, undisclosed or not recorded: counted, not compared.

    • mean_gapnumber | nullrequired

      Mean gender pay gap on gross hourly pay, % of the men's mean (Art. 9(1)(a)); negative: women are paid more. Null when either sex has nobody.

    • median_gapnumber | nullrequired

      Median gap on gross hourly pay (Art. 9(1)(c)).

    • annual_mean_gapnumber | nullrequired
    • annual_median_gapnumber | nullrequired
    • variable_mean_gapnumber | nullrequired

      Mean gap in variable components among all workers of each sex (Art. 9(1)(b)); null without variable pay.

    • variable_median_gapnumber | nullrequired
    • women_receiving_variable_pctnumber | nullrequired
    • men_receiving_variable_pctnumber | nullrequired
    • quartilesobject[]required

      Four groups by hourly pay, lowest first (Art. 9(1)(f)); n mod 4 extra people go to the first groups.

      6 fields
      • quartileintegerrequired
      • peopleintegerrequired
      • womenintegerrequired
      • menintegerrequired
      • women_pctnumber | nullrequired
      • men_pctnumber | nullrequired
    • componentsobject[]

      Reports only: each complementary or variable component (bonus, allowances, in kind) with its total, the share of women and men receiving it and its mean and median gap among all workers of each sex.

      6 fields
      • component"bonus" | "allowances" | "in_kind"required
      • totalnumberrequired
      • women_receiving_pctnumber | nullrequired
      • men_receiving_pctnumber | nullrequired
      • mean_gapnumber | nullrequired
      • median_gapnumber | nullrequired
  • categoriesobject[]required
    15 fields
    • idstringrequired
    • namestringrequired
    • womenintegerrequired
    • menintegerrequired
    • not_includedintegerrequired
    • base_mean_gapnumber | nullrequired
    • base_median_gapnumber | nullrequired
    • variable_mean_gapnumber | nullrequired
    • variable_median_gapnumber | nullrequired
    • total_mean_gapnumber | nullrequired
    • total_median_gapnumber | nullrequired
    • flaggedbooleanrequired

      |total_mean_gap| ≥ 5%: needs a justification by objective, gender-neutral factors or a remedy (Art. 10).

    • small_groupbooleanrequired

      Fewer than the company's minimum (min_group) of women or of men: the figures may reveal individual pay and say little; still flagged at the threshold, as the law sets it for every category.

    • assessment_duebooleanrequired

      Final report only: flagged and not justified by objective factors, or its remedy date has passed: a joint pay assessment with workers' representatives may be due.

    • justificationobject | nullrequired
      6 fields
      • reasonstringrequired
      • objective_factorsstring[]required
      • remedystring | nullrequired
      • remedy_bystring | nullrequired
      • updated_bystringrequired
      • updated_atstringrequired
  • uncategorisedintegerrequired

    Included people whose job title is in no pay category.

  • variable_sourcesobject | nullrequired

    Where the variable pay came from (totals only); null on reports made before it was read from Bizisy.

    4 fields
    • payrollobjectrequired
      4 fields
      • onbooleanrequired

        Payroll is on: its pay items in money count.

      • itemsobject[]required
        6 fields
        • idstringrequired
        • namestringrequired
        • component"bonus" | "allowances" | "not_pay"required
        • changedbooleanrequired

          HR changed it from the default.

        • totalnumber | nullrequired

          null when fewer than min_group people received it (it would show their pay).

        • peopleintegerrequired
      • not_in_moneyintegerrequired

        Earnings in hours or days: not counted (no amount).

      • other_currencyintegerrequired

        Amounts in another currency than the report's: not counted.

    • benefitsobjectrequired
      4 fields
      • onbooleanrequired
      • in_kindnumber | nullrequired
      • allowancesnumber | nullrequired

        Cash meal allowances. Both null when fewer than min_group people received benefits.

      • peopleintegerrequired
    • fileobjectrequired
      2 fields
      • peopleintegerrequired
      • columns"bonus" | "allowances" | "in_kind"[]required

        For these columns, the file's amount replaces Bizisy's for the people in it.

    • bonusesobject

      Bonus plans' awards paid by hand (awards paid through Payroll are its Bonus items).

      3 fields
      • onbooleanrequired
      • totalnumber | nullrequired

        null when fewer than min_group people received one.

      • peopleintegerrequired
  • finalised_bystring | nullrequired
  • follow_upobjectrequired
    3 fields
    • remedy_window_endsstring | nullrequired

      Six months after finalising (Art. 10(1)(c)): gaps not justified or remedied by then call for a joint pay assessment.

    • assessment_within_daysinteger | nullrequired

      Days to carry out a joint pay assessment once due, when the entity's national law sets it; null otherwise.

    • authoritystring | nullrequired

      Who receives the report, when national law names it; null otherwise.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_reports.components \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"report_id":"pr1","items":{"it2":"not_pay","it1":"default"}}'
Response
{
  "data": {
    "id": "pr1",
    "legal_entity": {
      "id": "e1",
      "name": "Acme Lda"
    },
    "year": 2025,
    "status": "draft",
    "headcount": 21,
    "duty": {
      "band": "under-50",
      "min": 0,
      "max": 49,
      "every_years": null,
      "first_due": null,
      "source": "pt-draft-2026-08",
      "source_label": "PT: Lei 60/2018 amendment (5 Aug 2026) (draft, not yet in force)",
      "enacted": false,
      "note": null,
      "due_by": null
    },
    "flagged": 1,
    "unjustified": 0,
    "assessment_due": 0,
    "inputs_count": 18,
    "created_at": "2026-02-01T10:00:00.000Z",
    "updated_at": "2026-02-03T10:00:00.000Z",
    "finalised_at": null,
    "submitted_on": null,
    "currency": "EUR",
    "population": 22,
    "excluded": {
      "no_pay": 1,
      "other_currency": 0
    },
    "uncategorised": 2,
    "finalised_by": null,
    "indicators": {
      "women": 9,
      "men": 11,
      "not_included": 1,
      "mean_gap": 6.2,
      "median_gap": 4.8,
      "annual_mean_gap": 9.1,
      "annual_median_gap": 7.5,
      "variable_mean_gap": 22.4,
      "variable_median_gap": null,
      "women_receiving_variable_pct": 33.3,
      "men_receiving_variable_pct": 45.5,
      "quartiles": [
        {
          "quartile": 1,
          "people": 5,
          "women": 3,
          "men": 2,
          "women_pct": 60,
          "men_pct": 40
        },
        {
          "quartile": 2,
          "people": 5,
          "women": 3,
          "men": 2,
          "women_pct": 60,
          "men_pct": 40
        },
        {
          "quartile": 3,
          "people": 5,
          "women": 2,
          "men": 3,
          "women_pct": 40,
          "men_pct": 60
        },
        {
          "quartile": 4,
          "people": 5,
          "women": 1,
          "men": 4,
          "women_pct": 20,
          "men_pct": 80
        }
      ],
      "components": [
        {
          "component": "bonus",
          "total": 48200,
          "women_receiving_pct": 41.7,
          "men_receiving_pct": 60,
          "mean_gap": 22.4,
          "median_gap": 18
        },
        {
          "component": "allowances",
          "total": 9600,
          "women_receiving_pct": 100,
          "men_receiving_pct": 100,
          "mean_gap": 1.2,
          "median_gap": 0
        },
        {
          "component": "in_kind",
          "total": 26400,
          "women_receiving_pct": 91.7,
          "men_receiving_pct": 90,
          "mean_gap": -2.5,
          "median_gap": 0
        }
      ]
    },
    "variable_sources": {
      "payroll": {
        "on": true,
        "items": [
          {
            "id": "it1",
            "name": "Annual bonus",
            "component": "bonus",
            "changed": false,
            "total": 48200,
            "people": 11
          },
          {
            "id": "it2",
            "name": "Salary advance",
            "component": "not_pay",
            "changed": false,
            "total": 3000,
            "people": 2
          }
        ],
        "not_in_money": 4,
        "other_currency": 0
      },
      "benefits": {
        "on": true,
        "in_kind": 26400,
        "allowances": 9600,
        "people": 22
      },
      "file": {
        "people": 0,
        "columns": []
      }
    },
    "categories": [
      {
        "id": "c1",
        "name": "Engineering",
        "women": 3,
        "men": 5,
        "not_included": 0,
        "base_mean_gap": 6.8,
        "base_median_gap": 5.1,
        "variable_mean_gap": 18,
        "variable_median_gap": 12.5,
        "total_mean_gap": 7.4,
        "total_median_gap": 5.9,
        "flagged": true,
        "small_group": false,
        "assessment_due": false,
        "justification": {
          "reason": "Two engineers joined in 2025 with ten or more years in the role.",
          "objective_factors": [
            "Years of relevant experience"
          ],
          "remedy": null,
          "remedy_by": null,
          "updated_by": "u1",
          "updated_at": "2026-02-03T10:00:00.000Z"
        }
      }
    ],
    "follow_up": {
      "remedy_window_ends": null,
      "assessment_within_days": 45,
      "authority": null
    }
  }
}

Justify a pay gap#

POST/v1/org/pay_reports.justifyWrite

Records why a category (category_id) of a report (report_id) has a mean pay gap of 5% or more (Art. 10): reason (10–2000 characters), objective_factors (up to 10 objective, gender-neutral factors that explain it, e.g. "seniority in the role"; none means it is not justified), remedy (what will be done, up to 2000) and remedy_by (YYYY-MM-DD, within six months of the report). Replaces the earlier justification. Works on drafts and final reports (the figures of a final report stay frozen). Categories under the threshold are refused. Owners, admins and HR, in the app only. Part of the Pay equity module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

Web app only
Refused for API keys and connected apps. Pay gaps are justified in the app only.
MCP tool
org_pay_reports_justify 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

  • report_idstringrequired
  • category_idstringrequired
  • reasonstringrequired

    10–2000 characters.

  • objective_factorsstring[]

    1–200 characters. Up to 10 items.

  • remedystring | null

    Up to 2000 characters.

  • remedy_bystring | null

Returns

23 fields
  • idstringrequired
  • legal_entityobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • yearintegerrequired
  • status"draft" | "final"required
  • headcountintegerrequired
  • dutyobjectrequired

    By the legal entity's country and its average workers (Σ days employed ÷ days in the year). Countries without their own law in Bizisy follow the Directive's minimum (source eu-directive; a country may set lower thresholds): 250+ report every year from 7 June 2027, 150–249 every three years from 2027, 100–149 every three years from 7 June 2031, under 100 no duty. Countries with a law or draft of their own use it (source names it; enacted false = a draft not yet in force).

    10 fields
    • bandstringrequired

      e.g. "250+", "150-249", "under-100".

    • minintegerrequired
    • maxinteger | nullrequired
    • every_yearsinteger | nullrequired

      How often this band reports; null: no duty.

    • first_dueinteger | nullrequired

      The year the first report of this band is due (7 June).

    • sourcestringrequired
    • source_labelstringrequired

      The law the thresholds come from.

    • enactedbooleanrequired
    • notestring | nullrequired

      What else matters under that law (English), e.g. a different report period or who prepares the report.

    • due_bystring | nullrequired

      When a report on this year is due (7 June of the next year); null when this band reports no such year.

  • flaggedintegerrequired

    Categories with a mean gap of 5% or more.

  • unjustifiedintegerrequired

    Flagged categories with no justification yet.

  • assessment_dueintegerrequired
  • inputs_countintegerrequired
  • created_atstringrequired
  • updated_atstringrequired
  • finalised_atstring | nullrequired
  • submitted_onstring | nullrequired
  • currencystring | nullrequired
  • populationintegerrequired
  • excludedobjectrequired

    People in the population left out of the gaps: no pay recorded, or pay in another currency than the entity's main one.

    2 fields
    • no_payintegerrequired
    • other_currencyintegerrequired
  • indicatorsobjectrequired
    13 fields
    • womenintegerrequired
    • menintegerrequired
    • not_includedintegerrequired

      Included in pay but recorded as another, undisclosed or not recorded: counted, not compared.

    • mean_gapnumber | nullrequired

      Mean gender pay gap on gross hourly pay, % of the men's mean (Art. 9(1)(a)); negative: women are paid more. Null when either sex has nobody.

    • median_gapnumber | nullrequired

      Median gap on gross hourly pay (Art. 9(1)(c)).

    • annual_mean_gapnumber | nullrequired
    • annual_median_gapnumber | nullrequired
    • variable_mean_gapnumber | nullrequired

      Mean gap in variable components among all workers of each sex (Art. 9(1)(b)); null without variable pay.

    • variable_median_gapnumber | nullrequired
    • women_receiving_variable_pctnumber | nullrequired
    • men_receiving_variable_pctnumber | nullrequired
    • quartilesobject[]required

      Four groups by hourly pay, lowest first (Art. 9(1)(f)); n mod 4 extra people go to the first groups.

      6 fields
      • quartileintegerrequired
      • peopleintegerrequired
      • womenintegerrequired
      • menintegerrequired
      • women_pctnumber | nullrequired
      • men_pctnumber | nullrequired
    • componentsobject[]

      Reports only: each complementary or variable component (bonus, allowances, in kind) with its total, the share of women and men receiving it and its mean and median gap among all workers of each sex.

      6 fields
      • component"bonus" | "allowances" | "in_kind"required
      • totalnumberrequired
      • women_receiving_pctnumber | nullrequired
      • men_receiving_pctnumber | nullrequired
      • mean_gapnumber | nullrequired
      • median_gapnumber | nullrequired
  • categoriesobject[]required
    15 fields
    • idstringrequired
    • namestringrequired
    • womenintegerrequired
    • menintegerrequired
    • not_includedintegerrequired
    • base_mean_gapnumber | nullrequired
    • base_median_gapnumber | nullrequired
    • variable_mean_gapnumber | nullrequired
    • variable_median_gapnumber | nullrequired
    • total_mean_gapnumber | nullrequired
    • total_median_gapnumber | nullrequired
    • flaggedbooleanrequired

      |total_mean_gap| ≥ 5%: needs a justification by objective, gender-neutral factors or a remedy (Art. 10).

    • small_groupbooleanrequired

      Fewer than the company's minimum (min_group) of women or of men: the figures may reveal individual pay and say little; still flagged at the threshold, as the law sets it for every category.

    • assessment_duebooleanrequired

      Final report only: flagged and not justified by objective factors, or its remedy date has passed: a joint pay assessment with workers' representatives may be due.

    • justificationobject | nullrequired
      6 fields
      • reasonstringrequired
      • objective_factorsstring[]required
      • remedystring | nullrequired
      • remedy_bystring | nullrequired
      • updated_bystringrequired
      • updated_atstringrequired
  • uncategorisedintegerrequired

    Included people whose job title is in no pay category.

  • variable_sourcesobject | nullrequired

    Where the variable pay came from (totals only); null on reports made before it was read from Bizisy.

    4 fields
    • payrollobjectrequired
      4 fields
      • onbooleanrequired

        Payroll is on: its pay items in money count.

      • itemsobject[]required
        6 fields
        • idstringrequired
        • namestringrequired
        • component"bonus" | "allowances" | "not_pay"required
        • changedbooleanrequired

          HR changed it from the default.

        • totalnumber | nullrequired

          null when fewer than min_group people received it (it would show their pay).

        • peopleintegerrequired
      • not_in_moneyintegerrequired

        Earnings in hours or days: not counted (no amount).

      • other_currencyintegerrequired

        Amounts in another currency than the report's: not counted.

    • benefitsobjectrequired
      4 fields
      • onbooleanrequired
      • in_kindnumber | nullrequired
      • allowancesnumber | nullrequired

        Cash meal allowances. Both null when fewer than min_group people received benefits.

      • peopleintegerrequired
    • fileobjectrequired
      2 fields
      • peopleintegerrequired
      • columns"bonus" | "allowances" | "in_kind"[]required

        For these columns, the file's amount replaces Bizisy's for the people in it.

    • bonusesobject

      Bonus plans' awards paid by hand (awards paid through Payroll are its Bonus items).

      3 fields
      • onbooleanrequired
      • totalnumber | nullrequired

        null when fewer than min_group people received one.

      • peopleintegerrequired
  • finalised_bystring | nullrequired
  • follow_upobjectrequired
    3 fields
    • remedy_window_endsstring | nullrequired

      Six months after finalising (Art. 10(1)(c)): gaps not justified or remedied by then call for a joint pay assessment.

    • assessment_within_daysinteger | nullrequired

      Days to carry out a joint pay assessment once due, when the entity's national law sets it; null otherwise.

    • authoritystring | nullrequired

      Who receives the report, when national law names it; null otherwise.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_reports.justify \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "report_id": "pr1",
  "category_id": "c1",
  "reason": "Two engineers joined with long experience.",
  "objective_factors": [
    "Years of relevant experience"
  ],
  "remedy": "Review in March.",
  "remedy_by": "2026-03-31"
}'
Response
{
  "data": {
    "id": "pr1",
    "legal_entity": {
      "id": "e1",
      "name": "Acme Lda"
    },
    "year": 2025,
    "status": "draft",
    "headcount": 21,
    "duty": {
      "band": "under-50",
      "min": 0,
      "max": 49,
      "every_years": null,
      "first_due": null,
      "source": "pt-draft-2026-08",
      "source_label": "PT: Lei 60/2018 amendment (5 Aug 2026) (draft, not yet in force)",
      "enacted": false,
      "note": null,
      "due_by": null
    },
    "flagged": 1,
    "unjustified": 0,
    "assessment_due": 0,
    "inputs_count": 18,
    "created_at": "2026-02-01T10:00:00.000Z",
    "updated_at": "2026-02-03T10:00:00.000Z",
    "finalised_at": null,
    "submitted_on": null,
    "currency": "EUR",
    "population": 22,
    "excluded": {
      "no_pay": 1,
      "other_currency": 0
    },
    "uncategorised": 2,
    "finalised_by": null,
    "indicators": {
      "women": 9,
      "men": 11,
      "not_included": 1,
      "mean_gap": 6.2,
      "median_gap": 4.8,
      "annual_mean_gap": 9.1,
      "annual_median_gap": 7.5,
      "variable_mean_gap": 22.4,
      "variable_median_gap": null,
      "women_receiving_variable_pct": 33.3,
      "men_receiving_variable_pct": 45.5,
      "quartiles": [
        {
          "quartile": 1,
          "people": 5,
          "women": 3,
          "men": 2,
          "women_pct": 60,
          "men_pct": 40
        },
        {
          "quartile": 2,
          "people": 5,
          "women": 3,
          "men": 2,
          "women_pct": 60,
          "men_pct": 40
        },
        {
          "quartile": 3,
          "people": 5,
          "women": 2,
          "men": 3,
          "women_pct": 40,
          "men_pct": 60
        },
        {
          "quartile": 4,
          "people": 5,
          "women": 1,
          "men": 4,
          "women_pct": 20,
          "men_pct": 80
        }
      ],
      "components": [
        {
          "component": "bonus",
          "total": 48200,
          "women_receiving_pct": 41.7,
          "men_receiving_pct": 60,
          "mean_gap": 22.4,
          "median_gap": 18
        },
        {
          "component": "allowances",
          "total": 9600,
          "women_receiving_pct": 100,
          "men_receiving_pct": 100,
          "mean_gap": 1.2,
          "median_gap": 0
        },
        {
          "component": "in_kind",
          "total": 26400,
          "women_receiving_pct": 91.7,
          "men_receiving_pct": 90,
          "mean_gap": -2.5,
          "median_gap": 0
        }
      ]
    },
    "variable_sources": {
      "payroll": {
        "on": true,
        "items": [
          {
            "id": "it1",
            "name": "Annual bonus",
            "component": "bonus",
            "changed": false,
            "total": 48200,
            "people": 11
          },
          {
            "id": "it2",
            "name": "Salary advance",
            "component": "not_pay",
            "changed": false,
            "total": 3000,
            "people": 2
          }
        ],
        "not_in_money": 4,
        "other_currency": 0
      },
      "benefits": {
        "on": true,
        "in_kind": 26400,
        "allowances": 9600,
        "people": 22
      },
      "file": {
        "people": 0,
        "columns": []
      }
    },
    "categories": [
      {
        "id": "c1",
        "name": "Engineering",
        "women": 3,
        "men": 5,
        "not_included": 0,
        "base_mean_gap": 6.8,
        "base_median_gap": 5.1,
        "variable_mean_gap": 18,
        "variable_median_gap": 12.5,
        "total_mean_gap": 7.4,
        "total_median_gap": 5.9,
        "flagged": true,
        "small_group": false,
        "assessment_due": false,
        "justification": {
          "reason": "Two engineers joined in 2025 with ten or more years in the role.",
          "objective_factors": [
            "Years of relevant experience"
          ],
          "remedy": null,
          "remedy_by": null,
          "updated_by": "u1",
          "updated_at": "2026-02-03T10:00:00.000Z"
        }
      }
    ],
    "follow_up": {
      "remedy_window_ends": null,
      "assessment_within_days": 45,
      "authority": null
    }
  }
}

Finalise a pay gap report#

POST/v1/org/pay_reports.finaliseWrite

Finalises a draft report (report_id): recomputes it one last time, freezes its figures and deletes the per-person variable pay (only totals stay). Refused while a category with a mean gap of 5% or more has no justification (the conflict names them), unless acknowledge_unjustified: true. Afterwards justifications and the submission date can still be recorded; a flagged category not justified by objective factors, or whose remedy date passes, shows on Home as a joint pay assessment that may be due. Sends the webhook pay_report.finalised (ids only). Owners, admins and HR, in the app only. Use dry_run first. Part of the Pay equity module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

Web app only
Refused for API keys and connected apps. Pay gap reports are finalised in the app only.
MCP tool
org_pay_reports_finalise on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • report_idstringrequired
  • acknowledge_unjustifiedboolean

    Default false.

Returns

23 fields
  • idstringrequired
  • legal_entityobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • yearintegerrequired
  • status"draft" | "final"required
  • headcountintegerrequired
  • dutyobjectrequired

    By the legal entity's country and its average workers (Σ days employed ÷ days in the year). Countries without their own law in Bizisy follow the Directive's minimum (source eu-directive; a country may set lower thresholds): 250+ report every year from 7 June 2027, 150–249 every three years from 2027, 100–149 every three years from 7 June 2031, under 100 no duty. Countries with a law or draft of their own use it (source names it; enacted false = a draft not yet in force).

    10 fields
    • bandstringrequired

      e.g. "250+", "150-249", "under-100".

    • minintegerrequired
    • maxinteger | nullrequired
    • every_yearsinteger | nullrequired

      How often this band reports; null: no duty.

    • first_dueinteger | nullrequired

      The year the first report of this band is due (7 June).

    • sourcestringrequired
    • source_labelstringrequired

      The law the thresholds come from.

    • enactedbooleanrequired
    • notestring | nullrequired

      What else matters under that law (English), e.g. a different report period or who prepares the report.

    • due_bystring | nullrequired

      When a report on this year is due (7 June of the next year); null when this band reports no such year.

  • flaggedintegerrequired

    Categories with a mean gap of 5% or more.

  • unjustifiedintegerrequired

    Flagged categories with no justification yet.

  • assessment_dueintegerrequired
  • inputs_countintegerrequired
  • created_atstringrequired
  • updated_atstringrequired
  • finalised_atstring | nullrequired
  • submitted_onstring | nullrequired
  • currencystring | nullrequired
  • populationintegerrequired
  • excludedobjectrequired

    People in the population left out of the gaps: no pay recorded, or pay in another currency than the entity's main one.

    2 fields
    • no_payintegerrequired
    • other_currencyintegerrequired
  • indicatorsobjectrequired
    13 fields
    • womenintegerrequired
    • menintegerrequired
    • not_includedintegerrequired

      Included in pay but recorded as another, undisclosed or not recorded: counted, not compared.

    • mean_gapnumber | nullrequired

      Mean gender pay gap on gross hourly pay, % of the men's mean (Art. 9(1)(a)); negative: women are paid more. Null when either sex has nobody.

    • median_gapnumber | nullrequired

      Median gap on gross hourly pay (Art. 9(1)(c)).

    • annual_mean_gapnumber | nullrequired
    • annual_median_gapnumber | nullrequired
    • variable_mean_gapnumber | nullrequired

      Mean gap in variable components among all workers of each sex (Art. 9(1)(b)); null without variable pay.

    • variable_median_gapnumber | nullrequired
    • women_receiving_variable_pctnumber | nullrequired
    • men_receiving_variable_pctnumber | nullrequired
    • quartilesobject[]required

      Four groups by hourly pay, lowest first (Art. 9(1)(f)); n mod 4 extra people go to the first groups.

      6 fields
      • quartileintegerrequired
      • peopleintegerrequired
      • womenintegerrequired
      • menintegerrequired
      • women_pctnumber | nullrequired
      • men_pctnumber | nullrequired
    • componentsobject[]

      Reports only: each complementary or variable component (bonus, allowances, in kind) with its total, the share of women and men receiving it and its mean and median gap among all workers of each sex.

      6 fields
      • component"bonus" | "allowances" | "in_kind"required
      • totalnumberrequired
      • women_receiving_pctnumber | nullrequired
      • men_receiving_pctnumber | nullrequired
      • mean_gapnumber | nullrequired
      • median_gapnumber | nullrequired
  • categoriesobject[]required
    15 fields
    • idstringrequired
    • namestringrequired
    • womenintegerrequired
    • menintegerrequired
    • not_includedintegerrequired
    • base_mean_gapnumber | nullrequired
    • base_median_gapnumber | nullrequired
    • variable_mean_gapnumber | nullrequired
    • variable_median_gapnumber | nullrequired
    • total_mean_gapnumber | nullrequired
    • total_median_gapnumber | nullrequired
    • flaggedbooleanrequired

      |total_mean_gap| ≥ 5%: needs a justification by objective, gender-neutral factors or a remedy (Art. 10).

    • small_groupbooleanrequired

      Fewer than the company's minimum (min_group) of women or of men: the figures may reveal individual pay and say little; still flagged at the threshold, as the law sets it for every category.

    • assessment_duebooleanrequired

      Final report only: flagged and not justified by objective factors, or its remedy date has passed: a joint pay assessment with workers' representatives may be due.

    • justificationobject | nullrequired
      6 fields
      • reasonstringrequired
      • objective_factorsstring[]required
      • remedystring | nullrequired
      • remedy_bystring | nullrequired
      • updated_bystringrequired
      • updated_atstringrequired
  • uncategorisedintegerrequired

    Included people whose job title is in no pay category.

  • variable_sourcesobject | nullrequired

    Where the variable pay came from (totals only); null on reports made before it was read from Bizisy.

    4 fields
    • payrollobjectrequired
      4 fields
      • onbooleanrequired

        Payroll is on: its pay items in money count.

      • itemsobject[]required
        6 fields
        • idstringrequired
        • namestringrequired
        • component"bonus" | "allowances" | "not_pay"required
        • changedbooleanrequired

          HR changed it from the default.

        • totalnumber | nullrequired

          null when fewer than min_group people received it (it would show their pay).

        • peopleintegerrequired
      • not_in_moneyintegerrequired

        Earnings in hours or days: not counted (no amount).

      • other_currencyintegerrequired

        Amounts in another currency than the report's: not counted.

    • benefitsobjectrequired
      4 fields
      • onbooleanrequired
      • in_kindnumber | nullrequired
      • allowancesnumber | nullrequired

        Cash meal allowances. Both null when fewer than min_group people received benefits.

      • peopleintegerrequired
    • fileobjectrequired
      2 fields
      • peopleintegerrequired
      • columns"bonus" | "allowances" | "in_kind"[]required

        For these columns, the file's amount replaces Bizisy's for the people in it.

    • bonusesobject

      Bonus plans' awards paid by hand (awards paid through Payroll are its Bonus items).

      3 fields
      • onbooleanrequired
      • totalnumber | nullrequired

        null when fewer than min_group people received one.

      • peopleintegerrequired
  • finalised_bystring | nullrequired
  • follow_upobjectrequired
    3 fields
    • remedy_window_endsstring | nullrequired

      Six months after finalising (Art. 10(1)(c)): gaps not justified or remedied by then call for a joint pay assessment.

    • assessment_within_daysinteger | nullrequired

      Days to carry out a joint pay assessment once due, when the entity's national law sets it; null otherwise.

    • authoritystring | nullrequired

      Who receives the report, when national law names it; null otherwise.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_reports.finalise \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"report_id":"pr1","acknowledge_unjustified":true}'
Response
{
  "data": {
    "id": "pr1",
    "legal_entity": {
      "id": "e1",
      "name": "Acme Lda"
    },
    "year": 2025,
    "status": "final",
    "headcount": 21,
    "duty": {
      "band": "under-50",
      "min": 0,
      "max": 49,
      "every_years": null,
      "first_due": null,
      "source": "pt-draft-2026-08",
      "source_label": "PT: Lei 60/2018 amendment (5 Aug 2026) (draft, not yet in force)",
      "enacted": false,
      "note": null,
      "due_by": null
    },
    "flagged": 1,
    "unjustified": 0,
    "assessment_due": 0,
    "inputs_count": 18,
    "created_at": "2026-02-01T10:00:00.000Z",
    "updated_at": "2026-02-03T10:00:00.000Z",
    "finalised_at": "2026-02-04T10:00:00.000Z",
    "submitted_on": null,
    "currency": "EUR",
    "population": 22,
    "excluded": {
      "no_pay": 1,
      "other_currency": 0
    },
    "uncategorised": 2,
    "finalised_by": "u1",
    "indicators": {
      "women": 9,
      "men": 11,
      "not_included": 1,
      "mean_gap": 6.2,
      "median_gap": 4.8,
      "annual_mean_gap": 9.1,
      "annual_median_gap": 7.5,
      "variable_mean_gap": 22.4,
      "variable_median_gap": null,
      "women_receiving_variable_pct": 33.3,
      "men_receiving_variable_pct": 45.5,
      "quartiles": [
        {
          "quartile": 1,
          "people": 5,
          "women": 3,
          "men": 2,
          "women_pct": 60,
          "men_pct": 40
        },
        {
          "quartile": 2,
          "people": 5,
          "women": 3,
          "men": 2,
          "women_pct": 60,
          "men_pct": 40
        },
        {
          "quartile": 3,
          "people": 5,
          "women": 2,
          "men": 3,
          "women_pct": 40,
          "men_pct": 60
        },
        {
          "quartile": 4,
          "people": 5,
          "women": 1,
          "men": 4,
          "women_pct": 20,
          "men_pct": 80
        }
      ],
      "components": [
        {
          "component": "bonus",
          "total": 48200,
          "women_receiving_pct": 41.7,
          "men_receiving_pct": 60,
          "mean_gap": 22.4,
          "median_gap": 18
        },
        {
          "component": "allowances",
          "total": 9600,
          "women_receiving_pct": 100,
          "men_receiving_pct": 100,
          "mean_gap": 1.2,
          "median_gap": 0
        },
        {
          "component": "in_kind",
          "total": 26400,
          "women_receiving_pct": 91.7,
          "men_receiving_pct": 90,
          "mean_gap": -2.5,
          "median_gap": 0
        }
      ]
    },
    "variable_sources": {
      "payroll": {
        "on": true,
        "items": [
          {
            "id": "it1",
            "name": "Annual bonus",
            "component": "bonus",
            "changed": false,
            "total": 48200,
            "people": 11
          },
          {
            "id": "it2",
            "name": "Salary advance",
            "component": "not_pay",
            "changed": false,
            "total": 3000,
            "people": 2
          }
        ],
        "not_in_money": 4,
        "other_currency": 0
      },
      "benefits": {
        "on": true,
        "in_kind": 26400,
        "allowances": 9600,
        "people": 22
      },
      "file": {
        "people": 0,
        "columns": []
      }
    },
    "categories": [
      {
        "id": "c1",
        "name": "Engineering",
        "women": 3,
        "men": 5,
        "not_included": 0,
        "base_mean_gap": 6.8,
        "base_median_gap": 5.1,
        "variable_mean_gap": 18,
        "variable_median_gap": 12.5,
        "total_mean_gap": 7.4,
        "total_median_gap": 5.9,
        "flagged": true,
        "small_group": false,
        "assessment_due": false,
        "justification": {
          "reason": "Two engineers joined in 2025 with ten or more years in the role.",
          "objective_factors": [
            "Years of relevant experience"
          ],
          "remedy": null,
          "remedy_by": null,
          "updated_by": "u1",
          "updated_at": "2026-02-03T10:00:00.000Z"
        }
      }
    ],
    "follow_up": {
      "remedy_window_ends": "2026-08-04",
      "assessment_within_days": 45,
      "authority": null
    }
  }
}

Record a pay gap report as submitted#

POST/v1/org/pay_reports.mark_submittedWrite

Records the day a final report (report_id) was submitted to the authority (on, YYYY-MM-DD, not in the future; null clears it). Bizisy does not submit it: send it to the body the entity's national law names (follow_up.authority when Bizisy knows it). Owners, admins and HR, in the app only. Part of the Pay equity 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. Submissions are recorded in the app only.
MCP tool
org_pay_reports_mark_submitted on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • report_idstringrequired
  • onstring | nullrequired

Returns

23 fields
  • idstringrequired
  • legal_entityobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • yearintegerrequired
  • status"draft" | "final"required
  • headcountintegerrequired
  • dutyobjectrequired

    By the legal entity's country and its average workers (Σ days employed ÷ days in the year). Countries without their own law in Bizisy follow the Directive's minimum (source eu-directive; a country may set lower thresholds): 250+ report every year from 7 June 2027, 150–249 every three years from 2027, 100–149 every three years from 7 June 2031, under 100 no duty. Countries with a law or draft of their own use it (source names it; enacted false = a draft not yet in force).

    10 fields
    • bandstringrequired

      e.g. "250+", "150-249", "under-100".

    • minintegerrequired
    • maxinteger | nullrequired
    • every_yearsinteger | nullrequired

      How often this band reports; null: no duty.

    • first_dueinteger | nullrequired

      The year the first report of this band is due (7 June).

    • sourcestringrequired
    • source_labelstringrequired

      The law the thresholds come from.

    • enactedbooleanrequired
    • notestring | nullrequired

      What else matters under that law (English), e.g. a different report period or who prepares the report.

    • due_bystring | nullrequired

      When a report on this year is due (7 June of the next year); null when this band reports no such year.

  • flaggedintegerrequired

    Categories with a mean gap of 5% or more.

  • unjustifiedintegerrequired

    Flagged categories with no justification yet.

  • assessment_dueintegerrequired
  • inputs_countintegerrequired
  • created_atstringrequired
  • updated_atstringrequired
  • finalised_atstring | nullrequired
  • submitted_onstring | nullrequired
  • currencystring | nullrequired
  • populationintegerrequired
  • excludedobjectrequired

    People in the population left out of the gaps: no pay recorded, or pay in another currency than the entity's main one.

    2 fields
    • no_payintegerrequired
    • other_currencyintegerrequired
  • indicatorsobjectrequired
    13 fields
    • womenintegerrequired
    • menintegerrequired
    • not_includedintegerrequired

      Included in pay but recorded as another, undisclosed or not recorded: counted, not compared.

    • mean_gapnumber | nullrequired

      Mean gender pay gap on gross hourly pay, % of the men's mean (Art. 9(1)(a)); negative: women are paid more. Null when either sex has nobody.

    • median_gapnumber | nullrequired

      Median gap on gross hourly pay (Art. 9(1)(c)).

    • annual_mean_gapnumber | nullrequired
    • annual_median_gapnumber | nullrequired
    • variable_mean_gapnumber | nullrequired

      Mean gap in variable components among all workers of each sex (Art. 9(1)(b)); null without variable pay.

    • variable_median_gapnumber | nullrequired
    • women_receiving_variable_pctnumber | nullrequired
    • men_receiving_variable_pctnumber | nullrequired
    • quartilesobject[]required

      Four groups by hourly pay, lowest first (Art. 9(1)(f)); n mod 4 extra people go to the first groups.

      6 fields
      • quartileintegerrequired
      • peopleintegerrequired
      • womenintegerrequired
      • menintegerrequired
      • women_pctnumber | nullrequired
      • men_pctnumber | nullrequired
    • componentsobject[]

      Reports only: each complementary or variable component (bonus, allowances, in kind) with its total, the share of women and men receiving it and its mean and median gap among all workers of each sex.

      6 fields
      • component"bonus" | "allowances" | "in_kind"required
      • totalnumberrequired
      • women_receiving_pctnumber | nullrequired
      • men_receiving_pctnumber | nullrequired
      • mean_gapnumber | nullrequired
      • median_gapnumber | nullrequired
  • categoriesobject[]required
    15 fields
    • idstringrequired
    • namestringrequired
    • womenintegerrequired
    • menintegerrequired
    • not_includedintegerrequired
    • base_mean_gapnumber | nullrequired
    • base_median_gapnumber | nullrequired
    • variable_mean_gapnumber | nullrequired
    • variable_median_gapnumber | nullrequired
    • total_mean_gapnumber | nullrequired
    • total_median_gapnumber | nullrequired
    • flaggedbooleanrequired

      |total_mean_gap| ≥ 5%: needs a justification by objective, gender-neutral factors or a remedy (Art. 10).

    • small_groupbooleanrequired

      Fewer than the company's minimum (min_group) of women or of men: the figures may reveal individual pay and say little; still flagged at the threshold, as the law sets it for every category.

    • assessment_duebooleanrequired

      Final report only: flagged and not justified by objective factors, or its remedy date has passed: a joint pay assessment with workers' representatives may be due.

    • justificationobject | nullrequired
      6 fields
      • reasonstringrequired
      • objective_factorsstring[]required
      • remedystring | nullrequired
      • remedy_bystring | nullrequired
      • updated_bystringrequired
      • updated_atstringrequired
  • uncategorisedintegerrequired

    Included people whose job title is in no pay category.

  • variable_sourcesobject | nullrequired

    Where the variable pay came from (totals only); null on reports made before it was read from Bizisy.

    4 fields
    • payrollobjectrequired
      4 fields
      • onbooleanrequired

        Payroll is on: its pay items in money count.

      • itemsobject[]required
        6 fields
        • idstringrequired
        • namestringrequired
        • component"bonus" | "allowances" | "not_pay"required
        • changedbooleanrequired

          HR changed it from the default.

        • totalnumber | nullrequired

          null when fewer than min_group people received it (it would show their pay).

        • peopleintegerrequired
      • not_in_moneyintegerrequired

        Earnings in hours or days: not counted (no amount).

      • other_currencyintegerrequired

        Amounts in another currency than the report's: not counted.

    • benefitsobjectrequired
      4 fields
      • onbooleanrequired
      • in_kindnumber | nullrequired
      • allowancesnumber | nullrequired

        Cash meal allowances. Both null when fewer than min_group people received benefits.

      • peopleintegerrequired
    • fileobjectrequired
      2 fields
      • peopleintegerrequired
      • columns"bonus" | "allowances" | "in_kind"[]required

        For these columns, the file's amount replaces Bizisy's for the people in it.

    • bonusesobject

      Bonus plans' awards paid by hand (awards paid through Payroll are its Bonus items).

      3 fields
      • onbooleanrequired
      • totalnumber | nullrequired

        null when fewer than min_group people received one.

      • peopleintegerrequired
  • finalised_bystring | nullrequired
  • follow_upobjectrequired
    3 fields
    • remedy_window_endsstring | nullrequired

      Six months after finalising (Art. 10(1)(c)): gaps not justified or remedied by then call for a joint pay assessment.

    • assessment_within_daysinteger | nullrequired

      Days to carry out a joint pay assessment once due, when the entity's national law sets it; null otherwise.

    • authoritystring | nullrequired

      Who receives the report, when national law names it; null otherwise.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_reports.mark_submitted \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"report_id":"pr1","on":"2026-03-01"}'
Response
{
  "data": {
    "id": "pr1",
    "legal_entity": {
      "id": "e1",
      "name": "Acme Lda"
    },
    "year": 2025,
    "status": "final",
    "headcount": 21,
    "duty": {
      "band": "under-50",
      "min": 0,
      "max": 49,
      "every_years": null,
      "first_due": null,
      "source": "pt-draft-2026-08",
      "source_label": "PT: Lei 60/2018 amendment (5 Aug 2026) (draft, not yet in force)",
      "enacted": false,
      "note": null,
      "due_by": null
    },
    "flagged": 1,
    "unjustified": 0,
    "assessment_due": 0,
    "inputs_count": 18,
    "created_at": "2026-02-01T10:00:00.000Z",
    "updated_at": "2026-02-03T10:00:00.000Z",
    "finalised_at": "2026-02-04T10:00:00.000Z",
    "submitted_on": "2026-03-01",
    "currency": "EUR",
    "population": 22,
    "excluded": {
      "no_pay": 1,
      "other_currency": 0
    },
    "uncategorised": 2,
    "finalised_by": "u1",
    "indicators": {
      "women": 9,
      "men": 11,
      "not_included": 1,
      "mean_gap": 6.2,
      "median_gap": 4.8,
      "annual_mean_gap": 9.1,
      "annual_median_gap": 7.5,
      "variable_mean_gap": 22.4,
      "variable_median_gap": null,
      "women_receiving_variable_pct": 33.3,
      "men_receiving_variable_pct": 45.5,
      "quartiles": [
        {
          "quartile": 1,
          "people": 5,
          "women": 3,
          "men": 2,
          "women_pct": 60,
          "men_pct": 40
        },
        {
          "quartile": 2,
          "people": 5,
          "women": 3,
          "men": 2,
          "women_pct": 60,
          "men_pct": 40
        },
        {
          "quartile": 3,
          "people": 5,
          "women": 2,
          "men": 3,
          "women_pct": 40,
          "men_pct": 60
        },
        {
          "quartile": 4,
          "people": 5,
          "women": 1,
          "men": 4,
          "women_pct": 20,
          "men_pct": 80
        }
      ],
      "components": [
        {
          "component": "bonus",
          "total": 48200,
          "women_receiving_pct": 41.7,
          "men_receiving_pct": 60,
          "mean_gap": 22.4,
          "median_gap": 18
        },
        {
          "component": "allowances",
          "total": 9600,
          "women_receiving_pct": 100,
          "men_receiving_pct": 100,
          "mean_gap": 1.2,
          "median_gap": 0
        },
        {
          "component": "in_kind",
          "total": 26400,
          "women_receiving_pct": 91.7,
          "men_receiving_pct": 90,
          "mean_gap": -2.5,
          "median_gap": 0
        }
      ]
    },
    "variable_sources": {
      "payroll": {
        "on": true,
        "items": [
          {
            "id": "it1",
            "name": "Annual bonus",
            "component": "bonus",
            "changed": false,
            "total": 48200,
            "people": 11
          },
          {
            "id": "it2",
            "name": "Salary advance",
            "component": "not_pay",
            "changed": false,
            "total": 3000,
            "people": 2
          }
        ],
        "not_in_money": 4,
        "other_currency": 0
      },
      "benefits": {
        "on": true,
        "in_kind": 26400,
        "allowances": 9600,
        "people": 22
      },
      "file": {
        "people": 0,
        "columns": []
      }
    },
    "categories": [
      {
        "id": "c1",
        "name": "Engineering",
        "women": 3,
        "men": 5,
        "not_included": 0,
        "base_mean_gap": 6.8,
        "base_median_gap": 5.1,
        "variable_mean_gap": 18,
        "variable_median_gap": 12.5,
        "total_mean_gap": 7.4,
        "total_median_gap": 5.9,
        "flagged": true,
        "small_group": false,
        "assessment_due": false,
        "justification": {
          "reason": "Two engineers joined in 2025 with ten or more years in the role.",
          "objective_factors": [
            "Years of relevant experience"
          ],
          "remedy": null,
          "remedy_by": null,
          "updated_by": "u1",
          "updated_at": "2026-02-03T10:00:00.000Z"
        }
      }
    ],
    "follow_up": {
      "remedy_window_ends": "2026-08-04",
      "assessment_within_days": 45,
      "authority": null
    }
  }
}

Delete a draft pay gap report#

POST/v1/org/pay_reports.removeDestructive

Deletes a draft report (report_id) and the variable pay uploaded for it. Final reports are kept (refused). Owners, admins and HR, in the app only. Part of the Pay equity module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

Web app only
Refused for API keys and connected apps. Pay gap reports are deleted in the app only.
MCP tool
org_pay_reports_remove on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • report_idstringrequired

Returns

  • idstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_reports.remove \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"report_id":"pr1"}'
Response
{
  "data": {
    "id": "pr1"
  }
}

Export a pay gap report#

POST/v1/org/pay_reports.exportRead

A report (report_id) as a CSV file (format csv; delimiter "," or ";"): the indicators, one line each, then the categories with their gaps and justifications. Totals only, never per-person pay. The print-ready page renders from org_pay_reports_get. Owners, admins and HR, in the app only. Part of the Pay equity module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

Web app only
Refused for API keys and connected apps. Pay gap reports are exported in the app only.
MCP tool
org_pay_reports_export on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • report_idstringrequired
  • format"csv"

    Default "csv".

  • delimiter"," | ";"

    Default ",".

Returns

  • filenamestringrequired
  • csvstringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_reports.export \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"report_id":"pr1","format":"csv","delimiter":";"}'
Response
{
  "data": {
    "filename": "pay-gap-report-acme-lda-2025.csv",
    "csv": "indicator,value\r\nyear,2025\r\n"
  }
}

List pay requests#

POST/v1/org/pay_requests.listRead

People's requests about pay levels (EU Pay Transparency Directive Art. 7), open ones first by due date, then the rest newest first: who asked, when, the answer given at once or why it was withheld (small_group, no_category, no_pay), HR's reply, and whether it is overdue (the answer is due within two months). status filters: open (default), answered or all. Owners, admins and HR, in the app only (pay data: never over an API key or MCP). Managers are never told. Part of the Pay equity 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. People's pay requests are pay data: read in the app only.
MCP tool
org_pay_requests_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • status"open" | "answered" | "all"

    Default "open".

Returns

  • itemsobject[]required
    13 fields
    • idstringrequired
    • created_atstringrequired
    • due_onstringrequired

      The answer is due by this day (two months after the request).

    • status"answered" | "open"required

      answered: the averages were given at once, or HR replied in writing; open: HR still has to reply.

    • answerobjectrequired
      6 fields
      • as_ofstringrequired
      • categoryobject | nullrequired

        Your category of workers: people doing the same work or work of equal value.

        2 fields
        • idstringrequired
        • namestringrequired
      • ownobject | nullrequired

        Your pay level that day: your gross pay in force, annualised (year: as is; month: × 12; hour: × your hours in a year), and per hour (your weekly hours, else FTE × the standard week). Null without pay recorded.

        3 fields
        • annualnumberrequired
        • hourlynumberrequired
        • currencystringrequired
      • womenobject | nullrequired

        Women in your category that day, not counting you, paid in your currency. Null when withheld.

        3 fields
        • countintegerrequired
        • annual_meannumberrequired

          Average gross annual pay (pay in force that day, annualised).

        • hourly_meannumberrequired

          Average gross hourly pay.

      • menobject | nullrequired
        3 fields
        • countintegerrequired
        • annual_meannumberrequired

          Average gross annual pay (pay in force that day, annualised).

        • hourly_meannumberrequired

          Average gross hourly pay.

      • withheld"small_group" | "recent_change" | "category_review" | "no_category" | "no_pay"required

        Why the averages were not given at once, so HR answers in writing within two months: small_group (fewer than the company's minimum of women or of men in your category, not counting you: averages could reveal a colleague's pay), recent_change (since your last answer, fewer than that minimum of people joined or left your category: comparing the two answers could reveal their pay), category_review (a job evaluation of your category is being changed, so HR confirms the category first), no_category (your job is in no pay category yet), no_pay (no pay recorded for you). Null: answered.

    • hr_replystring | nullrequired

      HR's written answer.

    • answered_atstring | nullrequired
    • personobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • overduebooleanrequired

      Open past its due date.

    • receivedstring | nullrequired

      Recorded by HR for a request received outside Bizisy: how it came (null: asked in Bizisy or no note).

    • recordedbooleanrequired

      Recorded by HR (org_pay_requests_record) rather than asked by the person in Bizisy.

    • asked_12mintegerrequired

      How many requests this person made in the last 12 months.

    • frequentbooleanrequired

      More than 4 requests in 12 months: never refused (Art. 7 sets no limit); when nothing changed, a written reply may refer to the earlier answer.

  • openintegerrequired
  • overdueintegerrequired
  • totalintegerrequired

    Requests matching status; items holds every open one and at most 200 answered ones (newest).

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_requests.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"all"}'
Response
{
  "data": {
    "items": [
      {
        "id": "rq2",
        "created_at": "2026-10-04T10:00:00.000Z",
        "due_on": "2026-12-04",
        "status": "open",
        "answer": {
          "as_of": "2026-10-04",
          "category": {
            "id": "c2",
            "name": "Design"
          },
          "own": {
            "annual": 30000,
            "hourly": 14.38,
            "currency": "EUR"
          },
          "women": null,
          "men": null,
          "withheld": "small_group"
        },
        "hr_reply": null,
        "answered_at": null,
        "person": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "overdue": false,
        "received": null,
        "recorded": false,
        "asked_12m": 1,
        "frequent": false
      }
    ],
    "open": 1,
    "overdue": 0,
    "total": 1
  }
}

Answer a pay request#

POST/v1/org/pay_requests.replyWrite

Answers a request about pay levels in writing (id from org_pay_requests_list; text 10–5000 characters): the person reads it in Me → Pay and gets an in-app notice that it was answered (never the text in the notice, no email). Use it for open requests (the averages were withheld: give what you can without revealing an identifiable colleague's pay, e.g. explain the category has too few people to share averages and offer the averages to workers' representatives or the labour inspectorate, Art. 12(3)), or to add to an answered one (the latest reply replaces the earlier). The request becomes answered. Owners, admins and HR, in the app only (never over an API key or MCP). Part of the Pay equity module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

Web app only
Refused for API keys and connected apps. Pay requests are answered in the app only.
MCP tool
org_pay_requests_reply 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

  • idstringrequired
  • textstringrequired

    10–5000 characters.

Returns

13 fields
  • idstringrequired
  • created_atstringrequired
  • due_onstringrequired

    The answer is due by this day (two months after the request).

  • status"answered" | "open"required

    answered: the averages were given at once, or HR replied in writing; open: HR still has to reply.

  • answerobjectrequired
    6 fields
    • as_ofstringrequired
    • categoryobject | nullrequired

      Your category of workers: people doing the same work or work of equal value.

      2 fields
      • idstringrequired
      • namestringrequired
    • ownobject | nullrequired

      Your pay level that day: your gross pay in force, annualised (year: as is; month: × 12; hour: × your hours in a year), and per hour (your weekly hours, else FTE × the standard week). Null without pay recorded.

      3 fields
      • annualnumberrequired
      • hourlynumberrequired
      • currencystringrequired
    • womenobject | nullrequired

      Women in your category that day, not counting you, paid in your currency. Null when withheld.

      3 fields
      • countintegerrequired
      • annual_meannumberrequired

        Average gross annual pay (pay in force that day, annualised).

      • hourly_meannumberrequired

        Average gross hourly pay.

    • menobject | nullrequired
      3 fields
      • countintegerrequired
      • annual_meannumberrequired

        Average gross annual pay (pay in force that day, annualised).

      • hourly_meannumberrequired

        Average gross hourly pay.

    • withheld"small_group" | "recent_change" | "category_review" | "no_category" | "no_pay"required

      Why the averages were not given at once, so HR answers in writing within two months: small_group (fewer than the company's minimum of women or of men in your category, not counting you: averages could reveal a colleague's pay), recent_change (since your last answer, fewer than that minimum of people joined or left your category: comparing the two answers could reveal their pay), category_review (a job evaluation of your category is being changed, so HR confirms the category first), no_category (your job is in no pay category yet), no_pay (no pay recorded for you). Null: answered.

  • hr_replystring | nullrequired

    HR's written answer.

  • answered_atstring | nullrequired
  • personobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • overduebooleanrequired

    Open past its due date.

  • receivedstring | nullrequired

    Recorded by HR for a request received outside Bizisy: how it came (null: asked in Bizisy or no note).

  • recordedbooleanrequired

    Recorded by HR (org_pay_requests_record) rather than asked by the person in Bizisy.

  • asked_12mintegerrequired

    How many requests this person made in the last 12 months.

  • frequentbooleanrequired

    More than 4 requests in 12 months: never refused (Art. 7 sets no limit); when nothing changed, a written reply may refer to the earlier answer.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_requests.reply \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "id": "rq2",
  "text": "Your category has too few people to share averages without revealing a colleague'\''s pay."
}'
Response
{
  "data": {
    "id": "rq2",
    "created_at": "2026-10-04T10:00:00.000Z",
    "due_on": "2026-12-04",
    "status": "answered",
    "answer": {
      "as_of": "2026-10-04",
      "category": {
        "id": "c2",
        "name": "Design"
      },
      "own": {
        "annual": 30000,
        "hourly": 14.38,
        "currency": "EUR"
      },
      "women": null,
      "men": null,
      "withheld": "small_group"
    },
    "hr_reply": "Your category has too few people to share averages without revealing a colleague's pay.",
    "answered_at": "2026-10-05T10:00:00.000Z",
    "person": {
      "id": "p2",
      "name": "Rui Costa",
      "title": "CTO",
      "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
    },
    "overdue": false,
    "received": null,
    "recorded": false,
    "asked_12m": 1,
    "frequent": false
  }
}

Record a pay request received on paper#

POST/v1/org/pay_requests.recordWrite

Records a request about pay levels (EU Pay Transparency Directive Art. 7) that a person made outside Bizisy, e.g. a letter or an email to HR, typically someone without a Bizisy login: person_id, received_on (YYYY-MM-DD, the day it was received: not in the future, within the last 12 months, while they worked here) and an optional note on how it came (up to 200 characters). Bizisy works out the same answer as when the person asks in Me, on the pay in force that day: their pay level and the average pay levels of women and men in their category, or why the averages are withheld (then answer in writing with org_pay_requests_reply). Hand the answer over in writing (Pay equity → Requests prints it); it is due two months after receipt, or sooner where the person's country's law says so (due_on). It is never refused for how many requests the person made (Art. 7 sets no limit) and the same differencing rule applies; the person sees it in Me → Pay when they have a login. Owners, admins and HR, in the app only (never over an API key or MCP). A dry run shows the answer without recording it. Part of the Pay equity 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. Requests received on paper are recorded in the app only.
MCP tool
org_pay_requests_record 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

  • person_idstringrequired
  • received_onstringrequired
  • notestring | null

    Up to 200 characters.

Returns

13 fields
  • idstringrequired
  • created_atstringrequired
  • due_onstringrequired

    The answer is due by this day (two months after the request).

  • status"answered" | "open"required

    answered: the averages were given at once, or HR replied in writing; open: HR still has to reply.

  • answerobjectrequired
    6 fields
    • as_ofstringrequired
    • categoryobject | nullrequired

      Your category of workers: people doing the same work or work of equal value.

      2 fields
      • idstringrequired
      • namestringrequired
    • ownobject | nullrequired

      Your pay level that day: your gross pay in force, annualised (year: as is; month: × 12; hour: × your hours in a year), and per hour (your weekly hours, else FTE × the standard week). Null without pay recorded.

      3 fields
      • annualnumberrequired
      • hourlynumberrequired
      • currencystringrequired
    • womenobject | nullrequired

      Women in your category that day, not counting you, paid in your currency. Null when withheld.

      3 fields
      • countintegerrequired
      • annual_meannumberrequired

        Average gross annual pay (pay in force that day, annualised).

      • hourly_meannumberrequired

        Average gross hourly pay.

    • menobject | nullrequired
      3 fields
      • countintegerrequired
      • annual_meannumberrequired

        Average gross annual pay (pay in force that day, annualised).

      • hourly_meannumberrequired

        Average gross hourly pay.

    • withheld"small_group" | "recent_change" | "category_review" | "no_category" | "no_pay"required

      Why the averages were not given at once, so HR answers in writing within two months: small_group (fewer than the company's minimum of women or of men in your category, not counting you: averages could reveal a colleague's pay), recent_change (since your last answer, fewer than that minimum of people joined or left your category: comparing the two answers could reveal their pay), category_review (a job evaluation of your category is being changed, so HR confirms the category first), no_category (your job is in no pay category yet), no_pay (no pay recorded for you). Null: answered.

  • hr_replystring | nullrequired

    HR's written answer.

  • answered_atstring | nullrequired
  • personobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • overduebooleanrequired

    Open past its due date.

  • receivedstring | nullrequired

    Recorded by HR for a request received outside Bizisy: how it came (null: asked in Bizisy or no note).

  • recordedbooleanrequired

    Recorded by HR (org_pay_requests_record) rather than asked by the person in Bizisy.

  • asked_12mintegerrequired

    How many requests this person made in the last 12 months.

  • frequentbooleanrequired

    More than 4 requests in 12 months: never refused (Art. 7 sets no limit); when nothing changed, a written reply may refer to the earlier answer.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_requests.record \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "person_id": "p1",
  "received_on": "2026-10-01",
  "note": "Letter handed to HR"
}'
Response
{
  "data": {
    "id": "rq2",
    "created_at": "2026-10-04T10:00:00.000Z",
    "due_on": "2026-12-04",
    "status": "open",
    "answer": {
      "as_of": "2026-10-04",
      "category": {
        "id": "c2",
        "name": "Design"
      },
      "own": {
        "annual": 30000,
        "hourly": 14.38,
        "currency": "EUR"
      },
      "women": null,
      "men": null,
      "withheld": "small_group"
    },
    "hr_reply": null,
    "answered_at": null,
    "person": {
      "id": "p2",
      "name": "Rui Costa",
      "title": "CTO",
      "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
    },
    "overdue": false,
    "received": "Letter handed to HR",
    "recorded": true,
    "asked_12m": 1,
    "frequent": false
  }
}

Pay rights reminder status#

POST/v1/org/pay_equity.reminder_statusRead

This year's reminder that people can ask about pay levels (EU Pay Transparency Directive Art. 7(3): every worker, every year): the reminder month (Pay equity → Settings), whether it started (the month came and the company has a pay category), how many people employed today were reminded in the app and by email, and the people employed today with no Bizisy login (count and ids): Bizisy cannot reach them, so tell them another way (Pay equity → Requests prints a notice to post or hand out). Owners, admins and HR, in the app only. Part of the Pay equity 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. Who was reminded of the right to ask about pay is read in the app only.
MCP tool
org_pay_equity_reminder_status on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

8 fields
  • yearintegerrequired
  • monthintegerrequired

    The reminder month, 1–12.

  • startedbooleanrequired
  • set_upbooleanrequired

    At least one pay category exists (no reminder before: nothing could be answered).

  • employedintegerrequired
  • remindedintegerrequired
  • emailedintegerrequired
  • without_loginobjectrequired
    2 fields
    • countintegerrequired
    • idsstring[]required

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/pay_equity.reminder_status \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "year": 2026,
    "month": 1,
    "started": true,
    "set_up": true,
    "employed": 22,
    "reminded": 19,
    "emailed": 19,
    "without_login": {
      "count": 3,
      "ids": [
        "p7",
        "p8",
        "p9"
      ]
    }
  }
}

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

Developer docs