Skip to content

API reference

Calibration, 9-box, succession and skills

Calibration sessions (population from a review cycle, facilitator, participants; moves, lock and reopen are in the app), potential, the 9-box, key positions with successors and bench strength, development actions, and the skills framework (catalog, skills required by job titles and given by courses, people's skills by source, gaps). Ratings, potential and succession are never readable by API keys or AI apps.

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

Assess potential#

POST/v1/talent/potential.setWrite

Records a person's potential (low, moderate or high) with short answers to three prompts: aspiration (wants more responsibility), ability (learns fast, handles the next level's complexity) and engagement (committed, likely to stay). Dated and kept as history; calibration may adjust it with a reason. Potential ratings tend to favour people like the rater. Rate what you have seen, not style or availability for long hours. The direct manager or HR, never about themselves; the person never sees it in Me. App only.

Who can call it
Manage key owner admin hr
Me key owner admin hr member
MCP tool
talent_potential_set on HR Assistant, 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

  • person_idstringrequired

    1–200 characters.

  • level"low" | "moderate" | "high"required
  • promptsobjectrequired

    Short answers to the three prompts (up to 500 characters each).

    3 fields
    • aspirationstringrequired

      Up to 500 characters.

    • abilitystringrequired

      Up to 500 characters.

    • engagementstringrequired

      Up to 500 characters.

  • cycle_idstring | null

    The review cycle it was assessed in, if any.

    1–200 characters.

Returns

8 fields
  • idstringrequired
  • person_idstringrequired
  • level"low" | "moderate" | "high"required
  • promptsobjectrequired
    3 fields
    • aspirationstringrequired
    • abilitystringrequired
    • engagementstringrequired
  • byobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • source"manager" | "hr" | "calibration"required
  • cycle_idstring | nullrequired
  • atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/potential.set \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "person_id": "p4",
  "level": "high",
  "prompts": {
    "aspiration": "Wants to lead the queue.",
    "ability": "Learns fast.",
    "engagement": "Committed."
  }
}'
Response
{
  "data": {
    "id": "pt9",
    "person_id": "p4",
    "level": "high",
    "prompts": {
      "aspiration": "Wants to lead the queue.",
      "ability": "Learns fast.",
      "engagement": "Committed."
    },
    "by": {
      "id": "p1",
      "name": "Ana Ferreira"
    },
    "source": "hr",
    "cycle_id": null,
    "at": "2026-11-13T18:23:26.061Z"
  }
}

A person's potential history#

POST/v1/talent/potential.historyRead

Every potential assessment of a person, newest first, with the prompts, who assessed it and how (manager, HR or calibration), plus the guidance texts the form shows. HR and the manager chain; never the person themselves, never machines.

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

Input

  • person_idstringrequired

    1–200 characters.

Returns

  • itemsobject[]required
    8 fields
    • idstringrequired
    • person_idstringrequired
    • level"low" | "moderate" | "high"required
    • promptsobjectrequired
      3 fields
      • aspirationstringrequired
      • abilitystringrequired
      • engagementstringrequired
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • source"manager" | "hr" | "calibration"required
    • cycle_idstring | nullrequired
    • atstringrequired
  • guidanceobjectrequired
    3 fields
    • aspirationstringrequired
    • abilitystringrequired
    • engagementstringrequired
  • bias_notestringrequired
  • can_assessbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/potential.history \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person_id":"p4"}'
Response
{
  "data": {
    "items": [
      {
        "id": "pt2",
        "person_id": "p4",
        "level": "high",
        "prompts": {
          "aspiration": "",
          "ability": "",
          "engagement": ""
        },
        "by": {
          "id": "p1",
          "name": "Ana Ferreira"
        },
        "source": "calibration",
        "cycle_id": "cy1",
        "at": "2026-11-10T18:23:26.061Z"
      },
      {
        "id": "pt1",
        "person_id": "p4",
        "level": "moderate",
        "prompts": {
          "aspiration": "Asked to lead the billing migration.",
          "ability": "Picked up the payments domain in weeks.",
          "engagement": "Mentors the two juniors without being asked."
        },
        "by": {
          "id": "p2",
          "name": "Tomás Silva"
        },
        "source": "manager",
        "cycle_id": "cy1",
        "at": "2026-10-14T18:23:26.061Z"
      }
    ],
    "guidance": {
      "aspiration": "Do they want more responsibility or a bigger role?",
      "ability": "Do they learn fast and handle the complexity of the next level?",
      "engagement": "Are they committed to the team and likely to stay?"
    },
    "bias_note": "Potential ratings tend to favour people like the rater.",
    "can_assess": true
  }
}

List calibration sessions#

POST/v1/talent/calibrations.listRead

Calibration sessions the caller may open: HR all (but sessions they are calibrated in), facilitators and participants theirs (participants once open). Each with its cycle, status, people and moves counts. Optional cycle_id. Never ratings.

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

Input

  • cycle_idstring

    1–200 characters.

Returns

  • itemsobject[]required
    18 fields
    • idstringrequired
    • namestringrequired
    • cycleobjectrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • release_onstringrequired
    • status"draft" | "open" | "locked"required
    • populationobjectrequired
      5 fields
      • unit_idsstring[]required
      • location_idsstring[]required
      • title_idsstring[]required
      • level_idsstring[]required
      • person_idsstring[]required
    • peopleintegerrequired

      People in the session.

    • movesintegerrequired

      Moves recorded so far.

    • facilitatorobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • participantsobject[]required
      2 fields
      • idstringrequired
      • namestringrequired
    • opened_atstring | nullrequired
    • locked_atstring | nullrequired
    • locked_byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • reopenedobject[]required
      3 fields
      • byobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • atstringrequired
      • reasonstringrequired
    • role"facilitator" | "participant" | "hr"required

      How the caller takes part.

    • can_movebooleanrequired
    • can_lockbooleanrequired
    • can_reopenbooleanrequired
    • syncingintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/calibrations.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cycle_id":"cy1"}'
Response
{
  "data": {
    "items": [
      {
        "id": "cs1",
        "name": "Contact centre — agents and team leaders",
        "cycle": {
          "id": "cy1",
          "name": "Annual review 2026",
          "release_on": "2026-12-01"
        },
        "status": "open",
        "population": {
          "unit_ids": [
            "cc1",
            "cc2",
            "cc3"
          ],
          "location_ids": [],
          "title_ids": [],
          "level_ids": [],
          "person_ids": []
        },
        "people": 35,
        "moves": 4,
        "facilitator": {
          "id": "p1",
          "name": "Ana Ferreira"
        },
        "participants": [
          {
            "id": "p2",
            "name": "Tomás Silva"
          },
          {
            "id": "p6",
            "name": "Marta Rocha"
          },
          {
            "id": "p7",
            "name": "Jo"
          }
        ],
        "opened_at": "2026-11-11T18:23:26.061Z",
        "locked_at": null,
        "locked_by": null,
        "reopened": [],
        "role": "facilitator",
        "can_move": true,
        "can_lock": true,
        "can_reopen": false,
        "syncing": 0
      },
      {
        "id": "cs2",
        "name": "Engineering and product",
        "cycle": {
          "id": "cy1",
          "name": "Annual review 2026",
          "release_on": "2026-12-01"
        },
        "status": "locked",
        "population": {
          "unit_ids": [],
          "location_ids": [],
          "title_ids": [],
          "level_ids": [],
          "person_ids": []
        },
        "people": 9,
        "moves": 2,
        "facilitator": {
          "id": "p1",
          "name": "Ana Ferreira"
        },
        "participants": [
          {
            "id": "p2",
            "name": "Tomás Silva"
          }
        ],
        "opened_at": "2026-11-11T18:23:26.061Z",
        "locked_at": "2026-11-13T18:09:02.061Z",
        "locked_by": {
          "id": "p1",
          "name": "Ana Ferreira"
        },
        "reopened": [],
        "role": "facilitator",
        "can_move": false,
        "can_lock": false,
        "can_reopen": true,
        "syncing": 0
      },
      {
        "id": "cs3",
        "name": "Finance and operations",
        "cycle": {
          "id": "cy1",
          "name": "Annual review 2026",
          "release_on": "2026-12-01"
        },
        "status": "draft",
        "population": {
          "unit_ids": [],
          "location_ids": [],
          "title_ids": [],
          "level_ids": [],
          "person_ids": []
        },
        "people": 4,
        "moves": 0,
        "facilitator": {
          "id": "p1",
          "name": "Ana Ferreira"
        },
        "participants": [
          {
            "id": "p6",
            "name": "Marta Rocha"
          }
        ],
        "opened_at": null,
        "locked_at": null,
        "locked_by": null,
        "reopened": [],
        "role": "facilitator",
        "can_move": false,
        "can_lock": false,
        "can_reopen": false,
        "syncing": 0
      }
    ]
  }
}

Open a calibration session#

POST/v1/talent/calibrations.getRead

