API reference
Payroll tools
Send a locked pay period to Staffology, Xero Payroll (UK) or Silae: where each legal entity goes, the preview of what goes per person, the send (in the app, bound to the preview, with consent for pay and private data) and the log of what was sent.
5 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
List payroll tools Bizisy sends to#
POST/v1/payroll/push.targetsRead
The payroll tools this server can send locked pay periods to (Staffology, Xero Payroll, Silae), each with its connection state, whether its connection may receive pay and private data (consent), where each legal entity goes and its options, the answers it asks for new employees, and the last send per legal entity. 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_push_targetson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
targetsobject[]required15 fields
connectorstringrequirednamestringrequiredcountriesstring[]requiredstatus"connecting" | "connected" | "error" | "removed"requiredlabelstring | nullrequiredpagestring | nullrequiredconsentobjectrequired3 fields
allowedbooleanrequiredmissing"pay" | "private"[]requiredgranteeobject | nullrequired3 fields
kind"connection"requiredidstringrequirednamestringrequired
answers"title" | "gender" | "marital_status" | "starter_declaration" | "ni_category"[]requiredcode_keystringrequiredemployeesbooleanrequiredleaversbooleanrequiredunits"amount" | "hours" | "days"[]requiredaccountobjectrequired2 fields
labelstringrequiredlookupstringrequired
optionsobject[]required4 fields
keystringrequiredlabelstringrequiredlookupstringrequiredrequiredbooleanrequired
entitiesobject[]required4 fields
legal_entity_idstringrequiredaccountobjectrequired2 fields
idstringrequirednamestringrequired
optionsobjectrequiredlast_pushobject | nullrequired8 fields
idstringrequiredperiod_idstringrequiredconnectorstringrequiredstatus"queued" | "sending" | "sent" | "partial" | "failed"requiredrequested_atstringrequiredfinished_atstring | nullrequiredcountsobjectrequired4 fields
peopleintegerrequiredsentintegerrequiredfailedintegerrequiredskippedintegerrequired
resultsobject[]required4 fields
person_idstring | nullrequiredop"employee" | "leaver" | "pay" | "push"requiredoutcome"ok" | "failed" | "skipped"requiredmessagestringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/payroll/push.targets \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/payroll/push.targets', {
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/push.targets",
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": {
"targets": [
{
"connector": "staffology",
"name": "Staffology",
"countries": [
"GB"
],
"status": "connected",
"label": "Acme UK Ltd",
"page": "/manage/integrations/staffology",
"consent": {
"allowed": true,
"missing": [],
"grantee": {
"kind": "connection",
"id": "staffology:3f2a",
"name": "Staffology (Acme UK Ltd)"
}
},
"answers": [
"gender",
"marital_status",
"starter_declaration"
],
"code_key": "staffology",
"employees": true,
"leavers": true,
"units": [
"amount"
],
"account": {
"label": "Staffology employer",
"lookup": "employers"
},
"options": [],
"entities": [
{
"legal_entity_id": "e1",
"account": {
"id": "11111111-2222-3333-4444-555555555555",
"name": "Acme UK Ltd"
},
"options": {},
"last_push": {
"id": "push1",
"period_id": "e1:2026-03-01",
"connector": "staffology",
"status": "partial",
"requested_at": "2026-04-02T09:00:00.000Z",
"finished_at": "2026-04-02T09:00:05.000Z",
"counts": {
"people": 2,
"sent": 2,
"failed": 1,
"skipped": 0
},
"results": []
}
}
]
}
]
}
}Choose where a legal entity goes in a payroll tool#
POST/v1/payroll/push.mapWrite
Sets where one legal entity's pay periods go in a connected payroll tool: account_id (the Staffology employer; for tools with one account per connection, the connection's account) with account_name, and the tool's options (Xero: payroll_calendar). account_id null stops sending that entity. Ids come from integrations_connections_lookup. 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_push_mapon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
legal_entity_idstringrequiredconnector"staffology" | "xero_payroll" | "silae"requiredThe payroll tool: see payroll_push_targets.
account_idstring | nullrequired1–200 characters.
account_namestringUp to 200 characters. Default
"".optionsobjectDefault
{}.
Returns
legal_entity_idstringrequiredconnectorstringrequiredaccountobject | nullrequired2 fields
idstringrequirednamestringrequired
optionsobjectrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/payroll/push.map \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"legal_entity_id": "e1",
"connector": "xero_payroll",
"account_id": "tenant-1",
"account_name": "Acme UK",
"options": {
"payroll_calendar": "22222222-3333-4444-5555-666666666666"
}
}'const res = await fetch('https://api.bizisy.com/v1/payroll/push.map', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"legal_entity_id": "e1",
"connector": "xero_payroll",
"account_id": "tenant-1",
"account_name": "Acme UK",
"options": {
"payroll_calendar": "22222222-3333-4444-5555-666666666666"
}
}),
});
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/push.map",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"legal_entity_id": "e1",
"connector": "xero_payroll",
"account_id": "tenant-1",
"account_name": "Acme UK",
"options": {
"payroll_calendar": "22222222-3333-4444-5555-666666666666",
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"legal_entity_id": "e1",
"connector": "xero_payroll",
"account": {
"id": "11111111-2222-3333-4444-555555555555",
"name": "Acme UK Ltd"
},
"options": {}
}
}Preview sending a pay period to a payroll tool#
POST/v1/payroll/push.previewRead
What sending a locked pay period to a payroll tool would do, per person: the employee record (create, update with the fields that changed, or match by employee number), the leaver, and the variable pay items with the tool's pay codes; problems say what will not go and why. Also: whether the connection may receive pay and private data (consent), the answers the tool needs for new people (answers_needed), plan_hash (pass it to payroll_push_send), ready and blocked (why it cannot be sent yet). Nothing is sent. Owners, admins, HR and roles with Payroll at Edit that cover the whole period; API keys and AI apps see values only with a 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
- Keys and apps
- Pay values only with a consent (Payroll → Settings → Machine access); otherwise null.
- MCP tool
payroll_push_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.
connector"staffology" | "xero_payroll" | "silae"requiredThe payroll tool: see payroll_push_targets.
Returns
11 fields
period_idstringrequiredconnectorstringrequiredaccountobject | nullrequired2 fields
idstringrequirednamestringrequired
rowsobject[]required9 fields
person_idstringrequirednamestringrequiredemployee_numberstring | nullrequiredemployee"create" | "update" | "match"requiredcreate: new in the tool; update: payroll data changed; match: found by employee number, else created.
fieldsstring (enum)[]requiredOne of:
given_name,family_name,birthday,address,tax_id,social_security_number,iban,employee_number,start_date,title,weekly_hours,fte,contract_type,pay.leaverobject | nullrequired2 fields
last_daystringrequiredreasonstring | nullrequired
itemsobject[]required7 fields
item_idstringrequiredcodestringrequirednamestringrequiredkind"earning" | "deduction"requiredunit"amount" | "hours" | "days"requiredvaluenumber | nullrequiredcurrencystring | nullrequired
problemsstring[]requiredneeds_answersbooleanrequired
skipped_itemsintegerrequiredconsentobjectrequired3 fields
allowedbooleanrequiredmissing"pay" | "private"[]requiredgranteeobject | nullrequired3 fields
kind"connection"requiredidstringrequirednamestringrequired
answers_needed"title" | "gender" | "marital_status" | "starter_declaration" | "ni_category"[]requiredplan_hashstring | nullrequiredPass it to payroll_push_send; null for callers who do not see pay values.
readybooleanrequiredblockedstring | nullrequiredlast_pushobject | nullrequired8 fields
idstringrequiredperiod_idstringrequiredconnectorstringrequiredstatus"queued" | "sending" | "sent" | "partial" | "failed"requiredrequested_atstringrequiredfinished_atstring | nullrequiredcountsobjectrequired4 fields
peopleintegerrequiredsentintegerrequiredfailedintegerrequiredskippedintegerrequired
resultsobject[]required4 fields
person_idstring | nullrequiredop"employee" | "leaver" | "pay" | "push"requiredoutcome"ok" | "failed" | "skipped"requiredmessagestringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/payroll/push.preview \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"period_id":"e1:2026-03-01","connector":"staffology"}'const res = await fetch('https://api.bizisy.com/v1/payroll/push.preview', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"period_id": "e1:2026-03-01",
"connector": "staffology"
}),
});
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/push.preview",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"period_id": "e1:2026-03-01",
"connector": "staffology",
},
)
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",
"connector": "staffology",
"account": {
"id": "11111111-2222-3333-4444-555555555555",
"name": "Acme UK Ltd"
},
"rows": [
{
"person_id": "p2",
"name": "Bruno Costa",
"employee_number": "1002",
"employee": "create",
"fields": [
"given_name",
"family_name",
"birthday",
"address",
"employee_number",
"start_date",
"pay"
],
"leaver": null,
"items": [
{
"item_id": "i1",
"code": "BONUS",
"name": "Bonus",
"kind": "earning",
"unit": "amount",
"value": 500,
"currency": "GBP"
}
],
"problems": [],
"needs_answers": true
},
{
"person_id": "p1",
"name": "Ana Ferreira",
"employee_number": "1001",
"employee": null,
"fields": [],
"leaver": {
"last_day": "2026-03-20",
"reason": "resignation"
},
"items": [],
"problems": [
"The pay item \"Overtime\" has no Staffology pay code in Pay items."
],
"needs_answers": false
}
],
"skipped_items": 1,
"consent": {
"allowed": true,
"missing": [],
"grantee": {
"kind": "connection",
"id": "staffology:3f2a",
"name": "Staffology (Acme UK Ltd)"
}
},
"answers_needed": [
"gender",
"marital_status",
"starter_declaration"
],
"plan_hash": "3b1f0c9a2d4e5f60718293a4b5c6d7e8",
"ready": true,
"blocked": null,
"last_push": null
}
}Send a pay period to a payroll tool#
POST/v1/payroll/push.sendWrite
Sends a locked pay period to a connected payroll tool, exactly as payroll_push_preview showed it: pass its plan_hash (a different plan is refused: preview again). New employees need the tool's answers (answers_needed; e.g. Staffology's gender, marital status and HMRC starter declaration), one entry per person; Bizisy keeps them only until they are sent. Needs the connection's consent for pay and private data. Queues the send and starts it; follow it with payroll_push_log. One send per period and tool at a time; at most 50 per period. In the app only. Owners, admins, HR and roles with Payroll at Edit that cover the whole 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. Sending a pay period to a payroll tool happens in the app only.
- MCP tool
payroll_push_sendon 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.
connector"staffology" | "xero_payroll" | "silae"requiredThe payroll tool: see payroll_push_targets.
plan_hashstringrequired8–64 characters.
answersobject[]Up to 2000 items.
6 fields
person_idstringrequiredtitlestringUp to 40 characters.
genderstringUp to 40 characters.
marital_statusstringUp to 40 characters.
starter_declarationstringUp to 40 characters.
ni_categorystringUp to 40 characters.
Returns
8 fields
idstringrequiredperiod_idstringrequiredconnectorstringrequiredstatus"queued" | "sending" | "sent" | "partial" | "failed"requiredrequested_atstringrequiredfinished_atstring | nullrequiredcountsobjectrequired4 fields
peopleintegerrequiredsentintegerrequiredfailedintegerrequiredskippedintegerrequired
resultsobject[]required4 fields
person_idstring | nullrequiredop"employee" | "leaver" | "pay" | "push"requiredoutcome"ok" | "failed" | "skipped"requiredmessagestringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/payroll/push.send \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"period_id": "e1:2026-03-01",
"connector": "staffology",
"plan_hash": "3b1f0c9a2d4e5f60718293a4b5c6d7e8",
"answers": [
{
"person_id": "p2",
"gender": "female",
"marital_status": "single",
"starter_declaration": "A"
}
]
}'const res = await fetch('https://api.bizisy.com/v1/payroll/push.send', {
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",
"connector": "staffology",
"plan_hash": "3b1f0c9a2d4e5f60718293a4b5c6d7e8",
"answers": [
{
"person_id": "p2",
"gender": "female",
"marital_status": "single",
"starter_declaration": "A"
}
]
}),
});
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/push.send",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"period_id": "e1:2026-03-01",
"connector": "staffology",
"plan_hash": "3b1f0c9a2d4e5f60718293a4b5c6d7e8",
"answers": [
{
"person_id": "p2",
"gender": "female",
"marital_status": "single",
"starter_declaration": "A",
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "push1",
"period_id": "e1:2026-03-01",
"connector": "staffology",
"status": "queued",
"requested_at": "2026-04-02T09:00:00.000Z",
"finished_at": null,
"counts": {
"people": 2,
"sent": 0,
"failed": 0,
"skipped": 0
},
"results": []
}
}Read what was sent to payroll tools#
POST/v1/payroll/push.logRead
The sends of a pay period to payroll tools, newest first: tool, status (queued, sending, sent, partial, failed), when, counts and per-person results (employee, leaver, pay or the whole send; ok, failed or skipped; a sentence of Bizisy's). Owners, admins, HR and roles with Payroll that cover the whole 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); this read of stored data keeps working while it is off.
- Who can call it
- Manage key owner admin hr
- MCP tool
payroll_push_logon 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
pushesobject[]required8 fields
idstringrequiredperiod_idstringrequiredconnectorstringrequiredstatus"queued" | "sending" | "sent" | "partial" | "failed"requiredrequested_atstringrequiredfinished_atstring | nullrequiredcountsobjectrequired4 fields
peopleintegerrequiredsentintegerrequiredfailedintegerrequiredskippedintegerrequired
resultsobject[]required4 fields
person_idstring | nullrequiredop"employee" | "leaver" | "pay" | "push"requiredoutcome"ok" | "failed" | "skipped"requiredmessagestringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/payroll/push.log \
-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/push.log', {
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/push.log",
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": {
"pushes": [
{
"id": "push1",
"period_id": "e1:2026-03-01",
"connector": "staffology",
"status": "partial",
"requested_at": "2026-04-02T09:00:00.000Z",
"finished_at": "2026-04-02T09:00:05.000Z",
"counts": {
"people": 2,
"sent": 2,
"failed": 1,
"skipped": 0
},
"results": [
{
"person_id": "p2",
"op": "employee",
"outcome": "ok",
"message": "In Staffology."
},
{
"person_id": "p1",
"op": "leaver",
"outcome": "ok",
"message": "Recorded as a leaver in Staffology."
},
{
"person_id": "p2",
"op": "pay",
"outcome": "failed",
"message": "Staffology took no pay items: open the monthly pay run for this period in Staffology with these people on it, check the pay codes, then send again."
}
]
}
]
}
}Something missing or wrong on this page? Write to hello@bizisy.com.