API reference
Payroll
Pay periods per legal entity and their change sets (hires, leavers, changes, pay, variable pay), locking, exports for the payroll provider (Excel, CSV, JSON, DATEV LODAS, BrightPay), payslips, net pay and the SEPA salary file. Bizisy prepares payroll; it never calculates or files it.
22 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
Payroll overview#
POST/v1/payroll/overviewRead
Payroll at a glance (Bizisy prepares payroll; it never calculates or files it): the legal entities and the pay frequencies each may use (monthly everywhere; fortnightly and weekly in Great Britain and Ireland), each pay schedule, the current pay period of each entity (open, ended, locked, exported or acknowledged), the locked history, the export formats (the country's own first), the payslip rules per country and what needs attention. Read a period with payroll_periods_get. Owners, admins, HR and roles with Payroll. Part of the Payroll 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
payroll_overviewon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
8 fields
entitiesobject[]required4 fields
idstringrequiredlegal_namestringrequiredcountrystringrequiredfrequencies"monthly" | "fortnightly" | "weekly"[]required
schedulesobject[]required7 fields
legal_entity_idstringrequiredfrequency"monthly" | "fortnightly" | "weekly"requiredfirst_startstringrequiredpay_dayinteger | nullrequireddebtorobject | nullrequired3 fields
namestringrequiredibanstringrequiredbicstring | nullrequired
datevobject | nullrequired2 fields
berater_nrstringrequiredmandanten_nrstringrequired
updated_atstringrequired
currentobject[]required9 fields
idstringrequiredlegal_entityobjectrequired3 fields
idstringrequiredlegal_namestringrequiredcountrystringrequired
frequency"monthly" | "fortnightly" | "weekly"requiredstartstringrequiredendstringrequiredstatus"open" | "ended" | "locked" | "exported" | "acknowledged"requiredopen: running; ended: its last day passed and it is not locked; locked; exported (at least one export); acknowledged (by the accountant).
locked_atstring | nullrequiredacknowledged_atstring | nullrequiredexportsintegerrequired
historyobject[]required9 fields
idstringrequiredlegal_entityobjectrequired3 fields
idstringrequiredlegal_namestringrequiredcountrystringrequired
frequency"monthly" | "fortnightly" | "weekly"requiredstartstringrequiredendstringrequiredstatus"open" | "ended" | "locked" | "exported" | "acknowledged"requiredopen: running; ended: its last day passed and it is not locked; locked; exported (at least one export); acknowledged (by the accountant).
locked_atstring | nullrequiredacknowledged_atstring | nullrequiredexportsintegerrequired
formatsobject[]required4 fields
idstringrequirednamestringrequireddescriptionstringrequiredcountriesstring[]required
payslip_rulesobject[]required4 fields
countrystringrequireddelivery"electronic" | "opt_out"requiredretentionstring | nullrequiredsourcestringrequired
unmatched_payslipsintegerrequiredcanobjectrequired2 fields
managebooleanrequiredconsentbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/payroll/overview \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/payroll/overview', {
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/payroll/overview",
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": {
"entities": [
{
"id": "e1",
"legal_name": "Acme Lda",
"country": "PT",
"frequencies": [
"monthly"
]
}
],
"schedules": [
{
"legal_entity_id": "e1",
"frequency": "monthly",
"first_start": "2026-03-01",
"pay_day": 28,
"debtor": {
"name": "Acme Lda",
"iban": "PT50000201231234567890154",
"bic": "CGDIPTPL"
},
"datev": null,
"updated_at": "2026-03-02T09:00:00.000Z"
}
],
"current": [
{
"id": "e1:2026-03-01",
"legal_entity": {
"id": "e1",
"legal_name": "Acme Lda",
"country": "PT"
},
"frequency": "monthly",
"start": "2026-03-01",
"end": "2026-03-31",
"status": "ended",
"locked_at": null,
"acknowledged_at": null,
"exports": 0
}
],
"history": [
{
"id": "e1:2026-02-01",
"legal_entity": {
"id": "e1",
"legal_name": "Acme Lda",
"country": "PT"
},
"frequency": "monthly",
"start": "2026-02-01",
"end": "2026-02-28",
"status": "acknowledged",
"locked_at": "2026-04-02T09:00:00.000Z",
"acknowledged_at": "2026-03-03T10:00:00.000Z",
"exports": 1
}
],
"formats": [
{
"id": "xlsx",
"name": "Excel workbook",
"description": "Every section on its own sheet.",
"countries": []
}
],
"payslip_rules": [
{
"country": "PT",
"delivery": "electronic",
"retention": null,
"source": "EU default."
}
],
"unmatched_payslips": 0,
"can": {
"manage": true,
"consent": true
}
}
}Set a pay schedule#
POST/v1/payroll/schedules.setWrite
Sets how a legal entity is paid: frequency (monthly; fortnightly or weekly only for entities in Great Britain or Ireland), first_start (the first period's first day; the 1st of a month for monthly) and pay_day (day of the month money arrives, optional). Also the company's bank account for the SEPA salary file (debtor: name, IBAN checked by its checksum, BIC optional) and the DATEV adviser and client numbers for the LODAS file. Frequency and first_start can't change once a period is locked. Owners, admins, HR and roles with Payroll at Edit, in the app only. Part of the Payroll 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 schedules and the bank account are set in the app only.
- MCP tool
payroll_schedules_seton HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
legal_entity_idstringrequiredfrequency"monthly" | "fortnightly" | "weekly"Default
"monthly".first_startstringrequiredPattern
^\d{4}-\d{2}-\d{2}$.pay_dayinteger | nullFrom 1 to 31.
debtorobject | null3 fields
namestringrequired1–70 characters.
ibanstringrequired5–40 characters.
bicstring | nullUp to 11 characters.
datevobject | null2 fields
berater_nrstringrequiredPattern
^\d{4,7}$.mandanten_nrstringrequiredPattern
^\d{1,5}$.
Returns
7 fields
legal_entity_idstringrequiredfrequency"monthly" | "fortnightly" | "weekly"requiredfirst_startstringrequiredpay_dayinteger | nullrequireddebtorobject | nullrequired3 fields
namestringrequiredibanstringrequiredbicstring | nullrequired
datevobject | nullrequired2 fields
berater_nrstringrequiredmandanten_nrstringrequired
updated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/payroll/schedules.set \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"legal_entity_id": "e2",
"frequency": "fortnightly",
"first_start": "2026-03-02",
"pay_day": null,
"debtor": {
"name": "Acme UK Ltd",
"bic": "WESTGB2L"
},
"datev": null
}'const res = await fetch('https://api.bizisy.com/v1/payroll/schedules.set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"legal_entity_id": "e2",
"frequency": "fortnightly",
"first_start": "2026-03-02",
"pay_day": null,
"debtor": {
"name": "Acme UK Ltd",
"bic": "WESTGB2L"
},
"datev": null
}),
});
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/payroll/schedules.set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"legal_entity_id": "e2",
"frequency": "fortnightly",
"first_start": "2026-03-02",
"pay_day": None,
"debtor": {
"name": "Acme UK Ltd",
"bic": "WESTGB2L",
},
"datev": None,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"legal_entity_id": "e1",
"frequency": "fortnightly",
"first_start": "2026-03-02",
"pay_day": null,
"debtor": {
"name": "Acme Lda",
"iban": "PT50000201231234567890154",
"bic": "CGDIPTPL"
},
"datev": null,
"updated_at": "2026-03-02T09:00:00.000Z"
}
}List pay items#
POST/v1/payroll/catalogue.listRead
The company's pay item catalogue: variable pay HR adds per period (bonus, overtime, commission, meal allowance, advance…) with kind (earning or deduction), unit (amount, hours or days) and a code per export target (DATEV wage type, BrightPay description). Archived items stay on earlier periods. Owners, admins, HR and roles with Payroll. Part of the Payroll 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
payroll_catalogue_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
itemsobject[]required6 fields
idstringrequirednamestringrequiredkind"earning" | "deduction"requiredunit"amount" | "hours" | "days"requiredcodesobjectrequiredarchivedbooleanrequired
maxintegerrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/payroll/catalogue.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/payroll/catalogue.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/payroll/catalogue.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": "Bonus",
"kind": "earning",
"unit": "amount",
"codes": {
"datev": "200",
"brightpay": "Bonus"
},
"archived": false
}
],
"max": 100
}
}Add a pay item#
POST/v1/payroll/catalogue.addWrite
Adds a pay item to the catalogue: name (unique), kind (earning or deduction), unit (amount, hours or days) and codes per export target (pt_ru: the Relatório Único Anexo A column it counts in — sub_ref meal allowance, sub_turn shift allowance, out_sub other regular allowances, prest_ir irregular pay, r_supl overtime pay, horas_supl overtime hours). At most 100 items. Owners, admins, HR and roles with Payroll at Edit. Part of the Payroll 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
- MCP tool
payroll_catalogue_addon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
namestringrequired1–60 characters.
kind"earning" | "deduction"Default
"earning".unit"amount" | "hours" | "days"Default
"amount".codesobjectCodes per export target: datev (Lohnart, 1–4 digits), datev_bs (Bearbeitungsschlüssel; default 1 hours, 2 amount, 10 days), brightpay (the description BrightPay knows the item by), generic, staffology (Staffology pay code), xero_payroll (Xero earnings rate id, hours), silae (Silae variable element code), lexware (Lohnartnummer, 1–4 digits), sage50 (Sage 50 Payroll payment or deduction reference), meta4 (the Meta4 concept code; edited with the Meta4 codes).
Default
{}.11 fields
datevstringrequiredUp to 40 characters.
datev_bsstringrequiredUp to 40 characters.
brightpaystringrequiredUp to 40 characters.
genericstringrequiredUp to 40 characters.
staffologystringrequiredUp to 40 characters.
xero_payrollstringrequiredUp to 40 characters.
silaestringrequiredUp to 40 characters.
lexwarestringrequiredUp to 40 characters.
sage50stringrequiredUp to 40 characters.
pt_rustringrequiredUp to 40 characters.
meta4stringrequiredUp to 40 characters.
Returns
idstringrequirednamestringrequiredkind"earning" | "deduction"requiredunit"amount" | "hours" | "days"requiredcodesobjectrequiredarchivedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/payroll/catalogue.add \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Overtime",
"kind": "earning",
"unit": "hours",
"codes": {
"datev": "1100",
"brightpay": "Overtime"
}
}'const res = await fetch('https://api.bizisy.com/v1/payroll/catalogue.add', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"name": "Overtime",
"kind": "earning",
"unit": "hours",
"codes": {
"datev": "1100",
"brightpay": "Overtime"
}
}),
});
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/payroll/catalogue.add",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "Overtime",
"kind": "earning",
"unit": "hours",
"codes": {
"datev": "1100",
"brightpay": "Overtime",
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "c1",
"name": "Overtime",
"kind": "earning",
"unit": "hours",
"codes": {
"datev": "200",
"brightpay": "Bonus"
},
"archived": false
}
}Change a pay item#
POST/v1/payroll/catalogue.updateWrite
Changes a pay item: name, kind, unit, codes (replaced whole) or archived (archived items cannot be added to new periods; earlier periods keep them). Owners, admins, HR and roles with Payroll at Edit. Part of the Payroll 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
- MCP tool
payroll_catalogue_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
idstringrequirednamestring1–60 characters.
kind"earning" | "deduction"unit"amount" | "hours" | "days"codesobjectCodes per export target: datev (Lohnart, 1–4 digits), datev_bs (Bearbeitungsschlüssel; default 1 hours, 2 amount, 10 days), brightpay (the description BrightPay knows the item by), generic, staffology (Staffology pay code), xero_payroll (Xero earnings rate id, hours), silae (Silae variable element code), lexware (Lohnartnummer, 1–4 digits), sage50 (Sage 50 Payroll payment or deduction reference), meta4 (the Meta4 concept code; edited with the Meta4 codes).
11 fields
datevstringrequiredUp to 40 characters.
datev_bsstringrequiredUp to 40 characters.
brightpaystringrequiredUp to 40 characters.
genericstringrequiredUp to 40 characters.
staffologystringrequiredUp to 40 characters.
xero_payrollstringrequiredUp to 40 characters.
silaestringrequiredUp to 40 characters.
lexwarestringrequiredUp to 40 characters.
sage50stringrequiredUp to 40 characters.
pt_rustringrequiredUp to 40 characters.
meta4stringrequiredUp to 40 characters.
archivedboolean
Returns
idstringrequirednamestringrequiredkind"earning" | "deduction"requiredunit"amount" | "hours" | "days"requiredcodesobjectrequiredarchivedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/payroll/catalogue.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"id":"c1","name":"Annual bonus","codes":{"datev":"201"}}'const res = await fetch('https://api.bizisy.com/v1/payroll/catalogue.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"id": "c1",
"name": "Annual bonus",
"codes": {
"datev": "201"
}
}),
});
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/payroll/catalogue.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"id": "c1",
"name": "Annual bonus",
"codes": {
"datev": "201",
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "c1",
"name": "Annual bonus",
"kind": "earning",
"unit": "amount",
"codes": {
"datev": "200",
"brightpay": "Bonus"
},
"archived": true
}
}Set an employee number#
POST/v1/payroll/people.set_numberWrite
Sets or clears a person's employee number (personnel number) for payroll providers: unique in the company, 1–20 letters, digits, dots, dashes or slashes (DATEV needs 1–5 digits). Owners, admins, HR and roles with Payroll at Edit, for the people they cover. Part of the Payroll 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
- MCP tool
payroll_people_set_numberon 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_idstringrequiredemployee_numberstring | nullrequired1–20 characters. Pattern
^[A-Za-z0-9._\-/]+$.
Returns
person_idstringrequiredemployee_numberstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/payroll/people.set_number \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"person_id":"p2","employee_number":"1002"}'const res = await fetch('https://api.bizisy.com/v1/payroll/people.set_number', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p2",
"employee_number": "1002"
}),
});
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/payroll/people.set_number",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p2",
"employee_number": "1002",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person_id": "p2",
"employee_number": "1002"
}
}Number everyone without an employee number#
POST/v1/payroll/people.assign_numbersWrite
Gives every person of the current pay periods who has no employee number the next unused number (after the highest numeric one, from 1001). Owners, admins, HR and roles with Payroll at Edit that cover everyone. Part of the Payroll 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
- MCP tool
payroll_people_assign_numberson HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
No input: send {}.
Returns
assignedintegerrequiredpeopleobject[]required2 fields
person_idstringrequiredemployee_numberstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/payroll/people.assign_numbers \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/payroll/people.assign_numbers', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
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, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/payroll/people.assign_numbers",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"assigned": 1,
"people": [
{
"person_id": "p2",
"employee_number": "1002"
}
]
}
}Read a pay period#
POST/v1/payroll/periods.getRead
A pay period with its change set: people (master data, job, contract and pay at the period's end), entries by section (hire, leaver, job_change, pay_change, personal_change, late: each with effective_date and before → after per field), variable pay items, warnings (missing or invalid IBAN, tax id, social security number, employee number, contract data, pay), notes, comments, attachments, exports (format, SHA-256, who, when), payslips and net pay. An open period is live (it follows the data); a locked one is frozen. Custom roles see the people they cover; API keys and AI apps get pay and private values only with a consent (Payroll → Settings → Machine access), else they are null and listed in withheld. Owners, admins, HR and roles with Payroll. Part of the Payroll 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
- Keys and apps
- Pay and private values only with a consent (Payroll → Settings → Machine access); otherwise null and listed in withheld.
- MCP tool
payroll_periods_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
period_idstringrequiredA period id from payroll_overview or payroll_periods_get: "<legal entity id>:<start date>".
12–120 characters.
Returns
14 fields
periodobjectrequired9 fields
idstringrequiredlegal_entityobjectrequired3 fields
idstringrequiredlegal_namestringrequiredcountrystringrequired
frequency"monthly" | "fortnightly" | "weekly"requiredstartstringrequiredendstringrequiredstatus"open" | "ended" | "locked" | "exported" | "acknowledged"requiredopen: running; ended: its last day passed and it is not locked; locked; exported (at least one export); acknowledged (by the accountant).
locked_atstring | nullrequiredacknowledged_atstring | nullrequiredexportsintegerrequired
previous_idstring | nullrequiredcountrystringrequiredentity_namesobjectrequiredLegal entity names by id (moves between entities).
change_setobjectrequired8 fields
first_exportbooleanrequiredThe entity's first period: everyone's details are listed for the payroll provider to set up.
peopleobject[]required23 fields
idstringrequirednamestringrequiredgiven_namestringrequiredfamily_namestringrequiredemployee_numberstring | nullrequiredbirthdaystring | nullrequiredaddressstring | nullrequiredaddress_countrystring | nullrequiredtax_idstring | nullrequiredsocial_security_numberstring | nullrequiredibanstring | nullrequiredstart_datestring | nullrequiredend_datestring | nullrequiredtitlestring | nullrequiredunitstring | nullrequiredlocationstring | nullrequiredemployment_typestring | nullrequiredftenumber | nullrequiredcontract_typestring | nullrequiredweekly_hoursnumber | nullrequiredpayobject | nullrequired3 fields
amountnumberrequiredcurrencystringrequiredperiodstringrequired
paper_payslipsbooleanrequiredin_periodbooleanrequired
entriesobject[]required7 fields
idstringrequiredsection"hire" | "leaver" | "job_change" | "pay_change" | "personal_change" | "late"requiredperson_idstringrequiredeffective_datestring | nullrequiredkind"hire" | "leaver" | "job_change" | "pay_change"requiredLate corrections: what came late.
changesobject[]requiredbefore → after per field; pay as "2400.00 EUR/month".
3 fields
fieldstringrequiredbeforestring | number | "null"requiredafterstring | number | "null"required
late_ofstring | nullrequiredLate corrections: the locked period they belong to.
itemsobject[]required11 fields
idstringrequiredperson_idstringrequiredcatalogue_idstringrequirednamestringrequiredkind"earning" | "deduction"requiredunit"amount" | "hours" | "days"requiredvaluenumberrequiredcurrencystring | nullrequirednotestring | nullrequiredcodesobjectrequiredsource"hr" | "import" | "referral" | "benefit" | "comp"requiredbenefit: from the benefits module (read-only here; changed in Benefits). comp: a salary review lump sum.
warningsobject[]required3 fields
codestring (enum)requiredOne of:
missing_iban,invalid_iban,missing_tax_id,invalid_tax_id,missing_ssn,invalid_ssn,missing_employee_number,missing_contract_type,missing_weekly_hours,missing_pay,missing_address,missing_birthday.person_idstringrequiredmessagestringrequired
absencesobject[]Only when the company uses Time off: approved time off inside the period (days counted inside it). Absent otherwise.
8 fields
idstringrequiredThe time off booking.
person_idstringrequiredtype_namestring | nullrequiredThe leave type; null for health leave when the caller has no consent for private data.
paidbooleanrequiredhealthbooleanrequiredHealth leave (e.g. sick leave): special-category data.
fromstringrequiredtostringrequiredClipped to the period.
daysnumberrequiredWorking days inside the period (half-day precision).
untakenobject[]Only when the company uses Time off: leavers' leave balance at their last day (positive: days owed; negative: taken in advance).
3 fields
person_idstringrequiredlast_daystringrequireddaysnumberrequired
withheld"pay" | "private"[]requiredValues left out for this caller: API keys and AI apps get pay and private values only with a consent (Payroll → Settings → Machine access).
notesobject[]required3 fields
person_idstring | nullrequiredtextstringrequiredupdated_atstringrequired
commentsobject[]required5 fields
idstringrequiredauthorstringrequiredminebooleanrequiredtextstringrequiredcreated_atstringrequired
attachmentsobject[]required5 fields
idstringrequirednamestringrequiredsizeintegerrequiredcontent_typestringrequiredcreated_atstringrequired
exportsobject[]required7 fields
idstringrequiredformatstringrequiredfilesobject[]required4 fields
namestringrequiredcontent_typestringrequiredsha256stringrequiredbytesintegerrequired
peopleintegerrequiredskippedintegerrequiredcreated_bystringrequiredcreated_atstringrequired
payslipsobject[]required8 fields
idstringrequirednamestringrequiredsizeintegerrequiredperson_idstring | nullrequiredperson_namestring | nullrequiredmatched_by"tax_id" | "employee_number" | "name" | "manual"requiredstatus"uploading" | "unmatched" | "published"requiredcreated_atstringrequired
net_payobject[]required3 fields
person_idstringrequiredamountnumber | nullrequiredcurrencystringrequired
catalogueobject[]required6 fields
idstringrequirednamestringrequiredkind"earning" | "deduction"requiredunit"amount" | "hours" | "days"requiredcodesobjectrequiredarchivedbooleanrequired
pay_dayinteger | nullrequireddebtor_setbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/payroll/periods.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"period_id":"e1:2026-03-01"}'const res = await fetch('https://api.bizisy.com/v1/payroll/periods.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"period_id": "e1: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
import requests
res = requests.post(
"https://api.bizisy.com/v1/payroll/periods.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"period_id": "e1:2026-03-01",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"period": {
"id": "e1:2026-03-01",
"legal_entity": {
"id": "e1",
"legal_name": "Acme Lda",
"country": "PT"
},
"frequency": "monthly",
"start": "2026-03-01",
"end": "2026-03-31",
"status": "locked",
"locked_at": "2026-04-02T09:00:00.000Z",
"acknowledged_at": null,
"exports": 0
},
"previous_id": "e1:2026-02-01",
"country": "PT",
"entity_names": {
"e1": "Acme Lda"
},
"change_set": {
"first_export": false,
"people": [
{
"id": "p2",
"name": "Bruno Costa",
"given_name": "Bruno",
"family_name": "Costa",
"employee_number": "1002",
"birthday": "1991-02-03",
"address": "Rua das Flores 1, 1000-001 Lisboa, PT",
"address_country": "PT",
"tax_id": "123456789",
"social_security_number": "12345678901",
"iban": "PT50000201231234567890154",
"start_date": "2026-03-10",
"end_date": null,
"title": "Engineer",
"unit": "Platform",
"location": "Lisbon",
"employment_type": "full_time",
"fte": 1,
"contract_type": "permanent",
"weekly_hours": 40,
"pay": {
"amount": 2400,
"currency": "EUR",
"period": "month"
},
"paper_payslips": false,
"in_period": true
}
],
"entries": [
{
"id": "hire:p2:j2",
"section": "hire",
"person_id": "p2",
"effective_date": "2026-03-10",
"kind": null,
"changes": [
{
"field": "start_date",
"before": null,
"after": "2026-03-10"
},
{
"field": "pay",
"before": null,
"after": "2400.00 EUR/month"
}
],
"late_of": null
}
],
"items": [
{
"id": "i1",
"person_id": "p2",
"catalogue_id": "c1",
"name": "Bonus",
"kind": "earning",
"unit": "amount",
"value": 500,
"currency": "EUR",
"note": "Signing bonus",
"codes": {
"datev": "200"
},
"source": "hr"
}
],
"warnings": [
{
"code": "missing_employee_number",
"person_id": "p2",
"message": "No employee number."
}
],
"withheld": []
},
"notes": [
{
"person_id": null,
"text": "Bonuses approved by the board on 20 March.",
"updated_at": "2026-03-28T10:00:00.000Z"
}
],
"comments": [
{
"id": "cm1",
"author": "Carla Contabilista",
"mine": false,
"text": "Received, running it on Monday.",
"created_at": "2026-04-02T11:00:00.000Z"
}
],
"attachments": [
{
"id": "at1",
"name": "overtime-march.pdf",
"size": 20000,
"content_type": "application/pdf",
"created_at": "2026-03-30T10:00:00.000Z"
}
],
"exports": [
{
"id": "x1",
"format": "xlsx",
"files": [
{
"name": "payroll_Acme-Lda_2026-03-01_2026-03-31.xlsx",
"content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"bytes": 6120
}
],
"people": 12,
"skipped": 0,
"created_by": "u1",
"created_at": "2026-04-02T10:00:00.000Z"
}
],
"payslips": [
{
"id": "s1",
"name": "payslips-march.pdf (page 1)",
"size": 48211,
"person_id": "p2",
"person_name": "Bruno Costa",
"matched_by": "tax_id",
"status": "published",
"created_at": "2026-04-03T10:00:00.000Z"
}
],
"net_pay": [
{
"person_id": "p2",
"amount": 1830.4,
"currency": "EUR"
}
],
"catalogue": [
{
"id": "c1",
"name": "Bonus",
"kind": "earning",
"unit": "amount",
"codes": {
"datev": "200",
"brightpay": "Bonus"
},
"archived": false
}
],
"pay_day": 28,
"debtor_set": true
}
}Lock a pay period#
POST/v1/payroll/periods.lockWrite
Locks the current pay period of a legal entity: its change set is frozen for export, and anything recorded later that takes effect within it goes into the next period as a late correction. Warnings do not stop a lock (the result counts them); read them first with payroll_periods_get. Preview with dry_run. Emits payroll.period.locked. Owners, admins, HR and roles with Payroll at Edit that cover everyone in the period. Part of the Payroll 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
- MCP tool
payroll_periods_lockon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
period_idstringrequiredA period id from payroll_overview or payroll_periods_get: "<legal entity id>:<start date>".
12–120 characters.
Returns
periodobjectrequired9 fields
idstringrequiredlegal_entityobjectrequired3 fields
idstringrequiredlegal_namestringrequiredcountrystringrequired
frequency"monthly" | "fortnightly" | "weekly"requiredstartstringrequiredendstringrequiredstatus"open" | "ended" | "locked" | "exported" | "acknowledged"requiredopen: running; ended: its last day passed and it is not locked; locked; exported (at least one export); acknowledged (by the accountant).
locked_atstring | nullrequiredacknowledged_atstring | nullrequiredexportsintegerrequired
peopleintegerrequiredwarningsintegerrequiredentriesintegerrequireditemsintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/payroll/periods.lock \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"period_id":"e1:2026-03-01"}'const res = await fetch('https://api.bizisy.com/v1/payroll/periods.lock', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"period_id": "e1: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/payroll/periods.lock",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"period_id": "e1:2026-03-01",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"period": {
"id": "e1:2026-03-01",
"legal_entity": {
"id": "e1",
"legal_name": "Acme Lda",
"country": "PT"
},
"frequency": "monthly",
"start": "2026-03-01",
"end": "2026-03-31",
"status": "locked",
"locked_at": "2026-04-02T09:00:00.000Z",
"acknowledged_at": null,
"exports": 0
},
"people": 12,
"warnings": 3,
"entries": 5,
"items": 4
}
}Unlock a pay period#
POST/v1/payroll/periods.unlockWrite
Unlocks the most recently locked period of a legal entity, while nothing was taken from it yet (no export, send to a payroll tool, accountant acknowledgement, payslip or net pay): it is live again. Once something was exported, corrections go into the next period instead. Owners, admins, HR and roles with Payroll at Edit that cover everyone in the period. Part of the Payroll 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
- MCP tool
payroll_periods_unlockon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
period_idstringrequiredA period id from payroll_overview or payroll_periods_get: "<legal entity id>:<start date>".
12–120 characters.
Returns
periodobjectrequired9 fields
idstringrequiredlegal_entityobjectrequired3 fields
idstringrequiredlegal_namestringrequiredcountrystringrequired
frequency"monthly" | "fortnightly" | "weekly"requiredstartstringrequiredendstringrequiredstatus"open" | "ended" | "locked" | "exported" | "acknowledged"requiredopen: running; ended: its last day passed and it is not locked; locked; exported (at least one export); acknowledged (by the accountant).
locked_atstring | nullrequiredacknowledged_atstring | nullrequiredexportsintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/payroll/periods.unlock \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"period_id":"e1:2026-03-01"}'const res = await fetch('https://api.bizisy.com/v1/payroll/periods.unlock', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"period_id": "e1: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/payroll/periods.unlock",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"period_id": "e1:2026-03-01",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"period": {
"id": "e1:2026-03-01",
"legal_entity": {
"id": "e1",
"legal_name": "Acme Lda",
"country": "PT"
},
"frequency": "monthly",
"start": "2026-03-01",
"end": "2026-03-31",
"status": "ended",
"locked_at": null,
"acknowledged_at": null,
"exports": 0
}
}
}Acknowledge a pay period#
POST/v1/payroll/periods.acknowledgeWrite
Confirms a locked period was received (the accountant or payroll bureau says so); HR sees who and when. Owners, admins, HR and roles with Payroll. Part of the Payroll 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
- MCP tool
payroll_periods_acknowledgeon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
period_idstringrequiredA period id from payroll_overview or payroll_periods_get: "<legal entity id>:<start date>".
12–120 characters.
Returns
periodobjectrequired9 fields
idstringrequiredlegal_entityobjectrequired3 fields
idstringrequiredlegal_namestringrequiredcountrystringrequired
frequency"monthly" | "fortnightly" | "weekly"requiredstartstringrequiredendstringrequiredstatus"open" | "ended" | "locked" | "exported" | "acknowledged"requiredopen: running; ended: its last day passed and it is not locked; locked; exported (at least one export); acknowledged (by the accountant).
locked_atstring | nullrequiredacknowledged_atstring | nullrequiredexportsintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/payroll/periods.acknowledge \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"period_id":"e1:2026-03-01"}'const res = await fetch('https://api.bizisy.com/v1/payroll/periods.acknowledge', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"period_id": "e1: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/payroll/periods.acknowledge",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"period_id": "e1:2026-03-01",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"period": {
"id": "e1:2026-03-01",
"legal_entity": {
"id": "e1",
"legal_name": "Acme Lda",
"country": "PT"
},
"frequency": "monthly",
"start": "2026-03-01",
"end": "2026-03-31",
"status": "acknowledged",
"locked_at": "2026-04-02T09:00:00.000Z",
"acknowledged_at": "2026-04-03T10:00:00.000Z",
"exports": 0
}
}
}Add variable pay#
POST/v1/payroll/items.addWrite
Adds a variable pay item for one person in an open period: catalogue_id (payroll_catalogue_list), value (an amount for amount items, else hours or days; at most 2 decimals), currency (amount items; default the person's pay currency, else EUR) and an optional note for the accountant. At most 5000 items per period. Owners, admins, HR and roles with Payroll at Edit, for the people they cover. Part of the Payroll 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
- MCP tool
payroll_items_addon 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
period_idstringrequiredA period id from payroll_overview or payroll_periods_get: "<legal entity id>:<start date>".
12–120 characters.
person_idstringrequiredcatalogue_idstringrequiredvaluenumberrequiredFrom -10000000 to 10000000.
currencystringPattern
^[A-Z]{3}$.notestringUp to 300 characters.
Returns
7 fields
idstringrequiredperiod_idstringrequiredperson_idstringrequiredcatalogue_idstringrequiredvaluenumberrequiredcurrencystring | nullrequirednotestring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/payroll/items.add \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"period_id": "e1:2026-03-01",
"person_id": "p2",
"catalogue_id": "c1",
"value": 500,
"currency": "EUR",
"note": "Signing bonus"
}'const res = await fetch('https://api.bizisy.com/v1/payroll/items.add', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"period_id": "e1:2026-03-01",
"person_id": "p2",
"catalogue_id": "c1",
"value": 500,
"currency": "EUR",
"note": "Signing bonus"
}),
});
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/payroll/items.add",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"period_id": "e1:2026-03-01",
"person_id": "p2",
"catalogue_id": "c1",
"value": 500,
"currency": "EUR",
"note": "Signing bonus",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "i1",
"period_id": "e1:2026-03-01",
"person_id": "p2",
"catalogue_id": "c1",
"value": 500,
"currency": "EUR",
"note": "Signing bonus"
}
}Remove variable pay#
POST/v1/payroll/items.removeDestructive
Removes a variable pay item from an open period. Owners, admins, HR and roles with Payroll at Edit, for the people they cover. Part of the Payroll 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
- MCP tool
payroll_items_removeon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
item_idstringrequired
Returns
idstringrequiredperiod_idstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/payroll/items.remove \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"item_id":"i1"}'const res = await fetch('https://api.bizisy.com/v1/payroll/items.remove', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"item_id": "i1"
}),
});
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/payroll/items.remove",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"item_id": "i1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "i1",
"period_id": "e1:2026-03-01"
}
}Import variable pay#
POST/v1/payroll/items.importWrite
Adds many variable pay items to an open period at once (a CSV read by the app, or rows from your system): each row names the person (person_id, employee_number, tax_id or exact full name), the item (catalogue name or code), value, optional currency and note. All or nothing: any row that can't be matched refuses the whole import with the row numbers (preview with dry_run). An API key or AI app without consent for private data names people by person_id or employee_number only. At most 2000 rows. Owners, admins, HR and roles with Payroll at Edit that cover everyone. Part of the Payroll 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
- Names people by person id or employee number only, unless a consent covers private data.
- MCP tool
payroll_items_importon 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
period_idstringrequiredA period id from payroll_overview or payroll_periods_get: "<legal entity id>:<start date>".
12–120 characters.
rowsobject[]required1–2000 items.
8 fields
person_idstringUp to 64 characters.
employee_numberstringUp to 20 characters.
tax_idstringUp to 40 characters.
namestringUp to 200 characters.
itemstringrequiredThe pay item's name or one of its codes.
1–60 characters.
valuenumberrequiredFrom -10000000 to 10000000.
currencystringPattern
^[A-Z]{3}$.notestringUp to 300 characters.
Returns
period_idstringrequiredaddedintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/payroll/items.import \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"period_id": "e1:2026-03-01",
"rows": [
{
"employee_number": "1002",
"item": "Bonus",
"value": 500
},
{
"name": "Bruno Costa",
"item": "200",
"value": 50,
"note": "Meal allowance"
}
]
}'const res = await fetch('https://api.bizisy.com/v1/payroll/items.import', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"period_id": "e1:2026-03-01",
"rows": [
{
"employee_number": "1002",
"item": "Bonus",
"value": 500
},
{
"name": "Bruno Costa",
"item": "200",
"value": 50,
"note": "Meal allowance"
}
]
}),
});
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/payroll/items.import",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"period_id": "e1:2026-03-01",
"rows": [
{
"employee_number": "1002",
"item": "Bonus",
"value": 500,
},
{
"name": "Bruno Costa",
"item": "200",
"value": 50,
"note": "Meal allowance",
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"period_id": "e1:2026-03-01",
"added": 2
}
}Write a note for the accountant#
POST/v1/payroll/notes.setWrite
Sets the note of an open period for the accountant: for the whole period (person_id null) or one person. Empty text removes it. Notes go into the exports. Owners, admins, HR and roles with Payroll at Edit, for the people they cover. Part of the Payroll 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
- MCP tool
payroll_notes_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
period_idstringrequiredA period id from payroll_overview or payroll_periods_get: "<legal entity id>:<start date>".
12–120 characters.
person_idstring | nullDefault
null.textstringrequiredUp to 2000 characters.
Returns
period_idstringrequiredperson_idstring | nullrequiredtextstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/payroll/notes.set \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"period_id": "e1:2026-03-01",
"person_id": "p2",
"text": "Starts on the 10th."
}'const res = await fetch('https://api.bizisy.com/v1/payroll/notes.set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"period_id": "e1:2026-03-01",
"person_id": "p2",
"text": "Starts on the 10th."
}),
});
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/payroll/notes.set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"period_id": "e1:2026-03-01",
"person_id": "p2",
"text": "Starts on the 10th.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"period_id": "e1:2026-03-01",
"person_id": null,
"text": "Starts on the 10th."
}
}Comment on a pay period#
POST/v1/payroll/comments.addWrite
Adds a comment to a pay period (open or locked): HR and the accountant talk there. At most 500 per period. Owners, admins, HR and roles with Payroll. Part of the Payroll 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
- MCP tool
payroll_comments_addon 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
period_idstringrequiredA period id from payroll_overview or payroll_periods_get: "<legal entity id>:<start date>".
12–120 characters.
textstringrequired1–2000 characters.
Returns
idstringrequiredauthorstringrequiredminebooleanrequiredtextstringrequiredcreated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/payroll/comments.add \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"period_id":"e1:2026-03-01","text":"Received, running it on Monday."}'const res = await fetch('https://api.bizisy.com/v1/payroll/comments.add', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"period_id": "e1:2026-03-01",
"text": "Received, running it on Monday."
}),
});
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/payroll/comments.add",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"period_id": "e1:2026-03-01",
"text": "Received, running it on Monday.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "cm1",
"author": "Carla Contabilista",
"mine": true,
"text": "Received, running it on Monday.",
"created_at": "2026-04-02T11:00:00.000Z"
}
}Export a pay period#
POST/v1/payroll/exports.createWrite
Exports a locked pay period for the payroll provider: format xlsx (every section on its own sheet), csv, json (bizisy.payroll-change-set.v1), datev_lodas (DATEV LODAS ASCII: personnel numbers, names and variable pay with DATEV wage types) brightpay_csv (BrightPay additions and deductions), lexware_lohn (Lexware lohn+gehalt pay data and master data), sage50_csv (Sage 50 Payroll payments and deductions, hours and rates) or silae_csv (Silae variable data). Returns the files (UTF-8 text or base64) and records each file's SHA-256, who and when; skipped lists what a format could not carry. Emits payroll.export.created. Custom roles export the people they cover. API keys and AI apps need a consent for pay and private data (Payroll → Settings → Machine access). Owners, admins, HR and roles with Payroll. Part of the Payroll 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
- Needs a consent for pay and private data (Payroll → Settings → Machine access).
- MCP tool
payroll_exports_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
period_idstringrequiredA period id from payroll_overview or payroll_periods_get: "<legal entity id>:<start date>".
12–120 characters.
formatstring (enum)requiredmeta4: the file Meta4 loads with its bulk-load template, with the company's Meta4 codes.
One of:
xlsx,csv,json,datev_lodas,brightpay_csv,lexware_lohn,sage50_csv,silae_csv,meta4.
Returns
exportobjectrequired7 fields
idstringrequiredformatstringrequiredfilesobject[]required4 fields
namestringrequiredcontent_typestringrequiredsha256stringrequiredbytesintegerrequired
peopleintegerrequiredskippedintegerrequiredcreated_bystringrequiredcreated_atstringrequired
filesobject[]required6 fields
namestringrequiredcontent_typestringrequiredsha256stringrequiredbytesintegerrequiredencoding"utf8" | "base64"requiredcontentstringrequiredThe file: UTF-8 text, or base64 for binary files (XLSX, Windows-1252 DATEV text).
skippedobject[]required3 fields
person_idstring | nullrequireditem_idstring | nullrequiredreasonstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/payroll/exports.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"period_id":"e1:2026-03-01","format":"datev_lodas"}'const res = await fetch('https://api.bizisy.com/v1/payroll/exports.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"period_id": "e1:2026-03-01",
"format": "datev_lodas"
}),
});
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/payroll/exports.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"period_id": "e1:2026-03-01",
"format": "datev_lodas",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"export": {
"id": "x1",
"format": "xlsx",
"files": [
{
"name": "payroll_Acme-Lda_2026-03-01_2026-03-31.xlsx",
"content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"bytes": 6120
}
],
"people": 12,
"skipped": 0,
"created_by": "u1",
"created_at": "2026-04-02T10:00:00.000Z"
},
"files": [
{
"name": "payroll_Acme-Lda_2026-03-01_2026-03-31.csv",
"content_type": "text/csv",
"sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"bytes": 120,
"encoding": "utf8",
"content": "section,employee_number,name\r\n"
}
],
"skipped": []
}
}Download an export again#
POST/v1/payroll/exports.downloadWrite
Downloads an earlier export of a locked period again: the files are made again from the frozen period and checked against the SHA-256 recorded when it was created (matches false: someone in it was erased since). SEPA salary files are not kept: create a new one. Recorded in Activity. Custom roles only when the export covers people they cover; API keys and AI apps need a consent for pay and private data.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Needs a consent for pay and private data.
- MCP tool
payroll_exports_downloadon 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
export_idstringrequired
Returns
exportobjectrequired7 fields
idstringrequiredformatstringrequiredfilesobject[]required4 fields
namestringrequiredcontent_typestringrequiredsha256stringrequiredbytesintegerrequired
peopleintegerrequiredskippedintegerrequiredcreated_bystringrequiredcreated_atstringrequired
filesobject[]required6 fields
namestringrequiredcontent_typestringrequiredsha256stringrequiredbytesintegerrequiredencoding"utf8" | "base64"requiredcontentstringrequiredThe file: UTF-8 text, or base64 for binary files (XLSX, Windows-1252 DATEV text).
matchesbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/payroll/exports.download \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"export_id":"x1"}'const res = await fetch('https://api.bizisy.com/v1/payroll/exports.download', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"export_id": "x1"
}),
});
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/payroll/exports.download",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"export_id": "x1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"export": {
"id": "x1",
"format": "xlsx",
"files": [
{
"name": "payroll_Acme-Lda_2026-03-01_2026-03-31.xlsx",
"content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"bytes": 6120
}
],
"people": 12,
"skipped": 0,
"created_by": "u1",
"created_at": "2026-04-02T10:00:00.000Z"
},
"files": [
{
"name": "payroll_Acme-Lda_2026-03-01_2026-03-31.csv",
"content_type": "text/csv",
"sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"bytes": 120,
"encoding": "utf8",
"content": "section,employee_number,name\r\n"
}
],
"matches": true
}
}Import net pay#
POST/v1/payroll/net_pay.importWrite
Records each person's net pay for a locked period from the payroll provider's results (a CSV read by the app, or rows from your system): rows name the person (person_id, employee_number, tax_id or exact full name) with amount and currency (default EUR). Replaces the period's net pay. All or nothing: unmatched rows refuse the import with their row numbers (preview with dry_run). An API key or AI app without consent for private data names people by person_id or employee_number only. Used for the SEPA salary file. At most 5000 rows. API keys and AI apps need a consent for pay data. Owners, admins, HR and roles with Payroll that cover everyone. Part of the Payroll 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
- Needs a consent for pay data; names people by person id or employee number only, unless the consent covers private data.
- MCP tool
payroll_net_pay_importon 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
period_idstringrequiredA period id from payroll_overview or payroll_periods_get: "<legal entity id>:<start date>".
12–120 characters.
rowsobject[]required1–5000 items.
6 fields
person_idstringUp to 64 characters.
employee_numberstringUp to 20 characters.
tax_idstringUp to 40 characters.
namestringUp to 200 characters.
amountnumberrequiredFrom 0 to 10000000.
currencystringPattern
^[A-Z]{3}$.
Returns
period_idstringrequiredrecordedintegerrequiredtotalobject[]required2 fields
currencystringrequiredamountnumberrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/payroll/net_pay.import \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"period_id": "e1:2026-03-01",
"rows": [
{
"employee_number": "1002",
"amount": 1830.4
},
{
"name": "Bruno Costa",
"amount": 1830.4,
"currency": "EUR"
}
]
}'const res = await fetch('https://api.bizisy.com/v1/payroll/net_pay.import', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"period_id": "e1:2026-03-01",
"rows": [
{
"employee_number": "1002",
"amount": 1830.4
},
{
"name": "Bruno Costa",
"amount": 1830.4,
"currency": "EUR"
}
]
}),
});
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/payroll/net_pay.import",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"period_id": "e1:2026-03-01",
"rows": [
{
"employee_number": "1002",
"amount": 1830.4,
},
{
"name": "Bruno Costa",
"amount": 1830.4,
"currency": "EUR",
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"period_id": "e1:2026-03-01",
"recorded": 12,
"total": [
{
"currency": "EUR",
"amount": 21960.8
}
]
}
}Clear net pay#
POST/v1/payroll/net_pay.clearDestructive
Removes a locked period's net pay (to import it again). Owners, admins, HR and roles with Payroll that cover everyone. Part of the Payroll 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
- MCP tool
payroll_net_pay_clearon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
period_idstringrequiredA period id from payroll_overview or payroll_periods_get: "<legal entity id>:<start date>".
12–120 characters.
Returns
period_idstringrequiredremovedintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/payroll/net_pay.clear \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"period_id":"e1:2026-03-01"}'const res = await fetch('https://api.bizisy.com/v1/payroll/net_pay.clear', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"period_id": "e1: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/payroll/net_pay.clear",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"period_id": "e1:2026-03-01",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"period_id": "e1:2026-03-01",
"removed": 12
}
}Create a SEPA salary file#
POST/v1/payroll/sepa.createWrite
Creates a SEPA credit transfer file (ISO 20022 pain.001.001.09, category purpose SALA, batch booking) paying each person's imported net pay from the legal entity's account (Payroll settings) on execution_date, to the IBAN each person has now. People without a valid IBAN, a name, a euro amount above zero are left out and listed in problems. Upload the file to your bank; Bizisy never moves money. The file's SHA-256, who and when are recorded; the file itself is not kept. In the app only. Owners, admins, HR and roles with Payroll at Edit that cover everyone in the period. Part of the Payroll 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 SEPA salary file is made in the app only.
- MCP tool
payroll_sepa_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
period_idstringrequiredA period id from payroll_overview or payroll_periods_get: "<legal entity id>:<start date>".
12–120 characters.
execution_datestringrequiredPattern
^\d{4}-\d{2}-\d{2}$.
Returns
exportobject | nullrequired7 fields
idstringrequiredformatstringrequiredfilesobject[]required4 fields
namestringrequiredcontent_typestringrequiredsha256stringrequiredbytesintegerrequired
peopleintegerrequiredskippedintegerrequiredcreated_bystringrequiredcreated_atstringrequired
fileobject | nullrequired6 fields
namestringrequiredcontent_typestringrequiredsha256stringrequiredbytesintegerrequiredencoding"utf8" | "base64"requiredcontentstringrequiredThe file: UTF-8 text, or base64 for binary files (XLSX, Windows-1252 DATEV text).
paymentsintegerrequiredtotalnumberrequiredproblemsobject[]required3 fields
person_idstring | nullrequiredcodestringrequiredmessagestringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/payroll/sepa.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"period_id":"e1:2026-03-01","execution_date":"2026-04-28"}'const res = await fetch('https://api.bizisy.com/v1/payroll/sepa.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"period_id": "e1:2026-03-01",
"execution_date": "2026-04-28"
}),
});
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/payroll/sepa.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"period_id": "e1:2026-03-01",
"execution_date": "2026-04-28",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"export": {
"id": "x1",
"format": "sepa_pain001",
"files": [
{
"name": "payroll_Acme-Lda_2026-03-01_2026-03-31.xlsx",
"content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"bytes": 6120
}
],
"people": 12,
"skipped": 0,
"created_by": "u1",
"created_at": "2026-04-02T10:00:00.000Z"
},
"file": {
"name": "salaries_2026-03-01_2026-03-31.xml",
"content_type": "application/xml",
"sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"bytes": 120,
"encoding": "utf8",
"content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
},
"payments": 11,
"total": 20130.4,
"problems": [
{
"person_id": "p9",
"code": "missing_iban",
"message": "No IBAN: left out of the file."
}
]
}
}My payroll companies#
POST/v1/payroll/workspaceRead
The companies you prepare or run payroll for with this account (yours, or outside access such as an accountant's clients): per company its address, your role and the state of its pay periods (open, ended and not locked, locked, exported, acknowledged). No people or amounts. Open a company on its own address to work on it. Needs Payroll in this company; an API key or AI app gets only this company. Part of the Payroll 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
- Keys and apps
- Only the company the key or app belongs to.
- MCP tool
payroll_workspaceon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
companiesobject[]required9 fields
org_idstringrequirednamestringrequiredurlstringrequiredrolestringrequiredexternalbooleanrequiredaccess_untilstring | nullrequiredcurrentbooleanrequiredperiodsobject[]requiredPer pay schedule: the current period, and the last locked one when it still waits for an export or acknowledgement.
3 fields
startstringrequiredendstringrequiredstatus"open" | "ended" | "locked" | "exported" | "acknowledged"required
set_upbooleanrequiredThe company has a pay schedule.
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/payroll/workspace \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/payroll/workspace', {
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/payroll/workspace",
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": {
"companies": [
{
"org_id": "o1",
"name": "Acme Lda",
"url": "https://acme.bizisy.com/manage/payroll",
"role": "Accountant",
"external": true,
"access_until": null,
"current": true,
"periods": [
{
"start": "2026-03-01",
"end": "2026-03-31",
"status": "exported"
}
],
"set_up": true
}
]
}
}Something missing or wrong on this page? Write to hello@bizisy.com.