One session's room: the population with each manager's rating beside the current one, potential, the 9-box placement, the distribution of ratings (beside the company's reference curve only when HR set one: information, never a quota), the centrality warning (the middle grew by more than 10 points), and the timeline of moves with reasons. Facilitator, participants (once open) and HR; nobody sees a session they are calibrated in. Confidential: app only.

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

Input

  • calibration_idstringrequired

    1–200 characters.

Returns

27 fields
  • idstringrequired
  • namestringrequired
  • cycleobjectrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • release_onstringrequired
  • status"draft" | "open" | "locked"required
  • populationobjectrequired
    5 fields
    • unit_idsstring[]required
    • location_idsstring[]required
    • title_idsstring[]required
    • level_idsstring[]required
    • person_idsstring[]required
  • peopleintegerrequired

    People in the session.

  • movesintegerrequired

    Moves recorded so far.

  • facilitatorobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • participantsobject[]required
    2 fields
    • idstringrequired
    • namestringrequired
  • opened_atstring | nullrequired
  • locked_atstring | nullrequired
  • locked_byobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • reopenedobject[]required
    3 fields
    • byobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired
    • reasonstringrequired
  • role"facilitator" | "participant" | "hr"required

    How the caller takes part.

  • can_movebooleanrequired
  • can_lockbooleanrequired
  • can_reopenbooleanrequired
  • syncingintegerrequired
  • scaleobjectrequired
    1 field
    • pointsobject[]required
      3 fields
      • valueintegerrequired
      • labelstringrequired
      • descriptionstringrequired
  • curvenumber[] | nullrequired

    The reference share per rating, low to high, when HR set one in Settings → Talent (null: none, the default). A reference, never a quota.

  • rowsobject[]required
    17 fields
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • titlestring | nullrequired
    • title_idstring | nullrequired
    • level_idstring | nullrequired
    • locationobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • managerobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • review_idstring | nullrequired
    • manager_ratinginteger | nullrequired

      The manager's rating (kept beside the current one).

    • ratinginteger | nullrequired

      The current (calibrated) rating.

    • potential_before"low" | "moderate" | "high"required
    • potential"low" | "moderate" | "high"required
    • boxstring | nullrequired

      The 9-box: `${performance}-${potential}` (low, mid, high), or null when rating or potential is missing.

    • movedbooleanrequired
    • self_ratinginteger | nullrequired

      The person's own rating: the rounded mean of the ratings in their submitted self-review (null when none).

    • last_ratingobject | nullrequired

      The final rating of their last released review in another cycle (points: that scale's size).

      3 fields
      • ratingintegerrequired
      • pointsintegerrequired
      • cyclestringrequired
    • minebooleanrequired

      The caller manages this person (anywhere up the chain): "Hide my own reports" in the room.

  • distributionobject[]required
    6 fields
    • valueintegerrequired
    • labelstringrequired
    • countintegerrequired
    • sharenumberrequired
    • targetnumber | nullrequired

      The reference share HR set for this rating (null: no reference); information, never a quota.

    • managersintegerrequired
  • ratedintegerrequired
  • missing_ratingsintegerrequired

    People whose manager has not rated them yet (they stay out of the lock).

  • centralityobjectrequired
    3 fields
    • beforenumberrequired
    • afternumberrequired
    • warnbooleanrequired
  • boxesobject[]required
    5 fields
    • keystringrequired
    • performancestringrequired
    • potentialstringrequired
    • namestringrequired
    • stepstringrequired
  • timelineobject[]required
    8 fields
    • idstringrequired
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • field"rating" | "potential"required
    • fromnumber | stringrequired
    • tonumber | stringrequired
    • reasonstringrequired
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/calibrations.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"calibration_id":"cs1"}'
Response
{
  "data": {
    "id": "cs1",
    "name": "Contact centre — agents and team leaders",
    "cycle": {
      "id": "cy1",
      "name": "Annual review 2026",
      "release_on": "2026-12-02"
    },
    "status": "open",
    "population": {
      "unit_ids": [
        "cc1",
        "cc2",
        "cc3"
      ],
      "location_ids": [],
      "title_ids": [],
      "level_ids": [],
      "person_ids": []
    },
    "people": 35,
    "moves": 4,
    "facilitator": {
      "id": "p1",
      "name": "Ana Ferreira"
    },
    "participants": [
      {
        "id": "p2",
        "name": "Tomás Silva"
      },
      {
        "id": "p6",
        "name": "Marta Rocha"
      },
      {
        "id": "p7",
        "name": "Jo"
      }
    ],
    "opened_at": "2026-11-12T08:17:31.479Z",
    "locked_at": null,
    "locked_by": null,
    "reopened": [],
    "role": "facilitator",
    "can_move": true,
    "can_lock": true,
    "can_reopen": false,
    "syncing": 0,
    "scale": {
      "points": [
        {
          "value": 1,
          "label": "Well below expectations",
          "description": "Results and behaviours fall well short of what the role needs."
        },
        {
          "value": 2,
          "label": "Below expectations",
          "description": "Some of what the role needs is missing; clear gaps to close."
        },
        {
          "value": 3,
          "label": "Meets expectations",
          "description": "Delivers what the role needs, reliably."
        },
        {
          "value": 4,
          "label": "Exceeds expectations",
          "description": "Often goes beyond what the role needs."
        },
        {
          "value": 5,
          "label": "Outstanding",
          "description": "Consistently far beyond what the role needs; a model for others."
        }
      ]
    },
    "curve": [
      10,
      20,
      40,
      20,
      10
    ],
    "rows": [
      {
        "person": {
          "id": "cp23",
          "name": "André Esteves"
        },
        "unit": {
          "id": "cc2",
          "name": "Porto — Telco support"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l2",
          "name": "Porto"
        },
        "manager": {
          "id": "p2",
          "name": "Tomás Silva"
        },
        "review_id": "rv-cp23",
        "manager_rating": 4,
        "rating": 4,
        "potential_before": "moderate",
        "potential": "moderate",
        "box": "high-mid",
        "moved": false,
        "self_rating": 4,
        "last_rating": null,
        "mine": true
      },
      {
        "person": {
          "id": "cp1",
          "name": "Beatriz Almeida"
        },
        "unit": {
          "id": "cc1",
          "name": "Lisbon — Spanish queue"
        },
        "title": "Team Leader",
        "title_id": "tt-tl",
        "level_id": null,
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "manager": {
          "id": "p7",
          "name": "Jo"
        },
        "review_id": "rv-cp1",
        "manager_rating": 5,
        "rating": 4,
        "potential_before": "high",
        "potential": "high",
        "box": "high-high",
        "moved": true,
        "self_rating": 5,
        "last_rating": {
          "rating": 5,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp24",
          "name": "Bruna Faria"
        },
        "unit": {
          "id": "cc3",
          "name": "Lisbon — Retention"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "manager": {
          "id": "p6",
          "name": "Marta Rocha"
        },
        "review_id": "rv-cp24",
        "manager_rating": 3,
        "rating": 3,
        "potential_before": "moderate",
        "potential": "moderate",
        "box": "mid-mid",
        "moved": false,
        "self_rating": 3,
        "last_rating": {
          "rating": 4,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp2",
          "name": "Carlos Barros"
        },
        "unit": {
          "id": "cc2",
          "name": "Porto — Telco support"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l2",
          "name": "Porto"
        },
        "manager": {
          "id": "p2",
          "name": "Tomás Silva"
        },
        "review_id": "rv-cp2",
        "manager_rating": 4,
        "rating": 4,
        "potential_before": "moderate",
        "potential": "moderate",
        "box": "high-mid",
        "moved": false,
        "self_rating": 3,
        "last_rating": {
          "rating": 5,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp25",
          "name": "Catarina Gomes"
        },
        "unit": {
          "id": "cc1",
          "name": "Lisbon — Spanish queue"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "manager": {
          "id": "p7",
          "name": "Jo"
        },
        "review_id": "rv-cp25",
        "manager_rating": 5,
        "rating": 4,
        "potential_before": "high",
        "potential": "high",
        "box": "high-high",
        "moved": true,
        "self_rating": 5,
        "last_rating": {
          "rating": 5,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp3",
          "name": "Diana Cardoso"
        },
        "unit": {
          "id": "cc3",
          "name": "Lisbon — Retention"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "manager": {
          "id": "p6",
          "name": "Marta Rocha"
        },
        "review_id": "rv-cp3",
        "manager_rating": 3,
        "rating": 3,
        "potential_before": "moderate",
        "potential": "moderate",
        "box": "mid-mid",
        "moved": false,
        "self_rating": 3,
        "last_rating": null,
        "mine": true
      },
      {
        "person": {
          "id": "cp26",
          "name": "Duarte Henriques"
        },
        "unit": {
          "id": "cc2",
          "name": "Porto — Telco support"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l2",
          "name": "Porto"
        },
        "manager": {
          "id": "p2",
          "name": "Tomás Silva"
        },
        "review_id": "rv-cp26",
        "manager_rating": 3,
        "rating": 3,
        "potential_before": "moderate",
        "potential": "moderate",
        "box": "mid-mid",
        "moved": false,
        "self_rating": 4,
        "last_rating": {
          "rating": 2,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp4",
          "name": "Eduardo Dias"
        },
        "unit": {
          "id": "cc1",
          "name": "Lisbon — Spanish queue"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "manager": {
          "id": "p7",
          "name": "Jo"
        },
        "review_id": "rv-cp4",
        "manager_rating": 3,
        "rating": 3,
        "potential_before": "low",
        "potential": "low",
        "box": "mid-low",
        "moved": false,
        "self_rating": 3,
        "last_rating": null,
        "mine": true
      },
      {
        "person": {
          "id": "cp27",
          "name": "Elsa Lima"
        },
        "unit": {
          "id": "cc3",
          "name": "Lisbon — Retention"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "manager": {
          "id": "p6",
          "name": "Marta Rocha"
        },
        "review_id": "rv-cp27",
        "manager_rating": 3,
        "rating": 3,
        "potential_before": "low",
        "potential": "low",
        "box": "mid-low",
        "moved": false,
        "self_rating": 3,
        "last_rating": {
          "rating": 4,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp28",
          "name": "Fábio Macedo"
        },
        "unit": {
          "id": "cc1",
          "name": "Lisbon — Spanish queue"
        },
        "title": "Team Leader",
        "title_id": "tt-tl",
        "level_id": null,
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "manager": {
          "id": "p7",
          "name": "Jo"
        },
        "review_id": "rv-cp28",
        "manager_rating": 4,
        "rating": 4,
        "potential_before": "moderate",
        "potential": "moderate",
        "box": "high-mid",
        "moved": false,
        "self_rating": 4,
        "last_rating": {
          "rating": 5,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp5",
          "name": "Filipa Esteves"
        },
        "unit": {
          "id": "cc2",
          "name": "Porto — Telco support"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l2",
          "name": "Porto"
        },
        "manager": {
          "id": "p2",
          "name": "Tomás Silva"
        },
        "review_id": "rv-cp5",
        "manager_rating": 4,
        "rating": 4,
        "potential_before": "high",
        "potential": "high",
        "box": "high-high",
        "moved": false,
        "self_rating": 4,
        "last_rating": {
          "rating": 3,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp6",
          "name": "Gonçalo Faria"
        },
        "unit": {
          "id": "cc3",
          "name": "Lisbon — Retention"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "manager": {
          "id": "p6",
          "name": "Marta Rocha"
        },
        "review_id": "rv-cp6",
        "manager_rating": 2,
        "rating": 3,
        "potential_before": "low",
        "potential": "low",
        "box": "mid-low",
        "moved": true,
        "self_rating": 3,
        "last_rating": {
          "rating": 1,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp29",
          "name": "Guida Neves"
        },
        "unit": {
          "id": "cc2",
          "name": "Porto — Telco support"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l2",
          "name": "Porto"
        },
        "manager": {
          "id": "p2",
          "name": "Tomás Silva"
        },
        "review_id": "rv-cp29",
        "manager_rating": 2,
        "rating": 2,
        "potential_before": "moderate",
        "potential": "moderate",
        "box": "low-mid",
        "moved": false,
        "self_rating": 2,
        "last_rating": {
          "rating": 3,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp7",
          "name": "Helena Gomes"
        },
        "unit": {
          "id": "cc1",
          "name": "Lisbon — Spanish queue"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "manager": {
          "id": "p7",
          "name": "Jo"
        },
        "review_id": "rv-cp7",
        "manager_rating": 3,
        "rating": 3,
        "potential_before": "moderate",
        "potential": "moderate",
        "box": "mid-mid",
        "moved": false,
        "self_rating": 2,
        "last_rating": {
          "rating": 4,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp30",
          "name": "Hugo Oliveira"
        },
        "unit": {
          "id": "cc3",
          "name": "Lisbon — Retention"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "manager": {
          "id": "p6",
          "name": "Marta Rocha"
        },
        "review_id": "rv-cp30",
        "manager_rating": 3,
        "rating": 3,
        "potential_before": "moderate",
        "potential": "moderate",
        "box": "mid-mid",
        "moved": false,
        "self_rating": 4,
        "last_rating": null,
        "mine": true
      },
      {
        "person": {
          "id": "cp8",
          "name": "Inês Henriques"
        },
        "unit": {
          "id": "cc2",
          "name": "Porto — Telco support"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l2",
          "name": "Porto"
        },
        "manager": {
          "id": "p2",
          "name": "Tomás Silva"
        },
        "review_id": "rv-cp8",
        "manager_rating": 3,
        "rating": 3,
        "potential_before": "moderate",
        "potential": "moderate",
        "box": "mid-mid",
        "moved": false,
        "self_rating": 5,
        "last_rating": {
          "rating": 4,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp31",
          "name": "Íris Pinto"
        },
        "unit": {
          "id": "cc1",
          "name": "Lisbon — Spanish queue"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "manager": {
          "id": "p7",
          "name": "Jo"
        },
        "review_id": "rv-cp31",
        "manager_rating": 3,
        "rating": 3,
        "potential_before": "low",
        "potential": "low",
        "box": "mid-low",
        "moved": false,
        "self_rating": 3,
        "last_rating": {
          "rating": 4,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp9",
          "name": "Joana Lima"
        },
        "unit": {
          "id": "cc3",
          "name": "Lisbon — Retention"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "manager": {
          "id": "p6",
          "name": "Marta Rocha"
        },
        "review_id": "rv-cp9",
        "manager_rating": 4,
        "rating": 4,
        "potential_before": "moderate",
        "potential": "moderate",
        "box": "high-mid",
        "moved": false,
        "self_rating": 4,
        "last_rating": {
          "rating": 4,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp32",
          "name": "Jorge Queirós"
        },
        "unit": {
          "id": "cc2",
          "name": "Porto — Telco support"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l2",
          "name": "Porto"
        },
        "manager": {
          "id": "p2",
          "name": "Tomás Silva"
        },
        "review_id": "rv-cp32",
        "manager_rating": 4,
        "rating": 4,
        "potential_before": "high",
        "potential": "high",
        "box": "high-high",
        "moved": false,
        "self_rating": 4,
        "last_rating": {
          "rating": 3,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp33",
          "name": "Leonor Ramos"
        },
        "unit": {
          "id": "cc3",
          "name": "Lisbon — Retention"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "manager": {
          "id": "p6",
          "name": "Marta Rocha"
        },
        "review_id": "rv-cp33",
        "manager_rating": 3,
        "rating": 3,
        "potential_before": "moderate",
        "potential": "moderate",
        "box": "mid-mid",
        "moved": false,
        "self_rating": 3,
        "last_rating": {
          "rating": 3,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp10",
          "name": "Luís Macedo"
        },
        "unit": {
          "id": "cc1",
          "name": "Lisbon — Spanish queue"
        },
        "title": "Team Leader",
        "title_id": "tt-tl",
        "level_id": null,
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "manager": {
          "id": "p7",
          "name": "Jo"
        },
        "review_id": "rv-cp10",
        "manager_rating": 5,
        "rating": 5,
        "potential_before": "high",
        "potential": "high",
        "box": "high-high",
        "moved": false,
        "self_rating": 4,
        "last_rating": {
          "rating": 5,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "p4",
          "name": "Lukas Weber"
        },
        "unit": {
          "id": "u1",
          "name": "Engineering"
        },
        "title": "Backend Engineer",
        "title_id": "tt-be",
        "level_id": null,
        "location": {
          "id": "l3",
          "name": "Berlin"
        },
        "manager": {
          "id": "p2",
          "name": "Tomás Silva"
        },
        "review_id": "rv-p4",
        "manager_rating": 4,
        "rating": 4,
        "potential_before": "high",
        "potential": "high",
        "box": "high-high",
        "moved": false,
        "self_rating": 4,
        "last_rating": {
          "rating": 5,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp11",
          "name": "Mariana Neves"
        },
        "unit": {
          "id": "cc2",
          "name": "Porto — Telco support"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l2",
          "name": "Porto"
        },
        "manager": {
          "id": "p2",
          "name": "Tomás Silva"
        },
        "review_id": "rv-cp11",
        "manager_rating": 3,
        "rating": 3,
        "potential_before": "moderate",
        "potential": "moderate",
        "box": "mid-mid",
        "moved": false,
        "self_rating": 3,
        "last_rating": {
          "rating": 4,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp34",
          "name": "Miguel Santos"
        },
        "unit": {
          "id": "cc1",
          "name": "Lisbon — Spanish queue"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "manager": {
          "id": "p7",
          "name": "Jo"
        },
        "review_id": "rv-cp34",
        "manager_rating": null,
        "rating": null,
        "potential_before": null,
        "potential": null,
        "box": null,
        "moved": false,
        "self_rating": null,
        "last_rating": {
          "rating": 4,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp12",
          "name": "Nuno Oliveira"
        },
        "unit": {
          "id": "cc3",
          "name": "Lisbon — Retention"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "manager": {
          "id": "p6",
          "name": "Marta Rocha"
        },
        "review_id": "rv-cp12",
        "manager_rating": 2,
        "rating": 2,
        "potential_before": "low",
        "potential": "low",
        "box": "low-low",
        "moved": false,
        "self_rating": 2,
        "last_rating": {
          "rating": 3,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp13",
          "name": "Olga Pinto"
        },
        "unit": {
          "id": "cc1",
          "name": "Lisbon — Spanish queue"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "manager": {
          "id": "p7",
          "name": "Jo"
        },
        "review_id": "rv-cp13",
        "manager_rating": 3,
        "rating": 3,
        "potential_before": "moderate",
        "potential": "moderate",
        "box": "mid-mid",
        "moved": false,
        "self_rating": 3,
        "last_rating": {
          "rating": 2,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp14",
          "name": "Pedro Queirós"
        },
        "unit": {
          "id": "cc2",
          "name": "Porto — Telco support"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l2",
          "name": "Porto"
        },
        "manager": {
          "id": "p2",
          "name": "Tomás Silva"
        },
        "review_id": "rv-cp14",
        "manager_rating": 4,
        "rating": 4,
        "potential_before": "high",
        "potential": "high",
        "box": "high-high",
        "moved": false,
        "self_rating": 5,
        "last_rating": {
          "rating": 5,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp15",
          "name": "Raquel Ramos"
        },
        "unit": {
          "id": "cc3",
          "name": "Lisbon — Retention"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "manager": {
          "id": "p6",
          "name": "Marta Rocha"
        },
        "review_id": "rv-cp15",
        "manager_rating": 3,
        "rating": 3,
        "potential_before": "moderate",
        "potential": "moderate",
        "box": "mid-mid",
        "moved": false,
        "self_rating": 3,
        "last_rating": {
          "rating": 2,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp16",
          "name": "Rui Santos"
        },
        "unit": {
          "id": "cc1",
          "name": "Lisbon — Spanish queue"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "manager": {
          "id": "p7",
          "name": "Jo"
        },
        "review_id": "rv-cp16",
        "manager_rating": 3,
        "rating": 3,
        "potential_before": "low",
        "potential": "low",
        "box": "mid-low",
        "moved": false,
        "self_rating": 5,
        "last_rating": {
          "rating": 2,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp17",
          "name": "Sara Teixeira"
        },
        "unit": {
          "id": "cc2",
          "name": "Porto — Telco support"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l2",
          "name": "Porto"
        },
        "manager": {
          "id": "p2",
          "name": "Tomás Silva"
        },
        "review_id": "rv-cp17",
        "manager_rating": 1,
        "rating": 1,
        "potential_before": "low",
        "potential": "moderate",
        "box": "low-mid",
        "moved": true,
        "self_rating": 1,
        "last_rating": null,
        "mine": true
      },
      {
        "person": {
          "id": "cp18",
          "name": "Tiago Valente"
        },
        "unit": {
          "id": "cc3",
          "name": "Lisbon — Retention"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "manager": {
          "id": "p6",
          "name": "Marta Rocha"
        },
        "review_id": "rv-cp18",
        "manager_rating": 3,
        "rating": 3,
        "potential_before": "moderate",
        "potential": "moderate",
        "box": "mid-mid",
        "moved": false,
        "self_rating": 3,
        "last_rating": null,
        "mine": true
      },
      {
        "person": {
          "id": "cp19",
          "name": "Vera Almeida"
        },
        "unit": {
          "id": "cc1",
          "name": "Lisbon — Spanish queue"
        },
        "title": "Team Leader",
        "title_id": "tt-tl",
        "level_id": null,
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "manager": {
          "id": "p7",
          "name": "Jo"
        },
        "review_id": "rv-cp19",
        "manager_rating": 4,
        "rating": 4,
        "potential_before": "moderate",
        "potential": "moderate",
        "box": "high-mid",
        "moved": false,
        "self_rating": 4,
        "last_rating": {
          "rating": 4,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp20",
          "name": "Xavier Barros"
        },
        "unit": {
          "id": "cc2",
          "name": "Porto — Telco support"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l2",
          "name": "Porto"
        },
        "manager": {
          "id": "p2",
          "name": "Tomás Silva"
        },
        "review_id": "rv-cp20",
        "manager_rating": 3,
        "rating": 3,
        "potential_before": "moderate",
        "potential": "moderate",
        "box": "mid-mid",
        "moved": false,
        "self_rating": 5,
        "last_rating": {
          "rating": 3,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp21",
          "name": "Yara Cardoso"
        },
        "unit": {
          "id": "cc3",
          "name": "Lisbon — Retention"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "manager": {
          "id": "p6",
          "name": "Marta Rocha"
        },
        "review_id": "rv-cp21",
        "manager_rating": 3,
        "rating": 3,
        "potential_before": "high",
        "potential": "high",
        "box": "mid-high",
        "moved": false,
        "self_rating": 4,
        "last_rating": {
          "rating": 2,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      },
      {
        "person": {
          "id": "cp22",
          "name": "Zé Dias"
        },
        "unit": {
          "id": "cc1",
          "name": "Lisbon — Spanish queue"
        },
        "title": "Customer Agent",
        "title_id": "tt-ag",
        "level_id": null,
        "location": {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        "manager": {
          "id": "p7",
          "name": "Jo"
        },
        "review_id": "rv-cp22",
        "manager_rating": 2,
        "rating": 2,
        "potential_before": "low",
        "potential": "low",
        "box": "low-low",
        "moved": false,
        "self_rating": 3,
        "last_rating": {
          "rating": 3,
          "points": 5,
          "cycle": "Annual review 2025"
        },
        "mine": true
      }
    ],
    "distribution": [
      {
        "value": 1,
        "label": "Well below expectations",
        "count": 1,
        "share": 3,
        "target": 10,
        "managers": 1
      },
      {
        "value": 2,
        "label": "Below expectations",
        "count": 3,
        "share": 9,
        "target": 20,
        "managers": 4
      },
      {
        "value": 3,
        "label": "Meets expectations",
        "count": 18,
        "share": 53,
        "target": 40,
        "managers": 17
      },
      {
        "value": 4,
        "label": "Exceeds expectations",
        "count": 11,
        "share": 32,
        "target": 20,
        "managers": 9
      },
      {
        "value": 5,
        "label": "Outstanding",
        "count": 1,
        "share": 3,
        "target": 10,
        "managers": 3
      }
    ],
    "rated": 34,
    "missing_ratings": 1,
    "centrality": {
      "before": 50,
      "after": 53,
      "warn": false
    },
    "boxes": [
      {
        "key": "low-high",
        "performance": "low",
        "potential": "high",
        "name": "Low performance, high potential",
        "step": "Clarify expectations and find what blocks them; check role fit."
      },
      {
        "key": "mid-high",
        "performance": "mid",
        "potential": "high",
        "name": "Moderate performance, high potential",
        "step": "Develop: a stretch assignment and a mentor to turn potential into results."
      },
      {
        "key": "high-high",
        "performance": "high",
        "potential": "high",
        "name": "High performance, high potential",
        "step": "Stretch role or next-level move; name as a successor and keep close."
      },
      {
        "key": "low-mid",
        "performance": "low",
        "potential": "mid",
        "name": "Low performance, moderate potential",
        "step": "Clarify expectations with a short, supported improvement plan."
      },
      {
        "key": "mid-mid",
        "performance": "mid",
        "potential": "mid",
        "name": "Moderate performance, moderate potential",
        "step": "Develop in role with clear goals and regular feedback."
      },
      {
        "key": "high-mid",
        "performance": "high",
        "potential": "mid",
        "name": "High performance, moderate potential",
        "step": "Grow in role with broader scope; consider for succession."
      },
      {
        "key": "low-low",
        "performance": "low",
        "potential": "low",
        "name": "Low performance, low potential",
        "step": "Clarify expectations and agree a plan; review role fit together."
      },
      {
        "key": "mid-low",
        "performance": "mid",
        "potential": "low",
        "name": "Moderate performance, low potential",
        "step": "Keep engaged in role; agree goals that play to strengths."
      },
      {
        "key": "high-low",
        "performance": "high",
        "potential": "low",
        "name": "High performance, low potential",
        "step": "Retain and recognise; use their expertise to coach others."
      }
    ],
    "timeline": [
      {
        "id": "mv0",
        "person": {
          "id": "cp25",
          "name": "Catarina Gomes"
        },
        "field": "rating",
        "from": 5,
        "to": 4,
        "reason": "Outstanding on quality, but missed two of four handling-time goals.",
        "by": {
          "id": "p6",
          "name": "Marta Rocha"
        },
        "at": "2026-11-14T07:05:31.479Z"
      },
      {
        "id": "mv1",
        "person": {
          "id": "cp17",
          "name": "Sara Teixeira"
        },
        "field": "potential",
        "from": "low",
        "to": "moderate",
        "reason": "Asked for the quality analyst path and finished the coaching course.",
        "by": {
          "id": "p7",
          "name": "Jo"
        },
        "at": "2026-11-14T05:53:31.479Z"
      },
      {
        "id": "mv2",
        "person": {
          "id": "cp6",
          "name": "Gonçalo Faria"
        },
        "field": "rating",
        "from": 2,
        "to": 3,
        "reason": "The absences were approved leave; the results met the bar once back.",
        "by": {
          "id": "p1",
          "name": "Ana Ferreira"
        },
        "at": "2026-11-14T04:41:31.479Z"
      },
      {
        "id": "mv3",
        "person": {
          "id": "cp1",
          "name": "Beatriz Almeida"
        },
        "field": "rating",
        "from": 5,
        "to": 4,
        "reason": "Strong year, but the Spanish queue targets were shared with Joana’s team.",
        "by": {
          "id": "p2",
          "name": "Tomás Silva"
        },
        "at": "2026-11-14T03:29:31.479Z"
      }
    ]
  }
}

Create a calibration session#

POST/v1/talent/calibrations.createWrite

Creates a draft session for people of one review cycle: by teams, sites, titles or levels (all set filters must match) or a list (at most 500 people; each person in one session per cycle). Names a facilitator (owner, admin or HR; default you) and participants (default: the population's direct managers). Nobody in the population may facilitate or take part. Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
talent_calibrations_create on HR Assistant
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

  • unit_idsstring[]

    Teams (org units) to include.

    1–200 characters. Up to 200 items.

  • location_idsstring[]

    Sites (work locations) to include.

    1–200 characters. Up to 200 items.

  • title_idsstring[]

    Job titles (catalog ids) to include.

    1–200 characters. Up to 200 items.

  • level_idsstring[]

    Levels (catalog level ids) to include.

    1–200 characters. Up to 200 items.

  • person_idsstring[]

    Or a list of people (each must be in the cycle).

    1–200 characters. Up to 500 items.

  • namestringrequired

    E.g. "Lisbon contact centre — team leaders".

    1–120 characters.

  • facilitator_idstring | null

    An owner, admin or HR person who runs the session and locks it (default: you).

    1–200 characters.

  • participant_idsstring[]

    Who calibrates: the managers of the population (default) and any HR people; never someone in the population.

    1–200 characters. Up to 50 items.

  • cycle_idstringrequired

    1–200 characters.

Returns

18 fields
  • idstringrequired
  • namestringrequired
  • cycleobjectrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • release_onstringrequired
  • status"draft" | "open" | "locked"required
  • populationobjectrequired
    5 fields
    • unit_idsstring[]required
    • location_idsstring[]required
    • title_idsstring[]required
    • level_idsstring[]required
    • person_idsstring[]required
  • peopleintegerrequired

    People in the session.

  • movesintegerrequired

    Moves recorded so far.

  • facilitatorobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • participantsobject[]required
    2 fields
    • idstringrequired
    • namestringrequired
  • opened_atstring | nullrequired
  • locked_atstring | nullrequired
  • locked_byobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • reopenedobject[]required
    3 fields
    • byobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired
    • reasonstringrequired
  • role"facilitator" | "participant" | "hr"required

    How the caller takes part.

  • can_movebooleanrequired
  • can_lockbooleanrequired
  • can_reopenbooleanrequired
  • syncingintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/calibrations.create \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "cycle_id": "cy1",
  "name": "List",
  "person_ids": [
    "p3",
    "p4"
  ],
  "facilitator_id": "p1",
  "participant_ids": [
    "p2"
  ]
}'
Response
{
  "data": {
    "id": "cs9",
    "name": "List",
    "cycle": {
      "id": "cy1",
      "name": "Annual review 2026",
      "release_on": "2026-12-01"
    },
    "status": "draft",
    "population": {
      "unit_ids": [],
      "location_ids": [],
      "title_ids": [],
      "level_ids": [],
      "person_ids": []
    },
    "people": 12,
    "moves": 0,
    "facilitator": {
      "id": "p1",
      "name": "Ana Ferreira"
    },
    "participants": [
      {
        "id": "p2",
        "name": "Tomás Silva"
      }
    ],
    "opened_at": null,
    "locked_at": null,
    "locked_by": null,
    "reopened": [],
    "role": "facilitator",
    "can_move": false,
    "can_lock": false,
    "can_reopen": false,
    "syncing": 0
  }
}

Change a calibration session#

POST/v1/talent/calibrations.updateWrite

Changes a session's name, facilitator or participants (any time before it is locked) or its population filters (only while draft). Same rules as create. Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
talent_calibrations_update on HR Assistant
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

  • unit_idsstring[]

    Teams (org units) to include.

    1–200 characters. Up to 200 items.

  • location_idsstring[]

    Sites (work locations) to include.

    1–200 characters. Up to 200 items.

  • title_idsstring[]

    Job titles (catalog ids) to include.

    1–200 characters. Up to 200 items.

  • level_idsstring[]

    Levels (catalog level ids) to include.

    1–200 characters. Up to 200 items.

  • person_idsstring[]

    Or a list of people (each must be in the cycle).

    1–200 characters. Up to 500 items.

  • namestring

    E.g. "Lisbon contact centre — team leaders".

    1–120 characters.

  • facilitator_idstring | null

    An owner, admin or HR person who runs the session and locks it (default: you).

    1–200 characters.

  • participant_idsstring[]

    Who calibrates: the managers of the population (default) and any HR people; never someone in the population.

    1–200 characters. Up to 50 items.

  • calibration_idstringrequired

    1–200 characters.

Returns

18 fields
  • idstringrequired
  • namestringrequired
  • cycleobjectrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • release_onstringrequired
  • status"draft" | "open" | "locked"required
  • populationobjectrequired
    5 fields
    • unit_idsstring[]required
    • location_idsstring[]required
    • title_idsstring[]required
    • level_idsstring[]required
    • person_idsstring[]required
  • peopleintegerrequired

    People in the session.

  • movesintegerrequired

    Moves recorded so far.

  • facilitatorobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • participantsobject[]required
    2 fields
    • idstringrequired
    • namestringrequired
  • opened_atstring | nullrequired
  • locked_atstring | nullrequired
  • locked_byobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • reopenedobject[]required
    3 fields
    • byobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired
    • reasonstringrequired
  • role"facilitator" | "participant" | "hr"required

    How the caller takes part.

  • can_movebooleanrequired
  • can_lockbooleanrequired
  • can_reopenbooleanrequired
  • syncingintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/calibrations.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"calibration_id":"cs1","name":"Renamed"}'
Response
{
  "data": {
    "id": "cs1",
    "name": "Renamed",
    "cycle": {
      "id": "cy1",
      "name": "Annual review 2026",
      "release_on": "2026-12-01"
    },
    "status": "open",
    "population": {
      "unit_ids": [
        "cc1",
        "cc2",
        "cc3"
      ],
      "location_ids": [],
      "title_ids": [],
      "level_ids": [],
      "person_ids": []
    },
    "people": 35,
    "moves": 4,
    "facilitator": {
      "id": "p1",
      "name": "Ana Ferreira"
    },
    "participants": [
      {
        "id": "p2",
        "name": "Tomás Silva"
      },
      {
        "id": "p6",
        "name": "Marta Rocha"
      },
      {
        "id": "p7",
        "name": "Jo"
      }
    ],
    "opened_at": "2026-11-11T18:23:26.066Z",
    "locked_at": null,
    "locked_by": null,
    "reopened": [],
    "role": "facilitator",
    "can_move": true,
    "can_lock": true,
    "can_reopen": false,
    "syncing": 0
  }
}

Open a calibration session#

POST/v1/talent/calibrations.openWrite

Opens a draft session: participants can now see the population's ratings and potential (confidential) and move them with a reason; they get an email that the session is open (no names or ratings in it). Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
talent_calibrations_open on HR Assistant
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

  • calibration_idstringrequired

    1–200 characters.

Returns

18 fields
  • idstringrequired
  • namestringrequired
  • cycleobjectrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • release_onstringrequired
  • status"draft" | "open" | "locked"required
  • populationobjectrequired
    5 fields
    • unit_idsstring[]required
    • location_idsstring[]required
    • title_idsstring[]required
    • level_idsstring[]required
    • person_idsstring[]required
  • peopleintegerrequired

    People in the session.

  • movesintegerrequired

    Moves recorded so far.

  • facilitatorobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • participantsobject[]required
    2 fields
    • idstringrequired
    • namestringrequired
  • opened_atstring | nullrequired
  • locked_atstring | nullrequired
  • locked_byobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • reopenedobject[]required
    3 fields
    • byobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired
    • reasonstringrequired
  • role"facilitator" | "participant" | "hr"required

    How the caller takes part.

  • can_movebooleanrequired
  • can_lockbooleanrequired
  • can_reopenbooleanrequired
  • syncingintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/calibrations.open \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"calibration_id":"cs1"}'
Response
{
  "data": {
    "id": "cs1",
    "name": "Contact centre — agents and team leaders",
    "cycle": {
      "id": "cy1",
      "name": "Annual review 2026",
      "release_on": "2026-12-01"
    },
    "status": "open",
    "population": {
      "unit_ids": [
        "cc1",
        "cc2",
        "cc3"
      ],
      "location_ids": [],
      "title_ids": [],
      "level_ids": [],
      "person_ids": []
    },
    "people": 35,
    "moves": 4,
    "facilitator": {
      "id": "p1",
      "name": "Ana Ferreira"
    },
    "participants": [
      {
        "id": "p2",
        "name": "Tomás Silva"
      },
      {
        "id": "p6",
        "name": "Marta Rocha"
      },
      {
        "id": "p7",
        "name": "Jo"
      }
    ],
    "opened_at": "2026-11-11T18:23:26.066Z",
    "locked_at": null,
    "locked_by": null,
    "reopened": [],
    "role": "facilitator",
    "can_move": true,
    "can_lock": true,
    "can_reopen": false,
    "syncing": 0
  }
}

Move a rating or potential in calibration#

POST/v1/talent/calibrations.moveWrite

Changes one person's rating (on the cycle's scale) or potential (low, moderate, high) in an open session, with a reason of 10–500 characters; recorded as a move (who, from, to, why, when) in the session timeline. The manager's original rating stays visible. Facilitator, participants and HR. App only.

Who can call it
Manage key owner admin hr
Me key owner admin hr member
MCP tool
talent_calibrations_move on HR Assistant, 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

  • calibration_idstringrequired

    1–200 characters.

  • person_idstringrequired

    1–200 characters.

  • field"rating" | "potential"required
  • tointeger | "low" | "moderate" | "high"required

    A rating on the scale, or low/moderate/high for potential.

  • reasonstringrequired

    Why (10–500 characters); participants and HR see it, the person never does.

    Up to 2000 characters.

Returns

  • moveobjectrequired
    8 fields
    • idstringrequired
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • field"rating" | "potential"required
    • fromnumber | stringrequired
    • tonumber | stringrequired
    • reasonstringrequired
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired
  • rowobjectrequired
    17 fields
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • titlestring | nullrequired
    • title_idstring | nullrequired
    • level_idstring | nullrequired
    • locationobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • managerobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • review_idstring | nullrequired
    • manager_ratinginteger | nullrequired

      The manager's rating (kept beside the current one).

    • ratinginteger | nullrequired

      The current (calibrated) rating.

    • potential_before"low" | "moderate" | "high"required
    • potential"low" | "moderate" | "high"required
    • boxstring | nullrequired

      The 9-box: `${performance}-${potential}` (low, mid, high), or null when rating or potential is missing.

    • movedbooleanrequired
    • self_ratinginteger | nullrequired

      The person's own rating: the rounded mean of the ratings in their submitted self-review (null when none).

    • last_ratingobject | nullrequired

      The final rating of their last released review in another cycle (points: that scale's size).

      3 fields
      • ratingintegerrequired
      • pointsintegerrequired
      • cyclestringrequired
    • minebooleanrequired

      The caller manages this person (anywhere up the chain): "Hide my own reports" in the room.

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/calibrations.move \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "calibration_id": "cs1",
  "person_id": "cp2",
  "field": "potential",
  "to": "high",
  "reason": "Asked to lead the Spanish queue."
}'
Response
{
  "data": {
    "move": {
      "id": "mv9",
      "person": {
        "id": "cp1",
        "name": "Beatriz Almeida"
      },
      "field": "rating",
      "from": 4,
      "to": 4,
      "reason": "Shared targets with another team.",
      "by": {
        "id": "p1",
        "name": "Ana Ferreira"
      },
      "at": "2026-11-14T08:17:48.250Z"
    },
    "row": {
      "person": {
        "id": "cp1",
        "name": "Beatriz Almeida"
      },
      "unit": {
        "id": "cc1",
        "name": "Lisbon — Spanish queue"
      },
      "title": "Team Leader",
      "title_id": "tt-tl",
      "level_id": null,
      "location": {
        "id": "l1",
        "name": "Lisbon HQ"
      },
      "manager": {
        "id": "p7",
        "name": "Jo"
      },
      "review_id": "rv-cp1",
      "manager_rating": 5,
      "rating": 4,
      "potential_before": "high",
      "potential": "high",
      "box": "high-high",
      "moved": true,
      "self_rating": 5,
      "last_rating": {
        "rating": 5,
        "points": 5,
        "cycle": "Annual review 2025"
      },
      "mine": true
    }
  }
}

Lock a calibration session#

POST/v1/talent/calibrations.lockWrite

Locks an open session: each current rating becomes the review's final rating (people without a manager rating stay out), calibrated potential is recorded, and nothing moves any more. A reference curve, when set, never blocks or counts against the lock. Large sessions finish in parts: call talent.calibrations.sync while syncing > 0. Facilitator or HR. App only.

Who can call it
Manage key owner admin hr
MCP tool
talent_calibrations_lock on HR Assistant
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

  • calibration_idstringrequired

    1–200 characters.

Returns

18 fields
  • idstringrequired
  • namestringrequired
  • cycleobjectrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • release_onstringrequired
  • status"draft" | "open" | "locked"required
  • populationobjectrequired
    5 fields
    • unit_idsstring[]required
    • location_idsstring[]required
    • title_idsstring[]required
    • level_idsstring[]required
    • person_idsstring[]required
  • peopleintegerrequired

    People in the session.

  • movesintegerrequired

    Moves recorded so far.

  • facilitatorobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • participantsobject[]required
    2 fields
    • idstringrequired
    • namestringrequired
  • opened_atstring | nullrequired
  • locked_atstring | nullrequired
  • locked_byobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • reopenedobject[]required
    3 fields
    • byobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired
    • reasonstringrequired
  • role"facilitator" | "participant" | "hr"required

    How the caller takes part.

  • can_movebooleanrequired
  • can_lockbooleanrequired
  • can_reopenbooleanrequired
  • syncingintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/calibrations.lock \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"calibration_id":"cs1"}'
Response
{
  "data": {
    "id": "cs1",
    "name": "Contact centre — agents and team leaders",
    "cycle": {
      "id": "cy1",
      "name": "Annual review 2026",
      "release_on": "2026-12-01"
    },
    "status": "locked",
    "population": {
      "unit_ids": [
        "cc1",
        "cc2",
        "cc3"
      ],
      "location_ids": [],
      "title_ids": [],
      "level_ids": [],
      "person_ids": []
    },
    "people": 35,
    "moves": 4,
    "facilitator": {
      "id": "p1",
      "name": "Ana Ferreira"
    },
    "participants": [
      {
        "id": "p2",
        "name": "Tomás Silva"
      },
      {
        "id": "p6",
        "name": "Marta Rocha"
      },
      {
        "id": "p7",
        "name": "Jo"
      }
    ],
    "opened_at": "2026-11-11T18:23:26.066Z",
    "locked_at": null,
    "locked_by": null,
    "reopened": [],
    "role": "facilitator",
    "can_move": false,
    "can_lock": false,
    "can_reopen": true,
    "syncing": 0
  }
}

Reopen a calibration session#

POST/v1/talent/calibrations.reopenWrite

Reopens a locked session with a reason (10–500 characters), only before the cycle's release date: ratings can move again and reviews wait for the next lock. Audited. Facilitator or HR. App only.

Who can call it
Manage key owner admin hr
MCP tool
talent_calibrations_reopen on HR Assistant
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

  • calibration_idstringrequired

    1–200 characters.

  • reasonstringrequired

    Up to 2000 characters.

Returns

18 fields
  • idstringrequired
  • namestringrequired
  • cycleobjectrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • release_onstringrequired
  • status"draft" | "open" | "locked"required
  • populationobjectrequired
    5 fields
    • unit_idsstring[]required
    • location_idsstring[]required
    • title_idsstring[]required
    • level_idsstring[]required
    • person_idsstring[]required
  • peopleintegerrequired

    People in the session.

  • movesintegerrequired

    Moves recorded so far.

  • facilitatorobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • participantsobject[]required
    2 fields
    • idstringrequired
    • namestringrequired
  • opened_atstring | nullrequired
  • locked_atstring | nullrequired
  • locked_byobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • reopenedobject[]required
    3 fields
    • byobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired
    • reasonstringrequired
  • role"facilitator" | "participant" | "hr"required

    How the caller takes part.

  • can_movebooleanrequired
  • can_lockbooleanrequired
  • can_reopenbooleanrequired
  • syncingintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/calibrations.reopen \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"calibration_id":"cs1","reason":"New evidence from the manager."}'
Response
{
  "data": {
    "id": "cs1",
    "name": "Contact centre — agents and team leaders",
    "cycle": {
      "id": "cy1",
      "name": "Annual review 2026",
      "release_on": "2026-12-01"
    },
    "status": "open",
    "population": {
      "unit_ids": [
        "cc1",
        "cc2",
        "cc3"
      ],
      "location_ids": [],
      "title_ids": [],
      "level_ids": [],
      "person_ids": []
    },
    "people": 35,
    "moves": 4,
    "facilitator": {
      "id": "p1",
      "name": "Ana Ferreira"
    },
    "participants": [
      {
        "id": "p2",
        "name": "Tomás Silva"
      },
      {
        "id": "p6",
        "name": "Marta Rocha"
      },
      {
        "id": "p7",
        "name": "Jo"
      }
    ],
    "opened_at": "2026-11-11T18:23:26.066Z",
    "locked_at": null,
    "locked_by": null,
    "reopened": [],
    "role": "facilitator",
    "can_move": true,
    "can_lock": true,
    "can_reopen": false,
    "syncing": 0
  }
}

Finish updating reviews after a lock or reopen#

POST/v1/talent/calibrations.syncWrite

Writes the next part of a large session's reviews after talent.calibrations.lock or .reopen (200 a call); call again while syncing > 0. Facilitator or HR.

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

Input

  • calibration_idstringrequired

    1–200 characters.

Returns

  • idstringrequired
  • syncingintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/calibrations.sync \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"calibration_id":"cs1"}'
Response
{
  "data": {
    "id": "cs1",
    "syncing": 0
  }
}

Evidence for one person in a calibration session#

POST/v1/talent/calibrations.evidenceRead

What the room needs to judge one person: current, manager's and self rating, earlier final ratings, the manager's and self-review answers, peer themes (only when enough peers answered; never who said what), goals around the review period and this session's moves. Whoever may open the session (facilitator, participants once open, HR); never someone in the population. Confidential: app only.

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

Input

  • calibration_idstringrequired

    1–200 characters.

  • person_idstringrequired

    1–200 characters.

Returns

14 fields
  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • titlestring | nullrequired
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • managerobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • ratinginteger | nullrequired

    The current (calibrated) rating.

  • manager_ratinginteger | nullrequired
  • self_ratinginteger | nullrequired
  • potential"low" | "moderate" | "high"required
  • lastobject[]required

    Final ratings of earlier released reviews, newest first (at most 3).

    3 fields
    • cyclestringrequired
    • ratingintegerrequired
    • pointsintegerrequired
  • manager_answersobject[]required

    The submitted manager review: the notes behind the rating.

    3 fields
    • questionstringrequired
    • ratinginteger | nullrequired
    • textstring | nullrequired
  • self_answersobject[]required

    The submitted self-review.

    3 fields
    • questionstringrequired
    • ratinginteger | nullrequired
    • textstring | nullrequired
  • peersobject | nullrequired
    3 fields
    • shownbooleanrequired

      false: fewer answers than the anonymity threshold; withheld.

    • answeredintegerrequired
    • themesobject[]required

      Unattributed, shuffled: never who wrote what.

      2 fields
      • questionstringrequired
      • textsstring[]required
  • goalsobject[]required

    Their goals around the review period.

    5 fields
    • idstringrequired
    • titlestringrequired
    • progressnumberrequired
    • statusstringrequired
    • periodstringrequired
  • movesobject[]required

    Moves of this person in this session, newest first.

    8 fields
    • idstringrequired
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • field"rating" | "potential"required
    • fromnumber | stringrequired
    • tonumber | stringrequired
    • reasonstringrequired
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/calibrations.evidence \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"calibration_id":"cs1","person_id":"cp1"}'
Response
{
  "data": {
    "person": {
      "id": "cp1",
      "name": "Beatriz Almeida"
    },
    "title": "Team Leader",
    "unit": {
      "id": "cc1",
      "name": "Lisbon — Spanish queue"
    },
    "manager": {
      "id": "p7",
      "name": "Jo"
    },
    "rating": 4,
    "manager_rating": 5,
    "self_rating": 5,
    "potential": "high",
    "last": [
      {
        "cycle": "Annual review 2025",
        "rating": 5,
        "points": 5
      },
      {
        "cycle": "Annual review 2024",
        "rating": 4,
        "points": 5
      }
    ],
    "manager_answers": [
      {
        "question": "How did the goals for this period go? What made the difference?",
        "rating": 5,
        "text": "Handled the Spanish queue through the summer peak; first-contact resolution up from 71% to 78%."
      },
      {
        "question": "What should they keep doing?",
        "rating": null,
        "text": "Calm on escalations, and new joiners ask for them by name."
      },
      {
        "question": "What could they do differently or better?",
        "rating": null,
        "text": "Write up the fixes they find so the whole team can use them."
      }
    ],
    "self_answers": [
      {
        "question": "How did the goals for this period go? What made the difference?",
        "rating": 5,
        "text": "I met my handling-time goal from August and covered the night shift in September."
      }
    ],
    "peers": {
      "shown": true,
      "answered": 4,
      "themes": [
        {
          "question": "What should they keep doing?",
          "texts": [
            "Explains the why, not just the script.",
            "Always picks up the hard calls.",
            "Shares macros with the team."
          ]
        },
        {
          "question": "What could they do differently or better?",
          "texts": [
            "Could hand over earlier at shift change."
          ]
        }
      ]
    },
    "goals": [
      {
        "id": "g1",
        "title": "Average handling time under 6 minutes",
        "progress": 89,
        "status": "on_track",
        "period": "2026 Q3"
      },
      {
        "id": "g2",
        "title": "Quality score of 90% or more",
        "progress": 74,
        "status": "on_track",
        "period": "2026 Q3"
      }
    ],
    "moves": [
      {
        "id": "mv0",
        "person": {
          "id": "cp1",
          "name": "Beatriz Almeida"
        },
        "field": "rating",
        "from": 5,
        "to": 4,
        "reason": "Strong year, but the Spanish queue targets were shared with Joana’s team.",
        "by": {
          "id": "p2",
          "name": "Tomás Silva"
        },
        "at": "2026-11-14T03:29:31.480Z"
      }
    ]
  }
}

Suggest calibration sessions#

POST/v1/talent/calibrations.suggestRead

Suggests sessions for the people of a launched cycle (that uses calibration) who are in no session yet: one per department of at most 40 people; a bigger department is split into balanced parts that keep each manager's team together; departments under 5 people are pooled. Default cycle: the one with the most people left. Create them with talent.calibrations.create_suggested. Owners, admins and HR.

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

Input

  • cycle_idstring

    1–200 characters.

Returns

  • cycleobject | nullrequired

    The cycle the suggestion is for (null: no launched cycle uses calibration).

    2 fields
    • idstringrequired
    • namestringrequired
  • cyclesobject[]required

    Launched cycles that use calibration, with people in no session yet.

    3 fields
    • idstringrequired
    • namestringrequired
    • unassignedintegerrequired
  • maxintegerrequired

    People per suggested session at most.

  • unassignedintegerrequired

    People of the cycle in no session yet.

  • sessionsobject[]required
    9 fields
    • keystringrequired
    • kind"unit" | "pooled" | "none"required

      unit: one department (part of parts when split); pooled: departments under 5 people together; none: people without a team.

    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • unitsobject[]required
      2 fields
      • idstringrequired
      • namestringrequired
    • partintegerrequired
    • partsintegerrequired
    • person_idsstring[]required
    • peopleintegerrequired
    • managersobject[]required

      The direct managers who would take part.

      2 fields
      • idstringrequired
      • namestringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/calibrations.suggest \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cycle_id":"cy2"}'
Response
{
  "data": {
    "cycle": {
      "id": "cy2",
      "name": "Mid-year check 2026"
    },
    "cycles": [
      {
        "id": "cy2",
        "name": "Mid-year check 2026",
        "unassigned": 315
      },
      {
        "id": "cy1",
        "name": "Annual review 2026",
        "unassigned": 0
      }
    ],
    "max": 40,
    "unassigned": 315,
    "sessions": [
      {
        "key": "cc1:1",
        "kind": "unit",
        "unit": {
          "id": "cc1",
          "name": "Lisbon — Spanish queue"
        },
        "units": [
          {
            "id": "cc1",
            "name": "Lisbon — Spanish queue"
          }
        ],
        "part": 1,
        "parts": 3,
        "person_ids": [
          "tl1",
          "ag1-1",
          "ag1-2"
        ],
        "people": 3,
        "managers": [
          {
            "id": "p7",
            "name": "Jo"
          }
        ]
      },
      {
        "key": "cc1:2",
        "kind": "unit",
        "unit": {
          "id": "cc1",
          "name": "Lisbon — Spanish queue"
        },
        "units": [
          {
            "id": "cc1",
            "name": "Lisbon — Spanish queue"
          }
        ],
        "part": 2,
        "parts": 3,
        "person_ids": [
          "tl10",
          "ag10-1",
          "ag10-2"
        ],
        "people": 3,
        "managers": [
          {
            "id": "p7",
            "name": "Jo"
          }
        ]
      }
    ]
  }
}

Create several calibration sessions#

POST/v1/talent/calibrations.create_suggestedWrite

Creates draft sessions in one go (usually from talent.calibrations.suggest): each with a name and its people (at most 500; each person in one session per cycle). You facilitate each; the population's direct managers take part. All or nothing. Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
talent_calibrations_create_suggested on HR Assistant
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

  • cycle_idstringrequired

    1–200 characters.

  • sessionsobject[]required

    1–100 items.

    2 fields
    • namestringrequired

      1–120 characters.

    • person_idsstring[]required

      1–200 characters. 1–500 items.

Returns

  • itemsobject[]required
    18 fields
    • idstringrequired
    • namestringrequired
    • cycleobjectrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • release_onstringrequired
    • status"draft" | "open" | "locked"required
    • populationobjectrequired
      5 fields
      • unit_idsstring[]required
      • location_idsstring[]required
      • title_idsstring[]required
      • level_idsstring[]required
      • person_idsstring[]required
    • peopleintegerrequired

      People in the session.

    • movesintegerrequired

      Moves recorded so far.

    • facilitatorobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • participantsobject[]required
      2 fields
      • idstringrequired
      • namestringrequired
    • opened_atstring | nullrequired
    • locked_atstring | nullrequired
    • locked_byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • reopenedobject[]required
      3 fields
      • byobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • atstringrequired
      • reasonstringrequired
    • role"facilitator" | "participant" | "hr"required

      How the caller takes part.

    • can_movebooleanrequired
    • can_lockbooleanrequired
    • can_reopenbooleanrequired
    • syncingintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/calibrations.create_suggested \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "cycle_id": "cy2",
  "sessions": [
    {
      "name": "Lisbon — Spanish queue",
      "person_ids": [
        "ag1-1",
        "ag1-2"
      ]
    }
  ]
}'
Response
{
  "data": {
    "items": [
      {
        "id": "cs10",
        "name": "Lisbon — Spanish queue",
        "cycle": {
          "id": "cy1",
          "name": "Annual review 2026",
          "release_on": "2026-12-02"
        },
        "status": "draft",
        "population": {
          "unit_ids": [],
          "location_ids": [],
          "title_ids": [],
          "level_ids": [],
          "person_ids": []
        },
        "people": 2,
        "moves": 0,
        "facilitator": {
          "id": "p1",
          "name": "Ana Ferreira"
        },
        "participants": [
          {
            "id": "p2",
            "name": "Tomás Silva"
          }
        ],
        "opened_at": null,
        "locked_at": null,
        "locked_by": null,
        "reopened": [],
        "role": "facilitator",
        "can_move": false,
        "can_lock": false,
        "can_reopen": false,
        "syncing": 0
      }
    ]
  }
}

The 9-box#

POST/v1/talent/ninebox.getRead

Performance (the latest calibrated, locked rating, in three bands) against potential (low, moderate, high) for the people the caller may see: HR everyone (never themselves), managers their reports. Filters: unit_id (team), location_id (site), title_id, level_id, manager_id, cycle_id. Box names describe the box, never the person; each has a suggested next step. Fewer than 3 people: totals only, unless you are everyone's direct manager. Calibration sessions have their own live 9-box (talent.calibrations.get). App only (confidential).

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

Input

  • unit_idstring

    1–200 characters.

  • location_idstring

    1–200 characters.

  • title_idstring

    1–200 characters.

  • level_idstring

    1–200 characters.

  • manager_idstring

    1–200 characters.

  • cycle_idstring

    1–200 characters.

Returns

  • boxesobject[]required
    7 fields
    • keystringrequired
    • performancestringrequired
    • potentialstringrequired
    • namestringrequired
    • stepstringrequired
    • countinteger | nullrequired
    • peopleobject[] | nullrequired
      10 fields
      • idstringrequired
      • namestringrequired
      • unitobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • titlestring | nullrequired
      • locationobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • ratingintegerrequired
      • rating_labelstringrequired
      • pointsintegerrequired
      • potential"low" | "moderate" | "high"required
      • cycleobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
  • totalintegerrequired

    People placed in the grid.

  • unplacedinteger | nullrequired

    People in the filter without a locked rating or a potential.

  • small_groupbooleanrequired

    Fewer than 3 people: only the total is shown (re-identification rule).

  • filtersobjectrequired

    The choices that have people, for the filter menus.

    6 fields
    • teamsobject[]required
      2 fields
      • idstringrequired
      • namestringrequired
    • sitesobject[]required
      2 fields
      • idstringrequired
      • namestringrequired
    • titlesobject[]required
      2 fields
      • idstringrequired
      • namestringrequired
    • levelsstring[]required
    • managersobject[]required
      2 fields
      • idstringrequired
      • namestringrequired
    • cyclesobject[]required
      2 fields
      • idstringrequired
      • namestringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/ninebox.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"unit_id":"cc1","cycle_id":"cy1"}'
Response
{
  "data": {
    "boxes": [
      {
        "key": "low-high",
        "performance": "low",
        "potential": "high",
        "name": "Low performance, high potential",
        "step": "Clarify expectations and find what blocks them; check role fit.",
        "count": 0,
        "people": []
      },
      {
        "key": "mid-high",
        "performance": "mid",
        "potential": "high",
        "name": "Moderate performance, high potential",
        "step": "Develop: a stretch assignment and a mentor to turn potential into results.",
        "count": 1,
        "people": [
          {
            "id": "cp21",
            "name": "Yara Cardoso",
            "unit": {
              "id": "cc3",
              "name": "Lisbon — Retention"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l1",
              "name": "Lisbon HQ"
            },
            "rating": 3,
            "rating_label": "Meets expectations",
            "points": 5,
            "potential": "high",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          }
        ]
      },
      {
        "key": "high-high",
        "performance": "high",
        "potential": "high",
        "name": "High performance, high potential",
        "step": "Stretch role or next-level move; name as a successor and keep close.",
        "count": 7,
        "people": [
          {
            "id": "cp1",
            "name": "Beatriz Almeida",
            "unit": {
              "id": "cc1",
              "name": "Lisbon — Spanish queue"
            },
            "title": "Team Leader",
            "location": {
              "id": "l1",
              "name": "Lisbon HQ"
            },
            "rating": 4,
            "rating_label": "Exceeds expectations",
            "points": 5,
            "potential": "high",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp25",
            "name": "Catarina Gomes",
            "unit": {
              "id": "cc1",
              "name": "Lisbon — Spanish queue"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l1",
              "name": "Lisbon HQ"
            },
            "rating": 4,
            "rating_label": "Exceeds expectations",
            "points": 5,
            "potential": "high",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp5",
            "name": "Filipa Esteves",
            "unit": {
              "id": "cc2",
              "name": "Porto — Telco support"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l2",
              "name": "Porto"
            },
            "rating": 4,
            "rating_label": "Exceeds expectations",
            "points": 5,
            "potential": "high",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp32",
            "name": "Jorge Queirós",
            "unit": {
              "id": "cc2",
              "name": "Porto — Telco support"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l2",
              "name": "Porto"
            },
            "rating": 4,
            "rating_label": "Exceeds expectations",
            "points": 5,
            "potential": "high",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp10",
            "name": "Luís Macedo",
            "unit": {
              "id": "cc1",
              "name": "Lisbon — Spanish queue"
            },
            "title": "Team Leader",
            "location": {
              "id": "l1",
              "name": "Lisbon HQ"
            },
            "rating": 5,
            "rating_label": "Outstanding",
            "points": 5,
            "potential": "high",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "p4",
            "name": "Lukas Weber",
            "unit": {
              "id": "u1",
              "name": "Engineering"
            },
            "title": "Backend Engineer",
            "location": {
              "id": "l3",
              "name": "Berlin"
            },
            "rating": 4,
            "rating_label": "Exceeds expectations",
            "points": 5,
            "potential": "high",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp14",
            "name": "Pedro Queirós",
            "unit": {
              "id": "cc2",
              "name": "Porto — Telco support"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l2",
              "name": "Porto"
            },
            "rating": 4,
            "rating_label": "Exceeds expectations",
            "points": 5,
            "potential": "high",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          }
        ]
      },
      {
        "key": "low-mid",
        "performance": "low",
        "potential": "mid",
        "name": "Low performance, moderate potential",
        "step": "Clarify expectations with a short, supported improvement plan.",
        "count": 2,
        "people": [
          {
            "id": "cp29",
            "name": "Guida Neves",
            "unit": {
              "id": "cc2",
              "name": "Porto — Telco support"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l2",
              "name": "Porto"
            },
            "rating": 2,
            "rating_label": "Below expectations",
            "points": 5,
            "potential": "moderate",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp17",
            "name": "Sara Teixeira",
            "unit": {
              "id": "cc2",
              "name": "Porto — Telco support"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l2",
              "name": "Porto"
            },
            "rating": 1,
            "rating_label": "Well below expectations",
            "points": 5,
            "potential": "moderate",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          }
        ]
      },
      {
        "key": "mid-mid",
        "performance": "mid",
        "potential": "mid",
        "name": "Moderate performance, moderate potential",
        "step": "Develop in role with clear goals and regular feedback.",
        "count": 12,
        "people": [
          {
            "id": "cp24",
            "name": "Bruna Faria",
            "unit": {
              "id": "cc3",
              "name": "Lisbon — Retention"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l1",
              "name": "Lisbon HQ"
            },
            "rating": 3,
            "rating_label": "Meets expectations",
            "points": 5,
            "potential": "moderate",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp3",
            "name": "Diana Cardoso",
            "unit": {
              "id": "cc3",
              "name": "Lisbon — Retention"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l1",
              "name": "Lisbon HQ"
            },
            "rating": 3,
            "rating_label": "Meets expectations",
            "points": 5,
            "potential": "moderate",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp26",
            "name": "Duarte Henriques",
            "unit": {
              "id": "cc2",
              "name": "Porto — Telco support"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l2",
              "name": "Porto"
            },
            "rating": 3,
            "rating_label": "Meets expectations",
            "points": 5,
            "potential": "moderate",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp7",
            "name": "Helena Gomes",
            "unit": {
              "id": "cc1",
              "name": "Lisbon — Spanish queue"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l1",
              "name": "Lisbon HQ"
            },
            "rating": 3,
            "rating_label": "Meets expectations",
            "points": 5,
            "potential": "moderate",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp30",
            "name": "Hugo Oliveira",
            "unit": {
              "id": "cc3",
              "name": "Lisbon — Retention"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l1",
              "name": "Lisbon HQ"
            },
            "rating": 3,
            "rating_label": "Meets expectations",
            "points": 5,
            "potential": "moderate",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp8",
            "name": "Inês Henriques",
            "unit": {
              "id": "cc2",
              "name": "Porto — Telco support"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l2",
              "name": "Porto"
            },
            "rating": 3,
            "rating_label": "Meets expectations",
            "points": 5,
            "potential": "moderate",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp33",
            "name": "Leonor Ramos",
            "unit": {
              "id": "cc3",
              "name": "Lisbon — Retention"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l1",
              "name": "Lisbon HQ"
            },
            "rating": 3,
            "rating_label": "Meets expectations",
            "points": 5,
            "potential": "moderate",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp11",
            "name": "Mariana Neves",
            "unit": {
              "id": "cc2",
              "name": "Porto — Telco support"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l2",
              "name": "Porto"
            },
            "rating": 3,
            "rating_label": "Meets expectations",
            "points": 5,
            "potential": "moderate",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp13",
            "name": "Olga Pinto",
            "unit": {
              "id": "cc1",
              "name": "Lisbon — Spanish queue"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l1",
              "name": "Lisbon HQ"
            },
            "rating": 3,
            "rating_label": "Meets expectations",
            "points": 5,
            "potential": "moderate",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp15",
            "name": "Raquel Ramos",
            "unit": {
              "id": "cc3",
              "name": "Lisbon — Retention"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l1",
              "name": "Lisbon HQ"
            },
            "rating": 3,
            "rating_label": "Meets expectations",
            "points": 5,
            "potential": "moderate",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp18",
            "name": "Tiago Valente",
            "unit": {
              "id": "cc3",
              "name": "Lisbon — Retention"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l1",
              "name": "Lisbon HQ"
            },
            "rating": 3,
            "rating_label": "Meets expectations",
            "points": 5,
            "potential": "moderate",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp20",
            "name": "Xavier Barros",
            "unit": {
              "id": "cc2",
              "name": "Porto — Telco support"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l2",
              "name": "Porto"
            },
            "rating": 3,
            "rating_label": "Meets expectations",
            "points": 5,
            "potential": "moderate",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          }
        ]
      },
      {
        "key": "high-mid",
        "performance": "high",
        "potential": "mid",
        "name": "High performance, moderate potential",
        "step": "Grow in role with broader scope; consider for succession.",
        "count": 5,
        "people": [
          {
            "id": "cp23",
            "name": "André Esteves",
            "unit": {
              "id": "cc2",
              "name": "Porto — Telco support"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l2",
              "name": "Porto"
            },
            "rating": 4,
            "rating_label": "Exceeds expectations",
            "points": 5,
            "potential": "moderate",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp2",
            "name": "Carlos Barros",
            "unit": {
              "id": "cc2",
              "name": "Porto — Telco support"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l2",
              "name": "Porto"
            },
            "rating": 4,
            "rating_label": "Exceeds expectations",
            "points": 5,
            "potential": "moderate",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp28",
            "name": "Fábio Macedo",
            "unit": {
              "id": "cc1",
              "name": "Lisbon — Spanish queue"
            },
            "title": "Team Leader",
            "location": {
              "id": "l1",
              "name": "Lisbon HQ"
            },
            "rating": 4,
            "rating_label": "Exceeds expectations",
            "points": 5,
            "potential": "moderate",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp9",
            "name": "Joana Lima",
            "unit": {
              "id": "cc3",
              "name": "Lisbon — Retention"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l1",
              "name": "Lisbon HQ"
            },
            "rating": 4,
            "rating_label": "Exceeds expectations",
            "points": 5,
            "potential": "moderate",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp19",
            "name": "Vera Almeida",
            "unit": {
              "id": "cc1",
              "name": "Lisbon — Spanish queue"
            },
            "title": "Team Leader",
            "location": {
              "id": "l1",
              "name": "Lisbon HQ"
            },
            "rating": 4,
            "rating_label": "Exceeds expectations",
            "points": 5,
            "potential": "moderate",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          }
        ]
      },
      {
        "key": "low-low",
        "performance": "low",
        "potential": "low",
        "name": "Low performance, low potential",
        "step": "Clarify expectations and agree a plan; review role fit together.",
        "count": 2,
        "people": [
          {
            "id": "cp12",
            "name": "Nuno Oliveira",
            "unit": {
              "id": "cc3",
              "name": "Lisbon — Retention"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l1",
              "name": "Lisbon HQ"
            },
            "rating": 2,
            "rating_label": "Below expectations",
            "points": 5,
            "potential": "low",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp22",
            "name": "Zé Dias",
            "unit": {
              "id": "cc1",
              "name": "Lisbon — Spanish queue"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l1",
              "name": "Lisbon HQ"
            },
            "rating": 2,
            "rating_label": "Below expectations",
            "points": 5,
            "potential": "low",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          }
        ]
      },
      {
        "key": "mid-low",
        "performance": "mid",
        "potential": "low",
        "name": "Moderate performance, low potential",
        "step": "Keep engaged in role; agree goals that play to strengths.",
        "count": 5,
        "people": [
          {
            "id": "cp4",
            "name": "Eduardo Dias",
            "unit": {
              "id": "cc1",
              "name": "Lisbon — Spanish queue"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l1",
              "name": "Lisbon HQ"
            },
            "rating": 3,
            "rating_label": "Meets expectations",
            "points": 5,
            "potential": "low",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp27",
            "name": "Elsa Lima",
            "unit": {
              "id": "cc3",
              "name": "Lisbon — Retention"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l1",
              "name": "Lisbon HQ"
            },
            "rating": 3,
            "rating_label": "Meets expectations",
            "points": 5,
            "potential": "low",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp6",
            "name": "Gonçalo Faria",
            "unit": {
              "id": "cc3",
              "name": "Lisbon — Retention"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l1",
              "name": "Lisbon HQ"
            },
            "rating": 3,
            "rating_label": "Meets expectations",
            "points": 5,
            "potential": "low",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp31",
            "name": "Íris Pinto",
            "unit": {
              "id": "cc1",
              "name": "Lisbon — Spanish queue"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l1",
              "name": "Lisbon HQ"
            },
            "rating": 3,
            "rating_label": "Meets expectations",
            "points": 5,
            "potential": "low",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          },
          {
            "id": "cp16",
            "name": "Rui Santos",
            "unit": {
              "id": "cc1",
              "name": "Lisbon — Spanish queue"
            },
            "title": "Customer Agent",
            "location": {
              "id": "l1",
              "name": "Lisbon HQ"
            },
            "rating": 3,
            "rating_label": "Meets expectations",
            "points": 5,
            "potential": "low",
            "cycle": {
              "id": "cy1",
              "name": "Annual review 2026"
            }
          }
        ]
      },
      {
        "key": "high-low",
        "performance": "high",
        "potential": "low",
        "name": "High performance, low potential",
        "step": "Retain and recognise; use their expertise to coach others.",
        "count": 0,
        "people": []
      }
    ],
    "total": 34,
    "unplaced": 1,
    "small_group": false,
    "filters": {
      "teams": [
        {
          "id": "u1",
          "name": "Engineering"
        },
        {
          "id": "cc3",
          "name": "Lisbon — Retention"
        },
        {
          "id": "cc1",
          "name": "Lisbon — Spanish queue"
        },
        {
          "id": "cc2",
          "name": "Porto — Telco support"
        }
      ],
      "sites": [
        {
          "id": "l3",
          "name": "Berlin"
        },
        {
          "id": "l1",
          "name": "Lisbon HQ"
        },
        {
          "id": "l2",
          "name": "Porto"
        }
      ],
      "titles": [
        {
          "id": "tt-be",
          "name": "Backend Engineer"
        },
        {
          "id": "tt-ag",
          "name": "Customer Agent"
        },
        {
          "id": "tt-tl",
          "name": "Team Leader"
        }
      ],
      "levels": [],
      "managers": [
        {
          "id": "p7",
          "name": "Jo"
        },
        {
          "id": "p6",
          "name": "Marta Rocha"
        },
        {
          "id": "p2",
          "name": "Tomás Silva"
        }
      ],
      "cycles": [
        {
          "id": "cy1",
          "name": "Annual review 2026"
        }
      ]
    }
  }
}

List key positions#

POST/v1/talent/succession.positions.listRead

Key positions (a job title, optionally in one team) with why they are key, impact of loss, the incumbent's risk of loss, incumbents (empty = vacant), bench strength (successors by readiness: Covered with a ready-now successor, Thin, Uncovered) and a flag for high impact × high risk without a ready-now successor; totals with the company's bench strength (share covered). Owners, admins and HR; nobody sees a plan where they are the incumbent or a successor, except the owner. Confidential: app only.

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

Input

  • archivedboolean

Returns

  • itemsobject[]required
    12 fields
    • idstringrequired
    • titleobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • whystringrequired
    • impact"low" | "medium" | "high"required
    • riskobjectrequired
      3 fields
      • level"low" | "medium" | "high"required
      • byobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • atstringrequired
    • incumbentsobject[]required

      Who holds the title (in the team) today; empty = vacant.

      2 fields
      • idstringrequired
      • namestringrequired
    • benchobjectrequired
      4 fields
      • ready_nowintegerrequired
      • 1_2_yearsintegerrequired
      • 3_plus_yearsintegerrequired
      • status"covered" | "thin" | "uncovered"required
    • flaggedbooleanrequired

      High impact, high risk and no ready-now successor.

    • archivedbooleanrequired
    • created_atstringrequired
    • updated_atstringrequired
  • totalsobjectrequired
    4 fields
    • positionsintegerrequired
    • bench_strengthnumber | nullrequired
    • flaggedintegerrequired
    • vacantintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/succession.positions.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "items": [
      {
        "id": "kp1",
        "title": {
          "id": "tt-sm",
          "name": "Site Manager"
        },
        "unit": {
          "id": "cc1",
          "name": "Lisbon — Spanish queue"
        },
        "why": "Runs 400 agents on the Lisbon floor; the client contract names the role.",
        "impact": "high",
        "risk": {
          "level": "high",
          "by": {
            "id": "p1",
            "name": "Ana Ferreira"
          },
          "at": "2026-10-24T18:23:26.067Z"
        },
        "incumbents": [
          {
            "id": "p7",
            "name": "Jo"
          }
        ],
        "bench": {
          "ready_now": 0,
          "1_2_years": 1,
          "3_plus_years": 1,
          "status": "thin"
        },
        "flagged": true,
        "archived": false,
        "created_at": "2026-10-04T18:23:26.067Z",
        "updated_at": "2026-11-10T18:23:26.067Z"
      },
      {
        "id": "kp2",
        "title": {
          "id": "tt-wfm",
          "name": "Workforce Planning Lead"
        },
        "unit": null,
        "why": "Forecasts and plans every queue; nobody else knows the model.",
        "impact": "high",
        "risk": {
          "level": "medium",
          "by": {
            "id": "p1",
            "name": "Ana Ferreira"
          },
          "at": "2026-10-24T18:23:26.067Z"
        },
        "incumbents": [
          {
            "id": "p6",
            "name": "Marta Rocha"
          }
        ],
        "bench": {
          "ready_now": 1,
          "1_2_years": 1,
          "3_plus_years": 0,
          "status": "covered"
        },
        "flagged": false,
        "archived": false,
        "created_at": "2026-10-04T18:23:26.067Z",
        "updated_at": "2026-11-10T18:23:26.067Z"
      },
      {
        "id": "kp3",
        "title": {
          "id": "tt-qm",
          "name": "Quality Manager"
        },
        "unit": null,
        "why": "Owns the quality programme the client audits each quarter.",
        "impact": "medium",
        "risk": {
          "level": "high",
          "by": {
            "id": "p1",
            "name": "Ana Ferreira"
          },
          "at": "2026-10-24T18:23:26.067Z"
        },
        "incumbents": [],
        "bench": {
          "ready_now": 0,
          "1_2_years": 0,
          "3_plus_years": 0,
          "status": "uncovered"
        },
        "flagged": false,
        "archived": false,
        "created_at": "2026-10-04T18:23:26.067Z",
        "updated_at": "2026-11-10T18:23:26.067Z"
      },
      {
        "id": "kp4",
        "title": {
          "id": "tt-em",
          "name": "Engineering Manager"
        },
        "unit": {
          "id": "u1",
          "name": "Engineering"
        },
        "why": "Leads the platform team.",
        "impact": "medium",
        "risk": {
          "level": "low",
          "by": {
            "id": "p1",
            "name": "Ana Ferreira"
          },
          "at": "2026-10-24T18:23:26.067Z"
        },
        "incumbents": [
          {
            "id": "p2",
            "name": "Tomás Silva"
          }
        ],
        "bench": {
          "ready_now": 1,
          "1_2_years": 0,
          "3_plus_years": 0,
          "status": "covered"
        },
        "flagged": false,
        "archived": false,
        "created_at": "2026-10-04T18:23:26.067Z",
        "updated_at": "2026-11-10T18:23:26.067Z"
      }
    ],
    "totals": {
      "positions": 4,
      "bench_strength": 50,
      "flagged": 1,
      "vacant": 1
    }
  }
}

Open a key position#

POST/v1/talent/succession.positions.getRead

One key position with incumbents, successors by readiness and rank (with their latest potential, skill fit against the title's required skills and their development actions), and the required skills. Owners, admins and HR; never a plan where you are the incumbent or a successor, except the owner. App only.

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

Input

  • position_idstringrequired

    1–200 characters.

Returns

14 fields
  • idstringrequired
  • titleobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • whystringrequired
  • impact"low" | "medium" | "high"required
  • riskobjectrequired
    3 fields
    • level"low" | "medium" | "high"required
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired
  • incumbentsobject[]required

    Who holds the title (in the team) today; empty = vacant.

    2 fields
    • idstringrequired
    • namestringrequired
  • benchobjectrequired
    4 fields
    • ready_nowintegerrequired
    • 1_2_yearsintegerrequired
    • 3_plus_yearsintegerrequired
    • status"covered" | "thin" | "uncovered"required
  • flaggedbooleanrequired

    High impact, high risk and no ready-now successor.

  • archivedbooleanrequired
  • created_atstringrequired
  • updated_atstringrequired
  • successorsobject[]required
    11 fields
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • titlestring | nullrequired
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • readiness"ready_now" | "1_2_years" | "3_plus_years"required
    • rankintegerrequired
    • notestringrequired
    • potential"low" | "moderate" | "high"required
    • fitnumber | nullrequired

      Share of the position's required skills they meet (null: none required).

    • gapsobject[]required
      5 fields
      • skill_idstringrequired
      • requiredintegerrequired
      • heldinteger | nullrequired
      • gapintegerrequired
      • status"met" | "below" | "missing"required
    • actionsobject[]required
      12 fields
      • idstringrequired
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • kind"stretch" | "mentoring" | "course" | "other"required
      • titlestringrequired
      • courseobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • duestring | nullrequired
      • status"planned" | "done" | "dropped"required
      • done_by_trainingbooleanrequired

        Done because a confirmed training record of the course exists.

      • source"succession" | "review" | "manual"required

        Why it was created (HR only; null for others).

      • shared_with_personbooleanrequired
      • created_atstringrequired
      • updated_atstringrequired
    • atstringrequired
  • requiredobject[]required
    2 fields
    • skill_idstringrequired
    • levelintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/succession.positions.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"position_id":"kp1"}'
Response
{
  "data": {
    "id": "kp1",
    "title": {
      "id": "tt-sm",
      "name": "Site Manager"
    },
    "unit": {
      "id": "cc1",
      "name": "Lisbon — Spanish queue"
    },
    "why": "Runs 400 agents on the Lisbon floor; the client contract names the role.",
    "impact": "high",
    "risk": {
      "level": "high",
      "by": {
        "id": "p1",
        "name": "Ana Ferreira"
      },
      "at": "2026-10-24T18:23:26.067Z"
    },
    "incumbents": [
      {
        "id": "p7",
        "name": "Jo"
      }
    ],
    "bench": {
      "ready_now": 0,
      "1_2_years": 1,
      "3_plus_years": 1,
      "status": "thin"
    },
    "flagged": true,
    "archived": false,
    "created_at": "2026-10-04T18:23:26.067Z",
    "updated_at": "2026-11-10T18:23:26.067Z",
    "required": [
      {
        "skill_id": "sk5",
        "level": 4
      },
      {
        "skill_id": "sk7",
        "level": 3
      },
      {
        "skill_id": "sk6",
        "level": 3
      },
      {
        "skill_id": "sk3",
        "level": 2
      }
    ],
    "successors": [
      {
        "person": {
          "id": "cp10",
          "name": "Luís Macedo"
        },
        "title": "Team Leader",
        "unit": {
          "id": "cc1",
          "name": "Lisbon — Spanish queue"
        },
        "readiness": "1_2_years",
        "rank": 1,
        "note": "Leads the Spanish queue; needs workforce planning.",
        "potential": "high",
        "fit": 50,
        "gaps": [
          {
            "skill_id": "sk5",
            "required": 4,
            "held": 3,
            "gap": 1,
            "status": "below"
          },
          {
            "skill_id": "sk7",
            "required": 3,
            "held": 1,
            "gap": 2,
            "status": "below"
          },
          {
            "skill_id": "sk6",
            "required": 3,
            "held": 3,
            "gap": 0,
            "status": "met"
          },
          {
            "skill_id": "sk3",
            "required": 2,
            "held": 4,
            "gap": 0,
            "status": "met"
          }
        ],
        "actions": [
          {
            "id": "da1",
            "person": {
              "id": "cp10",
              "name": "Luís Macedo"
            },
            "kind": "course",
            "title": "Take Workforce planning essentials",
            "course": {
              "id": "tc5",
              "name": "Workforce planning essentials"
            },
            "due": "2026-12-28",
            "status": "planned",
            "done_by_training": false,
            "source": "succession",
            "shared_with_person": true,
            "created_at": "2026-11-03T18:23:26.067Z",
            "updated_at": "2026-11-11T18:23:26.067Z"
          },
          {
            "id": "da2",
            "person": {
              "id": "cp10",
              "name": "Luís Macedo"
            },
            "kind": "stretch",
            "title": "Run the Lisbon floor for two weeks in December",
            "course": null,
            "due": "2026-12-13",
            "status": "planned",
            "done_by_training": false,
            "source": "succession",
            "shared_with_person": false,
            "created_at": "2026-11-03T18:23:26.067Z",
            "updated_at": "2026-11-11T18:23:26.067Z"
          }
        ],
        "at": "2026-11-01T18:23:26.067Z"
      },
      {
        "person": {
          "id": "cp1",
          "name": "Beatriz Almeida"
        },
        "title": "Team Leader",
        "unit": {
          "id": "cc1",
          "name": "Lisbon — Spanish queue"
        },
        "readiness": "3_plus_years",
        "rank": 2,
        "note": "",
        "potential": "high",
        "fit": 25,
        "gaps": [
          {
            "skill_id": "sk5",
            "required": 4,
            "held": 2,
            "gap": 2,
            "status": "below"
          },
          {
            "skill_id": "sk7",
            "required": 3,
            "held": null,
            "gap": 3,
            "status": "missing"
          },
          {
            "skill_id": "sk6",
            "required": 3,
            "held": 2,
            "gap": 1,
            "status": "below"
          },
          {
            "skill_id": "sk3",
            "required": 2,
            "held": 4,
            "gap": 0,
            "status": "met"
          }
        ],
        "actions": [],
        "at": "2026-11-01T18:23:26.067Z"
      }
    ]
  }
}

Mark or change a key position#

POST/v1/talent/succession.positions.saveWrite

Marks a job title (optionally in one team: unit_id) as a key position, or changes one (position_id): why it is key, impact of loss and the incumbent's risk of loss (low, medium, high; HR's or the manager's judgement, dated). Up to 500; one per title and team. Owners, admins and HR. App only.

Who can call it
Manage key owner admin hr
MCP tool
talent_succession_positions_save on HR Assistant
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

  • position_idstring

    1–200 characters.

  • title_idstring

    1–200 characters.

  • unit_idstring | null

    1–200 characters.

  • whystring

    Why it is key (free text).

    Up to 2000 characters.

  • impact"low" | "medium" | "high"

    Impact of loss: low, medium or high.

  • risk"low" | "medium" | "high"

    The incumbent's risk of loss: low, medium or high.

Returns

14 fields
  • idstringrequired
  • titleobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • whystringrequired
  • impact"low" | "medium" | "high"required
  • riskobjectrequired
    3 fields
    • level"low" | "medium" | "high"required
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired
  • incumbentsobject[]required

    Who holds the title (in the team) today; empty = vacant.

    2 fields
    • idstringrequired
    • namestringrequired
  • benchobjectrequired
    4 fields
    • ready_nowintegerrequired
    • 1_2_yearsintegerrequired
    • 3_plus_yearsintegerrequired
    • status"covered" | "thin" | "uncovered"required
  • flaggedbooleanrequired

    High impact, high risk and no ready-now successor.

  • archivedbooleanrequired
  • created_atstringrequired
  • updated_atstringrequired
  • successorsobject[]required
    11 fields
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • titlestring | nullrequired
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • readiness"ready_now" | "1_2_years" | "3_plus_years"required
    • rankintegerrequired
    • notestringrequired
    • potential"low" | "moderate" | "high"required
    • fitnumber | nullrequired

      Share of the position's required skills they meet (null: none required).

    • gapsobject[]required
      5 fields
      • skill_idstringrequired
      • requiredintegerrequired
      • heldinteger | nullrequired
      • gapintegerrequired
      • status"met" | "below" | "missing"required
    • actionsobject[]required
      12 fields
      • idstringrequired
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • kind"stretch" | "mentoring" | "course" | "other"required
      • titlestringrequired
      • courseobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • duestring | nullrequired
      • status"planned" | "done" | "dropped"required
      • done_by_trainingbooleanrequired

        Done because a confirmed training record of the course exists.

      • source"succession" | "review" | "manual"required

        Why it was created (HR only; null for others).

      • shared_with_personbooleanrequired
      • created_atstringrequired
      • updated_atstringrequired
    • atstringrequired
  • requiredobject[]required
    2 fields
    • skill_idstringrequired
    • levelintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/succession.positions.save \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title_id":"tt-qm","why":"Owns quality.","impact":"high","risk":"high"}'
Response
{
  "data": {
    "id": "kp9",
    "title": {
      "id": "tt-qm",
      "name": "Quality Manager"
    },
    "unit": null,
    "why": "Owns quality.",
    "impact": "high",
    "risk": {
      "level": "high",
      "by": {
        "id": "p1",
        "name": "Ana Ferreira"
      },
      "at": "2026-10-24T18:23:26.067Z"
    },
    "incumbents": [],
    "bench": {
      "ready_now": 0,
      "1_2_years": 0,
      "3_plus_years": 0,
      "status": "uncovered"
    },
    "flagged": true,
    "archived": false,
    "created_at": "2026-10-04T18:23:26.067Z",
    "updated_at": "2026-11-10T18:23:26.067Z",
    "required": [],
    "successors": []
  }
}

Archive a key position#

POST/v1/talent/succession.positions.archiveWrite

Archives a key position that is no longer key (archived false brings it back); its successors stay with it. Owners, admins and HR.

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

Input

  • position_idstringrequired

    1–200 characters.

  • archivedboolean

    Default true.

Returns

  • idstringrequired
  • archivedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/succession.positions.archive \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"position_id":"kp1"}'
Response
{
  "data": {
    "id": "kp1",
    "archived": true
  }
}

Name or change a successor#

POST/v1/talent/succession.successors.setWrite

Names a person as a successor for a key position, or changes their readiness (ready_now, 1_2_years, 3_plus_years), rank and note. Up to 10 per position; a person may succeed to several. Not the incumbent. The person is never told. Owners, admins and HR. App only.

Who can call it
Manage key owner admin hr
MCP tool
talent_succession_successors_set on HR Assistant
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

  • position_idstringrequired

    1–200 characters.

  • person_idstringrequired

    1–200 characters.

  • readiness"ready_now" | "1_2_years" | "3_plus_years"required
  • rankinteger

    From 1 to 10.

  • notestring

    Up to 2000 characters.

Returns

14 fields
  • idstringrequired
  • titleobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • whystringrequired
  • impact"low" | "medium" | "high"required
  • riskobjectrequired
    3 fields
    • level"low" | "medium" | "high"required
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired
  • incumbentsobject[]required

    Who holds the title (in the team) today; empty = vacant.

    2 fields
    • idstringrequired
    • namestringrequired
  • benchobjectrequired
    4 fields
    • ready_nowintegerrequired
    • 1_2_yearsintegerrequired
    • 3_plus_yearsintegerrequired
    • status"covered" | "thin" | "uncovered"required
  • flaggedbooleanrequired

    High impact, high risk and no ready-now successor.

  • archivedbooleanrequired
  • created_atstringrequired
  • updated_atstringrequired
  • successorsobject[]required
    11 fields
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • titlestring | nullrequired
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • readiness"ready_now" | "1_2_years" | "3_plus_years"required
    • rankintegerrequired
    • notestringrequired
    • potential"low" | "moderate" | "high"required
    • fitnumber | nullrequired

      Share of the position's required skills they meet (null: none required).

    • gapsobject[]required
      5 fields
      • skill_idstringrequired
      • requiredintegerrequired
      • heldinteger | nullrequired
      • gapintegerrequired
      • status"met" | "below" | "missing"required
    • actionsobject[]required
      12 fields
      • idstringrequired
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • kind"stretch" | "mentoring" | "course" | "other"required
      • titlestringrequired
      • courseobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • duestring | nullrequired
      • status"planned" | "done" | "dropped"required
      • done_by_trainingbooleanrequired

        Done because a confirmed training record of the course exists.

      • source"succession" | "review" | "manual"required

        Why it was created (HR only; null for others).

      • shared_with_personbooleanrequired
      • created_atstringrequired
      • updated_atstringrequired
    • atstringrequired
  • requiredobject[]required
    2 fields
    • skill_idstringrequired
    • levelintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/succession.successors.set \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "position_id": "kp1",
  "person_id": "cp10",
  "readiness": "ready_now",
  "rank": 1,
  "note": "Ready."
}'
Response
{
  "data": {
    "id": "kp1",
    "title": {
      "id": "tt-sm",
      "name": "Site Manager"
    },
    "unit": {
      "id": "cc1",
      "name": "Lisbon — Spanish queue"
    },
    "why": "Runs 400 agents on the Lisbon floor; the client contract names the role.",
    "impact": "high",
    "risk": {
      "level": "high",
      "by": {
        "id": "p1",
        "name": "Ana Ferreira"
      },
      "at": "2026-10-24T18:23:26.067Z"
    },
    "incumbents": [
      {
        "id": "p7",
        "name": "Jo"
      }
    ],
    "bench": {
      "ready_now": 0,
      "1_2_years": 1,
      "3_plus_years": 1,
      "status": "thin"
    },
    "flagged": true,
    "archived": false,
    "created_at": "2026-10-04T18:23:26.067Z",
    "updated_at": "2026-11-10T18:23:26.067Z",
    "required": [
      {
        "skill_id": "sk5",
        "level": 4
      },
      {
        "skill_id": "sk7",
        "level": 3
      },
      {
        "skill_id": "sk6",
        "level": 3
      },
      {
        "skill_id": "sk3",
        "level": 2
      }
    ],
    "successors": [
      {
        "person": {
          "id": "cp10",
          "name": "Luís Macedo"
        },
        "title": "Team Leader",
        "unit": {
          "id": "cc1",
          "name": "Lisbon — Spanish queue"
        },
        "readiness": "1_2_years",
        "rank": 1,
        "note": "Leads the Spanish queue; needs workforce planning.",
        "potential": "high",
        "fit": 50,
        "gaps": [
          {
            "skill_id": "sk5",
            "required": 4,
            "held": 3,
            "gap": 1,
            "status": "below"
          },
          {
            "skill_id": "sk7",
            "required": 3,
            "held": 1,
            "gap": 2,
            "status": "below"
          },
          {
            "skill_id": "sk6",
            "required": 3,
            "held": 3,
            "gap": 0,
            "status": "met"
          },
          {
            "skill_id": "sk3",
            "required": 2,
            "held": 4,
            "gap": 0,
            "status": "met"
          }
        ],
        "actions": [
          {
            "id": "da1",
            "person": {
              "id": "cp10",
              "name": "Luís Macedo"
            },
            "kind": "course",
            "title": "Take Workforce planning essentials",
            "course": {
              "id": "tc5",
              "name": "Workforce planning essentials"
            },
            "due": "2026-12-28",
            "status": "planned",
            "done_by_training": false,
            "source": "succession",
            "shared_with_person": true,
            "created_at": "2026-11-03T18:23:26.067Z",
            "updated_at": "2026-11-11T18:23:26.067Z"
          },
          {
            "id": "da2",
            "person": {
              "id": "cp10",
              "name": "Luís Macedo"
            },
            "kind": "stretch",
            "title": "Run the Lisbon floor for two weeks in December",
            "course": null,
            "due": "2026-12-13",
            "status": "planned",
            "done_by_training": false,
            "source": "succession",
            "shared_with_person": false,
            "created_at": "2026-11-03T18:23:26.067Z",
            "updated_at": "2026-11-11T18:23:26.067Z"
          }
        ],
        "at": "2026-11-01T18:23:26.067Z"
      },
      {
        "person": {
          "id": "cp1",
          "name": "Beatriz Almeida"
        },
        "title": "Team Leader",
        "unit": {
          "id": "cc1",
          "name": "Lisbon — Spanish queue"
        },
        "readiness": "3_plus_years",
        "rank": 2,
        "note": "",
        "potential": "high",
        "fit": 25,
        "gaps": [
          {
            "skill_id": "sk5",
            "required": 4,
            "held": 2,
            "gap": 2,
            "status": "below"
          },
          {
            "skill_id": "sk7",
            "required": 3,
            "held": null,
            "gap": 3,
            "status": "missing"
          },
          {
            "skill_id": "sk6",
            "required": 3,
            "held": 2,
            "gap": 1,
            "status": "below"
          },
          {
            "skill_id": "sk3",
            "required": 2,
            "held": 4,
            "gap": 0,
            "status": "met"
          }
        ],
        "actions": [],
        "at": "2026-11-01T18:23:26.067Z"
      }
    ]
  }
}

Remove a successor#

POST/v1/talent/succession.successors.removeWrite

Takes a person off a key position's successors (the entry is deleted). Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
talent_succession_successors_remove on HR Assistant
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

  • position_idstringrequired

    1–200 characters.

  • person_idstringrequired

    1–200 characters.

Returns

14 fields
  • idstringrequired
  • titleobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • whystringrequired
  • impact"low" | "medium" | "high"required
  • riskobjectrequired
    3 fields
    • level"low" | "medium" | "high"required
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstringrequired
  • incumbentsobject[]required

    Who holds the title (in the team) today; empty = vacant.

    2 fields
    • idstringrequired
    • namestringrequired
  • benchobjectrequired
    4 fields
    • ready_nowintegerrequired
    • 1_2_yearsintegerrequired
    • 3_plus_yearsintegerrequired
    • status"covered" | "thin" | "uncovered"required
  • flaggedbooleanrequired

    High impact, high risk and no ready-now successor.

  • archivedbooleanrequired
  • created_atstringrequired
  • updated_atstringrequired
  • successorsobject[]required
    11 fields
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • titlestring | nullrequired
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • readiness"ready_now" | "1_2_years" | "3_plus_years"required
    • rankintegerrequired
    • notestringrequired
    • potential"low" | "moderate" | "high"required
    • fitnumber | nullrequired

      Share of the position's required skills they meet (null: none required).

    • gapsobject[]required
      5 fields
      • skill_idstringrequired
      • requiredintegerrequired
      • heldinteger | nullrequired
      • gapintegerrequired
      • status"met" | "below" | "missing"required
    • actionsobject[]required
      12 fields
      • idstringrequired
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • kind"stretch" | "mentoring" | "course" | "other"required
      • titlestringrequired
      • courseobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • duestring | nullrequired
      • status"planned" | "done" | "dropped"required
      • done_by_trainingbooleanrequired

        Done because a confirmed training record of the course exists.

      • source"succession" | "review" | "manual"required

        Why it was created (HR only; null for others).

      • shared_with_personbooleanrequired
      • created_atstringrequired
      • updated_atstringrequired
    • atstringrequired
  • requiredobject[]required
    2 fields
    • skill_idstringrequired
    • levelintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/succession.successors.remove \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"position_id":"kp1","person_id":"cp1"}'
Response
{
  "data": {
    "id": "kp1",
    "title": {
      "id": "tt-sm",
      "name": "Site Manager"
    },
    "unit": {
      "id": "cc1",
      "name": "Lisbon — Spanish queue"
    },
    "why": "Runs 400 agents on the Lisbon floor; the client contract names the role.",
    "impact": "high",
    "risk": {
      "level": "high",
      "by": {
        "id": "p1",
        "name": "Ana Ferreira"
      },
      "at": "2026-10-24T18:23:26.067Z"
    },
    "incumbents": [
      {
        "id": "p7",
        "name": "Jo"
      }
    ],
    "bench": {
      "ready_now": 0,
      "1_2_years": 1,
      "3_plus_years": 1,
      "status": "thin"
    },
    "flagged": true,
    "archived": false,
    "created_at": "2026-10-04T18:23:26.067Z",
    "updated_at": "2026-11-10T18:23:26.067Z",
    "required": [
      {
        "skill_id": "sk5",
        "level": 4
      },
      {
        "skill_id": "sk7",
        "level": 3
      },
      {
        "skill_id": "sk6",
        "level": 3
      },
      {
        "skill_id": "sk3",
        "level": 2
      }
    ],
    "successors": [
      {
        "person": {
          "id": "cp10",
          "name": "Luís Macedo"
        },
        "title": "Team Leader",
        "unit": {
          "id": "cc1",
          "name": "Lisbon — Spanish queue"
        },
        "readiness": "1_2_years",
        "rank": 1,
        "note": "Leads the Spanish queue; needs workforce planning.",
        "potential": "high",
        "fit": 50,
        "gaps": [
          {
            "skill_id": "sk5",
            "required": 4,
            "held": 3,
            "gap": 1,
            "status": "below"
          },
          {
            "skill_id": "sk7",
            "required": 3,
            "held": 1,
            "gap": 2,
            "status": "below"
          },
          {
            "skill_id": "sk6",
            "required": 3,
            "held": 3,
            "gap": 0,
            "status": "met"
          },
          {
            "skill_id": "sk3",
            "required": 2,
            "held": 4,
            "gap": 0,
            "status": "met"
          }
        ],
        "actions": [
          {
            "id": "da1",
            "person": {
              "id": "cp10",
              "name": "Luís Macedo"
            },
            "kind": "course",
            "title": "Take Workforce planning essentials",
            "course": {
              "id": "tc5",
              "name": "Workforce planning essentials"
            },
            "due": "2026-12-28",
            "status": "planned",
            "done_by_training": false,
            "source": "succession",
            "shared_with_person": true,
            "created_at": "2026-11-03T18:23:26.067Z",
            "updated_at": "2026-11-11T18:23:26.067Z"
          },
          {
            "id": "da2",
            "person": {
              "id": "cp10",
              "name": "Luís Macedo"
            },
            "kind": "stretch",
            "title": "Run the Lisbon floor for two weeks in December",
            "course": null,
            "due": "2026-12-13",
            "status": "planned",
            "done_by_training": false,
            "source": "succession",
            "shared_with_person": false,
            "created_at": "2026-11-03T18:23:26.067Z",
            "updated_at": "2026-11-11T18:23:26.067Z"
          }
        ],
        "at": "2026-11-01T18:23:26.067Z"
      },
      {
        "person": {
          "id": "cp1",
          "name": "Beatriz Almeida"
        },
        "title": "Team Leader",
        "unit": {
          "id": "cc1",
          "name": "Lisbon — Spanish queue"
        },
        "readiness": "3_plus_years",
        "rank": 2,
        "note": "",
        "potential": "high",
        "fit": 25,
        "gaps": [
          {
            "skill_id": "sk5",
            "required": 4,
            "held": 2,
            "gap": 2,
            "status": "below"
          },
          {
            "skill_id": "sk7",
            "required": 3,
            "held": null,
            "gap": 3,
            "status": "missing"
          },
          {
            "skill_id": "sk6",
            "required": 3,
            "held": 2,
            "gap": 1,
            "status": "below"
          },
          {
            "skill_id": "sk3",
            "required": 2,
            "held": 4,
            "gap": 0,
            "status": "met"
          }
        ],
        "actions": [],
        "at": "2026-11-01T18:23:26.067Z"
      }
    ]
  }
}

List development actions#

POST/v1/talent/dev_actions.listRead

Development actions (stretch assignment, mentoring, course, other) with due date and status; a course action shows done once a confirmed training record of that course ends after it was created. HR: anyone's (person_id) with why it was created; managers: their reports'; in Me, your own shared actions only (never why they were created). Machines: titles only for the caller's own.

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

Input

  • person_idstring

    Whose; default you.

    1–200 characters.

Returns

  • itemsobject[]required
    12 fields
    • idstringrequired
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • kind"stretch" | "mentoring" | "course" | "other"required
    • titlestringrequired
    • courseobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • duestring | nullrequired
    • status"planned" | "done" | "dropped"required
    • done_by_trainingbooleanrequired

      Done because a confirmed training record of the course exists.

    • source"succession" | "review" | "manual"required

      Why it was created (HR only; null for others).

    • shared_with_personbooleanrequired
    • created_atstringrequired
    • updated_atstringrequired
  • can_editbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/dev_actions.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person_id":"p4"}'
Response
{
  "data": {
    "items": [],
    "can_edit": false
  }
}

Add or change a development action#

POST/v1/talent/dev_actions.saveWrite

Adds a development action for a person (or changes one: action_id): kind stretch, mentoring, course (course_id from training_courses_list: done automatically once a confirmed record of it exists) or other; title; due date; shared_with_person (default true: they see it in Me → My development, never why it was created); source succession, review or manual with source_ref. Up to 50 per person. HR and the person's managers.

Who can call it
Manage key owner admin hr
Me key owner admin hr member
MCP tool
talent_dev_actions_save on HR Assistant, 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

  • action_idstring

    1–200 characters.

  • person_idstring

    1–200 characters.

  • kind"stretch" | "mentoring" | "course" | "other"
  • titlestring

    1–200 characters.

  • course_idstring | null

    1–200 characters.

  • duestring | null

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • shared_with_personboolean
  • source"succession" | "review" | "manual"
  • source_refstring | null

    1–200 characters.

Returns

12 fields
  • idstringrequired
  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • kind"stretch" | "mentoring" | "course" | "other"required
  • titlestringrequired
  • courseobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • duestring | nullrequired
  • status"planned" | "done" | "dropped"required
  • done_by_trainingbooleanrequired

    Done because a confirmed training record of the course exists.

  • source"succession" | "review" | "manual"required

    Why it was created (HR only; null for others).

  • shared_with_personbooleanrequired
  • 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/dev_actions.save \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "person_id": "p4",
  "kind": "course",
  "title": "Take Coaching essentials",
  "course_id": "tc1",
  "due": "2026-12-15"
}'
Response
{
  "data": {
    "id": "da9",
    "person": {
      "id": "p4",
      "name": "Lukas Weber"
    },
    "kind": "course",
    "title": "Take Coaching essentials",
    "course": null,
    "due": "2026-12-15",
    "status": "planned",
    "done_by_training": false,
    "source": "manual",
    "shared_with_person": true,
    "created_at": "2026-11-03T18:23:26.067Z",
    "updated_at": "2026-11-11T18:23:26.067Z"
  }
}

Close a development action#

POST/v1/talent/dev_actions.closeWrite

Marks a development action done or dropped (status planned reopens it). HR and the person's managers.

Who can call it
Manage key owner admin hr
Me key owner admin hr member
MCP tool
talent_dev_actions_close on HR Assistant, 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

  • action_idstringrequired

    1–200 characters.

  • status"planned" | "done" | "dropped"required

Returns

12 fields
  • idstringrequired
  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • kind"stretch" | "mentoring" | "course" | "other"required
  • titlestringrequired
  • courseobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • duestring | nullrequired
  • status"planned" | "done" | "dropped"required
  • done_by_trainingbooleanrequired

    Done because a confirmed training record of the course exists.

  • source"succession" | "review" | "manual"required

    Why it was created (HR only; null for others).

  • shared_with_personbooleanrequired
  • 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/dev_actions.close \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"action_id":"da5","status":"done"}'
Response
{
  "data": {
    "id": "da5",
    "person": {
      "id": "p4",
      "name": "Lukas Weber"
    },
    "kind": "stretch",
    "title": "Lead the billing migration",
    "course": null,
    "due": "2027-01-12",
    "status": "done",
    "done_by_training": false,
    "source": "manual",
    "shared_with_person": true,
    "created_at": "2026-11-03T18:23:26.067Z",
    "updated_at": "2026-11-11T18:23:26.067Z"
  }
}

Suggest key positions#

POST/v1/talent/succession.positions.suggestRead

Roles worth planning for, from the org chart, that are not key positions yet: managers of large teams (10+ people below them; a title several people hold is suggested in the manager's team), titles whose last holder left in the past year (vacant), and titles one person holds alone. Each with a suggested impact and risk of loss. Never your own title. Mark them with talent.succession.positions.mark_suggested. Owners, admins and HR. App only.

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

Input

No input: send {}.

Returns

  • itemsobject[]required
    9 fields
    • keystringrequired
    • titleobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • reason"large_team" | "single_holder" | "vacant"required

      large_team: the holder leads many people; single_holder: one person holds the title; vacant: the last holder left recently.

    • holderobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • teaminteger | nullrequired

      People below the holder.

    • sincestring | nullrequired

      Vacant: the last holder's last day.

    • impact"low" | "medium" | "high"required

      Suggested impact of loss.

    • risk"low" | "medium" | "high"required

      Suggested risk of loss.

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/succession.positions.suggest \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "items": [
      {
        "key": "tt-ops:",
        "title": {
          "id": "tt-ops",
          "name": "Operations Director"
        },
        "unit": null,
        "reason": "large_team",
        "holder": {
          "id": "p7",
          "name": "Jo"
        },
        "team": 118,
        "since": null,
        "impact": "high",
        "risk": "medium"
      },
      {
        "key": "tt-tl:cc2",
        "title": {
          "id": "tt-tl",
          "name": "Team Leader"
        },
        "unit": {
          "id": "cc2",
          "name": "Porto — Telco support"
        },
        "reason": "large_team",
        "holder": {
          "id": "p2",
          "name": "Tomás Silva"
        },
        "team": 14,
        "since": null,
        "impact": "medium",
        "risk": "medium"
      },
      {
        "key": "tt-trn:",
        "title": {
          "id": "tt-trn",
          "name": "Training Coordinator"
        },
        "unit": null,
        "reason": "vacant",
        "holder": null,
        "team": null,
        "since": "2026-09-30",
        "impact": "high",
        "risk": "high"
      },
      {
        "key": "tt-pay:",
        "title": {
          "id": "tt-pay",
          "name": "Payroll Specialist"
        },
        "unit": null,
        "reason": "single_holder",
        "holder": {
          "id": "p6",
          "name": "Marta Rocha"
        },
        "team": null,
        "since": null,
        "impact": "medium",
        "risk": "medium"
      }
    ]
  }
}

Mark several key positions#

POST/v1/talent/succession.positions.mark_suggestedWrite

Marks several job titles (each optionally in one team) as key positions in one go, usually from talent.succession.positions.suggest: title, team, why, impact and risk of loss for each. Same rules as talent.succession.positions.save; all or nothing. At most 50 a call, 500 in all. Owners, admins and HR. App only.

Who can call it
Manage key owner admin hr
MCP tool
talent_succession_positions_mark_suggested on HR Assistant
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

  • itemsobject[]required

    1–50 items.

    5 fields
    • title_idstringrequired

      1–200 characters.

    • unit_idstring | null

      1–200 characters.

    • whystring

      Up to 2000 characters.

    • impact"low" | "medium" | "high"required
    • risk"low" | "medium" | "high"required

Returns

  • itemsobject[]required
    12 fields
    • idstringrequired
    • titleobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • whystringrequired
    • impact"low" | "medium" | "high"required
    • riskobjectrequired
      3 fields
      • level"low" | "medium" | "high"required
      • byobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • atstringrequired
    • incumbentsobject[]required

      Who holds the title (in the team) today; empty = vacant.

      2 fields
      • idstringrequired
      • namestringrequired
    • benchobjectrequired
      4 fields
      • ready_nowintegerrequired
      • 1_2_yearsintegerrequired
      • 3_plus_yearsintegerrequired
      • status"covered" | "thin" | "uncovered"required
    • flaggedbooleanrequired

      High impact, high risk and no ready-now successor.

    • archivedbooleanrequired
    • 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/succession.positions.mark_suggested \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "items": [
    {
      "title_id": "tt-tl",
      "unit_id": "cc1",
      "why": "Leads 11 people.",
      "impact": "medium",
      "risk": "medium"
    }
  ]
}'
Response
{
  "data": {
    "items": [
      {
        "id": "kp20",
        "title": {
          "id": "tt-tl",
          "name": "Team Leader"
        },
        "unit": null,
        "why": "Owns the quality programme the client audits each quarter.",
        "impact": "medium",
        "risk": {
          "level": "medium",
          "by": {
            "id": "p1",
            "name": "Ana Ferreira"
          },
          "at": "2026-10-25T09:09:17.919Z"
        },
        "incumbents": [],
        "bench": {
          "ready_now": 0,
          "1_2_years": 0,
          "3_plus_years": 0,
          "status": "uncovered"
        },
        "flagged": false,
        "archived": false,
        "created_at": "2026-10-05T09:09:17.919Z",
        "updated_at": "2026-11-11T09:09:17.919Z"
      }
    ]
  }
}

List skills#

POST/v1/talent/skills.listRead

The company's skill catalog (name, description, category, optional ESCO link), sorted by category and name, the 4 levels (Foundation, Working, Advanced, Expert) with what each means, and whether the starter set is still on offer. Archived skills only with archived true. Everyone but viewers.

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

Input

  • qstring

    Up to 100 characters.

  • archivedboolean

Returns

  • itemsobject[]required
    8 fields
    • idstringrequired
    • namestringrequired
    • descriptionstringrequired
    • categorystringrequired
    • esco_uristring | nullrequired
    • archivedbooleanrequired
    • peopleinteger | nullrequired

      People holding it (accepted; HR only).

    • titlesinteger | nullrequired

      Job titles that require it (HR only).

  • levelsobject[]required
    3 fields
    • levelintegerrequired
    • namestringrequired
    • descriptionstringrequired
  • starter_offerbooleanrequired
  • starterobject[]required
    3 fields
    • namestringrequired
    • categorystringrequired
    • descriptionstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/skills.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"lang"}'
Response
{
  "data": {
    "items": [
      {
        "id": "sk1",
        "name": "Customer handling",
        "description": "",
        "category": "Customer",
        "esco_uri": "http://data.europa.eu/esco/skill/6a5e5f6e-3d1d-4a0b-8b1a-2d5e0d6f6c11",
        "archived": false,
        "people": 4,
        "titles": 0
      },
      {
        "id": "sk2",
        "name": "Complaint resolution",
        "description": "",
        "category": "Customer",
        "esco_uri": null,
        "archived": false,
        "people": 5,
        "titles": 1
      },
      {
        "id": "sk3",
        "name": "Spanish",
        "description": "",
        "category": "Languages",
        "esco_uri": null,
        "archived": false,
        "people": 6,
        "titles": 2
      },
      {
        "id": "sk4",
        "name": "English",
        "description": "",
        "category": "Languages",
        "esco_uri": null,
        "archived": false,
        "people": 7,
        "titles": 0
      },
      {
        "id": "sk5",
        "name": "Team leadership",
        "description": "",
        "category": "Leadership",
        "esco_uri": null,
        "archived": false,
        "people": 8,
        "titles": 1
      },
      {
        "id": "sk6",
        "name": "Coaching",
        "description": "",
        "category": "Leadership",
        "esco_uri": null,
        "archived": false,
        "people": 9,
        "titles": 2
      },
      {
        "id": "sk7",
        "name": "Workforce planning",
        "description": "",
        "category": "Operations",
        "esco_uri": null,
        "archived": false,
        "people": 10,
        "titles": 0
      },
      {
        "id": "sk8",
        "name": "Quality monitoring",
        "description": "",
        "category": "Operations",
        "esco_uri": null,
        "archived": false,
        "people": 11,
        "titles": 1
      },
      {
        "id": "sk9",
        "name": "Data analysis",
        "description": "",
        "category": "Analytics",
        "esco_uri": null,
        "archived": false,
        "people": 12,
        "titles": 2
      }
    ],
    "levels": [
      {
        "level": 1,
        "name": "Foundation",
        "description": "Knows the basics; needs guidance to apply them."
      },
      {
        "level": 2,
        "name": "Working",
        "description": "Applies it in everyday work without help."
      },
      {
        "level": 3,
        "name": "Advanced",
        "description": "Handles complex cases and helps others."
      },
      {
        "level": 4,
        "name": "Expert",
        "description": "Sets the standard; teaches and improves how it is done."
      }
    ],
    "starter_offer": false,
    "starter": []
  }
}

Add or change a skill#

POST/v1/talent/skills.saveWrite

Adds a skill to the catalog, or changes one (skill_id): name (unique), description, category, and an optional ESCO URI (http://data.europa.eu/esco/skill/…) linking it to the EU's skills taxonomy. Up to 1000 skills. Owners, admins and HR.

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

Input

  • skill_idstring

    1–200 characters.

  • namestring

    1–80 characters.

  • descriptionstring

    Up to 500 characters.

  • categorystring

    Up to 60 characters.

  • esco_uriURL | null

    Up to 300 characters.

Returns

8 fields
  • idstringrequired
  • namestringrequired
  • descriptionstringrequired
  • categorystringrequired
  • esco_uristring | nullrequired
  • archivedbooleanrequired
  • peopleinteger | nullrequired

    People holding it (accepted; HR only).

  • titlesinteger | nullrequired

    Job titles that require it (HR only).

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/skills.save \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Negotiation","category":"Customer"}'
Response
{
  "data": {
    "id": "sk99",
    "name": "Negotiation",
    "description": "",
    "category": "Customer",
    "esco_uri": "http://data.europa.eu/esco/skill/6a5e5f6e-3d1d-4a0b-8b1a-2d5e0d6f6c11",
    "archived": false,
    "people": 4,
    "titles": 0
  }
}

Add starter skills#

POST/v1/talent/skills.starterWrite

Adds the chosen skills from the starter set (names from talent_skills_list starter; all when names is left out), or none (names: []) to stop offering it. Skills with a name already in the catalog are skipped. Owners, admins and HR.

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

Input

  • namesstring[]

    Up to 80 characters. Up to 16 items.

Returns

  • addedintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/skills.starter \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"names":[]}'
Response
{
  "data": {
    "added": 3
  }
}

Archive a skill#

POST/v1/talent/skills.archiveWrite

Archives a skill (archived false brings it back): it leaves pickers; people who hold it and titles that require it keep it. Owners, admins and HR.

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

Input

  • skill_idstringrequired

    1–200 characters.

  • archivedboolean

    Default true.

Returns

8 fields
  • idstringrequired
  • namestringrequired
  • descriptionstringrequired
  • categorystringrequired
  • esco_uristring | nullrequired
  • archivedbooleanrequired
  • peopleinteger | nullrequired

    People holding it (accepted; HR only).

  • titlesinteger | nullrequired

    Job titles that require it (HR only).

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/skills.archive \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"skill_id":"sk1"}'
Response
{
  "data": {
    "id": "sk1",
    "name": "Customer handling",
    "description": "",
    "category": "Customer",
    "esco_uri": "http://data.europa.eu/esco/skill/6a5e5f6e-3d1d-4a0b-8b1a-2d5e0d6f6c11",
    "archived": true,
    "people": 4,
    "titles": 0
  }
}

Skills required by job titles#

POST/v1/talent/skills.required.listRead

The skills each job title requires, with the level (1 Foundation – 4 Expert); title_id narrows to one title. Everyone but viewers (job tier).

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

Input

  • title_idstring

    1–200 characters.

Returns

  • itemsobject[]required
    3 fields
    • title_idstringrequired
    • skill_idstringrequired
    • levelintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/skills.required.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title_id":"tt-ag"}'
Response
{
  "data": {
    "items": [
      {
        "title_id": "tt-sm",
        "skill_id": "sk5",
        "level": 4
      },
      {
        "title_id": "tt-sm",
        "skill_id": "sk7",
        "level": 3
      },
      {
        "title_id": "tt-sm",
        "skill_id": "sk6",
        "level": 3
      },
      {
        "title_id": "tt-sm",
        "skill_id": "sk3",
        "level": 2
      },
      {
        "title_id": "tt-ag",
        "skill_id": "sk1",
        "level": 2
      },
      {
        "title_id": "tt-ag",
        "skill_id": "sk3",
        "level": 3
      },
      {
        "title_id": "tt-ag",
        "skill_id": "sk4",
        "level": 2
      },
      {
        "title_id": "tt-wfm",
        "skill_id": "sk7",
        "level": 4
      },
      {
        "title_id": "tt-wfm",
        "skill_id": "sk9",
        "level": 3
      }
    ]
  }
}

Set the skills a job title requires#

POST/v1/talent/skills.required.setWrite

Replaces the skills a job title (catalog id from org_titles_list) requires, each with a level 1–4 (up to 30); an empty list clears them. Open roles with the title show them too. Owners, admins and HR.

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

Input

  • title_idstringrequired

    1–200 characters.

  • skillsobject[]required

    Up to 30 items.

    2 fields
    • skill_idstringrequired

      1–200 characters.

    • levelintegerrequired

      From 1 to 4.

Returns

  • title_idstringrequired
  • skillsobject[]required
    2 fields
    • skill_idstringrequired
    • levelintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/skills.required.set \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title_id":"tt-ag","skills":[{"skill_id":"sk1","level":2}]}'
Response
{
  "data": {
    "title_id": "tt-ag",
    "skills": [
      {
        "skill_id": "sk1",
        "level": 2
      }
    ]
  }
}

Skills training courses give#

POST/v1/talent/skills.courses.listRead

Which skills (and level) each training course gives: a confirmed training record of the course counts as that skill (shown as from training). Everyone but viewers.

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

Input

  • course_idstring

    1–200 characters.

Returns

  • itemsobject[]required
    3 fields
    • course_idstringrequired
    • skill_idstringrequired
    • levelintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/skills.courses.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "items": [
      {
        "course_id": "tc1",
        "skill_id": "sk2",
        "level": 1
      },
      {
        "course_id": "tc3",
        "skill_id": "sk4",
        "level": 3
      }
    ]
  }
}

