Skip to content

API reference

Career paths

Paths between job titles (add, change, remove, suggest the next level), a person's own career (current title, skill gaps, suggested courses, open internal jobs) and career interest (said in the app only).

9 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.

List career paths#

POST/v1/talent/paths.listRead

Career paths between catalog job titles (from → to, kind promotion, lateral or specialist, typical months in the starting title, a note), with the skills each target title requires. Filters: family_id (the starting title's family; "none" for titles without one), title_id (paths starting from it). families counts paths per family; titles lists active titles for pickers (owners, admins, HR only). Family and level names show only to owners, admins, HR and viewers. Up to 200 paths per family and 2,000 in all. Everyone but viewers; API keys and AI assistants may read (no personal data).

Who can call it
Manage key owner admin hr
Me key owner admin hr member
MCP tool
talent_paths_list on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • family_idstring

    1–200 characters.

  • title_idstring

    1–200 characters.

Returns

  • itemsobject[]required
    9 fields
    • idstringrequired
    • fromobjectrequired
      5 fields
      • idstringrequired
      • namestringrequired
      • familystring | nullrequired

        Owners, admins, HR and viewers only (job architecture); null for others.

      • levelstring | nullrequired

        As family.

      • activebooleanrequired

        False when the title was archived (the path no longer shows in Me).

    • toobjectrequired
      5 fields
      • idstringrequired
      • namestringrequired
      • familystring | nullrequired

        Owners, admins, HR and viewers only (job architecture); null for others.

      • levelstring | nullrequired

        As family.

      • activebooleanrequired

        False when the title was archived (the path no longer shows in Me).

    • kind"promotion" | "lateral" | "specialist"required
    • typical_monthsinteger | nullrequired
    • notestring | nullrequired
    • requiredobject[]required

      Skills the target title requires (W1 skills framework), read only here.

      3 fields
      • skill_idstringrequired
      • namestringrequired
      • levelintegerrequired
    • created_atstringrequired
    • updated_atstringrequired
  • familiesobject[]required
    3 fields
    • idstring | nullrequired
    • namestring | nullrequired
    • pathsintegerrequired
  • titlesobject[]required
    7 fields
    • idstringrequired
    • namestringrequired
    • family_idstring | nullrequired
    • familystring | nullrequired
    • levelstring | nullrequired
    • level_rankinteger | nullrequired
    • track"ic" | "manager"required
  • limitsobjectrequired
    3 fields
    • per_familyintegerrequired
    • totalintegerrequired
    • usedintegerrequired
  • can_editbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/paths.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"family_id":"f1"}'
Response
{
  "data": {
    "items": [
      {
        "id": "t1:t2",
        "from": {
          "id": "t1",
          "name": "Customer care agent",
          "family": "Customer care",
          "level": "Junior",
          "active": true
        },
        "to": {
          "id": "t2",
          "name": "Senior agent",
          "family": "Customer care",
          "level": "Junior",
          "active": true
        },
        "kind": "promotion",
        "typical_months": 12,
        "note": "Usually after a year",
        "required": [
          {
            "skill_id": "s1",
            "name": "English",
            "level": 3
          }
        ],
        "created_at": "2026-11-16T10:00:00.000Z",
        "updated_at": "2026-11-16T10:00:00.000Z"
      }
    ],
    "families": [
      {
        "id": "f1",
        "name": "Customer care",
        "paths": 1
      },
      {
        "id": null,
        "name": null,
        "paths": 0
      }
    ],
    "titles": [
      {
        "id": "t1",
        "name": "Customer care agent",
        "family_id": "f1",
        "family": "Customer care",
        "level": "Junior",
        "level_rank": 1,
        "track": "ic"
      }
    ],
    "limits": {
      "per_family": 200,
      "total": 2000,
      "used": 1
    },
    "can_edit": true
  }
}

Get a career path#

POST/v1/talent/paths.getRead

One career path with its titles, kind, typical months, note and the skills the target title requires. Everyone but viewers; machines may read.

Who can call it
Manage key owner admin hr
Me key owner admin hr member
MCP tool
talent_paths_get on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • path_idstringrequired

    1–200 characters.

Returns

