API reference
Units, locations and legal entities
Divisions, departments and teams, the places people work and the companies that employ them.
22 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
List units (company, divisions, departments, teams)#
POST/v1/org/units.listRead
Lists the org structure as a flat list (root first, then by depth and name). Each unit has parent_id, head (its team lead: the default manager of people who join it, and who approves in place of a missing manager), member_count (people currently assigned directly) and custom (team custom fields you may see: public ones, plus private ones for owners, admins, HR and roles that manage the structure signed in to Bizisy; never over an API key or MCP). Archived units are hidden unless include_archived is true.
- Who can call it
- Manage key any Manage role
Me key anyone - Keys and apps
- Private team custom fields are never returned.
- MCP tool
org_units_liston My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
include_archivedbooleanAlso return archived items.
Default
false.
Returns
An array of objects with 8 fields
An array of objects:
idstringrequirednamestringrequiredkind"company" | "division" | "department" | "team"requiredparent_idstring | nullrequiredheadobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
archivedbooleanrequiredmember_countintegerrequiredcustomobject[]requiredTeam custom fields you may see (public; private ones for owners, admins, HR and roles that manage the structure, in the app).
7 fields
keystringrequiredlabelstringrequiredtypestring (enum)requiredOne of:
text,number,date,select,boolean,file,person,table.tier"public" | "job" | "private"requiredvaluestring | number | boolean | object[]requiredFor type file: the document id (download it with
documents_downloadordocuments_me_download); over an API key or MCP, "attached" for someone else's file. For type person: the person id. For type table: the rows, [{ <column key>: value }] (columns inorg_fields_list).fileobject | nullType file only: the file, or null when none is attached.
4 fields
namestring | nullrequiredThe file name; null over an API key or MCP for someone else's file.
sizeintegerrequiredcontent_typestringrequiredpreviewablebooleanrequiredThe web app can show it (PDF, PNG, JPEG, WebP).
personobject | nullType person only: who it names (null when not set, or not someone you may see).
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/units.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"include_archived":true}'const res = await fetch('https://api.bizisy.com/v1/org/units.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"include_archived": true
}),
});
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/units.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"include_archived": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"id": "u2",
"name": "Engineering",
"kind": "department",
"parent_id": "u1",
"head": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"archived": false,
"member_count": 4,
"custom": [
{
"key": "cost_centre",
"label": "Cost centre",
"type": "text",
"tier": "public",
"value": "CC-100"
}
]
},
{
"id": "u1",
"name": "Acme Lda",
"kind": "company",
"parent_id": null,
"head": null,
"archived": false,
"member_count": 4,
"custom": [
{
"key": "cost_centre",
"label": "Cost centre",
"type": "text",
"tier": "public",
"value": "CC-100"
}
]
}
]
}Create a unit#
POST/v1/org/units.createWrite
Creates a division, department or team. parent_id defaults to the company root. Names are unique (case-insensitive). The kind "company" is reserved for the root. custom sets team custom fields (org_fields_list, target unit), e.g. a cost centre; private ones are refused over an API key or MCP.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Private team custom fields are refused.
- MCP tool
org_units_createon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
namestringrequired1–100 characters.
kind"division" | "department" | "team"requiredparent_idstringhead_person_idstring | nullcustomobjectTeam custom fields (
org_fields_list, target unit) by key; null clears one. Private ones only in Bizisy, never over an API key or MCP.
Returns
8 fields
idstringrequirednamestringrequiredkind"company" | "division" | "department" | "team"requiredparent_idstring | nullrequiredheadobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
archivedbooleanrequiredmember_countintegerrequiredcustomobject[]requiredTeam custom fields you may see (public; private ones for owners, admins, HR and roles that manage the structure, in the app).
7 fields
keystringrequiredlabelstringrequiredtypestring (enum)requiredOne of:
text,number,date,select,boolean,file,person,table.tier"public" | "job" | "private"requiredvaluestring | number | boolean | object[]requiredFor type file: the document id (download it with
documents_downloadordocuments_me_download); over an API key or MCP, "attached" for someone else's file. For type person: the person id. For type table: the rows, [{ <column key>: value }] (columns inorg_fields_list).fileobject | nullType file only: the file, or null when none is attached.
4 fields
namestring | nullrequiredThe file name; null over an API key or MCP for someone else's file.
sizeintegerrequiredcontent_typestringrequiredpreviewablebooleanrequiredThe web app can show it (PDF, PNG, JPEG, WebP).
personobject | nullType person only: who it names (null when not set, or not someone you may see).
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/units.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"name":"Platform","kind":"team","parent_id":"u2","head_person_id":null}'const res = await fetch('https://api.bizisy.com/v1/org/units.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"name": "Platform",
"kind": "team",
"parent_id": "u2",
"head_person_id": 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/org/units.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "Platform",
"kind": "team",
"parent_id": "u2",
"head_person_id": None,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "u2",
"name": "Platform",
"kind": "team",
"parent_id": "u1",
"head": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"archived": false,
"member_count": 4,
"custom": [
{
"key": "cost_centre",
"label": "Cost centre",
"type": "text",
"tier": "public",
"value": "CC-100"
}
]
}
}Rename, move or change a unit#
POST/v1/org/units.updateWrite
Updates a unit: name, kind, parent_id (moves the unit with its whole subtree) or head_person_id (the team lead; null clears it; see org_units_set_head — changing it changes no one's manager). A unit cannot move under itself or its own sub-units; the company root cannot move or change kind. custom changes team custom fields (target unit; null clears one): now only, never with a later effective_date; private ones are refused over an API key or MCP.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Private team custom fields are refused and never returned.
- MCP tool
org_units_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
unit_idstringrequirednamestring1–100 characters.
kind"division" | "department" | "team"parent_idstringhead_person_idstring | nulleffective_datestringWhen it takes effect (YYYY-MM-DD in the company time zone): today or absent changes it now; a later day schedules it (
org_units_changeslists them; applied at 00:00 that day). Past days are refused.customobjectTeam custom fields (
org_fields_list, target unit) by key; null clears one. Private ones only in Bizisy, never over an API key or MCP.
Returns
9 fields
idstringrequirednamestringrequiredkind"company" | "division" | "department" | "team"requiredparent_idstring | nullrequiredheadobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
archivedbooleanrequiredmember_countintegerrequiredcustomobject[]requiredTeam custom fields you may see (public; private ones for owners, admins, HR and roles that manage the structure, in the app).
7 fields
keystringrequiredlabelstringrequiredtypestring (enum)requiredOne of:
text,number,date,select,boolean,file,person,table.tier"public" | "job" | "private"requiredvaluestring | number | boolean | object[]requiredFor type file: the document id (download it with
documents_downloadordocuments_me_download); over an API key or MCP, "attached" for someone else's file. For type person: the person id. For type table: the rows, [{ <column key>: value }] (columns inorg_fields_list).fileobject | nullType file only: the file, or null when none is attached.
4 fields
namestring | nullrequiredThe file name; null over an API key or MCP for someone else's file.
sizeintegerrequiredcontent_typestringrequiredpreviewablebooleanrequiredThe web app can show it (PDF, PNG, JPEG, WebP).
personobject | nullType person only: who it names (null when not set, or not someone you may see).
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
scheduledobject[]requiredChanges scheduled for a later day by this call (effective_date after today); [] when applied now.
9 fields
idstringrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
field"name" | "parent" | "head" | "archive"requiredvaluestring | nullrequiredname: the new name; parent: the new parent unit's name; head: the new team lead's name (null: no lead); archive: null.
effective_datestringrequiredstatus"scheduled" | "applied" | "failed" | "cancelled"requiredproblemstring | nullrequiredWhy it could not apply (failed).
plan_idstring | nullrequiredcreated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/units.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"unit_id": "u2",
"kind": "division",
"parent_id": "u1",
"head_person_id": "p2"
}'const res = await fetch('https://api.bizisy.com/v1/org/units.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"unit_id": "u2",
"kind": "division",
"parent_id": "u1",
"head_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/units.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"unit_id": "u2",
"kind": "division",
"parent_id": "u1",
"head_person_id": "p2",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "u2",
"name": "Engineering",
"kind": "division",
"parent_id": "u1",
"head": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"archived": false,
"member_count": 4,
"custom": [
{
"key": "cost_centre",
"label": "Cost centre",
"type": "text",
"tier": "public",
"value": "CC-100"
}
],
"scheduled": [
{
"id": "uc1",
"unit": {
"id": "u2",
"name": "Engineering"
},
"field": "name",
"value": "Platform",
"effective_date": "2026-11-01",
"status": "scheduled",
"problem": null,
"plan_id": null,
"created_at": "2026-10-04T10:00:00.000Z"
}
]
}
}Set or remove the team lead of a unit#
POST/v1/org/units.set_headWrite
Sets the team lead of a unit (the company, a division, department or team), effective now; person_id null removes the team lead. What a team lead means: people who join the unit later (hire, rehire, a job change into it, CSV import, org_setup_apply) get the lead as manager when no manager is given (the lead joining their own unit gets the parent unit's lead), and when Settings → Approval rules asks the manager to approve a change about someone with no manager, the lead of their unit (or of a unit above) decides before HR. Setting a lead changes no one's manager today: people already in the unit keep theirs. The lead must work here today or be starting later (people who have left are refused), and an archived unit cannot get a new lead. One person may lead several units. It never needs approval and the person keeps their own team. To also move the person into the unit, call org_people_change_job with unit_id and an explicit manager_id (that is a job change and follows Settings → Approval rules; without manager_id the unit's current lead would become their manager). Returns the unit, previous_head (who stopped being lead, or null), also_heads (other units this person already leads) and changed (false when that person was already the lead: nothing was written). Leads have history: org_chart_get as of a past date shows the lead of that date (org_units_history). effective_date: a later day schedules the change instead (applied at 00:00 that day, with the same checks then). Owners, admins and HR only.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_units_set_headon 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
unit_idstringrequiredperson_idstring | nullrequiredThe new team lead (
org_people_list), or null to remove the team lead.effective_datestringWhen it takes effect (YYYY-MM-DD in the company time zone): today or absent changes it now; a later day schedules it (
org_units_changeslists them; applied at 00:00 that day). Past days are refused.
Returns
12 fields
idstringrequirednamestringrequiredkind"company" | "division" | "department" | "team"requiredparent_idstring | nullrequiredheadobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
archivedbooleanrequiredmember_countintegerrequiredcustomobject[]requiredTeam custom fields you may see (public; private ones for owners, admins, HR and roles that manage the structure, in the app).
7 fields
keystringrequiredlabelstringrequiredtypestring (enum)requiredOne of:
text,number,date,select,boolean,file,person,table.tier"public" | "job" | "private"requiredvaluestring | number | boolean | object[]requiredFor type file: the document id (download it with
documents_downloadordocuments_me_download); over an API key or MCP, "attached" for someone else's file. For type person: the person id. For type table: the rows, [{ <column key>: value }] (columns inorg_fields_list).fileobject | nullType file only: the file, or null when none is attached.
4 fields
namestring | nullrequiredThe file name; null over an API key or MCP for someone else's file.
sizeintegerrequiredcontent_typestringrequiredpreviewablebooleanrequiredThe web app can show it (PDF, PNG, JPEG, WebP).
personobject | nullType person only: who it names (null when not set, or not someone you may see).
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
previous_headobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
also_headsobject[]required2 fields
idstringrequirednamestringrequired
changedbooleanrequiredscheduledobject[]requiredChanges scheduled for a later day by this call (effective_date after today); [] when applied now.
9 fields
idstringrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
field"name" | "parent" | "head" | "archive"requiredvaluestring | nullrequiredname: the new name; parent: the new parent unit's name; head: the new team lead's name (null: no lead); archive: null.
effective_datestringrequiredstatus"scheduled" | "applied" | "failed" | "cancelled"requiredproblemstring | nullrequiredWhy it could not apply (failed).
plan_idstring | nullrequiredcreated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/units.set_head \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"unit_id":"u2","person_id":"p2","effective_date":"2026-11-01"}'const res = await fetch('https://api.bizisy.com/v1/org/units.set_head', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"unit_id": "u2",
"person_id": "p2",
"effective_date": "2026-11-01"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/units.set_head",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"unit_id": "u2",
"person_id": "p2",
"effective_date": "2026-11-01",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "u2",
"name": "Engineering",
"kind": "department",
"parent_id": "u1",
"head": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"archived": false,
"member_count": 4,
"custom": [
{
"key": "cost_centre",
"label": "Cost centre",
"type": "text",
"tier": "public",
"value": "CC-100"
}
],
"previous_head": {
"id": "p9",
"name": "Lukas Weber",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"also_heads": [
{
"id": "u3",
"name": "Web"
}
],
"changed": true,
"scheduled": []
}
}Archive a unit#
POST/v1/org/units.archiveDestructive
Archives a unit that has no active sub-units. People already assigned keep the assignment, but nobody new can be assigned. The company root cannot be archived. Units are never deleted.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_units_archiveon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
unit_idstringrequiredeffective_datestringWhen it takes effect (YYYY-MM-DD in the company time zone): today or absent changes it now; a later day schedules it (
org_units_changeslists them; applied at 00:00 that day). Past days are refused.
Returns
9 fields
idstringrequirednamestringrequiredkind"company" | "division" | "department" | "team"requiredparent_idstring | nullrequiredheadobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
archivedbooleanrequiredmember_countintegerrequiredcustomobject[]requiredTeam custom fields you may see (public; private ones for owners, admins, HR and roles that manage the structure, in the app).
7 fields
keystringrequiredlabelstringrequiredtypestring (enum)requiredOne of:
text,number,date,select,boolean,file,person,table.tier"public" | "job" | "private"requiredvaluestring | number | boolean | object[]requiredFor type file: the document id (download it with
documents_downloadordocuments_me_download); over an API key or MCP, "attached" for someone else's file. For type person: the person id. For type table: the rows, [{ <column key>: value }] (columns inorg_fields_list).fileobject | nullType file only: the file, or null when none is attached.
4 fields
namestring | nullrequiredThe file name; null over an API key or MCP for someone else's file.
sizeintegerrequiredcontent_typestringrequiredpreviewablebooleanrequiredThe web app can show it (PDF, PNG, JPEG, WebP).
personobject | nullType person only: who it names (null when not set, or not someone you may see).
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
scheduledobject[]requiredChanges scheduled for a later day by this call (effective_date after today); [] when applied now.
9 fields
idstringrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
field"name" | "parent" | "head" | "archive"requiredvaluestring | nullrequiredname: the new name; parent: the new parent unit's name; head: the new team lead's name (null: no lead); archive: null.
effective_datestringrequiredstatus"scheduled" | "applied" | "failed" | "cancelled"requiredproblemstring | nullrequiredWhy it could not apply (failed).
plan_idstring | nullrequiredcreated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/units.archive \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"unit_id":"u2","effective_date":"2026-12-01"}'const res = await fetch('https://api.bizisy.com/v1/org/units.archive', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"unit_id": "u2",
"effective_date": "2026-12-01"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/units.archive",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"unit_id": "u2",
"effective_date": "2026-12-01",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "u2",
"name": "Engineering",
"kind": "department",
"parent_id": "u1",
"head": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"archived": true,
"member_count": 4,
"custom": [
{
"key": "cost_centre",
"label": "Cost centre",
"type": "text",
"tier": "public",
"value": "CC-100"
}
],
"scheduled": []
}
}Scheduled structure changes#
POST/v1/org/units.changesRead
Unit changes scheduled for later days (renames, moves, team lead changes and archiving, from org_units_update, org_units_set_head or org_units_archive with effective_date, or a reorg plan): status scheduled (default) or all (also applied, failed with why, and cancelled in the last 90 days), soonest first. They are not announced yet: owners, admins and HR, and roles that edit the structure.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_units_changeson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
status"scheduled" | "all"Default
"scheduled".unit_idstring
Returns
An array of objects with 9 fields
An array of objects:
idstringrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
field"name" | "parent" | "head" | "archive"requiredvaluestring | nullrequiredname: the new name; parent: the new parent unit's name; head: the new team lead's name (null: no lead); archive: null.
effective_datestringrequiredstatus"scheduled" | "applied" | "failed" | "cancelled"requiredproblemstring | nullrequiredWhy it could not apply (failed).
plan_idstring | nullrequiredcreated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/units.changes \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status":"all","unit_id":"u2"}'const res = await fetch('https://api.bizisy.com/v1/org/units.changes', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"status": "all",
"unit_id": "u2"
}),
});
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/units.changes",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"status": "all",
"unit_id": "u2",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"id": "uc1",
"unit": {
"id": "u2",
"name": "Engineering"
},
"field": "name",
"value": "Platform",
"effective_date": "2026-11-01",
"status": "scheduled",
"problem": null,
"plan_id": null,
"created_at": "2026-10-04T10:00:00.000Z"
},
{
"id": "uc2",
"unit": {
"id": "u2",
"name": "Engineering"
},
"field": "head",
"value": "Rui Costa",
"effective_date": "2026-11-01",
"status": "failed",
"problem": "This person has left. Choose someone who works here now or is starting.",
"plan_id": null,
"created_at": "2026-10-04T10:00:00.000Z"
}
]
}Cancel a scheduled structure change#
POST/v1/org/units.cancel_changeWrite
Cancels a unit change scheduled for a later day (org_units_changes): nothing changes on that day. Owners, admins and HR, and roles that edit the structure (renames and archiving only).
- Who can call it
- Manage key owner admin hr
- MCP tool
org_units_cancel_changeon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
change_idstringrequired
Returns
9 fields
idstringrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
field"name" | "parent" | "head" | "archive"requiredvaluestring | nullrequiredname: the new name; parent: the new parent unit's name; head: the new team lead's name (null: no lead); archive: null.
effective_datestringrequiredstatus"scheduled" | "applied" | "failed" | "cancelled"requiredproblemstring | nullrequiredWhy it could not apply (failed).
plan_idstring | nullrequiredcreated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/units.cancel_change \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"change_id":"uc1"}'const res = await fetch('https://api.bizisy.com/v1/org/units.cancel_change', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"change_id": "uc1"
}),
});
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/units.cancel_change",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"change_id": "uc1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "uc1",
"unit": {
"id": "u2",
"name": "Engineering"
},
"field": "name",
"value": "Platform",
"effective_date": "2026-11-01",
"status": "cancelled",
"problem": null,
"plan_id": null,
"created_at": "2026-10-04T10:00:00.000Z"
}
}A unit's history#
POST/v1/org/units.historyRead
The earlier states of a unit (name, kind, parent, team lead, archived) with the days each held (valid_to exclusive; null: still so), oldest first. A unit that has not changed since dated structure shipped has one entry, from its creation. For what is scheduled next, see org_units_changes.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
org_units_historyon My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
unit_idstringrequired
Returns
An array of objects with 7 fields
An array of objects:
valid_fromstringrequiredvalid_tostring | nullrequirednamestringrequiredkind"company" | "division" | "department" | "team"requiredparentobject | nullrequired2 fields
idstringrequirednamestringrequired
headobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
archivedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/units.history \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"unit_id":"u2"}'const res = await fetch('https://api.bizisy.com/v1/org/units.history', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"unit_id": "u2"
}),
});
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/units.history",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"unit_id": "u2",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"valid_from": "2025-01-01",
"valid_to": "2026-10-04",
"name": "Engineering",
"kind": "department",
"parent": {
"id": "u1",
"name": "Acme Lda"
},
"head": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"archived": false
},
{
"valid_from": "2026-10-04",
"valid_to": null,
"name": "Product Engineering",
"kind": "department",
"parent": {
"id": "u1",
"name": "Acme Lda"
},
"head": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"archived": false
}
]
}List locations#
POST/v1/org/locations.listRead
Lists offices and remote locations with country, city and time zone, oldest first. The first location sets the company time zone used for "today".
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
org_locations_liston My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
include_archivedbooleanAlso return archived items.
Default
false.
Returns
An array of objects with 8 fields
An array of objects:
idstringrequirednamestringrequiredcountrystringrequiredregionstring | nullrequiredState or province code for public holidays; null: national only.
citystring | nullrequiredtimezonestringrequiredremotebooleanrequiredarchivedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/locations.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"include_archived":true}'const res = await fetch('https://api.bizisy.com/v1/org/locations.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"include_archived": true
}),
});
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/locations.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"include_archived": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"id": "l1",
"name": "Head office",
"country": "PT",
"region": null,
"city": "Lisboa",
"timezone": "Europe/Lisbon",
"remote": false,
"archived": false
}
]
}Create a location#
POST/v1/org/locations.createWrite
Creates a location. country is a 2-letter code; timezone defaults from the country (e.g. PT → Europe/Lisbon); region (optional) is the state or province code whose public holidays apply there. Names are unique.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_locations_createon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
namestringrequired1–100 characters.
countryanyrequiredcitystring | nullUp to 100 characters.
timezonestringremotebooleanregionany | nullThe state or province for public holidays, as its code within the country (e.g. MD for Madrid in ES, BY for Bavaria in DE); null: the national holidays only.
Returns
8 fields
idstringrequirednamestringrequiredcountrystringrequiredregionstring | nullrequiredState or province code for public holidays; null: national only.
citystring | nullrequiredtimezonestringrequiredremotebooleanrequiredarchivedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/locations.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Remote EU",
"country": "DE",
"city": null,
"timezone": "Europe/Berlin",
"remote": true
}'const res = await fetch('https://api.bizisy.com/v1/org/locations.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"name": "Remote EU",
"country": "DE",
"city": null,
"timezone": "Europe/Berlin",
"remote": 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/locations.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "Remote EU",
"country": "DE",
"city": None,
"timezone": "Europe/Berlin",
"remote": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "l1",
"name": "Remote EU",
"country": "DE",
"region": null,
"city": null,
"timezone": "Europe/Berlin",
"remote": true,
"archived": false
}
}Update a location#
POST/v1/org/locations.updateWrite
Changes the name, country, region, city, time zone or remote flag of a location (changing the country clears the region unless one is sent).
- Who can call it
- Manage key owner admin hr
- MCP tool
org_locations_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
location_idstringrequirednamestring1–100 characters.
countryanycitystring | nullUp to 100 characters.
timezonestringremotebooleanregionany | nullThe state or province for public holidays, as its code within the country (e.g. MD for Madrid in ES, BY for Bavaria in DE); null: the national holidays only.
Returns
8 fields
idstringrequirednamestringrequiredcountrystringrequiredregionstring | nullrequiredState or province code for public holidays; null: national only.
citystring | nullrequiredtimezonestringrequiredremotebooleanrequiredarchivedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/locations.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"location_id": "l1",
"country": "PT",
"city": "Lisboa",
"timezone": "Europe/Lisbon",
"remote": false
}'const res = await fetch('https://api.bizisy.com/v1/org/locations.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"location_id": "l1",
"country": "PT",
"city": "Lisboa",
"timezone": "Europe/Lisbon",
"remote": false
}),
});
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/locations.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"location_id": "l1",
"country": "PT",
"city": "Lisboa",
"timezone": "Europe/Lisbon",
"remote": False,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "l1",
"name": "Head office",
"country": "PT",
"region": null,
"city": "Lisboa",
"timezone": "Europe/Lisbon",
"remote": false,
"archived": false
}
}Archive a location#
POST/v1/org/locations.archiveDestructive
Archives a location: people keep it, but nobody new can be assigned to it. Locations are never deleted.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_locations_archiveon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
location_idstringrequired
Returns
8 fields
idstringrequirednamestringrequiredcountrystringrequiredregionstring | nullrequiredState or province code for public holidays; null: national only.
citystring | nullrequiredtimezonestringrequiredremotebooleanrequiredarchivedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/locations.archive \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"location_id":"l1"}'const res = await fetch('https://api.bizisy.com/v1/org/locations.archive', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"location_id": "l1"
}),
});
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/locations.archive",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"location_id": "l1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "l1",
"name": "Head office",
"country": "PT",
"region": null,
"city": "Lisboa",
"timezone": "Europe/Lisbon",
"remote": false,
"archived": true
}
}List legal entities#
POST/v1/org/entities.listRead
Lists the legal entities (employing companies) with country, tax id and postal address (null when not set), oldest first.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
org_entities_liston My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
include_archivedbooleanAlso return archived items.
Default
false.
Returns
An array of objects with 11 fields
An array of objects:
idstringrequiredlegal_namestringrequiredcountrystringrequiredtax_idstring | nullrequiredarchivedbooleanrequiredaddressobject | nullrequiredThe registered postal address (the country is country); null when not set. Shown in the candidate privacy notice and on offer letters.
5 fields
line1stringrequiredStreet and number.
line2string | nullrequiredFloor, building or other detail.
postal_codestring | nullrequiredcitystringrequiredregionstring | nullrequiredState, province or region, where the address uses one.
collective_agreementstring | nullrequiredThe collective agreement that applies (document templates: {{employer.collective_agreement}}); null when none or not set.
collective_agreement_codestring | nullrequiredIts official code (e.g. the Spanish REGCON code); null when not set.
accident_insurerstring | nullrequiredThe workplace-accident insurer (required in Portuguese contracts); null when not set.
accident_policystring | nullrequiredThe workplace-accident policy number; null when not set.
social_securitystring | nullrequiredThe social security institution(s) the employer pays contributions to; null when not set.
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/entities.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"include_archived":true}'const res = await fetch('https://api.bizisy.com/v1/org/entities.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"include_archived": true
}),
});
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/entities.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"include_archived": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"id": "e1",
"legal_name": "Acme Lda",
"country": "PT",
"tax_id": null,
"archived": false,
"address": null,
"collective_agreement": null,
"collective_agreement_code": null,
"accident_insurer": "Fidelidade",
"accident_policy": "AT-123",
"social_security": null
}
]
}Create a legal entity#
POST/v1/org/entities.createWrite
Creates a legal entity (an employing company) with its 2-letter country, optional tax id and optional postal address {line1 (street and number), line2, postal_code, city, region} (line1 and city required when an address is given). The address is shown in the candidate privacy notice and on offer letters ({{employer_address}}). Optional document details (used by document templates, e.g. {{employer.accident_insurer}}): collective_agreement, collective_agreement_code, accident_insurer, accident_policy, social_security.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_entities_createon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
legal_namestringrequired1–200 characters.
countryanyrequiredtax_idstring | nullUp to 40 characters.
addressobject | null5 fields
line1stringrequiredStreet and number.
1–200 characters.
line2string | nullFloor, building or other detail (optional).
Up to 200 characters.
postal_codestring | nullPostal code (optional: some countries have none).
Up to 20 characters.
citystringrequired1–100 characters.
regionstring | nullState, province or region, where the address uses one (optional).
Up to 100 characters.
collective_agreementstring | nullThe collective agreement that applies, as documents name it (null clears it).
Up to 300 characters.
collective_agreement_codestring | nullIts official code, e.g. the Spanish REGCON code (null clears it).
Up to 60 characters.
accident_insurerstring | nullThe workplace-accident insurer (Portugal: required in contracts).
Up to 200 characters.
accident_policystring | nullThe workplace-accident policy number.
Up to 80 characters.
social_securitystring | nullThe social security institution(s) the employer pays contributions to.
Up to 300 characters.
Returns
11 fields
idstringrequiredlegal_namestringrequiredcountrystringrequiredtax_idstring | nullrequiredarchivedbooleanrequiredaddressobject | nullrequiredThe registered postal address (the country is country); null when not set. Shown in the candidate privacy notice and on offer letters.
5 fields
line1stringrequiredStreet and number.
line2string | nullrequiredFloor, building or other detail.
postal_codestring | nullrequiredcitystringrequiredregionstring | nullrequiredState, province or region, where the address uses one.
collective_agreementstring | nullrequiredThe collective agreement that applies (document templates: {{employer.collective_agreement}}); null when none or not set.
collective_agreement_codestring | nullrequiredIts official code (e.g. the Spanish REGCON code); null when not set.
accident_insurerstring | nullrequiredThe workplace-accident insurer (required in Portuguese contracts); null when not set.
accident_policystring | nullrequiredThe workplace-accident policy number; null when not set.
social_securitystring | nullrequiredThe social security institution(s) the employer pays contributions to; null when not set.
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/entities.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"legal_name": "Acme GmbH",
"country": "DE",
"address": {
"line1": "Torstraße 1",
"line2": null,
"postal_code": "10119",
"city": "Berlin",
"region": null
}
}'const res = await fetch('https://api.bizisy.com/v1/org/entities.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"legal_name": "Acme GmbH",
"country": "DE",
"address": {
"line1": "Torstraße 1",
"line2": null,
"postal_code": "10119",
"city": "Berlin",
"region": 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/org/entities.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"legal_name": "Acme GmbH",
"country": "DE",
"address": {
"line1": "Torstraße 1",
"line2": None,
"postal_code": "10119",
"city": "Berlin",
"region": None,
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "e1",
"legal_name": "Acme GmbH",
"country": "DE",
"tax_id": null,
"archived": false,
"address": null,
"collective_agreement": null,
"collective_agreement_code": null,
"accident_insurer": "Fidelidade",
"accident_policy": "AT-123",
"social_security": null
}
}Update a legal entity#
POST/v1/org/entities.updateWrite
Changes the legal name, country, tax id or postal address of a legal entity; send only what changes. address: {line1 (street and number), line2, postal_code, city, region}, the whole address each time (line1 and city required); null removes it. Optional document details (used by document templates, e.g. {{employer.accident_insurer}}): collective_agreement, collective_agreement_code, accident_insurer, accident_policy, social_security.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_entities_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
legal_entity_idstringrequiredlegal_namestring1–200 characters.
countryanytax_idstring | nullUp to 40 characters.
addressobject | null5 fields
line1stringrequiredStreet and number.
1–200 characters.
line2string | nullFloor, building or other detail (optional).
Up to 200 characters.
postal_codestring | nullPostal code (optional: some countries have none).
Up to 20 characters.
citystringrequired1–100 characters.
regionstring | nullState, province or region, where the address uses one (optional).
Up to 100 characters.
collective_agreementstring | nullThe collective agreement that applies, as documents name it (null clears it).
Up to 300 characters.
collective_agreement_codestring | nullIts official code, e.g. the Spanish REGCON code (null clears it).
Up to 60 characters.
accident_insurerstring | nullThe workplace-accident insurer (Portugal: required in contracts).
Up to 200 characters.
accident_policystring | nullThe workplace-accident policy number.
Up to 80 characters.
social_securitystring | nullThe social security institution(s) the employer pays contributions to.
Up to 300 characters.
Returns
11 fields
idstringrequiredlegal_namestringrequiredcountrystringrequiredtax_idstring | nullrequiredarchivedbooleanrequiredaddressobject | nullrequiredThe registered postal address (the country is country); null when not set. Shown in the candidate privacy notice and on offer letters.
5 fields
line1stringrequiredStreet and number.
line2string | nullrequiredFloor, building or other detail.
postal_codestring | nullrequiredcitystringrequiredregionstring | nullrequiredState, province or region, where the address uses one.
collective_agreementstring | nullrequiredThe collective agreement that applies (document templates: {{employer.collective_agreement}}); null when none or not set.
collective_agreement_codestring | nullrequiredIts official code (e.g. the Spanish REGCON code); null when not set.
accident_insurerstring | nullrequiredThe workplace-accident insurer (required in Portuguese contracts); null when not set.
accident_policystring | nullrequiredThe workplace-accident policy number; null when not set.
social_securitystring | nullrequiredThe social security institution(s) the employer pays contributions to; null when not set.
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/entities.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"legal_entity_id": "e1",
"accident_insurer": "Fidelidade",
"accident_policy": "AT-123",
"collective_agreement": null,
"collective_agreement_code": "C-77",
"social_security": "Segurança Social"
}'const res = await fetch('https://api.bizisy.com/v1/org/entities.update', {
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",
"accident_insurer": "Fidelidade",
"accident_policy": "AT-123",
"collective_agreement": null,
"collective_agreement_code": "C-77",
"social_security": "Segurança Social"
}),
});
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/entities.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"legal_entity_id": "e1",
"accident_insurer": "Fidelidade",
"accident_policy": "AT-123",
"collective_agreement": None,
"collective_agreement_code": "C-77",
"social_security": "Segurança Social",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "e1",
"legal_name": "Acme Lda",
"country": "PT",
"tax_id": "PT123456789",
"archived": false,
"address": {
"line1": "Rua do Souto 10",
"line2": "2.º andar",
"postal_code": "4700-329",
"city": "Braga",
"region": null
},
"collective_agreement": null,
"collective_agreement_code": "C-77",
"accident_insurer": "Fidelidade",
"accident_policy": "AT-123",
"social_security": "Segurança Social"
}
}Archive a legal entity#
POST/v1/org/entities.archiveDestructive
Archives a legal entity: existing job rows keep it, but nobody new can be assigned to it.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_entities_archiveon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
legal_entity_idstringrequired
Returns
11 fields
idstringrequiredlegal_namestringrequiredcountrystringrequiredtax_idstring | nullrequiredarchivedbooleanrequiredaddressobject | nullrequiredThe registered postal address (the country is country); null when not set. Shown in the candidate privacy notice and on offer letters.
5 fields
line1stringrequiredStreet and number.
line2string | nullrequiredFloor, building or other detail.
postal_codestring | nullrequiredcitystringrequiredregionstring | nullrequiredState, province or region, where the address uses one.
collective_agreementstring | nullrequiredThe collective agreement that applies (document templates: {{employer.collective_agreement}}); null when none or not set.
collective_agreement_codestring | nullrequiredIts official code (e.g. the Spanish REGCON code); null when not set.
accident_insurerstring | nullrequiredThe workplace-accident insurer (required in Portuguese contracts); null when not set.
accident_policystring | nullrequiredThe workplace-accident policy number; null when not set.
social_securitystring | nullrequiredThe social security institution(s) the employer pays contributions to; null when not set.
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/entities.archive \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"legal_entity_id":"e1"}'const res = await fetch('https://api.bizisy.com/v1/org/entities.archive', {
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"
}),
});
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/entities.archive",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"legal_entity_id": "e1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "e1",
"legal_name": "Acme Lda",
"country": "PT",
"tax_id": null,
"archived": true,
"address": null,
"collective_agreement": null,
"collective_agreement_code": null,
"accident_insurer": "Fidelidade",
"accident_policy": "AT-123",
"social_security": null
}
}Reorg plans#
POST/v1/org/plans.listRead
Reorg and what-if plans: drafts first (newest first), then applied and discarded ones. Each has its effective date, its changes in words and how many people it moves. Reorg plans are confidential: owners, admins and HR only (never custom roles); the people in them see nothing until it is applied.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_plans_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
plansobject[]required12 fields
idstringrequirednamestringrequirednotestring | nullrequiredeffective_datestringrequiredstatus"draft" | "applied" | "discarded"requiredchangesany[]requiredThe changes, as saved.
linesstring[]requiredEach change in words, in order.
people_movedintegerrequiredprepared_bystring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredapplied_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/plans.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/plans.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/plans.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": {
"plans": [
{
"id": "pl1",
"name": "Platform split",
"note": "Q4",
"effective_date": "2026-11-01",
"status": "draft",
"changes": [
{
"type": "create_team",
"key": "plat",
"name": "Platform",
"parent_id": "u2"
},
{
"type": "move",
"person_ids": [
"p2"
],
"unit_id": "new:plat",
"manager_id": "p3"
}
],
"lines": [
"Create Platform under Engineering",
"Move Rui Costa to Platform, reporting to Sofia Costa"
],
"people_moved": 1,
"prepared_by": "Ana Ferreira",
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:00:00.000Z",
"applied_at": null
}
]
}
}Get a reorg plan#
POST/v1/org/plans.getRead
One reorg plan with its changes. Compare it with org_plans_compare; apply it with org_plans_apply. Reorg plans are confidential: owners, admins and HR only (never custom roles); the people in them see nothing until it is applied.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_plans_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
plan_idstringrequired
Returns
12 fields
idstringrequirednamestringrequirednotestring | nullrequiredeffective_datestringrequiredstatus"draft" | "applied" | "discarded"requiredchangesany[]requiredThe changes, as saved.
linesstring[]requiredEach change in words, in order.
people_movedintegerrequiredprepared_bystring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredapplied_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/plans.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"plan_id":"pl1"}'const res = await fetch('https://api.bizisy.com/v1/org/plans.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"plan_id": "pl1"
}),
});
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/plans.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"plan_id": "pl1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "pl1",
"name": "Platform split",
"note": "Q4",
"effective_date": "2026-11-01",
"status": "draft",
"changes": [
{
"type": "create_team",
"key": "plat",
"name": "Platform",
"parent_id": "u2"
},
{
"type": "move",
"person_ids": [
"p2"
],
"unit_id": "new:plat",
"manager_id": "p3"
}
],
"lines": [
"Create Platform under Engineering",
"Move Rui Costa to Platform, reporting to Sofia Costa"
],
"people_moved": 1,
"prepared_by": "Ana Ferreira",
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:00:00.000Z",
"applied_at": null
}
}Save a reorg plan#
POST/v1/org/plans.saveWrite
Creates or (with plan_id) replaces a draft reorg plan: a name, an effective_date (YYYY-MM-DD, today or later) and up to 200 changes, in order: move {person_ids, unit_id?, manager_id?} (at most 50 people each), create_team {key, name, kind?, parent_id?} (later changes name it as "new:<key>"), rename_team {unit_id, name}, move_team {unit_id, parent_id}, archive_team {unit_id}, set_lead {unit_id, person_id or null}. Nothing changes until it is applied (org_plans_apply); several plans can exist side by side (at most 20 drafts). Reorg plans are confidential: owners, admins and HR only (never custom roles); the people in them see nothing until it is applied.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_plans_saveon 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
plan_idstringnamestringrequired1–100 characters.
notestring | nullUp to 1000 characters.
effective_datestringrequiredchangesobject[]requiredUp to 200 items.
20 fields (one of several shapes)
Option 1
type"move"requiredperson_idsstring[]required1–50 items.
unit_idstring1–60 characters.
manager_idstring | null
Option 2
type"create_team"requiredkeystringrequiredPattern
^[a-z0-9_-]{1,30}$.namestringrequired1–100 characters.
kind"division" | "department" | "team"Default
"team".parent_idstring1–60 characters.
Option 3
type"rename_team"requiredunit_idstringrequired1–60 characters.
namestringrequired1–100 characters.
Option 4
type"move_team"requiredunit_idstringrequired1–60 characters.
parent_idstringrequired1–60 characters.
Option 5
type"archive_team"requiredunit_idstringrequired1–60 characters.
Option 6
type"set_lead"requiredunit_idstringrequired1–60 characters.
person_idstring | nullrequired
Returns
12 fields
idstringrequirednamestringrequirednotestring | nullrequiredeffective_datestringrequiredstatus"draft" | "applied" | "discarded"requiredchangesany[]requiredThe changes, as saved.
linesstring[]requiredEach change in words, in order.
people_movedintegerrequiredprepared_bystring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredapplied_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/plans.save \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Platform split",
"effective_date": "2026-11-01",
"note": "Q4",
"changes": [
{
"type": "create_team",
"key": "plat",
"name": "Platform",
"kind": "team",
"parent_id": "u2"
},
{
"type": "move",
"person_ids": [
"p2"
],
"unit_id": "new:plat",
"manager_id": "p3"
},
{
"type": "rename_team",
"unit_id": "u2",
"name": "Product Engineering"
},
{
"type": "move_team",
"unit_id": "u3",
"parent_id": "u2"
},
{
"type": "archive_team",
"unit_id": "u4"
},
{
"type": "set_lead",
"unit_id": "new:plat",
"person_id": "p3"
}
]
}'const res = await fetch('https://api.bizisy.com/v1/org/plans.save', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"name": "Platform split",
"effective_date": "2026-11-01",
"note": "Q4",
"changes": [
{
"type": "create_team",
"key": "plat",
"name": "Platform",
"kind": "team",
"parent_id": "u2"
},
{
"type": "move",
"person_ids": [
"p2"
],
"unit_id": "new:plat",
"manager_id": "p3"
},
{
"type": "rename_team",
"unit_id": "u2",
"name": "Product Engineering"
},
{
"type": "move_team",
"unit_id": "u3",
"parent_id": "u2"
},
{
"type": "archive_team",
"unit_id": "u4"
},
{
"type": "set_lead",
"unit_id": "new:plat",
"person_id": "p3"
}
]
}),
});
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/plans.save",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "Platform split",
"effective_date": "2026-11-01",
"note": "Q4",
"changes": [
{
"type": "create_team",
"key": "plat",
"name": "Platform",
"kind": "team",
"parent_id": "u2",
},
{
"type": "move",
"person_ids": [
"p2",
],
"unit_id": "new:plat",
"manager_id": "p3",
},
{
"type": "rename_team",
"unit_id": "u2",
"name": "Product Engineering",
},
{
"type": "move_team",
"unit_id": "u3",
"parent_id": "u2",
},
{
"type": "archive_team",
"unit_id": "u4",
},
{
"type": "set_lead",
"unit_id": "new:plat",
"person_id": "p3",
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "pl1",
"name": "Platform split",
"note": "Q4",
"effective_date": "2026-11-01",
"status": "draft",
"changes": [
{
"type": "create_team",
"key": "plat",
"name": "Platform",
"parent_id": "u2"
},
{
"type": "move",
"person_ids": [
"p2"
],
"unit_id": "new:plat",
"manager_id": "p3"
}
],
"lines": [
"Create Platform under Engineering",
"Move Rui Costa to Platform, reporting to Sofia Costa"
],
"people_moved": 1,
"prepared_by": "Ana Ferreira",
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:00:00.000Z",
"applied_at": null
}
}Discard a reorg plan#
POST/v1/org/plans.discardWrite
Discards a draft plan: nothing in it is applied. Reorg plans are confidential: owners, admins and HR only (never custom roles); the people in them see nothing until it is applied.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_plans_discardon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
plan_idstringrequired
Returns
12 fields
idstringrequirednamestringrequirednotestring | nullrequiredeffective_datestringrequiredstatus"draft" | "applied" | "discarded"requiredchangesany[]requiredThe changes, as saved.
linesstring[]requiredEach change in words, in order.
people_movedintegerrequiredprepared_bystring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredapplied_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/plans.discard \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"plan_id":"pl1"}'const res = await fetch('https://api.bizisy.com/v1/org/plans.discard', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"plan_id": "pl1"
}),
});
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/plans.discard",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"plan_id": "pl1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "pl1",
"name": "Platform split",
"note": "Q4",
"effective_date": "2026-11-01",
"status": "discarded",
"changes": [
{
"type": "create_team",
"key": "plat",
"name": "Platform",
"parent_id": "u2"
},
{
"type": "move",
"person_ids": [
"p2"
],
"unit_id": "new:plat",
"manager_id": "p3"
}
],
"lines": [
"Create Platform under Engineering",
"Move Rui Costa to Platform, reporting to Sofia Costa"
],
"people_moved": 1,
"prepared_by": "Ana Ferreira",
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:00:00.000Z",
"applied_at": null
}
}Compare a reorg plan#
POST/v1/org/plans.compareRead
What a plan would change on its effective date, compared with the organization that day without it — nothing is written: every team (new, archived, changed or the same) with its people directly in it and in it and below, and its lead, before and after; managers whose number of direct reports changes; each person who moves (team and manager, before and after); and warnings (a team archived with people still in it, someone reporting to a person not employed then). Rules and approvals are checked when it is applied (org_plans_apply with dry_run). Reorg plans are confidential: owners, admins and HR only (never custom roles); the people in them see nothing until it is applied.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_plans_compareon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
plan_idstringrequired
Returns
effective_datestringrequiredteamsobject[]required6 fields
idstringrequiredA team id, or new:<key> for a team the plan creates.
namestringrequiredparentstring | nullrequiredstate"new" | "archived" | "changed" | "same"requiredbeforeobjectrequired4 fields
directintegerrequiredtotalintegerrequiredleadstring | nullrequirednamestring | nullrequired
afterobjectrequired3 fields
directintegerrequiredtotalintegerrequiredleadstring | nullrequired
managersobject[]requiredPeople whose number of direct reports changes.
3 fields
personobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
beforeintegerrequiredafterintegerrequired
movesobject[]required5 fields
personobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
from_teamstring | nullrequiredto_teamstring | nullrequiredfrom_managerstring | nullrequiredto_managerstring | nullrequired
warningsstring[]required
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/plans.compare \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"plan_id":"pl1"}'const res = await fetch('https://api.bizisy.com/v1/org/plans.compare', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"plan_id": "pl1"
}),
});
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/plans.compare",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"plan_id": "pl1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"effective_date": "2026-11-01",
"teams": [
{
"id": "new:plat",
"name": "Platform",
"parent": "Engineering",
"state": "new",
"before": {
"direct": 0,
"total": 0,
"lead": null,
"name": null
},
"after": {
"direct": 3,
"total": 3,
"lead": "Rui Costa"
}
},
{
"id": "u2",
"name": "Engineering",
"parent": "Acme Lda",
"state": "changed",
"before": {
"direct": 8,
"total": 8,
"lead": "Rui Costa",
"name": null
},
"after": {
"direct": 5,
"total": 8,
"lead": "Rui Costa"
}
}
],
"managers": [
{
"person": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"before": 6,
"after": 3
}
],
"moves": [
{
"person": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"from_team": "Engineering",
"to_team": "Platform",
"from_manager": "Ana Ferreira",
"to_manager": "Rui Costa"
}
],
"warnings": []
}
}Apply a reorg plan#
POST/v1/org/plans.applyDestructive
Applies a draft plan as one change, all or nothing (D8): teams it creates are created now (empty until people move in); people move from its effective date (org_people_move: the same rules, and approval requests where Settings → Approval rules asks for them); renames, team moves, archiving and team leads take effect that day (scheduled when it is later: org_units_changes). Use dry_run first and show the result. The plan is then marked applied. Reorg plans are confidential: owners, admins and HR only (never custom roles); the people in them see nothing until it is applied.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_plans_applyon 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
plan_idstringrequired
Returns
planobjectrequired12 fields
idstringrequirednamestringrequirednotestring | nullrequiredeffective_datestringrequiredstatus"draft" | "applied" | "discarded"requiredchangesany[]requiredThe changes, as saved.
linesstring[]requiredEach change in words, in order.
people_movedintegerrequiredprepared_bystring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredapplied_atstring | nullrequired
created_teamsobject[]required2 fields
idstringrequirednamestringrequired
movedintegerrequiredrequestedintegerrequiredMoves sent for approval.
scheduledintegerrequiredStructure changes scheduled for the effective date.
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/plans.apply \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"plan_id":"pl1"}'const res = await fetch('https://api.bizisy.com/v1/org/plans.apply', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"plan_id": "pl1"
}),
});
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/plans.apply",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"plan_id": "pl1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"plan": {
"id": "pl1",
"name": "Platform split",
"note": "Q4",
"effective_date": "2026-11-01",
"status": "applied",
"changes": [
{
"type": "create_team",
"key": "plat",
"name": "Platform",
"parent_id": "u2"
},
{
"type": "move",
"person_ids": [
"p2"
],
"unit_id": "new:plat",
"manager_id": "p3"
}
],
"lines": [
"Create Platform under Engineering",
"Move Rui Costa to Platform, reporting to Sofia Costa"
],
"people_moved": 1,
"prepared_by": "Ana Ferreira",
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:00:00.000Z",
"applied_at": "2026-10-04T10:00:00.000Z"
},
"created_teams": [
{
"id": "u9",
"name": "Platform"
}
],
"moved": 3,
"requested": 0,
"scheduled": 1
}
}Something missing or wrong on this page? Write to hello@bizisy.com.