API reference
People
The directory, finding anything by name, queries over people, one person's profile, profile changes and photos, and bank account changes with a proof (Verified bank details).
25 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
List people (directory)#
POST/v1/org/people.listRead
Lists people as of a date (default: today in the company time zone), sorted by name. Returns public fields only (use org_people_get for one person). Filters combine (AND): status defaults to active + pre_hire ("terminated" or "all" include leavers; when joined_between or left_between is set it defaults to all); q searches name, email and title (case-insensitive); unit_id (ids from org_units_list; include_subunits=true adds every unit below it); location_id (org_locations_list); manager_id (a person id: their direct reports). HR filters (owners, admins and HR, in the app only; forbidden for others and over MCP or an API key, since they reveal job details): legal_entity_id (org_entities_list); joined_between {from, to} (YYYY-MM-DD, inclusive: an employment period, hire or rehire, starts in the range) and left_between {from, to} (the last day of an employment period falls in the range, including scheduled ones), counted as org_reports_headcount counts joiners and leavers. Unit, location, entity and manager are those of the job shown for the person as of the date (for leavers, their last job). A scheduled last day is job detail: with a future as_of, people whose job you cannot see still show as employed if they are today. Unknown ids are not_found. Erased people are never listed. group_id: only members of a saved group (org_groups_list), today and as you see them (a condition on data you may not see for someone is not met for them); for owners, admins, HR, viewers and custom roles that are not outsiders.
- Who can call it
- Manage key any Manage role
Me key anyone - Keys and apps
- The HR filters legal_entity_id, joined_between and left_between are refused.
- MCP tool
org_people_liston My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
as_ofstringstatus"active" | "pre_hire" | "terminated" | "invited" | "all"invited: people invited by email who are still waiting for their details (owners, admins and HR, and roles that cover them).
qstringUp to 100 characters.
unit_idstringinclude_subunitsbooleanlocation_idstringlegal_entity_idstringmanager_idstringjoined_betweenobject2 fields
fromstringrequiredtostringrequired
left_betweenobject2 fields
fromstringrequiredtostringrequired
group_idstring
Returns
An array of objects with 15 fields
An array of objects:
idstringrequirednamestringrequiredgiven_namestringrequiredfamily_namestringrequiredpreferred_namestring | nullrequiredwork_emailstringrequiredtitlestring | nullrequiredstatus"invited" | "pre_hire" | "active" | "terminated" | "none"requiredinvited: waiting for their details (names, title, start date), not employed yet; pre_hire: starts later; active; terminated: has left; none: no job.
start_datestring | nullrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
invitedbooleanrequiredhas_loginbooleanrequiredphoto_urlstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/people.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"joined_between": {
"from": "2026-03-01",
"to": "2026-03-31"
},
"left_between": {
"from": "2026-01-01",
"to": "2026-12-31"
}
}'const res = await fetch('https://api.bizisy.com/v1/org/people.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"joined_between": {
"from": "2026-03-01",
"to": "2026-03-31"
},
"left_between": {
"from": "2026-01-01",
"to": "2026-12-31"
}
}),
});
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/people.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"joined_between": {
"from": "2026-03-01",
"to": "2026-03-31",
},
"left_between": {
"from": "2026-01-01",
"to": "2026-12-31",
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"id": "p1",
"name": "Ana Ferreira",
"given_name": "Ana",
"family_name": "Ferreira",
"preferred_name": null,
"work_email": "ana@acme.test",
"title": "Engineer",
"status": "active",
"start_date": "2024-01-15",
"unit": {
"id": "u2",
"name": "Engineering"
},
"location": {
"id": "l1",
"name": "Head office"
},
"manager": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"invited": true,
"has_login": true,
"photo_url": null
},
{
"id": "p3",
"name": "Ana Ferreira",
"given_name": "Ana",
"family_name": "Ferreira",
"preferred_name": null,
"work_email": "ana@acme.test",
"title": "Engineer",
"status": "pre_hire",
"start_date": "2024-01-15",
"unit": null,
"location": null,
"manager": null,
"invited": true,
"has_login": true,
"photo_url": null
}
]
}Get a person#
POST/v1/org/people.getRead
Returns one person as of a date: profile, current job, manager, direct reports and job history. Fields you may not see come back null; visible_tiers says which tiers (public, private, job, pay) you got; custom lists the custom fields you may see. Over MCP or an API key, private fields are only returned for yourself. Pay is separate: org_pay_list.
- Who can call it
- Manage key any Manage role
Me key anyone - Keys and apps
- Private fields only for yourself.
- MCP tool
org_people_geton My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
person_idstringrequiredas_ofstring
Returns
35 fields
idstringrequirednamestringrequiredgiven_namestringrequiredfamily_namestringrequiredpreferred_namestring | nullrequiredwork_emailstringrequiredtitlestring | nullrequiredstatus"invited" | "pre_hire" | "active" | "terminated" | "none"requiredinvited: waiting for their details (names, title, start date), not employed yet; pre_hire: starts later; active; terminated: has left; none: no job.
start_datestring | nullrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
invitedbooleanrequiredhas_loginbooleanrequiredphoto_urlstring | nullrequiredpronounsstring | nullrequiredwork_phonestring | nullrequiredpersonal_emailstring | nullrequiredpersonal_phonestring | nullrequiredaddressobject | nullrequired5 fields
line1stringrequiredline2stringcitystringrequiredpostal_codestringcountrystringrequired
birthdaystring | nullrequiredsex"female" | "male" | "another" | "undisclosed"requiredFor equal-pay reporting only (private: the person, owners, admins and HR in the app). female and male are compared; another and undisclosed are counted, not compared.
emergency_contactsobject[] | nullrequired3 fields
namestringrequiredrelationshipstringrequiredphonestringrequired
tax_idstring | nullrequiredsocial_security_numberstring | nullrequiredibanstring | 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
jobobject | nullrequired23 fields
idstringrequiredvalid_fromstringrequiredvalid_tostring | nullrequiredtitlestringrequiredThe job title as the catalog names it now (reports and grouping use this).
title_idstring | nullrequiredThe catalog title (
org_titles_list); null while not in the catalog yet.display_titlestring | nullrequiredA different title shown on the profile, chart and directory; null: the catalog title.
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumberrequiredreasonstringrequiredend_reasonstring | nullrequiredleaving_typestring (enum)requiredWhy the employment ended (structured); null: not recorded or still employed.
One of:
resignation,retirement,dismissal,redundancy,end_of_contract,mutual_agreement,death,other.toldboolean | nullrequiredWith a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until
org_people_mark_toldor the day passes. null on other rows.contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequiredcustomobject[]requiredJob custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.
7 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
regrettedboolean | nullPrivate (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.
historyobject[] | nullrequired23 fields
idstringrequiredvalid_fromstringrequiredvalid_tostring | nullrequiredtitlestringrequiredThe job title as the catalog names it now (reports and grouping use this).
title_idstring | nullrequiredThe catalog title (
org_titles_list); null while not in the catalog yet.display_titlestring | nullrequiredA different title shown on the profile, chart and directory; null: the catalog title.
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumberrequiredreasonstringrequiredend_reasonstring | nullrequiredleaving_typestring (enum)requiredWhy the employment ended (structured); null: not recorded or still employed.
One of:
resignation,retirement,dismissal,redundancy,end_of_contract,mutual_agreement,death,other.toldboolean | nullrequiredWith a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until
org_people_mark_toldor the day passes. null on other rows.contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequiredcustomobject[]requiredJob custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.
7 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
regrettedboolean | nullPrivate (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.
reportsobject[]required4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
visible_tiers"public" | "private" | "job" | "pay"[]requiredplannedobject | nullrequiredWhile invited (status invited): the job details known so far (job tier; null otherwise or when not visible).
14 fields
titlestring | nullrequiredtitle_idstring | nullrequiredstart_datestring | nullrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumber | nullrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequired
missing"given_name" | "family_name" | "title" | "start_date"[]requiredWhile invited: what is still needed to register them (given_name, family_name, title, start_date); [] otherwise.
dotted_managersobject[]requiredDotted-line managers today (spec structure-over-time D10): they see job details, never approve.
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
dotted_reportsobject[]requiredPeople this person has a dotted line to today.
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/people.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"person_id":"p1","as_of":"2026-10-04"}'const res = await fetch('https://api.bizisy.com/v1/org/people.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"person_id": "p1",
"as_of": "2026-10-04"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/people.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"person_id": "p1",
"as_of": "2026-10-04",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "p1",
"name": "Ana Ferreira",
"given_name": "Ana",
"family_name": "Ferreira",
"preferred_name": null,
"work_email": "ana@acme.test",
"title": "Engineer",
"status": "active",
"start_date": "2024-01-15",
"unit": {
"id": "u2",
"name": "Engineering"
},
"location": {
"id": "l1",
"name": "Head office"
},
"manager": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"invited": true,
"has_login": true,
"photo_url": null,
"pronouns": "she/her",
"work_phone": "+351 210 000 000",
"personal_email": null,
"personal_phone": null,
"address": null,
"birthday": null,
"sex": "female",
"emergency_contacts": null,
"tax_id": null,
"social_security_number": null,
"iban": null,
"custom": [
{
"key": "t_shirt_size",
"label": "T-shirt size",
"type": "select",
"tier": "public",
"value": "M"
},
{
"key": "remote",
"label": "Remote allowance",
"type": "boolean",
"tier": "job",
"value": null
}
],
"job": {
"id": "j1",
"valid_from": "2024-01-15",
"valid_to": null,
"title": "Engineer",
"title_id": "t1",
"display_title": null,
"unit": {
"id": "u2",
"name": "Engineering"
},
"manager": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"location": {
"id": "l1",
"name": "Head office"
},
"legal_entity": {
"id": "e1",
"name": "Acme Lda"
},
"employment_type": "full_time",
"fte": 1,
"reason": "hire",
"end_reason": null,
"leaving_type": null,
"told": null,
"contract_type": "fixed_term",
"contract_end_date": "2026-01-14",
"probation_end_date": "2024-07-14",
"weekly_hours": 40,
"notice_period_days": 30,
"custom": [
{
"key": "shift_pattern",
"label": "Shift pattern",
"type": "select",
"tier": "job",
"value": "Day"
}
]
},
"history": [
{
"id": "j1",
"valid_from": "2024-01-15",
"valid_to": null,
"title": "Engineer",
"title_id": "t1",
"display_title": null,
"unit": {
"id": "u2",
"name": "Engineering"
},
"manager": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"location": {
"id": "l1",
"name": "Head office"
},
"legal_entity": {
"id": "e1",
"name": "Acme Lda"
},
"employment_type": "full_time",
"fte": 1,
"reason": "hire",
"end_reason": null,
"leaving_type": null,
"told": null,
"contract_type": "fixed_term",
"contract_end_date": "2026-01-14",
"probation_end_date": "2024-07-14",
"weekly_hours": 40,
"notice_period_days": 30,
"custom": [
{
"key": "shift_pattern",
"label": "Shift pattern",
"type": "select",
"tier": "job",
"value": "Day"
}
]
}
],
"reports": [],
"visible_tiers": [
"public",
"job"
],
"planned": null,
"missing": [],
"dotted_managers": [
{
"id": "p7",
"name": "João Pereira",
"title": "Sales Lead",
"photo_url": null
}
],
"dotted_reports": []
}
}Update a person's profile#
POST/v1/org/people.update_profileWrite
Changes profile fields of a person (names, work email, phones, personal email, address, birthday, pronouns, emergency contacts, sex (female, male, another or undisclosed: for equal-pay reporting only, private, never written over MCP or an API key), tax_id, social_security_number, iban: payroll details change only in the app, never over MCP or an API key, and the person and every owner, admin and HR member are emailed when they change) and custom field values (custom: { <key>: value or null }, keys from org_fields_list). Send only the fields to change; null clears a field. Only owners and admins can change the work email of an owner's or admin's login. Job changes go through org_people_change_job.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Payroll details (tax_id, social_security_number, iban) and sex are refused.
- MCP tool
org_people_update_profileon 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
given_namestring1–100 characters.
family_namestring1–100 characters.
work_emailanypreferred_namestring | null1–100 characters.
pronounsstring | nullUp to 40 characters.
work_phonestring | nullPattern
^\+?[0-9 ().-]{3,40}$.personal_emailany | nullpersonal_phonestring | nullPattern
^\+?[0-9 ().-]{3,40}$.addressobject | null5 fields
line1stringrequired1–200 characters.
line2stringUp to 200 characters.
citystringrequired1–100 characters.
postal_codestringUp to 20 characters.
countryanyrequired
birthdaystring | nullsex"female" | "male" | "another" | "undisclosed"Sex for equal-pay reporting (EU Pay Transparency Directive): female, male, another or undisclosed. Private; used in pay gap totals only.
emergency_contactsobject[]Up to 5 items.
3 fields
namestringrequired1–100 characters.
relationshipstringrequired1–60 characters.
phonestringrequiredPattern
^\+?[0-9 ().-]{3,40}$.
tax_idstring | nullPattern
^[A-Za-z0-9 ./-]{1,40}$.social_security_numberstring | nullPattern
^[A-Za-z0-9 ./-]{1,40}$.ibanany | nullcustomobjectCustom field values by key (
org_fields_list); null (or [] for a table) clears one. Person fields take a person id; table fields take rows [{ <column key>: value }].person_idstringrequired
Returns
35 fields
idstringrequirednamestringrequiredgiven_namestringrequiredfamily_namestringrequiredpreferred_namestring | nullrequiredwork_emailstringrequiredtitlestring | nullrequiredstatus"invited" | "pre_hire" | "active" | "terminated" | "none"requiredinvited: waiting for their details (names, title, start date), not employed yet; pre_hire: starts later; active; terminated: has left; none: no job.
start_datestring | nullrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
invitedbooleanrequiredhas_loginbooleanrequiredphoto_urlstring | nullrequiredpronounsstring | nullrequiredwork_phonestring | nullrequiredpersonal_emailstring | nullrequiredpersonal_phonestring | nullrequiredaddressobject | nullrequired5 fields
line1stringrequiredline2stringcitystringrequiredpostal_codestringcountrystringrequired
birthdaystring | nullrequiredsex"female" | "male" | "another" | "undisclosed"requiredFor equal-pay reporting only (private: the person, owners, admins and HR in the app). female and male are compared; another and undisclosed are counted, not compared.
emergency_contactsobject[] | nullrequired3 fields
namestringrequiredrelationshipstringrequiredphonestringrequired
tax_idstring | nullrequiredsocial_security_numberstring | nullrequiredibanstring | 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
jobobject | nullrequired23 fields
idstringrequiredvalid_fromstringrequiredvalid_tostring | nullrequiredtitlestringrequiredThe job title as the catalog names it now (reports and grouping use this).
title_idstring | nullrequiredThe catalog title (
org_titles_list); null while not in the catalog yet.display_titlestring | nullrequiredA different title shown on the profile, chart and directory; null: the catalog title.
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumberrequiredreasonstringrequiredend_reasonstring | nullrequiredleaving_typestring (enum)requiredWhy the employment ended (structured); null: not recorded or still employed.
One of:
resignation,retirement,dismissal,redundancy,end_of_contract,mutual_agreement,death,other.toldboolean | nullrequiredWith a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until
org_people_mark_toldor the day passes. null on other rows.contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequiredcustomobject[]requiredJob custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.
7 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
regrettedboolean | nullPrivate (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.
historyobject[] | nullrequired23 fields
idstringrequiredvalid_fromstringrequiredvalid_tostring | nullrequiredtitlestringrequiredThe job title as the catalog names it now (reports and grouping use this).
title_idstring | nullrequiredThe catalog title (
org_titles_list); null while not in the catalog yet.display_titlestring | nullrequiredA different title shown on the profile, chart and directory; null: the catalog title.
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumberrequiredreasonstringrequiredend_reasonstring | nullrequiredleaving_typestring (enum)requiredWhy the employment ended (structured); null: not recorded or still employed.
One of:
resignation,retirement,dismissal,redundancy,end_of_contract,mutual_agreement,death,other.toldboolean | nullrequiredWith a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until
org_people_mark_toldor the day passes. null on other rows.contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequiredcustomobject[]requiredJob custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.
7 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
regrettedboolean | nullPrivate (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.
reportsobject[]required4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
visible_tiers"public" | "private" | "job" | "pay"[]requiredplannedobject | nullrequiredWhile invited (status invited): the job details known so far (job tier; null otherwise or when not visible).
14 fields
titlestring | nullrequiredtitle_idstring | nullrequiredstart_datestring | nullrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumber | nullrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequired
missing"given_name" | "family_name" | "title" | "start_date"[]requiredWhile invited: what is still needed to register them (given_name, family_name, title, start_date); [] otherwise.
dotted_managersobject[]requiredDotted-line managers today (spec structure-over-time D10): they see job details, never approve.
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
dotted_reportsobject[]requiredPeople this person has a dotted line to today.
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/people.update_profile \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"person_id": "p1",
"given_name": "Ana Maria",
"work_email": "ana.maria@acme.test",
"address": null,
"emergency_contacts": [],
"sex": "female"
}'const res = await fetch('https://api.bizisy.com/v1/org/people.update_profile', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p1",
"given_name": "Ana Maria",
"work_email": "ana.maria@acme.test",
"address": null,
"emergency_contacts": [],
"sex": "female"
}),
});
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/people.update_profile",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p1",
"given_name": "Ana Maria",
"work_email": "ana.maria@acme.test",
"address": None,
"emergency_contacts": [],
"sex": "female",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "p1",
"name": "Ana Maria Ferreira",
"given_name": "Ana Maria",
"family_name": "Ferreira",
"preferred_name": null,
"work_email": "ana.maria@acme.test",
"title": "Engineer",
"status": "active",
"start_date": "2024-01-15",
"unit": {
"id": "u2",
"name": "Engineering"
},
"location": {
"id": "l1",
"name": "Head office"
},
"manager": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"invited": true,
"has_login": true,
"photo_url": null,
"pronouns": "she/her",
"work_phone": "+351 210 000 000",
"personal_email": null,
"personal_phone": null,
"address": null,
"birthday": null,
"sex": "female",
"emergency_contacts": null,
"tax_id": null,
"social_security_number": null,
"iban": null,
"custom": [
{
"key": "t_shirt_size",
"label": "T-shirt size",
"type": "select",
"tier": "public",
"value": "M"
},
{
"key": "remote",
"label": "Remote allowance",
"type": "boolean",
"tier": "job",
"value": null
}
],
"job": {
"id": "j1",
"valid_from": "2024-01-15",
"valid_to": null,
"title": "Engineer",
"title_id": "t1",
"display_title": null,
"unit": {
"id": "u2",
"name": "Engineering"
},
"manager": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"location": {
"id": "l1",
"name": "Head office"
},
"legal_entity": {
"id": "e1",
"name": "Acme Lda"
},
"employment_type": "full_time",
"fte": 1,
"reason": "hire",
"end_reason": null,
"leaving_type": null,
"told": null,
"contract_type": "fixed_term",
"contract_end_date": "2026-01-14",
"probation_end_date": "2024-07-14",
"weekly_hours": 40,
"notice_period_days": 30,
"custom": [
{
"key": "shift_pattern",
"label": "Shift pattern",
"type": "select",
"tier": "job",
"value": "Day"
}
]
},
"history": [
{
"id": "j1",
"valid_from": "2024-01-15",
"valid_to": null,
"title": "Engineer",
"title_id": "t1",
"display_title": null,
"unit": {
"id": "u2",
"name": "Engineering"
},
"manager": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"location": {
"id": "l1",
"name": "Head office"
},
"legal_entity": {
"id": "e1",
"name": "Acme Lda"
},
"employment_type": "full_time",
"fte": 1,
"reason": "hire",
"end_reason": null,
"leaving_type": null,
"told": null,
"contract_type": "fixed_term",
"contract_end_date": "2026-01-14",
"probation_end_date": "2024-07-14",
"weekly_hours": 40,
"notice_period_days": 30,
"custom": [
{
"key": "shift_pattern",
"label": "Shift pattern",
"type": "select",
"tier": "job",
"value": "Day"
}
]
}
],
"reports": [],
"visible_tiers": [
"public",
"job"
],
"planned": null,
"missing": [],
"dotted_managers": [
{
"id": "p7",
"name": "João Pereira",
"title": "Sales Lead",
"photo_url": null
}
],
"dotted_reports": []
}
}Upload a person's photo#
POST/v1/org/people.photo.uploadWrite
Sets the profile photo of a person (owners, admins and HR). The image (image_base64: the file as base64) must be a JPEG, PNG or WebP of at most 2 MB and 24 megapixels (over MCP the request is limited to 2 MiB, so about 1.5 MB; send larger files through the REST API); the server checks the bytes, centre-crops it to a square, re-encodes it as a 512×512 WebP and drops all metadata (EXIF, location). A new upload replaces the old photo. The photo is visible to everyone in the organization who can see the person (public tier, also over the API and MCP as photo_url); never outside it. Returns the new photo_url (a path on the company address, fetched with the same credentials). Errors: not_found for unknown or erased people, validation_failed for an image that is not JPEG/PNG/WebP, too large or damaged, rate_limited when the server is busy with other images (retry in a few seconds). Use dry_run to check the image without saving it.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_people_photo_uploadon 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
- Body limit
- 3 MiB (other actions: 2 MiB)
Input
person_idstringrequiredimage_base64stringrequiredThe image file as base64 (a data: URL is accepted): JPEG, PNG or WebP, at most 2 MB. Square images work best; the server centre-crops.
1–2900000 characters.
Returns
person_idstringrequiredphoto_urlstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict payload_too_large rate_limited internal
curl https://api.bizisy.com/v1/org/people.photo.upload \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"person_id":"p1","image_base64":"UklGRg=="}'const res = await fetch('https://api.bizisy.com/v1/org/people.photo.upload', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p1",
"image_base64": "UklGRg=="
}),
});
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/people.photo.upload",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p1",
"image_base64": "UklGRg==",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person_id": "p1",
"photo_url": "https://acme.bizisy.com/api/photos/people/p1?v=01k0000000000000000000000d"
}
}Remove a person's photo#
POST/v1/org/people.photo.removeDestructive
Deletes the profile photo of a person (owners, admins and HR); their initials show instead. Succeeds when there is no photo. Errors: not_found for unknown or erased people.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_people_photo_removeon 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
person_idstringrequired
Returns
person_idstringrequiredphoto_urlstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/people.photo.remove \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"person_id":"p1"}'const res = await fetch('https://api.bizisy.com/v1/org/people.photo.remove', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"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, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/people.photo.remove",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person_id": "p1",
"photo_url": null
}
}Move people to a new manager, team or location#
POST/v1/org/people.moveWrite
Moves one or more people (at most 50 per call) from effective_date (YYYY-MM-DD): a new manager_id (or null for none), unit_id (team) and/or location_id. Moving into a team without manager_id makes that team's lead each person's manager (as org_people_change_job does). reason defaults to transfer when the team changes, else change. Returns preview (summary, every field that changes per person with before and after, who must approve, and who is blocked and why) and people[] with each one's status: applied, requested (sent for approval), unchanged (already so) or blocked. Use dry_run first and show the preview. If anyone is blocked (not employed that day, a reporting cycle, a change already waiting for approval…), the real call is refused (conflict, details.blocked) unless skip_blocked is true, which moves the others. When Settings → Approval rules requires approval for job changes, each person gets their own request with their own approver. Owners, admins and HR; a manager (in My workspace) can propose it for people in their team, and HR always decides.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
org_people_moveon HR Assistant, My Workplace- 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
person_idsstring[]required1–50 items.
effective_datestringrequiredmanager_idstring | nullunit_idstringlocation_idstringreason"change" | "transfer"skip_blockedboolean
Returns
previewobjectrequired4 fields
summarystringrequiredchangesobject[]required6 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
fieldstringrequiredlabelstringrequiredfromstring | nullrequiredtostring | nullrequiredeffectivestringrequired
approvals_neededobject[]required3 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
waiting_for"manager" | "hr"requiredapproversstring[]required
blockedobject[]required2 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
reasonstringrequired
peopleobject[]required3 fields
idstringrequirednamestringrequiredstatus"applied" | "requested" | "unchanged" | "blocked"required
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/people.move \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"person_ids": [
"p1"
],
"effective_date": "2026-11-01",
"manager_id": null,
"reason": "change",
"skip_blocked": true
}'const res = await fetch('https://api.bizisy.com/v1/org/people.move', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_ids": [
"p1"
],
"effective_date": "2026-11-01",
"manager_id": null,
"reason": "change",
"skip_blocked": true
}),
});
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/people.move",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_ids": [
"p1",
],
"effective_date": "2026-11-01",
"manager_id": None,
"reason": "change",
"skip_blocked": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"people": [
{
"id": "p1",
"name": "Ana Ferreira",
"status": "applied"
},
{
"id": "p2",
"name": "Bea Silva",
"status": "blocked"
}
],
"preview": {
"summary": "1 person moves to Product from 1 Nov 2026.",
"changes": [],
"approvals_needed": [],
"blocked": [
{
"person": {
"id": "p2",
"name": "Bea Silva"
},
"reason": "Bea Silva already has a change waiting for approval."
}
]
}
}
}Mark someone as leaving#
POST/v1/org/people.mark_leavingDestructive
Ends a person's employment after last_day (inclusive, YYYY-MM-DD, may be in the future) and takes care of what follows, in one change: each direct report gets a new manager from the day after (reassign [{person_id, manager_id or null}]; anyone not listed goes to the leaver's own manager, or none), replacement_position true opens a position for their role (their title, team and location, to start the day after), and access decides their Bizisy login: after_last_day (default: it stops working at midnight after the last day, company time), now (owners and admins only) or keep. The offboarding checklists that start by themselves start. reason is free text (e.g. resigned); leaving_type is why, structured (resignation, retirement, dismissal, redundancy, end_of_contract, mutual_agreement, death, other), for the turnover split in Reports. Returns preview (every change with before and after, who must approve) and warnings. Use dry_run first and show the preview. When Settings → Approval rules requires approval for terminations, one request holds all of it and it applies when approved. Use it instead of org_people_terminate. Owners, admins and HR; a manager (in My workspace) can propose it for someone in their team (a resignation: last day and reason; no replacement position, no ending the login now), and HR always decides.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
org_people_mark_leavingon HR Assistant, My Workplace- 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
person_idstringrequiredlast_daystringrequiredreasonstringUp to 200 characters.
leaving_typestring (enum)Why they leave: resignation, retirement (voluntary); dismissal, redundancy, end_of_contract (involuntary); mutual_agreement, death, other. Splits turnover in Reports. null or absent: not recorded (a termination it replaces keeps its type).
One of:
resignation,retirement,dismissal,redundancy,end_of_contract,mutual_agreement,death,other.reassignobject[]Up to 500 items.
2 fields
person_idstringrequiredmanager_idstring | nullrequired
replacement_positionbooleanaccess"after_last_day" | "now" | "keep"person_toldbooleanWhether the person has already been told about this last day. false: it stays with HR and their manager (Home asks to tell them) until someone marks them told with
org_people_mark_toldor the day passes; until then they see no last day, reason, offboarding task or time off change. Absent: true for resignation, retirement, mutual_agreement and death, false otherwise (a moved termination keeps its own).regrettedboolean | nullHR only, for a voluntary leaving type (resignation, retirement): would you have wanted to keep this person? true, false, or null (not set). Used only in attrition reports (regretted attrition), never shown to the person or their team. Refused with another leaving type.
Returns
personobjectrequired35 fields
idstringrequirednamestringrequiredgiven_namestringrequiredfamily_namestringrequiredpreferred_namestring | nullrequiredwork_emailstringrequiredtitlestring | nullrequiredstatus"invited" | "pre_hire" | "active" | "terminated" | "none"requiredinvited: waiting for their details (names, title, start date), not employed yet; pre_hire: starts later; active; terminated: has left; none: no job.
start_datestring | nullrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
invitedbooleanrequiredhas_loginbooleanrequiredphoto_urlstring | nullrequiredpronounsstring | nullrequiredwork_phonestring | nullrequiredpersonal_emailstring | nullrequiredpersonal_phonestring | nullrequiredaddressobject | nullrequired5 fields
line1stringrequiredline2stringcitystringrequiredpostal_codestringcountrystringrequired
birthdaystring | nullrequiredsex"female" | "male" | "another" | "undisclosed"requiredFor equal-pay reporting only (private: the person, owners, admins and HR in the app). female and male are compared; another and undisclosed are counted, not compared.
emergency_contactsobject[] | nullrequired3 fields
namestringrequiredrelationshipstringrequiredphonestringrequired
tax_idstring | nullrequiredsocial_security_numberstring | nullrequiredibanstring | 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
jobobject | nullrequired23 fields
idstringrequiredvalid_fromstringrequiredvalid_tostring | nullrequiredtitlestringrequiredThe job title as the catalog names it now (reports and grouping use this).
title_idstring | nullrequiredThe catalog title (
org_titles_list); null while not in the catalog yet.display_titlestring | nullrequiredA different title shown on the profile, chart and directory; null: the catalog title.
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumberrequiredreasonstringrequiredend_reasonstring | nullrequiredleaving_typestring (enum)requiredWhy the employment ended (structured); null: not recorded or still employed.
One of:
resignation,retirement,dismissal,redundancy,end_of_contract,mutual_agreement,death,other.toldboolean | nullrequiredWith a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until
org_people_mark_toldor the day passes. null on other rows.contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequiredcustomobject[]requiredJob custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.
7 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
regrettedboolean | nullPrivate (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.
historyobject[] | nullrequired23 fields
idstringrequiredvalid_fromstringrequiredvalid_tostring | nullrequiredtitlestringrequiredThe job title as the catalog names it now (reports and grouping use this).
title_idstring | nullrequiredThe catalog title (
org_titles_list); null while not in the catalog yet.display_titlestring | nullrequiredA different title shown on the profile, chart and directory; null: the catalog title.
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumberrequiredreasonstringrequiredend_reasonstring | nullrequiredleaving_typestring (enum)requiredWhy the employment ended (structured); null: not recorded or still employed.
One of:
resignation,retirement,dismissal,redundancy,end_of_contract,mutual_agreement,death,other.toldboolean | nullrequiredWith a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until
org_people_mark_toldor the day passes. null on other rows.contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequiredcustomobject[]requiredJob custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.
7 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
regrettedboolean | nullPrivate (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.
reportsobject[]required4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
visible_tiers"public" | "private" | "job" | "pay"[]requiredplannedobject | nullrequiredWhile invited (status invited): the job details known so far (job tier; null otherwise or when not visible).
14 fields
titlestring | nullrequiredtitle_idstring | nullrequiredstart_datestring | nullrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumber | nullrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequired
missing"given_name" | "family_name" | "title" | "start_date"[]requiredWhile invited: what is still needed to register them (given_name, family_name, title, start_date); [] otherwise.
dotted_managersobject[]requiredDotted-line managers today (spec structure-over-time D10): they see job details, never approve.
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
dotted_reportsobject[]requiredPeople this person has a dotted line to today.
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
approvalobject | nullrequired11 fields
idstringrequiredstatus"pending" | "approved"requiredwaiting_for"manager" | "hr"requiredapproversstring[]requiredautomaticbooleanrequirednote"proposed_by_approver" | "no_other_approver"requiredfallbackbooleanrequiredteam_leadobject | nullrequired3 fields
unit_idstringrequiredunit_namestringrequiredreason"no_manager" | "manager_left"required
team_lead_blockedobject | nullrequired3 fields
unit_idstringrequiredunit_namestringrequiredwhat"lead" | "removed" | "moved" | "archived"required
untrusted"no_login" | "invited_by_proposer"requiredthen"manager" | "hr"required
previewobjectrequired4 fields
summarystringrequiredchangesobject[]required6 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
fieldstringrequiredlabelstringrequiredfromstring | nullrequiredtostring | nullrequiredeffectivestringrequired
approvals_neededobject[]required3 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
waiting_for"manager" | "hr"requiredapproversstring[]required
blockedobject[]required2 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
reasonstringrequired
warningsstring[]required
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/people.mark_leaving \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"person_id": "p1",
"last_day": "2026-11-21",
"reason": "resigned",
"reassign": [
{
"person_id": "p2",
"manager_id": null
}
],
"replacement_position": true,
"access": "now"
}'const res = await fetch('https://api.bizisy.com/v1/org/people.mark_leaving', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p1",
"last_day": "2026-11-21",
"reason": "resigned",
"reassign": [
{
"person_id": "p2",
"manager_id": null
}
],
"replacement_position": true,
"access": "now"
}),
});
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/people.mark_leaving",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p1",
"last_day": "2026-11-21",
"reason": "resigned",
"reassign": [
{
"person_id": "p2",
"manager_id": None,
},
],
"replacement_position": True,
"access": "now",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person": {
"id": "p1",
"name": "Ana Ferreira",
"given_name": "Ana",
"family_name": "Ferreira",
"preferred_name": null,
"work_email": "ana@acme.test",
"title": "Engineer",
"status": "active",
"start_date": "2024-01-15",
"unit": {
"id": "u2",
"name": "Engineering"
},
"location": {
"id": "l1",
"name": "Head office"
},
"manager": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"invited": true,
"has_login": true,
"photo_url": null,
"pronouns": "she/her",
"work_phone": "+351 210 000 000",
"personal_email": null,
"personal_phone": null,
"address": null,
"birthday": null,
"sex": "female",
"emergency_contacts": null,
"tax_id": null,
"social_security_number": null,
"iban": null,
"custom": [
{
"key": "t_shirt_size",
"label": "T-shirt size",
"type": "select",
"tier": "public",
"value": "M"
},
{
"key": "remote",
"label": "Remote allowance",
"type": "boolean",
"tier": "job",
"value": null
}
],
"job": {
"id": "j1",
"valid_from": "2024-01-15",
"valid_to": null,
"title": "Engineer",
"title_id": "t1",
"display_title": null,
"unit": {
"id": "u2",
"name": "Engineering"
},
"manager": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"location": {
"id": "l1",
"name": "Head office"
},
"legal_entity": {
"id": "e1",
"name": "Acme Lda"
},
"employment_type": "full_time",
"fte": 1,
"reason": "hire",
"end_reason": null,
"leaving_type": null,
"told": null,
"contract_type": "fixed_term",
"contract_end_date": "2026-01-14",
"probation_end_date": "2024-07-14",
"weekly_hours": 40,
"notice_period_days": 30,
"custom": [
{
"key": "shift_pattern",
"label": "Shift pattern",
"type": "select",
"tier": "job",
"value": "Day"
}
]
},
"history": [
{
"id": "j1",
"valid_from": "2024-01-15",
"valid_to": null,
"title": "Engineer",
"title_id": "t1",
"display_title": null,
"unit": {
"id": "u2",
"name": "Engineering"
},
"manager": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"location": {
"id": "l1",
"name": "Head office"
},
"legal_entity": {
"id": "e1",
"name": "Acme Lda"
},
"employment_type": "full_time",
"fte": 1,
"reason": "hire",
"end_reason": null,
"leaving_type": null,
"told": null,
"contract_type": "fixed_term",
"contract_end_date": "2026-01-14",
"probation_end_date": "2024-07-14",
"weekly_hours": 40,
"notice_period_days": 30,
"custom": [
{
"key": "shift_pattern",
"label": "Shift pattern",
"type": "select",
"tier": "job",
"value": "Day"
}
]
}
],
"reports": [],
"visible_tiers": [
"public",
"job"
],
"planned": null,
"missing": [],
"dotted_managers": [
{
"id": "p7",
"name": "João Pereira",
"title": "Sales Lead",
"photo_url": null
}
],
"dotted_reports": []
},
"approval": null,
"warnings": [],
"preview": {
"summary": "Ana Ferreira leaves after 21 Nov 2026; 1 person gets a new manager from 22 Nov 2026.",
"changes": [
{
"person": {
"id": "p1",
"name": "Ana Ferreira"
},
"field": "last_day",
"label": "Last working day",
"from": null,
"to": "2026-11-21",
"effective": "2026-11-21"
}
],
"approvals_needed": [],
"blocked": []
}
}
}Promote or give a raise#
POST/v1/org/people.promoteWrite
A promotion or raise in one change, from effective_date (YYYY-MM-DD): a new title (optional; reason defaults to promotion) and/or new pay, either {amount, currency, period} or {percent} of the pay in force that day (−50 to +200). note goes with the pay row. Pay follows the rules of org_pay_add (never your own; an HR member's pay only by an owner or admin; an owner's only by another owner). When approval is needed for job changes or pay, one request holds both and HR decides it last (a manager step sees only the job part). Over an API key or MCP, pay is accepted only as a request HR decides in Bizisy, even when approval is off, and the result never shows amounts (pay is null). Returns preview (what changes; pay only for those who may see it) and approval. Use dry_run first. Owners, admins and HR; a manager (in My workspace) can propose a new title for someone in their team (never pay), and HR always decides.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
org_people_promoteon HR Assistant, My Workplace- 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
person_idstringrequiredeffective_datestringrequiredtitlestringThe 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.display_titlestring | nullA different title to show on the profile, chart and directory (reports use the catalog title); null removes it. Cleared when the catalog title changes, unless sent.
1–120 characters.
create_titlebooleanfalse: refuse a title that is not in the catalog yet (not_found with details.candidates) instead of adding it.
reason"promotion" | "change"payobject4 fields (one of several shapes)
Option 1
amountnumberrequiredFrom 0 to 100000000.
currencyanyrequiredperiod"year" | "month" | "hour"required
Option 2
percentnumberrequiredFrom -50 to 200.
notestringUp to 200 characters.
Returns
personobjectrequired35 fields
idstringrequirednamestringrequiredgiven_namestringrequiredfamily_namestringrequiredpreferred_namestring | nullrequiredwork_emailstringrequiredtitlestring | nullrequiredstatus"invited" | "pre_hire" | "active" | "terminated" | "none"requiredinvited: waiting for their details (names, title, start date), not employed yet; pre_hire: starts later; active; terminated: has left; none: no job.
start_datestring | nullrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
invitedbooleanrequiredhas_loginbooleanrequiredphoto_urlstring | nullrequiredpronounsstring | nullrequiredwork_phonestring | nullrequiredpersonal_emailstring | nullrequiredpersonal_phonestring | nullrequiredaddressobject | nullrequired5 fields
line1stringrequiredline2stringcitystringrequiredpostal_codestringcountrystringrequired
birthdaystring | nullrequiredsex"female" | "male" | "another" | "undisclosed"requiredFor equal-pay reporting only (private: the person, owners, admins and HR in the app). female and male are compared; another and undisclosed are counted, not compared.
emergency_contactsobject[] | nullrequired3 fields
namestringrequiredrelationshipstringrequiredphonestringrequired
tax_idstring | nullrequiredsocial_security_numberstring | nullrequiredibanstring | 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
jobobject | nullrequired23 fields
idstringrequiredvalid_fromstringrequiredvalid_tostring | nullrequiredtitlestringrequiredThe job title as the catalog names it now (reports and grouping use this).
title_idstring | nullrequiredThe catalog title (
org_titles_list); null while not in the catalog yet.display_titlestring | nullrequiredA different title shown on the profile, chart and directory; null: the catalog title.
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumberrequiredreasonstringrequiredend_reasonstring | nullrequiredleaving_typestring (enum)requiredWhy the employment ended (structured); null: not recorded or still employed.
One of:
resignation,retirement,dismissal,redundancy,end_of_contract,mutual_agreement,death,other.toldboolean | nullrequiredWith a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until
org_people_mark_toldor the day passes. null on other rows.contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequiredcustomobject[]requiredJob custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.
7 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
regrettedboolean | nullPrivate (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.
historyobject[] | nullrequired23 fields
idstringrequiredvalid_fromstringrequiredvalid_tostring | nullrequiredtitlestringrequiredThe job title as the catalog names it now (reports and grouping use this).
title_idstring | nullrequiredThe catalog title (
org_titles_list); null while not in the catalog yet.display_titlestring | nullrequiredA different title shown on the profile, chart and directory; null: the catalog title.
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumberrequiredreasonstringrequiredend_reasonstring | nullrequiredleaving_typestring (enum)requiredWhy the employment ended (structured); null: not recorded or still employed.
One of:
resignation,retirement,dismissal,redundancy,end_of_contract,mutual_agreement,death,other.toldboolean | nullrequiredWith a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until
org_people_mark_toldor the day passes. null on other rows.contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequiredcustomobject[]requiredJob custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.
7 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
regrettedboolean | nullPrivate (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.
reportsobject[]required4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
visible_tiers"public" | "private" | "job" | "pay"[]requiredplannedobject | nullrequiredWhile invited (status invited): the job details known so far (job tier; null otherwise or when not visible).
14 fields
titlestring | nullrequiredtitle_idstring | nullrequiredstart_datestring | nullrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumber | nullrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequired
missing"given_name" | "family_name" | "title" | "start_date"[]requiredWhile invited: what is still needed to register them (given_name, family_name, title, start_date); [] otherwise.
dotted_managersobject[]requiredDotted-line managers today (spec structure-over-time D10): they see job details, never approve.
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
dotted_reportsobject[]requiredPeople this person has a dotted line to today.
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
approvalobject | nullrequired11 fields
idstringrequiredstatus"pending" | "approved"requiredwaiting_for"manager" | "hr"requiredapproversstring[]requiredautomaticbooleanrequirednote"proposed_by_approver" | "no_other_approver"requiredfallbackbooleanrequiredteam_leadobject | nullrequired3 fields
unit_idstringrequiredunit_namestringrequiredreason"no_manager" | "manager_left"required
team_lead_blockedobject | nullrequired3 fields
unit_idstringrequiredunit_namestringrequiredwhat"lead" | "removed" | "moved" | "archived"required
untrusted"no_login" | "invited_by_proposer"requiredthen"manager" | "hr"required
previewobjectrequired4 fields
summarystringrequiredchangesobject[]required6 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
fieldstringrequiredlabelstringrequiredfromstring | nullrequiredtostring | nullrequiredeffectivestringrequired
approvals_neededobject[]required3 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
waiting_for"manager" | "hr"requiredapproversstring[]required
blockedobject[]required2 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
reasonstringrequired
payobject | nullrequired2 fields
currentobject | nullrequired8 fields
idstringrequiredvalid_fromstringrequiredvalid_tostring | nullrequiredamountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requirednotestring | nullrequiredcreated_atstringrequired
historyobject[]required8 fields
idstringrequiredvalid_fromstringrequiredvalid_tostring | nullrequiredamountnumberrequiredcurrencystringrequiredperiod"year" | "month" | "hour"requirednotestring | nullrequiredcreated_atstringrequired
title_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/people.promote \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"person_id": "p1",
"effective_date": "2026-11-01",
"title": "Lead",
"reason": "promotion",
"pay": {
"amount": 4000,
"currency": "EUR",
"period": "month"
}
}'const res = await fetch('https://api.bizisy.com/v1/org/people.promote', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p1",
"effective_date": "2026-11-01",
"title": "Lead",
"reason": "promotion",
"pay": {
"amount": 4000,
"currency": "EUR",
"period": "month"
}
}),
});
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/people.promote",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p1",
"effective_date": "2026-11-01",
"title": "Lead",
"reason": "promotion",
"pay": {
"amount": 4000,
"currency": "EUR",
"period": "month",
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person": {
"id": "p1",
"name": "Ana Ferreira",
"given_name": "Ana",
"family_name": "Ferreira",
"preferred_name": null,
"work_email": "ana@acme.test",
"title": "Engineer",
"status": "active",
"start_date": "2024-01-15",
"unit": {
"id": "u2",
"name": "Engineering"
},
"location": {
"id": "l1",
"name": "Head office"
},
"manager": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"invited": true,
"has_login": true,
"photo_url": null,
"pronouns": "she/her",
"work_phone": "+351 210 000 000",
"personal_email": null,
"personal_phone": null,
"address": null,
"birthday": null,
"sex": "female",
"emergency_contacts": null,
"tax_id": null,
"social_security_number": null,
"iban": null,
"custom": [
{
"key": "t_shirt_size",
"label": "T-shirt size",
"type": "select",
"tier": "public",
"value": "M"
},
{
"key": "remote",
"label": "Remote allowance",
"type": "boolean",
"tier": "job",
"value": null
}
],
"job": {
"id": "j1",
"valid_from": "2024-01-15",
"valid_to": null,
"title": "Engineer",
"title_id": "t1",
"display_title": null,
"unit": {
"id": "u2",
"name": "Engineering"
},
"manager": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"location": {
"id": "l1",
"name": "Head office"
},
"legal_entity": {
"id": "e1",
"name": "Acme Lda"
},
"employment_type": "full_time",
"fte": 1,
"reason": "hire",
"end_reason": null,
"leaving_type": null,
"told": null,
"contract_type": "fixed_term",
"contract_end_date": "2026-01-14",
"probation_end_date": "2024-07-14",
"weekly_hours": 40,
"notice_period_days": 30,
"custom": [
{
"key": "shift_pattern",
"label": "Shift pattern",
"type": "select",
"tier": "job",
"value": "Day"
}
]
},
"history": [
{
"id": "j1",
"valid_from": "2024-01-15",
"valid_to": null,
"title": "Engineer",
"title_id": "t1",
"display_title": null,
"unit": {
"id": "u2",
"name": "Engineering"
},
"manager": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"location": {
"id": "l1",
"name": "Head office"
},
"legal_entity": {
"id": "e1",
"name": "Acme Lda"
},
"employment_type": "full_time",
"fte": 1,
"reason": "hire",
"end_reason": null,
"leaving_type": null,
"told": null,
"contract_type": "fixed_term",
"contract_end_date": "2026-01-14",
"probation_end_date": "2024-07-14",
"weekly_hours": 40,
"notice_period_days": 30,
"custom": [
{
"key": "shift_pattern",
"label": "Shift pattern",
"type": "select",
"tier": "job",
"value": "Day"
}
]
}
],
"reports": [],
"visible_tiers": [
"public",
"job"
],
"planned": null,
"missing": [],
"dotted_managers": [
{
"id": "p7",
"name": "João Pereira",
"title": "Sales Lead",
"photo_url": null
}
],
"dotted_reports": []
},
"approval": null,
"title_match": null,
"pay": {
"current": {
"id": "pay1",
"valid_from": "2024-01-15",
"valid_to": null,
"amount": 42000,
"currency": "EUR",
"period": "year",
"note": null,
"created_at": "2026-10-04T10:00:00.000Z"
},
"history": [
{
"id": "pay1",
"valid_from": "2024-01-15",
"valid_to": null,
"amount": 42000,
"currency": "EUR",
"period": "year",
"note": null,
"created_at": "2026-10-04T10:00:00.000Z"
}
]
},
"preview": {
"summary": "Ana Ferreira: new title Senior Engineer from 1 Nov 2026.",
"changes": [
{
"person": {
"id": "p1",
"name": "Ana Ferreira"
},
"field": "title",
"label": "Title",
"from": "Engineer",
"to": "Senior Engineer",
"effective": "2026-11-01"
}
],
"approvals_needed": [],
"blocked": []
}
}
}Decide on a probation#
POST/v1/org/people.probation_decideWrite
The outcome of someone's probation (trial period), as HR practice has it: passed (confirmed; Home, reminders and My team stop asking), extend (new_end_date: the probation end on their current contract moves; it follows the job-change approval rule), or end (last_day: they leave as with org_people_mark_leaving, reason "Did not pass probation"). note is kept with the decision. For people employed through a Portuguese legal entity, legal gives the Código do Trabalho rules (art. 112–114): the notice to end a trial period now (no notice up to 60 days served, 7 days after 60, 15 after 120) and the 240-day maximum; warnings say when a choice goes against them (Bizisy never changes it for you). Owners, admins and HR decide; a manager (in My workspace) proposes it for someone in their team and HR decides. Use dry_run first.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
org_people_probation_decideon HR Assistant, My Workplace- 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
person_idstringrequiredoutcome"passed" | "extend" | "end"requirednew_end_datestringlast_daystringnotestringUp to 500 characters.
person_toldbooleanWhether the person has already been told about this last day. false: it stays with HR and their manager (Home asks to tell them) until someone marks them told with
org_people_mark_toldor the day passes; until then they see no last day, reason, offboarding task or time off change. Absent: true for resignation, retirement, mutual_agreement and death, false otherwise (a moved termination keeps its own).
Returns
personobjectrequired35 fields
idstringrequirednamestringrequiredgiven_namestringrequiredfamily_namestringrequiredpreferred_namestring | nullrequiredwork_emailstringrequiredtitlestring | nullrequiredstatus"invited" | "pre_hire" | "active" | "terminated" | "none"requiredinvited: waiting for their details (names, title, start date), not employed yet; pre_hire: starts later; active; terminated: has left; none: no job.
start_datestring | nullrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
invitedbooleanrequiredhas_loginbooleanrequiredphoto_urlstring | nullrequiredpronounsstring | nullrequiredwork_phonestring | nullrequiredpersonal_emailstring | nullrequiredpersonal_phonestring | nullrequiredaddressobject | nullrequired5 fields
line1stringrequiredline2stringcitystringrequiredpostal_codestringcountrystringrequired
birthdaystring | nullrequiredsex"female" | "male" | "another" | "undisclosed"requiredFor equal-pay reporting only (private: the person, owners, admins and HR in the app). female and male are compared; another and undisclosed are counted, not compared.
emergency_contactsobject[] | nullrequired3 fields
namestringrequiredrelationshipstringrequiredphonestringrequired
tax_idstring | nullrequiredsocial_security_numberstring | nullrequiredibanstring | 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
jobobject | nullrequired23 fields
idstringrequiredvalid_fromstringrequiredvalid_tostring | nullrequiredtitlestringrequiredThe job title as the catalog names it now (reports and grouping use this).
title_idstring | nullrequiredThe catalog title (
org_titles_list); null while not in the catalog yet.display_titlestring | nullrequiredA different title shown on the profile, chart and directory; null: the catalog title.
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumberrequiredreasonstringrequiredend_reasonstring | nullrequiredleaving_typestring (enum)requiredWhy the employment ended (structured); null: not recorded or still employed.
One of:
resignation,retirement,dismissal,redundancy,end_of_contract,mutual_agreement,death,other.toldboolean | nullrequiredWith a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until
org_people_mark_toldor the day passes. null on other rows.contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequiredcustomobject[]requiredJob custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.
7 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
regrettedboolean | nullPrivate (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.
historyobject[] | nullrequired23 fields
idstringrequiredvalid_fromstringrequiredvalid_tostring | nullrequiredtitlestringrequiredThe job title as the catalog names it now (reports and grouping use this).
title_idstring | nullrequiredThe catalog title (
org_titles_list); null while not in the catalog yet.display_titlestring | nullrequiredA different title shown on the profile, chart and directory; null: the catalog title.
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumberrequiredreasonstringrequiredend_reasonstring | nullrequiredleaving_typestring (enum)requiredWhy the employment ended (structured); null: not recorded or still employed.
One of:
resignation,retirement,dismissal,redundancy,end_of_contract,mutual_agreement,death,other.toldboolean | nullrequiredWith a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until
org_people_mark_toldor the day passes. null on other rows.contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequiredcustomobject[]requiredJob custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.
7 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
regrettedboolean | nullPrivate (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.
reportsobject[]required4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
visible_tiers"public" | "private" | "job" | "pay"[]requiredplannedobject | nullrequiredWhile invited (status invited): the job details known so far (job tier; null otherwise or when not visible).
14 fields
titlestring | nullrequiredtitle_idstring | nullrequiredstart_datestring | nullrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumber | nullrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequired
missing"given_name" | "family_name" | "title" | "start_date"[]requiredWhile invited: what is still needed to register them (given_name, family_name, title, start_date); [] otherwise.
dotted_managersobject[]requiredDotted-line managers today (spec structure-over-time D10): they see job details, never approve.
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
dotted_reportsobject[]requiredPeople this person has a dotted line to today.
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
approvalobject | nullrequired11 fields
idstringrequiredstatus"pending" | "approved"requiredwaiting_for"manager" | "hr"requiredapproversstring[]requiredautomaticbooleanrequirednote"proposed_by_approver" | "no_other_approver"requiredfallbackbooleanrequiredteam_leadobject | nullrequired3 fields
unit_idstringrequiredunit_namestringrequiredreason"no_manager" | "manager_left"required
team_lead_blockedobject | nullrequired3 fields
unit_idstringrequiredunit_namestringrequiredwhat"lead" | "removed" | "moved" | "archived"required
untrusted"no_login" | "invited_by_proposer"requiredthen"manager" | "hr"required
previewobjectrequired4 fields
summarystringrequiredchangesobject[]required6 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
fieldstringrequiredlabelstringrequiredfromstring | nullrequiredtostring | nullrequiredeffectivestringrequired
approvals_neededobject[]required3 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
waiting_for"manager" | "hr"requiredapproversstring[]required
blockedobject[]required2 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
reasonstringrequired
warningsstring[]requiredThings to check before going ahead, such as Portuguese legal limits (warnings, never refusals).
legalobject | nullrequired4 fields
countrystringrequireddays_servedintegerrequiredprobation_notice_daysintegerrequiredprobation_max_endstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/people.probation_decide \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"person_id": "p1",
"outcome": "extend",
"new_end_date": "2026-12-31",
"note": "More time on the sales targets"
}'const res = await fetch('https://api.bizisy.com/v1/org/people.probation_decide', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p1",
"outcome": "extend",
"new_end_date": "2026-12-31",
"note": "More time on the sales targets"
}),
});
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/people.probation_decide",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p1",
"outcome": "extend",
"new_end_date": "2026-12-31",
"note": "More time on the sales targets",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person": {
"id": "p1",
"name": "Ana Ferreira",
"given_name": "Ana",
"family_name": "Ferreira",
"preferred_name": null,
"work_email": "ana@acme.test",
"title": "Engineer",
"status": "active",
"start_date": "2024-01-15",
"unit": {
"id": "u2",
"name": "Engineering"
},
"location": {
"id": "l1",
"name": "Head office"
},
"manager": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"invited": true,
"has_login": true,
"photo_url": null,
"pronouns": "she/her",
"work_phone": "+351 210 000 000",
"personal_email": null,
"personal_phone": null,
"address": null,
"birthday": null,
"sex": "female",
"emergency_contacts": null,
"tax_id": null,
"social_security_number": null,
"iban": null,
"custom": [
{
"key": "t_shirt_size",
"label": "T-shirt size",
"type": "select",
"tier": "public",
"value": "M"
},
{
"key": "remote",
"label": "Remote allowance",
"type": "boolean",
"tier": "job",
"value": null
}
],
"job": {
"id": "j1",
"valid_from": "2024-01-15",
"valid_to": null,
"title": "Engineer",
"title_id": "t1",
"display_title": null,
"unit": {
"id": "u2",
"name": "Engineering"
},
"manager": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"location": {
"id": "l1",
"name": "Head office"
},
"legal_entity": {
"id": "e1",
"name": "Acme Lda"
},
"employment_type": "full_time",
"fte": 1,
"reason": "hire",
"end_reason": null,
"leaving_type": null,
"told": null,
"contract_type": "fixed_term",
"contract_end_date": "2026-01-14",
"probation_end_date": "2024-07-14",
"weekly_hours": 40,
"notice_period_days": 30,
"custom": [
{
"key": "shift_pattern",
"label": "Shift pattern",
"type": "select",
"tier": "job",
"value": "Day"
}
]
},
"history": [
{
"id": "j1",
"valid_from": "2024-01-15",
"valid_to": null,
"title": "Engineer",
"title_id": "t1",
"display_title": null,
"unit": {
"id": "u2",
"name": "Engineering"
},
"manager": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"location": {
"id": "l1",
"name": "Head office"
},
"legal_entity": {
"id": "e1",
"name": "Acme Lda"
},
"employment_type": "full_time",
"fte": 1,
"reason": "hire",
"end_reason": null,
"leaving_type": null,
"told": null,
"contract_type": "fixed_term",
"contract_end_date": "2026-01-14",
"probation_end_date": "2024-07-14",
"weekly_hours": 40,
"notice_period_days": 30,
"custom": [
{
"key": "shift_pattern",
"label": "Shift pattern",
"type": "select",
"tier": "job",
"value": "Day"
}
]
}
],
"reports": [],
"visible_tiers": [
"public",
"job"
],
"planned": null,
"missing": [],
"dotted_managers": [
{
"id": "p7",
"name": "João Pereira",
"title": "Sales Lead",
"photo_url": null
}
],
"dotted_reports": []
},
"approval": null,
"warnings": [],
"legal": {
"country": "PT",
"days_served": 95,
"probation_notice_days": 7,
"probation_max_end": "2027-02-26"
},
"preview": {
"summary": "Ana Ferreira passes probation.",
"changes": [
{
"person": {
"id": "p1",
"name": "Ana Ferreira"
},
"field": "probation",
"label": "Probation",
"from": "Ends 20 Oct 2026",
"to": "Passed",
"effective": "2026-10-04"
}
],
"approvals_needed": [],
"blocked": []
}
}
}Decide on a fixed-term contract#
POST/v1/org/people.contract_decideWrite
What happens when someone's fixed-term contract (contract_end_date on their current job) ends, as HR practice has it: renew (new_end_date: a job change from the day after the current end, so each renewal shows in the history), permanent (contract_type permanent and no end date, from effective_date, default the day after the end) or end (they leave on the contract end date, as with org_people_mark_leaving, reason "End of fixed-term contract"). For people employed through a Portuguese legal entity, warnings apply the Código do Trabalho (2023): at most 2 years and 3 renewals, renewals in total no longer than the first term, and written notice 15 days before the end to let it end. Changes follow the approval rules. Owners, admins and HR. Use dry_run first.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_people_contract_decideon 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
person_idstringrequiredoutcome"renew" | "permanent" | "end"requirednew_end_datestringeffective_datestringperson_toldbooleanWhether the person has already been told about this last day. false: it stays with HR and their manager (Home asks to tell them) until someone marks them told with
org_people_mark_toldor the day passes; until then they see no last day, reason, offboarding task or time off change. Absent: true for resignation, retirement, mutual_agreement and death, false otherwise (a moved termination keeps its own).
Returns
personobjectrequired35 fields
idstringrequirednamestringrequiredgiven_namestringrequiredfamily_namestringrequiredpreferred_namestring | nullrequiredwork_emailstringrequiredtitlestring | nullrequiredstatus"invited" | "pre_hire" | "active" | "terminated" | "none"requiredinvited: waiting for their details (names, title, start date), not employed yet; pre_hire: starts later; active; terminated: has left; none: no job.
start_datestring | nullrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
invitedbooleanrequiredhas_loginbooleanrequiredphoto_urlstring | nullrequiredpronounsstring | nullrequiredwork_phonestring | nullrequiredpersonal_emailstring | nullrequiredpersonal_phonestring | nullrequiredaddressobject | nullrequired5 fields
line1stringrequiredline2stringcitystringrequiredpostal_codestringcountrystringrequired
birthdaystring | nullrequiredsex"female" | "male" | "another" | "undisclosed"requiredFor equal-pay reporting only (private: the person, owners, admins and HR in the app). female and male are compared; another and undisclosed are counted, not compared.
emergency_contactsobject[] | nullrequired3 fields
namestringrequiredrelationshipstringrequiredphonestringrequired
tax_idstring | nullrequiredsocial_security_numberstring | nullrequiredibanstring | 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
jobobject | nullrequired23 fields
idstringrequiredvalid_fromstringrequiredvalid_tostring | nullrequiredtitlestringrequiredThe job title as the catalog names it now (reports and grouping use this).
title_idstring | nullrequiredThe catalog title (
org_titles_list); null while not in the catalog yet.display_titlestring | nullrequiredA different title shown on the profile, chart and directory; null: the catalog title.
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumberrequiredreasonstringrequiredend_reasonstring | nullrequiredleaving_typestring (enum)requiredWhy the employment ended (structured); null: not recorded or still employed.
One of:
resignation,retirement,dismissal,redundancy,end_of_contract,mutual_agreement,death,other.toldboolean | nullrequiredWith a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until
org_people_mark_toldor the day passes. null on other rows.contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequiredcustomobject[]requiredJob custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.
7 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
regrettedboolean | nullPrivate (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.
historyobject[] | nullrequired23 fields
idstringrequiredvalid_fromstringrequiredvalid_tostring | nullrequiredtitlestringrequiredThe job title as the catalog names it now (reports and grouping use this).
title_idstring | nullrequiredThe catalog title (
org_titles_list); null while not in the catalog yet.display_titlestring | nullrequiredA different title shown on the profile, chart and directory; null: the catalog title.
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumberrequiredreasonstringrequiredend_reasonstring | nullrequiredleaving_typestring (enum)requiredWhy the employment ended (structured); null: not recorded or still employed.
One of:
resignation,retirement,dismissal,redundancy,end_of_contract,mutual_agreement,death,other.toldboolean | nullrequiredWith a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until
org_people_mark_toldor the day passes. null on other rows.contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequiredcustomobject[]requiredJob custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.
7 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
regrettedboolean | nullPrivate (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.
reportsobject[]required4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
visible_tiers"public" | "private" | "job" | "pay"[]requiredplannedobject | nullrequiredWhile invited (status invited): the job details known so far (job tier; null otherwise or when not visible).
14 fields
titlestring | nullrequiredtitle_idstring | nullrequiredstart_datestring | nullrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumber | nullrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequired
missing"given_name" | "family_name" | "title" | "start_date"[]requiredWhile invited: what is still needed to register them (given_name, family_name, title, start_date); [] otherwise.
dotted_managersobject[]requiredDotted-line managers today (spec structure-over-time D10): they see job details, never approve.
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
dotted_reportsobject[]requiredPeople this person has a dotted line to today.
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
approvalobject | nullrequired11 fields
idstringrequiredstatus"pending" | "approved"requiredwaiting_for"manager" | "hr"requiredapproversstring[]requiredautomaticbooleanrequirednote"proposed_by_approver" | "no_other_approver"requiredfallbackbooleanrequiredteam_leadobject | nullrequired3 fields
unit_idstringrequiredunit_namestringrequiredreason"no_manager" | "manager_left"required
team_lead_blockedobject | nullrequired3 fields
unit_idstringrequiredunit_namestringrequiredwhat"lead" | "removed" | "moved" | "archived"required
untrusted"no_login" | "invited_by_proposer"requiredthen"manager" | "hr"required
previewobjectrequired4 fields
summarystringrequiredchangesobject[]required6 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
fieldstringrequiredlabelstringrequiredfromstring | nullrequiredtostring | nullrequiredeffectivestringrequired
approvals_neededobject[]required3 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
waiting_for"manager" | "hr"requiredapproversstring[]required
blockedobject[]required2 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
reasonstringrequired
warningsstring[]requiredThings to check before going ahead, such as Portuguese legal limits (warnings, never refusals).
legalobject | nullrequired4 fields
countrystringrequireddays_servedintegerrequiredprobation_notice_daysintegerrequiredprobation_max_endstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/people.contract_decide \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"person_id":"p1","outcome":"permanent","effective_date":"2026-11-01"}'const res = await fetch('https://api.bizisy.com/v1/org/people.contract_decide', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p1",
"outcome": "permanent",
"effective_date": "2026-11-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/people.contract_decide",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p1",
"outcome": "permanent",
"effective_date": "2026-11-01",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person": {
"id": "p1",
"name": "Ana Ferreira",
"given_name": "Ana",
"family_name": "Ferreira",
"preferred_name": null,
"work_email": "ana@acme.test",
"title": "Engineer",
"status": "active",
"start_date": "2024-01-15",
"unit": {
"id": "u2",
"name": "Engineering"
},
"location": {
"id": "l1",
"name": "Head office"
},
"manager": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"invited": true,
"has_login": true,
"photo_url": null,
"pronouns": "she/her",
"work_phone": "+351 210 000 000",
"personal_email": null,
"personal_phone": null,
"address": null,
"birthday": null,
"sex": "female",
"emergency_contacts": null,
"tax_id": null,
"social_security_number": null,
"iban": null,
"custom": [
{
"key": "t_shirt_size",
"label": "T-shirt size",
"type": "select",
"tier": "public",
"value": "M"
},
{
"key": "remote",
"label": "Remote allowance",
"type": "boolean",
"tier": "job",
"value": null
}
],
"job": {
"id": "j1",
"valid_from": "2024-01-15",
"valid_to": null,
"title": "Engineer",
"title_id": "t1",
"display_title": null,
"unit": {
"id": "u2",
"name": "Engineering"
},
"manager": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"location": {
"id": "l1",
"name": "Head office"
},
"legal_entity": {
"id": "e1",
"name": "Acme Lda"
},
"employment_type": "full_time",
"fte": 1,
"reason": "hire",
"end_reason": null,
"leaving_type": null,
"told": null,
"contract_type": "fixed_term",
"contract_end_date": "2026-01-14",
"probation_end_date": "2024-07-14",
"weekly_hours": 40,
"notice_period_days": 30,
"custom": [
{
"key": "shift_pattern",
"label": "Shift pattern",
"type": "select",
"tier": "job",
"value": "Day"
}
]
},
"history": [
{
"id": "j1",
"valid_from": "2024-01-15",
"valid_to": null,
"title": "Engineer",
"title_id": "t1",
"display_title": null,
"unit": {
"id": "u2",
"name": "Engineering"
},
"manager": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"location": {
"id": "l1",
"name": "Head office"
},
"legal_entity": {
"id": "e1",
"name": "Acme Lda"
},
"employment_type": "full_time",
"fte": 1,
"reason": "hire",
"end_reason": null,
"leaving_type": null,
"told": null,
"contract_type": "fixed_term",
"contract_end_date": "2026-01-14",
"probation_end_date": "2024-07-14",
"weekly_hours": 40,
"notice_period_days": 30,
"custom": [
{
"key": "shift_pattern",
"label": "Shift pattern",
"type": "select",
"tier": "job",
"value": "Day"
}
]
}
],
"reports": [],
"visible_tiers": [
"public",
"job"
],
"planned": null,
"missing": [],
"dotted_managers": [
{
"id": "p7",
"name": "João Pereira",
"title": "Sales Lead",
"photo_url": null
}
],
"dotted_reports": []
},
"approval": null,
"warnings": [
"In Portugal a fixed-term contract lasts at most 2 years in total, renewals included (Código do Trabalho, art. 148)."
],
"legal": null,
"preview": {
"summary": "Ana Ferreira's contract is renewed until 31 Oct 2027.",
"changes": [],
"approvals_needed": [],
"blocked": []
}
}
}Find people, teams, locations and positions#
POST/v1/org/findRead
Finds what a name refers to, in one call: people (by name, preferred name, email or title), teams, locations, open positions and legal entities whose name contains q (2+ characters; accents and case ignored). kinds limits the search. Each result has kind, id, name and a short detail (title and team, a team's parent, a position's status). Leavers are included with status terminated; erased people never. Open positions only for those who may see them. Use the ids with the other tools.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
org_findon My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
qstringrequired2–100 characters.
kinds"person" | "team" | "location" | "position" | "legal_entity"[]At least 1 item.
limitintegerFrom 1 to 50.
Returns
resultsobject[]required5 fields
kind"person" | "team" | "location" | "position" | "legal_entity"requiredidstringrequirednamestringrequireddetailstring | nullrequiredstatusstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/find \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"q":"eng","kinds":["team","position"],"limit":5}'const res = await fetch('https://api.bizisy.com/v1/org/find', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"q": "eng",
"kinds": [
"team",
"position"
],
"limit": 5
}),
});
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/find",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"q": "eng",
"kinds": [
"team",
"position",
],
"limit": 5,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"results": [
{
"kind": "person",
"id": "p1",
"name": "João Pereira",
"detail": "Engineer · Platform",
"status": "active"
},
{
"kind": "team",
"id": "u1",
"name": "Engineering",
"detail": null,
"status": null
}
]
}
}Query people (filters, columns, pages)#
POST/v1/org/people.queryRead
Lists people with the filters and fields you choose, a page at a time (limit up to 200, offset; total says how many match). Filters (combined with AND): status (default active and starting soon; terminated or all for leavers; invited for people invited by email who are still waiting for their details), unit_id (include_subunits for every team below), manager_id, location_id, title_id (a job title from org_titles_list; titles merged into it count too), starts_between {from, to}, and job-detail filters on_probation (true: a probation end date today or later), probation_ends_between, contract_ends_between. columns picks fields: title, unit, manager, location, start_date, employment_type, fte, contract_type, contract_end_date, probation_end_date (default title, unit, manager). Job details (employment_type, fte, contract_type, contract_end_date, probation_end_date and the job filters) count only for people whose job details you may see — yourself, people you manage, everyone for owners, admins and HR; for others those columns are null and the job filters leave them out. group_id: members of a saved group (org_groups_list) today, as you see them. Never private or pay data. Dates as of today.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
org_people_queryon My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
status"active" | "pre_hire" | "terminated" | "invited" | "all"unit_idstringinclude_subunitsbooleanmanager_idstringlocation_idstringtitle_idstringstarts_betweenobject2 fields
fromstringrequiredtostringrequired
on_probationbooleanprobation_ends_betweenobject2 fields
fromstringrequiredtostringrequired
contract_ends_betweenobject2 fields
fromstringrequiredtostringrequired
group_idstringcolumnsstring (enum)[]One of:
title,unit,manager,location,start_date,employment_type,fte,contract_type,contract_end_date,probation_end_date. 1–10 items.limitintegerFrom 1 to 200.
offsetintegerAt least 0.
Returns
totalintegerrequiredoffsetintegerrequirednext_offsetinteger | nullrequiredpeopleobject[]requiredThe chosen columns only.
13 fields
idstringrequirednamestringrequiredstatusstringrequiredtitlestring | number | "null"unitstring | number | "null"managerstring | number | "null"locationstring | number | "null"start_datestring | number | "null"employment_typestring | number | "null"ftestring | number | "null"contract_typestring | number | "null"contract_end_datestring | number | "null"probation_end_datestring | number | "null"
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/people.query \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"status": "all",
"unit_id": "u1",
"include_subunits": true,
"on_probation": true,
"probation_ends_between": {
"from": "2026-10-01",
"to": "2026-12-31"
},
"columns": [
"probation_end_date",
"manager"
],
"limit": 100,
"offset": 0
}'const res = await fetch('https://api.bizisy.com/v1/org/people.query', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"status": "all",
"unit_id": "u1",
"include_subunits": true,
"on_probation": true,
"probation_ends_between": {
"from": "2026-10-01",
"to": "2026-12-31"
},
"columns": [
"probation_end_date",
"manager"
],
"limit": 100,
"offset": 0
}),
});
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/people.query",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"status": "all",
"unit_id": "u1",
"include_subunits": True,
"on_probation": True,
"probation_ends_between": {
"from": "2026-10-01",
"to": "2026-12-31",
},
"columns": [
"probation_end_date",
"manager",
],
"limit": 100,
"offset": 0,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"total": 3,
"offset": 0,
"next_offset": 2,
"people": [
{
"id": "p1",
"name": "Ana Ferreira",
"status": "active",
"title": "Engineer",
"unit": "Platform",
"manager": null
},
{
"id": "p2",
"name": "Bea Silva",
"status": "active",
"title": "Lead",
"unit": "Platform",
"manager": "Ana Ferreira"
}
]
}
}A person's journey#
POST/v1/org/people.journeyRead
Where a person is in their employment, from hire to leaving: stage (hired: before the start date; onboarding: an onboarding checklist is open; probation: until probation_end_date; employed; leaving: a last day is set; former), every stage with done/current/upcoming/skipped, its date and checklist progress, next (the one thing coming: the start, the next onboarding task, the probation end, the contract end, the work anniversary or the last day, with the person-page tab to act on it) and timeline (newest first: hired, rehired, promotion, transfer, change with what changed, pay changes (only for those who see pay: the person and owners, admins and HR in the app), probation ended, onboarding and offboarding started and completed, last day; future-dated ones have scheduled true). Job details: the person, their managers (dotted-line ones too), owners, admins and HR, and custom roles covering them; others are refused. The person themselves never sees a planned last day or a future change here. Use it for "where is Ana in onboarding?" or "what is next for Ben?".
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
org_people_journeyon HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
person_idstringrequired
Returns
personobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
todaystringrequiredstage"hired" | "onboarding" | "probation" | "employed" | "leaving" | "former"requirednull: never employed (an invited person with no job yet).
stagesobject[]required4 fields
key"hired" | "onboarding" | "probation" | "employed" | "leaving" | "former"requiredstate"done" | "current" | "upcoming" | "skipped"requireddatestring | nullrequiredhired: start date; probation: end date; leaving: last day; former: last day.
progressobject | nullrequiredonboarding and leaving: the checklist progress.
3 fields
doneintegerrequiredskippedintegerrequiredtotalintegerrequired
nextobject | nullrequired4 fields
kind"start" | "onboarding_task" | "probation_end" | "contract_end" | "anniversary" | "last_day"requireddatestring | nullrequiredlabelstring | nullrequiredonboarding_task: the task title.
tab"job" | "contract" | "checklists"requiredWhere on the person page to act on it.
timelineobject[]requiredNewest first.
10 fields
kindstring (enum)requiredOne of:
hired,rehired,promotion,transfer,change,pay,probation_ended,onboarding_started,onboarding_completed,offboarding_started,offboarding_completed,last_day.datestringrequiredscheduledbooleanrequiredA future-dated change (never shown to the person themselves).
titlestring | nullrequiredunitstring | nullrequiredmanagerstring | nullrequiredchangedstring (enum)[]requiredOne of:
title,unit,manager,location,legal_entity,employment_type,fte,contract.payobject | nullrequired3 fields
amountnumberrequiredcurrencystringrequiredperiodstringrequired
checklistobject | nullrequired2 fields
idstringrequirednamestringrequired
tab"job" | "pay" | "contract" | "checklists"required
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/people.journey \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"person_id":"p1"}'const res = await fetch('https://api.bizisy.com/v1/org/people.journey', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"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/people.journey",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"person_id": "p1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"today": "2026-10-04",
"stage": "probation",
"stages": [
{
"key": "hired",
"state": "done",
"date": "2026-06-01",
"progress": null
},
{
"key": "onboarding",
"state": "done",
"date": null,
"progress": {
"done": 9,
"skipped": 1,
"total": 10
}
},
{
"key": "probation",
"state": "current",
"date": "2026-11-30",
"progress": null
},
{
"key": "employed",
"state": "upcoming",
"date": null,
"progress": null
},
{
"key": "leaving",
"state": "upcoming",
"date": null,
"progress": null
},
{
"key": "former",
"state": "upcoming",
"date": null,
"progress": null
}
],
"next": {
"kind": "probation_end",
"date": "2026-11-30",
"label": null,
"tab": "contract"
},
"timeline": [
{
"kind": "onboarding_completed",
"date": "2026-07-03",
"scheduled": false,
"title": null,
"unit": null,
"manager": null,
"changed": [],
"pay": null,
"checklist": {
"id": "run1",
"name": "Onboarding"
},
"tab": "checklists"
},
{
"kind": "hired",
"date": "2026-06-01",
"scheduled": false,
"title": "Engineer",
"unit": "Engineering",
"manager": "Ana Ferreira",
"changed": [],
"pay": null,
"checklist": null,
"tab": "job"
}
]
}
}People by journey stage#
POST/v1/org/people.journey_listRead
The people whose job details you may see (owners, admins and HR: everyone; a manager: the people below them; a custom role: those it covers), with their journey stage (hired, onboarding, probation, employed, leaving, former), the stage date (start date, probation end or last day; for onboarding, the next open task's due date) and checklist progress. stage filters to one stage; due_by (YYYY-MM-DD) keeps only those whose stage date is on or before it (e.g. probation ending this month). Former employees are listed only with stage "former". Never yourself. Use org_people_journey for one person's detail.
- Who can call it
- Manage key any Manage role
- MCP tool
org_people_journey_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
stage"hired" | "onboarding" | "probation" | "employed" | "leaving" | "former"due_bystringPattern
^\d{4}-\d{2}-\d{2}$.
Returns
todaystringrequiredpeopleobject[]required4 fields
personobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
stage"hired" | "onboarding" | "probation" | "employed" | "leaving" | "former"requireddatestring | nullrequiredprogressobject | nullrequired3 fields
doneintegerrequiredskippedintegerrequiredtotalintegerrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/people.journey_list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"stage":"probation","due_by":"2026-10-31"}'const res = await fetch('https://api.bizisy.com/v1/org/people.journey_list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"stage": "probation",
"due_by": "2026-10-31"
}),
});
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/people.journey_list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"stage": "probation",
"due_by": "2026-10-31",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"today": "2026-10-04",
"people": [
{
"person": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"stage": "probation",
"date": "2026-11-30",
"progress": null
}
]
}
}Change a bank account (with proof)#
POST/v1/org/bank.requestWrite
With Verified bank details on: asks for a new bank account (IBAN) for yourself (person_id left out) or, as owner, admin, HR or a custom role with Private details at Edit, for someone else. Nothing changes for payroll yet: the change waits for a proof (org_bank_proof_start / org_bank_proof_finish), is checked automatically and, unless the company trusts the check, reviewed by HR. A new request replaces an open one. In the Bizisy app only (never over an API key or an AI app). validation_failed for an invalid IBAN; conflict when it is already the account on record. Part of the Verified bank details module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).
- Web app only
- Refused for API keys and connected apps. Bank accounts change in the app only (Verified bank details).
- MCP tool
org_bank_requeston My Workplace, 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
person_idstringibanstringrequired15–42 characters.
Returns
13 fields
idstringrequiredpersonobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
status"awaiting_proof" | "in_review" | "verified" | "rejected" | "cancelled"requirednew_ibanstring | nullrequiredThe account asked for: only for the person and those who see private details; else null.
new_last4stringrequiredcurrent_last4string | nullrequiredThe account payroll uses now (last 4 characters).
proofobject | nullrequired3 fields
content_typestringrequiredsizeintegerrequireduploaded_atstringrequired
verdictobject | nullrequired3 fields
result"verified" | "needs_review" | "rejected"requiredreasonsstring (enum)[]requiredOne of:
iban_on_document,iban_not_found,other_iban,name_matches,name_partial,name_not_found,unreadable,not_read,no_ai_credits.checked_atstringrequired
requested_as"self" | "hr"requireddecidedobject | nullrequired4 fields
how"automatic" | "hr"requiredbyobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
atstringrequirednotestring | nullrequired
canobjectrequired3 fields
uploadbooleanrequireddecidebooleanrequiredcancelbooleanrequired
created_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/bank.request \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"person_id":"p2"}'const res = await fetch('https://api.bizisy.com/v1/org/bank.request', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p2"
}),
});
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/bank.request",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p2",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "bc1",
"person": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": null
},
"status": "awaiting_proof",
"new_iban": "PT50000201231234567890154",
"new_last4": "0154",
"current_last4": "3000",
"proof": null,
"verdict": null,
"requested_as": "self",
"decided": null,
"can": {
"upload": true,
"decide": true,
"cancel": true
},
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:01:02.000Z"
}
}Start uploading a bank proof#
POST/v1/org/bank.proof.startWrite
Starts the upload of the proof for a bank account change: a bank statement or the bank's IBAN certificate showing the account and its holder, as PDF, PNG, JPEG or WebP, at most 10 MB. Returns a signed upload (PUT the bytes within 15 minutes), then call org_bank_proof_finish. The person or HR, in the app only. Part of the Verified bank details module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).
- Web app only
- Refused for API keys and connected apps. Bank accounts change in the app only (Verified bank details).
- MCP tool
org_bank_proof_starton My Workplace, 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
change_idstringrequirednamestringrequired1–200 characters.
sizeintegerrequiredAt least 1.
content_typestringrequiredsha256stringrequiredPattern
^[0-9a-f]{64}$.
Returns
file_idstringrequireduploadobject | nullrequired4 fields
urlstringrequiredmethod"PUT"requiredheadersobjectrequiredresumablefalserequired
expires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/bank.proof.start \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"change_id": "bc1",
"name": "iban.pdf",
"size": 48211,
"content_type": "application/pdf",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}'const res = await fetch('https://api.bizisy.com/v1/org/bank.proof.start', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"change_id": "bc1",
"name": "iban.pdf",
"size": 48211,
"content_type": "application/pdf",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}),
});
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/bank.proof.start",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"change_id": "bc1",
"name": "iban.pdf",
"size": 48211,
"content_type": "application/pdf",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"file_id": "f1",
"upload": {
"url": "https://storage.googleapis.com/upload",
"method": "PUT",
"headers": {
"content-type": "application/pdf"
},
"resumable": false
},
"expires_at": "2026-10-04T10:15:00.000Z"
}
}Check a bank proof#
POST/v1/org/bank.proof.finishWrite
Finishes the proof upload and checks it automatically (Google Cloud Document AI reads the text; Bizisy looks for the IBAN and the holder's legal name). Checking a bank proof uses 1 AI credit (ai_credits says how many are left; a dry run says the cost and reads nothing); with no AI credits left the proof is not read and HR reviews it (reason no_ai_credits, which only HR sees). Verdict verified (applied at once when the company trusts the check, else HR reviews), needs_review (HR reviews) or rejected (a different account is on the document: upload another proof or cancel). The reasons say why; the document's text is never kept. At most 5 checks per person and 200 per company a day (rate_limited). The person or HR, in the app only. Part of the Verified bank details module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).
- Web app only
- Refused for API keys and connected apps. Bank accounts change in the app only (Verified bank details).
- MCP tool
org_bank_proof_finishon My Workplace, 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
change_idstringrequiredfile_idstringrequired
Returns
14 fields
idstringrequiredpersonobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
status"awaiting_proof" | "in_review" | "verified" | "rejected" | "cancelled"requirednew_ibanstring | nullrequiredThe account asked for: only for the person and those who see private details; else null.
new_last4stringrequiredcurrent_last4string | nullrequiredThe account payroll uses now (last 4 characters).
proofobject | nullrequired3 fields
content_typestringrequiredsizeintegerrequireduploaded_atstringrequired
verdictobject | nullrequired3 fields
result"verified" | "needs_review" | "rejected"requiredreasonsstring (enum)[]requiredOne of:
iban_on_document,iban_not_found,other_iban,name_matches,name_partial,name_not_found,unreadable,not_read,no_ai_credits.checked_atstringrequired
requested_as"self" | "hr"requireddecidedobject | nullrequired4 fields
how"automatic" | "hr"requiredbyobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
atstringrequirednotestring | nullrequired
canobjectrequired3 fields
uploadbooleanrequireddecidebooleanrequiredcancelbooleanrequired
created_atstringrequiredupdated_atstringrequiredai_creditsobject | nullrequiredFor HR only (null for the person, and when Bizisy does not read proofs here): what checking the proof costs. A dry run says what it would use and reads nothing.
3 fields
costintegerrequiredAI credits a check uses (1).
leftinteger | nullrequiredAI credits the company has left (after this check; on a dry run, now); null when unlimited.
notestringrequiredThe same in words, e.g. "Uses 1 AI credit (12 left)".
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/bank.proof.finish \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"change_id":"bc1","file_id":"f1"}'const res = await fetch('https://api.bizisy.com/v1/org/bank.proof.finish', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"change_id": "bc1",
"file_id": "f1"
}),
});
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/bank.proof.finish",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"change_id": "bc1",
"file_id": "f1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "bc1",
"person": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": null
},
"status": "in_review",
"new_iban": "PT50000201231234567890154",
"new_last4": "0154",
"current_last4": "3000",
"proof": {
"content_type": "application/pdf",
"size": 48211,
"uploaded_at": "2026-10-04T10:01:00.000Z"
},
"verdict": {
"result": "verified",
"reasons": [
"iban_on_document",
"name_matches"
],
"checked_at": "2026-10-04T10:01:02.000Z"
},
"requested_as": "self",
"decided": null,
"can": {
"upload": true,
"decide": true,
"cancel": true
},
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:01:02.000Z",
"ai_credits": {
"cost": 1,
"left": 12,
"note": "Used 1 AI credit (12 left)"
}
}
}Approve or reject a bank account change#
POST/v1/org/bank.decideWrite
HR decides a bank account change waiting for review (status in_review), after looking at the proof (org_bank_proof_url) and the automatic verdict: approve sets the account for payroll (the person and HR get the usual payroll details email), reject closes it (note: why, shown to the person). Owners, admins, HR and custom roles with Private details at Edit covering the person; never your own change, and never one you asked for (a second person decides). In the app only. Part of the Verified bank details module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).
- Web app only
- Refused for API keys and connected apps. Bank accounts change in the app only (Verified bank details).
- MCP tool
org_bank_decideon 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
change_idstringrequireddecision"approve" | "reject"requirednotestringUp to 300 characters.
proof_uploaded_atstringThe proof's uploaded_at as you read it: refused (conflict) when a newer proof came since.
Returns
13 fields
idstringrequiredpersonobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
status"awaiting_proof" | "in_review" | "verified" | "rejected" | "cancelled"requirednew_ibanstring | nullrequiredThe account asked for: only for the person and those who see private details; else null.
new_last4stringrequiredcurrent_last4string | nullrequiredThe account payroll uses now (last 4 characters).
proofobject | nullrequired3 fields
content_typestringrequiredsizeintegerrequireduploaded_atstringrequired
verdictobject | nullrequired3 fields
result"verified" | "needs_review" | "rejected"requiredreasonsstring (enum)[]requiredOne of:
iban_on_document,iban_not_found,other_iban,name_matches,name_partial,name_not_found,unreadable,not_read,no_ai_credits.checked_atstringrequired
requested_as"self" | "hr"requireddecidedobject | nullrequired4 fields
how"automatic" | "hr"requiredbyobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
atstringrequirednotestring | nullrequired
canobjectrequired3 fields
uploadbooleanrequireddecidebooleanrequiredcancelbooleanrequired
created_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/bank.decide \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"change_id": "bc1",
"decision": "reject",
"note": "The holder is someone else"
}'const res = await fetch('https://api.bizisy.com/v1/org/bank.decide', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"change_id": "bc1",
"decision": "reject",
"note": "The holder is someone else"
}),
});
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/bank.decide",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"change_id": "bc1",
"decision": "reject",
"note": "The holder is someone else",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "bc1",
"person": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": null
},
"status": "verified",
"new_iban": "PT50000201231234567890154",
"new_last4": "0154",
"current_last4": "3000",
"proof": {
"content_type": "application/pdf",
"size": 48211,
"uploaded_at": "2026-10-04T10:01:00.000Z"
},
"verdict": {
"result": "verified",
"reasons": [
"iban_on_document",
"name_matches"
],
"checked_at": "2026-10-04T10:01:02.000Z"
},
"requested_as": "self",
"decided": {
"how": "hr",
"by": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"at": "2026-10-04T11:00:00.000Z",
"note": null
},
"can": {
"upload": false,
"decide": false,
"cancel": false
},
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:01:02.000Z"
}
}Cancel a bank account change#
POST/v1/org/bank.cancelWrite
Cancels an open bank account change (waiting for a proof or for review); the account on record stays and the proof is deleted. The person or HR, in the app only. Part of the Verified bank details module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).
- Web app only
- Refused for API keys and connected apps. Bank accounts change in the app only (Verified bank details).
- MCP tool
org_bank_cancelon My Workplace, 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
change_idstringrequired
Returns
13 fields
idstringrequiredpersonobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
status"awaiting_proof" | "in_review" | "verified" | "rejected" | "cancelled"requirednew_ibanstring | nullrequiredThe account asked for: only for the person and those who see private details; else null.
new_last4stringrequiredcurrent_last4string | nullrequiredThe account payroll uses now (last 4 characters).
proofobject | nullrequired3 fields
content_typestringrequiredsizeintegerrequireduploaded_atstringrequired
verdictobject | nullrequired3 fields
result"verified" | "needs_review" | "rejected"requiredreasonsstring (enum)[]requiredOne of:
iban_on_document,iban_not_found,other_iban,name_matches,name_partial,name_not_found,unreadable,not_read,no_ai_credits.checked_atstringrequired
requested_as"self" | "hr"requireddecidedobject | nullrequired4 fields
how"automatic" | "hr"requiredbyobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
atstringrequirednotestring | nullrequired
canobjectrequired3 fields
uploadbooleanrequireddecidebooleanrequiredcancelbooleanrequired
created_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/bank.cancel \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"change_id":"bc1"}'const res = await fetch('https://api.bizisy.com/v1/org/bank.cancel', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"change_id": "bc1"
}),
});
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/bank.cancel",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"change_id": "bc1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "bc1",
"person": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": null
},
"status": "cancelled",
"new_iban": "PT50000201231234567890154",
"new_last4": "0154",
"current_last4": "3000",
"proof": null,
"verdict": {
"result": "verified",
"reasons": [
"iban_on_document",
"name_matches"
],
"checked_at": "2026-10-04T10:01:02.000Z"
},
"requested_as": "self",
"decided": null,
"can": {
"upload": false,
"decide": false,
"cancel": false
},
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:01:02.000Z"
}
}Get a bank account change#
POST/v1/org/bank.getRead
One bank account change: status, the account asked for (only for the person and those who see private details), the proof's type and size, the automatic verdict and its reasons, and who decided. The person or HR, in the app only. Part of the Verified bank details module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules); this read of stored data keeps working while it is off.
- Web app only
- Refused for API keys and connected apps. Bank accounts change in the app only (Verified bank details).
- MCP tool
org_bank_geton My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
change_idstringrequired
Returns
13 fields
idstringrequiredpersonobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
status"awaiting_proof" | "in_review" | "verified" | "rejected" | "cancelled"requirednew_ibanstring | nullrequiredThe account asked for: only for the person and those who see private details; else null.
new_last4stringrequiredcurrent_last4string | nullrequiredThe account payroll uses now (last 4 characters).
proofobject | nullrequired3 fields
content_typestringrequiredsizeintegerrequireduploaded_atstringrequired
verdictobject | nullrequired3 fields
result"verified" | "needs_review" | "rejected"requiredreasonsstring (enum)[]requiredOne of:
iban_on_document,iban_not_found,other_iban,name_matches,name_partial,name_not_found,unreadable,not_read,no_ai_credits.checked_atstringrequired
requested_as"self" | "hr"requireddecidedobject | nullrequired4 fields
how"automatic" | "hr"requiredbyobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
atstringrequirednotestring | nullrequired
canobjectrequired3 fields
uploadbooleanrequireddecidebooleanrequiredcancelbooleanrequired
created_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/bank.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"change_id":"bc1"}'const res = await fetch('https://api.bizisy.com/v1/org/bank.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"change_id": "bc1"
}),
});
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/bank.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"change_id": "bc1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "bc1",
"person": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": null
},
"status": "in_review",
"new_iban": "PT50000201231234567890154",
"new_last4": "0154",
"current_last4": "3000",
"proof": {
"content_type": "application/pdf",
"size": 48211,
"uploaded_at": "2026-10-04T10:01:00.000Z"
},
"verdict": {
"result": "verified",
"reasons": [
"iban_on_document",
"name_matches"
],
"checked_at": "2026-10-04T10:01:02.000Z"
},
"requested_as": "self",
"decided": null,
"can": {
"upload": true,
"decide": true,
"cancel": true
},
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:01:02.000Z"
}
}My bank account change#
POST/v1/org/bank.mineRead
Your latest bank account change, if any (open, or closed in the last 30 days), and whether changes need a proof (the company has Verified bank details).
- Who can call it
- Me key anyone
- MCP tool
org_bank_mineon My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
requiredbooleanrequiredchangeobject | nullrequired13 fields
idstringrequiredpersonobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
status"awaiting_proof" | "in_review" | "verified" | "rejected" | "cancelled"requirednew_ibanstring | nullrequiredThe account asked for: only for the person and those who see private details; else null.
new_last4stringrequiredcurrent_last4string | nullrequiredThe account payroll uses now (last 4 characters).
proofobject | nullrequired3 fields
content_typestringrequiredsizeintegerrequireduploaded_atstringrequired
verdictobject | nullrequired3 fields
result"verified" | "needs_review" | "rejected"requiredreasonsstring (enum)[]requiredOne of:
iban_on_document,iban_not_found,other_iban,name_matches,name_partial,name_not_found,unreadable,not_read,no_ai_credits.checked_atstringrequired
requested_as"self" | "hr"requireddecidedobject | nullrequired4 fields
how"automatic" | "hr"requiredbyobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
atstringrequirednotestring | nullrequired
canobjectrequired3 fields
uploadbooleanrequireddecidebooleanrequiredcancelbooleanrequired
created_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/bank.mine \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/bank.mine', {
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/bank.mine",
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": {
"required": true,
"change": {
"id": "bc1",
"person": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": null
},
"status": "in_review",
"new_iban": "PT50000201231234567890154",
"new_last4": "0154",
"current_last4": "3000",
"proof": {
"content_type": "application/pdf",
"size": 48211,
"uploaded_at": "2026-10-04T10:01:00.000Z"
},
"verdict": {
"result": "verified",
"reasons": [
"iban_on_document",
"name_matches"
],
"checked_at": "2026-10-04T10:01:02.000Z"
},
"requested_as": "self",
"decided": null,
"can": {
"upload": true,
"decide": true,
"cancel": true
},
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:01:02.000Z"
}
}
}List bank account changes#
POST/v1/org/bank.changes.listRead
Bank account changes HR may see: status open (default: waiting for a proof or for review), in_review, or all (the last 100). person_id narrows to one person. Owners, admins, HR and custom roles with Private details at Edit (the people they cover), in the app only. Part of the Verified bank details module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules); this read of stored data keeps working while it is off.
- Web app only
- Refused for API keys and connected apps. Bank accounts change in the app only (Verified bank details).
- MCP tool
org_bank_changes_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
status"open" | "in_review" | "all"Default
"open".person_idstring
Returns
changesobject[]required13 fields
idstringrequiredpersonobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
status"awaiting_proof" | "in_review" | "verified" | "rejected" | "cancelled"requirednew_ibanstring | nullrequiredThe account asked for: only for the person and those who see private details; else null.
new_last4stringrequiredcurrent_last4string | nullrequiredThe account payroll uses now (last 4 characters).
proofobject | nullrequired3 fields
content_typestringrequiredsizeintegerrequireduploaded_atstringrequired
verdictobject | nullrequired3 fields
result"verified" | "needs_review" | "rejected"requiredreasonsstring (enum)[]requiredOne of:
iban_on_document,iban_not_found,other_iban,name_matches,name_partial,name_not_found,unreadable,not_read,no_ai_credits.checked_atstringrequired
requested_as"self" | "hr"requireddecidedobject | nullrequired4 fields
how"automatic" | "hr"requiredbyobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
atstringrequirednotestring | nullrequired
canobjectrequired3 fields
uploadbooleanrequireddecidebooleanrequiredcancelbooleanrequired
created_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/bank.changes.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status":"all","person_id":"p2"}'const res = await fetch('https://api.bizisy.com/v1/org/bank.changes.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"status": "all",
"person_id": "p2"
}),
});
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/bank.changes.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"status": "all",
"person_id": "p2",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"changes": [
{
"id": "bc1",
"person": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": null
},
"status": "in_review",
"new_iban": "PT50000201231234567890154",
"new_last4": "0154",
"current_last4": "3000",
"proof": {
"content_type": "application/pdf",
"size": 48211,
"uploaded_at": "2026-10-04T10:01:00.000Z"
},
"verdict": {
"result": "verified",
"reasons": [
"iban_on_document",
"name_matches"
],
"checked_at": "2026-10-04T10:01:02.000Z"
},
"requested_as": "self",
"decided": null,
"can": {
"upload": true,
"decide": true,
"cancel": true
},
"created_at": "2026-10-04T10:00:00.000Z",
"updated_at": "2026-10-04T10:01:02.000Z"
}
]
}
}Open a bank proof#
POST/v1/org/bank.proof_urlRead
A link (5 minutes) to download the proof of a bank account change. The person or HR, in the app only. Part of the Verified bank details module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules); this read of stored data keeps working while it is off.
- Web app only
- Refused for API keys and connected apps. Bank accounts change in the app only (Verified bank details).
- MCP tool
org_bank_proof_urlon My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
change_idstringrequired
Returns
urlstringrequiredexpires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/bank.proof_url \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"change_id":"bc1"}'const res = await fetch('https://api.bizisy.com/v1/org/bank.proof_url', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"change_id": "bc1"
}),
});
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/bank.proof_url",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"change_id": "bc1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"url": "https://storage.googleapis.com/download",
"expires_at": "2026-10-04T10:05:00.000Z"
}
}Get the bank details settings#
POST/v1/org/bank.settings.getRead
Verified bank details: whether a change the automatic check verified applies at once (trust_automatic true) or HR always reviews it (false, the default). Owners, admins and HR, in the app only. Part of the Verified bank details module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules); this read of stored data keeps working while it is off.
- Web app only
- Refused for API keys and connected apps. Bank accounts change in the app only (Verified bank details).
- MCP tool
org_bank_settings_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
trust_automaticbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/bank.settings.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/bank.settings.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/bank.settings.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": {
"trust_automatic": false
}
}Change the bank details settings#
POST/v1/org/bank.settings.updateWrite
trust_automatic: true applies a change the automatic check verified at once (needs-review and rejected ones still go to HR or back to the person); false (the default) has HR review every change. Owners and admins, in the app only. Part of the Verified bank details module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).
- Web app only
- Refused for API keys and connected apps. Bank accounts change in the app only (Verified bank details).
- MCP tool
org_bank_settings_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
trust_automaticbooleanrequired
Returns
trust_automaticbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/bank.settings.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"trust_automatic":true}'const res = await fetch('https://api.bizisy.com/v1/org/bank.settings.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"trust_automatic": true
}),
});
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/bank.settings.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"trust_automatic": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"trust_automatic": true
}
}Something missing or wrong on this page? Write to hello@bizisy.com.