9 fields
  • idstringrequired
  • fromobjectrequired
    5 fields
    • idstringrequired
    • namestringrequired
    • familystring | nullrequired

      Owners, admins, HR and viewers only (job architecture); null for others.

    • levelstring | nullrequired

      As family.

    • activebooleanrequired

      False when the title was archived (the path no longer shows in Me).

  • toobjectrequired
    5 fields
    • idstringrequired
    • namestringrequired
    • familystring | nullrequired

      Owners, admins, HR and viewers only (job architecture); null for others.

    • levelstring | nullrequired

      As family.

    • activebooleanrequired

      False when the title was archived (the path no longer shows in Me).

  • kind"promotion" | "lateral" | "specialist"required
  • typical_monthsinteger | nullrequired
  • notestring | nullrequired
  • requiredobject[]required

    Skills the target title requires (W1 skills framework), read only here.

    3 fields
    • skill_idstringrequired
    • namestringrequired
    • levelintegerrequired
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/paths.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path_id":"t1:t2"}'
Response
{
  "data": {
    "id": "t1:t2",
    "from": {
      "id": "t1",
      "name": "Customer care agent",
      "family": "Customer care",
      "level": "Junior",
      "active": true
    },
    "to": {
      "id": "t2",
      "name": "Senior agent",
      "family": "Customer care",
      "level": "Junior",
      "active": true
    },
    "kind": "promotion",
    "typical_months": 12,
    "note": "Usually after a year",
    "required": [
      {
        "skill_id": "s1",
        "name": "English",
        "level": 3
      }
    ],
    "created_at": "2026-11-16T10:00:00.000Z",
    "updated_at": "2026-11-16T10:00:00.000Z"
  }
}

Save a career path#

POST/v1/talent/paths.setWrite

Adds a career path between two active catalog titles (from_title_id → to_title_id, org_titles_search), or changes one (path_id; sending other titles moves it). kind: promotion (default), lateral or specialist; typical_months (1–240) people usually spend in the starting title; note (up to 1,000 characters, shown to people in My career). One path per pair (a second one is a conflict). Up to 200 paths per family and 2,000 in all. Owners, admins, HR or a custom role with Structure at Edit; API keys of those too (no personal data). Dry run shows the result without saving.

Who can call it
Manage key owner admin hr
MCP tool
talent_paths_set on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • path_idstring

    The path to change; leave out to add one.

    1–200 characters.

  • from_title_idstringrequired

    1–200 characters.

  • to_title_idstringrequired

    1–200 characters.

  • kind"promotion" | "lateral" | "specialist"

    Default "promotion".

  • typical_monthsinteger | null

    From 1 to 240.

  • notestring | null

    Up to 1000 characters.

Returns

9 fields
  • idstringrequired
  • fromobjectrequired
    5 fields
    • idstringrequired
    • namestringrequired
    • familystring | nullrequired

      Owners, admins, HR and viewers only (job architecture); null for others.

    • levelstring | nullrequired

      As family.

    • activebooleanrequired

      False when the title was archived (the path no longer shows in Me).

  • toobjectrequired
    5 fields
    • idstringrequired
    • namestringrequired
    • familystring | nullrequired

      Owners, admins, HR and viewers only (job architecture); null for others.

    • levelstring | nullrequired

      As family.

    • activebooleanrequired

      False when the title was archived (the path no longer shows in Me).

  • kind"promotion" | "lateral" | "specialist"required
  • typical_monthsinteger | nullrequired
  • notestring | nullrequired
  • requiredobject[]required

    Skills the target title requires (W1 skills framework), read only here.

    3 fields
    • skill_idstringrequired
    • namestringrequired
    • levelintegerrequired
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/paths.set \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "path_id": "t1:t2",
  "from_title_id": "t1",
  "to_title_id": "t3",
  "kind": "lateral",
  "typical_months": null,
  "note": null
}'
Response
{
  "data": {
    "id": "t1:t2",
    "from": {
      "id": "t1",
      "name": "Customer care agent",
      "family": "Customer care",
      "level": "Junior",
      "active": true
    },
    "to": {
      "id": "t2",
      "name": "Senior agent",
      "family": "Customer care",
      "level": "Junior",
      "active": true
    },
    "kind": "lateral",
    "typical_months": null,
    "note": null,
    "required": [
      {
        "skill_id": "s1",
        "name": "English",
        "level": 3
      }
    ],
    "created_at": "2026-11-16T10:00:00.000Z",
    "updated_at": "2026-11-16T10:00:00.000Z"
  }
}

Remove a career path#

POST/v1/talent/paths.removeWrite

