API reference
Meta4 bridge
The codes Meta4 knows each leave type, pay item, time-clock total, leaving reason and contract type by (matched from a pasted code list), the preview of a locked period before its Meta4 file is made (payroll_exports_create, format meta4), and the reconciliation with Meta4's results.
6 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
Preview a period for Meta4#
POST/v1/payroll/meta4.previewRead
Before downloading a locked period's Meta4 file: the lines per section (hires, leavers, job and pay changes, variable pay, time-clock totals, absences, late corrections), the problems first (people without an employee number, rows without a Meta4 code, starter codes still to confirm; each says how to fix it), and how it compares with the last Meta4 export of the period (the same, or how many lines changed). Nothing is written. Custom roles see the people they cover. API keys and AI apps need a consent for pay and private data. 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_meta4_previewon 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
period_idstringrequiredlinesintegerrequiredsectionsobject[]required2 fields
sectionstring (enum)requiredOne of:
hires,leavers,changes,pay,items,time,absences,late.linesintegerrequired
problemsobject[]required5 fields
kind"no_number" | "no_code" | "to_confirm" | "open_month"requiredperson_idstring | nullrequiredcode_rowstring | nullrequiredcountintegerrequiredmessagestringrequired
lastobject | nullrequired4 fields
export_idstringrequiredcreated_atstringrequiredsamebooleanrequiredchangedintegerrequiredLines added, removed or changed since that export.
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/payroll/meta4.preview \
-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/meta4.preview', {
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/meta4.preview",
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",
"lines": 4,
"sections": [
{
"section": "hires",
"lines": 1
},
{
"section": "leavers",
"lines": 0
},
{
"section": "changes",
"lines": 0
},
{
"section": "pay",
"lines": 0
},
{
"section": "items",
"lines": 2
},
{
"section": "time",
"lines": 0
},
{
"section": "absences",
"lines": 1
},
{
"section": "late",
"lines": 0
}
],
"problems": [
{
"kind": "to_confirm",
"person_id": null,
"code_row": "pay:base",
"count": 1,
"message": "Base pay uses Bizisy's starter code VB: confirm it is your Meta4 code."
}
],
"last": {
"export_id": "x1",
"created_at": "2026-04-02T10:00:00.000Z",
"same": false,
"changed": 1
}
}
}Get the Meta4 codes#
POST/v1/payroll/code_map.getRead
The codes Meta4 (the payroll tool) knows each Bizisy thing by, one row each: the company's leave types and pay items, time-clock totals (overtime on a working day, rest day or holiday; night hours; days without a record), base pay, leaving reasons and contract types. Each row has its code and a status: confirmed, to_confirm (Bizisy's starter code for the country: a placeholder, since Meta4 codes are each company's own) or missing. 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_code_map_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
tool"meta4"Default
"meta4".
Returns
tool"meta4"requiredcountrystringrequiredrowsobject[]required7 fields
group"leave" | "items" | "time" | "pay" | "leaving" | "contract"requiredkeystringrequiredlabelstringrequiredunit"days" | "hours" | "amount"requiredcodestring | nullrequiredThe code sent to the payroll tool (null: none yet).
status"confirmed" | "to_confirm" | "missing"requiredconfirmed: HR set or confirmed it; to_confirm: Bizisy's starter code, a placeholder; missing: no code (rows of this kind are listed as problems in the export).
descriptionstring | nullrequiredThe tool's description of the code, from a pasted code list.
countsobjectrequired3 fields
confirmedintegerrequiredto_confirmintegerrequiredmissingintegerrequired
updated_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/payroll/code_map.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"tool":"meta4"}'const res = await fetch('https://api.bizisy.com/v1/payroll/code_map.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"tool": "meta4"
}),
});
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/code_map.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"tool": "meta4",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"tool": "meta4",
"country": "PT",
"updated_at": "2026-11-14T10:00:00.000Z",
"counts": {
"confirmed": 1,
"to_confirm": 1,
"missing": 1
},
"rows": [
{
"group": "leave",
"key": "vacation",
"label": "Holidays",
"unit": "days",
"code": "F01",
"status": "confirmed",
"description": "Férias"
},
{
"group": "items",
"key": "c1",
"label": "Bonus",
"unit": "amount",
"code": null,
"status": "missing",
"description": null
},
{
"group": "pay",
"key": "base",
"label": "Base pay",
"unit": "amount",
"code": "VB",
"status": "to_confirm",
"description": null
}
]
}
}Set Meta4 codes#
POST/v1/payroll/code_map.setWrite
Sets the Meta4 code of rows of the code map (group and key from payroll_code_map_get; code null: no code). Rows not sent keep theirs; confirm = send the starter code. Pay item codes are kept on the pay item (catalogue). Locked periods' exports keep the codes they were made with. At most 2000 rows. 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_code_map_seton HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
tool"meta4"Default
"meta4".rowsobject[]required1–2000 items.
4 fields
group"leave" | "items" | "time" | "pay" | "leaving" | "contract"requiredkeystringrequired1–64 characters.
codestring | nullrequired1–40 characters. Pattern
^[^\s;,"=+@\t\r\n][^;"\t\r\n]{0,39}$.descriptionstring | nullUp to 120 characters.
Returns
tool"meta4"requiredcountrystringrequiredrowsobject[]required7 fields
group"leave" | "items" | "time" | "pay" | "leaving" | "contract"requiredkeystringrequiredlabelstringrequiredunit"days" | "hours" | "amount"requiredcodestring | nullrequiredThe code sent to the payroll tool (null: none yet).
status"confirmed" | "to_confirm" | "missing"requiredconfirmed: HR set or confirmed it; to_confirm: Bizisy's starter code, a placeholder; missing: no code (rows of this kind are listed as problems in the export).
descriptionstring | nullrequiredThe tool's description of the code, from a pasted code list.
countsobjectrequired3 fields
confirmedintegerrequiredto_confirmintegerrequiredmissingintegerrequired
updated_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/payroll/code_map.set \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"rows": [
{
"group": "leave",
"key": "vacation",
"code": "F01",
"description": "Férias"
},
{
"group": "pay",
"key": "base",
"code": null
}
]
}'const res = await fetch('https://api.bizisy.com/v1/payroll/code_map.set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"rows": [
{
"group": "leave",
"key": "vacation",
"code": "F01",
"description": "Férias"
},
{
"group": "pay",
"key": "base",
"code": 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/code_map.set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"rows": [
{
"group": "leave",
"key": "vacation",
"code": "F01",
"description": "Férias",
},
{
"group": "pay",
"key": "base",
"code": None,
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"tool": "meta4",
"country": "PT",
"updated_at": "2026-11-14T10:00:00.000Z",
"counts": {
"confirmed": 1,
"to_confirm": 1,
"missing": 1
},
"rows": [
{
"group": "leave",
"key": "vacation",
"label": "Holidays",
"unit": "days",
"code": "F01",
"status": "confirmed",
"description": "Férias"
},
{
"group": "items",
"key": "c1",
"label": "Bonus",
"unit": "amount",
"code": null,
"status": "missing",
"description": null
},
{
"group": "pay",
"key": "base",
"label": "Base pay",
"unit": "amount",
"code": "VB",
"status": "to_confirm",
"description": null
}
]
}
}Match a Meta4 code list#
POST/v1/payroll/code_map.matchRead
Reads a code list pasted from Meta4 (its concept and absence tables: one code and description per line, separated by a tab, semicolon or comma) and proposes the code of each row of the code map whose description names it (Portuguese, Spanish or English words; the company's own leave types and pay items by their name). Nothing is saved: send the proposals you accept to payroll_code_map_set. Returns the proposals, the rows left to fill by hand, and the lines no row matched. At most 200 kB of text. 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_code_map_matchon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
tool"meta4"Default
"meta4".textstringrequired1–200000 characters.
Returns
linesintegerrequiredCode lines read from the text.
matchesobject[]required6 fields
group"leave" | "items" | "time" | "pay" | "leaving" | "contract"requiredkeystringrequiredlabelstringrequiredcodestringrequireddescriptionstringrequiredchangedbooleanrequiredDiffers from the code the row has now.
openobject[]requiredRows no line named: fill them by hand.
3 fields
group"leave" | "items" | "time" | "pay" | "leaving" | "contract"requiredkeystringrequiredlabelstringrequired
unusedobject[]requiredLines that named no row (codes Bizisy does not send, such as taxes).
Up to 200 items.
2 fields
codestringrequireddescriptionstringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/payroll/code_map.match \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"F01;Férias\nVB01;Vencimento base"}'const res = await fetch('https://api.bizisy.com/v1/payroll/code_map.match', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"text": "F01;Férias\nVB01;Vencimento base"
}),
});
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/code_map.match",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"text": "F01;Férias\nVB01;Vencimento base",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"lines": 2,
"matches": [
{
"group": "leave",
"key": "vacation",
"label": "Holidays",
"code": "F01",
"description": "Férias",
"changed": false
},
{
"group": "pay",
"key": "base",
"label": "Base pay",
"code": "VB01",
"description": "Vencimento base",
"changed": true
}
],
"open": [
{
"group": "items",
"key": "c1",
"label": "Bonus"
}
],
"unused": []
}
}Reconcile a period with Meta4#
POST/v1/payroll/reconcile.runWrite
Compares what Meta4 paid for a locked period (rows from its results file: employee_number or person_id, the concept code, units and/or amount) with what the period's last Meta4 export sent, per person and code: matched, different (both values), not_in_meta4 (sent, not paid: not loaded, wrong code, person not found) or only_in_meta4 (a code Bizisy manages paid without being sent: a change made in Meta4). Codes Bizisy doesn't send (taxes, social security) are counted as ignored. Replaces the period's previous reconciliation; dry_run compares without keeping it. At most 200,000 rows. Owners, admins, HR and roles with Payroll at Edit that cover everyone in the period; API keys and AI apps need a pay consent. 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_reconcile_runon 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
- Body limit
- 20 MiB (other actions: 2 MiB)
Input
period_idstringrequiredA period id from payroll_overview or payroll_periods_get: "<legal entity id>:<start date>".
12–120 characters.
rowsobject[]required1–200000 items.
5 fields
employee_numberstring1–20 characters.
person_idstring1–64 characters.
codestringrequired1–40 characters.
unitsnumber | nullFrom -10000000 to 10000000.
amountnumber | nullFrom -1000000000 to 1000000000.
Returns
period_idstringrequiredexport_idstringrequiredcreated_atstringrequiredcountsobjectrequired6 fields
matchedintegerrequireddifferentintegerrequirednot_in_meta4integerrequiredonly_in_meta4integerrequiredignoredintegerrequiredLines of codes Bizisy doesn't send (taxes, social security…).
unknownintegerrequiredLines whose employee number is nobody in the period.
rowsobject[]requiredThe lines not matched (different first), at most 3000; matched lines are counted.
9 fields
person_idstringrequirednamestringrequiredemployee_numberstring | nullrequiredcodestringrequiredstate"matched" | "different" | "not_in_meta4" | "only_in_meta4"requiredsent_unitsnumber | nullrequiredsent_amountnumber | nullrequiredpaid_unitsnumber | nullrequiredpaid_amountnumber | nullrequired
truncatedbooleanrequiredMore lines were not matched than are kept.
Errors
validation_failed unauthenticated forbidden not_found conflict payload_too_large rate_limited internal
curl https://api.bizisy.com/v1/payroll/reconcile.run \
-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",
"code": "SR",
"units": 21,
"amount": 158.97
},
{
"person_id": "p2",
"code": "HE1",
"units": 4
}
]
}'const res = await fetch('https://api.bizisy.com/v1/payroll/reconcile.run', {
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",
"code": "SR",
"units": 21,
"amount": 158.97
},
{
"person_id": "p2",
"code": "HE1",
"units": 4
}
]
}),
});
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/reconcile.run",
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",
"code": "SR",
"units": 21,
"amount": 158.97,
},
{
"person_id": "p2",
"code": "HE1",
"units": 4,
},
],
},
)
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",
"export_id": "x1",
"created_at": "2026-04-03T10:00:00.000Z",
"counts": {
"matched": 12,
"different": 1,
"not_in_meta4": 1,
"only_in_meta4": 0,
"ignored": 212,
"unknown": 0
},
"truncated": false,
"rows": [
{
"person_id": "p2",
"name": "Bruno Costa",
"employee_number": "1002",
"code": "HE1",
"state": "different",
"sent_units": 6.5,
"sent_amount": null,
"paid_units": 6,
"paid_amount": 41.2
}
]
}
}Get a period's reconciliation with Meta4#
POST/v1/payroll/reconcile.getRead
The last reconciliation of a locked period with Meta4 (payroll_reconcile_run): counts and the rows, differences first, with each person's name and employee number. null when the period hasn't been reconciled. Owners, admins, HR and roles with Payroll at Edit that cover everyone in the period; API keys and AI apps need a pay consent. 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_reconcile_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
period_idstringrequiredexport_idstringrequiredcreated_atstringrequiredcountsobjectrequired6 fields
matchedintegerrequireddifferentintegerrequirednot_in_meta4integerrequiredonly_in_meta4integerrequiredignoredintegerrequiredLines of codes Bizisy doesn't send (taxes, social security…).
unknownintegerrequiredLines whose employee number is nobody in the period.
rowsobject[]requiredThe lines not matched (different first), at most 3000; matched lines are counted.
9 fields
person_idstringrequirednamestringrequiredemployee_numberstring | nullrequiredcodestringrequiredstate"matched" | "different" | "not_in_meta4" | "only_in_meta4"requiredsent_unitsnumber | nullrequiredsent_amountnumber | nullrequiredpaid_unitsnumber | nullrequiredpaid_amountnumber | nullrequired
truncatedbooleanrequiredMore lines were not matched than are kept.
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/payroll/reconcile.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/reconcile.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/reconcile.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",
"export_id": "x1",
"created_at": "2026-04-03T10:00:00.000Z",
"counts": {
"matched": 12,
"different": 1,
"not_in_meta4": 1,
"only_in_meta4": 0,
"ignored": 212,
"unknown": 0
},
"truncated": false,
"rows": [
{
"person_id": "p2",
"name": "Bruno Costa",
"employee_number": "1002",
"code": "HE1",
"state": "different",
"sent_units": 6.5,
"sent_amount": null,
"paid_units": 6,
"paid_amount": 41.2
}
]
}
}Something missing or wrong on this page? Write to hello@bizisy.com.