Skip to content

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_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • qstring

    Up to 120 characters.

  • status"active" | "archived" | "merged" | "all"

    Default "active".

  • family_idstring
  • unreviewedboolean
  • unusedboolean
  • duplicatesboolean

Returns

An array of objects with 14 fields

An array of objects:

  • idstringrequired
  • namestringrequired
  • aliasesstring[]required
  • familyobject | nullrequired

    "Function › Family", or just the function.

    2 fields
    • idstringrequired
    • namestringrequired
  • track"ic" | "manager"required
  • levelobject | nullrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • rankintegerrequired
  • descriptionstring | nullrequired
  • status"active" | "archived"required
  • merged_intoobject | nullrequired

    Merged titles read as this one everywhere.

    2 fields
    • idstringrequired
    • namestringrequired
  • reviewedbooleanrequired

    False 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"required
  • created_atstringrequired
  • peopleinteger | nullrequired

    People whose job today has this title (null when the caller does not see counts).

  • positionsinteger | nullrequired

    Draft, open and on-hold positions with this title.

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
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
}'
Response
{
  "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_search on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • qstring

    Up to 120 characters. Default "".

Returns

  • itemsobject[]required
    7 fields
    • idstringrequired
    • namestringrequired
    • familystring | nullrequired
    • levelstring | nullrequired
    • track"ic" | "manager"required
    • level_rankinteger | nullrequired
    • family_idstring | nullrequired
  • exactobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • similarobject[]required
    2 fields
    • idstringrequired
    • namestringrequired
  • can_addbooleanrequired

    Whether 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
curl https://api.bizisy.com/v1/org/titles.search \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"back"}'
Response
{
  "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_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • title_idstringrequired

Returns

14 fields
  • idstringrequired
  • namestringrequired
  • aliasesstring[]required
  • familyobject | nullrequired

    "Function › Family", or just the function.

    2 fields
    • idstringrequired
    • namestringrequired
  • track"ic" | "manager"required
  • levelobject | nullrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • rankintegerrequired
  • descriptionstring | nullrequired
  • status"active" | "archived"required
  • merged_intoobject | nullrequired

    Merged titles read as this one everywhere.

    2 fields
    • idstringrequired
    • namestringrequired
  • reviewedbooleanrequired

    False 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"required
  • created_atstringrequired
  • peopleinteger | nullrequired

    People whose job today has this title (null when the caller does not see counts).

  • positionsinteger | nullrequired

    Draft, open and on-hold positions with this title.

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/titles.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title_id":"t1"}'
Response
{
  "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_create on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • namestringrequired

    1–120 characters.

  • family_idstring | null
  • track"ic" | "manager"
  • level_idstring | null
  • descriptionstring | null

    What the role does (shown with the title).

    Up to 4000 characters.

Returns

15 fields
  • idstringrequired
  • namestringrequired
  • aliasesstring[]required
  • familyobject | nullrequired

    "Function › Family", or just the function.

    2 fields
    • idstringrequired
    • namestringrequired
  • track"ic" | "manager"required
  • levelobject | nullrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • rankintegerrequired
  • descriptionstring | nullrequired
  • status"active" | "archived"required
  • merged_intoobject | nullrequired

    Merged titles read as this one everywhere.

    2 fields
    • idstringrequired
    • namestringrequired
  • reviewedbooleanrequired

    False 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"required
  • created_atstringrequired
  • peopleinteger | nullrequired

    People whose job today has this title (null when the caller does not see counts).

  • positionsinteger | nullrequired

    Draft, open and on-hold positions with this title.

  • similarobject[]required
    3 fields
    • idstringrequired
    • namestringrequired
    • peopleintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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."
}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • title_idstring
  • idsstring[]

    1–200 items.

  • namestring

    1–120 characters.

  • reviewedboolean
  • family_idstring | null
  • track"ic" | "manager"
  • level_idstring | null
  • descriptionstring | null

    What the role does (shown with the title).

    Up to 4000 characters.

Returns

An array of objects with 14 fields

An array of objects:

  • idstringrequired
  • namestringrequired
  • aliasesstring[]required
  • familyobject | nullrequired

    "Function › Family", or just the function.

    2 fields
    • idstringrequired
    • namestringrequired
  • track"ic" | "manager"required
  • levelobject | nullrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • rankintegerrequired
  • descriptionstring | nullrequired
  • status"active" | "archived"required
  • merged_intoobject | nullrequired

    Merged titles read as this one everywhere.

    2 fields
    • idstringrequired
    • namestringrequired
  • reviewedbooleanrequired

    False 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"required
  • created_atstringrequired
  • peopleinteger | nullrequired

    People whose job today has this title (null when the caller does not see counts).

  • positionsinteger | nullrequired

    Draft, open and on-hold positions with this title.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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}'
Response
{
  "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_merge on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • from_idsstring[]required

    1–200 items.

  • into_idstringrequired

Returns

  • titleobjectrequired
    14 fields
    • idstringrequired
    • namestringrequired
    • aliasesstring[]required
    • familyobject | nullrequired

      "Function › Family", or just the function.

      2 fields
      • idstringrequired
      • namestringrequired
    • track"ic" | "manager"required
    • levelobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • rankintegerrequired
    • descriptionstring | nullrequired
    • status"active" | "archived"required
    • merged_intoobject | nullrequired

      Merged titles read as this one everywhere.

      2 fields
      • idstringrequired
      • namestringrequired
    • reviewedbooleanrequired

      False 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"required
    • created_atstringrequired
    • peopleinteger | nullrequired

      People whose job today has this title (null when the caller does not see counts).

    • positionsinteger | nullrequired

      Draft, open and on-hold positions with this title.

  • previewobjectrequired
    1 field
    • summarystringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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"}'
Response
{
  "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_archive on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • idsstring[]required

    1–200 items.

Returns

An array of objects with 14 fields

An array of objects:

  • idstringrequired
  • namestringrequired
  • aliasesstring[]required
  • familyobject | nullrequired

    "Function › Family", or just the function.

    2 fields
    • idstringrequired
    • namestringrequired
  • track"ic" | "manager"required
  • levelobject | nullrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • rankintegerrequired
  • descriptionstring | nullrequired
  • status"active" | "archived"required
  • merged_intoobject | nullrequired

    Merged titles read as this one everywhere.

    2 fields
    • idstringrequired
    • namestringrequired
  • reviewedbooleanrequired

    False 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"required
  • created_atstringrequired
  • peopleinteger | nullrequired

    People whose job today has this title (null when the caller does not see counts).

  • positionsinteger | nullrequired

    Draft, open and on-hold positions with this title.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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"]}'
Response
{
  "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_restore on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • idsstring[]required

    1–200 items.

Returns

An array of objects with 14 fields

An array of objects:

  • idstringrequired
  • namestringrequired
  • aliasesstring[]required
  • familyobject | nullrequired

    "Function › Family", or just the function.

    2 fields
    • idstringrequired
    • namestringrequired
  • track"ic" | "manager"required
  • levelobject | nullrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • rankintegerrequired
  • descriptionstring | nullrequired
  • status"active" | "archived"required
  • merged_intoobject | nullrequired

    Merged titles read as this one everywhere.

    2 fields
    • idstringrequired
    • namestringrequired
  • reviewedbooleanrequired

    False 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"required
  • created_atstringrequired
  • peopleinteger | nullrequired

    People whose job today has this title (null when the caller does not see counts).

  • positionsinteger | nullrequired

    Draft, open and on-hold positions with this title.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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"]}'
Response
{
  "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_suggestions on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • clustersobject[]required
    3 fields
    • titlesobject[]required
      3 fields
      • idstringrequired
      • namestringrequired
      • peopleintegerrequired
    • peopleintegerrequired
    • keepobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
  • level_wordsobject[]required
    3 fields
    • idstringrequired
    • namestringrequired
    • wordstringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/titles.suggestions \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_apart on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • idsstring[]required

    2–20 items.

Returns

An array of objects with 14 fields

An array of objects:

  • idstringrequired
  • namestringrequired
  • aliasesstring[]required
  • familyobject | nullrequired

    "Function › Family", or just the function.

    2 fields
    • idstringrequired
    • namestringrequired
  • track"ic" | "manager"required
  • levelobject | nullrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • rankintegerrequired
  • descriptionstring | nullrequired
  • status"active" | "archived"required
  • merged_intoobject | nullrequired

    Merged titles read as this one everywhere.

    2 fields
    • idstringrequired
    • namestringrequired
  • reviewedbooleanrequired

    False 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"required
  • created_atstringrequired
  • peopleinteger | nullrequired

    People whose job today has this title (null when the caller does not see counts).

  • positionsinteger | nullrequired

    Draft, open and on-hold positions with this title.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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"]}'
Response
{
  "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_get on HR Assistant
Method
POST with a JSON body, or GET with 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
curl https://api.bizisy.com/v1/org/titles.settings.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs 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
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"}'
Response
{
  "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_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

An array of objects:

  • idstringrequired
  • namestringrequired
  • parent_idstring | nullrequired
  • archivedbooleanrequired
  • titlesintegerrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/title_families.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_create on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • namestringrequired

    1–80 characters.

  • parent_idstring | null

Returns

  • idstringrequired
  • namestringrequired
  • parent_idstring | nullrequired
  • archivedbooleanrequired
  • titlesintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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"}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • family_idstringrequired
  • namestring

    1–80 characters.

  • archivedboolean

Returns

  • idstringrequired
  • namestringrequired
  • parent_idstring | nullrequired
  • archivedbooleanrequired
  • titlesintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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}'
Response
{
  "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_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

An array of objects:

  • idstringrequired
  • track"ic" | "manager"required
  • rankintegerrequired
  • namestringrequired
  • archivedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/title_levels.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_set on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • track"ic" | "manager"required
  • levelsobject[]required

    Up to 20 items.

    2 fields
    • idstring
    • namestringrequired

      1–40 characters.

Returns

An array of objects:

  • idstringrequired
  • track"ic" | "manager"required
  • rankintegerrequired
  • namestringrequired
  • archivedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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"
    }
  ]
}'
Response
{
  "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.

Developer docs