API reference
Open positions
Roles the company plans to fill and headcount budgets per team: the headcount plan.
12 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
List open positions (headcount plan)#
POST/v1/org/positions.listRead
Lists open positions: roles the company plans to fill (title, team, location, legal entity, who it reports to — a person or another position —, contract type, weekly hours, target start date, status, reason "new" or "replacement" with the leaver it replaces, and who filled it). status: "active" (default: draft, open and on hold), one status (draft, open, on_hold, filled, cancelled), "closed" (filled and cancelled) or "all". Filled and cancelled positions come newest first, a page at a time: limit (default 50, at most 200) of them per call; for the next page pass after = the id of the last closed position you got (only with filled, cancelled, closed or all; with all the draft, open and on-hold ones come only on the first page). Filters: unit_id, reports_to_person_id. Who sees what: owners, admins and HR see every position; a manager sees only the open and on-hold positions that report to them or to someone below them (also when that person starts later or has left: the line they belong to); everyone else sees none (an empty list). notes are for owners, admins and HR only; pay_range (the budget) only for owners, admins and HR signed in to Bizisy, never over MCP or an API key (pay_range_hidden is then true); replaces is shown only when you may see that person's job details. can_reopen: a filled position whose hire did not start (org_positions_reopen).
- Who can call it
- Manage key any Manage role
Me key anyone - Keys and apps
- pay_range (the budget) is never returned (pay_range_hidden is true).
- MCP tool
org_positions_liston My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
statusstring (enum)One of:
active,draft,open,on_hold,filled,cancelled,closed,all. Default"active".unit_idstringreports_to_person_idstringlimitintegerFrom 1 to 200.
afterstring
Returns
An array of objects with 26 fields
An array of objects:
idstringrequiredtitlestringrequiredtitle_idstring | nullrequiredstatus"draft" | "open" | "on_hold" | "filled" | "cancelled"requiredreason"new" | "replacement"requiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
reports_to_personobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
reports_to_positionobject | nullrequired2 fields
idstringrequiredtitlestringrequired
contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredweekly_hoursnumber | nullrequiredpay_rangeobject | nullrequired4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
pay_range_hiddenbooleanrequiredtarget_start_datestring | nullrequirednotesstring | nullrequiredreplacesobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
filled_byobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
filled_onstring | nullrequiredcan_reopenbooleanrequiredrequestobject | nullrequired4 fields
byobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
atstringrequirednotestring | nullrequiredwithdrawnbooleanrequired
title_descriptionstring | nullrequiredcustomobject[]required7 fields
keystringrequiredlabelstringrequiredtypestring (enum)requiredOne of:
text,number,date,select,boolean,file,person,table.tier"public" | "job" | "private"requiredvaluestring | number | boolean | object[]requiredFor type file: the document id (download it with
documents_downloadordocuments_me_download); over an API key or MCP, "attached" for someone else's file. For type person: the person id. For type table: the rows, [{ <column key>: value }] (columns inorg_fields_list).fileobject | nullType file only: the file, or null when none is attached.
4 fields
namestring | nullrequiredThe file name; null over an API key or MCP for someone else's file.
sizeintegerrequiredcontent_typestringrequiredpreviewablebooleanrequiredThe web app can show it (PDF, PNG, JPEG, WebP).
personobject | nullType person only: who it names (null when not set, or not someone you may see).
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
approvalobject | nullrequired7 fields
state"pending" | "approved" | "rejected" | "withdrawn"requiredreasons"always" | "over_plan" | "above_band"[]requiredWhy it needed approval: always, new headcount over the plan, pay above the band.
target_status"open" | "on_hold"requiredasked_byobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
asked_atstringrequiredstepsobject[]required8 fields
kind"manager" | "hr" | "role" | "person"requiredlabelstringrequiredWho decides it: the manager, HR, a role or a person.
state"waiting" | "pending" | "approved" | "rejected"requiredbyobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
atstring | nullrequiredcommentstring | nullrequiredautobooleanrequiredApproved by itself: nobody but the proposer could decide it (noted).
fallbackbooleanrequiredHR decides in place of the step's own approver, who could not.
closed_atstring | nullrequired
created_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/positions.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status":"on_hold","unit_id":"u1","reports_to_person_id":"p1"}'const res = await fetch('https://api.bizisy.com/v1/org/positions.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"status": "on_hold",
"unit_id": "u1",
"reports_to_person_id": "p1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/positions.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"status": "on_hold",
"unit_id": "u1",
"reports_to_person_id": "p1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"id": "pos1",
"title": "Data Engineer",
"title_id": "t2",
"status": "open",
"reason": "replacement",
"unit": {
"id": "u2",
"name": "Engineering"
},
"location": {
"id": "l1",
"name": "Lisbon"
},
"legal_entity": {
"id": "e1",
"name": "Acme Lda"
},
"reports_to_person": {
"id": "p1",
"name": "Ana Ferreira",
"title": "CTO",
"photo_url": null
},
"reports_to_position": null,
"contract_type": "permanent",
"weekly_hours": 40,
"pay_range": null,
"pay_range_hidden": true,
"target_start_date": "2026-12-01",
"notes": "Budget approved in Q3",
"replaces": {
"id": "p3",
"name": "Rui Costa",
"title": "Data Engineer",
"photo_url": null
},
"filled_by": null,
"filled_on": null,
"can_reopen": false,
"request": {
"by": {
"id": "p2",
"name": "Tomás Silva",
"title": "Engineering Manager",
"photo_url": null
},
"at": "2026-10-03T09:00:00.000Z",
"note": "Rui leaves at the end of November.",
"withdrawn": false
},
"title_description": "Builds and runs the data pipelines the company reports from.",
"custom": [
{
"key": "hiring_manager",
"label": "Hiring manager",
"type": "person",
"tier": "public",
"value": "p1",
"person": {
"id": "p1",
"name": "Ana Ferreira",
"title": "CTO",
"photo_url": null
}
}
],
"approval": null,
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:00:00.000Z"
},
{
"id": "pos2",
"title": "Data Engineer",
"title_id": "t2",
"status": "on_hold",
"reason": "new",
"unit": {
"id": "u2",
"name": "Engineering"
},
"location": {
"id": "l1",
"name": "Lisbon"
},
"legal_entity": {
"id": "e1",
"name": "Acme Lda"
},
"reports_to_person": null,
"reports_to_position": {
"id": "pos1",
"title": "Data Engineer"
},
"contract_type": "permanent",
"weekly_hours": 40,
"pay_range": null,
"pay_range_hidden": true,
"target_start_date": "2026-12-01",
"notes": null,
"replaces": null,
"filled_by": null,
"filled_on": null,
"can_reopen": false,
"request": {
"by": {
"id": "p2",
"name": "Tomás Silva",
"title": "Engineering Manager",
"photo_url": null
},
"at": "2026-10-03T09:00:00.000Z",
"note": "Rui leaves at the end of November.",
"withdrawn": false
},
"title_description": "Builds and runs the data pipelines the company reports from.",
"custom": [
{
"key": "hiring_manager",
"label": "Hiring manager",
"type": "person",
"tier": "public",
"value": "p1",
"person": {
"id": "p1",
"name": "Ana Ferreira",
"title": "CTO",
"photo_url": null
}
}
],
"approval": null,
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:00:00.000Z"
}
]
}Get an open position#
POST/v1/org/positions.getRead
Returns one position with the same visibility as org_positions_list: owners, admins and HR any position (filled and cancelled ones too); a manager the open and on-hold positions in their line; otherwise not_found.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
org_positions_geton My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
position_idstringrequired
Returns
26 fields
idstringrequiredtitlestringrequiredtitle_idstring | nullrequiredstatus"draft" | "open" | "on_hold" | "filled" | "cancelled"requiredreason"new" | "replacement"requiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
reports_to_personobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
reports_to_positionobject | nullrequired2 fields
idstringrequiredtitlestringrequired
contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredweekly_hoursnumber | nullrequiredpay_rangeobject | nullrequired4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
pay_range_hiddenbooleanrequiredtarget_start_datestring | nullrequirednotesstring | nullrequiredreplacesobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
filled_byobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
filled_onstring | nullrequiredcan_reopenbooleanrequiredrequestobject | nullrequired4 fields
byobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
atstringrequirednotestring | nullrequiredwithdrawnbooleanrequired
title_descriptionstring | nullrequiredcustomobject[]required7 fields
keystringrequiredlabelstringrequiredtypestring (enum)requiredOne of:
text,number,date,select,boolean,file,person,table.tier"public" | "job" | "private"requiredvaluestring | number | boolean | object[]requiredFor type file: the document id (download it with
documents_downloadordocuments_me_download); over an API key or MCP, "attached" for someone else's file. For type person: the person id. For type table: the rows, [{ <column key>: value }] (columns inorg_fields_list).fileobject | nullType file only: the file, or null when none is attached.
4 fields
namestring | nullrequiredThe file name; null over an API key or MCP for someone else's file.
sizeintegerrequiredcontent_typestringrequiredpreviewablebooleanrequiredThe web app can show it (PDF, PNG, JPEG, WebP).
personobject | nullType person only: who it names (null when not set, or not someone you may see).
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
approvalobject | nullrequired7 fields
state"pending" | "approved" | "rejected" | "withdrawn"requiredreasons"always" | "over_plan" | "above_band"[]requiredWhy it needed approval: always, new headcount over the plan, pay above the band.
target_status"open" | "on_hold"requiredasked_byobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
asked_atstringrequiredstepsobject[]required8 fields
kind"manager" | "hr" | "role" | "person"requiredlabelstringrequiredWho decides it: the manager, HR, a role or a person.
state"waiting" | "pending" | "approved" | "rejected"requiredbyobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
atstring | nullrequiredcommentstring | nullrequiredautobooleanrequiredApproved by itself: nobody but the proposer could decide it (noted).
fallbackbooleanrequiredHR decides in place of the step's own approver, who could not.
closed_atstring | nullrequired
created_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/positions.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"position_id":"pos1"}'const res = await fetch('https://api.bizisy.com/v1/org/positions.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"position_id": "pos1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/positions.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"position_id": "pos1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "pos1",
"title": "Data Engineer",
"title_id": "t2",
"status": "open",
"reason": "replacement",
"unit": {
"id": "u2",
"name": "Engineering"
},
"location": {
"id": "l1",
"name": "Lisbon"
},
"legal_entity": {
"id": "e1",
"name": "Acme Lda"
},
"reports_to_person": {
"id": "p1",
"name": "Ana Ferreira",
"title": "CTO",
"photo_url": null
},
"reports_to_position": null,
"contract_type": "permanent",
"weekly_hours": 40,
"pay_range": null,
"pay_range_hidden": true,
"target_start_date": "2026-12-01",
"notes": "Budget approved in Q3",
"replaces": {
"id": "p3",
"name": "Rui Costa",
"title": "Data Engineer",
"photo_url": null
},
"filled_by": null,
"filled_on": null,
"can_reopen": false,
"request": {
"by": {
"id": "p2",
"name": "Tomás Silva",
"title": "Engineering Manager",
"photo_url": null
},
"at": "2026-10-03T09:00:00.000Z",
"note": "Rui leaves at the end of November.",
"withdrawn": false
},
"title_description": "Builds and runs the data pipelines the company reports from.",
"custom": [
{
"key": "hiring_manager",
"label": "Hiring manager",
"type": "person",
"tier": "public",
"value": "p1",
"person": {
"id": "p1",
"name": "Ana Ferreira",
"title": "CTO",
"photo_url": null
}
}
],
"approval": null,
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:00:00.000Z"
}
}Create an open position#
POST/v1/org/positions.createWrite
Plans a role to fill. Required: title. Optional: status (open by default, or draft or on_hold), unit_id, location_id and legal_entity_id (default to the only active one), reports_to_person_id (someone employed now or starting soon) or reports_to_position_id (another draft, open or on-hold position; never both), contract_type, weekly_hours, target_start_date (YYYY-MM-DD), notes (owners, admins and HR only; do not put personal data here), reason ("new", default, or "replacement" with an optional replaces_person_id: the leaver), pay_range {min, max, currency, period: year, month or hour} — the budget, which can only be set by signing in to Bizisy (refused over MCP or an API key) —, and custom (position custom fields, org_fields_list target position, e.g. a cost centre; private ones are refused over MCP or an API key). At most 500 draft, open or on-hold positions per organization. Owners, admins and HR. Use dry_run first. To fill it, hire someone with org_people_hire and position_id.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- pay_range and private custom fields are refused.
- MCP tool
org_positions_createon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
titlestringThe job title as typed: matched to the job title catalog (exact name, an earlier wording, or the same words), else added to it when the change applies (see
org_titles_list).1–120 characters.
title_idstringA job title from
org_titles_list, instead of title.create_titlebooleanfalse: refuse a title that is not in the catalog yet (not_found with details.candidates) instead of adding it.
status"draft" | "open" | "on_hold"unit_idstring | nulllocation_idstring | nulllegal_entity_idstring | nullreports_to_person_idstring | nullreports_to_position_idstring | nullcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"weekly_hoursnumber | nullFrom 0 to 80.
pay_rangeobject | null4 fields
minnumberrequiredFrom 0 to 100000000.
maxnumberrequiredFrom 0 to 100000000.
currencyanyrequiredperiod"year" | "month" | "hour"required
target_start_datestring | nullnotesstring | nullUp to 1000 characters.
reason"new" | "replacement"replaces_person_idstring | nullcustomobjectPosition custom fields (
org_fields_list, target position) by key; null clears one. Private ones only in Bizisy, never over an API key or MCP.
Returns
27 fields
idstringrequiredtitlestringrequiredtitle_idstring | nullrequiredstatus"draft" | "open" | "on_hold" | "filled" | "cancelled"requiredreason"new" | "replacement"requiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
reports_to_personobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
reports_to_positionobject | nullrequired2 fields
idstringrequiredtitlestringrequired
contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredweekly_hoursnumber | nullrequiredpay_rangeobject | nullrequired4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
pay_range_hiddenbooleanrequiredtarget_start_datestring | nullrequirednotesstring | nullrequiredreplacesobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
filled_byobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
filled_onstring | nullrequiredcan_reopenbooleanrequiredrequestobject | nullrequired4 fields
byobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
atstringrequirednotestring | nullrequiredwithdrawnbooleanrequired
title_descriptionstring | nullrequiredcustomobject[]required7 fields
keystringrequiredlabelstringrequiredtypestring (enum)requiredOne of:
text,number,date,select,boolean,file,person,table.tier"public" | "job" | "private"requiredvaluestring | number | boolean | object[]requiredFor type file: the document id (download it with
documents_downloadordocuments_me_download); over an API key or MCP, "attached" for someone else's file. For type person: the person id. For type table: the rows, [{ <column key>: value }] (columns inorg_fields_list).fileobject | nullType file only: the file, or null when none is attached.
4 fields
namestring | nullrequiredThe file name; null over an API key or MCP for someone else's file.
sizeintegerrequiredcontent_typestringrequiredpreviewablebooleanrequiredThe web app can show it (PDF, PNG, JPEG, WebP).
personobject | nullType person only: who it names (null when not set, or not someone you may see).
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
approvalobject | nullrequired7 fields
state"pending" | "approved" | "rejected" | "withdrawn"requiredreasons"always" | "over_plan" | "above_band"[]requiredWhy it needed approval: always, new headcount over the plan, pay above the band.
target_status"open" | "on_hold"requiredasked_byobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
asked_atstringrequiredstepsobject[]required8 fields
kind"manager" | "hr" | "role" | "person"requiredlabelstringrequiredWho decides it: the manager, HR, a role or a person.
state"waiting" | "pending" | "approved" | "rejected"requiredbyobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
atstring | nullrequiredcommentstring | nullrequiredautobooleanrequiredApproved by itself: nobody but the proposer could decide it (noted).
fallbackbooleanrequiredHR decides in place of the step's own approver, who could not.
closed_atstring | nullrequired
created_atstringrequiredupdated_atstringrequiredtitle_matchobject | nullrequiredWhat happened to the job title: matched to the catalog, or new to it.
5 fields
idstring | nullrequiredThe catalog title; null while it waits for approval (it is added when the change applies).
namestringrequiredcreatedbooleanrequiredTrue: the title is new to the catalog (added now, or when an approval applies).
matched_fromstringWhat was typed, when the catalog names it differently.
similarobject[]Catalog titles that look the same as a new one: tell the user before applying.
3 fields
idstringrequirednamestringrequiredpeopleinteger | nullrequiredWho holds it today; null when you do not see the catalog counts.
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/positions.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"title": "Data Engineer",
"status": "draft",
"unit_id": "u2",
"location_id": null,
"legal_entity_id": "e1",
"reports_to_person_id": "p1",
"contract_type": "permanent",
"weekly_hours": 40,
"target_start_date": "2026-12-01",
"notes": "n",
"reason": "replacement",
"replaces_person_id": "p3"
}'const res = await fetch('https://api.bizisy.com/v1/org/positions.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"title": "Data Engineer",
"status": "draft",
"unit_id": "u2",
"location_id": null,
"legal_entity_id": "e1",
"reports_to_person_id": "p1",
"contract_type": "permanent",
"weekly_hours": 40,
"target_start_date": "2026-12-01",
"notes": "n",
"reason": "replacement",
"replaces_person_id": "p3"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/positions.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"title": "Data Engineer",
"status": "draft",
"unit_id": "u2",
"location_id": None,
"legal_entity_id": "e1",
"reports_to_person_id": "p1",
"contract_type": "permanent",
"weekly_hours": 40,
"target_start_date": "2026-12-01",
"notes": "n",
"reason": "replacement",
"replaces_person_id": "p3",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "pos1",
"title": "Data Engineer",
"title_id": "t2",
"status": "draft",
"reason": "replacement",
"unit": {
"id": "u2",
"name": "Engineering"
},
"location": {
"id": "l1",
"name": "Lisbon"
},
"legal_entity": {
"id": "e1",
"name": "Acme Lda"
},
"reports_to_person": {
"id": "p1",
"name": "Ana Ferreira",
"title": "CTO",
"photo_url": null
},
"reports_to_position": null,
"contract_type": "permanent",
"weekly_hours": 40,
"pay_range": null,
"pay_range_hidden": true,
"target_start_date": "2026-12-01",
"notes": "n",
"replaces": {
"id": "p3",
"name": "Rui Costa",
"title": "Data Engineer",
"photo_url": null
},
"filled_by": null,
"filled_on": null,
"can_reopen": false,
"request": {
"by": {
"id": "p2",
"name": "Tomás Silva",
"title": "Engineering Manager",
"photo_url": null
},
"at": "2026-10-03T09:00:00.000Z",
"note": "Rui leaves at the end of November.",
"withdrawn": false
},
"title_description": "Builds and runs the data pipelines the company reports from.",
"custom": [
{
"key": "hiring_manager",
"label": "Hiring manager",
"type": "person",
"tier": "public",
"value": "p1",
"person": {
"id": "p1",
"name": "Ana Ferreira",
"title": "CTO",
"photo_url": null
}
}
],
"approval": null,
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:00:00.000Z",
"title_match": {
"id": "t2",
"name": "Data Engineer",
"created": false
}
}
}Change an open position#
POST/v1/org/positions.updateWrite
Changes a position: any field of org_positions_create (null clears one; setting reports_to_person_id clears reports_to_position_id and the other way round; reason "new" clears replaces_person_id) and status: draft → open, on_hold or cancelled; open ↔ on_hold; open or on hold → cancelled; cancelled → draft or open (reopen; who it reports to is checked again). Cancelling a position moves the positions that reported to it to whoever it reported to. "filled" is never set here: hire into the position with org_people_hire and position_id. custom changes position custom fields (org_fields_list, target position; null clears one; private ones are refused over MCP or an API key). A filled position only takes notes and custom fields; if its hire did not start, reopen it with org_positions_reopen. pay_range can only be changed by signing in to Bizisy (refused over MCP or an API key; leave it out to keep it). Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- pay_range and private custom fields are refused.
- MCP tool
org_positions_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
position_idstringrequiredtitlestringThe job title as typed: matched to the job title catalog (exact name, an earlier wording, or the same words), else added to it when the change applies (see
org_titles_list).1–120 characters.
title_idstringA job title from
org_titles_list, instead of title.create_titlebooleanfalse: refuse a title that is not in the catalog yet (not_found with details.candidates) instead of adding it.
status"draft" | "open" | "on_hold" | "filled" | "cancelled"unit_idstring | nulllocation_idstring | nulllegal_entity_idstring | nullreports_to_person_idstring | nullreports_to_position_idstring | nullcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"weekly_hoursnumber | nullFrom 0 to 80.
pay_rangeobject | null4 fields
minnumberrequiredFrom 0 to 100000000.
maxnumberrequiredFrom 0 to 100000000.
currencyanyrequiredperiod"year" | "month" | "hour"required
target_start_datestring | nullnotesstring | nullUp to 1000 characters.
reason"new" | "replacement"replaces_person_idstring | nullcustomobjectPosition custom fields (
org_fields_list, target position) by key; null clears one. Private ones only in Bizisy, never over an API key or MCP.
Returns
26 fields
idstringrequiredtitlestringrequiredtitle_idstring | nullrequiredstatus"draft" | "open" | "on_hold" | "filled" | "cancelled"requiredreason"new" | "replacement"requiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
reports_to_personobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
reports_to_positionobject | nullrequired2 fields
idstringrequiredtitlestringrequired
contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredweekly_hoursnumber | nullrequiredpay_rangeobject | nullrequired4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
pay_range_hiddenbooleanrequiredtarget_start_datestring | nullrequirednotesstring | nullrequiredreplacesobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
filled_byobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
filled_onstring | nullrequiredcan_reopenbooleanrequiredrequestobject | nullrequired4 fields
byobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
atstringrequirednotestring | nullrequiredwithdrawnbooleanrequired
title_descriptionstring | nullrequiredcustomobject[]required7 fields
keystringrequiredlabelstringrequiredtypestring (enum)requiredOne of:
text,number,date,select,boolean,file,person,table.tier"public" | "job" | "private"requiredvaluestring | number | boolean | object[]requiredFor type file: the document id (download it with
documents_downloadordocuments_me_download); over an API key or MCP, "attached" for someone else's file. For type person: the person id. For type table: the rows, [{ <column key>: value }] (columns inorg_fields_list).fileobject | nullType file only: the file, or null when none is attached.
4 fields
namestring | nullrequiredThe file name; null over an API key or MCP for someone else's file.
sizeintegerrequiredcontent_typestringrequiredpreviewablebooleanrequiredThe web app can show it (PDF, PNG, JPEG, WebP).
personobject | nullType person only: who it names (null when not set, or not someone you may see).
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
approvalobject | nullrequired7 fields
state"pending" | "approved" | "rejected" | "withdrawn"requiredreasons"always" | "over_plan" | "above_band"[]requiredWhy it needed approval: always, new headcount over the plan, pay above the band.
target_status"open" | "on_hold"requiredasked_byobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
asked_atstringrequiredstepsobject[]required8 fields
kind"manager" | "hr" | "role" | "person"requiredlabelstringrequiredWho decides it: the manager, HR, a role or a person.
state"waiting" | "pending" | "approved" | "rejected"requiredbyobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
atstring | nullrequiredcommentstring | nullrequiredautobooleanrequiredApproved by itself: nobody but the proposer could decide it (noted).
fallbackbooleanrequiredHR decides in place of the step's own approver, who could not.
closed_atstring | nullrequired
created_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/positions.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"position_id": "pos1",
"title": "Lead",
"reports_to_position_id": "pos2",
"reports_to_person_id": null,
"notes": null,
"reason": "new"
}'const res = await fetch('https://api.bizisy.com/v1/org/positions.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"position_id": "pos1",
"title": "Lead",
"reports_to_position_id": "pos2",
"reports_to_person_id": null,
"notes": null,
"reason": "new"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/positions.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"position_id": "pos1",
"title": "Lead",
"reports_to_position_id": "pos2",
"reports_to_person_id": None,
"notes": None,
"reason": "new",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "pos1",
"title": "Lead",
"title_id": "t2",
"status": "filled",
"reason": "new",
"unit": {
"id": "u2",
"name": "Engineering"
},
"location": {
"id": "l1",
"name": "Lisbon"
},
"legal_entity": {
"id": "e1",
"name": "Acme Lda"
},
"reports_to_person": {
"id": "p1",
"name": "Ana Ferreira",
"title": "CTO",
"photo_url": null
},
"reports_to_position": null,
"contract_type": "permanent",
"weekly_hours": 40,
"pay_range": null,
"pay_range_hidden": true,
"target_start_date": "2026-12-01",
"notes": null,
"replaces": {
"id": "p3",
"name": "Rui Costa",
"title": "Data Engineer",
"photo_url": null
},
"filled_by": {
"id": "p9",
"name": "Zoe Lima",
"title": "Data Engineer",
"photo_url": null
},
"filled_on": "2026-12-01",
"can_reopen": true,
"request": {
"by": {
"id": "p2",
"name": "Tomás Silva",
"title": "Engineering Manager",
"photo_url": null
},
"at": "2026-10-03T09:00:00.000Z",
"note": "Rui leaves at the end of November.",
"withdrawn": false
},
"title_description": "Builds and runs the data pipelines the company reports from.",
"custom": [
{
"key": "hiring_manager",
"label": "Hiring manager",
"type": "person",
"tier": "public",
"value": "p1",
"person": {
"id": "p1",
"name": "Ana Ferreira",
"title": "CTO",
"photo_url": null
}
}
],
"approval": null,
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:00:00.000Z"
}
}Reopen a filled position (the hire did not start)#
POST/v1/org/positions.reopenWrite
Puts a filled position back to open when its hire fell through: the person was terminated on or before their start date, or erased (can_reopen in org_positions_get). The positions that were moved under that person go back under this position, and their job no longer records it. Refused otherwise (conflict). Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_positions_reopenon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
position_idstringrequired
Returns
26 fields
idstringrequiredtitlestringrequiredtitle_idstring | nullrequiredstatus"draft" | "open" | "on_hold" | "filled" | "cancelled"requiredreason"new" | "replacement"requiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
reports_to_personobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
reports_to_positionobject | nullrequired2 fields
idstringrequiredtitlestringrequired
contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredweekly_hoursnumber | nullrequiredpay_rangeobject | nullrequired4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
pay_range_hiddenbooleanrequiredtarget_start_datestring | nullrequirednotesstring | nullrequiredreplacesobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
filled_byobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
filled_onstring | nullrequiredcan_reopenbooleanrequiredrequestobject | nullrequired4 fields
byobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
atstringrequirednotestring | nullrequiredwithdrawnbooleanrequired
title_descriptionstring | nullrequiredcustomobject[]required7 fields
keystringrequiredlabelstringrequiredtypestring (enum)requiredOne of:
text,number,date,select,boolean,file,person,table.tier"public" | "job" | "private"requiredvaluestring | number | boolean | object[]requiredFor type file: the document id (download it with
documents_downloadordocuments_me_download); over an API key or MCP, "attached" for someone else's file. For type person: the person id. For type table: the rows, [{ <column key>: value }] (columns inorg_fields_list).fileobject | nullType file only: the file, or null when none is attached.
4 fields
namestring | nullrequiredThe file name; null over an API key or MCP for someone else's file.
sizeintegerrequiredcontent_typestringrequiredpreviewablebooleanrequiredThe web app can show it (PDF, PNG, JPEG, WebP).
personobject | nullType person only: who it names (null when not set, or not someone you may see).
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
approvalobject | nullrequired7 fields
state"pending" | "approved" | "rejected" | "withdrawn"requiredreasons"always" | "over_plan" | "above_band"[]requiredWhy it needed approval: always, new headcount over the plan, pay above the band.
target_status"open" | "on_hold"requiredasked_byobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
asked_atstringrequiredstepsobject[]required8 fields
kind"manager" | "hr" | "role" | "person"requiredlabelstringrequiredWho decides it: the manager, HR, a role or a person.
state"waiting" | "pending" | "approved" | "rejected"requiredbyobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
atstring | nullrequiredcommentstring | nullrequiredautobooleanrequiredApproved by itself: nobody but the proposer could decide it (noted).
fallbackbooleanrequiredHR decides in place of the step's own approver, who could not.
closed_atstring | nullrequired
created_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/positions.reopen \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"position_id":"pos1"}'const res = await fetch('https://api.bizisy.com/v1/org/positions.reopen', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"position_id": "pos1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/positions.reopen",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"position_id": "pos1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "pos1",
"title": "Data Engineer",
"title_id": "t2",
"status": "open",
"reason": "replacement",
"unit": {
"id": "u2",
"name": "Engineering"
},
"location": {
"id": "l1",
"name": "Lisbon"
},
"legal_entity": {
"id": "e1",
"name": "Acme Lda"
},
"reports_to_person": {
"id": "p1",
"name": "Ana Ferreira",
"title": "CTO",
"photo_url": null
},
"reports_to_position": null,
"contract_type": "permanent",
"weekly_hours": 40,
"pay_range": null,
"pay_range_hidden": true,
"target_start_date": "2026-12-01",
"notes": "Budget approved in Q3",
"replaces": {
"id": "p3",
"name": "Rui Costa",
"title": "Data Engineer",
"photo_url": null
},
"filled_by": null,
"filled_on": null,
"can_reopen": false,
"request": {
"by": {
"id": "p2",
"name": "Tomás Silva",
"title": "Engineering Manager",
"photo_url": null
},
"at": "2026-10-03T09:00:00.000Z",
"note": "Rui leaves at the end of November.",
"withdrawn": false
},
"title_description": "Builds and runs the data pipelines the company reports from.",
"custom": [
{
"key": "hiring_manager",
"label": "Hiring manager",
"type": "person",
"tier": "public",
"value": "p1",
"person": {
"id": "p1",
"name": "Ana Ferreira",
"title": "CTO",
"photo_url": null
}
}
],
"approval": null,
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:00:00.000Z"
}
}Get the approval rule for opening positions#
POST/v1/org/positions.approval_rule.getRead
Settings → Approval rules → Opening a position: when opening a position (a headcount request) needs approval — off (default), always, over_plan (only new headcount above the team's headcount budget for its target month; replacements never), above_band (a pay range above the band of its title), over_plan_or_above_band — and who approves, in order (manager, hr, a role, a named person). Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_positions_approval_rule_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
when"off" | "always" | "over_plan" | "above_band" | "over_plan_or_above_band"requiredoff (default: positions open at once), always, over_plan (only new headcount above the team's headcount budget for its target month), above_band (only a pay range above the pay band of its title), over_plan_or_above_band.
stepsobject[]requiredWho approves, in order.
4 fields
kind"manager" | "hr" | "role" | "person"requiredmanager: the person the position reports to (their own manager when they asked for it); hr: an owner, admin or HR member; role: anyone with a custom role (role_id,
platform_roles_list); person: one named person (person_id), e.g. the finance director.role_idstring | nullrequiredperson_idstring | nullrequiredlabelstringrequiredWho decides, in words.
updated_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/positions.approval_rule.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/positions.approval_rule.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/positions.approval_rule.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"when": "over_plan",
"steps": [
{
"kind": "manager",
"role_id": null,
"person_id": null,
"label": "The manager it reports to"
},
{
"kind": "person",
"role_id": null,
"person_id": "p6",
"label": "Marta Rocha"
}
],
"updated_at": "2026-10-04T10:00:00.000Z"
}
}Change the approval rule for opening positions#
POST/v1/org/positions.approval_rule.updateWrite
Sets when opening a position needs approval (when: off, always, over_plan, above_band, over_plan_or_above_band) and who approves, in order (steps, 1 to 5: manager, hr, role with role_id, person with person_id). Positions already waiting keep their steps. Owners and admins, in the app only (never over an API key or MCP, so an assistant can never switch approval off).
- Web app only
- Refused for API keys and connected apps. Who approves new positions is set in the app only, so an assistant can never switch approval off.
- MCP tool
org_positions_approval_rule_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
when"off" | "always" | "over_plan" | "above_band" | "over_plan_or_above_band"requiredstepsobject[]required1–5 items.
3 fields
kind"manager" | "hr" | "role" | "person"requiredrole_idstring | null1–100 characters.
person_idstring | null1–100 characters.
Returns
when"off" | "always" | "over_plan" | "above_band" | "over_plan_or_above_band"requiredoff (default: positions open at once), always, over_plan (only new headcount above the team's headcount budget for its target month), above_band (only a pay range above the pay band of its title), over_plan_or_above_band.
stepsobject[]requiredWho approves, in order.
4 fields
kind"manager" | "hr" | "role" | "person"requiredmanager: the person the position reports to (their own manager when they asked for it); hr: an owner, admin or HR member; role: anyone with a custom role (role_id,
platform_roles_list); person: one named person (person_id), e.g. the finance director.role_idstring | nullrequiredperson_idstring | nullrequiredlabelstringrequiredWho decides, in words.
updated_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/positions.approval_rule.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"when": "over_plan_or_above_band",
"steps": [
{
"kind": "manager"
},
{
"kind": "role",
"role_id": "r1"
},
{
"kind": "person",
"person_id": "p6",
"role_id": null
}
]
}'const res = await fetch('https://api.bizisy.com/v1/org/positions.approval_rule.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"when": "over_plan_or_above_band",
"steps": [
{
"kind": "manager"
},
{
"kind": "role",
"role_id": "r1"
},
{
"kind": "person",
"person_id": "p6",
"role_id": null
}
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/positions.approval_rule.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"when": "over_plan_or_above_band",
"steps": [
{
"kind": "manager",
},
{
"kind": "role",
"role_id": "r1",
},
{
"kind": "person",
"person_id": "p6",
"role_id": None,
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"when": "over_plan_or_above_band",
"steps": [
{
"kind": "manager",
"role_id": null,
"person_id": null,
"label": "The manager it reports to"
},
{
"kind": "person",
"role_id": null,
"person_id": "p6",
"label": "Marta Rocha"
}
],
"updated_at": "2026-10-04T10:00:00.000Z"
}
}Positions waiting for approval#
POST/v1/org/positions.requestsRead
Requests to open a position (headcount requests) under Settings → Approval rules → Opening a position: status open (default: waiting), decided (approved, rejected, withdrawn; newest 100) or all; waiting_for_me only those you can decide now; unit_id narrows to a team. Each has the position (title, team, location, who it reports to, target start), why it needs approval (always, over_plan, above_band), the steps with who decided, who can decide now, and — for its approvers and owners, admins and HR, in the app — the numbers: the pay range, the band of its title and the team's headcount budget against people, open and requested positions. Owners, admins and HR see every request; others the ones they asked for or approve. Deciding is in the app (org_positions_decide refuses API keys and MCP).
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
org_positions_requestson HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
status"open" | "decided" | "all"Default
"open".waiting_for_mebooleanunit_idstring1–100 characters.
Returns
itemsobject[]required7 fields
positionobjectrequired10 fields
idstringrequiredtitlestringrequiredreason"new" | "replacement"requiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
reports_toobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
target_start_datestring | nullrequiredcontract_typestring | nullrequiredweekly_hoursnumber | nullrequiredstatusstringrequired
approvalobjectrequired7 fields
state"pending" | "approved" | "rejected" | "withdrawn"requiredreasons"always" | "over_plan" | "above_band"[]requiredtarget_status"open" | "on_hold"requiredasked_byobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
asked_atstringrequiredclosed_atstring | nullrequiredstepsobject[]required8 fields
kind"manager" | "hr" | "role" | "person"requiredlabelstringrequiredstate"waiting" | "pending" | "approved" | "rejected"requiredbyobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
atstring | nullrequiredcommentstring | nullrequiredautobooleanrequiredfallbackbooleanrequired
impactobject | nullrequiredThe numbers when asked (pay tier): approvers and owners, admins and HR, in the app; null for others.
4 fields
budgetobject | nullrequiredThe plan of its team (or the nearest team above it with one) for its target month; null without a plan.
8 fields
unitobjectrequired2 fields
idstringrequirednamestringrequired
monthstringrequiredheadcountintegerrequiredThe headcount budget in force.
actualintegerrequiredopenintegerrequiredrequestedintegerrequiredOther positions waiting for approval there.
afterintegerrequiredactual + open + requested + this one.
overbooleanrequired
payobject | nullrequired4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
bandobject | nullrequired4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
above_bandbooleanrequired
stepinteger | nullrequiredThe open step (null when decided).
waiting_forstring[]requiredWho can decide the open step now (names).
can_decidebooleanrequiredcan_withdrawbooleanrequired
waiting_for_meintegerrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/positions.requests \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status":"all","waiting_for_me":true,"unit_id":"u2"}'const res = await fetch('https://api.bizisy.com/v1/org/positions.requests', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"status": "all",
"waiting_for_me": true,
"unit_id": "u2"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/positions.requests",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"status": "all",
"waiting_for_me": True,
"unit_id": "u2",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"items": [
{
"position": {
"id": "pos1",
"title": "Data Engineer",
"reason": "new",
"unit": {
"id": "u2",
"name": "Engineering"
},
"location": {
"id": "l1",
"name": "Lisbon"
},
"reports_to": {
"id": "p1",
"name": "Ana Ferreira",
"title": "CTO",
"photo_url": null
},
"target_start_date": "2026-12-01",
"contract_type": "permanent",
"weekly_hours": 40,
"status": "draft"
},
"approval": {
"state": "pending",
"reasons": [
"over_plan"
],
"target_status": "open",
"asked_by": {
"id": "p2",
"name": "Tomás Silva",
"title": "Engineering Manager",
"photo_url": null
},
"asked_at": "2026-10-04T10:00:00.000Z",
"steps": [
{
"kind": "manager",
"label": "The manager it reports to",
"state": "pending",
"by": null,
"at": null,
"comment": null,
"auto": false,
"fallback": false
},
{
"kind": "person",
"label": "Marta Rocha",
"state": "waiting",
"by": null,
"at": null,
"comment": null,
"auto": false,
"fallback": false
}
],
"closed_at": null
},
"impact": {
"budget": {
"unit": {
"id": "u2",
"name": "Engineering"
},
"month": "2026-12",
"headcount": 8,
"actual": 7,
"open": 1,
"requested": 0,
"after": 9,
"over": true
},
"pay": {
"min": 40000,
"max": 52000,
"currency": "EUR",
"period": "year"
},
"band": {
"min": 38000,
"max": 50000,
"currency": "EUR",
"period": "year"
},
"above_band": true
},
"step": 0,
"waiting_for": [
"Ana Ferreira"
],
"can_decide": true,
"can_withdraw": false
}
],
"waiting_for_me": 1
}
}Approve or reject opening a position#
POST/v1/org/positions.decideWrite
Decides the open step of a request to open a position (org_positions_requests): approve (the next step's approvers are asked; after the last one the position opens with the status asked for, open or on hold) or reject with a comment saying why (the position is cancelled and keeps the reason; whoever asked is emailed). Only the step's approvers, never the person who asked. In the app only: refused over an API key or MCP.
- Web app only
- Refused for API keys and connected apps. Approving a position needs a person signed in to Bizisy.
- MCP tool
org_positions_decideon HR Assistant, My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
position_idstringrequired1–100 characters.
decision"approve" | "reject"requiredcommentstringUp to 500 characters.
stepintegerThe step you saw: refused when the request moved on meanwhile.
From 0 to 5.
Returns
7 fields
positionobjectrequired10 fields
idstringrequiredtitlestringrequiredreason"new" | "replacement"requiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
reports_toobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
target_start_datestring | nullrequiredcontract_typestring | nullrequiredweekly_hoursnumber | nullrequiredstatusstringrequired
approvalobjectrequired7 fields
state"pending" | "approved" | "rejected" | "withdrawn"requiredreasons"always" | "over_plan" | "above_band"[]requiredtarget_status"open" | "on_hold"requiredasked_byobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
asked_atstringrequiredclosed_atstring | nullrequiredstepsobject[]required8 fields
kind"manager" | "hr" | "role" | "person"requiredlabelstringrequiredstate"waiting" | "pending" | "approved" | "rejected"requiredbyobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
atstring | nullrequiredcommentstring | nullrequiredautobooleanrequiredfallbackbooleanrequired
impactobject | nullrequiredThe numbers when asked (pay tier): approvers and owners, admins and HR, in the app; null for others.
4 fields
budgetobject | nullrequiredThe plan of its team (or the nearest team above it with one) for its target month; null without a plan.
8 fields
unitobjectrequired2 fields
idstringrequirednamestringrequired
monthstringrequiredheadcountintegerrequiredThe headcount budget in force.
actualintegerrequiredopenintegerrequiredrequestedintegerrequiredOther positions waiting for approval there.
afterintegerrequiredactual + open + requested + this one.
overbooleanrequired
payobject | nullrequired4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
bandobject | nullrequired4 fields
minnumberrequiredmaxnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"required
above_bandbooleanrequired
stepinteger | nullrequiredThe open step (null when decided).
waiting_forstring[]requiredWho can decide the open step now (names).
can_decidebooleanrequiredcan_withdrawbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/positions.decide \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"position_id": "pos1",
"decision": "reject",
"comment": "Not in this year'\''s budget",
"step": 1
}'const res = await fetch('https://api.bizisy.com/v1/org/positions.decide', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"position_id": "pos1",
"decision": "reject",
"comment": "Not in this year's budget",
"step": 1
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/positions.decide",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"position_id": "pos1",
"decision": "reject",
"comment": "Not in this year's budget",
"step": 1,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"position": {
"id": "pos1",
"title": "Data Engineer",
"reason": "new",
"unit": {
"id": "u2",
"name": "Engineering"
},
"location": {
"id": "l1",
"name": "Lisbon"
},
"reports_to": {
"id": "p1",
"name": "Ana Ferreira",
"title": "CTO",
"photo_url": null
},
"target_start_date": "2026-12-01",
"contract_type": "permanent",
"weekly_hours": 40,
"status": "draft"
},
"approval": {
"state": "pending",
"reasons": [
"over_plan"
],
"target_status": "open",
"asked_by": {
"id": "p2",
"name": "Tomás Silva",
"title": "Engineering Manager",
"photo_url": null
},
"asked_at": "2026-10-04T10:00:00.000Z",
"steps": [
{
"kind": "manager",
"label": "The manager it reports to",
"state": "approved",
"by": {
"id": "p1",
"name": "Ana Ferreira",
"title": "CTO",
"photo_url": null
},
"at": "2026-10-05T09:00:00.000Z",
"comment": null,
"auto": false,
"fallback": false
},
{
"kind": "person",
"label": "Marta Rocha",
"state": "pending",
"by": null,
"at": null,
"comment": null,
"auto": false,
"fallback": false
}
],
"closed_at": null
},
"impact": {
"budget": {
"unit": {
"id": "u2",
"name": "Engineering"
},
"month": "2026-12",
"headcount": 8,
"actual": 7,
"open": 1,
"requested": 0,
"after": 9,
"over": true
},
"pay": {
"min": 40000,
"max": 52000,
"currency": "EUR",
"period": "year"
},
"band": {
"min": 38000,
"max": 50000,
"currency": "EUR",
"period": "year"
},
"above_band": true
},
"step": 1,
"waiting_for": [
"Ana Ferreira"
],
"can_decide": true,
"can_withdraw": false
}
}Headcount budgets#
POST/v1/org/budgets.listRead
Headcount budget against actual per team on as_of (default today): a budget covers the team and every team below it, from its from_month until the team's next budget. For every live team with a budget (or, with include_all, every live team): budget in force, the next one, actual headcount and FTE employed on that day, open positions (status open, only when as_of is today), remaining (budget − actual − open) and status (over, over_with_open, on_budget, room). totals sums the top-level budgeted teams only (a team inside a budgeted department is part of the department's number). Owners, admins and HR; never a custom role. Part of the Reports & analytics module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).
- Who can call it
- Manage key owner admin hr
- MCP tool
org_budgets_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
as_ofstringinclude_allbooleanDefault
false.
Returns
as_ofstringrequiredmonthstringrequiredteamsobject[]required8 fields
unitobjectrequired4 fields
idstringrequirednamestringrequiredkindstringrequiredparent_idstring | nullrequired
budgetobject | nullrequiredThe budget in force on as_of (null: none yet; next says when one starts).
4 fields
from_monthstringrequiredheadcountintegerrequiredftenumber | nullrequirednotestring | nullrequired
nextobject | nullrequiredThe next budget row after as_of, if any.
4 fields
from_monthstringrequiredheadcountintegerrequiredftenumber | nullrequirednotestring | nullrequired
actualobjectrequiredPeople employed on as_of in this team and every team below it.
2 fields
headcountintegerrequiredftenumberrequired
openintegerrequiredOpen positions (status open; drafts and on-hold roles are not counted) in this team and below; only when as_of is today, else 0.
remaininginteger | nullrequiredbudget − actual − open: places left to plan; negative when over. null without a budget.
status"over" | "over_with_open" | "on_budget" | "room"requiredover (more people than budgeted), over_with_open (filling the open roles would pass it), on_budget, room; null without a budget.
historyobject[]requiredEvery budget row of this team, oldest first.
4 fields
from_monthstringrequiredheadcountintegerrequiredftenumber | nullrequirednotestring | nullrequired
totalsobjectrequired5 fields
budgetintegerrequiredactualintegerrequiredopenintegerrequiredremainingintegerrequiredoverintegerrequiredBudgeted teams over their budget.
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/budgets.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"as_of":"2026-12-31","include_all":true}'const res = await fetch('https://api.bizisy.com/v1/org/budgets.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"as_of": "2026-12-31",
"include_all": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/budgets.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"as_of": "2026-12-31",
"include_all": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"as_of": "2026-12-31",
"month": "2026-10",
"teams": [
{
"unit": {
"id": "u2",
"name": "Engineering",
"kind": "department",
"parent_id": "u1"
},
"budget": {
"from_month": "2026-01",
"headcount": 8,
"fte": null,
"note": "FY26 plan"
},
"next": null,
"actual": {
"headcount": 6,
"fte": 5.5
},
"open": 2,
"remaining": 0,
"status": "on_budget",
"history": [
{
"from_month": "2026-01",
"headcount": 8,
"fte": null,
"note": "FY26 plan"
}
]
}
],
"totals": {
"budget": 8,
"actual": 6,
"open": 2,
"remaining": 0,
"over": 0
}
}
}Set a headcount budget#
POST/v1/org/budgets.setWrite
Sets a team's headcount budget from from_month (YYYY-MM; default this month) on: headcount (people, 0–10000), optionally fte and a note (at most 300 characters). It holds until the team's next budget row; setting the same month again replaces that row. A budget covers the team and every team below it. Owners, admins and HR; never a custom role. Part of the Reports & analytics module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).
- Who can call it
- Manage key owner admin hr
- MCP tool
org_budgets_seton HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
unit_idstringrequiredfrom_monthstringPattern
^\d{4}-(0[1-9]|1[0-2])$.headcountintegerrequiredFrom 0 to 10000.
ftenumber | nullFrom 0 to 10000.
notestring | nullUp to 300 characters.
Returns
unit_idstringrequiredunit_namestringrequiredreplacedbooleanrequiredrowobjectrequired4 fields
from_monthstringrequiredheadcountintegerrequiredftenumber | nullrequirednotestring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/budgets.set \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"unit_id": "u2",
"from_month": "2027-01",
"headcount": 10,
"fte": 9.5,
"note": "FY27 plan"
}'const res = await fetch('https://api.bizisy.com/v1/org/budgets.set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"unit_id": "u2",
"from_month": "2027-01",
"headcount": 10,
"fte": 9.5,
"note": "FY27 plan"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/budgets.set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"unit_id": "u2",
"from_month": "2027-01",
"headcount": 10,
"fte": 9.5,
"note": "FY27 plan",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"unit_id": "u2",
"unit_name": "Engineering",
"replaced": false,
"row": {
"from_month": "2026-10",
"headcount": 8,
"fte": null,
"note": null
}
}
}Remove a headcount budget#
POST/v1/org/budgets.removeWrite
Removes a team's budget row for from_month (YYYY-MM). The row before it (if any) then holds on. Owners, admins and HR; never a custom role. Part of the Reports & analytics module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).
- Who can call it
- Manage key owner admin hr
- MCP tool
org_budgets_removeon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
unit_idstringrequiredfrom_monthstringrequiredPattern
^\d{4}-(0[1-9]|1[0-2])$.
Returns
unit_idstringrequiredfrom_monthstringrequiredremovedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/budgets.remove \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"unit_id":"u2","from_month":"2027-01"}'const res = await fetch('https://api.bizisy.com/v1/org/budgets.remove', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"unit_id": "u2",
"from_month": "2027-01"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/budgets.remove",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"unit_id": "u2",
"from_month": "2027-01",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"unit_id": "u2",
"from_month": "2027-01",
"removed": true
}
}Something missing or wrong on this page? Write to hello@bizisy.com.