API reference
Org chart
The org chart on any date, as nodes or as a list.
3 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
Org chart#
POST/v1/org/chart.getRead
Returns the org chart as of a date (as_of, default today) as a flat list of nodes {id, kind, parent_id, label, sublabel, person_id?, photo_url?} (photo_url: path of the person photo on the company address, null without one). by="manager" (default): one node per employed person under their manager. by="unit": unit nodes (sublabel = kind) with people under their unit. Person nodes also carry unit_id, location_id, status (active or pre_hire), start_date (of the current employment period), is_unit_head (the team lead of a live unit on that date), dotted_managers (ids of dotted-line managers on the chart: people they also report to, without authority), direct_count and total_count (direct and all reports by manager among the people in this chart); unit nodes carry direct_count and total_count (people directly in the unit, and in it and every unit below). leaving_on (last day, when a termination is scheduled), contract_end (contract end date) and next_change {on, reason, title} (the next scheduled job change in the current employment, e.g. a promotion; null when none) appear only on people whose job details you may see, as in org_people_get (yourself, your reports, or everyone for owners, admins and HR, also over MCP or an API key); for anyone else a future as_of still shows people employed today whose last day falls before it. include_upcoming=true adds people starting within upcoming_days (default 30, at most 365) after the date, with status pre_hire. include_positions=true adds open roles: nodes of kind "position" (label = the position title) for the open and on-hold positions you may see (owners, admins and HR: all; a manager: those in their line; anyone else: none), with position_status, target_start_date, reason, unit_id and location_id; by manager they hang under the person or position they report to; when that person is not on the chart (starting later, or left) under the first of their managers who is, and under a role you cannot see, its first visible ancestor (else at the top), by unit under their unit (or the company). They are never counted in direct_count or total_count, and with an as_of before today there are none (positions are today's plan). color_by adds color {key, label} to person nodes for colouring and grouping (the team colour needs nothing): location, legal_entity, employment_type, contract_type (these three only on people whose job details you may see), family or level (job title catalog: only for owners, admins, HR, viewers and custom roles that see the job architecture, else forbidden; and then only on people whose job details you may see), span (no reports, narrow, in range or wide span of control), or field:<key> for a public or job custom field of type select, boolean or text: a person field, a job field (the job row on the chart's date; only on people whose job details you may see) or a public team field (each person's team value, e.g. cost centre); private fields and open position fields are refused. key null means not set. group_id (a saved group from org_groups_list; owners, admins, HR, viewers and custom roles that are not outsiders) adds in_group to person nodes: a member today, as you see them (a condition on data you may not see for someone is not met for them); nobody is left out of the chart.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
org_chart_geton My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
as_ofstringby"manager" | "unit"Default
"manager".include_upcomingbooleanDefault
false.upcoming_daysintegerFrom 1 to 365.
include_positionsbooleanDefault
false.color_bystring (enum) | stringgroup_idstring
Returns
nodesobject[]required23 fields
idstringrequiredkind"person" | "unit" | "position"requiredparent_idstring | nullrequiredlabelstringrequiredsublabelstring | nullrequiredperson_idstringphoto_urlstring | nullunit_idstring | nulllocation_idstring | nullstatus"active" | "pre_hire"start_datestring | nullis_unit_headbooleandotted_managersstring[]Dotted-line managers on this chart (ids): people they also report to, without approvals.
direct_countintegertotal_countintegerleaving_onstring | nullcontract_endstring | nullnext_changeobject | null3 fields
onstringrequiredreasonstringrequiredtitlestringrequired
position_status"open" | "on_hold"target_start_datestring | nullreason"new" | "replacement"colorobject2 fields
keystring | nullrequiredlabelstringrequired
in_groupboolean
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/chart.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"include_upcoming":true,"upcoming_days":60}'const res = await fetch('https://api.bizisy.com/v1/org/chart.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"include_upcoming": true,
"upcoming_days": 60
}),
});
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/chart.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"include_upcoming": True,
"upcoming_days": 60,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"nodes": [
{
"id": "u1",
"kind": "unit",
"parent_id": null,
"label": "Acme Lda",
"sublabel": "company",
"direct_count": 1,
"total_count": 2
},
{
"id": "p1",
"kind": "person",
"parent_id": "u1",
"label": "Ana Ferreira",
"sublabel": "Engineer",
"person_id": "p1",
"unit_id": "u1",
"location_id": "l1",
"status": "active",
"start_date": "2024-01-15",
"is_unit_head": true,
"direct_count": 1,
"total_count": 1,
"leaving_on": null,
"contract_end": "2027-01-14",
"next_change": {
"on": "2026-12-01",
"reason": "promotion",
"title": "Lead Engineer"
}
},
{
"id": "p3",
"kind": "person",
"parent_id": "p1",
"label": "Rui Costa",
"sublabel": "CTO",
"person_id": "p3",
"unit_id": null,
"location_id": null,
"status": "pre_hire",
"start_date": "2026-11-02",
"is_unit_head": false,
"direct_count": 0,
"total_count": 0,
"color": {
"key": "l1",
"label": "Lisbon"
}
},
{
"id": "pos1",
"kind": "position",
"parent_id": "p1",
"label": "Data Engineer",
"sublabel": null,
"unit_id": "u1",
"location_id": null,
"position_status": "open",
"target_start_date": "2026-12-01",
"reason": "new"
}
]
}
}Export the org chart as a list#
POST/v1/org/chart.exportRead
Returns the org chart as a list, one row per person, in reporting order (each manager followed by the people under them): name, title, team, manager (name and manager_id), location, status (active, or pre_hire for people starting soon), start_date, level (1 = the top of the company), direct_reports and total_reports. format "json" (default) returns rows; format "csv" returns a CSV file (UTF-8, comma-separated; delimiter ";" suits Excel in most of Europe; cells a spreadsheet would run as formulas are prefixed with '). Same people and dates as org_chart_get: as_of (default today), include_upcoming with upcoming_days (default 30, at most 365). Narrow it with root_person_id (that person and everyone under them; not_found if they are not on the chart on that date), unit_id (that team and its sub-teams; not_found for an unknown or archived team) and person_ids (only these people, at most 5000; ids not on the chart are ignored); filters combine. Everyone who can see the chart may use it, in the app, over MCP or with an API key. It never includes job details such as leaving dates, contract ends or scheduled changes, nor private or pay data. Pictures and PDFs of the chart are made in the Bizisy app (Org chart → Export).
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
org_chart_exporton My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
as_ofstringinclude_upcomingbooleanDefault
false.upcoming_daysintegerFrom 1 to 365.
root_person_idstring1–100 characters.
unit_idstring1–100 characters.
person_idsstring[]1–100 characters. Up to 5000 items.
format"json" | "csv"Default
"json".delimiter"," | ";"
Returns
7 fields
format"json" | "csv"requiredfilenamestringrequiredas_ofstringrequiredcountintegerrequiredcolumnsstring[]requiredrowsobject[]12 fields
person_idstringrequirednamestringrequiredtitlestring | nullrequiredteamstring | nullrequiredmanagerstring | nullrequiredmanager_idstring | nullrequiredlocationstring | nullrequiredstatus"active" | "pre_hire"requiredstart_datestring | nullrequiredlevelintegerrequireddirect_reportsintegerrequiredtotal_reportsintegerrequired
csvstring
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/chart.export \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"root_person_id":"p1","include_upcoming":true,"upcoming_days":60}'const res = await fetch('https://api.bizisy.com/v1/org/chart.export', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"root_person_id": "p1",
"include_upcoming": true,
"upcoming_days": 60
}),
});
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/chart.export",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"root_person_id": "p1",
"include_upcoming": True,
"upcoming_days": 60,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"format": "json",
"filename": "org-chart-2026-10-04.json",
"as_of": "2026-10-04",
"count": 1,
"columns": [
"name",
"title",
"team",
"manager",
"location",
"status",
"start_date",
"level",
"direct_reports",
"total_reports"
],
"rows": [
{
"person_id": "p1",
"name": "Ana Ferreira",
"title": "Engineer",
"team": "Acme Lda",
"manager": null,
"manager_id": null,
"location": "Lisbon",
"status": "active",
"start_date": "2024-01-15",
"level": 1,
"direct_reports": 1,
"total_reports": 1
}
]
}
}What changed between two dates#
POST/v1/org/chart.diffRead
Compares the organization on two dates (from before to; at most 5 years apart; either may be in the future): headcount on each date, people who joined and left, who changed team (moved), manager (manager_changed) or job title (retitled), and teams added, archived, renamed, moved under another parent, or given another team lead. Each date uses its own structure (org_units_history; scheduled changes only for those who manage the structure). A scheduled last day is job detail: for people whose job you cannot see, someone employed today still shows as employed on a later date. Owners, admins and HR, and roles that edit the people they cover (only people they cover).
- Who can call it
- Manage key owner admin hr
- MCP tool
org_chart_diffon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
fromstringrequiredtostringrequired
Returns
9 fields
fromstringrequiredtostringrequiredheadcountobjectrequired2 fields
fromintegerrequiredtointegerrequired
joinedobject[]required4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
leftobject[]required4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
movedobject[]requiredChanged team (from and to: the team on each date).
3 fields
personobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
fromobject | nullrequired2 fields
idstringrequirednamestringrequired
toobject | nullrequired2 fields
idstringrequirednamestringrequired
manager_changedobject[]required3 fields
personobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
fromobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
toobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
retitledobject[]required3 fields
personobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
fromstringrequiredtostringrequired
unitsobjectrequired5 fields
addedobject[]required2 fields
idstringrequirednamestringrequired
archivedobject[]required2 fields
idstringrequirednamestringrequired
renamedobject[]requiredfrom, to: the names.
3 fields
unitobjectrequired2 fields
idstringrequirednamestringrequired
fromstring | nullrequiredtostring | nullrequired
movedobject[]requiredfrom, to: the parent units' names.
3 fields
unitobjectrequired2 fields
idstringrequirednamestringrequired
fromstring | nullrequiredtostring | nullrequired
lead_changedobject[]requiredfrom, to: the team leads' names (null: none).
3 fields
unitobjectrequired2 fields
idstringrequirednamestringrequired
fromstring | nullrequiredtostring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/chart.diff \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"from":"2026-01-01","to":"2026-10-04"}'const res = await fetch('https://api.bizisy.com/v1/org/chart.diff', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"from": "2026-01-01",
"to": "2026-10-04"
}),
});
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/chart.diff",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"from": "2026-01-01",
"to": "2026-10-04",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"from": "2026-01-01",
"to": "2026-10-04",
"headcount": {
"from": 9,
"to": 12
},
"joined": [
{
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
}
],
"left": [],
"moved": [
{
"person": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"from": {
"id": "u2",
"name": "Engineering"
},
"to": {
"id": "u9",
"name": "Platform"
}
}
],
"manager_changed": [
{
"person": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"from": null,
"to": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
}
}
],
"retitled": [
{
"person": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"from": "Engineer",
"to": "Senior Engineer"
}
],
"units": {
"added": [
{
"id": "u9",
"name": "Platform"
}
],
"archived": [],
"renamed": [
{
"unit": {
"id": "u2",
"name": "Product Engineering"
},
"from": "Engineering",
"to": "Product Engineering"
}
],
"moved": [],
"lead_changed": []
}
}
}Something missing or wrong on this page? Write to hello@bizisy.com.