API reference

Units, locations and legal entities

Divisions, departments and teams, the places people work and the companies that employ them.

13 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) and member_count (people currently assigned directly). Archived units are hidden unless include_archived is true.

Who can call it: Manage key any Manage role
Me key anyone
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 7 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

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}'

Node

const res = await fetch('https://api.bizisy.com/v1/org/units.list', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "include_archived": true
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os
import requests

res = requests.post(
    "https://api.bizisy.com/v1/org/units.list",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
    json={
        "include_archived": True,
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

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
    },
    {
      "id": "u1",
      "name": "Acme Lda",
      "kind": "company",
      "parent_id": null,
      "head": null,
      "archived": false,
      "member_count": 4
    }
  ]
}

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.

Who can call it: Manage key owner admin hr
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

Returns

7 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

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}'

Node

const res = await fetch('https://api.bizisy.com/v1/org/units.create', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "name": "Platform",
    "kind": "team",
    "parent_id": "u2",
    "head_person_id": null
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os, uuid
import requests

res = requests.post(
    "https://api.bizisy.com/v1/org/units.create",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "name": "Platform",
        "kind": "team",
        "parent_id": "u2",
        "head_person_id": None,
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

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
  }
}

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.

Who can call it: Manage key owner admin hr
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

Returns

7 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

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"
}'

Node

const res = await fetch('https://api.bizisy.com/v1/org/units.update', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "unit_id": "u2",
    "kind": "division",
    "parent_id": "u1",
    "head_person_id": "p2"
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os, uuid
import requests

res = requests.post(
    "https://api.bizisy.com/v1/org/units.update",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "unit_id": "u2",
        "kind": "division",
        "parent_id": "u1",
        "head_person_id": "p2",
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

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
  }
}

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 no history: org_chart_get shows today's lead on any date. 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.

Returns

10 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
previous_headobject | nullrequired
4 fields
- idstringrequired
- namestringrequired
- titlestring | nullrequired
- photo_urlstring | nullrequired
also_headsobject[]required
2 fields
- idstringrequired
- namestringrequired
changedbooleanrequired

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"}'

Node

const res = await fetch('https://api.bizisy.com/v1/org/units.set_head', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "unit_id": "u2",
    "person_id": "p2"
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os, uuid
import requests

res = requests.post(
    "https://api.bizisy.com/v1/org/units.set_head",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "unit_id": "u2",
        "person_id": "p2",
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

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,
    "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
  }
}

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

Returns

7 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

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"}'

Node

const res = await fetch('https://api.bizisy.com/v1/org/units.archive', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "unit_id": "u2"
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os, uuid
import requests

res = requests.post(
    "https://api.bizisy.com/v1/org/units.archive",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "unit_id": "u2",
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

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
  }
}

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 7 fields

An array of objects:

idstringrequired
namestringrequired
countrystringrequired
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}'

Node

