Skip to content

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_get on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • as_ofstring
  • by"manager" | "unit"

    Default "manager".

  • include_upcomingboolean

    Default false.

  • upcoming_daysinteger

    From 1 to 365.

  • include_positionsboolean

    Default false.

  • color_bystring (enum) | string
  • group_idstring

Returns

  • nodesobject[]required
    23 fields
    • idstringrequired
    • kind"person" | "unit" | "position"required
    • parent_idstring | nullrequired
    • labelstringrequired
    • sublabelstring | nullrequired
    • person_idstring
    • photo_urlstring | null
    • unit_idstring | null
    • location_idstring | null
    • status"active" | "pre_hire"
    • start_datestring | null
    • is_unit_headboolean
    • dotted_managersstring[]

      Dotted-line managers on this chart (ids): people they also report to, without approvals.

    • direct_countinteger
    • total_countinteger
    • leaving_onstring | null
    • contract_endstring | null
    • next_changeobject | null
      3 fields
      • onstringrequired
      • reasonstringrequired
      • titlestringrequired
    • position_status"open" | "on_hold"
    • target_start_datestring | null
    • reason"new" | "replacement"
    • colorobject
      2 fields
      • keystring | nullrequired
      • labelstringrequired
    • in_groupboolean

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
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}'
Response
{
  "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_export on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • as_ofstring
  • include_upcomingboolean

    Default false.

  • upcoming_daysinteger

    From 1 to 365.

  • root_person_idstring

    1–100 characters.

  • unit_idstring

    1–100 characters.

  • person_idsstring[]

    1–100 characters. Up to 5000 items.

  • format"json" | "csv"

    Default "json".

  • delimiter"," | ";"

Returns

7 fields
  • format"json" | "csv"required
  • filenamestringrequired
  • as_ofstringrequired
  • countintegerrequired
  • columnsstring[]required
  • rowsobject[]
    12 fields
    • person_idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • teamstring | nullrequired
    • managerstring | nullrequired
    • manager_idstring | nullrequired
    • locationstring | nullrequired
    • status"active" | "pre_hire"required
    • start_datestring | nullrequired
    • levelintegerrequired
    • direct_reportsintegerrequired
    • total_reportsintegerrequired
  • csvstring

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
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}'
Response
{
  "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_diff on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • fromstringrequired
  • tostringrequired

Returns

9 fields
  • fromstringrequired
  • tostringrequired
  • headcountobjectrequired
    2 fields
    • fromintegerrequired
    • tointegerrequired
  • joinedobject[]required
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • leftobject[]required
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • movedobject[]required

    Changed team (from and to: the team on each date).

    3 fields
    • personobjectrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • fromobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • toobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
  • manager_changedobject[]required
    3 fields
    • personobjectrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • fromobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • toobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
  • retitledobject[]required
    3 fields
    • personobjectrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • fromstringrequired
    • tostringrequired
  • unitsobjectrequired
    5 fields
    • addedobject[]required
      2 fields
      • idstringrequired
      • namestringrequired
    • archivedobject[]required
      2 fields
      • idstringrequired
      • namestringrequired
    • renamedobject[]required

      from, to: the names.

      3 fields
      • unitobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • fromstring | nullrequired
      • tostring | nullrequired
    • movedobject[]required

      from, to: the parent units' names.

      3 fields
      • unitobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • fromstring | nullrequired
      • tostring | nullrequired
    • lead_changedobject[]required

      from, to: the team leads' names (null: none).

      3 fields
      • unitobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • fromstring | nullrequired
      • tostring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
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"}'
Response
{
  "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.

Developer docs