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_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
itemsobject[]required11 fields
idstringrequiredtargetobjectrequired5 fields
kind"title" | "level"requiredtitle_idstring | nullrequiredfamily_idstring | nullrequiredlevel_idstring | nullrequirednamestringrequiredThe title's name, or "Family · Level".
valid_fromstringrequiredvalid_tostring | nullrequiredWhen the next row for the same target starts (exclusive); null = open-ended.
in_forcebooleanrequiredThe row that applies today for its target.
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requirednotestring | nullrequiredpeopleobject | nullrequiredPeople whose band today is this row, by where their pay sits (null for rows not in force).
4 fields
belowintegerrequiredinintegerrequiredaboveintegerrequirednot_comparedintegerrequiredPay in another currency or period, or no pay recorded.
limitintegerrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/pay_bands.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/pay_bands.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_bands.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"items": [
{
"id": "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_seton HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
targetobjectrequired5 fields (one of several shapes)
Option 1
kind"title"requiredtitle_idstringrequired
Option 2
kind"level"requiredfamily_idstringrequiredlevel_idstringrequired
valid_fromstringminnumberrequiredFrom 0 to 100000000.
maxnumberrequiredFrom 0 to 100000000.
currencyanyrequiredperiod"year" | "month" | "hour"requirednotestring | nullUp to 200 characters.
Returns
bandobjectrequired11 fields
idstringrequiredtargetobjectrequired5 fields
kind"title" | "level"requiredtitle_idstring | nullrequiredfamily_idstring | nullrequiredlevel_idstring | nullrequirednamestringrequiredThe title's name, or "Family · Level".
valid_fromstringrequiredvalid_tostring | nullrequiredWhen the next row for the same target starts (exclusive); null = open-ended.
in_forcebooleanrequiredThe row that applies today for its target.
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requirednotestring | nullrequiredpeopleobject | nullrequiredPeople whose band today is this row, by where their pay sits (null for rows not in force).
4 fields
belowintegerrequiredinintegerrequiredaboveintegerrequirednot_comparedintegerrequiredPay in another currency or period, or no pay recorded.
createdbooleanrequiredpreviewobjectrequired5 fields
belowintegerrequiredinintegerrequiredaboveintegerrequirednot_comparedintegerrequiredPay in another currency or period, or no pay recorded.
summarystringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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"
}'const res = await fetch('https://api.bizisy.com/v1/org/pay_bands.set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"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"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_bands.set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"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",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_removeon HR Assistant- Preview
?dry_run=trueruns 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 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"}'const res = await fetch('https://api.bizisy.com/v1/org/pay_bands.remove', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"band_id": "b1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_bands.remove",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"band_id": "b1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_positionon HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
person_idstringrequiredas_ofstringtitle_idstringproposedobject3 fields
amountnumberrequiredFrom 0 to 100000000.
currencyanyrequiredperiod"year" | "month" | "hour"required
Returns
8 fields
person_idstringrequiredas_ofstringrequiredbandobject | nullrequired8 fields
idstringrequiredtargetobjectrequired5 fields
kind"title" | "level"requiredtitle_idstring | nullrequiredfamily_idstring | nullrequiredlevel_idstring | nullrequirednamestringrequiredThe title's name, or "Family · Level".
valid_fromstringrequiredminnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredsource"title" | "level"required"title": the title's own band; "level": the band of its family and level.
payobject | nullrequired4 fields
amountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requiredproposedbooleanrequired
ftenumber | nullrequiredcomparednumber | nullrequiredThe pay as the band counts it (its period, full time).
pctnumber | nullrequiredstatus"below" | "in" | "above" | "other_currency" | "other_period"requiredNull when there is no band or no pay.
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
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"
}
}'const res = await fetch('https://api.bizisy.com/v1/org/pay_bands.position', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"person_id": "p1",
"as_of": "2026-11-01",
"title_id": "t1",
"proposed": {
"amount": 42000,
"currency": "EUR",
"period": "year"
}
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_bands.position",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"person_id": "p1",
"as_of": "2026-11-01",
"title_id": "t1",
"proposed": {
"amount": 42000,
"currency": "EUR",
"period": "year",
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
status"all" | "none" | "draft" | "approved"Default
"all".
Returns
An array of objects:
titleobjectrequired2 fields
idstringrequirednamestringrequired
familystring | nullrequiredlevelstring | nullrequiredpeopleintegerrequiredevaluationobject | nullrequired12 fields
idstringrequiredtitle_idstringrequiredfactorsobjectrequired4 fields
skillsintegerrequiredeffortintegerrequiredresponsibilityintegerrequiredworking_conditionsintegerrequired
otherobject[]required2 fields
namestringrequiredscoreintegerrequired
rationalestringrequiredstatus"draft" | "approved"requiredsource"hr" | "ai"requiredscorenumber | nullrequiredWeighted score 20–100 with the company's weights; null when every weight used is 0.
updated_bystringrequiredupdated_atstringrequiredapproved_bystring | nullrequiredapproved_atstring | nullrequired
categoryobject | nullrequired2 fields
idstringrequirednamestringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/title_evaluations.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status":"draft"}'const res = await fetch('https://api.bizisy.com/v1/org/title_evaluations.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"status": "draft"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/title_evaluations.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"status": "draft",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_seton HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
title_idstringrequiredfactorsobjectrequired4 fields
skillsintegerrequiredFrom 1 to 5.
effortintegerrequiredFrom 1 to 5.
responsibilityintegerrequiredFrom 1 to 5.
working_conditionsintegerrequiredFrom 1 to 5.
otherobject[]Up to 3 items.
2 fields
namestringrequired1–60 characters.
scoreintegerrequiredFrom 1 to 5.
rationalestringrequired10–2000 characters.
Returns
12 fields
idstringrequiredtitle_idstringrequiredfactorsobjectrequired4 fields
skillsintegerrequiredeffortintegerrequiredresponsibilityintegerrequiredworking_conditionsintegerrequired
otherobject[]required2 fields
namestringrequiredscoreintegerrequired
rationalestringrequiredstatus"draft" | "approved"requiredsource"hr" | "ai"requiredscorenumber | nullrequiredWeighted score 20–100 with the company's weights; null when every weight used is 0.
updated_bystringrequiredupdated_atstringrequiredapproved_bystring | nullrequiredapproved_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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."
}'const res = await fetch('https://api.bizisy.com/v1/org/title_evaluations.set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"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."
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/title_evaluations.set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"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.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_approveon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
title_idsstring[]required1–200 items.
Returns
An array of objects with 12 fields
An array of objects:
idstringrequiredtitle_idstringrequiredfactorsobjectrequired4 fields
skillsintegerrequiredeffortintegerrequiredresponsibilityintegerrequiredworking_conditionsintegerrequired
otherobject[]required2 fields
namestringrequiredscoreintegerrequired
rationalestringrequiredstatus"draft" | "approved"requiredsource"hr" | "ai"requiredscorenumber | nullrequiredWeighted score 20–100 with the company's weights; null when every weight used is 0.
updated_bystringrequiredupdated_atstringrequiredapproved_bystring | nullrequiredapproved_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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"]}'const res = await fetch('https://api.bizisy.com/v1/org/title_evaluations.approve', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"title_ids": [
"t1",
"t2"
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/title_evaluations.approve",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"title_ids": [
"t1",
"t2",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
itemsobject[]required7 fields
idstringrequirednamestringrequiredrationalestringrequiredtitlesobject[]required5 fields
idstringrequirednamestringrequiredscorenumber | nullrequiredapprovedbooleanrequiredFalse when its evaluation was edited since (back to draft): approve it again.
peopleintegerrequired
peopleintegerrequiredcreated_atstringrequiredupdated_atstringrequired
unplacedobject[]required5 fields
idstringrequirednamestringrequiredscorenumber | nullrequiredapprovedbooleanrequiredFalse 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 https://api.bizisy.com/v1/org/pay_categories.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/pay_categories.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_categories.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"items": [
{
"id": "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_suggeston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
spreadnumberFrom 0 to 50. Default
5.
Returns
groupsobject[]required5 fields
namestringrequiredmin_scorenumberrequiredmax_scorenumberrequiredtitle_idsstring[]requiredtitlesobject[]required5 fields
idstringrequirednamestringrequiredscorenumberrequiredpeopleintegerrequiredcategoryobject | nullrequired2 fields
idstringrequirednamestringrequired
spreadnumberrequirednot_evaluatedintegerrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/pay_categories.suggest \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"spread":8}'const res = await fetch('https://api.bizisy.com/v1/org/pay_categories.suggest', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"spread": 8
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_categories.suggest",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"spread": 8,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_seton HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
category_idstringnamestringrequired1–80 characters.
title_idsstring[]required1–500 items.
rationalestringrequired10–2000 characters.
Returns
8 fields
idstringrequirednamestringrequiredrationalestringrequiredtitlesobject[]required5 fields
idstringrequirednamestringrequiredscorenumber | nullrequiredapprovedbooleanrequiredFalse when its evaluation was edited since (back to draft): approve it again.
peopleintegerrequired
peopleintegerrequiredcreated_atstringrequiredupdated_atstringrequiredcreatedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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."
}'const res = await fetch('https://api.bizisy.com/v1/org/pay_categories.set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"category_id": "c1",
"name": "Engineering",
"title_ids": [
"t1"
],
"rationale": "Same engineering work, equal evaluation scores."
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_categories.set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"category_id": "c1",
"name": "Engineering",
"title_ids": [
"t1",
],
"rationale": "Same engineering work, equal evaluation scores.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_removeon HR Assistant- Preview
?dry_run=trueruns 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 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"}'const res = await fetch('https://api.bizisy.com/v1/org/pay_categories.remove', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"category_id": "c1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_categories.remove",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"category_id": "c1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
8 fields
weightsobjectrequired5 fields
skillsnumberrequiredeffortnumberrequiredresponsibilitynumberrequiredworking_conditionsnumberrequiredothernumberrequired
representativesobjectrequired3 fields
existbooleanrequiredcriteria_agreed_onstring | nullrequirednotestring | nullrequired
standard_week_hoursnumberrequiredpay_policystring | nullrequiredshow_bands_to_peoplebooleanrequiredreminder_monthintegerrequiredmin_groupintegerrequiredupdated_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/pay_equity.settings.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/pay_equity.settings.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_equity.settings.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"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_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
weightsobjectFactor weights in %, integers adding up to 100. "other" weighs the average of any other factors an evaluation names.
5 fields
skillsintegerrequiredFrom 0 to 100.
effortintegerrequiredFrom 0 to 100.
responsibilityintegerrequiredFrom 0 to 100.
working_conditionsintegerrequiredFrom 0 to 100.
otherintegerrequiredFrom 0 to 100.
representativesobjectWhether workers' representatives exist, when they agreed the evaluation criteria (Art. 4(4)), and a note.
3 fields
existbooleanrequiredcriteria_agreed_onstring | nullrequirednotestring | nullrequiredUp to 500 characters.
standard_week_hoursnumberA full-time week, for hourly pay levels when a job has no weekly hours.
From 1 to 60.
pay_policystring | nullHow pay, pay levels and progression are set (Art. 6), shown to everyone.
Up to 10000 characters.
show_bands_to_peoplebooleanWhether people see their own band and where they sit in it.
reminder_monthintegerThe month everyone is reminded of their right to ask about pay levels.
From 1 to 12.
min_groupintegerThe fewest people of each sex in a category before averages are shown to someone asking.
From 3 to 10.
Returns
8 fields
weightsobjectrequired5 fields
skillsnumberrequiredeffortnumberrequiredresponsibilitynumberrequiredworking_conditionsnumberrequiredothernumberrequired
representativesobjectrequired3 fields
existbooleanrequiredcriteria_agreed_onstring | nullrequirednotestring | nullrequired
standard_week_hoursnumberrequiredpay_policystring | nullrequiredshow_bands_to_peoplebooleanrequiredreminder_monthintegerrequiredmin_groupintegerrequiredupdated_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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
}'const res = await fetch('https://api.bizisy.com/v1/org/pay_equity.settings.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"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
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_equity.settings.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"weights": {
"skills": 30,
"effort": 20,
"responsibility": 30,
"working_conditions": 20,
"other": 0,
},
"representatives": {
"exist": True,
"criteria_agreed_on": "2026-09-01",
"note": None,
},
"standard_week_hours": 40,
"pay_policy": "Pay follows the band of your job.",
"reminder_month": 3,
"min_group": 5,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_overviewon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
legal_entity_idstringas_ofstring
Returns
15 fields
legal_entityobjectrequired2 fields
idstringrequirednamestringrequired
entitiesobject[]requiredActive legal entities: pass one as legal_entity_id to switch.
2 fields
idstringrequirednamestringrequired
periodobjectrequired2 fields
fromstringrequiredtostringrequired
currencystring | nullrequiredother_currenciesstring[]requiredpopulationintegerrequiredincludedintegerrequiredexcludedobjectrequired2 fields
no_payintegerrequiredother_currencyintegerrequired
indicatorsobjectrequired13 fields
womenintegerrequiredmenintegerrequirednot_includedintegerrequiredIncluded in pay but recorded as another, undisclosed or not recorded: counted, not compared.
mean_gapnumber | nullrequiredMean 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 | nullrequiredMedian gap on gross hourly pay (Art. 9(1)(c)).
annual_mean_gapnumber | nullrequiredannual_median_gapnumber | nullrequiredvariable_mean_gapnumber | nullrequiredMean gap in variable components among all workers of each sex (Art. 9(1)(b)); null without variable pay.
variable_median_gapnumber | nullrequiredwomen_receiving_variable_pctnumber | nullrequiredmen_receiving_variable_pctnumber | nullrequiredquartilesobject[]requiredFour groups by hourly pay, lowest first (Art. 9(1)(f)); n mod 4 extra people go to the first groups.
6 fields
quartileintegerrequiredpeopleintegerrequiredwomenintegerrequiredmenintegerrequiredwomen_pctnumber | nullrequiredmen_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"requiredtotalnumberrequiredwomen_receiving_pctnumber | nullrequiredmen_receiving_pctnumber | nullrequiredmean_gapnumber | nullrequiredmedian_gapnumber | nullrequired
categoriesobject[]required11 fields
idstringrequirednamestringrequiredwomenintegerrequiredmenintegerrequirednot_includedintegerrequiredmean_gapnumber | nullrequiredmedian_gapnumber | nullrequiredflaggedbooleanrequiredMean gap of 5% or more either way, in a category that is not small_group.
small_groupbooleanrequiredFewer 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_bandintegerrequiredPeople in the category on the period's last day whose pay is below their band.
above_bandintegerrequired
uncategorisedintegerrequiredthresholdnumberrequiredmin_groupintegerrequireddutyobjectrequired2 fields
last_yearobjectrequiredThe 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
bandstringrequirede.g. "250+", "150-249", "under-100".
minintegerrequiredmaxinteger | nullrequiredevery_yearsinteger | nullrequiredHow often this band reports; null: no duty.
first_dueinteger | nullrequiredThe year the first report of this band is due (7 June).
sourcestringrequiredsource_labelstringrequiredThe law the thresholds come from.
enactedbooleanrequirednotestring | nullrequiredWhat else matters under that law (English), e.g. a different report period or who prepares the report.
due_bystring | nullrequiredWhen a report on this year is due (7 June of the next year); null when this band reports no such year.
yearintegerrequiredworkersintegerrequired
this_yearobjectrequiredAverage workers so far this year, as a hint of next year's duty (due_by: a report on this year).
12 fields
bandstringrequirede.g. "250+", "150-249", "under-100".
minintegerrequiredmaxinteger | nullrequiredevery_yearsinteger | nullrequiredHow often this band reports; null: no duty.
first_dueinteger | nullrequiredThe year the first report of this band is due (7 June).
sourcestringrequiredsource_labelstringrequiredThe law the thresholds come from.
enactedbooleanrequirednotestring | nullrequiredWhat else matters under that law (English), e.g. a different report period or who prepares the report.
due_bystring | nullrequiredWhen a report on this year is due (7 June of the next year); null when this band reports no such year.
yearintegerrequiredworkersintegerrequired
attentionobject[]required3 fields
kind"titles_not_evaluated" | "no_category" | "no_sex" | "no_pay" | "other_currency"requiredtitles_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).
countintegerrequiredidsstring[]required
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/org/pay_equity.overview', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"legal_entity_id": "e1",
"as_of": "2026-06-30"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_equity.overview",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"legal_entity_id": "e1",
"as_of": "2026-06-30",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
legal_entity_idstring
Returns
itemsobject[]required14 fields
idstringrequiredlegal_entityobjectrequired2 fields
idstringrequirednamestringrequired
yearintegerrequiredstatus"draft" | "final"requiredheadcountintegerrequireddutyobjectrequiredBy 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
bandstringrequirede.g. "250+", "150-249", "under-100".
minintegerrequiredmaxinteger | nullrequiredevery_yearsinteger | nullrequiredHow often this band reports; null: no duty.
first_dueinteger | nullrequiredThe year the first report of this band is due (7 June).
sourcestringrequiredsource_labelstringrequiredThe law the thresholds come from.
enactedbooleanrequirednotestring | nullrequiredWhat else matters under that law (English), e.g. a different report period or who prepares the report.
due_bystring | nullrequiredWhen a report on this year is due (7 June of the next year); null when this band reports no such year.
flaggedintegerrequiredCategories with a mean gap of 5% or more.
unjustifiedintegerrequiredFlagged categories with no justification yet.
assessment_dueintegerrequiredinputs_countintegerrequiredcreated_atstringrequiredupdated_atstringrequiredfinalised_atstring | nullrequiredsubmitted_onstring | nullrequired
dutiesobject[]requiredEach 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
bandstringrequirede.g. "250+", "150-249", "under-100".
minintegerrequiredmaxinteger | nullrequiredevery_yearsinteger | nullrequiredHow often this band reports; null: no duty.
first_dueinteger | nullrequiredThe year the first report of this band is due (7 June).
sourcestringrequiredsource_labelstringrequiredThe law the thresholds come from.
enactedbooleanrequirednotestring | nullrequiredWhat else matters under that law (English), e.g. a different report period or who prepares the report.
due_bystring | nullrequiredWhen a report on this year is due (7 June of the next year); null when this band reports no such year.
legal_entityobjectrequired2 fields
idstringrequirednamestringrequired
yearintegerrequiredworkersintegerrequiredreport_idstring | nullrequiredThat year's report, when one exists.
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/org/pay_reports.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"legal_entity_id": "e1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_reports.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"legal_entity_id": "e1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
report_idstringrequired
Returns
23 fields
idstringrequiredlegal_entityobjectrequired2 fields
idstringrequirednamestringrequired
yearintegerrequiredstatus"draft" | "final"requiredheadcountintegerrequireddutyobjectrequiredBy 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
bandstringrequirede.g. "250+", "150-249", "under-100".
minintegerrequiredmaxinteger | nullrequiredevery_yearsinteger | nullrequiredHow often this band reports; null: no duty.
first_dueinteger | nullrequiredThe year the first report of this band is due (7 June).
sourcestringrequiredsource_labelstringrequiredThe law the thresholds come from.
enactedbooleanrequirednotestring | nullrequiredWhat else matters under that law (English), e.g. a different report period or who prepares the report.
due_bystring | nullrequiredWhen a report on this year is due (7 June of the next year); null when this band reports no such year.
flaggedintegerrequiredCategories with a mean gap of 5% or more.
unjustifiedintegerrequiredFlagged categories with no justification yet.
assessment_dueintegerrequiredinputs_countintegerrequiredcreated_atstringrequiredupdated_atstringrequiredfinalised_atstring | nullrequiredsubmitted_onstring | nullrequiredcurrencystring | nullrequiredpopulationintegerrequiredexcludedobjectrequiredPeople 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_payintegerrequiredother_currencyintegerrequired
indicatorsobjectrequired13 fields
womenintegerrequiredmenintegerrequirednot_includedintegerrequiredIncluded in pay but recorded as another, undisclosed or not recorded: counted, not compared.
mean_gapnumber | nullrequiredMean 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 | nullrequiredMedian gap on gross hourly pay (Art. 9(1)(c)).
annual_mean_gapnumber | nullrequiredannual_median_gapnumber | nullrequiredvariable_mean_gapnumber | nullrequiredMean gap in variable components among all workers of each sex (Art. 9(1)(b)); null without variable pay.
variable_median_gapnumber | nullrequiredwomen_receiving_variable_pctnumber | nullrequiredmen_receiving_variable_pctnumber | nullrequiredquartilesobject[]requiredFour groups by hourly pay, lowest first (Art. 9(1)(f)); n mod 4 extra people go to the first groups.
6 fields
quartileintegerrequiredpeopleintegerrequiredwomenintegerrequiredmenintegerrequiredwomen_pctnumber | nullrequiredmen_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"requiredtotalnumberrequiredwomen_receiving_pctnumber | nullrequiredmen_receiving_pctnumber | nullrequiredmean_gapnumber | nullrequiredmedian_gapnumber | nullrequired
categoriesobject[]required15 fields
idstringrequirednamestringrequiredwomenintegerrequiredmenintegerrequirednot_includedintegerrequiredbase_mean_gapnumber | nullrequiredbase_median_gapnumber | nullrequiredvariable_mean_gapnumber | nullrequiredvariable_median_gapnumber | nullrequiredtotal_mean_gapnumber | nullrequiredtotal_median_gapnumber | nullrequiredflaggedbooleanrequired|total_mean_gap| ≥ 5%: needs a justification by objective, gender-neutral factors or a remedy (Art. 10).
small_groupbooleanrequiredFewer 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_duebooleanrequiredFinal 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 | nullrequired6 fields
reasonstringrequiredobjective_factorsstring[]requiredremedystring | nullrequiredremedy_bystring | nullrequiredupdated_bystringrequiredupdated_atstringrequired
uncategorisedintegerrequiredIncluded people whose job title is in no pay category.
variable_sourcesobject | nullrequiredWhere the variable pay came from (totals only); null on reports made before it was read from Bizisy.
4 fields
payrollobjectrequired4 fields
onbooleanrequiredPayroll is on: its pay items in money count.
itemsobject[]required6 fields
idstringrequirednamestringrequiredcomponent"bonus" | "allowances" | "not_pay"requiredchangedbooleanrequiredHR changed it from the default.
totalnumber | nullrequirednull when fewer than min_group people received it (it would show their pay).
peopleintegerrequired
not_in_moneyintegerrequiredEarnings in hours or days: not counted (no amount).
other_currencyintegerrequiredAmounts in another currency than the report's: not counted.
benefitsobjectrequired4 fields
onbooleanrequiredin_kindnumber | nullrequiredallowancesnumber | nullrequiredCash meal allowances. Both null when fewer than min_group people received benefits.
peopleintegerrequired
fileobjectrequired2 fields
peopleintegerrequiredcolumns"bonus" | "allowances" | "in_kind"[]requiredFor these columns, the file's amount replaces Bizisy's for the people in it.
bonusesobjectBonus plans' awards paid by hand (awards paid through Payroll are its Bonus items).
3 fields
onbooleanrequiredtotalnumber | nullrequirednull when fewer than min_group people received one.
peopleintegerrequired
finalised_bystring | nullrequiredfollow_upobjectrequired3 fields
remedy_window_endsstring | nullrequiredSix months after finalising (Art. 10(1)(c)): gaps not justified or remedied by then call for a joint pay assessment.
assessment_within_daysinteger | nullrequiredDays to carry out a joint pay assessment once due, when the entity's national law sets it; null otherwise.
authoritystring | nullrequiredWho receives the report, when national law names it; null otherwise.
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/org/pay_reports.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"report_id": "pr1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_reports.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"report_id": "pr1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_createon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
legal_entity_idstringrequiredyearintegerrequiredFrom 2000 to 2100.
Returns
24 fields
idstringrequiredlegal_entityobjectrequired2 fields
idstringrequirednamestringrequired
yearintegerrequiredstatus"draft" | "final"requiredheadcountintegerrequireddutyobjectrequiredBy 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
bandstringrequirede.g. "250+", "150-249", "under-100".
minintegerrequiredmaxinteger | nullrequiredevery_yearsinteger | nullrequiredHow often this band reports; null: no duty.
first_dueinteger | nullrequiredThe year the first report of this band is due (7 June).
sourcestringrequiredsource_labelstringrequiredThe law the thresholds come from.
enactedbooleanrequirednotestring | nullrequiredWhat else matters under that law (English), e.g. a different report period or who prepares the report.
due_bystring | nullrequiredWhen a report on this year is due (7 June of the next year); null when this band reports no such year.
flaggedintegerrequiredCategories with a mean gap of 5% or more.
unjustifiedintegerrequiredFlagged categories with no justification yet.
assessment_dueintegerrequiredinputs_countintegerrequiredcreated_atstringrequiredupdated_atstringrequiredfinalised_atstring | nullrequiredsubmitted_onstring | nullrequiredcurrencystring | nullrequiredpopulationintegerrequiredexcludedobjectrequiredPeople 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_payintegerrequiredother_currencyintegerrequired
indicatorsobjectrequired13 fields
womenintegerrequiredmenintegerrequirednot_includedintegerrequiredIncluded in pay but recorded as another, undisclosed or not recorded: counted, not compared.
mean_gapnumber | nullrequiredMean 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 | nullrequiredMedian gap on gross hourly pay (Art. 9(1)(c)).
annual_mean_gapnumber | nullrequiredannual_median_gapnumber | nullrequiredvariable_mean_gapnumber | nullrequiredMean gap in variable components among all workers of each sex (Art. 9(1)(b)); null without variable pay.
variable_median_gapnumber | nullrequiredwomen_receiving_variable_pctnumber | nullrequiredmen_receiving_variable_pctnumber | nullrequiredquartilesobject[]requiredFour groups by hourly pay, lowest first (Art. 9(1)(f)); n mod 4 extra people go to the first groups.
6 fields
quartileintegerrequiredpeopleintegerrequiredwomenintegerrequiredmenintegerrequiredwomen_pctnumber | nullrequiredmen_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"requiredtotalnumberrequiredwomen_receiving_pctnumber | nullrequiredmen_receiving_pctnumber | nullrequiredmean_gapnumber | nullrequiredmedian_gapnumber | nullrequired
categoriesobject[]required15 fields
idstringrequirednamestringrequiredwomenintegerrequiredmenintegerrequirednot_includedintegerrequiredbase_mean_gapnumber | nullrequiredbase_median_gapnumber | nullrequiredvariable_mean_gapnumber | nullrequiredvariable_median_gapnumber | nullrequiredtotal_mean_gapnumber | nullrequiredtotal_median_gapnumber | nullrequiredflaggedbooleanrequired|total_mean_gap| ≥ 5%: needs a justification by objective, gender-neutral factors or a remedy (Art. 10).
small_groupbooleanrequiredFewer 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_duebooleanrequiredFinal 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 | nullrequired6 fields
reasonstringrequiredobjective_factorsstring[]requiredremedystring | nullrequiredremedy_bystring | nullrequiredupdated_bystringrequiredupdated_atstringrequired
uncategorisedintegerrequiredIncluded people whose job title is in no pay category.
variable_sourcesobject | nullrequiredWhere the variable pay came from (totals only); null on reports made before it was read from Bizisy.
4 fields
payrollobjectrequired4 fields
onbooleanrequiredPayroll is on: its pay items in money count.
itemsobject[]required6 fields
idstringrequirednamestringrequiredcomponent"bonus" | "allowances" | "not_pay"requiredchangedbooleanrequiredHR changed it from the default.
totalnumber | nullrequirednull when fewer than min_group people received it (it would show their pay).
peopleintegerrequired
not_in_moneyintegerrequiredEarnings in hours or days: not counted (no amount).
other_currencyintegerrequiredAmounts in another currency than the report's: not counted.
benefitsobjectrequired4 fields
onbooleanrequiredin_kindnumber | nullrequiredallowancesnumber | nullrequiredCash meal allowances. Both null when fewer than min_group people received benefits.
peopleintegerrequired
fileobjectrequired2 fields
peopleintegerrequiredcolumns"bonus" | "allowances" | "in_kind"[]requiredFor these columns, the file's amount replaces Bizisy's for the people in it.
bonusesobjectBonus plans' awards paid by hand (awards paid through Payroll are its Bonus items).
3 fields
onbooleanrequiredtotalnumber | nullrequirednull when fewer than min_group people received one.
peopleintegerrequired
finalised_bystring | nullrequiredfollow_upobjectrequired3 fields
remedy_window_endsstring | nullrequiredSix months after finalising (Art. 10(1)(c)): gaps not justified or remedied by then call for a joint pay assessment.
assessment_within_daysinteger | nullrequiredDays to carry out a joint pay assessment once due, when the entity's national law sets it; null otherwise.
authoritystring | nullrequiredWho receives the report, when national law names it; null otherwise.
createdbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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}'const res = await fetch('https://api.bizisy.com/v1/org/pay_reports.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"legal_entity_id": "e1",
"year": 2025
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_reports.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"legal_entity_id": "e1",
"year": 2025,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_variableon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
report_idstringrequiredcsvstringrequired1–1000000 characters.
appendbooleanDefault
false.
Returns
7 fields
reportobjectrequired23 fields
idstringrequiredlegal_entityobjectrequired2 fields
idstringrequirednamestringrequired
yearintegerrequiredstatus"draft" | "final"requiredheadcountintegerrequireddutyobjectrequiredBy 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
bandstringrequirede.g. "250+", "150-249", "under-100".
minintegerrequiredmaxinteger | nullrequiredevery_yearsinteger | nullrequiredHow often this band reports; null: no duty.
first_dueinteger | nullrequiredThe year the first report of this band is due (7 June).
sourcestringrequiredsource_labelstringrequiredThe law the thresholds come from.
enactedbooleanrequirednotestring | nullrequiredWhat else matters under that law (English), e.g. a different report period or who prepares the report.
due_bystring | nullrequiredWhen a report on this year is due (7 June of the next year); null when this band reports no such year.
flaggedintegerrequiredCategories with a mean gap of 5% or more.
unjustifiedintegerrequiredFlagged categories with no justification yet.
assessment_dueintegerrequiredinputs_countintegerrequiredcreated_atstringrequiredupdated_atstringrequiredfinalised_atstring | nullrequiredsubmitted_onstring | nullrequiredcurrencystring | nullrequiredpopulationintegerrequiredexcludedobjectrequiredPeople 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_payintegerrequiredother_currencyintegerrequired
indicatorsobjectrequired13 fields
womenintegerrequiredmenintegerrequirednot_includedintegerrequiredIncluded in pay but recorded as another, undisclosed or not recorded: counted, not compared.
mean_gapnumber | nullrequiredMean 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 | nullrequiredMedian gap on gross hourly pay (Art. 9(1)(c)).
annual_mean_gapnumber | nullrequiredannual_median_gapnumber | nullrequiredvariable_mean_gapnumber | nullrequiredMean gap in variable components among all workers of each sex (Art. 9(1)(b)); null without variable pay.
variable_median_gapnumber | nullrequiredwomen_receiving_variable_pctnumber | nullrequiredmen_receiving_variable_pctnumber | nullrequiredquartilesobject[]requiredFour groups by hourly pay, lowest first (Art. 9(1)(f)); n mod 4 extra people go to the first groups.
6 fields
quartileintegerrequiredpeopleintegerrequiredwomenintegerrequiredmenintegerrequiredwomen_pctnumber | nullrequiredmen_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"requiredtotalnumberrequiredwomen_receiving_pctnumber | nullrequiredmen_receiving_pctnumber | nullrequiredmean_gapnumber | nullrequiredmedian_gapnumber | nullrequired
categoriesobject[]required15 fields
idstringrequirednamestringrequiredwomenintegerrequiredmenintegerrequirednot_includedintegerrequiredbase_mean_gapnumber | nullrequiredbase_median_gapnumber | nullrequiredvariable_mean_gapnumber | nullrequiredvariable_median_gapnumber | nullrequiredtotal_mean_gapnumber | nullrequiredtotal_median_gapnumber | nullrequiredflaggedbooleanrequired|total_mean_gap| ≥ 5%: needs a justification by objective, gender-neutral factors or a remedy (Art. 10).
small_groupbooleanrequiredFewer 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_duebooleanrequiredFinal 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 | nullrequired6 fields
reasonstringrequiredobjective_factorsstring[]requiredremedystring | nullrequiredremedy_bystring | nullrequiredupdated_bystringrequiredupdated_atstringrequired
uncategorisedintegerrequiredIncluded people whose job title is in no pay category.
variable_sourcesobject | nullrequiredWhere the variable pay came from (totals only); null on reports made before it was read from Bizisy.
4 fields
payrollobjectrequired4 fields
onbooleanrequiredPayroll is on: its pay items in money count.
itemsobject[]required6 fields
idstringrequirednamestringrequiredcomponent"bonus" | "allowances" | "not_pay"requiredchangedbooleanrequiredHR changed it from the default.
totalnumber | nullrequirednull when fewer than min_group people received it (it would show their pay).
peopleintegerrequired
not_in_moneyintegerrequiredEarnings in hours or days: not counted (no amount).
other_currencyintegerrequiredAmounts in another currency than the report's: not counted.
benefitsobjectrequired4 fields
onbooleanrequiredin_kindnumber | nullrequiredallowancesnumber | nullrequiredCash meal allowances. Both null when fewer than min_group people received benefits.
peopleintegerrequired
fileobjectrequired2 fields
peopleintegerrequiredcolumns"bonus" | "allowances" | "in_kind"[]requiredFor these columns, the file's amount replaces Bizisy's for the people in it.
bonusesobjectBonus plans' awards paid by hand (awards paid through Payroll are its Bonus items).
3 fields
onbooleanrequiredtotalnumber | nullrequirednull when fewer than min_group people received one.
peopleintegerrequired
finalised_bystring | nullrequiredfollow_upobjectrequired3 fields
remedy_window_endsstring | nullrequiredSix months after finalising (Art. 10(1)(c)): gaps not justified or remedied by then call for a joint pay assessment.
assessment_within_daysinteger | nullrequiredDays to carry out a joint pay assessment once due, when the entity's national law sets it; null otherwise.
authoritystring | nullrequiredWho receives the report, when national law names it; null otherwise.
appliedbooleanrequiredFalse when row_errors stopped the upload.
matchedintegerrequiredPeople whose variable pay was read.
unknownobject[]required2 fields
rowintegerrequiredemailstringrequired
outsideobject[]requiredPeople with no job in the entity that year.
2 fields
rowintegerrequiredemailstringrequired
duplicatesobject[]requiredFurther rows of a person already in the file: added to their first row.
2 fields
rowintegerrequiredemailstringrequired
row_errorsobject[]required2 fields
rowintegerrequiredmessagestringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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"
}'const res = await fetch('https://api.bizisy.com/v1/org/pay_reports.upload_variable', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"report_id": "pr1",
"csv": "work_email,bonus,allowances,in_kind\nana@acme.test,1500,0,0\n"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_reports.upload_variable",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"report_id": "pr1",
"csv": "work_email,bonus,allowances,in_kind\nana@acme.test,1500,0,0\n",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_componentson HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
report_idstringrequireditemsobjectrequired
Returns
23 fields
idstringrequiredlegal_entityobjectrequired2 fields
idstringrequirednamestringrequired
yearintegerrequiredstatus"draft" | "final"requiredheadcountintegerrequireddutyobjectrequiredBy 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
bandstringrequirede.g. "250+", "150-249", "under-100".
minintegerrequiredmaxinteger | nullrequiredevery_yearsinteger | nullrequiredHow often this band reports; null: no duty.
first_dueinteger | nullrequiredThe year the first report of this band is due (7 June).
sourcestringrequiredsource_labelstringrequiredThe law the thresholds come from.
enactedbooleanrequirednotestring | nullrequiredWhat else matters under that law (English), e.g. a different report period or who prepares the report.
due_bystring | nullrequiredWhen a report on this year is due (7 June of the next year); null when this band reports no such year.
flaggedintegerrequiredCategories with a mean gap of 5% or more.
unjustifiedintegerrequiredFlagged categories with no justification yet.
assessment_dueintegerrequiredinputs_countintegerrequiredcreated_atstringrequiredupdated_atstringrequiredfinalised_atstring | nullrequiredsubmitted_onstring | nullrequiredcurrencystring | nullrequiredpopulationintegerrequiredexcludedobjectrequiredPeople 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_payintegerrequiredother_currencyintegerrequired
indicatorsobjectrequired13 fields
womenintegerrequiredmenintegerrequirednot_includedintegerrequiredIncluded in pay but recorded as another, undisclosed or not recorded: counted, not compared.
mean_gapnumber | nullrequiredMean 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 | nullrequiredMedian gap on gross hourly pay (Art. 9(1)(c)).
annual_mean_gapnumber | nullrequiredannual_median_gapnumber | nullrequiredvariable_mean_gapnumber | nullrequiredMean gap in variable components among all workers of each sex (Art. 9(1)(b)); null without variable pay.
variable_median_gapnumber | nullrequiredwomen_receiving_variable_pctnumber | nullrequiredmen_receiving_variable_pctnumber | nullrequiredquartilesobject[]requiredFour groups by hourly pay, lowest first (Art. 9(1)(f)); n mod 4 extra people go to the first groups.
6 fields
quartileintegerrequiredpeopleintegerrequiredwomenintegerrequiredmenintegerrequiredwomen_pctnumber | nullrequiredmen_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"requiredtotalnumberrequiredwomen_receiving_pctnumber | nullrequiredmen_receiving_pctnumber | nullrequiredmean_gapnumber | nullrequiredmedian_gapnumber | nullrequired
categoriesobject[]required15 fields
idstringrequirednamestringrequiredwomenintegerrequiredmenintegerrequirednot_includedintegerrequiredbase_mean_gapnumber | nullrequiredbase_median_gapnumber | nullrequiredvariable_mean_gapnumber | nullrequiredvariable_median_gapnumber | nullrequiredtotal_mean_gapnumber | nullrequiredtotal_median_gapnumber | nullrequiredflaggedbooleanrequired|total_mean_gap| ≥ 5%: needs a justification by objective, gender-neutral factors or a remedy (Art. 10).
small_groupbooleanrequiredFewer 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_duebooleanrequiredFinal 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 | nullrequired6 fields
reasonstringrequiredobjective_factorsstring[]requiredremedystring | nullrequiredremedy_bystring | nullrequiredupdated_bystringrequiredupdated_atstringrequired
uncategorisedintegerrequiredIncluded people whose job title is in no pay category.
variable_sourcesobject | nullrequiredWhere the variable pay came from (totals only); null on reports made before it was read from Bizisy.
4 fields
payrollobjectrequired4 fields
onbooleanrequiredPayroll is on: its pay items in money count.
itemsobject[]required6 fields
idstringrequirednamestringrequiredcomponent"bonus" | "allowances" | "not_pay"requiredchangedbooleanrequiredHR changed it from the default.
totalnumber | nullrequirednull when fewer than min_group people received it (it would show their pay).
peopleintegerrequired
not_in_moneyintegerrequiredEarnings in hours or days: not counted (no amount).
other_currencyintegerrequiredAmounts in another currency than the report's: not counted.
benefitsobjectrequired4 fields
onbooleanrequiredin_kindnumber | nullrequiredallowancesnumber | nullrequiredCash meal allowances. Both null when fewer than min_group people received benefits.
peopleintegerrequired
fileobjectrequired2 fields
peopleintegerrequiredcolumns"bonus" | "allowances" | "in_kind"[]requiredFor these columns, the file's amount replaces Bizisy's for the people in it.
bonusesobjectBonus plans' awards paid by hand (awards paid through Payroll are its Bonus items).
3 fields
onbooleanrequiredtotalnumber | nullrequirednull when fewer than min_group people received one.
peopleintegerrequired
finalised_bystring | nullrequiredfollow_upobjectrequired3 fields
remedy_window_endsstring | nullrequiredSix months after finalising (Art. 10(1)(c)): gaps not justified or remedied by then call for a joint pay assessment.
assessment_within_daysinteger | nullrequiredDays to carry out a joint pay assessment once due, when the entity's national law sets it; null otherwise.
authoritystring | nullrequiredWho receives the report, when national law names it; null otherwise.
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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"}}'const res = await fetch('https://api.bizisy.com/v1/org/pay_reports.components', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"report_id": "pr1",
"items": {
"it2": "not_pay",
"it1": "default"
}
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_reports.components",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"report_id": "pr1",
"items": {
"it2": "not_pay",
"it1": "default",
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_justifyon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
report_idstringrequiredcategory_idstringrequiredreasonstringrequired10–2000 characters.
objective_factorsstring[]1–200 characters. Up to 10 items.
remedystring | nullUp to 2000 characters.
remedy_bystring | null
Returns
23 fields
idstringrequiredlegal_entityobjectrequired2 fields
idstringrequirednamestringrequired
yearintegerrequiredstatus"draft" | "final"requiredheadcountintegerrequireddutyobjectrequiredBy 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
bandstringrequirede.g. "250+", "150-249", "under-100".
minintegerrequiredmaxinteger | nullrequiredevery_yearsinteger | nullrequiredHow often this band reports; null: no duty.
first_dueinteger | nullrequiredThe year the first report of this band is due (7 June).
sourcestringrequiredsource_labelstringrequiredThe law the thresholds come from.
enactedbooleanrequirednotestring | nullrequiredWhat else matters under that law (English), e.g. a different report period or who prepares the report.
due_bystring | nullrequiredWhen a report on this year is due (7 June of the next year); null when this band reports no such year.
flaggedintegerrequiredCategories with a mean gap of 5% or more.
unjustifiedintegerrequiredFlagged categories with no justification yet.
assessment_dueintegerrequiredinputs_countintegerrequiredcreated_atstringrequiredupdated_atstringrequiredfinalised_atstring | nullrequiredsubmitted_onstring | nullrequiredcurrencystring | nullrequiredpopulationintegerrequiredexcludedobjectrequiredPeople 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_payintegerrequiredother_currencyintegerrequired
indicatorsobjectrequired13 fields
womenintegerrequiredmenintegerrequirednot_includedintegerrequiredIncluded in pay but recorded as another, undisclosed or not recorded: counted, not compared.
mean_gapnumber | nullrequiredMean 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 | nullrequiredMedian gap on gross hourly pay (Art. 9(1)(c)).
annual_mean_gapnumber | nullrequiredannual_median_gapnumber | nullrequiredvariable_mean_gapnumber | nullrequiredMean gap in variable components among all workers of each sex (Art. 9(1)(b)); null without variable pay.
variable_median_gapnumber | nullrequiredwomen_receiving_variable_pctnumber | nullrequiredmen_receiving_variable_pctnumber | nullrequiredquartilesobject[]requiredFour groups by hourly pay, lowest first (Art. 9(1)(f)); n mod 4 extra people go to the first groups.
6 fields
quartileintegerrequiredpeopleintegerrequiredwomenintegerrequiredmenintegerrequiredwomen_pctnumber | nullrequiredmen_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"requiredtotalnumberrequiredwomen_receiving_pctnumber | nullrequiredmen_receiving_pctnumber | nullrequiredmean_gapnumber | nullrequiredmedian_gapnumber | nullrequired
categoriesobject[]required15 fields
idstringrequirednamestringrequiredwomenintegerrequiredmenintegerrequirednot_includedintegerrequiredbase_mean_gapnumber | nullrequiredbase_median_gapnumber | nullrequiredvariable_mean_gapnumber | nullrequiredvariable_median_gapnumber | nullrequiredtotal_mean_gapnumber | nullrequiredtotal_median_gapnumber | nullrequiredflaggedbooleanrequired|total_mean_gap| ≥ 5%: needs a justification by objective, gender-neutral factors or a remedy (Art. 10).
small_groupbooleanrequiredFewer 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_duebooleanrequiredFinal 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 | nullrequired6 fields
reasonstringrequiredobjective_factorsstring[]requiredremedystring | nullrequiredremedy_bystring | nullrequiredupdated_bystringrequiredupdated_atstringrequired
uncategorisedintegerrequiredIncluded people whose job title is in no pay category.
variable_sourcesobject | nullrequiredWhere the variable pay came from (totals only); null on reports made before it was read from Bizisy.
4 fields
payrollobjectrequired4 fields
onbooleanrequiredPayroll is on: its pay items in money count.
itemsobject[]required6 fields
idstringrequirednamestringrequiredcomponent"bonus" | "allowances" | "not_pay"requiredchangedbooleanrequiredHR changed it from the default.
totalnumber | nullrequirednull when fewer than min_group people received it (it would show their pay).
peopleintegerrequired
not_in_moneyintegerrequiredEarnings in hours or days: not counted (no amount).
other_currencyintegerrequiredAmounts in another currency than the report's: not counted.
benefitsobjectrequired4 fields
onbooleanrequiredin_kindnumber | nullrequiredallowancesnumber | nullrequiredCash meal allowances. Both null when fewer than min_group people received benefits.
peopleintegerrequired
fileobjectrequired2 fields
peopleintegerrequiredcolumns"bonus" | "allowances" | "in_kind"[]requiredFor these columns, the file's amount replaces Bizisy's for the people in it.
bonusesobjectBonus plans' awards paid by hand (awards paid through Payroll are its Bonus items).
3 fields
onbooleanrequiredtotalnumber | nullrequirednull when fewer than min_group people received one.
peopleintegerrequired
finalised_bystring | nullrequiredfollow_upobjectrequired3 fields
remedy_window_endsstring | nullrequiredSix months after finalising (Art. 10(1)(c)): gaps not justified or remedied by then call for a joint pay assessment.
assessment_within_daysinteger | nullrequiredDays to carry out a joint pay assessment once due, when the entity's national law sets it; null otherwise.
authoritystring | nullrequiredWho receives the report, when national law names it; null otherwise.
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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"
}'const res = await fetch('https://api.bizisy.com/v1/org/pay_reports.justify', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"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"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_reports.justify",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"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",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_finaliseon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
report_idstringrequiredacknowledge_unjustifiedbooleanDefault
false.
Returns
23 fields
idstringrequiredlegal_entityobjectrequired2 fields
idstringrequirednamestringrequired
yearintegerrequiredstatus"draft" | "final"requiredheadcountintegerrequireddutyobjectrequiredBy 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
bandstringrequirede.g. "250+", "150-249", "under-100".
minintegerrequiredmaxinteger | nullrequiredevery_yearsinteger | nullrequiredHow often this band reports; null: no duty.
first_dueinteger | nullrequiredThe year the first report of this band is due (7 June).
sourcestringrequiredsource_labelstringrequiredThe law the thresholds come from.
enactedbooleanrequirednotestring | nullrequiredWhat else matters under that law (English), e.g. a different report period or who prepares the report.
due_bystring | nullrequiredWhen a report on this year is due (7 June of the next year); null when this band reports no such year.
flaggedintegerrequiredCategories with a mean gap of 5% or more.
unjustifiedintegerrequiredFlagged categories with no justification yet.
assessment_dueintegerrequiredinputs_countintegerrequiredcreated_atstringrequiredupdated_atstringrequiredfinalised_atstring | nullrequiredsubmitted_onstring | nullrequiredcurrencystring | nullrequiredpopulationintegerrequiredexcludedobjectrequiredPeople 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_payintegerrequiredother_currencyintegerrequired
indicatorsobjectrequired13 fields
womenintegerrequiredmenintegerrequirednot_includedintegerrequiredIncluded in pay but recorded as another, undisclosed or not recorded: counted, not compared.
mean_gapnumber | nullrequiredMean 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 | nullrequiredMedian gap on gross hourly pay (Art. 9(1)(c)).
annual_mean_gapnumber | nullrequiredannual_median_gapnumber | nullrequiredvariable_mean_gapnumber | nullrequiredMean gap in variable components among all workers of each sex (Art. 9(1)(b)); null without variable pay.
variable_median_gapnumber | nullrequiredwomen_receiving_variable_pctnumber | nullrequiredmen_receiving_variable_pctnumber | nullrequiredquartilesobject[]requiredFour groups by hourly pay, lowest first (Art. 9(1)(f)); n mod 4 extra people go to the first groups.
6 fields
quartileintegerrequiredpeopleintegerrequiredwomenintegerrequiredmenintegerrequiredwomen_pctnumber | nullrequiredmen_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"requiredtotalnumberrequiredwomen_receiving_pctnumber | nullrequiredmen_receiving_pctnumber | nullrequiredmean_gapnumber | nullrequiredmedian_gapnumber | nullrequired
categoriesobject[]required15 fields
idstringrequirednamestringrequiredwomenintegerrequiredmenintegerrequirednot_includedintegerrequiredbase_mean_gapnumber | nullrequiredbase_median_gapnumber | nullrequiredvariable_mean_gapnumber | nullrequiredvariable_median_gapnumber | nullrequiredtotal_mean_gapnumber | nullrequiredtotal_median_gapnumber | nullrequiredflaggedbooleanrequired|total_mean_gap| ≥ 5%: needs a justification by objective, gender-neutral factors or a remedy (Art. 10).
small_groupbooleanrequiredFewer 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_duebooleanrequiredFinal 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 | nullrequired6 fields
reasonstringrequiredobjective_factorsstring[]requiredremedystring | nullrequiredremedy_bystring | nullrequiredupdated_bystringrequiredupdated_atstringrequired
uncategorisedintegerrequiredIncluded people whose job title is in no pay category.
variable_sourcesobject | nullrequiredWhere the variable pay came from (totals only); null on reports made before it was read from Bizisy.
4 fields
payrollobjectrequired4 fields
onbooleanrequiredPayroll is on: its pay items in money count.
itemsobject[]required6 fields
idstringrequirednamestringrequiredcomponent"bonus" | "allowances" | "not_pay"requiredchangedbooleanrequiredHR changed it from the default.
totalnumber | nullrequirednull when fewer than min_group people received it (it would show their pay).
peopleintegerrequired
not_in_moneyintegerrequiredEarnings in hours or days: not counted (no amount).
other_currencyintegerrequiredAmounts in another currency than the report's: not counted.
benefitsobjectrequired4 fields
onbooleanrequiredin_kindnumber | nullrequiredallowancesnumber | nullrequiredCash meal allowances. Both null when fewer than min_group people received benefits.
peopleintegerrequired
fileobjectrequired2 fields
peopleintegerrequiredcolumns"bonus" | "allowances" | "in_kind"[]requiredFor these columns, the file's amount replaces Bizisy's for the people in it.
bonusesobjectBonus plans' awards paid by hand (awards paid through Payroll are its Bonus items).
3 fields
onbooleanrequiredtotalnumber | nullrequirednull when fewer than min_group people received one.
peopleintegerrequired
finalised_bystring | nullrequiredfollow_upobjectrequired3 fields
remedy_window_endsstring | nullrequiredSix months after finalising (Art. 10(1)(c)): gaps not justified or remedied by then call for a joint pay assessment.
assessment_within_daysinteger | nullrequiredDays to carry out a joint pay assessment once due, when the entity's national law sets it; null otherwise.
authoritystring | nullrequiredWho receives the report, when national law names it; null otherwise.
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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}'const res = await fetch('https://api.bizisy.com/v1/org/pay_reports.finalise', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"report_id": "pr1",
"acknowledge_unjustified": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_reports.finalise",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"report_id": "pr1",
"acknowledge_unjustified": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_submittedon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
report_idstringrequiredonstring | nullrequired
Returns
23 fields
idstringrequiredlegal_entityobjectrequired2 fields
idstringrequirednamestringrequired
yearintegerrequiredstatus"draft" | "final"requiredheadcountintegerrequireddutyobjectrequiredBy 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
bandstringrequirede.g. "250+", "150-249", "under-100".
minintegerrequiredmaxinteger | nullrequiredevery_yearsinteger | nullrequiredHow often this band reports; null: no duty.
first_dueinteger | nullrequiredThe year the first report of this band is due (7 June).
sourcestringrequiredsource_labelstringrequiredThe law the thresholds come from.
enactedbooleanrequirednotestring | nullrequiredWhat else matters under that law (English), e.g. a different report period or who prepares the report.
due_bystring | nullrequiredWhen a report on this year is due (7 June of the next year); null when this band reports no such year.
flaggedintegerrequiredCategories with a mean gap of 5% or more.
unjustifiedintegerrequiredFlagged categories with no justification yet.
assessment_dueintegerrequiredinputs_countintegerrequiredcreated_atstringrequiredupdated_atstringrequiredfinalised_atstring | nullrequiredsubmitted_onstring | nullrequiredcurrencystring | nullrequiredpopulationintegerrequiredexcludedobjectrequiredPeople 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_payintegerrequiredother_currencyintegerrequired
indicatorsobjectrequired13 fields
womenintegerrequiredmenintegerrequirednot_includedintegerrequiredIncluded in pay but recorded as another, undisclosed or not recorded: counted, not compared.
mean_gapnumber | nullrequiredMean 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 | nullrequiredMedian gap on gross hourly pay (Art. 9(1)(c)).
annual_mean_gapnumber | nullrequiredannual_median_gapnumber | nullrequiredvariable_mean_gapnumber | nullrequiredMean gap in variable components among all workers of each sex (Art. 9(1)(b)); null without variable pay.
variable_median_gapnumber | nullrequiredwomen_receiving_variable_pctnumber | nullrequiredmen_receiving_variable_pctnumber | nullrequiredquartilesobject[]requiredFour groups by hourly pay, lowest first (Art. 9(1)(f)); n mod 4 extra people go to the first groups.
6 fields
quartileintegerrequiredpeopleintegerrequiredwomenintegerrequiredmenintegerrequiredwomen_pctnumber | nullrequiredmen_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"requiredtotalnumberrequiredwomen_receiving_pctnumber | nullrequiredmen_receiving_pctnumber | nullrequiredmean_gapnumber | nullrequiredmedian_gapnumber | nullrequired
categoriesobject[]required15 fields
idstringrequirednamestringrequiredwomenintegerrequiredmenintegerrequirednot_includedintegerrequiredbase_mean_gapnumber | nullrequiredbase_median_gapnumber | nullrequiredvariable_mean_gapnumber | nullrequiredvariable_median_gapnumber | nullrequiredtotal_mean_gapnumber | nullrequiredtotal_median_gapnumber | nullrequiredflaggedbooleanrequired|total_mean_gap| ≥ 5%: needs a justification by objective, gender-neutral factors or a remedy (Art. 10).
small_groupbooleanrequiredFewer 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_duebooleanrequiredFinal 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 | nullrequired6 fields
reasonstringrequiredobjective_factorsstring[]requiredremedystring | nullrequiredremedy_bystring | nullrequiredupdated_bystringrequiredupdated_atstringrequired
uncategorisedintegerrequiredIncluded people whose job title is in no pay category.
variable_sourcesobject | nullrequiredWhere the variable pay came from (totals only); null on reports made before it was read from Bizisy.
4 fields
payrollobjectrequired4 fields
onbooleanrequiredPayroll is on: its pay items in money count.
itemsobject[]required6 fields
idstringrequirednamestringrequiredcomponent"bonus" | "allowances" | "not_pay"requiredchangedbooleanrequiredHR changed it from the default.
totalnumber | nullrequirednull when fewer than min_group people received it (it would show their pay).
peopleintegerrequired
not_in_moneyintegerrequiredEarnings in hours or days: not counted (no amount).
other_currencyintegerrequiredAmounts in another currency than the report's: not counted.
benefitsobjectrequired4 fields
onbooleanrequiredin_kindnumber | nullrequiredallowancesnumber | nullrequiredCash meal allowances. Both null when fewer than min_group people received benefits.
peopleintegerrequired
fileobjectrequired2 fields
peopleintegerrequiredcolumns"bonus" | "allowances" | "in_kind"[]requiredFor these columns, the file's amount replaces Bizisy's for the people in it.
bonusesobjectBonus plans' awards paid by hand (awards paid through Payroll are its Bonus items).
3 fields
onbooleanrequiredtotalnumber | nullrequirednull when fewer than min_group people received one.
peopleintegerrequired
finalised_bystring | nullrequiredfollow_upobjectrequired3 fields
remedy_window_endsstring | nullrequiredSix months after finalising (Art. 10(1)(c)): gaps not justified or remedied by then call for a joint pay assessment.
assessment_within_daysinteger | nullrequiredDays to carry out a joint pay assessment once due, when the entity's national law sets it; null otherwise.
authoritystring | nullrequiredWho receives the report, when national law names it; null otherwise.
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/org/pay_reports.mark_submitted', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"report_id": "pr1",
"on": "2026-03-01"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_reports.mark_submitted",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"report_id": "pr1",
"on": "2026-03-01",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_removeon HR Assistant- Preview
?dry_run=trueruns 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 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"}'const res = await fetch('https://api.bizisy.com/v1/org/pay_reports.remove', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"report_id": "pr1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_reports.remove",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"report_id": "pr1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_exporton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
report_idstringrequiredformat"csv"Default
"csv".delimiter"," | ";"Default
",".
Returns
filenamestringrequiredcsvstringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
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":";"}'const res = await fetch('https://api.bizisy.com/v1/org/pay_reports.export', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"report_id": "pr1",
"format": "csv",
"delimiter": ";"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_reports.export",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"report_id": "pr1",
"format": "csv",
"delimiter": ";",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
status"open" | "answered" | "all"Default
"open".
Returns
itemsobject[]required13 fields
idstringrequiredcreated_atstringrequireddue_onstringrequiredThe answer is due by this day (two months after the request).
status"answered" | "open"requiredanswered: the averages were given at once, or HR replied in writing; open: HR still has to reply.
answerobjectrequired6 fields
as_ofstringrequiredcategoryobject | nullrequiredYour category of workers: people doing the same work or work of equal value.
2 fields
idstringrequirednamestringrequired
ownobject | nullrequiredYour 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
annualnumberrequiredhourlynumberrequiredcurrencystringrequired
womenobject | nullrequiredWomen in your category that day, not counting you, paid in your currency. Null when withheld.
3 fields
countintegerrequiredannual_meannumberrequiredAverage gross annual pay (pay in force that day, annualised).
hourly_meannumberrequiredAverage gross hourly pay.
menobject | nullrequired3 fields
countintegerrequiredannual_meannumberrequiredAverage gross annual pay (pay in force that day, annualised).
hourly_meannumberrequiredAverage gross hourly pay.
withheld"small_group" | "recent_change" | "category_review" | "no_category" | "no_pay"requiredWhy 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 | nullrequiredHR's written answer.
answered_atstring | nullrequiredpersonobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
overduebooleanrequiredOpen past its due date.
receivedstring | nullrequiredRecorded by HR for a request received outside Bizisy: how it came (null: asked in Bizisy or no note).
recordedbooleanrequiredRecorded by HR (
org_pay_requests_record) rather than asked by the person in Bizisy.asked_12mintegerrequiredHow many requests this person made in the last 12 months.
frequentbooleanrequiredMore 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.
openintegerrequiredoverdueintegerrequiredtotalintegerrequiredRequests 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 https://api.bizisy.com/v1/org/pay_requests.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status":"all"}'const res = await fetch('https://api.bizisy.com/v1/org/pay_requests.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"status": "all"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_requests.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"status": "all",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_replyon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
idstringrequiredtextstringrequired10–5000 characters.
Returns
13 fields
idstringrequiredcreated_atstringrequireddue_onstringrequiredThe answer is due by this day (two months after the request).
status"answered" | "open"requiredanswered: the averages were given at once, or HR replied in writing; open: HR still has to reply.
answerobjectrequired6 fields
as_ofstringrequiredcategoryobject | nullrequiredYour category of workers: people doing the same work or work of equal value.
2 fields
idstringrequirednamestringrequired
ownobject | nullrequiredYour 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
annualnumberrequiredhourlynumberrequiredcurrencystringrequired
womenobject | nullrequiredWomen in your category that day, not counting you, paid in your currency. Null when withheld.
3 fields
countintegerrequiredannual_meannumberrequiredAverage gross annual pay (pay in force that day, annualised).
hourly_meannumberrequiredAverage gross hourly pay.
menobject | nullrequired3 fields
countintegerrequiredannual_meannumberrequiredAverage gross annual pay (pay in force that day, annualised).
hourly_meannumberrequiredAverage gross hourly pay.
withheld"small_group" | "recent_change" | "category_review" | "no_category" | "no_pay"requiredWhy 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 | nullrequiredHR's written answer.
answered_atstring | nullrequiredpersonobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
overduebooleanrequiredOpen past its due date.
receivedstring | nullrequiredRecorded by HR for a request received outside Bizisy: how it came (null: asked in Bizisy or no note).
recordedbooleanrequiredRecorded by HR (
org_pay_requests_record) rather than asked by the person in Bizisy.asked_12mintegerrequiredHow many requests this person made in the last 12 months.
frequentbooleanrequiredMore 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 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."
}'const res = await fetch('https://api.bizisy.com/v1/org/pay_requests.reply', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"id": "rq2",
"text": "Your category has too few people to share averages without revealing a colleague's pay."
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_requests.reply",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"id": "rq2",
"text": "Your category has too few people to share averages without revealing a colleague's pay.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_recordon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
person_idstringrequiredreceived_onstringrequirednotestring | nullUp to 200 characters.
Returns
13 fields
idstringrequiredcreated_atstringrequireddue_onstringrequiredThe answer is due by this day (two months after the request).
status"answered" | "open"requiredanswered: the averages were given at once, or HR replied in writing; open: HR still has to reply.
answerobjectrequired6 fields
as_ofstringrequiredcategoryobject | nullrequiredYour category of workers: people doing the same work or work of equal value.
2 fields
idstringrequirednamestringrequired
ownobject | nullrequiredYour 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
annualnumberrequiredhourlynumberrequiredcurrencystringrequired
womenobject | nullrequiredWomen in your category that day, not counting you, paid in your currency. Null when withheld.
3 fields
countintegerrequiredannual_meannumberrequiredAverage gross annual pay (pay in force that day, annualised).
hourly_meannumberrequiredAverage gross hourly pay.
menobject | nullrequired3 fields
countintegerrequiredannual_meannumberrequiredAverage gross annual pay (pay in force that day, annualised).
hourly_meannumberrequiredAverage gross hourly pay.
withheld"small_group" | "recent_change" | "category_review" | "no_category" | "no_pay"requiredWhy 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 | nullrequiredHR's written answer.
answered_atstring | nullrequiredpersonobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
overduebooleanrequiredOpen past its due date.
receivedstring | nullrequiredRecorded by HR for a request received outside Bizisy: how it came (null: asked in Bizisy or no note).
recordedbooleanrequiredRecorded by HR (
org_pay_requests_record) rather than asked by the person in Bizisy.asked_12mintegerrequiredHow many requests this person made in the last 12 months.
frequentbooleanrequiredMore 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 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"
}'const res = await fetch('https://api.bizisy.com/v1/org/pay_requests.record', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p1",
"received_on": "2026-10-01",
"note": "Letter handed to HR"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_requests.record",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p1",
"received_on": "2026-10-01",
"note": "Letter handed to HR",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_statuson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
8 fields
yearintegerrequiredmonthintegerrequiredThe reminder month, 1–12.
startedbooleanrequiredset_upbooleanrequiredAt least one pay category exists (no reminder before: nothing could be answered).
employedintegerrequiredremindedintegerrequiredemailedintegerrequiredwithout_loginobjectrequired2 fields
countintegerrequiredidsstring[]required
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/pay_equity.reminder_status \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/pay_equity.reminder_status', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/pay_equity.reminder_status",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"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.