Removes a career path: it no longer shows in My career. People's interest in the target title stays (they can remove it). Owners, admins, HR or a custom role with Structure at Edit; API keys of those too. Dry run shows it without removing.

Who can call it
Manage key owner admin hr
MCP tool
talent_paths_remove on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • path_idstringrequired

    1–200 characters.

Returns

  • idstringrequired
  • removedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/paths.remove \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"path_id":"t1:t2"}'
Response
{
  "data": {
    "id": "t1:t2",
    "removed": true
  }
}

Suggest career paths#

POST/v1/talent/paths.suggestWrite

Proposes paths from each catalog title to the titles at the next level up in the same family and track (job title catalog: family, track, level). Deterministic, not AI; pairs that already have a path are left out; titles without a family, track or level get no proposal. create false (default) only lists them; create true adds them all as promotions (or only pairs, a subset of the proposals). family_id limits it to one family. Limits as talent_paths_set. Owners, admins, HR or a custom role with Structure at Edit; API keys of those too. Dry run with create true shows what would be added.

Who can call it
Manage key owner admin hr
MCP tool
talent_paths_suggest on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • family_idstring

    1–200 characters.

  • createboolean

    Default false.

  • pairsobject[]

    With create: add only these proposals.

    Up to 500 items.

    2 fields
    • from_title_idstringrequired

      1–200 characters.

    • to_title_idstringrequired

      1–200 characters.

Returns

  • itemsobject[]required
    3 fields
    • fromobjectrequired
      5 fields
      • idstringrequired
      • namestringrequired
      • familystring | nullrequired

        Owners, admins, HR and viewers only (job architecture); null for others.

      • levelstring | nullrequired

        As family.

      • activebooleanrequired

        False when the title was archived (the path no longer shows in Me).

    • toobjectrequired
      5 fields
      • idstringrequired
      • namestringrequired
      • familystring | nullrequired

        Owners, admins, HR and viewers only (job architecture); null for others.

      • levelstring | nullrequired

        As family.

      • activebooleanrequired

        False when the title was archived (the path no longer shows in Me).

    • kind"promotion" | "lateral" | "specialist"required
  • createdintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/paths.suggest \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "family_id": "f1",
  "create": true,
  "pairs": [
    {
      "from_title_id": "t1",
      "to_title_id": "t2"
    }
  ]
}'
Response
{
  "data": {
    "items": [
      {
        "from": {
          "id": "t1",
          "name": "Customer care agent",
          "family": "Customer care",
          "level": "Junior",
          "active": true
        },
        "to": {
          "id": "t2",
          "name": "Senior agent",
          "family": "Customer care",
          "level": "Junior",
          "active": true
        },
        "kind": "promotion"
      }
    ],
    "created": 0
  }
}

My career#

POST/v1/talent/paths.mineRead

