API reference
Spend tools (Pleo, Moss, Payhawk, Spendesk)
What Bizisy does in each spend tool its API allows (invites, teams or cost centres, approvers from team leads, blocking a leaver's cards), the plan before syncing starts and what HR does in the tool itself. Connecting, starting, confirming and excluding happen in the web app.
7 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
Spend tools status#
POST/v1/org/spend.statusRead
Pleo, Moss, Payhawk and Spendesk (spec integration-platform-spend): for each, what its API lets Bizisy do (capabilities: invite people, teams or cost centres, approvers, block leavers' cards), whether it is connected, whether syncing has started (started: false means Bizisy only reads it and shows the plan until an owner or admin clicks Start syncing), the settings (team mapping with team names), when it was last read, and counts (people matched by work email, excluded, administrators never touched, people in the tool who are not in Bizisy, changes the next run sends, changes waiting for a person, failed changes, checks: things to do in the tool itself). Connecting and settings are integrations_connections_*. Owners, admins and HR; never custom roles. Part of the Finance module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules); this read of stored data keeps working while it is off.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_spend_statuson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
toolsobject[]required10 fields
connector"pleo" | "moss" | "payhawk" | "spendesk"requirednamestringrequiredavailablebooleanrequiredThis server offers it (Pleo needs Bizisy's partner app).
capabilitiesobjectrequired6 fields
invitebooleanrequiredgroups"teams" | "cost_centres" | "read"requiredapprovers"team_manager" | "owner" | "read"requiredoffboard"block_cards"requiredsingle_teambooleanrequiredadmins_knownbooleanrequired
connectionobject | nullrequired5 fields
statusstringrequiredlabelstring | nullrequiredconnected_onstring | nullrequiredfailingbooleanrequiredlast_errorstring | nullrequired
startedbooleanrequiredread_atstring | nullrequiredtruncatedbooleanrequiredsettingsobjectrequired6 fields
create"off" | "confirm" | "auto"requiredPayhawk: confirm (HR confirms each invite), auto (invited days_before the start), off (a reminder only).
days_beforeintegerrequiredFrom 0 to 14.
create_for"everyone" | "mapped"requiredeveryone starting, or only people whose team maps to a group of the tool.
teamsobject[]required4 fields
unit_idstringrequiredunit_namestring | nullrequiredgroup_idstring | nullrequiredgroup_namestring | nullrequired
approversbooleanrequiredThe mapped team's lead is its approver in the tool (Payhawk team manager, Spendesk cost-centre owner).
offboardbooleanrequiredPayhawk: block a leaver's active cards the day after the last day.
countsobjectrequired9 fields
matchedintegerrequiredexcludedintegerrequiredadminsintegerrequiredunmatched_in_toolintegerrequiredchangesintegerrequiredwaitingintegerrequiredfailedintegerrequiredchecksintegerrequiredgroupsintegerrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/spend.status \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/spend.status', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/spend.status",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"tools": [
{
"connector": "payhawk",
"name": "Payhawk",
"available": true,
"capabilities": {
"invite": true,
"groups": "teams",
"approvers": "team_manager",
"offboard": "block_cards",
"single_team": false,
"admins_known": true
},
"connection": {
"status": "connected",
"label": "Acme Payhawk",
"connected_on": "2026-10-01",
"failing": false,
"last_error": null
},
"started": true,
"read_at": "2026-10-04T10:00:00.000Z",
"truncated": false,
"settings": {
"create": "confirm",
"days_before": 3,
"create_for": "everyone",
"approvers": true,
"offboard": true,
"teams": [
{
"unit_id": "u2",
"unit_name": "Engineering",
"group_id": "t1",
"group_name": "Engineering"
}
]
},
"counts": {
"matched": 12,
"excluded": 1,
"admins": 2,
"unmatched_in_tool": 1,
"changes": 2,
"waiting": 1,
"failed": 0,
"checks": 1,
"groups": 3
}
},
{
"connector": "pleo",
"name": "Pleo",
"available": false,
"capabilities": {
"invite": false,
"groups": "teams",
"approvers": null,
"offboard": null,
"single_team": true,
"admins_known": false
},
"connection": null,
"started": false,
"read_at": null,
"truncated": false,
"settings": {
"create": "confirm",
"days_before": 3,
"create_for": "everyone",
"approvers": true,
"offboard": true,
"teams": []
},
"counts": {
"matched": 0,
"excluded": 0,
"admins": 0,
"unmatched_in_tool": 0,
"changes": 0,
"waiting": 0,
"failed": 0,
"checks": 0,
"groups": 0
}
}
]
}
}Preview a spend tool sync#
POST/v1/org/spend.previewRead
What the next run does in a connected spend tool (a dry run: nothing is sent), from Bizisy today and the tool as last read: changes (offboard: block a leaver's cards; invite; group_create / group_rename; team: move between the groups Bizisy manages; approver: the team lead as approver), each waiting_for_confirm or not, with its last error; and checks: what HR does in the tool itself because its API can't (deactivate a leaver, invite a starter, differences). Before Start syncing, this is the plan an owner or admin reviews. Names are public; no private or pay data. Owners, admins and HR; never custom roles. Part of the Finance 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
org_spend_previewon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
connector"pleo" | "moss" | "payhawk" | "spendesk"required
Returns
startedbooleanrequiredread_atstring | nullrequireditemsobject[]required11 fields
kind"offboard" | "invite" | "group_create" | "group_rename" | "team" | "approver"requiredoffboard: block the leaver's active cards (Payhawk); invite: a new account; group_create / group_rename: a team or cost centre; team: move the person between the groups Bizisy manages; approver: the team's lead becomes its approver.
personobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
teamobject | nullrequired2 fields
idstringrequirednamestringrequired
groupobject | nullrequiredThe tool's group it goes to (null: still to create).
2 fields
idstringrequirednamestringrequired
from_groupsobject[]required2 fields
idstringrequirednamestringrequired
emailstring | nullrequiredinvite: the work email the tool sends its invitation to.
waiting_for_confirmbooleanrequiredheld"new_link" | "many"requiredWhy a card block waits for an owner or admin: new_link (the first change to an account Bizisy did not create: is it theirs?), many (many at once).
start_datestring | nullrequiredinvite: the first day; offboard: the last day.
last_errorstring | nullrequiredfailuresintegerrequired
checksobject[]required4 fields
kindstring (enum)requiredTo do in the tool itself (its API can't): leaver_active (left, still active there: deactivate or remove them), invite_manually (starts soon, no account: invite them there), manager_differs / team_differs (the tool says otherwise than Bizisy), approver_missing (the team lead has no account there), approver_differs (Spendesk: the cost centre has an owner the company chose, so Bizisy leaves it), other_team (Pleo: in a team Bizisy does not manage).
One of:
leaver_active,invite_manually,manager_differs,team_differs,approver_missing,approver_differs,other_team.personobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
teamobject | nullrequired2 fields
idstringrequirednamestringrequired
datestring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/spend.preview \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"connector":"payhawk"}'const res = await fetch('https://api.bizisy.com/v1/org/spend.preview', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"connector": "payhawk"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/spend.preview",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"connector": "payhawk",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"started": true,
"read_at": "2026-10-04T10:00:00.000Z",
"items": [
{
"kind": "invite",
"person": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"team": {
"id": "u2",
"name": "Engineering"
},
"group": null,
"from_groups": [],
"email": "ines@acme.test",
"waiting_for_confirm": true,
"held": null,
"start_date": "2026-10-12",
"last_error": null,
"failures": 0
},
{
"kind": "team",
"person": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"team": {
"id": "u2",
"name": "Engineering"
},
"group": {
"id": "t1",
"name": "Engineering"
},
"from_groups": [
{
"id": "t2",
"name": "Sales"
}
],
"email": null,
"waiting_for_confirm": false,
"held": null,
"start_date": null,
"last_error": null,
"failures": 0
}
],
"checks": [
{
"kind": "leaver_active",
"person": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"team": null,
"date": "2026-09-30"
}
]
}
}Teams or cost centres of a spend tool#
POST/v1/org/spend.groupsRead
The teams (Pleo, Moss, Payhawk) or cost centres (Spendesk) of a connected spend tool as Bizisy last read them, to map Bizisy teams onto (settings teams in integrations_connections_update), with whether Bizisy created each one. Read again with integrations_connections_run. Owners, admins and HR; never custom roles. Part of the Finance 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
org_spend_groupson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
connector"pleo" | "moss" | "payhawk" | "spendesk"required
Returns
read_atstring | nullrequiredgroupsobject[]required4 fields
idstringrequirednamestringrequiredarchivedbooleanrequiredcreated_by_bizisybooleanrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/spend.groups \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"connector":"spendesk"}'const res = await fetch('https://api.bizisy.com/v1/org/spend.groups', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"connector": "spendesk"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/spend.groups",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"connector": "spendesk",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"read_at": "2026-10-04T10:00:00.000Z",
"groups": [
{
"id": "cc1",
"name": "Engineering",
"archived": false,
"created_by_bizisy": true
}
]
}
}Start syncing a spend tool#
POST/v1/org/spend.startWrite
After reviewing the plan (org_spend_preview), starts sending it: from now on each run (hourly, and right now) makes the changes the plan lists, except those waiting for a person. Until then Bizisy only reads the tool. Refused before the tool was read once. Owners and admins, in the app only. Part of the Finance 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. An owner or admin starts syncing a spend tool in the app, after reviewing the plan.
- MCP tool
org_spend_starton HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
connector"pleo" | "moss" | "payhawk" | "spendesk"required
Returns
connector"pleo" | "moss" | "payhawk" | "spendesk"requiredstarted_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/spend.start \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"connector":"payhawk"}'const res = await fetch('https://api.bizisy.com/v1/org/spend.start', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"connector": "payhawk"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/spend.start",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"connector": "payhawk",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"connector": "payhawk",
"started_at": "2026-10-04T10:00:00.000Z"
}
}Confirm a spend tool change that waits#
POST/v1/org/spend.confirmWrite
Confirms a change that waits for a person (org_spend_preview waiting_for_confirm): kind invite (Payhawk invites someone starting soon: the tool emails its invitation to their work email), offboard (block a leaver's active cards, held as the first change to an account Bizisy did not create, or as many at once) or approver (the team lead becomes the approver of their team or cost centre: spending authority, so it waits until someone checks the tool account matched by work email is theirs). Held changes and approvers: owners and admins only. Bizisy sends it at once. Nobody confirms a change about themselves. Owners, admins and HR, in the app only. Part of the Finance 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. A person confirms invites and card blocks in the app.
- MCP tool
org_spend_confirmon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
connector"pleo" | "moss" | "payhawk" | "spendesk"requiredperson_idstringrequired1–64 characters.
kind"invite" | "offboard" | "approver"required
Returns
person_idstringrequiredconfirmed"invite" | "offboard" | "approver"required
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/spend.confirm \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"connector":"payhawk","person_id":"p9","kind":"offboard"}'const res = await fetch('https://api.bizisy.com/v1/org/spend.confirm', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"connector": "payhawk",
"person_id": "p9",
"kind": "offboard"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/spend.confirm",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"connector": "payhawk",
"person_id": "p9",
"kind": "offboard",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person_id": "p5",
"confirmed": "invite"
}
}Keep a person out of a spend tool sync#
POST/v1/org/spend.excludeWrite
Excludes a person from a spend tool's sync (excluded true: Bizisy never invites, moves, makes approver or blocks the cards of them there, and lists no checks about them) or includes them again. Nobody keeps themselves out; keeping out someone who has left is for owners and admins. Owners, admins and HR, in the app only. Part of the Finance 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. Excluding someone from a spend tool sync happens in the app.
- MCP tool
org_spend_excludeon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
connector"pleo" | "moss" | "payhawk" | "spendesk"requiredperson_idstringrequired1–64 characters.
excludedbooleanrequired
Returns
person_idstringrequiredexcludedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/spend.exclude \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"connector":"moss","person_id":"p1","excluded":true}'const res = await fetch('https://api.bizisy.com/v1/org/spend.exclude', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"connector": "moss",
"person_id": "p1",
"excluded": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/spend.exclude",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"connector": "moss",
"person_id": "p1",
"excluded": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person_id": "p1",
"excluded": true
}
}Retry a spend tool change that failed#
POST/v1/org/spend.retryWrite
Clears a failure so Bizisy tries again at once (after 3 failures a change waits for this): a person's (person_id) or a team's group change (team_id: creating, renaming or the approver of its team or cost centre). Owners, admins and HR, in the app only. Part of the Finance 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. Retrying a failed change happens in the app.
- MCP tool
org_spend_retryon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
connector"pleo" | "moss" | "payhawk" | "spendesk"requiredperson_idstring1–64 characters.
team_idstring1–64 characters.
Returns
retriedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/spend.retry \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"connector":"payhawk","person_id":"p2"}'const res = await fetch('https://api.bizisy.com/v1/org/spend.retry', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"connector": "payhawk",
"person_id": "p2"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/spend.retry",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"connector": "payhawk",
"person_id": "p2",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"retried": true
}
}Something missing or wrong on this page? Write to hello@bizisy.com.