API reference
Jobs and employment
Hire (with starting pay and a scheduled invite), change jobs from a date, terminate (and say whether the person has been told), rehire, correct job history, and save any of it for later.
13 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
Hire (add) a person#
POST/v1/org/people.hireWrite
Adds a person with their first job. Required: given_name, family_name, work_email (unique), title (as typed: matched to the job title catalog, else added to it; title_match in the result says which, with similar titles) or title_id (from org_titles_list), start_date (YYYY-MM-DD; a future date makes them pre_hire). Optional: unit_id, manager_id (must be employed or starting on start_date; when absent and unit_id is set, the team lead of that unit becomes the manager — manager_default in the result says so; send null for no manager; a position_id whose position names whom it reports to gets no default), location_id and legal_entity_id (default to the only active one), employment_type (full_time, part_time, contractor, intern; default full_time), fte (0–1, default 1), contract terms (contract_type: permanent, fixed_term, temporary, internship, freelance; contract_end_date for fixed_term/temporary/internship; probation_end_date; weekly_hours; notice_period_days), profile fields (including tax_id, social_security_number, iban and sex: refused over an API key or MCP) and custom: { <field key>: value } (see org_fields_list), position_id (an open or on-hold position from org_positions_list: the hire fills it, and positions that reported to it then report to the new person; drafts, filled and cancelled positions are refused). Starts the onboarding checklists that start by themselves and match the person (see org_checklists_runs_list), unless the start date is more than 30 days ago (onboarding in the result counts them and their tasks). pay: optional starting pay {amount, currency, period, note} from start_date, with org_pay_add's rules (in the app only; refused over MCP or an API key; becomes a request when pay changes need approval). invite: {when: now | start | days_before | none, days (1–14, with days_before), role}: the sign-in invite now, or at 08:00 company time on that day (org_invites_scheduled lists them). source {kind: hiring, job_id, application_id} (from hiring_applications_hire_draft, in the app only): the candidate becomes hired and linked to the person, and their referral is recorded. Use dry_run first.
- 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_hireon 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_namestringrequired1–100 characters.
family_namestringrequired1–100 characters.
work_emailanyrequiredpreferred_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 }].titlestringThe job title as typed: matched to the job title catalog (exact name, an earlier wording, or the same words), else added to it when the change applies (see
org_titles_list).1–120 characters.
title_idstringA job title from
org_titles_list, instead of title.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.
unit_idstring | nullmanager_idstring | nulllocation_idstring | nulllegal_entity_idstring | nullemployment_type"full_time" | "part_time" | "contractor" | "intern"Default
"full_time".ftenumberFrom 0 to 1. Default
1.contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"contract_end_datestring | nullprobation_end_datestring | nullweekly_hoursnumber | nullFrom 0 to 80.
notice_period_daysinteger | nullFrom 0 to 365.
start_datestringrequiredposition_idstringpayobjectStarting pay from start_date (in the app only, like
org_pay_add; a request when pay changes need approval).4 fields
amountnumberrequiredFrom 0 to 100000000.
currencyanyrequiredperiod"year" | "month" | "hour"requirednotestringUp to 200 characters.
inviteobjectThe sign-in invite: now, on their first day (start), days_before (1–14 days before the start) or none (default). A day today or earlier sends it at once.
3 fields
when"now" | "start" | "days_before" | "none"requireddaysintegerFrom 1 to 14.
role"member" | "hr" | "admin" | "viewer"
sourceobjectA candidate hired from Hiring (hiring_applications_hire_draft gives it): the candidate becomes hired and linked to this person, in the same change. In the app only.
3 fields
kind"hiring"requiredjob_idstringrequiredapplication_idstringrequired
Returns
40 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
manager_defaultobject | nullrequiredThe manager was not given, so the lead of this team became the manager (null: the manager was given, or there was no default).
2 fields
unit_idstringrequiredunit_namestringrequired
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.
payobject | nullrequiredThe starting pay: recorded, or a request waiting for approval.
2 fields
recordedbooleanrequiredapprovalobject | 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
inviteobject | nullrequired5 fields
status"sent" | "scheduled"requiredonstringrequiredThe company-local day it was or will be sent.
urlstring | nullrequiredThe sign-in link, only when sent now and only in the web app.
expires_atstring | nullrequiredemailobject | nullrequired3 fields
status"sent" | "failed" | "skipped"requiredmessagestringrequiredreason"rate_limited"
onboardingobjectrequiredOnboarding checklists started for them, and their tasks.
2 fields
checklistsintegerrequiredtasksintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/people.hire \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"given_name": "Inês",
"family_name": "Martins",
"preferred_name": "Inês M.",
"work_email": "ines@acme.test",
"work_phone": "+351 912 000 000",
"personal_email": "ines@example.test",
"personal_phone": null,
"address": {
"line1": "Rua A 1",
"line2": "2 Esq",
"city": "Porto",
"postal_code": "4000-001",
"country": "PT"
},
"birthday": "1995-02-01",
"pronouns": "she/her",
"emergency_contacts": [
{
"name": "Rui",
"relationship": "Partner",
"phone": "+351 911"
}
],
"title": "AE",
"unit_id": "u2",
"manager_id": "p2",
"location_id": null,
"legal_entity_id": null,
"employment_type": "contractor",
"fte": 0.5,
"start_date": "2026-11-02"
}'const res = await fetch('https://api.bizisy.com/v1/org/people.hire', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"given_name": "Inês",
"family_name": "Martins",
"preferred_name": "Inês M.",
"work_email": "ines@acme.test",
"work_phone": "+351 912 000 000",
"personal_email": "ines@example.test",
"personal_phone": null,
"address": {
"line1": "Rua A 1",
"line2": "2 Esq",
"city": "Porto",
"postal_code": "4000-001",
"country": "PT"
},
"birthday": "1995-02-01",
"pronouns": "she/her",
"emergency_contacts": [
{
"name": "Rui",
"relationship": "Partner",
"phone": "+351 911"
}
],
"title": "AE",
"unit_id": "u2",
"manager_id": "p2",
"location_id": null,
"legal_entity_id": null,
"employment_type": "contractor",
"fte": 0.5,
"start_date": "2026-11-02"
}),
});
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.hire",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"given_name": "Inês",
"family_name": "Martins",
"preferred_name": "Inês M.",
"work_email": "ines@acme.test",
"work_phone": "+351 912 000 000",
"personal_email": "ines@example.test",
"personal_phone": None,
"address": {
"line1": "Rua A 1",
"line2": "2 Esq",
"city": "Porto",
"postal_code": "4000-001",
"country": "PT",
},
"birthday": "1995-02-01",
"pronouns": "she/her",
"emergency_contacts": [
{
"name": "Rui",
"relationship": "Partner",
"phone": "+351 911",
},
],
"title": "AE",
"unit_id": "u2",
"manager_id": "p2",
"location_id": None,
"legal_entity_id": None,
"employment_type": "contractor",
"fte": 0.5,
"start_date": "2026-11-02",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "p1",
"name": "Inês M.",
"given_name": "Inês",
"family_name": "Martins",
"preferred_name": "Inês M.",
"work_email": "ines@acme.test",
"title": "AE",
"status": "active",
"start_date": "2026-11-02",
"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 912 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": "AE",
"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": [],
"manager_default": {
"unit_id": "u2",
"unit_name": "Engineering"
},
"title_match": {
"id": null,
"name": "Backend Engineer",
"created": true,
"similar": [
{
"id": "t1",
"name": "Back-end Engineer",
"people": 6
}
]
},
"pay": {
"recorded": true,
"approval": null
},
"invite": {
"status": "scheduled",
"on": "2026-11-02",
"url": null,
"expires_at": null,
"email": null
},
"onboarding": {
"checklists": 1,
"tasks": 6
}
}
}Change a person's job (effective-dated)#
POST/v1/org/people.change_jobWrite
Records a job change from effective_date (YYYY-MM-DD, may be in the future): title, unit_id, manager_id, location_id, legal_entity_id, employment_type, fte and/or contract terms (contract_type, contract_end_date, probation_end_date, weekly_hours, notice_period_days; null clears one), and custom: job custom fields (org_fields_list, target job; { <key>: value }, null clears one; the others carry forward). title is matched to the job title catalog or added to it when the change applies (title_match in the result says which, with similar titles); or send title_id. display_title shows a different title on the profile. reason is change, promotion or transfer. Moving into another unit without manager_id makes that unit's team lead the manager (the parent unit's lead when the person is that lead; manager_default in the result says so); send manager_id (or null) to choose. When Settings → Approval rules requires approval for job changes, nothing changes yet: a request is created for the approvers (approval in the result says who; org_approvals_get follows it) and the change applies when approved; a person can have one open job request at a time. The current row is closed on that date and a new one opens with the merged fields; a scheduled termination is kept. Rejected if the person is not employed that day, if a row already starts that day (use org_people_correct_job), if the manager is not employed then, or if it would create a reporting cycle on any day from effective_date on. Rows already scheduled after effective_date keep their own values — check history if a later change exists. If every field sent already has that value on effective_date, nothing is written and unchanged is true (safe to retry).
- Who can call it
- Manage key owner admin hr
- MCP tool
org_people_change_jobon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
titlestringThe job title as typed: matched to the job title catalog (exact name, an earlier wording, or the same words), else added to it when the change applies (see
org_titles_list).1–120 characters.
title_idstringA job title from
org_titles_list, instead of title.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.
unit_idstring | nullmanager_idstring | nulllocation_idstring | nulllegal_entity_idstring | nullemployment_type"full_time" | "part_time" | "contractor" | "intern"ftenumberFrom 0 to 1.
contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"contract_end_datestring | nullprobation_end_datestring | nullweekly_hoursnumber | nullFrom 0 to 80.
notice_period_daysinteger | nullFrom 0 to 365.
customobjectJob custom fields (
org_fields_list, target job) by key; null clears one. Values follow the job timeline: the others carry forward unchanged.person_idstringrequiredeffective_datestringrequiredreason"change" | "promotion" | "transfer"required
Returns
39 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
unchangedbooleantrue when the job already was exactly so on effective_date: nothing was written.
manager_defaultobject | nullrequiredThe manager was not given, so the lead of this team became the manager (null: the manager was given, or there was no default).
2 fields
unit_idstringrequiredunit_namestringrequired
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.change_job \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"person_id": "p1",
"effective_date": "2026-10-05",
"reason": "transfer",
"unit_id": "u3",
"manager_id": null,
"location_id": "l2",
"legal_entity_id": "e1",
"employment_type": "part_time",
"fte": 0.8
}'const res = await fetch('https://api.bizisy.com/v1/org/people.change_job', {
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-10-05",
"reason": "transfer",
"unit_id": "u3",
"manager_id": null,
"location_id": "l2",
"legal_entity_id": "e1",
"employment_type": "part_time",
"fte": 0.8
}),
});
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.change_job",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p1",
"effective_date": "2026-10-05",
"reason": "transfer",
"unit_id": "u3",
"manager_id": None,
"location_id": "l2",
"legal_entity_id": "e1",
"employment_type": "part_time",
"fte": 0.8,
},
)
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": [],
"approval": {
"id": "apr1",
"status": "pending",
"waiting_for": "manager",
"approvers": [
"Bea Silva"
],
"automatic": false,
"note": null,
"fallback": false,
"then": "hr",
"team_lead": {
"unit_id": "u2",
"unit_name": "Engineering",
"reason": "no_manager"
},
"team_lead_blocked": null,
"untrusted": null
},
"manager_default": null,
"title_match": {
"id": "t1",
"name": "Back-end Engineer",
"created": false,
"matched_from": "backend engineer"
}
}
}Terminate employment#
POST/v1/org/people.terminateDestructive
Prefer org_people_mark_leaving, which also reassigns direct reports, can open a replacement position and ends the login. Ends employment after last_day (inclusive, YYYY-MM-DD, may be in the future) and starts the offboarding checklists that start by themselves (see org_checklists_runs_list); reason is free text (e.g. resigned; default: the reason of a scheduled termination it replaces, else "terminated"); leaving_type is why, structured (resignation, retirement, dismissal, redundancy, end_of_contract, mutual_agreement, death, other), for the turnover split in Reports. Job changes scheduled after the last day are removed, and a later scheduled termination is moved to last_day. If this employment period already has an end date, use org_people_correct_job (valid_to = last day + 1) instead. Direct reports are NOT reassigned: warnings lists them so you can change their manager. If they have a login, warnings says so: it keeps working until an owner or admin disables it with platform_members_disable. When Settings → Approval rules requires approval for terminations, a request is created instead (approval in the result): the termination, and its offboarding checklists, start only when it is approved.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_people_terminateon 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_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.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
warningsstring[]requiredapprovalobject | 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
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/people.terminate \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"person_id":"p1","last_day":"2026-10-31","reason":"resigned"}'const res = await fetch('https://api.bizisy.com/v1/org/people.terminate', {
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-10-31",
"reason": "resigned"
}),
});
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.terminate",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p1",
"last_day": "2026-10-31",
"reason": "resigned",
},
)
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": []
},
"warnings": [
"Ana Ferreira can still sign in until an owner or admin disables their login."
],
"approval": null
}
}Rehire a former employee#
POST/v1/org/people.rehireWrite
Starts a new employment for someone who has left, from start_date, with a new title and optional unit_id, manager_id (absent with a unit_id: that unit's team lead, as manager_default says; null for none), location_id, legal_entity_id, employment_type (default full_time) and fte (default 1). Rejected while they are still employed on start_date, if they already have a later job, or if they were never terminated (use org_people_hire for new people). When Settings → Approval rules requires approval for job changes, a request is created instead (approval in the result) and the rehire applies when approved.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_people_rehireon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
titlestringThe job title as typed: matched to the job title catalog (exact name, an earlier wording, or the same words), else added to it when the change applies (see
org_titles_list).1–120 characters.
title_idstringA job title from
org_titles_list, instead of title.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.
unit_idstring | nullmanager_idstring | nulllocation_idstring | nulllegal_entity_idstring | nullemployment_type"full_time" | "part_time" | "contractor" | "intern"Default
"full_time".ftenumberFrom 0 to 1. Default
1.contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"contract_end_datestring | nullprobation_end_datestring | nullweekly_hoursnumber | nullFrom 0 to 80.
notice_period_daysinteger | nullFrom 0 to 365.
customobjectJob custom fields (
org_fields_list, target job) by key; null clears one. Values follow the job timeline: the others carry forward unchanged.person_idstringrequiredstart_datestringrequired
Returns
38 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
manager_defaultobject | nullrequiredThe manager was not given, so the lead of this team became the manager (null: the manager was given, or there was no default).
2 fields
unit_idstringrequiredunit_namestringrequired
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.rehire \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"person_id": "p1",
"start_date": "2026-11-02",
"title": "Engineer",
"unit_id": "u2",
"manager_id": "p2",
"location_id": null,
"legal_entity_id": "e1",
"employment_type": "intern",
"fte": 1
}'const res = await fetch('https://api.bizisy.com/v1/org/people.rehire', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p1",
"start_date": "2026-11-02",
"title": "Engineer",
"unit_id": "u2",
"manager_id": "p2",
"location_id": null,
"legal_entity_id": "e1",
"employment_type": "intern",
"fte": 1
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/people.rehire",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p1",
"start_date": "2026-11-02",
"title": "Engineer",
"unit_id": "u2",
"manager_id": "p2",
"location_id": None,
"legal_entity_id": "e1",
"employment_type": "intern",
"fte": 1,
},
)
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": "2026-11-02",
"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,
"manager_default": null,
"title_match": null
}
}Correct a job row (fix history)#
POST/v1/org/people.correct_jobWrite
Fixes a mistake in one job row in place, without recording a new change: title, unit_id, manager_id, location_id, legal_entity_id, employment_type, fte, or valid_from (a contiguous previous row is adjusted with it). On the last row of an employment period that already has an end date, last_day (inclusive; or valid_to, the day after it) and end_reason or leaving_type adjust the termination: a later valid_to postpones it, an earlier one moves it earlier within that row (to end before a scheduled change, use org_people_terminate), and valid_to = null cancels it. It never ends an open-ended row: use org_people_terminate for that. Use it for typos and wrong dates, not for real changes (use org_people_change_job). Open checklist tasks move with a corrected start date or last day, and cancelling a termination cancels its offboarding checklist. Every correction is audited. When Settings → Approval rules requires approval, a correction of the current or a future row (job changes), or of a last day (terminations), creates a request instead (approval in the result), and checklists move only when it is approved; corrections of rows that ended before today apply at once.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_people_correct_jobon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
titlestringThe job title as typed: matched to the job title catalog (exact name, an earlier wording, or the same words), else added to it when the change applies (see
org_titles_list).1–120 characters.
title_idstringA job title from
org_titles_list, instead of title.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.
unit_idstring | nullmanager_idstring | nulllocation_idstring | nulllegal_entity_idstring | nullemployment_type"full_time" | "part_time" | "contractor" | "intern"ftenumberFrom 0 to 1.
contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"contract_end_datestring | nullprobation_end_datestring | nullweekly_hoursnumber | nullFrom 0 to 80.
notice_period_daysinteger | nullFrom 0 to 365.
customobjectJob custom fields (
org_fields_list, target job) by key; null clears one. Values follow the job timeline: the others carry forward unchanged.job_idstringrequiredvalid_fromstringvalid_tostring | nulllast_daystringThe last day worked (inclusive), as
org_people_terminatetakes it: the same as valid_to = last_day + 1. Send last_day or valid_to, not both.end_reasonstring | nullUp 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.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
37 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
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.correct_job \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"job_id": "j1",
"valid_from": "2024-01-16",
"valid_to": null,
"end_reason": null,
"unit_id": null,
"fte": 0.9
}'const res = await fetch('https://api.bizisy.com/v1/org/people.correct_job', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"job_id": "j1",
"valid_from": "2024-01-16",
"valid_to": null,
"end_reason": null,
"unit_id": null,
"fte": 0.9
}),
});
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.correct_job",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"job_id": "j1",
"valid_from": "2024-01-16",
"valid_to": None,
"end_reason": None,
"unit_id": None,
"fte": 0.9,
},
)
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": [],
"approval": {
"id": "apr2",
"status": "pending",
"waiting_for": "hr",
"approvers": [
"Ana Ferreira"
],
"automatic": false,
"note": null,
"fallback": false,
"then": null,
"team_lead": null,
"team_lead_blocked": null,
"untrusted": null
},
"title_match": null
}
}Dotted-line managers#
POST/v1/org/dotted_lines.listRead
Dotted-line (matrix) reporting lines: a secondary manager a person also works with, who sees their job details but never approves or proposes for them. Filter by person_id (their dotted-line managers) or manager_id (whom they have a dotted line to); ended lines are left out unless include_ended. The note is shown to those who see the person's job details.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
org_dotted_lines_liston My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
person_idstringmanager_idstringinclude_endedbooleanDefault
false.
Returns
An array of objects:
idstringrequiredpersonobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
managerobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
valid_fromstringrequiredlast_daystring | nullrequiredThe last day (inclusive); null: open-ended.
notestring | nullrequiredJob tier: only for those who see the person's job details.
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/dotted_lines.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"manager_id":"p7","include_ended":true}'const res = await fetch('https://api.bizisy.com/v1/org/dotted_lines.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"manager_id": "p7",
"include_ended": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/dotted_lines.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"manager_id": "p7",
"include_ended": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"id": "dl1",
"person": {
"id": "p1",
"name": "Ana Ferreira",
"title": "Engineer",
"photo_url": null
},
"manager": {
"id": "p7",
"name": "João Pereira",
"title": "Sales Lead",
"photo_url": null
},
"valid_from": "2026-10-04",
"last_day": null,
"note": "Platform project"
}
]
}Add a dotted-line manager#
POST/v1/org/dotted_lines.addWrite
Adds a dotted-line (matrix) manager for a person: someone they also work with and report to on a project or function, besides their manager. From valid_from (default today; YYYY-MM-DD) to last_day (inclusive, optional), with an optional note. The dotted-line manager sees the person's job details (not private details or pay), never approves or proposes changes for them, and shows on the chart, the person's page and their My team. At most 3 at a time; not their manager or themself; the dotted-line manager must work here on valid_from. Owners, admins and HR, and roles that edit the people they cover.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_dotted_lines_addon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
person_idstringrequiredmanager_idstringrequiredvalid_fromstringlast_daystringnotestring1–300 characters.
Returns
idstringrequiredpersonobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
managerobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
valid_fromstringrequiredlast_daystring | nullrequiredThe last day (inclusive); null: open-ended.
notestring | nullrequiredJob tier: only for those who see the person's job details.
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/dotted_lines.add \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"person_id": "p1",
"manager_id": "p7",
"valid_from": "2026-10-04",
"last_day": "2026-12-31",
"note": "Platform project"
}'const res = await fetch('https://api.bizisy.com/v1/org/dotted_lines.add', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p1",
"manager_id": "p7",
"valid_from": "2026-10-04",
"last_day": "2026-12-31",
"note": "Platform project"
}),
});
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/dotted_lines.add",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p1",
"manager_id": "p7",
"valid_from": "2026-10-04",
"last_day": "2026-12-31",
"note": "Platform project",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "dl1",
"person": {
"id": "p1",
"name": "Ana Ferreira",
"title": "Engineer",
"photo_url": null
},
"manager": {
"id": "p7",
"name": "João Pereira",
"title": "Sales Lead",
"photo_url": null
},
"valid_from": "2026-10-04",
"last_day": "2026-12-31",
"note": "Platform project"
}
}End a dotted-line manager#
POST/v1/org/dotted_lines.endWrite
Ends a dotted-line reporting line after last_day (inclusive; default today). A line that has not started by then is removed. Owners, admins and HR, and roles that edit the people they cover.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_dotted_lines_endon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
line_idstringrequiredlast_daystring
Returns
idstringrequiredremovedbooleanrequiredlast_daystring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/dotted_lines.end \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"line_id":"dl1","last_day":"2026-12-31"}'const res = await fetch('https://api.bizisy.com/v1/org/dotted_lines.end', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"line_id": "dl1",
"last_day": "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, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/dotted_lines.end",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"line_id": "dl1",
"last_day": "2026-12-31",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "dl1",
"removed": false,
"last_day": "2026-12-31"
}
}Mark someone as told about their last day#
POST/v1/org/people.mark_toldWrite
Records that a person has been told about their last day. A termination recorded with person_told false (the default for dismissals, redundancies, contracts not renewed, other and unrecorded leaving types) is kept from the person: they don't see the last day, why they leave, their offboarding tasks or the effect on their time off until they are marked told or the day passes. Marking them told shows them everything, starts their offboarding tasks and ends their time off booked after the last day. Owners, admins and HR, a custom role with People at Propose or more covering them, or anyone in their management chain; never about yourself. Already told: nothing changes (changed false). conflict when they have no last day ahead.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
org_people_mark_toldon 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_idstringrequired
Returns
personobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
last_daystringrequiredchangedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/people.mark_told \
-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.mark_told', {
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.mark_told",
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": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"last_day": "2026-11-30",
"changed": true
}
}Save a process for later#
POST/v1/org/drafts.saveWrite
Saves a process about people that is not finished yet, so anyone who may start it can carry on later in Bizisy (People → Saved for later) or through this API. process: hire, change_job, promote, move, leaving, probation, contract or rehire; person_ids: the person (none for a hire; one or more for a move); label: a short name shown in the list (e.g. "Ana Lima · Engineer"); data.input: the action's input as far as it is known, with the same field names (org_people_hire, org_people_change_job, org_people_promote, org_people_move, org_people_mark_leaving, org_people_contract_decide, org_people_rehire), so the web app opens it in that process's form. A process about one person keeps one saved draft per person (saving again replaces it); hires and moves keep many (draft_id replaces one). Kept until someone deletes it. Over an API key or MCP, private details and pay are refused (the person adds them in the app). Owners, admins and HR, and custom roles for the people they cover. In My workspace, a manager saves a proposal for someone in their team: process proposal, variant promote, move, resign or probation, data.input the proposal so far (org_people_promote, org_people_move, org_people_mark_leaving or org_people_probation_decide); it is private to them (HR sees it once sent), one per person and variant, at most ${MAX_PROPOSAL_DRAFTS}.
- Who can call it
- Manage key any Manage role
Me key anyone - Keys and apps
- Private details and pay are refused (the person adds them in the app).
- MCP tool
org_drafts_saveon 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
processstring (enum)requiredOne of:
hire,change_job,promote,move,leaving,probation,contract,rehire,proposal.variant"promote" | "move" | "resign" | "probation"Proposals only: what is proposed.
person_idsstring[]Up to 50 items.
labelstringrequired1–120 characters.
dataobjectrequireddraft_idstring
Returns
8 fields
idstringrequiredprocessstring (enum)requiredOne of:
hire,change_job,promote,move,leaving,probation,contract,rehire,proposal.variantstring | nullrequiredProposals: what is proposed (promote, move, resign or probation).
labelstringrequiredpeopleobject[]required2 fields
idstringrequirednamestringrequired
saved_byobjectrequired2 fields
user_idstringrequirednamestring | nullrequired
saved_atstringrequiredcreated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/drafts.save \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"process": "promote",
"person_ids": [
"p4"
],
"label": "Promotion of Lukas",
"data": {
"input": {
"person_id": "p4"
}
},
"draft_id": "d2"
}'const res = await fetch('https://api.bizisy.com/v1/org/drafts.save', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"process": "promote",
"person_ids": [
"p4"
],
"label": "Promotion of Lukas",
"data": {
"input": {
"person_id": "p4"
}
},
"draft_id": "d2"
}),
});
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/drafts.save",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"process": "promote",
"person_ids": [
"p4",
],
"label": "Promotion of Lukas",
"data": {
"input": {
"person_id": "p4",
},
},
"draft_id": "d2",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "d1",
"process": "promote",
"variant": null,
"label": "Promotion of Lukas",
"people": [],
"saved_by": {
"user_id": "usr6",
"name": "Marta Rocha"
},
"saved_at": "2026-10-08T15:00:00.000Z",
"created_at": "2026-10-07T10:00:00.000Z"
}
}List processes saved for later#
POST/v1/org/drafts.listRead
Lists the processes saved for later that you may carry on (newest first): what process, a short label, the people it is about, who saved it and when. Filter by process or person_id. Never the saved values (open one in the web app).
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
org_drafts_liston HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
processstring (enum)One of:
hire,change_job,promote,move,leaving,probation,contract,rehire,proposal.person_idstringvariant"promote" | "move" | "resign" | "probation"
Returns
An array of objects with 8 fields
An array of objects:
idstringrequiredprocessstring (enum)requiredOne of:
hire,change_job,promote,move,leaving,probation,contract,rehire,proposal.variantstring | nullrequiredProposals: what is proposed (promote, move, resign or probation).
labelstringrequiredpeopleobject[]required2 fields
idstringrequirednamestringrequired
saved_byobjectrequired2 fields
user_idstringrequirednamestring | nullrequired
saved_atstringrequiredcreated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/drafts.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"process":"hire"}'const res = await fetch('https://api.bizisy.com/v1/org/drafts.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"process": "hire"
}),
});
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/drafts.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"process": "hire",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"id": "d1",
"process": "hire",
"variant": null,
"label": "Ana Lima · Engineer",
"people": [],
"saved_by": {
"user_id": "usr6",
"name": "Marta Rocha"
},
"saved_at": "2026-10-08T15:00:00.000Z",
"created_at": "2026-10-07T10:00:00.000Z"
},
{
"id": "d2",
"process": "promote",
"variant": null,
"label": "Promotion of Lukas",
"people": [
{
"id": "p4",
"name": "Lukas Weber"
}
],
"saved_by": {
"user_id": "usr6",
"name": "Marta Rocha"
},
"saved_at": "2026-10-08T15:00:00.000Z",
"created_at": "2026-10-07T10:00:00.000Z"
}
]
}Open a process saved for later#
POST/v1/org/drafts.getRead
One saved draft with the values as they were saved (data.input: the action input so far). Over an API key or MCP, private details and pay are left out. To finish it, run the process's action with data.input completed, then delete the draft with org_drafts_delete.
- Who can call it
- Manage key any Manage role
Me key anyone - Keys and apps
- Private details and pay are left out.
- MCP tool
org_drafts_geton HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
draft_idstringrequired
Returns
9 fields
idstringrequiredprocessstring (enum)requiredOne of:
hire,change_job,promote,move,leaving,probation,contract,rehire,proposal.variantstring | nullrequiredProposals: what is proposed (promote, move, resign or probation).
labelstringrequiredpeopleobject[]required2 fields
idstringrequirednamestringrequired
saved_byobjectrequired2 fields
user_idstringrequirednamestring | nullrequired
saved_atstringrequiredcreated_atstringrequireddataobjectrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/drafts.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"draft_id":"d1"}'const res = await fetch('https://api.bizisy.com/v1/org/drafts.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"draft_id": "d1"
}),
});
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/drafts.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"draft_id": "d1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "d1",
"process": "hire",
"variant": null,
"label": "Ana Lima · Engineer",
"people": [],
"saved_by": {
"user_id": "usr6",
"name": "Marta Rocha"
},
"saved_at": "2026-10-08T15:00:00.000Z",
"created_at": "2026-10-07T10:00:00.000Z",
"data": {
"input": {
"given_name": "Ana",
"family_name": "Lima",
"title": "Engineer"
},
"form": {
"step": 1
}
}
}
}Delete a process saved for later#
POST/v1/org/drafts.deleteDestructive
Deletes a saved draft (finished, or no longer needed). Anyone who may carry it on may delete it.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
org_drafts_deleteon HR Assistant, My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
draft_idstringrequired
Returns
idstringrequireddeletedtruerequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/drafts.delete \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"draft_id":"d1"}'const res = await fetch('https://api.bizisy.com/v1/org/drafts.delete', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"draft_id": "d1"
}),
});
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/drafts.delete",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"draft_id": "d1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "d1",
"deleted": true
}
}Something missing or wrong on this page? Write to hello@bizisy.com.