API reference
Job titles
The job title catalog: titles grow as people type them; families, levels, merging duplicates and renaming.
17 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
List job titles#
POST/v1/org/titles.listRead
The job title catalog: every title people have (titles grow as people type them in hires, job changes, positions and imports). Filters: q (name or earlier wording), status (active by default, archived, merged or all), family_id, unreviewed (added by an AI, an import or an API key and not looked at by HR), unused (nobody holds it and no open position), duplicates (titles that look like another one). people counts who holds each title today; positions counts open roles. Owners, admins, HR and viewers; others use org_titles_search.
- Who can call it
- Manage key any Manage role
- MCP tool
org_titles_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
qstringUp to 120 characters.
status"active" | "archived" | "merged" | "all"Default
"active".family_idstringunreviewedbooleanunusedbooleanduplicatesboolean
Returns
An array of objects with 14 fields
An array of objects:
idstringrequirednamestringrequiredaliasesstring[]requiredfamilyobject | nullrequired"Function › Family", or just the function.
2 fields
idstringrequirednamestringrequired
track"ic" | "manager"requiredlevelobject | nullrequired3 fields
idstringrequirednamestringrequiredrankintegerrequired
descriptionstring | nullrequiredstatus"active" | "archived"requiredmerged_intoobject | nullrequiredMerged titles read as this one everywhere.
2 fields
idstringrequirednamestringrequired
reviewedbooleanrequiredFalse for titles added by an AI, an import or an API key that HR has not looked at yet.
created_via"app" | "ai" | "import" | "api"requiredcreated_atstringrequiredpeopleinteger | nullrequiredPeople whose job today has this title (null when the caller does not see counts).
positionsinteger | nullrequiredDraft, open and on-hold positions with this title.
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/titles.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "eng",
"status": "all",
"family_id": "f1",
"unreviewed": true,
"unused": false,
"duplicates": true
}'const res = await fetch('https://api.bizisy.com/v1/org/titles.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"q": "eng",
"status": "all",
"family_id": "f1",
"unreviewed": true,
"unused": false,
"duplicates": 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/titles.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"q": "eng",
"status": "all",
"family_id": "f1",
"unreviewed": True,
"unused": False,
"duplicates": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"id": "t1",
"name": "Back-end Engineer",
"aliases": [
"BE Developer"
],
"family": {
"id": "f1",
"name": "Technology › Engineering"
},
"track": "ic",
"level": {
"id": "l2",
"name": "Mid",
"rank": 2
},
"description": "Builds and runs the services behind the product.",
"status": "active",
"merged_into": null,
"reviewed": true,
"created_via": "app",
"created_at": "2026-10-07T10:00:00.000Z",
"people": 6,
"positions": 1
},
{
"id": "t2",
"name": "Backend Engineer",
"aliases": [],
"family": null,
"track": null,
"level": null,
"description": "Builds and runs the services behind the product.",
"status": "active",
"merged_into": null,
"reviewed": false,
"created_via": "ai",
"created_at": "2026-10-07T10:00:00.000Z",
"people": 1,
"positions": 0
}
]
}Search job titles#
POST/v1/org/titles.searchRead
Finds catalog job titles by name or earlier wording (q), best matches first, at most 10: id, name, family and level. exact is the title the text already means (same words in any spelling), or null; similar lists titles that look the same when it would be new. Anyone in the company (titles show in the directory).
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
org_titles_searchon HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
qstringUp to 120 characters. Default
"".
Returns
itemsobject[]required7 fields
idstringrequirednamestringrequiredfamilystring | nullrequiredlevelstring | nullrequiredtrack"ic" | "manager"requiredlevel_rankinteger | nullrequiredfamily_idstring | nullrequired
exactobject | nullrequired2 fields
idstringrequirednamestringrequired
similarobject[]required2 fields
idstringrequirednamestringrequired
can_addbooleanrequiredWhether the caller may add a title that is not in the catalog by typing it.
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/titles.search \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"q":"back"}'const res = await fetch('https://api.bizisy.com/v1/org/titles.search', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"q": "back"
}),
});
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/titles.search",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"q": "back",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"items": [
{
"id": "t1",
"name": "Back-end Engineer",
"family": "Technology › Engineering",
"family_id": "f1",
"level": "Mid",
"track": "ic",
"level_rank": 2
}
],
"exact": null,
"similar": [
{
"id": "t1",
"name": "Back-end Engineer"
}
],
"can_add": true
}
}Get a job title#
POST/v1/org/titles.getRead
One catalog title with its earlier wordings, family, track, level, description and counts. Owners, admins, HR and viewers.
- Who can call it
- Manage key any Manage role
- MCP tool
org_titles_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
title_idstringrequired
Returns
14 fields
idstringrequirednamestringrequiredaliasesstring[]requiredfamilyobject | nullrequired"Function › Family", or just the function.
2 fields
idstringrequirednamestringrequired
track"ic" | "manager"requiredlevelobject | nullrequired3 fields
idstringrequirednamestringrequiredrankintegerrequired
descriptionstring | nullrequiredstatus"active" | "archived"requiredmerged_intoobject | nullrequiredMerged titles read as this one everywhere.
2 fields
idstringrequirednamestringrequired
reviewedbooleanrequiredFalse for titles added by an AI, an import or an API key that HR has not looked at yet.
created_via"app" | "ai" | "import" | "api"requiredcreated_atstringrequiredpeopleinteger | nullrequiredPeople whose job today has this title (null when the caller does not see counts).
positionsinteger | nullrequiredDraft, open and on-hold positions with this title.
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/titles.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title_id":"t1"}'const res = await fetch('https://api.bizisy.com/v1/org/titles.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"title_id": "t1"
}),
});
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/titles.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"title_id": "t1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "t1",
"name": "Back-end Engineer",
"aliases": [
"BE Developer"
],
"family": {
"id": "f1",
"name": "Technology › Engineering"
},
"track": "ic",
"level": {
"id": "l2",
"name": "Mid",
"rank": 2
},
"description": "Builds and runs the services behind the product.",
"status": "active",
"merged_into": null,
"reviewed": true,
"created_via": "app",
"created_at": "2026-10-07T10:00:00.000Z",
"people": 6,
"positions": 1
}
}Add a job title#
POST/v1/org/titles.createWrite
Adds a title to the catalog (titles are also added by themselves when someone types a new one in a hire or job change). name (1–120), optional family_id (org_title_families_list), track (ic or manager), level_id (org_title_levels_list, same track) and description. A title with the same words as an existing one is a conflict (details.id). similar lists titles that look the same. Owners, admins and HR; API keys and AI connections too, unless Settings say only HR adds titles. At most 500 active titles.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Refused when the company lets only HR add job titles (org.titles.settings.update).
- MCP tool
org_titles_createon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
namestringrequired1–120 characters.
family_idstring | nulltrack"ic" | "manager"level_idstring | nulldescriptionstring | nullWhat the role does (shown with the title).
Up to 4000 characters.
Returns
15 fields
idstringrequirednamestringrequiredaliasesstring[]requiredfamilyobject | nullrequired"Function › Family", or just the function.
2 fields
idstringrequirednamestringrequired
track"ic" | "manager"requiredlevelobject | nullrequired3 fields
idstringrequirednamestringrequiredrankintegerrequired
descriptionstring | nullrequiredstatus"active" | "archived"requiredmerged_intoobject | nullrequiredMerged titles read as this one everywhere.
2 fields
idstringrequirednamestringrequired
reviewedbooleanrequiredFalse for titles added by an AI, an import or an API key that HR has not looked at yet.
created_via"app" | "ai" | "import" | "api"requiredcreated_atstringrequiredpeopleinteger | nullrequiredPeople whose job today has this title (null when the caller does not see counts).
positionsinteger | nullrequiredDraft, open and on-hold positions with this title.
similarobject[]required3 fields
idstringrequirednamestringrequiredpeopleintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/titles.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Senior Data Analyst",
"family_id": "f1",
"track": "ic",
"level_id": "l3",
"description": "Turns data into decisions."
}'const res = await fetch('https://api.bizisy.com/v1/org/titles.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"name": "Senior Data Analyst",
"family_id": "f1",
"track": "ic",
"level_id": "l3",
"description": "Turns data into decisions."
}),
});
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/titles.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "Senior Data Analyst",
"family_id": "f1",
"track": "ic",
"level_id": "l3",
"description": "Turns data into decisions.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "t1",
"name": "Senior Data Analyst",
"aliases": [
"BE Developer"
],
"family": {
"id": "f1",
"name": "Technology › Engineering"
},
"track": "ic",
"level": {
"id": "l2",
"name": "Mid",
"rank": 2
},
"description": "Turns data into decisions.",
"status": "active",
"merged_into": null,
"reviewed": true,
"created_via": "app",
"created_at": "2026-10-07T10:00:00.000Z",
"people": 6,
"positions": 1,
"similar": [
{
"id": "t2",
"name": "Backend Engineer",
"people": 1
}
]
}
}Change job titles#
POST/v1/org/titles.updateWrite
Changes one title (title_id) or several (ids, for family, track, level and reviewed). name fixes the wording everywhere, history included (the same job): the old wording becomes an earlier wording that still matches. To give people a different title from a date, change their jobs instead (org_changes_draft with retitle). Also family_id, track, level_id, description (null clears), reviewed. Owners, admins and HR; API keys and AI connections too.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_titles_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
title_idstringidsstring[]1–200 items.
namestring1–120 characters.
reviewedbooleanfamily_idstring | nulltrack"ic" | "manager"level_idstring | nulldescriptionstring | nullWhat the role does (shown with the title).
Up to 4000 characters.
Returns
An array of objects with 14 fields
An array of objects:
idstringrequirednamestringrequiredaliasesstring[]requiredfamilyobject | nullrequired"Function › Family", or just the function.
2 fields
idstringrequirednamestringrequired
track"ic" | "manager"requiredlevelobject | nullrequired3 fields
idstringrequirednamestringrequiredrankintegerrequired
descriptionstring | nullrequiredstatus"active" | "archived"requiredmerged_intoobject | nullrequiredMerged titles read as this one everywhere.
2 fields
idstringrequirednamestringrequired
reviewedbooleanrequiredFalse for titles added by an AI, an import or an API key that HR has not looked at yet.
created_via"app" | "ai" | "import" | "api"requiredcreated_atstringrequiredpeopleinteger | nullrequiredPeople whose job today has this title (null when the caller does not see counts).
positionsinteger | nullrequiredDraft, open and on-hold positions with this title.
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/titles.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"ids":["t1","t2"],"family_id":null,"reviewed":true}'const res = await fetch('https://api.bizisy.com/v1/org/titles.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"ids": [
"t1",
"t2"
],
"family_id": null,
"reviewed": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/titles.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"ids": [
"t1",
"t2",
],
"family_id": None,
"reviewed": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"id": "t1",
"name": "Back-end Engineer",
"aliases": [
"BE Developer"
],
"family": {
"id": "f1",
"name": "Technology › Engineering"
},
"track": "ic",
"level": {
"id": "l2",
"name": "Mid",
"rank": 2
},
"description": "Builds and runs the services behind the product.",
"status": "active",
"merged_into": null,
"reviewed": true,
"created_via": "app",
"created_at": "2026-10-07T10:00:00.000Z",
"people": 6,
"positions": 1
}
]
}Merge job titles#
POST/v1/org/titles.mergeWrite
Merges duplicate titles (from_ids) into one (into_id, an active title): everyone holding them, open positions and pending requests show the surviving title from now on, history included, and their names become earlier wordings of it that keep matching. Nothing about anyone's job changes otherwise. preview.summary says how many people and positions it touches. Owners, admins and HR; API keys and AI connections too. Use dry_run first.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_titles_mergeon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
from_idsstring[]required1–200 items.
into_idstringrequired
Returns
titleobjectrequired14 fields
idstringrequirednamestringrequiredaliasesstring[]requiredfamilyobject | nullrequired"Function › Family", or just the function.
2 fields
idstringrequirednamestringrequired
track"ic" | "manager"requiredlevelobject | nullrequired3 fields
idstringrequirednamestringrequiredrankintegerrequired
descriptionstring | nullrequiredstatus"active" | "archived"requiredmerged_intoobject | nullrequiredMerged titles read as this one everywhere.
2 fields
idstringrequirednamestringrequired
reviewedbooleanrequiredFalse for titles added by an AI, an import or an API key that HR has not looked at yet.
created_via"app" | "ai" | "import" | "api"requiredcreated_atstringrequiredpeopleinteger | nullrequiredPeople whose job today has this title (null when the caller does not see counts).
positionsinteger | nullrequiredDraft, open and on-hold positions with this title.
previewobjectrequired1 field
summarystringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/titles.merge \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"from_ids":["t2"],"into_id":"t1"}'const res = await fetch('https://api.bizisy.com/v1/org/titles.merge', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"from_ids": [
"t2"
],
"into_id": "t1"
}),
});
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/titles.merge",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"from_ids": [
"t2",
],
"into_id": "t1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"title": {
"id": "t1",
"name": "Back-end Engineer",
"aliases": [
"BE Developer"
],
"family": {
"id": "f1",
"name": "Technology › Engineering"
},
"track": "ic",
"level": {
"id": "l2",
"name": "Mid",
"rank": 2
},
"description": "Builds and runs the services behind the product.",
"status": "active",
"merged_into": null,
"reviewed": true,
"created_via": "app",
"created_at": "2026-10-07T10:00:00.000Z",
"people": 6,
"positions": 1
},
"preview": {
"summary": "1 person and 0 open positions will show Back-end Engineer. Backend Engineer become earlier wordings of it."
}
}
}Archive job titles#
POST/v1/org/titles.archiveWrite
Archives titles (ids): they can no longer be given to anyone, while people who hold them and history keep them. Restore with org_titles_restore. Owners, admins and HR; API keys and AI connections too.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_titles_archiveon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
idsstring[]required1–200 items.
Returns
An array of objects with 14 fields
An array of objects:
idstringrequirednamestringrequiredaliasesstring[]requiredfamilyobject | nullrequired"Function › Family", or just the function.
2 fields
idstringrequirednamestringrequired
track"ic" | "manager"requiredlevelobject | nullrequired3 fields
idstringrequirednamestringrequiredrankintegerrequired
descriptionstring | nullrequiredstatus"active" | "archived"requiredmerged_intoobject | nullrequiredMerged titles read as this one everywhere.
2 fields
idstringrequirednamestringrequired
reviewedbooleanrequiredFalse for titles added by an AI, an import or an API key that HR has not looked at yet.
created_via"app" | "ai" | "import" | "api"requiredcreated_atstringrequiredpeopleinteger | nullrequiredPeople whose job today has this title (null when the caller does not see counts).
positionsinteger | nullrequiredDraft, open and on-hold positions with this title.
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/titles.archive \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"ids":["t2"]}'const res = await fetch('https://api.bizisy.com/v1/org/titles.archive', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"ids": [
"t2"
]
}),
});
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/titles.archive",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"ids": [
"t2",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"id": "t1",
"name": "Back-end Engineer",
"aliases": [
"BE Developer"
],
"family": {
"id": "f1",
"name": "Technology › Engineering"
},
"track": "ic",
"level": {
"id": "l2",
"name": "Mid",
"rank": 2
},
"description": "Builds and runs the services behind the product.",
"status": "archived",
"merged_into": null,
"reviewed": true,
"created_via": "app",
"created_at": "2026-10-07T10:00:00.000Z",
"people": 6,
"positions": 1
}
]
}Restore job titles#
POST/v1/org/titles.restoreWrite
Makes archived titles (ids) available again. A merged title cannot be restored. Owners, admins and HR; API keys and AI connections too.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_titles_restoreon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
idsstring[]required1–200 items.
Returns
An array of objects with 14 fields
An array of objects:
idstringrequirednamestringrequiredaliasesstring[]requiredfamilyobject | nullrequired"Function › Family", or just the function.
2 fields
idstringrequirednamestringrequired
track"ic" | "manager"requiredlevelobject | nullrequired3 fields
idstringrequirednamestringrequiredrankintegerrequired
descriptionstring | nullrequiredstatus"active" | "archived"requiredmerged_intoobject | nullrequiredMerged titles read as this one everywhere.
2 fields
idstringrequirednamestringrequired
reviewedbooleanrequiredFalse for titles added by an AI, an import or an API key that HR has not looked at yet.
created_via"app" | "ai" | "import" | "api"requiredcreated_atstringrequiredpeopleinteger | nullrequiredPeople whose job today has this title (null when the caller does not see counts).
positionsinteger | nullrequiredDraft, open and on-hold positions with this title.
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/titles.restore \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"ids":["t2"]}'const res = await fetch('https://api.bizisy.com/v1/org/titles.restore', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"ids": [
"t2"
]
}),
});
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/titles.restore",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"ids": [
"t2",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"id": "t1",
"name": "Back-end Engineer",
"aliases": [
"BE Developer"
],
"family": {
"id": "f1",
"name": "Technology › Engineering"
},
"track": "ic",
"level": {
"id": "l2",
"name": "Mid",
"rank": 2
},
"description": "Builds and runs the services behind the product.",
"status": "active",
"merged_into": null,
"reviewed": true,
"created_via": "app",
"created_at": "2026-10-07T10:00:00.000Z",
"people": 6,
"positions": 1
}
]
}Suggest job title clean-ups#
POST/v1/org/titles.suggestionsRead
What to tidy in the catalog: clusters of titles that probably mean the same job (merge them with org_titles_merge, keeping the one most people hold), and titles whose words name a level (e.g. "Senior") while they have none. To suggest families and levels for every title, read org_titles_list and propose the changes as a draft for HR (org_changes_draft with title_update operations). Owners, admins, HR and viewers.
- Who can call it
- Manage key any Manage role
- MCP tool
org_titles_suggestionson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
clustersobject[]required3 fields
titlesobject[]required3 fields
idstringrequirednamestringrequiredpeopleintegerrequired
peopleintegerrequiredkeepobjectrequired2 fields
idstringrequirednamestringrequired
level_wordsobject[]required3 fields
idstringrequirednamestringrequiredwordstringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/titles.suggestions \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/titles.suggestions', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/titles.suggestions",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"clusters": [
{
"titles": [
{
"id": "t1",
"name": "Back-end Engineer",
"people": 6
},
{
"id": "t2",
"name": "Backend Engineer",
"people": 1
}
],
"people": 7,
"keep": {
"id": "t1",
"name": "Back-end Engineer"
}
}
],
"level_words": [
{
"id": "t3",
"name": "Senior Analyst",
"word": "senior"
}
]
}
}Keep job titles apart#
POST/v1/org/titles.keep_apartWrite
Says that titles (ids, 2–20) are different jobs, however alike their words: they are no longer suggested as duplicates of each other (org_titles_suggestions, the duplicates filter, Home). Owners, admins and HR; API keys and AI connections too.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_titles_keep_aparton HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
idsstring[]required2–20 items.
Returns
An array of objects with 14 fields
An array of objects:
idstringrequirednamestringrequiredaliasesstring[]requiredfamilyobject | nullrequired"Function › Family", or just the function.
2 fields
idstringrequirednamestringrequired
track"ic" | "manager"requiredlevelobject | nullrequired3 fields
idstringrequirednamestringrequiredrankintegerrequired
descriptionstring | nullrequiredstatus"active" | "archived"requiredmerged_intoobject | nullrequiredMerged titles read as this one everywhere.
2 fields
idstringrequirednamestringrequired
reviewedbooleanrequiredFalse for titles added by an AI, an import or an API key that HR has not looked at yet.
created_via"app" | "ai" | "import" | "api"requiredcreated_atstringrequiredpeopleinteger | nullrequiredPeople whose job today has this title (null when the caller does not see counts).
positionsinteger | nullrequiredDraft, open and on-hold positions with this title.
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/titles.keep_apart \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"ids":["t1","t2"]}'const res = await fetch('https://api.bizisy.com/v1/org/titles.keep_apart', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"ids": [
"t1",
"t2"
]
}),
});
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/titles.keep_apart",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"ids": [
"t1",
"t2",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"id": "t1",
"name": "Back-end Engineer",
"aliases": [
"BE Developer"
],
"family": {
"id": "f1",
"name": "Technology › Engineering"
},
"track": "ic",
"level": {
"id": "l2",
"name": "Mid",
"rank": 2
},
"description": "Builds and runs the services behind the product.",
"status": "active",
"merged_into": null,
"reviewed": true,
"created_via": "app",
"created_at": "2026-10-07T10:00:00.000Z",
"people": 6,
"positions": 1
}
]
}Get job title settings#
POST/v1/org/titles.settings.getRead
Who may add a job title by typing it. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_titles_settings_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
new_titles_by"anyone" | "hr"required"anyone": whoever may change a job may add a title by typing it; "hr": only owners, admins and HR signed in to Bizisy (others pick from the catalog; a manager's proposal still carries a new title for HR to decide).
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/titles.settings.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/titles.settings.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/titles.settings.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"new_titles_by": "anyone"
}
}Change job title settings#
POST/v1/org/titles.settings.updateWrite
new_titles_by: "anyone" (whoever may change a job may add a title by typing it; the default) or "hr" (only owners, admins and HR signed in to Bizisy; everyone else, API keys and AI connections included, picks from the catalog). Owners, admins and HR, in the app only.
- Web app only
- Refused for API keys and connected apps. Who may add job titles is set in the app only, so an assistant can never widen it.
- MCP tool
org_titles_settings_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
new_titles_by"anyone" | "hr"required"anyone": whoever may change a job may add a title by typing it; "hr": only owners, admins and HR signed in to Bizisy (others pick from the catalog; a manager's proposal still carries a new title for HR to decide).
Returns
new_titles_by"anyone" | "hr"required"anyone": whoever may change a job may add a title by typing it; "hr": only owners, admins and HR signed in to Bizisy (others pick from the catalog; a manager's proposal still carries a new title for HR to decide).
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/titles.settings.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"new_titles_by":"hr"}'const res = await fetch('https://api.bizisy.com/v1/org/titles.settings.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"new_titles_by": "hr"
}),
});
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/titles.settings.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"new_titles_by": "hr",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"new_titles_by": "hr"
}
}List job families#
POST/v1/org/title_families.listRead
Functions (parent_id null, e.g. Technology) and the families in them (e.g. Engineering), with how many active titles each holds. Owners, admins, HR and viewers.
- Who can call it
- Manage key any Manage role
- MCP tool
org_title_families_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
An array of objects:
idstringrequirednamestringrequiredparent_idstring | nullrequiredarchivedbooleanrequiredtitlesintegerrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/title_families.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/title_families.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/title_families.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"id": "f0",
"name": "Technology",
"parent_id": null,
"archived": false,
"titles": 0
},
{
"id": "f1",
"name": "Engineering",
"parent_id": "f0",
"archived": false,
"titles": 4
}
]
}Add a job family#
POST/v1/org/title_families.createWrite
Adds a function (no parent_id) or a family inside a function (parent_id: a function). Two levels only. name 1–80, unique within its parent. At most 200. Owners, admins and HR; API keys and AI connections too.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_title_families_createon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
namestringrequired1–80 characters.
parent_idstring | null
Returns
idstringrequirednamestringrequiredparent_idstring | nullrequiredarchivedbooleanrequiredtitlesintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/title_families.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"name":"Engineering","parent_id":"f0"}'const res = await fetch('https://api.bizisy.com/v1/org/title_families.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"name": "Engineering",
"parent_id": "f0"
}),
});
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/title_families.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "Engineering",
"parent_id": "f0",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "f1",
"name": "Engineering",
"parent_id": "f0",
"archived": false,
"titles": 0
}
}Change a job family#
POST/v1/org/title_families.updateWrite
Renames a function or family (name), or archives or restores it (archived; titles keep it, it can no longer be picked). Owners, admins and HR; API keys and AI connections too.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_title_families_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
family_idstringrequirednamestring1–80 characters.
archivedboolean
Returns
idstringrequirednamestringrequiredparent_idstring | nullrequiredarchivedbooleanrequiredtitlesintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/title_families.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"family_id":"f1","name":"Software Engineering","archived":false}'const res = await fetch('https://api.bizisy.com/v1/org/title_families.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"family_id": "f1",
"name": "Software Engineering",
"archived": false
}),
});
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/title_families.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"family_id": "f1",
"name": "Software Engineering",
"archived": False,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "f1",
"name": "Software Engineering",
"parent_id": "f0",
"archived": false,
"titles": 4
}
}List job levels#
POST/v1/org/title_levels.listRead
The level ladders: ic (individual contributors) and manager, each ordered by rank (1 = most junior). Owners, admins, HR and viewers.
- Who can call it
- Manage key any Manage role
- MCP tool
org_title_levels_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
An array of objects:
idstringrequiredtrack"ic" | "manager"requiredrankintegerrequirednamestringrequiredarchivedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/title_levels.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/title_levels.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/title_levels.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"id": "l1",
"track": "ic",
"rank": 1,
"name": "Junior",
"archived": false
},
{
"id": "l2",
"track": "ic",
"rank": 2,
"name": "Mid",
"archived": false
}
]
}Set a level ladder#
POST/v1/org/title_levels.setWrite
Replaces one track's ladder (track: ic or manager) with levels in order, most junior first: [{ id? (keep an existing level), name }]. Existing levels left out are archived (titles keep them until changed). At most 20 per track. Owners, admins and HR; API keys and AI connections too.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_title_levels_seton HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
track"ic" | "manager"requiredlevelsobject[]requiredUp to 20 items.
2 fields
idstringnamestringrequired1–40 characters.
Returns
An array of objects:
idstringrequiredtrack"ic" | "manager"requiredrankintegerrequirednamestringrequiredarchivedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/title_levels.set \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"track": "ic",
"levels": [
{
"id": "l1",
"name": "Junior"
},
{
"name": "Mid"
},
{
"name": "Senior"
}
]
}'const res = await fetch('https://api.bizisy.com/v1/org/title_levels.set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"track": "ic",
"levels": [
{
"id": "l1",
"name": "Junior"
},
{
"name": "Mid"
},
{
"name": "Senior"
}
]
}),
});
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/title_levels.set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"track": "ic",
"levels": [
{
"id": "l1",
"name": "Junior",
},
{
"name": "Mid",
},
{
"name": "Senior",
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"id": "l1",
"track": "ic",
"rank": 1,
"name": "Junior",
"archived": false
},
{
"id": "l4",
"track": "ic",
"rank": 2,
"name": "Mid",
"archived": false
}
]
}Something missing or wrong on this page? Write to hello@bizisy.com.