For the person signed in: their job title today, the skills it requires against the ones they hold (only accepted skills count; the manager's level wins over their own), and the career paths from it: per target title the skill gaps (biggest first), up to 3 active courses per gap skill (completed ones left out), open internal jobs for that title and whether they said they are interested. Use it to answer "what jobs can I move to?"; never apply or show interest for the person. Their own data only.

Who can call it
Me key owner admin hr member
MCP tool
talent_paths_mine on My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • titleobject | nullrequired

    Your job title today in the catalog; null when you have none.

    2 fields
    • idstringrequired
    • namestringrequired
  • requiredobject[]required

    Skills your title requires: what you hold against what it needs.

    6 fields
    • skill_idstringrequired
    • namestringrequired
    • requiredintegerrequired
    • heldinteger | nullrequired
    • gapintegerrequired
    • status"met" | "below" | "missing"required
  • pathsobject[]required
    10 fields
    • idstringrequired
    • toobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • kind"promotion" | "lateral" | "specialist"required
    • typical_monthsinteger | nullrequired
    • notestring | nullrequired
    • gapsobject[]required

      Every skill the target requires, gaps first (biggest first).

      6 fields
      • skill_idstringrequired
      • namestringrequired
      • requiredintegerrequired
      • heldinteger | nullrequired
      • gapintegerrequired
      • status"met" | "below" | "missing"required
    • readybooleanrequired

      You hold every required skill at the level needed (or the target requires none).

    • coursesobject[]required

      Active courses that teach a gap skill, at most 3 per skill, those you completed left out.

      2 fields
      • skill_idstringrequired
      • itemsobject[]required
        3 fields
        • idstringrequired
        • titlestringrequired
        • hoursnumberrequired
    • jobsobject[]required

      Open internal jobs for the target title.

      3 fields
      • job_idstringrequired
      • titlestringrequired
      • locationstring | nullrequired
    • interestobject | nullrequired

      You said you are interested.

      2 fields
      • shared_with_managerbooleanrequired
      • updated_atstringrequired
  • interests_leftintegerrequired
  • trainingbooleanrequired

    Training is on (suggested courses can show).

  • hiringbooleanrequired

    Internal jobs can show.

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/paths.mine \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "title": {
      "id": "t1",
      "name": "Customer care agent"
    },
    "required": [
      {
        "skill_id": "s1",
        "name": "English",
        "required": 2,
        "held": 2,
        "gap": 0,
        "status": "met"
      }
    ],
    "paths": [
      {
        "id": "t1:t2",
        "to": {
          "id": "t2",
          "name": "Senior agent"
        },
        "kind": "promotion",
        "typical_months": 12,
        "note": null,
        "gaps": [
          {
            "skill_id": "s1",
            "name": "English",
            "required": 3,
            "held": 2,
            "gap": 1,
            "status": "below"
          }
        ],
        "ready": false,
        "courses": [
          {
            "skill_id": "s1",
            "items": [
              {
                "id": "c1",
                "title": "English C1",
                "hours": 40
              }
            ]
          }
        ],
        "jobs": [
          {
            "job_id": "j1",
            "title": "Senior agent",
            "location": "Porto"
          }
        ],
        "interest": {
          "shared_with_manager": false,
          "updated_at": "2026-11-16T10:00:00.000Z"
        }
      }
    ],
    "interests_left": 49,
    "training": true,
    "hiring": true
  }
}

Say I'm interested in a job#

POST/v1/talent/paths.interest.setWrite

The person signed in says they are interested in a job title one of their career paths leads to (to_title_id from talent_paths_mine), and whether to share it with their manager (shared_with_manager, default false; their manager chain sees it only when shared; HR always sees it). Saying it again changes the sharing. Up to 50 titles. Only in the Bizisy app: API keys and AI assistants can't say it for someone.

Who can call it
Me key owner admin hr member
MCP tool
talent_paths_interest_set on My Workplace
Preview
?dry_run=true runs 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

  • to_title_idstringrequired

    1–200 characters.

  • shared_with_managerboolean

    Default false.

Returns

  • to_title_idstringrequired
  • shared_with_managerbooleanrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/paths.interest.set \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"to_title_id":"t2","shared_with_manager":true}'
Response
{
  "data": {
    "to_title_id": "t2",
    "shared_with_manager": true,
    "updated_at": "2026-11-16T10:00:00.000Z"
  }
}

Remove my interest in a job#

POST/v1/talent/paths.interest.removeWrite

The person signed in is no longer interested in a job title (to_title_id). Only in the Bizisy app.

Who can call it
Me key owner admin hr member
MCP tool
talent_paths_interest_remove on My Workplace
Preview
?dry_run=true runs 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

  • to_title_idstringrequired

    1–200 characters.

Returns

  • to_title_idstringrequired
  • removedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/paths.interest.remove \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"to_title_id":"t2"}'
Response
{
  "data": {
    "to_title_id": "t2",
    "removed": true
  }
}

Career interest#

POST/v1/talent/paths.interest.listRead

Job titles people said they are interested in (from My career). Owners, admins and HR see everyone's; a manager sees only what people in their reporting line chose to share with their manager; everyone sees their own. A signal for development and succession, never a decision. person_id narrows it to one person. Only in the Bizisy app: API keys and AI assistants can't read it.

Who can call it
Manage key owner admin hr
Me key owner admin hr member
MCP tool
talent_paths_interest_list on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • person_idstring

    1–200 characters.

Returns

  • itemsobject[]required
    4 fields
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • to_titleobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • shared_with_managerbooleanrequired
    • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/paths.interest.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person_id":"p2"}'
Response
{
  "data": {
    "items": [
      {
        "person": {
          "id": "p2",
          "name": "Rita Lopes"
        },
        "to_title": {
          "id": "t2",
          "name": "Senior agent"
        },
        "shared_with_manager": true,
        "updated_at": "2026-11-16T10:00:00.000Z"
      }
    ]
  }
}

Something missing or wrong on this page? Write to hello@bizisy.com.

Developer docs