Set the skills a course gives#

POST/v1/talent/skills.courses.setWrite

Replaces the skills a training course (training_courses_list) gives, each with a level 1–4 (up to 30); people with a confirmed record of the course then hold them (from training, derived, never stored). Owners, admins and HR.

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

Input

  • course_idstringrequired

    1–200 characters.

  • skillsobject[]required

    Up to 30 items.

    2 fields
    • skill_idstringrequired

      1–200 characters.

    • levelintegerrequired

      From 1 to 4.

Returns

  • course_idstringrequired
  • skillsobject[]required
    2 fields
    • skill_idstringrequired
    • levelintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/skills.courses.set \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"course_id":"tc1","skills":[{"skill_id":"sk2","level":1}]}'
Response
{
  "data": {
    "course_id": "tc1",
    "skills": [
      {
        "skill_id": "sk2",
        "level": 1
      }
    ]
  }
}

A person's skills#

POST/v1/talent/person_skills.listRead

Skills a person holds, per skill with every source (self-assessed, manager, training, inferred) and the level that counts (the manager's, else training or accepted inferred, else self), plus what their job title requires and the gap. Suggestions from the AI and rejected ones only for HR and their managers. The person (default: you), their managers and HR; machines see accepted levels only.

Who can call it
Manage key owner admin hr
Me key owner admin hr member
MCP tool
talent_person_skills_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

  • personobjectrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • title_idstring | nullrequired
  • itemsobject[]required
    4 fields
    • skillobjectrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • categorystringrequired
    • entriesobject[]required

      Every source; where self and manager disagree both show.

      6 fields
      • source"self" | "manager" | "training" | "inferred"required
      • levelintegerrequired
      • status"accepted" | "suggested" | "rejected"required
      • evidencestring | nullrequired
      • byobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • atstring | nullrequired
    • levelinteger | nullrequired

      The level that counts for gaps: the manager's, else training or accepted inferred, else self.

    • source"self" | "manager" | "training" | "inferred"required
  • requiredobject[]required
    6 fields
    • skill_idstringrequired
    • namestringrequired
    • requiredintegerrequired
    • heldinteger | nullrequired
    • gapintegerrequired
    • status"met" | "below" | "missing"required
  • fitnumber | nullrequired
  • can_assessbooleanrequired

    The caller may set the manager level and accept or reject suggestions.

  • can_self_assessbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/person_skills.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person_id":"p4"}'
Response
{
  "data": {
    "person": {
      "id": "p1",
      "name": "Ana Ferreira",
      "title": "Head of People",
      "title_id": "tt-be"
    },
    "items": [
      {
        "skill": {
          "id": "sk4",
          "name": "English",
          "category": "Languages"
        },
        "entries": [
          {
            "source": "self",
            "level": 4,
            "status": "accepted",
            "evidence": null,
            "by": {
              "id": "p1",
              "name": "Ana Ferreira"
            },
            "at": "2026-10-14T18:23:26.067Z"
          },
          {
            "source": "manager",
            "level": 3,
            "status": "accepted",
            "evidence": null,
            "by": {
              "id": "p2",
              "name": "Tomás Silva"
            },
            "at": "2026-10-24T18:23:26.067Z"
          }
        ],
        "level": 3,
        "source": "manager"
      },
      {
        "skill": {
          "id": "sk6",
          "name": "Coaching",
          "category": "Leadership"
        },
        "entries": [
          {
            "source": "training",
            "level": 2,
            "status": "accepted",
            "evidence": null,
            "by": null,
            "at": null
          }
        ],
        "level": 2,
        "source": "training"
      },
      {
        "skill": {
          "id": "sk9",
          "name": "Data analysis",
          "category": "Analytics"
        },
        "entries": [
          {
            "source": "self",
            "level": 2,
            "status": "accepted",
            "evidence": null,
            "by": {
              "id": "p1",
              "name": "Ana Ferreira"
            },
            "at": "2026-10-14T18:23:26.067Z"
          }
        ],
        "level": 2,
        "source": "self"
      }
    ],
    "required": [
      {
        "skill_id": "sk4",
        "name": "English",
        "required": 3,
        "held": 3,
        "gap": 0,
        "status": "met"
      },
      {
        "skill_id": "sk6",
        "name": "Coaching",
        "required": 3,
        "held": 2,
        "gap": 1,
        "status": "below"
      },
      {
        "skill_id": "sk5",
        "name": "Team leadership",
        "required": 2,
        "held": null,
        "gap": 2,
        "status": "missing"
      }
    ],
    "fit": 33,
    "can_assess": false,
    "can_self_assess": true
  }
}

Set a skill level for a person#

POST/v1/talent/person_skills.setWrite

Sets a person's level (1–4) of a skill, or removes it (level null): for yourself it is self-assessed (shown as such); for someone you manage, or as HR, it is the manager level, which counts for gaps. Up to 200 skills per person. Not by API keys or AI apps.

Who can call it
Manage key owner admin hr
Me key owner admin hr member
MCP tool
talent_person_skills_set on HR Assistant, 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

  • person_idstring

    Whose; default you.

    1–200 characters.

  • skill_idstringrequired

    1–200 characters.

  • levelinteger | nullrequired

    From 1 to 4.

  • evidencestring | null

    Up to 500 characters.

Returns

  • person_idstringrequired
  • skill_idstringrequired
  • source"self" | "manager"required
  • levelinteger | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/person_skills.set \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"person_id":"p4","skill_id":"sk4","level":null}'