const res = await fetch('https://api.bizisy.com/v1/org/locations.list', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "include_archived": true
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os
import requests

res = requests.post(
    "https://api.bizisy.com/v1/org/locations.list",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
    json={
        "include_archived": True,
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

Response

{
  "data": [
    {
      "id": "l1",
      "name": "Head office",
      "country": "PT",
      "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). 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

Returns

7 fields

idstringrequired
namestringrequired
countrystringrequired
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
}'

Node

const res = await fetch('https://api.bizisy.com/v1/org/locations.create', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "name": "Remote EU",
    "country": "DE",
    "city": null,
    "timezone": "Europe/Berlin",
    "remote": true
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os, uuid
import requests

res = requests.post(
    "https://api.bizisy.com/v1/org/locations.create",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "name": "Remote EU",
        "country": "DE",
        "city": None,
        "timezone": "Europe/Berlin",
        "remote": True,
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

Response

{
  "data": {
    "id": "l1",
    "name": "Remote EU",
    "country": "DE",
    "city": null,
    "timezone": "Europe/Berlin",
    "remote": true,
    "archived": false
  }
}

Update a location#

POST/v1/org/locations.updateWrite

Changes the name, country, city, time zone or remote flag of a location.

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

Returns

7 fields

idstringrequired
namestringrequired
countrystringrequired
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
}'

Node

const res = await fetch('https://api.bizisy.com/v1/org/locations.update', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "location_id": "l1",
    "country": "PT",
    "city": "Lisboa",
    "timezone": "Europe/Lisbon",
    "remote": false
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os, uuid
import requests

res = requests.post(
    "https://api.bizisy.com/v1/org/locations.update",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "location_id": "l1",
        "country": "PT",
        "city": "Lisboa",
        "timezone": "Europe/Lisbon",
        "remote": False,
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

Response

{
  "data": {
    "id": "l1",
    "name": "Head office",
    "country": "PT",
    "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

7 fields

idstringrequired
namestringrequired
countrystringrequired
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"}'

Node

const res = await fetch('https://api.bizisy.com/v1/org/locations.archive', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "location_id": "l1"
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os, uuid
import requests

res = requests.post(
    "https://api.bizisy.com/v1/org/locations.archive",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "location_id": "l1",
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

Response

{
  "data": {
    "id": "l1",
    "name": "Head office",
    "country": "PT",
    "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 and tax id, 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:

idstringrequired
legal_namestringrequired
countrystringrequired
tax_idstring | nullrequired
archivedbooleanrequired

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}'

Node

const res = await fetch('https://api.bizisy.com/v1/org/entities.list', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "include_archived": true
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os
import requests

res = requests.post(
    "https://api.bizisy.com/v1/org/entities.list",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
    json={
        "include_archived": True,
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

Response

{
  "data": [
    {
      "id": "e1",
      "legal_name": "Acme Lda",
      "country": "PT",
      "tax_id": null,
      "archived": false
    }
  ]
}

Create a legal entity#

POST/v1/org/entities.createWrite

Creates a legal entity (an employing company) with its 2-letter country and optional tax id.

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.

Returns

idstringrequired
legal_namestringrequired
countrystringrequired
tax_idstring | nullrequired
archivedbooleanrequired

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","tax_id":null}'

Node

const res = await fetch('https://api.bizisy.com/v1/org/entities.create', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "legal_name": "Acme GmbH",
    "country": "DE",
    "tax_id": null
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os, uuid
import requests

res = requests.post(
    "https://api.bizisy.com/v1/org/entities.create",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "legal_name": "Acme GmbH",
        "country": "DE",
        "tax_id": None,
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

Response

{
  "data": {
    "id": "e1",
    "legal_name": "Acme GmbH",
    "country": "DE",
    "tax_id": null,
    "archived": false
  }
}

Update a legal entity#

POST/v1/org/entities.updateWrite

Changes the legal name, country or tax id of a legal entity.

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.

Returns

idstringrequired
legal_namestringrequired
countrystringrequired
tax_idstring | nullrequired
archivedbooleanrequired

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","legal_name":"Acme, Lda","country":"PT"}'

Node

const res = await fetch('https://api.bizisy.com/v1/org/entities.update', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "legal_entity_id": "e1",
    "legal_name": "Acme, Lda",
    "country": "PT"
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os, uuid
import requests

res = requests.post(
    "https://api.bizisy.com/v1/org/entities.update",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "legal_entity_id": "e1",
        "legal_name": "Acme, Lda",
        "country": "PT",
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

Response

{
  "data": {
    "id": "e1",
    "legal_name": "Acme, Lda",
    "country": "PT",
    "tax_id": "PT123456789",
    "archived": false
  }
}

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

idstringrequired
legal_namestringrequired
countrystringrequired
tax_idstring | nullrequired
archivedbooleanrequired

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"}'

Node

const res = await fetch('https://api.bizisy.com/v1/org/entities.archive', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "legal_entity_id": "e1"
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os, uuid
import requests

res = requests.post(
    "https://api.bizisy.com/v1/org/entities.archive",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "legal_entity_id": "e1",
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

Response

{
  "data": {
    "id": "e1",
    "legal_name": "Acme Lda",
    "country": "PT",
    "tax_id": null,
    "archived": true
  }
}

Something missing or wrong on this page? Write to hello@bizisy.com.