Skip to content

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

Input

  • include_archivedboolean

    Also return archived items.

    Default false.

Returns

An array of objects with 8 fields

An array of objects:

  • idstringrequired
  • namestringrequired
  • kind"company" | "division" | "department" | "team"required
  • parent_idstring | nullrequired
  • headobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • archivedbooleanrequired
  • member_countintegerrequired
  • customobject[]required

    Team custom fields you may see (public; private ones for owners, admins, HR and roles that manage the structure, in the app).

    7 fields
    • keystringrequired
    • labelstringrequired
    • typestring (enum)required

      One of: text, number, date, select, boolean, file, person, table.

    • tier"public" | "job" | "private"required
    • valuestring | number | boolean | object[]required

      For type file: the document id (download it with documents_download or documents_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 in org_fields_list).

    • fileobject | null

      Type file only: the file, or null when none is attached.

      4 fields
      • namestring | nullrequired

        The file name; null over an API key or MCP for someone else's file.

      • sizeintegerrequired
      • content_typestringrequired
      • previewablebooleanrequired

        The web app can show it (PDF, PNG, JPEG, WebP).

    • personobject | null

      Type person only: who it names (null when not set, or not someone you may see).

      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/units.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"include_archived":true}'
Response
{
  "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_create on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • namestringrequired

    1–100 characters.

  • kind"division" | "department" | "team"required
  • parent_idstring
  • head_person_idstring | null
  • customobject

    Team 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
  • idstringrequired
  • namestringrequired
  • kind"company" | "division" | "department" | "team"required
  • parent_idstring | nullrequired
  • headobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • archivedbooleanrequired
  • member_countintegerrequired
  • customobject[]required

    Team custom fields you may see (public; private ones for owners, admins, HR and roles that manage the structure, in the app).

    7 fields
    • keystringrequired
    • labelstringrequired
    • typestring (enum)required

      One of: text, number, date, select, boolean, file, person, table.

    • tier"public" | "job" | "private"required
    • valuestring | number | boolean | object[]required

      For type file: the document id (download it with documents_download or documents_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 in org_fields_list).

    • fileobject | null

      Type file only: the file, or null when none is attached.

      4 fields
      • namestring | nullrequired

        The file name; null over an API key or MCP for someone else's file.

      • sizeintegerrequired
      • content_typestringrequired
      • previewablebooleanrequired

        The web app can show it (PDF, PNG, JPEG, WebP).

    • personobject | null

      Type person only: who it names (null when not set, or not someone you may see).

      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • unit_idstringrequired
  • namestring

    1–100 characters.

  • kind"division" | "department" | "team"
  • parent_idstring
  • head_person_idstring | null
  • effective_datestring

    When it takes effect (YYYY-MM-DD in the company time zone): today or absent changes it now; a later day schedules it (org_units_changes lists them; applied at 00:00 that day). Past days are refused.

  • customobject

    Team 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
  • idstringrequired
  • namestringrequired
  • kind"company" | "division" | "department" | "team"required
  • parent_idstring | nullrequired
  • headobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • archivedbooleanrequired
  • member_countintegerrequired
  • customobject[]required

    Team custom fields you may see (public; private ones for owners, admins, HR and roles that manage the structure, in the app).

    7 fields
    • keystringrequired
    • labelstringrequired
    • typestring (enum)required

      One of: text, number, date, select, boolean, file, person, table.

    • tier"public" | "job" | "private"required
    • valuestring | number | boolean | object[]required

      For type file: the document id (download it with documents_download or documents_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 in org_fields_list).

    • fileobject | null

      Type file only: the file, or null when none is attached.

      4 fields
      • namestring | nullrequired

        The file name; null over an API key or MCP for someone else's file.

      • sizeintegerrequired
      • content_typestringrequired
      • previewablebooleanrequired

        The web app can show it (PDF, PNG, JPEG, WebP).

    • personobject | null

      Type person only: who it names (null when not set, or not someone you may see).

      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
  • scheduledobject[]required

    Changes scheduled for a later day by this call (effective_date after today); [] when applied now.

    9 fields
    • idstringrequired
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • field"name" | "parent" | "head" | "archive"required
    • valuestring | nullrequired

      name: the new name; parent: the new parent unit's name; head: the new team lead's name (null: no lead); archive: null.

    • effective_datestringrequired
    • status"scheduled" | "applied" | "failed" | "cancelled"required
    • problemstring | nullrequired

      Why it could not apply (failed).

    • plan_idstring | nullrequired
    • created_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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"
}'
Response
{
  "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_head on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired
  • person_idstring | nullrequired

    The new team lead (org_people_list), or null to remove the team lead.

  • effective_datestring

    When it takes effect (YYYY-MM-DD in the company time zone): today or absent changes it now; a later day schedules it (org_units_changes lists them; applied at 00:00 that day). Past days are refused.

Returns

12 fields
  • idstringrequired
  • namestringrequired
  • kind"company" | "division" | "department" | "team"required
  • parent_idstring | nullrequired
  • headobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • archivedbooleanrequired
  • member_countintegerrequired
  • customobject[]required

    Team custom fields you may see (public; private ones for owners, admins, HR and roles that manage the structure, in the app).

    7 fields
    • keystringrequired
    • labelstringrequired
    • typestring (enum)required

      One of: text, number, date, select, boolean, file, person, table.

    • tier"public" | "job" | "private"required
    • valuestring | number | boolean | object[]required

      For type file: the document id (download it with documents_download or documents_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 in org_fields_list).

    • fileobject | null

      Type file only: the file, or null when none is attached.

      4 fields
      • namestring | nullrequired

        The file name; null over an API key or MCP for someone else's file.

      • sizeintegerrequired
      • content_typestringrequired
      • previewablebooleanrequired

        The web app can show it (PDF, PNG, JPEG, WebP).

    • personobject | null

      Type person only: who it names (null when not set, or not someone you may see).

      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
  • previous_headobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • also_headsobject[]required
    2 fields
    • idstringrequired
    • namestringrequired
  • changedbooleanrequired
  • scheduledobject[]required

    Changes scheduled for a later day by this call (effective_date after today); [] when applied now.

    9 fields
    • idstringrequired
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • field"name" | "parent" | "head" | "archive"required
    • valuestring | nullrequired

      name: the new name; parent: the new parent unit's name; head: the new team lead's name (null: no lead); archive: null.

    • effective_datestringrequired
    • status"scheduled" | "applied" | "failed" | "cancelled"required
    • problemstring | nullrequired

      Why it could not apply (failed).

    • plan_idstring | nullrequired
    • created_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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"}'
Response
{
  "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_archive on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • unit_idstringrequired
  • effective_datestring

    When it takes effect (YYYY-MM-DD in the company time zone): today or absent changes it now; a later day schedules it (org_units_changes lists them; applied at 00:00 that day). Past days are refused.

Returns

9 fields
  • idstringrequired
  • namestringrequired
  • kind"company" | "division" | "department" | "team"required
  • parent_idstring | nullrequired
  • headobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • archivedbooleanrequired
  • member_countintegerrequired
  • customobject[]required

    Team custom fields you may see (public; private ones for owners, admins, HR and roles that manage the structure, in the app).

    7 fields
    • keystringrequired
    • labelstringrequired
    • typestring (enum)required

      One of: text, number, date, select, boolean, file, person, table.

    • tier"public" | "job" | "private"required
    • valuestring | number | boolean | object[]required

      For type file: the document id (download it with documents_download or documents_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 in org_fields_list).

    • fileobject | null

      Type file only: the file, or null when none is attached.

      4 fields
      • namestring | nullrequired

        The file name; null over an API key or MCP for someone else's file.

      • sizeintegerrequired
      • content_typestringrequired
      • previewablebooleanrequired

        The web app can show it (PDF, PNG, JPEG, WebP).

    • personobject | null

      Type person only: who it names (null when not set, or not someone you may see).

      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
  • scheduledobject[]required

    Changes scheduled for a later day by this call (effective_date after today); [] when applied now.

    9 fields
    • idstringrequired
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • field"name" | "parent" | "head" | "archive"required
    • valuestring | nullrequired

      name: the new name; parent: the new parent unit's name; head: the new team lead's name (null: no lead); archive: null.

    • effective_datestringrequired
    • status"scheduled" | "applied" | "failed" | "cancelled"required
    • problemstring | nullrequired

      Why it could not apply (failed).

    • plan_idstring | nullrequired
    • created_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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"}'
Response
{
  "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_changes on HR Assistant
Method
POST with a JSON body, or GET with 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:

  • idstringrequired
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • field"name" | "parent" | "head" | "archive"required
  • valuestring | nullrequired

    name: the new name; parent: the new parent unit's name; head: the new team lead's name (null: no lead); archive: null.

  • effective_datestringrequired
  • status"scheduled" | "applied" | "failed" | "cancelled"required
  • problemstring | nullrequired

    Why it could not apply (failed).

  • plan_idstring | nullrequired
  • created_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
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"}'
Response
{
  "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_change on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • change_idstringrequired

Returns

9 fields
  • idstringrequired
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • field"name" | "parent" | "head" | "archive"required
  • valuestring | nullrequired

    name: the new name; parent: the new parent unit's name; head: the new team lead's name (null: no lead); archive: null.

  • effective_datestringrequired
  • status"scheduled" | "applied" | "failed" | "cancelled"required
  • problemstring | nullrequired

    Why it could not apply (failed).

  • plan_idstring | nullrequired
  • created_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

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

Input

  • unit_idstringrequired

Returns

An array of objects with 7 fields

An array of objects:

  • valid_fromstringrequired
  • valid_tostring | nullrequired
  • namestringrequired
  • kind"company" | "division" | "department" | "team"required
  • parentobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • headobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • archivedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/units.history \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"unit_id":"u2"}'
Response
{
  "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_list on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • include_archivedboolean

    Also return archived items.

    Default false.

Returns

An array of objects with 8 fields

An array of objects:

  • idstringrequired
  • namestringrequired
  • countrystringrequired
  • regionstring | nullrequired

    State or province code for public holidays; null: national only.

  • citystring | nullrequired
  • timezonestringrequired
  • remotebooleanrequired
  • archivedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/locations.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"include_archived":true}'
Response
{
  "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_create on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • namestringrequired

    1–100 characters.

  • countryanyrequired
  • citystring | null

    Up to 100 characters.

  • timezonestring
  • remoteboolean
  • regionany | null

    The 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
  • idstringrequired
  • namestringrequired
  • countrystringrequired
  • regionstring | nullrequired

    State or province code for public holidays; null: national only.

  • citystring | nullrequired
  • timezonestringrequired
  • remotebooleanrequired
  • archivedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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
}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • location_idstringrequired
  • namestring

    1–100 characters.

  • countryany
  • citystring | null

    Up to 100 characters.

  • timezonestring
  • remoteboolean
  • regionany | null

    The 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
  • idstringrequired
  • namestringrequired
  • countrystringrequired
  • regionstring | nullrequired

    State or province code for public holidays; null: national only.

  • citystring | nullrequired
  • timezonestringrequired
  • remotebooleanrequired
  • archivedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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
}'
Response
{
  "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_archive on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • location_idstringrequired

Returns

8 fields
  • idstringrequired
  • namestringrequired
  • countrystringrequired
  • regionstring | nullrequired

    State or province code for public holidays; null: national only.

  • citystring | nullrequired
  • timezonestringrequired
  • remotebooleanrequired
  • archivedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

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

Input

  • include_archivedboolean

    Also return archived items.

    Default false.

Returns

An array of objects with 11 fields

An array of objects:

  • idstringrequired
  • legal_namestringrequired
  • countrystringrequired
  • tax_idstring | nullrequired
  • archivedbooleanrequired
  • addressobject | nullrequired

    The registered postal address (the country is country); null when not set. Shown in the candidate privacy notice and on offer letters.

    5 fields
    • line1stringrequired

      Street and number.

    • line2string | nullrequired

      Floor, building or other detail.

    • postal_codestring | nullrequired
    • citystringrequired
    • regionstring | nullrequired

      State, province or region, where the address uses one.

  • collective_agreementstring | nullrequired

    The collective agreement that applies (document templates: {{employer.collective_agreement}}); null when none or not set.

  • collective_agreement_codestring | nullrequired

    Its official code (e.g. the Spanish REGCON code); null when not set.

  • accident_insurerstring | nullrequired

    The workplace-accident insurer (required in Portuguese contracts); null when not set.

  • accident_policystring | nullrequired

    The workplace-accident policy number; null when not set.

  • social_securitystring | nullrequired

    The social security institution(s) the employer pays contributions to; null when not set.

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/entities.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"include_archived":true}'
Response
{
  "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_create on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • legal_namestringrequired

    1–200 characters.

  • countryanyrequired
  • tax_idstring | null

    Up to 40 characters.

  • addressobject | null
    5 fields
    • line1stringrequired

      Street and number.

      1–200 characters.

    • line2string | null

      Floor, building or other detail (optional).

      Up to 200 characters.

    • postal_codestring | null

      Postal code (optional: some countries have none).

      Up to 20 characters.

    • citystringrequired

      1–100 characters.

    • regionstring | null

      State, province or region, where the address uses one (optional).

      Up to 100 characters.

  • collective_agreementstring | null

    The collective agreement that applies, as documents name it (null clears it).

    Up to 300 characters.

  • collective_agreement_codestring | null

    Its official code, e.g. the Spanish REGCON code (null clears it).

    Up to 60 characters.

  • accident_insurerstring | null

    The workplace-accident insurer (Portugal: required in contracts).

    Up to 200 characters.

  • accident_policystring | null

    The workplace-accident policy number.

    Up to 80 characters.

  • social_securitystring | null

    The social security institution(s) the employer pays contributions to.

    Up to 300 characters.

Returns

11 fields
  • idstringrequired
  • legal_namestringrequired
  • countrystringrequired
  • tax_idstring | nullrequired
  • archivedbooleanrequired
  • addressobject | nullrequired

    The registered postal address (the country is country); null when not set. Shown in the candidate privacy notice and on offer letters.

    5 fields
    • line1stringrequired

      Street and number.

    • line2string | nullrequired

      Floor, building or other detail.

    • postal_codestring | nullrequired
    • citystringrequired
    • regionstring | nullrequired

      State, province or region, where the address uses one.

  • collective_agreementstring | nullrequired

    The collective agreement that applies (document templates: {{employer.collective_agreement}}); null when none or not set.

  • collective_agreement_codestring | nullrequired

    Its official code (e.g. the Spanish REGCON code); null when not set.

  • accident_insurerstring | nullrequired

    The workplace-accident insurer (required in Portuguese contracts); null when not set.

  • accident_policystring | nullrequired

    The workplace-accident policy number; null when not set.

  • social_securitystring | nullrequired

    The 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
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
  }
}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • legal_entity_idstringrequired
  • legal_namestring

    1–200 characters.

  • countryany
  • tax_idstring | null

    Up to 40 characters.

  • addressobject | null
    5 fields
    • line1stringrequired

      Street and number.

      1–200 characters.

    • line2string | null

      Floor, building or other detail (optional).

      Up to 200 characters.

    • postal_codestring | null

      Postal code (optional: some countries have none).

      Up to 20 characters.

    • citystringrequired

      1–100 characters.

    • regionstring | null

      State, province or region, where the address uses one (optional).

      Up to 100 characters.

  • collective_agreementstring | null

    The collective agreement that applies, as documents name it (null clears it).

    Up to 300 characters.

  • collective_agreement_codestring | null

    Its official code, e.g. the Spanish REGCON code (null clears it).

    Up to 60 characters.

  • accident_insurerstring | null

    The workplace-accident insurer (Portugal: required in contracts).

    Up to 200 characters.

  • accident_policystring | null

    The workplace-accident policy number.

    Up to 80 characters.

  • social_securitystring | null

    The social security institution(s) the employer pays contributions to.

    Up to 300 characters.

Returns

11 fields
  • idstringrequired
  • legal_namestringrequired
  • countrystringrequired
  • tax_idstring | nullrequired
  • archivedbooleanrequired
  • addressobject | nullrequired

    The registered postal address (the country is country); null when not set. Shown in the candidate privacy notice and on offer letters.

    5 fields
    • line1stringrequired

      Street and number.

    • line2string | nullrequired

      Floor, building or other detail.

    • postal_codestring | nullrequired
    • citystringrequired
    • regionstring | nullrequired

      State, province or region, where the address uses one.

  • collective_agreementstring | nullrequired

    The collective agreement that applies (document templates: {{employer.collective_agreement}}); null when none or not set.

  • collective_agreement_codestring | nullrequired

    Its official code (e.g. the Spanish REGCON code); null when not set.

  • accident_insurerstring | nullrequired

    The workplace-accident insurer (required in Portuguese contracts); null when not set.

  • accident_policystring | nullrequired

    The workplace-accident policy number; null when not set.

  • social_securitystring | nullrequired

    The 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
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"
}'
Response
{
  "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_archive on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • legal_entity_idstringrequired

Returns

11 fields
  • idstringrequired
  • legal_namestringrequired
  • countrystringrequired
  • tax_idstring | nullrequired
  • archivedbooleanrequired
  • addressobject | nullrequired

    The registered postal address (the country is country); null when not set. Shown in the candidate privacy notice and on offer letters.

    5 fields
    • line1stringrequired

      Street and number.

    • line2string | nullrequired

      Floor, building or other detail.

    • postal_codestring | nullrequired
    • citystringrequired
    • regionstring | nullrequired

      State, province or region, where the address uses one.

  • collective_agreementstring | nullrequired

    The collective agreement that applies (document templates: {{employer.collective_agreement}}); null when none or not set.

  • collective_agreement_codestring | nullrequired

    Its official code (e.g. the Spanish REGCON code); null when not set.

  • accident_insurerstring | nullrequired

    The workplace-accident insurer (required in Portuguese contracts); null when not set.

  • accident_policystring | nullrequired

    The workplace-accident policy number; null when not set.

  • social_securitystring | nullrequired

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

Input

No input: send {}.

Returns

  • plansobject[]required
    12 fields
    • idstringrequired
    • namestringrequired
    • notestring | nullrequired
    • effective_datestringrequired
    • status"draft" | "applied" | "discarded"required
    • changesany[]required

      The changes, as saved.

    • linesstring[]required

      Each change in words, in order.

    • people_movedintegerrequired
    • prepared_bystring | nullrequired
    • created_atstringrequired
    • updated_atstringrequired
    • applied_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/plans.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • plan_idstringrequired

Returns

12 fields
  • idstringrequired
  • namestringrequired
  • notestring | nullrequired
  • effective_datestringrequired
  • status"draft" | "applied" | "discarded"required
  • changesany[]required

    The changes, as saved.

  • linesstring[]required

    Each change in words, in order.

  • people_movedintegerrequired
  • prepared_bystring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired
  • applied_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/plans.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan_id":"pl1"}'
Response
{
  "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_save on HR Assistant
Preview
?dry_run=true runs 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_idstring
  • namestringrequired

    1–100 characters.

  • notestring | null

    Up to 1000 characters.

  • effective_datestringrequired
  • changesobject[]required

    Up to 200 items.

    20 fields (one of several shapes)

    Option 1

    • type"move"required
    • person_idsstring[]required

      1–50 items.

    • unit_idstring

      1–60 characters.

    • manager_idstring | null

    Option 2

    • type"create_team"required
    • keystringrequired

      Pattern ^[a-z0-9_-]{1,30}$.

    • namestringrequired

      1–100 characters.

    • kind"division" | "department" | "team"

      Default "team".

    • parent_idstring

      1–60 characters.

    Option 3

    • type"rename_team"required
    • unit_idstringrequired

      1–60 characters.

    • namestringrequired

      1–100 characters.

    Option 4

    • type"move_team"required
    • unit_idstringrequired

      1–60 characters.

    • parent_idstringrequired

      1–60 characters.

    Option 5

    • type"archive_team"required
    • unit_idstringrequired

      1–60 characters.

    Option 6

    • type"set_lead"required
    • unit_idstringrequired

      1–60 characters.

    • person_idstring | nullrequired

Returns

12 fields
  • idstringrequired
  • namestringrequired
  • notestring | nullrequired
  • effective_datestringrequired
  • status"draft" | "applied" | "discarded"required
  • changesany[]required

    The changes, as saved.

  • linesstring[]required

    Each change in words, in order.

  • people_movedintegerrequired
  • prepared_bystring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired
  • applied_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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"
    }
  ]
}'
Response
{
  "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_discard on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • plan_idstringrequired

Returns

12 fields
  • idstringrequired
  • namestringrequired
  • notestring | nullrequired
  • effective_datestringrequired
  • status"draft" | "applied" | "discarded"required
  • changesany[]required

    The changes, as saved.

  • linesstring[]required

    Each change in words, in order.

  • people_movedintegerrequired
  • prepared_bystring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired
  • applied_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

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

Input

  • plan_idstringrequired

Returns

  • effective_datestringrequired
  • teamsobject[]required
    6 fields
    • idstringrequired

      A team id, or new:<key> for a team the plan creates.

    • namestringrequired
    • parentstring | nullrequired
    • state"new" | "archived" | "changed" | "same"required
    • beforeobjectrequired
      4 fields
      • directintegerrequired
      • totalintegerrequired
      • leadstring | nullrequired
      • namestring | nullrequired
    • afterobjectrequired
      3 fields
      • directintegerrequired
      • totalintegerrequired
      • leadstring | nullrequired
  • managersobject[]required

    People whose number of direct reports changes.

    3 fields
    • personobjectrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • beforeintegerrequired
    • afterintegerrequired
  • movesobject[]required
    5 fields
    • personobjectrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • from_teamstring | nullrequired
    • to_teamstring | nullrequired
    • from_managerstring | nullrequired
    • to_managerstring | nullrequired
  • warningsstring[]required

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/plans.compare \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan_id":"pl1"}'
Response
{
  "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_apply on HR Assistant
Preview
?dry_run=true runs 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

  • planobjectrequired
    12 fields
    • idstringrequired
    • namestringrequired
    • notestring | nullrequired
    • effective_datestringrequired
    • status"draft" | "applied" | "discarded"required
    • changesany[]required

      The changes, as saved.

    • linesstring[]required

      Each change in words, in order.

    • people_movedintegerrequired
    • prepared_bystring | nullrequired
    • created_atstringrequired
    • updated_atstringrequired
    • applied_atstring | nullrequired
  • created_teamsobject[]required
    2 fields
    • idstringrequired
    • namestringrequired
  • movedintegerrequired
  • requestedintegerrequired

    Moves sent for approval.

  • scheduledintegerrequired

    Structure changes scheduled for the effective date.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

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

Developer docs