Response
{
  "data": {
    "person_id": "p1",
    "skill_id": "sk4",
    "source": "self",
    "level": null
  }
}

Accept a suggested skill#

POST/v1/talent/person_skills.acceptWrite

Accepts a skill the AI suggested for a person (inferred): it then counts, shown as inferred and accepted; level may be adjusted. Their managers and HR.

Who can call it
Manage key owner admin hr
Me key owner admin hr member
MCP tool
talent_person_skills_accept on HR Assistant, 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

  • person_idstringrequired

    1–200 characters.

  • skill_idstringrequired

    1–200 characters.

  • levelinteger

    From 1 to 4.

Returns

  • person_idstringrequired
  • skill_idstringrequired
  • status"accepted" | "rejected"required
  • levelintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/person_skills.accept \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"person_id":"p4","skill_id":"sk9"}'
Response
{
  "data": {
    "person_id": "p4",
    "skill_id": "sk9",
    "status": "accepted",
    "level": 3
  }
}

Reject a suggested skill#

POST/v1/talent/person_skills.rejectWrite

Rejects a skill the AI suggested for a person: it never counts and is kept so it is not suggested again. Their managers and HR.

Who can call it
Manage key owner admin hr
Me key owner admin hr member
MCP tool
talent_person_skills_reject on HR Assistant, 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

  • person_idstringrequired

    1–200 characters.

  • skill_idstringrequired

    1–200 characters.

  • levelinteger

    From 1 to 4.

Returns

  • person_idstringrequired
  • skill_idstringrequired
  • status"accepted" | "rejected"required
  • levelintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/person_skills.reject \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"person_id":"p4","skill_id":"sk9"}'
Response
{
  "data": {
    "person_id": "p4",
    "skill_id": "sk9",
    "status": "rejected",
    "level": 3
  }
}

Skill gaps of a team#

POST/v1/talent/skills.gapsRead

For each person in a team (unit_id) or the people you manage: their title's required skills against the level that counts, the gap and the fit (share met). HR any team; managers their reports.

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

Input

  • unit_idstring

    1–200 characters.

Returns

  • peopleobject[]required
    4 fields
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • titlestring | nullrequired
    • fitnumber | nullrequired
    • gapsobject[]required
      6 fields
      • skill_idstringrequired
      • namestringrequired
      • requiredintegerrequired
      • heldinteger | nullrequired
      • gapintegerrequired
      • status"met" | "below" | "missing"required
  • skillsobject[]required
    2 fields
    • idstringrequired
    • namestringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/skills.gaps \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"unit_id":"cc1"}'
Response
{
  "data": {
    "people": [
      {
        "person": {
          "id": "cp14",
          "name": "Pedro Queirós"
        },
        "title": "Customer Agent",
        "fit": 0,
        "gaps": [
          {
            "skill_id": "sk1",
            "required": 2,
            "held": null,
            "gap": 2,
            "status": "missing",
            "name": "Customer handling"
          },
          {
            "skill_id": "sk3",
            "required": 3,
            "held": null,
            "gap": 3,
            "status": "missing",
            "name": "Spanish"
          },
          {
            "skill_id": "sk4",
            "required": 2,
            "held": null,
            "gap": 2,
            "status": "missing",
            "name": "English"
          }
        ]
      },
      {
        "person": {
          "id": "cp1",
          "name": "Beatriz Almeida"
        },
        "title": "Team Leader",
        "fit": 33,
        "gaps": [
          {
            "skill_id": "sk1",
            "required": 2,
            "held": null,
            "gap": 2,
            "status": "missing",
            "name": "Customer handling"
          },
          {
            "skill_id": "sk3",
            "required": 3,
            "held": 4,
            "gap": 0,
            "status": "met",
            "name": "Spanish"
          },
          {
            "skill_id": "sk4",
            "required": 2,
            "held": null,
            "gap": 2,
            "status": "missing",
            "name": "English"
          }
        ]
      },
      {
        "person": {
          "id": "cp4",
          "name": "Eduardo Dias"
        },
        "title": "Customer Agent",
        "fit": 33,
        "gaps": [
          {
            "skill_id": "sk1",
            "required": 2,
            "held": 2,
            "gap": 0,
            "status": "met",
            "name": "Customer handling"
          },
          {
            "skill_id": "sk3",
            "required": 3,
            "held": 2,
            "gap": 1,
            "status": "below",
            "name": "Spanish"
          },
          {
            "skill_id": "sk4",
            "required": 2,
            "held": null,
            "gap": 2,
            "status": "missing",
            "name": "English"
          }
        ]
      },
      {
        "person": {
          "id": "cp7",
          "name": "Helena Gomes"
        },
        "title": "Customer Agent",
        "fit": 33,
        "gaps": [
          {
            "skill_id": "sk1",
            "required": 2,
            "held": 2,
            "gap": 0,
            "status": "met",
            "name": "Customer handling"
          },
          {
            "skill_id": "sk3",
            "required": 3,
            "held": 2,
            "gap": 1,
            "status": "below",
            "name": "Spanish"
          },
          {
            "skill_id": "sk4",
            "required": 2,
            "held": null,
            "gap": 2,
            "status": "missing",
            "name": "English"
          }
        ]
      },
      {
        "person": {
          "id": "cp10",
          "name": "Luís Macedo"
        },
        "title": "Team Leader",
        "fit": 33,
        "gaps": [
          {
            "skill_id": "sk1",
            "required": 2,
            "held": null,
            "gap": 2,
            "status": "missing",
            "name": "Customer handling"
          },
          {
            "skill_id": "sk3",
            "required": 3,
            "held": 4,
            "gap": 0,
            "status": "met",
            "name": "Spanish"
          },
          {
            "skill_id": "sk4",
            "required": 2,
            "held": null,
            "gap": 2,
            "status": "missing",
            "name": "English"
          }
        ]
      },
      {
        "person": {
          "id": "cp2",
          "name": "Carlos Barros"
        },
        "title": "Customer Agent",
        "fit": 67,
        "gaps": [
          {
            "skill_id": "sk1",
            "required": 2,
            "held": 3,
            "gap": 0,
            "status": "met",
            "name": "Customer handling"
          },
          {
            "skill_id": "sk3",
            "required": 3,
            "held": 3,
            "gap": 0,
            "status": "met",
            "name": "Spanish"
          },
          {
            "skill_id": "sk4",
            "required": 2,
            "held": null,
            "gap": 2,
            "status": "missing",
            "name": "English"
          }
        ]
      },
      {
        "person": {
          "id": "cp3",
          "name": "Diana Cardoso"
        },
        "title": "Customer Agent",
        "fit": 67,
        "gaps": [
          {
            "skill_id": "sk1",
            "required": 2,
            "held": 3,
            "gap": 0,
            "status": "met",
            "name": "Customer handling"
          },
          {
            "skill_id": "sk3",
            "required": 3,
            "held": 3,
            "gap": 0,
            "status": "met",
            "name": "Spanish"
          },
          {
            "skill_id": "sk4",
            "required": 2,
            "held": null,
            "gap": 2,
            "status": "missing",
            "name": "English"
          }
        ]
      },
      {
        "person": {
          "id": "cp5",
          "name": "Filipa Esteves"
        },
        "title": "Customer Agent",
        "fit": 67,
        "gaps": [
          {
            "skill_id": "sk1",
            "required": 2,
            "held": 2,
            "gap": 0,
            "status": "met",
            "name": "Customer handling"
          },
          {
            "skill_id": "sk3",
            "required": 3,
            "held": 3,
            "gap": 0,
            "status": "met",
            "name": "Spanish"
          },
          {
            "skill_id": "sk4",
            "required": 2,
            "held": null,
            "gap": 2,
            "status": "missing",
            "name": "English"
          }
        ]
      },
      {
        "person": {
          "id": "cp6",
          "name": "Gonçalo Faria"
        },
        "title": "Customer Agent",
        "fit": 67,
        "gaps": [
          {
            "skill_id": "sk1",
            "required": 2,
            "held": 3,
            "gap": 0,
            "status": "met",
            "name": "Customer handling"
          },
          {
            "skill_id": "sk3",
            "required": 3,
            "held": 3,
            "gap": 0,
            "status": "met",
            "name": "Spanish"
          },
          {
            "skill_id": "sk4",
            "required": 2,
            "held": null,
            "gap": 2,
            "status": "missing",
            "name": "English"
          }
        ]
      },
      {
        "person": {
          "id": "cp8",
          "name": "Inês Henriques"
        },
        "title": "Customer Agent",
        "fit": 67,
        "gaps": [
          {
            "skill_id": "sk1",
            "required": 2,
            "held": 2,
            "gap": 0,
            "status": "met",
            "name": "Customer handling"
          },
          {
            "skill_id": "sk3",
            "required": 3,
            "held": 3,
            "gap": 0,
            "status": "met",
            "name": "Spanish"
          },
          {
            "skill_id": "sk4",
            "required": 2,
            "held": null,
            "gap": 2,
            "status": "missing",
            "name": "English"
          }
        ]
      },
      {
        "person": {
          "id": "cp9",
          "name": "Joana Lima"
        },
        "title": "Customer Agent",
        "fit": 67,
        "gaps": [
          {
            "skill_id": "sk1",
            "required": 2,
            "held": 2,
            "gap": 0,
            "status": "met",
            "name": "Customer handling"
          },
          {
            "skill_id": "sk3",
            "required": 3,
            "held": 3,
            "gap": 0,
            "status": "met",
            "name": "Spanish"
          },
          {
            "skill_id": "sk4",
            "required": 2,
            "held": null,
            "gap": 2,
            "status": "missing",
            "name": "English"
          }
        ]
      },
      {
        "person": {
          "id": "cp11",
          "name": "Mariana Neves"
        },
        "title": "Customer Agent",
        "fit": 67,
        "gaps": [
          {
            "skill_id": "sk1",
            "required": 2,
            "held": 3,
            "gap": 0,
            "status": "met",
            "name": "Customer handling"
          },
          {
            "skill_id": "sk3",
            "required": 3,
            "held": 3,
            "gap": 0,
            "status": "met",
            "name": "Spanish"
          },
          {
            "skill_id": "sk4",
            "required": 2,
            "held": null,
            "gap": 2,
            "status": "missing",
            "name": "English"
          }
        ]
      },
      {
        "person": {
          "id": "cp12",
          "name": "Nuno Oliveira"
        },
        "title": "Customer Agent",
        "fit": 67,
        "gaps": [
          {
            "skill_id": "sk1",
            "required": 2,
            "held": 3,
            "gap": 0,
            "status": "met",
            "name": "Customer handling"
          },
          {
            "skill_id": "sk3",
            "required": 3,
            "held": 3,
            "gap": 0,
            "status": "met",
            "name": "Spanish"
          },
          {
            "skill_id": "sk4",
            "required": 2,
            "held": null,
            "gap": 2,
            "status": "missing",
            "name": "English"
          }
        ]
      },
      {
        "person": {
          "id": "cp13",
          "name": "Olga Pinto"
        },
        "title": "Customer Agent",
        "fit": 67,
        "gaps": [
          {
            "skill_id": "sk1",
            "required": 2,
            "held": 2,
            "gap": 0,
            "status": "met",
            "name": "Customer handling"
          },
          {
            "skill_id": "sk3",
            "required": 3,
            "held": 3,
            "gap": 0,
            "status": "met",
            "name": "Spanish"
          },
          {
            "skill_id": "sk4",
            "required": 2,
            "held": null,
            "gap": 2,
            "status": "missing",
            "name": "English"
          }
        ]
      }
    ],
    "skills": [
      {
        "id": "sk1",
        "name": "Customer handling"
      },
      {
        "id": "sk3",
        "name": "Spanish"
      },
      {
        "id": "sk4",
        "name": "English"
      }
    ]
  }
}

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

Developer docs