Skip to content

API reference

Performance and talent

Review cycles (who, template, dates, launch, progress, reminders), review templates and rating scales, reviews and their statuses, peer reviewers, and goals with their cascade and progress. Answers, ratings and who gave feedback are never available to API keys: reviews are written in the app.

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

Talent settings#

POST/v1/talent/settings.getRead

The company's talent settings: rating scales (3–7 points with labels and one-line descriptions; default 5-point), the calibration reference curve per scale (none by default; when set, information beside the distribution, never a quota), the anonymity threshold for peer and upward feedback (at least 3), second-level sign-off, the potential guidance prompts, how many years review results are kept after a cycle closes (default 5), and, for owners, admins and HR, the works council checklist for the countries of the legal entities (never through API keys or AI assistants). Everyone but viewers reads it (forms show the scale).

Who can call it
Manage key owner admin hr
Me key owner admin hr member
Keys and apps
Without the works council checklist.
MCP tool
talent_settings_get on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

10 fields
  • scalesobject[]required
    3 fields
    • idstringrequired
    • namestringrequired
    • pointsobject[]required
      3 fields
      • valueintegerrequired
      • labelstringrequired
      • descriptionstringrequired
  • default_scale_idstringrequired
  • target_curveobjectrequired

    Per scale id: a reference distribution for calibration (percent of people per point, lowest first), shown beside the real one as information, never a quota. A scale without an entry has none (the default).

  • anonymity_minintegerrequired

    Peer and upward answers show only with at least this many (3–10).

  • second_level_signoffbooleanrequired
  • potential_guidanceobjectrequired
    3 fields
    • aspirationstringrequired
    • abilitystringrequired
    • engagementstringrequired
  • retention_yearsintegerrequired
  • consultationobject | nullrequired

    HR only.

    2 fields
    • notesobject[]required

      The works council checklist for the countries of your legal entities (informational).

      3 fields
      • countrystring | nullrequired
      • textstringrequired
      • basisstringrequired
    • doneobject | nullrequired

      Ticked "Done or not needed": who (person id) and when.

      2 fields
      • bystring | nullrequired
      • atstringrequired
  • profilesobjectrequired
    2 fields
    • onbooleanrequired

      Talent profiles are on (off by default): each person's education, certificates and experience with their history, courses and skills.

    • colleaguesbooleanrequired

      People may choose to show their profile to colleagues (on by default); off: profiles are HR and managers only.

  • goal_suggestionsobjectrequired
    4 fields
    • onbooleanrequired

      AI suggestions of measures for goals are switched on for the company.

    • availablebooleanrequired

      This server can make them (a language model is configured).

    • addendum_acceptedboolean | nullrequired

      HR only: an owner accepted the AI features addendum for goal suggestions (needed to switch on).

    • addendum_versionstring | nullrequired

      HR only: the addendum version to accept.

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/settings.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "scales": [
      {
        "id": "five",
        "name": "5-point",
        "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."
          }
        ]
      }
    ],
    "default_scale_id": "five",
    "target_curve": {
      "five": [
        10,
        20,
        40,
        20,
        10
      ]
    },
    "anonymity_min": 3,
    "second_level_signoff": false,
    "potential_guidance": {
      "aspiration": "Do they want more responsibility?",
      "ability": "Do they learn fast?",
      "engagement": "Are they committed?"
    },
    "retention_years": 5,
    "profiles": {
      "on": true,
      "colleagues": true
    },
    "consultation": {
      "notes": [
        {
          "country": "DE",
          "text": "Appraisal principles need the works council's consent.",
          "basis": "BetrVG § 94(2)"
        },
        {
          "country": null,
          "text": "Inform and consult employee representatives where national law requires.",
          "basis": "Directive 2002/14/EC"
        }
      ],
      "done": null
    },
    "goal_suggestions": {
      "on": true,
      "available": true,
      "addendum_accepted": true,
      "addendum_version": "ai-2"
    }
  }
}

Change the talent settings#

POST/v1/talent/settings.updateWrite

Changes the talent settings (only what is given): profiles ({ on, colleagues }: talent profiles on or off, and whether people may show theirs to colleagues), scales (the full list; 3–7 points each, valued 1… from the lowest; a scale a template uses can't be removed), default_scale_id, target_curve (per scale id: whole percents adding up to 100 to show a reference distribution in calibration, or null for none; no scale has one unless HR sets it; a reference never forces anything), anonymity_min (3–10: never lower than 3), second_level_signoff (the next manager up approves each review before release), potential_guidance (the three prompts), retention_years (1–10, after a cycle closes), consultation_done (true: the works council checklist is done or not needed, recorded with who and when). Launched cycles keep the scale they started with. Owners, admins and HR.

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

  • scalesobject[]

    1–10 items.

    3 fields
    • idstringrequired

      A short id, e.g. "five" or "four_point".

      Pattern ^[a-z0-9_-]{1,40}$.

    • namestringrequired

      1–60 characters.

    • pointsobject[]required

      3 to 7 points, lowest first, valued 1, 2, 3…

      3–7 items.

      3 fields
      • valueintegerrequired

        From 1 to 7.

      • labelstringrequired

        What the point is called, e.g. "Meets expectations".

        1–60 characters.

      • descriptionstringrequired

        One line shown in the form under the label.

        Up to 200 characters.

  • default_scale_idstring
  • target_curveobject
  • anonymity_mininteger

    From 3 to 10.

  • second_level_signoffboolean
  • potential_guidanceobject
    3 fields
    • aspirationstringrequired

      1–300 characters.

    • abilitystringrequired

      1–300 characters.

    • engagementstringrequired

      1–300 characters.

  • retention_yearsinteger

    From 1 to 10.

  • consultation_donetrue
  • profilesobject
    2 fields
    • onboolean

      Switch talent profiles on or off. Off hides every profile; nothing is deleted.

    • colleaguesboolean

      Let people show their profile to colleagues (each person still chooses; off: HR and managers only).

  • goal_suggestionsboolean

    Switch AI suggestions of measures for goals on or off. On needs the AI features addendum accepted by an owner (accept_addendum, on the same screen).

  • accept_addendumobject

    Owners only: accept the AI features addendum for goal suggestions (the version shown in Settings → Talent).

    2 fields
    • versionstringrequired
    • lang"en" | "de" | "es" | "fr" | "it" | "pt"

      Default "en".

Returns

10 fields
  • scalesobject[]required
    3 fields
    • idstringrequired
    • namestringrequired
    • pointsobject[]required
      3 fields
      • valueintegerrequired
      • labelstringrequired
      • descriptionstringrequired
  • default_scale_idstringrequired
  • target_curveobjectrequired

    Per scale id: a reference distribution for calibration (percent of people per point, lowest first), shown beside the real one as information, never a quota. A scale without an entry has none (the default).

  • anonymity_minintegerrequired

    Peer and upward answers show only with at least this many (3–10).

  • second_level_signoffbooleanrequired
  • potential_guidanceobjectrequired
    3 fields
    • aspirationstringrequired
    • abilitystringrequired
    • engagementstringrequired
  • retention_yearsintegerrequired
  • consultationobject | nullrequired

    HR only.

    2 fields
    • notesobject[]required

      The works council checklist for the countries of your legal entities (informational).

      3 fields
      • countrystring | nullrequired
      • textstringrequired
      • basisstringrequired
    • doneobject | nullrequired

      Ticked "Done or not needed": who (person id) and when.

      2 fields
      • bystring | nullrequired
      • atstringrequired
  • profilesobjectrequired
    2 fields
    • onbooleanrequired

      Talent profiles are on (off by default): each person's education, certificates and experience with their history, courses and skills.

    • colleaguesbooleanrequired

      People may choose to show their profile to colleagues (on by default); off: profiles are HR and managers only.

  • goal_suggestionsobjectrequired
    4 fields
    • onbooleanrequired

      AI suggestions of measures for goals are switched on for the company.

    • availablebooleanrequired

      This server can make them (a language model is configured).

    • addendum_acceptedboolean | nullrequired

      HR only: an owner accepted the AI features addendum for goal suggestions (needed to switch on).

    • addendum_versionstring | nullrequired

      HR only: the addendum version to accept.

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/settings.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "scales": [
    {
      "id": "five",
      "name": "5-point",
      "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."
        }
      ]
    }
  ],
  "target_curve": {
    "five": [
      10,
      20,
      40,
      20,
      10
    ]
  },
  "retention_years": 5,
  "consultation_done": true
}'
Response
{
  "data": {
    "scales": [
      {
        "id": "five",
        "name": "5-point",
        "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."
          }
        ]
      }
    ],
    "default_scale_id": "five",
    "target_curve": {
      "five": [
        10,
        20,
        40,
        20,
        10
      ]
    },
    "anonymity_min": 3,
    "second_level_signoff": false,
    "potential_guidance": {
      "aspiration": "Do they want more responsibility?",
      "ability": "Do they learn fast?",
      "engagement": "Are they committed?"
    },
    "retention_years": 5,
    "profiles": {
      "on": true,
      "colleagues": true
    },
    "consultation": {
      "notes": [
        {
          "country": "DE",
          "text": "Appraisal principles need the works council's consent.",
          "basis": "BetrVG § 94(2)"
        },
        {
          "country": null,
          "text": "Inform and consult employee representatives where national law requires.",
          "basis": "Directive 2002/14/EC"
        }
      ],
      "done": null
    },
    "goal_suggestions": {
      "on": true,
      "available": true,
      "addendum_accepted": true,
      "addendum_version": "ai-2"
    }
  }
}

List review templates#

POST/v1/talent/templates.listRead

The company's review templates: its saved ones and, for each starter it hasn't saved yet (Annual review, Mid-year check, Probation review, Project 360), the starter itself (id starter:<name>). Each has its steps (self, manager, peer, upward), sections of questions and scale. archived true lists archived ones. Owners, admins and HR.

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

Input

  • archivedboolean

Returns

  • itemsobject[]required
    11 fields
    • idstringrequired

      A saved template's id, or starter:<name> for a starter not saved yet.

    • namestringrequired
    • starterstring | nullrequired
    • savedbooleanrequired
    • archivedbooleanrequired
    • stepsobjectrequired
      4 fields
      • selfbooleanrequired
      • managerbooleanrequired
      • peerbooleanrequired
      • upwardbooleanrequired
    • sectionsobject[]required
      5 fields
      • idstringrequired
      • titlestringrequired
      • titlesobject
        4 fields
        • selfstring
        • managerstring
        • peerstring
        • upwardstring
      • show_goalsbooleanrequired
      • questionsobject[]required
        6 fields
        • idstringrequired
        • textstringrequired
        • textsobject

          Wording per step (self in the first person); text when absent.

          4 fields
          • selfstring
          • managerstring
          • peerstring
          • upwardstring
        • kind"rating" | "text" | "both"required
        • requiredbooleanrequired
        • for"self" | "manager" | "peer" | "upward"[]required
    • scale_idstringrequired
    • questionsintegerrequired
    • overall_ratingbooleanrequired

      The manager gives an overall rating (false: development only).

    • updated_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/templates.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"archived":true}'
Response
{
  "data": {
    "items": [
      {
        "id": "tpl1",
        "name": "Annual review",
        "starter": "annual",
        "saved": true,
        "archived": false,
        "steps": {
          "self": true,
          "manager": true,
          "peer": true,
          "upward": false
        },
        "sections": [
          {
            "id": "s1",
            "title": "Progress",
            "show_goals": true,
            "questions": [
              {
                "id": "q1",
                "text": "Where are the goals now?",
                "kind": "text",
                "required": true,
                "for": [
                  "self",
                  "manager"
                ]
              }
            ]
          },
          {
            "id": "s2",
            "title": "Overall",
            "show_goals": false,
            "questions": [
              {
                "id": "q3",
                "text": "Overall rating so far.",
                "kind": "rating",
                "required": true,
                "for": [
                  "manager"
                ]
              }
            ]
          }
        ],
        "scale_id": "five",
        "questions": 2,
        "overall_rating": true,
        "updated_at": "2026-11-14T10:00:00.000Z"
      },
      {
        "id": "starter:mid_year",
        "name": "Annual review",
        "starter": "mid_year",
        "saved": false,
        "archived": false,
        "steps": {
          "self": true,
          "manager": true,
          "peer": true,
          "upward": false
        },
        "sections": [
          {
            "id": "s1",
            "title": "Progress",
            "show_goals": true,
            "questions": [
              {
                "id": "q1",
                "text": "Where are the goals now?",
                "kind": "text",
                "required": true,
                "for": [
                  "self",
                  "manager"
                ]
              }
            ]
          },
          {
            "id": "s2",
            "title": "Overall",
            "show_goals": false,
            "questions": [
              {
                "id": "q3",
                "text": "Overall rating so far.",
                "kind": "rating",
                "required": true,
                "for": [
                  "manager"
                ]
              }
            ]
          }
        ],
        "scale_id": "five",
        "questions": 2,
        "overall_rating": true,
        "updated_at": null
      }
    ]
  }
}

Get a review template#

POST/v1/talent/templates.getRead

One review template (or starter:<name>) with its steps, sections, questions and scale. Owners, admins and HR.

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

Input

  • template_idstringrequired

Returns

11 fields
  • idstringrequired

    A saved template's id, or starter:<name> for a starter not saved yet.

  • namestringrequired
  • starterstring | nullrequired
  • savedbooleanrequired
  • archivedbooleanrequired
  • stepsobjectrequired
    4 fields
    • selfbooleanrequired
    • managerbooleanrequired
    • peerbooleanrequired
    • upwardbooleanrequired
  • sectionsobject[]required
    5 fields
    • idstringrequired
    • titlestringrequired
    • titlesobject
      4 fields
      • selfstring
      • managerstring
      • peerstring
      • upwardstring
    • show_goalsbooleanrequired
    • questionsobject[]required
      6 fields
      • idstringrequired
      • textstringrequired
      • textsobject

        Wording per step (self in the first person); text when absent.

        4 fields
        • selfstring
        • managerstring
        • peerstring
        • upwardstring
      • kind"rating" | "text" | "both"required
      • requiredbooleanrequired
      • for"self" | "manager" | "peer" | "upward"[]required
  • scale_idstringrequired
  • questionsintegerrequired
  • overall_ratingbooleanrequired

    The manager gives an overall rating (false: development only).

  • updated_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/templates.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_id":"starter:annual"}'
Response
{
  "data": {
    "id": "tpl1",
    "name": "Annual review",
    "starter": "annual",
    "saved": true,
    "archived": false,
    "steps": {
      "self": true,
      "manager": true,
      "peer": true,
      "upward": false
    },
    "sections": [
      {
        "id": "s1",
        "title": "Progress",
        "show_goals": true,
        "questions": [
          {
            "id": "q1",
            "text": "Where are the goals now?",
            "kind": "text",
            "required": true,
            "for": [
              "self",
              "manager"
            ]
          }
        ]
      },
      {
        "id": "s2",
        "title": "Overall",
        "show_goals": false,
        "questions": [
          {
            "id": "q3",
            "text": "Overall rating so far.",
            "kind": "rating",
            "required": true,
            "for": [
              "manager"
            ]
          }
        ]
      }
    ],
    "scale_id": "five",
    "questions": 2,
    "overall_rating": true,
    "updated_at": "2026-11-14T10:00:00.000Z"
  }
}

Save a review template#

POST/v1/talent/templates.saveWrite

Creates or changes a review template: name, steps (self, manager, peer, upward; manager always on), sections (title, show_goals to show the person's goals read only, questions: text, kind rating|text|both, required, for which steps), scale_id and overall_rating (false: a development-only review without an overall rating, e.g. a mid-year check or a 360). template_id: a saved template to change, or starter:<name> to save a starter as the company's own; leave out for a new one. Keep question ids when editing so cycles in draft keep their answers. Up to 50 templates, 30 questions each. Launched cycles keep the copy they started with. Owners, admins and HR.

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

Input

  • namestringrequired

    1–120 characters.

  • stepsobjectrequired

    Which steps run; the manager step is always on.

    4 fields
    • selfbooleanrequired
    • managerbooleanrequired
    • peerbooleanrequired
    • upwardbooleanrequired
  • sectionsobject[]required

    1–10 items.

    5 fields
    • idstring

      Pattern ^[a-z0-9_-]{1,40}$.

    • titlestringrequired

      1–120 characters.

    • titlesobject

      Section title per step when it differs (self: "How you work"). Empty or left out: title.

      4 fields
      • selfstring

        Up to 120 characters.

      • managerstring

        Up to 120 characters.

      • peerstring

        Up to 120 characters.

      • upwardstring

        Up to 120 characters.

    • show_goalsboolean

      Show the person's goals for the review period here (read only).

      Default false.

    • questionsobject[]required

      Up to 30 items.

      6 fields
      • idstring

        Keep the id when editing a question; leave out for a new one.

        Pattern ^[a-z0-9_-]{1,40}$.

      • textstringrequired

        The question as the manager and peers read it (about "them").

        1–500 characters.

      • textsobject

        Wording per step when it differs, e.g. self: "What should you keep doing?" (first person). Empty or left out: text.

        4 fields
        • selfstring

          Up to 500 characters.

        • managerstring

          Up to 500 characters.

        • peerstring

          Up to 500 characters.

        • upwardstring

          Up to 500 characters.

      • kind"rating" | "text" | "both"required

        rating (a point on the scale), text, or both.

      • requiredboolean

        Default true.

      • for"self" | "manager" | "peer" | "upward"[]required

        Which steps answer it: self, manager, peer, upward.

        At least 1 item.

  • scale_idstringrequired

    A scale from talent_settings_get.

  • overall_ratingboolean

    The manager gives an overall rating on the scale (default true; a starter keeps its own: off for Mid-year check and Project 360). Off: a development-only review with no overall rating, so no calibration, and salary reviews treat people as "No rating".

  • template_idstring

Returns

11 fields
  • idstringrequired

    A saved template's id, or starter:<name> for a starter not saved yet.

  • namestringrequired
  • starterstring | nullrequired
  • savedbooleanrequired
  • archivedbooleanrequired
  • stepsobjectrequired
    4 fields
    • selfbooleanrequired
    • managerbooleanrequired
    • peerbooleanrequired
    • upwardbooleanrequired
  • sectionsobject[]required
    5 fields
    • idstringrequired
    • titlestringrequired
    • titlesobject
      4 fields
      • selfstring
      • managerstring
      • peerstring
      • upwardstring
    • show_goalsbooleanrequired
    • questionsobject[]required
      6 fields
      • idstringrequired
      • textstringrequired
      • textsobject

        Wording per step (self in the first person); text when absent.

        4 fields
        • selfstring
        • managerstring
        • peerstring
        • upwardstring
      • kind"rating" | "text" | "both"required
      • requiredbooleanrequired
      • for"self" | "manager" | "peer" | "upward"[]required
  • scale_idstringrequired
  • questionsintegerrequired
  • overall_ratingbooleanrequired

    The manager gives an overall rating (false: development only).

  • updated_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/templates.save \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "template_id": "starter:annual",
  "name": "Annual review",
  "steps": {
    "self": true,
    "manager": true,
    "peer": true,
    "upward": false
  },
  "scale_id": "five",
  "sections": [
    {
      "id": "s1",
      "title": "Progress",
      "show_goals": true,
      "questions": [
        {
          "id": "q1",
          "text": "Where are the goals now?",
          "kind": "text",
          "required": true,
          "for": [
            "self",
            "manager"
          ]
        }
      ]
    },
    {
      "id": "s2",
      "title": "Overall",
      "show_goals": false,
      "questions": [
        {
          "id": "q3",
          "text": "Overall rating so far.",
          "kind": "rating",
          "required": true,
          "for": [
            "manager"
          ]
        }
      ]
    }
  ]
}'
Response
{
  "data": {
    "id": "tpl1",
    "name": "Annual review",
    "starter": "annual",
    "saved": true,
    "archived": false,
    "steps": {
      "self": true,
      "manager": true,
      "peer": true,
      "upward": false
    },
    "sections": [
      {
        "id": "s1",
        "title": "Progress",
        "show_goals": true,
        "questions": [
          {
            "id": "q1",
            "text": "Where are the goals now?",
            "kind": "text",
            "required": true,
            "for": [
              "self",
              "manager"
            ]
          }
        ]
      },
      {
        "id": "s2",
        "title": "Overall",
        "show_goals": false,
        "questions": [
          {
            "id": "q3",
            "text": "Overall rating so far.",
            "kind": "rating",
            "required": true,
            "for": [
              "manager"
            ]
          }
        ]
      }
    ],
    "scale_id": "five",
    "questions": 2,
    "overall_rating": true,
    "updated_at": "2026-11-14T10:00:00.000Z"
  }
}

Archive a review template#

POST/v1/talent/templates.archiveWrite

Archives a saved review template (archived false restores it). Cycles that used it keep their copy. Owners, admins and HR.

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

Input

  • template_idstringrequired
  • archivedboolean

    Default true.

Returns

11 fields
  • idstringrequired

    A saved template's id, or starter:<name> for a starter not saved yet.

  • namestringrequired
  • starterstring | nullrequired
  • savedbooleanrequired
  • archivedbooleanrequired
  • stepsobjectrequired
    4 fields
    • selfbooleanrequired
    • managerbooleanrequired
    • peerbooleanrequired
    • upwardbooleanrequired
  • sectionsobject[]required
    5 fields
    • idstringrequired
    • titlestringrequired
    • titlesobject
      4 fields
      • selfstring
      • managerstring
      • peerstring
      • upwardstring
    • show_goalsbooleanrequired
    • questionsobject[]required
      6 fields
      • idstringrequired
      • textstringrequired
      • textsobject

        Wording per step (self in the first person); text when absent.

        4 fields
        • selfstring
        • managerstring
        • peerstring
        • upwardstring
      • kind"rating" | "text" | "both"required
      • requiredbooleanrequired
      • for"self" | "manager" | "peer" | "upward"[]required
  • scale_idstringrequired
  • questionsintegerrequired
  • overall_ratingbooleanrequired

    The manager gives an overall rating (false: development only).

  • updated_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/templates.archive \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"template_id":"tpl1","archived":false}'
Response
{
  "data": {
    "id": "tpl1",
    "name": "Annual review",
    "starter": "annual",
    "saved": true,
    "archived": false,
    "steps": {
      "self": true,
      "manager": true,
      "peer": true,
      "upward": false
    },
    "sections": [
      {
        "id": "s1",
        "title": "Progress",
        "show_goals": true,
        "questions": [
          {
            "id": "q1",
            "text": "Where are the goals now?",
            "kind": "text",
            "required": true,
            "for": [
              "self",
              "manager"
            ]
          }
        ]
      },
      {
        "id": "s2",
        "title": "Overall",
        "show_goals": false,
        "questions": [
          {
            "id": "q3",
            "text": "Overall rating so far.",
            "kind": "rating",
            "required": true,
            "for": [
              "manager"
            ]
          }
        ]
      }
    ],
    "scale_id": "five",
    "questions": 2,
    "overall_rating": true,
    "updated_at": "2026-11-14T10:00:00.000Z"
  }
}

List review cycles#

POST/v1/talent/cycles.listRead

Review cycles: owners, admins and HR see every cycle with progress counts (self, manager, sign-off, peers, overdue); managers see the cycles where they write reviews, with their own progress; everyone else the cycles they are in (name and dates only: never whether their manager has submitted). status filters (draft, launching, active, closed, cancelled).

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

Input

  • status"draft" | "launching" | "active" | "closed" | "cancelled"

Returns

  • itemsobject[]required
    21 fields
    • idstringrequired
    • namestringrequired
    • status"draft" | "launching" | "active" | "closed" | "cancelled"required
    • templateobjectrequired
      6 fields
      • idstring | nullrequired
      • namestringrequired
      • stepsobjectrequired
        4 fields
        • selfbooleanrequired
        • managerbooleanrequired
        • peerbooleanrequired
        • upwardbooleanrequired
      • sectionsobject[]required
        5 fields
        • idstringrequired
        • titlestringrequired
        • titlesobject
          4 fields
          • selfstring
          • managerstring
          • peerstring
          • upwardstring
        • show_goalsbooleanrequired
        • questionsobject[]required
          6 fields
          • idstringrequired
          • textstringrequired
          • textsobject

            Wording per step (self in the first person); text when absent.

          • kind"rating" | "text" | "both"required
          • requiredbooleanrequired
          • for"self" | "manager" | "peer" | "upward"[]required
      • scale_idstringrequired
      • overall_ratingbooleanrequired

        The manager gives an overall rating (false: development only: no calibration, salary reviews use "No rating").

    • scaleobjectrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • pointsobject[]required
        3 fields
        • valueintegerrequired
        • labelstringrequired
        • descriptionstringrequired
    • datesobjectrequired
      7 fields
      • startstringrequired
      • nominate_bystring | nullrequired
      • self_duestring | nullrequired
      • peer_duestring | nullrequired
      • manager_duestringrequired
      • calibrate_bystring | nullrequired
      • release_onstringrequired
    • upwardbooleanrequired
    • potential_stepbooleanrequired
    • uses_calibrationbooleanrequired
    • second_levelbooleanrequired
    • populationobject | nullrequired

      HR only.

      7 fields
      • unit_idsstring[]required
      • location_idsstring[]required
      • title_idsstring[]required
      • level_idsstring[]required
      • person_idsstring[]required
      • min_tenure_daysintegerrequired
      • as_ofstringrequired
    • launchobject | nullrequired

      Reviews written so far while launching.

      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • scheduled_onstring | nullrequired

      A draft launched "on the start date": Bizisy launches it on this day (HR only).

    • schedule_problemstring | nullrequired

      Why a scheduled launch couldn't run on its day; the cycle stays a draft (HR only).

    • progressobject | nullrequired

      HR: the whole cycle; a manager: the reviews they write. Null for people in the cycle.

      8 fields
      • reviewsintegerrequired
      • selfobjectrequired
        2 fields
        • doneintegerrequired
        • totalintegerrequired
      • managerobjectrequired
        2 fields
        • doneintegerrequired
        • totalintegerrequired
      • signoffobjectrequired
        2 fields
        • doneintegerrequired
        • totalintegerrequired
      • peersobjectrequired
        2 fields
        • doneintegerrequired
        • totalintegerrequired
      • leftintegerrequired
      • overdueintegerrequired
      • releasedintegerrequired
    • by_teamobject[] | nullrequired

      HR only.

      6 fields
      • unit_idstring | nullrequired
      • namestring | nullrequired
      • reviewsintegerrequired
      • selfintegerrequired
      • managerintegerrequired
      • signoffintegerrequired
    • overdueobject[] | nullrequired

      HR only: reviews past a due date.

      4 fields
      • review_idstringrequired
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • step"self" | "manager" | "signoff"required
      • duestringrequired
    • previewobject | nullrequired

      Drafts, HR only: who it would review and what it would send.

      7 fields
      • totalintegerrequired

        People the cycle would review.

      • by_teamobject[]required
        3 fields
        • unit_idstring | nullrequired
        • namestring | nullrequired
        • countintegerrequired
      • excludedobject[]required
        2 fields
        • personobjectrequired
          2 fields
          • idstringrequired
          • namestringrequired
        • reason"not_employed" | "tenure"required
      • no_managerobject[]required

        In the cycle without a manager to review them: HR reassigns.

        2 fields
        • idstringrequired
        • namestringrequired
      • emailsobjectrequired
        2 fields
        • startedintegerrequired
        • upwardintegerrequired
      • consultationobject[]required
        3 fields
        • countrystring | nullrequired
        • textstringrequired
        • basisstringrequired
      • consultation_donebooleanrequired
    • role"hr" | "manager" | "person"required
    • created_atstringrequired
    • closed_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/cycles.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"active"}'
Response
{
  "data": {
    "items": [
      {
        "id": "cy1",
        "name": "Annual review 2026",
        "status": "active",
        "template": {
          "id": "tpl1",
          "name": "Annual review",
          "steps": {
            "self": true,
            "manager": true,
            "peer": true,
            "upward": false
          },
          "sections": [
            {
              "id": "s1",
              "title": "Progress",
              "show_goals": true,
              "questions": [
                {
                  "id": "q1",
                  "text": "Where are the goals now?",
                  "kind": "text",
                  "required": true,
                  "for": [
                    "self",
                    "manager"
                  ]
                }
              ]
            },
            {
              "id": "s2",
              "title": "Overall",
              "show_goals": false,
              "questions": [
                {
                  "id": "q3",
                  "text": "Overall rating so far.",
                  "kind": "rating",
                  "required": true,
                  "for": [
                    "manager"
                  ]
                }
              ]
            }
          ],
          "scale_id": "five",
          "overall_rating": true
        },
        "scale": {
          "id": "five",
          "name": "5-point",
          "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."
            }
          ]
        },
        "dates": {
          "start": "2026-11-16",
          "nominate_by": "2026-11-18",
          "self_due": "2026-11-25",
          "peer_due": "2026-11-24",
          "manager_due": "2026-11-30",
          "calibrate_by": null,
          "release_on": "2026-12-02"
        },
        "upward": false,
        "potential_step": false,
        "uses_calibration": true,
        "second_level": false,
        "population": {
          "unit_ids": [],
          "location_ids": [],
          "title_ids": [],
          "level_ids": [],
          "person_ids": [],
          "min_tenure_days": 90,
          "as_of": "2026-11-16"
        },
        "launch": {
          "done": 412,
          "total": 412
        },
        "scheduled_on": null,
        "schedule_problem": null,
        "progress": {
          "reviews": 412,
          "self": {
            "done": 300,
            "total": 410
          },
          "manager": {
            "done": 120,
            "total": 410
          },
          "signoff": {
            "done": 0,
            "total": 0
          },
          "peers": {
            "done": 800,
            "total": 1200
          },
          "left": 2,
          "overdue": 14,
          "released": 0
        },
        "by_team": [
          {
            "unit_id": "u1",
            "name": "Customer care",
            "reviews": 200,
            "self": 150,
            "manager": 60,
            "signoff": 0
          }
        ],
        "overdue": [
          {
            "review_id": "rv1",
            "person": {
              "id": "p2",
              "name": "Tomás Silva"
            },
            "step": "self",
            "due": "2026-11-25"
          }
        ],
        "preview": null,
        "role": "hr",
        "created_at": "2026-11-14T10:00:00.000Z",
        "closed_at": null
      }
    ]
  }
}

Get a review cycle#

POST/v1/talent/cycles.getRead

One review cycle: template, scale and dates; for owners, admins and HR also who is in it, progress by team and step, overdue reviews and, for a draft, the preview (counts per team, people left out and why, people without a manager, emails it will send, the works council checklist). Managers see the progress of the reviews they write; people in the cycle its dates only.

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

Input

  • cycle_idstringrequired

Returns

21 fields
  • idstringrequired
  • namestringrequired
  • status"draft" | "launching" | "active" | "closed" | "cancelled"required
  • templateobjectrequired
    6 fields
    • idstring | nullrequired
    • namestringrequired
    • stepsobjectrequired
      4 fields
      • selfbooleanrequired
      • managerbooleanrequired
      • peerbooleanrequired
      • upwardbooleanrequired
    • sectionsobject[]required
      5 fields
      • idstringrequired
      • titlestringrequired
      • titlesobject
        4 fields
        • selfstring
        • managerstring
        • peerstring
        • upwardstring
      • show_goalsbooleanrequired
      • questionsobject[]required
        6 fields
        • idstringrequired
        • textstringrequired
        • textsobject

          Wording per step (self in the first person); text when absent.

          4 fields
          • selfstring
          • managerstring
          • peerstring
          • upwardstring
        • kind"rating" | "text" | "both"required
        • requiredbooleanrequired
        • for"self" | "manager" | "peer" | "upward"[]required
    • scale_idstringrequired
    • overall_ratingbooleanrequired

      The manager gives an overall rating (false: development only: no calibration, salary reviews use "No rating").

  • scaleobjectrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • pointsobject[]required
      3 fields
      • valueintegerrequired
      • labelstringrequired
      • descriptionstringrequired
  • datesobjectrequired
    7 fields
    • startstringrequired
    • nominate_bystring | nullrequired
    • self_duestring | nullrequired
    • peer_duestring | nullrequired
    • manager_duestringrequired
    • calibrate_bystring | nullrequired
    • release_onstringrequired
  • upwardbooleanrequired
  • potential_stepbooleanrequired
  • uses_calibrationbooleanrequired
  • second_levelbooleanrequired
  • populationobject | nullrequired

    HR only.

    7 fields
    • unit_idsstring[]required
    • location_idsstring[]required
    • title_idsstring[]required
    • level_idsstring[]required
    • person_idsstring[]required
    • min_tenure_daysintegerrequired
    • as_ofstringrequired
  • launchobject | nullrequired

    Reviews written so far while launching.

    2 fields
    • doneintegerrequired
    • totalintegerrequired
  • scheduled_onstring | nullrequired

    A draft launched "on the start date": Bizisy launches it on this day (HR only).

  • schedule_problemstring | nullrequired

    Why a scheduled launch couldn't run on its day; the cycle stays a draft (HR only).

  • progressobject | nullrequired

    HR: the whole cycle; a manager: the reviews they write. Null for people in the cycle.

    8 fields
    • reviewsintegerrequired
    • selfobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • managerobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • signoffobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • peersobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • leftintegerrequired
    • overdueintegerrequired
    • releasedintegerrequired
  • by_teamobject[] | nullrequired

    HR only.

    6 fields
    • unit_idstring | nullrequired
    • namestring | nullrequired
    • reviewsintegerrequired
    • selfintegerrequired
    • managerintegerrequired
    • signoffintegerrequired
  • overdueobject[] | nullrequired

    HR only: reviews past a due date.

    4 fields
    • review_idstringrequired
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • step"self" | "manager" | "signoff"required
    • duestringrequired
  • previewobject | nullrequired

    Drafts, HR only: who it would review and what it would send.

    7 fields
    • totalintegerrequired

      People the cycle would review.

    • by_teamobject[]required
      3 fields
      • unit_idstring | nullrequired
      • namestring | nullrequired
      • countintegerrequired
    • excludedobject[]required
      2 fields
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • reason"not_employed" | "tenure"required
    • no_managerobject[]required

      In the cycle without a manager to review them: HR reassigns.

      2 fields
      • idstringrequired
      • namestringrequired
    • emailsobjectrequired
      2 fields
      • startedintegerrequired
      • upwardintegerrequired
    • consultationobject[]required
      3 fields
      • countrystring | nullrequired
      • textstringrequired
      • basisstringrequired
    • consultation_donebooleanrequired
  • role"hr" | "manager" | "person"required
  • created_atstringrequired
  • closed_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/cycles.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cycle_id":"cy1"}'
Response
{
  "data": {
    "id": "cy1",
    "name": "Annual review 2026",
    "status": "active",
    "template": {
      "id": "tpl1",
      "name": "Annual review",
      "steps": {
        "self": true,
        "manager": true,
        "peer": true,
        "upward": false
      },
      "sections": [
        {
          "id": "s1",
          "title": "Progress",
          "show_goals": true,
          "questions": [
            {
              "id": "q1",
              "text": "Where are the goals now?",
              "kind": "text",
              "required": true,
              "for": [
                "self",
                "manager"
              ]
            }
          ]
        },
        {
          "id": "s2",
          "title": "Overall",
          "show_goals": false,
          "questions": [
            {
              "id": "q3",
              "text": "Overall rating so far.",
              "kind": "rating",
              "required": true,
              "for": [
                "manager"
              ]
            }
          ]
        }
      ],
      "scale_id": "five",
      "overall_rating": true
    },
    "scale": {
      "id": "five",
      "name": "5-point",
      "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."
        }
      ]
    },
    "dates": {
      "start": "2026-11-16",
      "nominate_by": "2026-11-18",
      "self_due": "2026-11-25",
      "peer_due": "2026-11-24",
      "manager_due": "2026-11-30",
      "calibrate_by": null,
      "release_on": "2026-12-02"
    },
    "upward": false,
    "potential_step": false,
    "uses_calibration": true,
    "second_level": false,
    "population": {
      "unit_ids": [],
      "location_ids": [],
      "title_ids": [],
      "level_ids": [],
      "person_ids": [],
      "min_tenure_days": 90,
      "as_of": "2026-11-16"
    },
    "launch": {
      "done": 412,
      "total": 412
    },
    "scheduled_on": null,
    "schedule_problem": null,
    "progress": {
      "reviews": 412,
      "self": {
        "done": 300,
        "total": 410
      },
      "manager": {
        "done": 120,
        "total": 410
      },
      "signoff": {
        "done": 0,
        "total": 0
      },
      "peers": {
        "done": 800,
        "total": 1200
      },
      "left": 2,
      "overdue": 14,
      "released": 0
    },
    "by_team": [
      {
        "unit_id": "u1",
        "name": "Customer care",
        "reviews": 200,
        "self": 150,
        "manager": 60,
        "signoff": 0
      }
    ],
    "overdue": [
      {
        "review_id": "rv1",
        "person": {
          "id": "p2",
          "name": "Tomás Silva"
        },
        "step": "self",
        "due": "2026-11-25"
      }
    ],
    "preview": null,
    "role": "hr",
    "created_at": "2026-11-14T10:00:00.000Z",
    "closed_at": null
  }
}

Create a review cycle#

POST/v1/talent/cycles.createWrite

Creates a review cycle as a draft (D3's four steps): who (population: teams, sites, titles, levels or a list; minimum tenure, default 90 days), what (template_id: a template or starter; the cycle keeps a copy), when (dates: start, nominate_by and peer_due when peers are on, self_due, manager_due, calibrate_by, release_on, in order), upward, potential_step, uses_calibration. Returns the preview (counts per team, people left out with the reason, emails, the works council checklist); launch it with talent_cycles_launch. Up to 10 cycles running at once. Owners, admins and HR.

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

Input

  • namestringrequired

    e.g. "Annual review 2026".

    1–120 characters.

  • template_idstringrequired

    A template id or starter:<name> (talent_templates_list); the cycle keeps a copy.

  • populationobject
    7 fields
    • unit_idsstring[]

      Teams (people directly in them).

      1–200 characters. Up to 200 items.

    • location_idsstring[]

      Sites.

      1–200 characters. Up to 200 items.

    • title_idsstring[]

      Job titles from the catalog.

      1–200 characters. Up to 200 items.

    • level_idsstring[]

      Levels from the catalog.

      1–200 characters. Up to 200 items.

    • person_idsstring[]

      A list of people (with the filters: only those also matching them).

      1–200 characters. Up to 5000 items.

    • min_tenure_daysinteger

      Leave out people who joined fewer than this many days before the as-of date (default 90).

      From 0 to 730. Default 90.

    • as_ofstring

      Employed on this day (default today).

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

  • datesobjectrequired
    7 fields
    • startstringrequired

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

    • nominate_bystring | null

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

    • self_duestring | null

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

    • peer_duestring | null

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

    • manager_duestringrequired

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

    • calibrate_bystring | null

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

    • release_onstringrequired

      People see their review from this day, once signed off (and calibrated when the cycle uses calibration).

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

  • upwardboolean

    Reports give upward feedback on their manager (the template's upward step).

  • potential_stepboolean

    The manager step also asks for the person's potential.

  • uses_calibrationboolean

    Ratings are released only after a locked calibration session.

Returns

21 fields
  • idstringrequired
  • namestringrequired
  • status"draft" | "launching" | "active" | "closed" | "cancelled"required
  • templateobjectrequired
    6 fields
    • idstring | nullrequired
    • namestringrequired
    • stepsobjectrequired
      4 fields
      • selfbooleanrequired
      • managerbooleanrequired
      • peerbooleanrequired
      • upwardbooleanrequired
    • sectionsobject[]required
      5 fields
      • idstringrequired
      • titlestringrequired
      • titlesobject
        4 fields
        • selfstring
        • managerstring
        • peerstring
        • upwardstring
      • show_goalsbooleanrequired
      • questionsobject[]required
        6 fields
        • idstringrequired
        • textstringrequired
        • textsobject

          Wording per step (self in the first person); text when absent.

          4 fields
          • selfstring
          • managerstring
          • peerstring
          • upwardstring
        • kind"rating" | "text" | "both"required
        • requiredbooleanrequired
        • for"self" | "manager" | "peer" | "upward"[]required
    • scale_idstringrequired
    • overall_ratingbooleanrequired

      The manager gives an overall rating (false: development only: no calibration, salary reviews use "No rating").

  • scaleobjectrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • pointsobject[]required
      3 fields
      • valueintegerrequired
      • labelstringrequired
      • descriptionstringrequired
  • datesobjectrequired
    7 fields
    • startstringrequired
    • nominate_bystring | nullrequired
    • self_duestring | nullrequired
    • peer_duestring | nullrequired
    • manager_duestringrequired
    • calibrate_bystring | nullrequired
    • release_onstringrequired
  • upwardbooleanrequired
  • potential_stepbooleanrequired
  • uses_calibrationbooleanrequired
  • second_levelbooleanrequired
  • populationobject | nullrequired

    HR only.

    7 fields
    • unit_idsstring[]required
    • location_idsstring[]required
    • title_idsstring[]required
    • level_idsstring[]required
    • person_idsstring[]required
    • min_tenure_daysintegerrequired
    • as_ofstringrequired
  • launchobject | nullrequired

    Reviews written so far while launching.

    2 fields
    • doneintegerrequired
    • totalintegerrequired
  • scheduled_onstring | nullrequired

    A draft launched "on the start date": Bizisy launches it on this day (HR only).

  • schedule_problemstring | nullrequired

    Why a scheduled launch couldn't run on its day; the cycle stays a draft (HR only).

  • progressobject | nullrequired

    HR: the whole cycle; a manager: the reviews they write. Null for people in the cycle.

    8 fields
    • reviewsintegerrequired
    • selfobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • managerobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • signoffobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • peersobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • leftintegerrequired
    • overdueintegerrequired
    • releasedintegerrequired
  • by_teamobject[] | nullrequired

    HR only.

    6 fields
    • unit_idstring | nullrequired
    • namestring | nullrequired
    • reviewsintegerrequired
    • selfintegerrequired
    • managerintegerrequired
    • signoffintegerrequired
  • overdueobject[] | nullrequired

    HR only: reviews past a due date.

    4 fields
    • review_idstringrequired
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • step"self" | "manager" | "signoff"required
    • duestringrequired
  • previewobject | nullrequired

    Drafts, HR only: who it would review and what it would send.

    7 fields
    • totalintegerrequired

      People the cycle would review.

    • by_teamobject[]required
      3 fields
      • unit_idstring | nullrequired
      • namestring | nullrequired
      • countintegerrequired
    • excludedobject[]required
      2 fields
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • reason"not_employed" | "tenure"required
    • no_managerobject[]required

      In the cycle without a manager to review them: HR reassigns.

      2 fields
      • idstringrequired
      • namestringrequired
    • emailsobjectrequired
      2 fields
      • startedintegerrequired
      • upwardintegerrequired
    • consultationobject[]required
      3 fields
      • countrystring | nullrequired
      • textstringrequired
      • basisstringrequired
    • consultation_donebooleanrequired
  • role"hr" | "manager" | "person"required
  • created_atstringrequired
  • closed_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/cycles.create \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "Annual review 2026",
  "template_id": "starter:annual",
  "dates": {
    "start": "2026-11-16",
    "nominate_by": "2026-11-18",
    "self_due": "2026-11-25",
    "peer_due": "2026-11-24",
    "manager_due": "2026-11-30",
    "release_on": "2026-12-02"
  },
  "population": {
    "unit_ids": [
      "u1"
    ],
    "min_tenure_days": 60
  },
  "uses_calibration": true,
  "upward": true,
  "potential_step": true
}'
Response
{
  "data": {
    "id": "cy1",
    "name": "Annual review 2026",
    "status": "draft",
    "template": {
      "id": "tpl1",
      "name": "Annual review",
      "steps": {
        "self": true,
        "manager": true,
        "peer": true,
        "upward": false
      },
      "sections": [
        {
          "id": "s1",
          "title": "Progress",
          "show_goals": true,
          "questions": [
            {
              "id": "q1",
              "text": "Where are the goals now?",
              "kind": "text",
              "required": true,
              "for": [
                "self",
                "manager"
              ]
            }
          ]
        },
        {
          "id": "s2",
          "title": "Overall",
          "show_goals": false,
          "questions": [
            {
              "id": "q3",
              "text": "Overall rating so far.",
              "kind": "rating",
              "required": true,
              "for": [
                "manager"
              ]
            }
          ]
        }
      ],
      "scale_id": "five",
      "overall_rating": true
    },
    "scale": {
      "id": "five",
      "name": "5-point",
      "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."
        }
      ]
    },
    "dates": {
      "start": "2026-11-16",
      "nominate_by": "2026-11-18",
      "self_due": "2026-11-25",
      "peer_due": "2026-11-24",
      "manager_due": "2026-11-30",
      "calibrate_by": null,
      "release_on": "2026-12-02"
    },
    "upward": true,
    "potential_step": true,
    "uses_calibration": true,
    "second_level": false,
    "population": {
      "unit_ids": [],
      "location_ids": [],
      "title_ids": [],
      "level_ids": [],
      "person_ids": [],
      "min_tenure_days": 90,
      "as_of": "2026-11-16"
    },
    "launch": null,
    "scheduled_on": null,
    "schedule_problem": null,
    "progress": null,
    "by_team": null,
    "overdue": null,
    "preview": {
      "total": 412,
      "by_team": [
        {
          "unit_id": "u1",
          "name": "Customer care",
          "count": 200
        }
      ],
      "excluded": [
        {
          "person": {
            "id": "p9",
            "name": "Inês Lopes"
          },
          "reason": "tenure"
        }
      ],
      "no_manager": [
        {
          "id": "p1",
          "name": "Ana Costa"
        }
      ],
      "emails": {
        "started": 412,
        "upward": 0
      },
      "consultation": [
        {
          "country": "DE",
          "text": "Appraisal principles need the works council's consent.",
          "basis": "BetrVG § 94(2)"
        },
        {
          "country": null,
          "text": "Inform and consult employee representatives where national law requires.",
          "basis": "Directive 2002/14/EC"
        }
      ],
      "consultation_done": false
    },
    "role": "hr",
    "created_at": "2026-11-14T10:00:00.000Z",
    "closed_at": null
  }
}

Change a review cycle#

POST/v1/talent/cycles.updateWrite

Changes a review cycle (only what is given). A draft: everything (name, template_id, population, dates, upward, potential_step, uses_calibration). A running cycle: its name and dates (due dates can move; the release date never moves earlier than today, and never once people can see their reviews). Owners, admins and HR.

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

Input

  • namestring

    e.g. "Annual review 2026".

    1–120 characters.

  • template_idstring

    A template id or starter:<name> (talent_templates_list); the cycle keeps a copy.

  • populationobject
    7 fields
    • unit_idsstring[]

      Teams (people directly in them).

      1–200 characters. Up to 200 items.

    • location_idsstring[]

      Sites.

      1–200 characters. Up to 200 items.

    • title_idsstring[]

      Job titles from the catalog.

      1–200 characters. Up to 200 items.

    • level_idsstring[]

      Levels from the catalog.

      1–200 characters. Up to 200 items.

    • person_idsstring[]

      A list of people (with the filters: only those also matching them).

      1–200 characters. Up to 5000 items.

    • min_tenure_daysinteger

      Leave out people who joined fewer than this many days before the as-of date (default 90).

      From 0 to 730. Default 90.

    • as_ofstring

      Employed on this day (default today).

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

  • datesobject
    7 fields
    • startstringrequired

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

    • nominate_bystring | null

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

    • self_duestring | null

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

    • peer_duestring | null

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

    • manager_duestringrequired

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

    • calibrate_bystring | null

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

    • release_onstringrequired

      People see their review from this day, once signed off (and calibrated when the cycle uses calibration).

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

  • upwardboolean

    Reports give upward feedback on their manager (the template's upward step).

  • potential_stepboolean

    The manager step also asks for the person's potential.

  • uses_calibrationboolean

    Ratings are released only after a locked calibration session.

  • cycle_idstringrequired

Returns

21 fields
  • idstringrequired
  • namestringrequired
  • status"draft" | "launching" | "active" | "closed" | "cancelled"required
  • templateobjectrequired
    6 fields
    • idstring | nullrequired
    • namestringrequired
    • stepsobjectrequired
      4 fields
      • selfbooleanrequired
      • managerbooleanrequired
      • peerbooleanrequired
      • upwardbooleanrequired
    • sectionsobject[]required
      5 fields
      • idstringrequired
      • titlestringrequired
      • titlesobject
        4 fields
        • selfstring
        • managerstring
        • peerstring
        • upwardstring
      • show_goalsbooleanrequired
      • questionsobject[]required
        6 fields
        • idstringrequired
        • textstringrequired
        • textsobject

          Wording per step (self in the first person); text when absent.

          4 fields
          • selfstring
          • managerstring
          • peerstring
          • upwardstring
        • kind"rating" | "text" | "both"required
        • requiredbooleanrequired
        • for"self" | "manager" | "peer" | "upward"[]required
    • scale_idstringrequired
    • overall_ratingbooleanrequired

      The manager gives an overall rating (false: development only: no calibration, salary reviews use "No rating").

  • scaleobjectrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • pointsobject[]required
      3 fields
      • valueintegerrequired
      • labelstringrequired
      • descriptionstringrequired
  • datesobjectrequired
    7 fields
    • startstringrequired
    • nominate_bystring | nullrequired
    • self_duestring | nullrequired
    • peer_duestring | nullrequired
    • manager_duestringrequired
    • calibrate_bystring | nullrequired
    • release_onstringrequired
  • upwardbooleanrequired
  • potential_stepbooleanrequired
  • uses_calibrationbooleanrequired
  • second_levelbooleanrequired
  • populationobject | nullrequired

    HR only.

    7 fields
    • unit_idsstring[]required
    • location_idsstring[]required
    • title_idsstring[]required
    • level_idsstring[]required
    • person_idsstring[]required
    • min_tenure_daysintegerrequired
    • as_ofstringrequired
  • launchobject | nullrequired

    Reviews written so far while launching.

    2 fields
    • doneintegerrequired
    • totalintegerrequired
  • scheduled_onstring | nullrequired

    A draft launched "on the start date": Bizisy launches it on this day (HR only).

  • schedule_problemstring | nullrequired

    Why a scheduled launch couldn't run on its day; the cycle stays a draft (HR only).

  • progressobject | nullrequired

    HR: the whole cycle; a manager: the reviews they write. Null for people in the cycle.

    8 fields
    • reviewsintegerrequired
    • selfobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • managerobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • signoffobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • peersobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • leftintegerrequired
    • overdueintegerrequired
    • releasedintegerrequired
  • by_teamobject[] | nullrequired

    HR only.

    6 fields
    • unit_idstring | nullrequired
    • namestring | nullrequired
    • reviewsintegerrequired
    • selfintegerrequired
    • managerintegerrequired
    • signoffintegerrequired
  • overdueobject[] | nullrequired

    HR only: reviews past a due date.

    4 fields
    • review_idstringrequired
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • step"self" | "manager" | "signoff"required
    • duestringrequired
  • previewobject | nullrequired

    Drafts, HR only: who it would review and what it would send.

    7 fields
    • totalintegerrequired

      People the cycle would review.

    • by_teamobject[]required
      3 fields
      • unit_idstring | nullrequired
      • namestring | nullrequired
      • countintegerrequired
    • excludedobject[]required
      2 fields
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • reason"not_employed" | "tenure"required
    • no_managerobject[]required

      In the cycle without a manager to review them: HR reassigns.

      2 fields
      • idstringrequired
      • namestringrequired
    • emailsobjectrequired
      2 fields
      • startedintegerrequired
      • upwardintegerrequired
    • consultationobject[]required
      3 fields
      • countrystring | nullrequired
      • textstringrequired
      • basisstringrequired
    • consultation_donebooleanrequired
  • role"hr" | "manager" | "person"required
  • created_atstringrequired
  • closed_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/cycles.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"cycle_id":"cy1","name":"Annual review 2026 (all sites)"}'
Response
{
  "data": {
    "id": "cy1",
    "name": "Annual review 2026 (all sites)",
    "status": "active",
    "template": {
      "id": "tpl1",
      "name": "Annual review",
      "steps": {
        "self": true,
        "manager": true,
        "peer": true,
        "upward": false
      },
      "sections": [
        {
          "id": "s1",
          "title": "Progress",
          "show_goals": true,
          "questions": [
            {
              "id": "q1",
              "text": "Where are the goals now?",
              "kind": "text",
              "required": true,
              "for": [
                "self",
                "manager"
              ]
            }
          ]
        },
        {
          "id": "s2",
          "title": "Overall",
          "show_goals": false,
          "questions": [
            {
              "id": "q3",
              "text": "Overall rating so far.",
              "kind": "rating",
              "required": true,
              "for": [
                "manager"
              ]
            }
          ]
        }
      ],
      "scale_id": "five",
      "overall_rating": true
    },
    "scale": {
      "id": "five",
      "name": "5-point",
      "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."
        }
      ]
    },
    "dates": {
      "start": "2026-11-16",
      "nominate_by": "2026-11-18",
      "self_due": "2026-11-25",
      "peer_due": "2026-11-24",
      "manager_due": "2026-11-30",
      "calibrate_by": null,
      "release_on": "2026-12-02"
    },
    "upward": false,
    "potential_step": false,
    "uses_calibration": true,
    "second_level": false,
    "population": {
      "unit_ids": [],
      "location_ids": [],
      "title_ids": [],
      "level_ids": [],
      "person_ids": [],
      "min_tenure_days": 90,
      "as_of": "2026-11-16"
    },
    "launch": {
      "done": 412,
      "total": 412
    },
    "scheduled_on": null,
    "schedule_problem": null,
    "progress": {
      "reviews": 412,
      "self": {
        "done": 300,
        "total": 410
      },
      "manager": {
        "done": 120,
        "total": 410
      },
      "signoff": {
        "done": 0,
        "total": 0
      },
      "peers": {
        "done": 800,
        "total": 1200
      },
      "left": 2,
      "overdue": 14,
      "released": 0
    },
    "by_team": [
      {
        "unit_id": "u1",
        "name": "Customer care",
        "reviews": 200,
        "self": 150,
        "manager": 60,
        "signoff": 0
      }
    ],
    "overdue": [
      {
        "review_id": "rv1",
        "person": {
          "id": "p2",
          "name": "Tomás Silva"
        },
        "step": "self",
        "due": "2026-11-25"
      }
    ],
    "preview": null,
    "role": "hr",
    "created_at": "2026-11-14T10:00:00.000Z",
    "closed_at": null
  }
}

Launch a review cycle#

POST/v1/talent/cycles.launchWrite

Launches a draft cycle: people are fixed as the preview shows them (dry-run first to see the counts and exclusions), the template and scale are copied, each person gets a review (the reviewer is their manager today) and an email with the steps and dates; with peers on, people choose peer reviewers by the nomination date; with upward on, reports are asked for upward feedback. Large cycles write 200 reviews at a time: the first now, the rest as the cycle page continues (talent_cycles_launch_continue) or within the hour. Up to 10 cycles running at once. Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
talent_cycles_launch 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
  • when"now" | "start"

    now (default): launch at once. start: when the start date is in the future, Bizisy launches it on that day (the emails go then); the cycle stays a draft with scheduled_on until then and can still be changed or cancelled. A start date of today or earlier launches at once.

    Default "now".

Returns

21 fields
  • idstringrequired
  • namestringrequired
  • status"draft" | "launching" | "active" | "closed" | "cancelled"required
  • templateobjectrequired
    6 fields
    • idstring | nullrequired
    • namestringrequired
    • stepsobjectrequired
      4 fields
      • selfbooleanrequired
      • managerbooleanrequired
      • peerbooleanrequired
      • upwardbooleanrequired
    • sectionsobject[]required
      5 fields
      • idstringrequired
      • titlestringrequired
      • titlesobject
        4 fields
        • selfstring
        • managerstring
        • peerstring
        • upwardstring
      • show_goalsbooleanrequired
      • questionsobject[]required
        6 fields
        • idstringrequired
        • textstringrequired
        • textsobject

          Wording per step (self in the first person); text when absent.

          4 fields
          • selfstring
          • managerstring
          • peerstring
          • upwardstring
        • kind"rating" | "text" | "both"required
        • requiredbooleanrequired
        • for"self" | "manager" | "peer" | "upward"[]required
    • scale_idstringrequired
    • overall_ratingbooleanrequired

      The manager gives an overall rating (false: development only: no calibration, salary reviews use "No rating").

  • scaleobjectrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • pointsobject[]required
      3 fields
      • valueintegerrequired
      • labelstringrequired
      • descriptionstringrequired
  • datesobjectrequired
    7 fields
    • startstringrequired
    • nominate_bystring | nullrequired
    • self_duestring | nullrequired
    • peer_duestring | nullrequired
    • manager_duestringrequired
    • calibrate_bystring | nullrequired
    • release_onstringrequired
  • upwardbooleanrequired
  • potential_stepbooleanrequired
  • uses_calibrationbooleanrequired
  • second_levelbooleanrequired
  • populationobject | nullrequired

    HR only.

    7 fields
    • unit_idsstring[]required
    • location_idsstring[]required
    • title_idsstring[]required
    • level_idsstring[]required
    • person_idsstring[]required
    • min_tenure_daysintegerrequired
    • as_ofstringrequired
  • launchobject | nullrequired

    Reviews written so far while launching.

    2 fields
    • doneintegerrequired
    • totalintegerrequired
  • scheduled_onstring | nullrequired

    A draft launched "on the start date": Bizisy launches it on this day (HR only).

  • schedule_problemstring | nullrequired

    Why a scheduled launch couldn't run on its day; the cycle stays a draft (HR only).

  • progressobject | nullrequired

    HR: the whole cycle; a manager: the reviews they write. Null for people in the cycle.

    8 fields
    • reviewsintegerrequired
    • selfobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • managerobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • signoffobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • peersobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • leftintegerrequired
    • overdueintegerrequired
    • releasedintegerrequired
  • by_teamobject[] | nullrequired

    HR only.

    6 fields
    • unit_idstring | nullrequired
    • namestring | nullrequired
    • reviewsintegerrequired
    • selfintegerrequired
    • managerintegerrequired
    • signoffintegerrequired
  • overdueobject[] | nullrequired

    HR only: reviews past a due date.

    4 fields
    • review_idstringrequired
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • step"self" | "manager" | "signoff"required
    • duestringrequired
  • previewobject | nullrequired

    Drafts, HR only: who it would review and what it would send.

    7 fields
    • totalintegerrequired

      People the cycle would review.

    • by_teamobject[]required
      3 fields
      • unit_idstring | nullrequired
      • namestring | nullrequired
      • countintegerrequired
    • excludedobject[]required
      2 fields
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • reason"not_employed" | "tenure"required
    • no_managerobject[]required

      In the cycle without a manager to review them: HR reassigns.

      2 fields
      • idstringrequired
      • namestringrequired
    • emailsobjectrequired
      2 fields
      • startedintegerrequired
      • upwardintegerrequired
    • consultationobject[]required
      3 fields
      • countrystring | nullrequired
      • textstringrequired
      • basisstringrequired
    • consultation_donebooleanrequired
  • role"hr" | "manager" | "person"required
  • created_atstringrequired
  • closed_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/cycles.launch \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"cycle_id":"cy1","when":"start"}'
Response
{
  "data": {
    "id": "cy1",
    "name": "Annual review 2026",
    "status": "launching",
    "template": {
      "id": "tpl1",
      "name": "Annual review",
      "steps": {
        "self": true,
        "manager": true,
        "peer": true,
        "upward": false
      },
      "sections": [
        {
          "id": "s1",
          "title": "Progress",
          "show_goals": true,
          "questions": [
            {
              "id": "q1",
              "text": "Where are the goals now?",
              "kind": "text",
              "required": true,
              "for": [
                "self",
                "manager"
              ]
            }
          ]
        },
        {
          "id": "s2",
          "title": "Overall",
          "show_goals": false,
          "questions": [
            {
              "id": "q3",
              "text": "Overall rating so far.",
              "kind": "rating",
              "required": true,
              "for": [
                "manager"
              ]
            }
          ]
        }
      ],
      "scale_id": "five",
      "overall_rating": true
    },
    "scale": {
      "id": "five",
      "name": "5-point",
      "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."
        }
      ]
    },
    "dates": {
      "start": "2026-11-16",
      "nominate_by": "2026-11-18",
      "self_due": "2026-11-25",
      "peer_due": "2026-11-24",
      "manager_due": "2026-11-30",
      "calibrate_by": null,
      "release_on": "2026-12-02"
    },
    "upward": false,
    "potential_step": false,
    "uses_calibration": true,
    "second_level": false,
    "population": {
      "unit_ids": [],
      "location_ids": [],
      "title_ids": [],
      "level_ids": [],
      "person_ids": [],
      "min_tenure_days": 90,
      "as_of": "2026-11-16"
    },
    "launch": {
      "done": 200,
      "total": 412
    },
    "scheduled_on": null,
    "schedule_problem": null,
    "progress": {
      "reviews": 412,
      "self": {
        "done": 300,
        "total": 410
      },
      "manager": {
        "done": 120,
        "total": 410
      },
      "signoff": {
        "done": 0,
        "total": 0
      },
      "peers": {
        "done": 800,
        "total": 1200
      },
      "left": 2,
      "overdue": 14,
      "released": 0
    },
    "by_team": [
      {
        "unit_id": "u1",
        "name": "Customer care",
        "reviews": 200,
        "self": 150,
        "manager": 60,
        "signoff": 0
      }
    ],
    "overdue": [
      {
        "review_id": "rv1",
        "person": {
          "id": "p2",
          "name": "Tomás Silva"
        },
        "step": "self",
        "due": "2026-11-25"
      }
    ],
    "preview": null,
    "role": "hr",
    "created_at": "2026-11-14T10:00:00.000Z",
    "closed_at": null
  }
}

Continue launching a review cycle#

POST/v1/talent/cycles.launch_continueWrite

Writes the next 200 reviews of a cycle that is launching (the cycle page calls it until done; the hourly sweep does too). Nothing when it is not launching. Owners, admins and HR.

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

Input

  • cycle_idstringrequired

Returns

  • doneintegerrequired
  • totalintegerrequired
  • status"draft" | "launching" | "active" | "closed" | "cancelled"required

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/cycles.launch_continue \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"cycle_id":"cy1"}'
Response
{
  "data": {
    "done": 400,
    "total": 412,
    "status": "launching"
  }
}

Cancel a review cycle#

POST/v1/talent/cycles.cancelWrite

Cancels a review cycle (draft, launching or running): nothing more is asked or sent, and nothing of it is ever released to the people in it. Its answers are kept for HR until retention deletes them. Owners, admins and HR.

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

Input

  • cycle_idstringrequired

Returns

21 fields
  • idstringrequired
  • namestringrequired
  • status"draft" | "launching" | "active" | "closed" | "cancelled"required
  • templateobjectrequired
    6 fields
    • idstring | nullrequired
    • namestringrequired
    • stepsobjectrequired
      4 fields
      • selfbooleanrequired
      • managerbooleanrequired
      • peerbooleanrequired
      • upwardbooleanrequired
    • sectionsobject[]required
      5 fields
      • idstringrequired
      • titlestringrequired
      • titlesobject
        4 fields
        • selfstring
        • managerstring
        • peerstring
        • upwardstring
      • show_goalsbooleanrequired
      • questionsobject[]required
        6 fields
        • idstringrequired
        • textstringrequired
        • textsobject

          Wording per step (self in the first person); text when absent.

          4 fields
          • selfstring
          • managerstring
          • peerstring
          • upwardstring
        • kind"rating" | "text" | "both"required
        • requiredbooleanrequired
        • for"self" | "manager" | "peer" | "upward"[]required
    • scale_idstringrequired
    • overall_ratingbooleanrequired

      The manager gives an overall rating (false: development only: no calibration, salary reviews use "No rating").

  • scaleobjectrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • pointsobject[]required
      3 fields
      • valueintegerrequired
      • labelstringrequired
      • descriptionstringrequired
  • datesobjectrequired
    7 fields
    • startstringrequired
    • nominate_bystring | nullrequired
    • self_duestring | nullrequired
    • peer_duestring | nullrequired
    • manager_duestringrequired
    • calibrate_bystring | nullrequired
    • release_onstringrequired
  • upwardbooleanrequired
  • potential_stepbooleanrequired
  • uses_calibrationbooleanrequired
  • second_levelbooleanrequired
  • populationobject | nullrequired

    HR only.

    7 fields
    • unit_idsstring[]required
    • location_idsstring[]required
    • title_idsstring[]required
    • level_idsstring[]required
    • person_idsstring[]required
    • min_tenure_daysintegerrequired
    • as_ofstringrequired
  • launchobject | nullrequired

    Reviews written so far while launching.

    2 fields
    • doneintegerrequired
    • totalintegerrequired
  • scheduled_onstring | nullrequired

    A draft launched "on the start date": Bizisy launches it on this day (HR only).

  • schedule_problemstring | nullrequired

    Why a scheduled launch couldn't run on its day; the cycle stays a draft (HR only).

  • progressobject | nullrequired

    HR: the whole cycle; a manager: the reviews they write. Null for people in the cycle.

    8 fields
    • reviewsintegerrequired
    • selfobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • managerobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • signoffobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • peersobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • leftintegerrequired
    • overdueintegerrequired
    • releasedintegerrequired
  • by_teamobject[] | nullrequired

    HR only.

    6 fields
    • unit_idstring | nullrequired
    • namestring | nullrequired
    • reviewsintegerrequired
    • selfintegerrequired
    • managerintegerrequired
    • signoffintegerrequired
  • overdueobject[] | nullrequired

    HR only: reviews past a due date.

    4 fields
    • review_idstringrequired
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • step"self" | "manager" | "signoff"required
    • duestringrequired
  • previewobject | nullrequired

    Drafts, HR only: who it would review and what it would send.

    7 fields
    • totalintegerrequired

      People the cycle would review.

    • by_teamobject[]required
      3 fields
      • unit_idstring | nullrequired
      • namestring | nullrequired
      • countintegerrequired
    • excludedobject[]required
      2 fields
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • reason"not_employed" | "tenure"required
    • no_managerobject[]required

      In the cycle without a manager to review them: HR reassigns.

      2 fields
      • idstringrequired
      • namestringrequired
    • emailsobjectrequired
      2 fields
      • startedintegerrequired
      • upwardintegerrequired
    • consultationobject[]required
      3 fields
      • countrystring | nullrequired
      • textstringrequired
      • basisstringrequired
    • consultation_donebooleanrequired
  • role"hr" | "manager" | "person"required
  • created_atstringrequired
  • closed_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/cycles.cancel \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"cycle_id":"cy1"}'
Response
{
  "data": {
    "id": "cy1",
    "name": "Annual review 2026",
    "status": "cancelled",
    "template": {
      "id": "tpl1",
      "name": "Annual review",
      "steps": {
        "self": true,
        "manager": true,
        "peer": true,
        "upward": false
      },
      "sections": [
        {
          "id": "s1",
          "title": "Progress",
          "show_goals": true,
          "questions": [
            {
              "id": "q1",
              "text": "Where are the goals now?",
              "kind": "text",
              "required": true,
              "for": [
                "self",
                "manager"
              ]
            }
          ]
        },
        {
          "id": "s2",
          "title": "Overall",
          "show_goals": false,
          "questions": [
            {
              "id": "q3",
              "text": "Overall rating so far.",
              "kind": "rating",
              "required": true,
              "for": [
                "manager"
              ]
            }
          ]
        }
      ],
      "scale_id": "five",
      "overall_rating": true
    },
    "scale": {
      "id": "five",
      "name": "5-point",
      "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."
        }
      ]
    },
    "dates": {
      "start": "2026-11-16",
      "nominate_by": "2026-11-18",
      "self_due": "2026-11-25",
      "peer_due": "2026-11-24",
      "manager_due": "2026-11-30",
      "calibrate_by": null,
      "release_on": "2026-12-02"
    },
    "upward": false,
    "potential_step": false,
    "uses_calibration": true,
    "second_level": false,
    "population": {
      "unit_ids": [],
      "location_ids": [],
      "title_ids": [],
      "level_ids": [],
      "person_ids": [],
      "min_tenure_days": 90,
      "as_of": "2026-11-16"
    },
    "launch": {
      "done": 412,
      "total": 412
    },
    "scheduled_on": null,
    "schedule_problem": null,
    "progress": {
      "reviews": 412,
      "self": {
        "done": 300,
        "total": 410
      },
      "manager": {
        "done": 120,
        "total": 410
      },
      "signoff": {
        "done": 0,
        "total": 0
      },
      "peers": {
        "done": 800,
        "total": 1200
      },
      "left": 2,
      "overdue": 14,
      "released": 0
    },
    "by_team": [
      {
        "unit_id": "u1",
        "name": "Customer care",
        "reviews": 200,
        "self": 150,
        "manager": 60,
        "signoff": 0
      }
    ],
    "overdue": [
      {
        "review_id": "rv1",
        "person": {
          "id": "p2",
          "name": "Tomás Silva"
        },
        "step": "self",
        "due": "2026-11-25"
      }
    ],
    "preview": null,
    "role": "hr",
    "created_at": "2026-11-14T10:00:00.000Z",
    "closed_at": "2026-11-20T10:00:00.000Z"
  }
}

Close a review cycle#

POST/v1/talent/cycles.closeWrite

Closes a running review cycle once its release date has come: open steps stop (people keep what was released; reviews never submitted stay unreleased), and the retention period starts (Settings → Talent, default 5 years). Owners, admins and HR.

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

Input

  • cycle_idstringrequired

Returns

21 fields
  • idstringrequired
  • namestringrequired
  • status"draft" | "launching" | "active" | "closed" | "cancelled"required
  • templateobjectrequired
    6 fields
    • idstring | nullrequired
    • namestringrequired
    • stepsobjectrequired
      4 fields
      • selfbooleanrequired
      • managerbooleanrequired
      • peerbooleanrequired
      • upwardbooleanrequired
    • sectionsobject[]required
      5 fields
      • idstringrequired
      • titlestringrequired
      • titlesobject
        4 fields
        • selfstring
        • managerstring
        • peerstring
        • upwardstring
      • show_goalsbooleanrequired
      • questionsobject[]required
        6 fields
        • idstringrequired
        • textstringrequired
        • textsobject

          Wording per step (self in the first person); text when absent.

          4 fields
          • selfstring
          • managerstring
          • peerstring
          • upwardstring
        • kind"rating" | "text" | "both"required
        • requiredbooleanrequired
        • for"self" | "manager" | "peer" | "upward"[]required
    • scale_idstringrequired
    • overall_ratingbooleanrequired

      The manager gives an overall rating (false: development only: no calibration, salary reviews use "No rating").

  • scaleobjectrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • pointsobject[]required
      3 fields
      • valueintegerrequired
      • labelstringrequired
      • descriptionstringrequired
  • datesobjectrequired
    7 fields
    • startstringrequired
    • nominate_bystring | nullrequired
    • self_duestring | nullrequired
    • peer_duestring | nullrequired
    • manager_duestringrequired
    • calibrate_bystring | nullrequired
    • release_onstringrequired
  • upwardbooleanrequired
  • potential_stepbooleanrequired
  • uses_calibrationbooleanrequired
  • second_levelbooleanrequired
  • populationobject | nullrequired

    HR only.

    7 fields
    • unit_idsstring[]required
    • location_idsstring[]required
    • title_idsstring[]required
    • level_idsstring[]required
    • person_idsstring[]required
    • min_tenure_daysintegerrequired
    • as_ofstringrequired
  • launchobject | nullrequired

    Reviews written so far while launching.

    2 fields
    • doneintegerrequired
    • totalintegerrequired
  • scheduled_onstring | nullrequired

    A draft launched "on the start date": Bizisy launches it on this day (HR only).

  • schedule_problemstring | nullrequired

    Why a scheduled launch couldn't run on its day; the cycle stays a draft (HR only).

  • progressobject | nullrequired

    HR: the whole cycle; a manager: the reviews they write. Null for people in the cycle.

    8 fields
    • reviewsintegerrequired
    • selfobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • managerobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • signoffobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • peersobjectrequired
      2 fields
      • doneintegerrequired
      • totalintegerrequired
    • leftintegerrequired
    • overdueintegerrequired
    • releasedintegerrequired
  • by_teamobject[] | nullrequired

    HR only.

    6 fields
    • unit_idstring | nullrequired
    • namestring | nullrequired
    • reviewsintegerrequired
    • selfintegerrequired
    • managerintegerrequired
    • signoffintegerrequired
  • overdueobject[] | nullrequired

    HR only: reviews past a due date.

    4 fields
    • review_idstringrequired
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • step"self" | "manager" | "signoff"required
    • duestringrequired
  • previewobject | nullrequired

    Drafts, HR only: who it would review and what it would send.

    7 fields
    • totalintegerrequired

      People the cycle would review.

    • by_teamobject[]required
      3 fields
      • unit_idstring | nullrequired
      • namestring | nullrequired
      • countintegerrequired
    • excludedobject[]required
      2 fields
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • reason"not_employed" | "tenure"required
    • no_managerobject[]required

      In the cycle without a manager to review them: HR reassigns.

      2 fields
      • idstringrequired
      • namestringrequired
    • emailsobjectrequired
      2 fields
      • startedintegerrequired
      • upwardintegerrequired
    • consultationobject[]required
      3 fields
      • countrystring | nullrequired
      • textstringrequired
      • basisstringrequired
    • consultation_donebooleanrequired
  • role"hr" | "manager" | "person"required
  • created_atstringrequired
  • closed_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/cycles.close \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"cycle_id":"cy1"}'
Response
{
  "data": {
    "id": "cy1",
    "name": "Annual review 2026",
    "status": "closed",
    "template": {
      "id": "tpl1",
      "name": "Annual review",
      "steps": {
        "self": true,
        "manager": true,
        "peer": true,
        "upward": false
      },
      "sections": [
        {
          "id": "s1",
          "title": "Progress",
          "show_goals": true,
          "questions": [
            {
              "id": "q1",
              "text": "Where are the goals now?",
              "kind": "text",
              "required": true,
              "for": [
                "self",
                "manager"
              ]
            }
          ]
        },
        {
          "id": "s2",
          "title": "Overall",
          "show_goals": false,
          "questions": [
            {
              "id": "q3",
              "text": "Overall rating so far.",
              "kind": "rating",
              "required": true,
              "for": [
                "manager"
              ]
            }
          ]
        }
      ],
      "scale_id": "five",
      "overall_rating": true
    },
    "scale": {
      "id": "five",
      "name": "5-point",
      "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."
        }
      ]
    },
    "dates": {
      "start": "2026-11-16",
      "nominate_by": "2026-11-18",
      "self_due": "2026-11-25",
      "peer_due": "2026-11-24",
      "manager_due": "2026-11-30",
      "calibrate_by": null,
      "release_on": "2026-12-02"
    },
    "upward": false,
    "potential_step": false,
    "uses_calibration": true,
    "second_level": false,
    "population": {
      "unit_ids": [],
      "location_ids": [],
      "title_ids": [],
      "level_ids": [],
      "person_ids": [],
      "min_tenure_days": 90,
      "as_of": "2026-11-16"
    },
    "launch": {
      "done": 412,
      "total": 412
    },
    "scheduled_on": null,
    "schedule_problem": null,
    "progress": {
      "reviews": 412,
      "self": {
        "done": 300,
        "total": 410
      },
      "manager": {
        "done": 120,
        "total": 410
      },
      "signoff": {
        "done": 0,
        "total": 0
      },
      "peers": {
        "done": 800,
        "total": 1200
      },
      "left": 2,
      "overdue": 14,
      "released": 0
    },
    "by_team": [
      {
        "unit_id": "u1",
        "name": "Customer care",
        "reviews": 200,
        "self": 150,
        "manager": 60,
        "signoff": 0
      }
    ],
    "overdue": [
      {
        "review_id": "rv1",
        "person": {
          "id": "p2",
          "name": "Tomás Silva"
        },
        "step": "self",
        "due": "2026-11-25"
      }
    ],
    "preview": null,
    "role": "hr",
    "created_at": "2026-11-14T10:00:00.000Z",
    "closed_at": "2026-12-10T10:00:00.000Z"
  }
}

Preview a review cycle email#

POST/v1/talent/cycles.preview_emailRead

One email a review cycle sends, rendered exactly as it is sent, in the company's language: kind cycle_started, peers_to_approve, feedback_asked, reminder, calibration_opened, review_ready; cycle_name and date (the due or release date the email names) as the cycle has them, or will; peers: the cycle asks for peer feedback (cycle_started). Returns the subject, the HTML (show it in a sandboxed frame) and the plain text. Nothing is sent or stored. Owners, admins and HR, in the app only.

Web app only
Refused for API keys and connected apps. Previews of the review cycle emails show in the app only (Talent → Performance → Preview emails).
MCP tool
talent_cycles_preview_email on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • kind"cycle_started" | "peers_to_approve" | "feedback_asked" | "reminder" | "calibration_opened" | "review_ready"required
  • cycle_namestringrequired

    1–120 characters.

  • datestring | null

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

  • peersboolean

Returns

  • kind"cycle_started" | "peers_to_approve" | "feedback_asked" | "reminder" | "calibration_opened" | "review_ready"required
  • subjectstringrequired
  • htmlstringrequired

    The whole email as one HTML document.

  • textstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/cycles.preview_email \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "cycle_started",
  "cycle_name": "Annual review 2026",
  "date": "2026-12-04",
  "peers": true
}'
Response
{
  "data": {
    "kind": "cycle_started",
    "subject": "Annual review 2026 has started",
    "html": "<!doctype html><html><body><p>Annual review 2026</p></body></html>",
    "text": "Annual review 2026"
  }
}

List reviews#

POST/v1/talent/reviews.listRead

Reviews and their step statuses (job tier, no answers or ratings): owners, admins and HR see every review but their own; managers the reviews they write, the ones waiting for their second-level sign-off and their wider team's; never your own (see talent_me_home). Filters: cycle_id, person_id, mine (write: reviews you write; signoff: waiting for your sign-off). Peer counts only: never who gave feedback. Through API keys and AI assistants, statuses only.

Who can call it
Manage key owner admin hr
Me key owner admin hr member
Keys and apps
Statuses only (to do, done, left): never answers, ratings or who gave feedback.
MCP tool
talent_reviews_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.

  • person_idstring

    1–200 characters.

  • mine"write" | "signoff"

Returns

  • itemsobject[]required
    9 fields
    • idstringrequired
    • cycleobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • personobjectrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • teamstring | nullrequired
    • reviewerobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • stepsobjectrequired
      3 fields
      • self"pending" | "submitted" | "n/a"required
      • manager"pending" | "submitted" | "n/a"required
      • signoff"pending" | "submitted" | "n/a"required
    • left_onstring | nullrequired
    • releasedbooleanrequired
    • peersobjectrequired
      3 fields
      • askedintegerrequired
      • answeredintegerrequired
      • nominatedintegerrequired
    • role"hr" | "manager" | "chain" | "signoff"required

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/reviews.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cycle_id":"cy1","mine":"write"}'
Response
{
  "data": {
    "items": [
      {
        "id": "rv1",
        "cycle": {
          "id": "cy1",
          "name": "Annual review 2026"
        },
        "person": {
          "id": "p2",
          "name": "Tomás Silva",
          "team": "Customer care"
        },
        "reviewer": {
          "id": "p1",
          "name": "Ana Costa"
        },
        "steps": {
          "self": "submitted",
          "manager": "pending",
          "signoff": "n/a"
        },
        "left_on": null,
        "released": false,
        "peers": {
          "asked": 4,
          "answered": 3,
          "nominated": 0
        },
        "role": "manager"
      }
    ]
  }
}

Get a review#

POST/v1/talent/reviews.getRead

One review, shaped by who you are (D5, D12): the person sees their own self-review and, only from the release date once it is signed off (and calibrated, when the cycle uses calibration), the manager's answers, the final rating and the peer and upward groups that reached the anonymity threshold; before that "Not available yet" tells nothing about status. The reviewer sees and writes their draft; HR and higher managers (after the manager submitted) read it. Peer and upward answers are always unattributed. API keys and AI assistants can't read reviews.

Web app only
Refused for API keys and connected apps. Reviews (answers, ratings, feedback) are read in the app only.
MCP tool
talent_reviews_get on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • review_idstringrequired

Returns

19 fields
  • idstringrequired
  • cycleobjectrequired
    10 fields
    • idstringrequired
    • namestringrequired
    • statusstringrequired
    • release_onstringrequired
    • self_duestring | nullrequired
    • manager_duestringrequired
    • uses_calibrationbooleanrequired
    • second_levelbooleanrequired
    • potential_stepbooleanrequired
    • overall_ratingbooleanrequired

      The manager gives an overall rating (false: a development-only review).

  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • reviewerobject | nullrequired

    null: no reviewer (HR reassigns) or a former manager. Hidden from the person before release.

    2 fields
    • idstringrequired
    • namestringrequired
  • access"hr" | "manager" | "chain" | "self" | "signoff"required
  • releasedboolean | nullrequired

    null for the person before release (they learn nothing about status).

  • stepsobject | nullrequired

    Job tier: HR and managers only.

    3 fields
    • self"pending" | "submitted" | "n/a"required
    • manager"pending" | "submitted" | "n/a"required
    • signoff"pending" | "submitted" | "n/a"required
  • sectionsobject[]required
    5 fields
    • idstringrequired
    • titlestringrequired
    • titlesobject
      4 fields
      • selfstring
      • managerstring
      • peerstring
      • upwardstring
    • show_goalsbooleanrequired
    • questionsobject[]required
      6 fields
      • idstringrequired
      • textstringrequired
      • textsobject

        Wording per step (self in the first person); text when absent.

        4 fields
        • selfstring
        • managerstring
        • peerstring
        • upwardstring
      • kind"rating" | "text" | "both"required
      • requiredbooleanrequired
      • for"self" | "manager" | "peer" | "upward"[]required
  • scaleobjectrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • pointsobject[]required
      3 fields
      • valueintegerrequired
      • labelstringrequired
      • descriptionstringrequired
  • selfobject | nullrequired
    2 fields
    • answersobject[]required
      3 fields
      • question_idstringrequired
      • ratinginteger | nullrequired
      • textstring | nullrequired
    • submitted_atstring | nullrequired
  • managerobject | nullrequired
    3 fields
    • answersobject[]required
      3 fields
      • question_idstringrequired
      • ratinginteger | nullrequired
      • textstring | nullrequired
    • ratinginteger | nullrequired
    • submitted_atstring | nullrequired
  • final_ratinginteger | nullrequired

    The rating after calibration (or the manager's): HR and managers, and the person once released.

  • groupsobject[]required
    5 fields
    • kind"peer" | "upward"required
    • shownbooleanrequired

      false: fewer answers than the anonymity threshold; withheld from everyone.

    • answeredinteger | nullrequired

      How many answered (HR, the reviewer and higher managers); null for the person.

    • askedinteger | nullrequired
    • answersobject[]required

      Unattributed, texts shuffled: never who wrote what.

      3 fields
      • question_idstringrequired
      • ratingsinteger[]required
      • textsstring[]required
  • signoffobject | nullrequired
    3 fields
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstring | nullrequired
    • sent_back_notestring | nullrequired
  • ackobject | nullrequired
    1 field
    • atstringrequired
  • commentobject | nullrequired
    2 fields
    • textstringrequired
    • atstringrequired
  • discuss_requested_atstring | nullrequired
  • left_onstring | nullrequired

    HR and managers: the review closed as "left" on this day.

  • canobjectrequired
    8 fields
    • answer_selfbooleanrequired
    • answer_managerbooleanrequired
    • signoffbooleanrequired
    • acknowledgebooleanrequired
    • commentbooleanrequired
    • discussbooleanrequired
    • reopenbooleanrequired
    • reassignbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/reviews.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"review_id":"rv1"}'
Response
{
  "data": {
    "id": "rv1",
    "cycle": {
      "id": "cy1",
      "name": "Annual review 2026",
      "status": "active",
      "release_on": "2026-12-02",
      "self_due": "2026-11-25",
      "manager_due": "2026-11-30",
      "uses_calibration": true,
      "second_level": false,
      "potential_step": false,
      "overall_rating": true
    },
    "person": {
      "id": "p2",
      "name": "Tomás Silva"
    },
    "reviewer": {
      "id": "p1",
      "name": "Ana Costa"
    },
    "access": "manager",
    "released": false,
    "steps": {
      "self": "submitted",
      "manager": "pending",
      "signoff": "n/a"
    },
    "sections": [
      {
        "id": "s1",
        "title": "Progress",
        "show_goals": true,
        "questions": [
          {
            "id": "q1",
            "text": "Where are the goals now?",
            "kind": "text",
            "required": true,
            "for": [
              "self",
              "manager"
            ]
          }
        ]
      },
      {
        "id": "s2",
        "title": "Overall",
        "show_goals": false,
        "questions": [
          {
            "id": "q3",
            "text": "Overall rating so far.",
            "kind": "rating",
            "required": true,
            "for": [
              "manager"
            ]
          }
        ]
      }
    ],
    "scale": {
      "id": "five",
      "name": "5-point",
      "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."
        }
      ]
    },
    "self": {
      "answers": [
        {
          "question_id": "q1",
          "rating": null,
          "text": "Halfway there."
        }
      ],
      "submitted_at": "2026-11-20T10:00:00.000Z"
    },
    "manager": {
      "answers": [],
      "rating": null,
      "submitted_at": null
    },
    "final_rating": null,
    "groups": [
      {
        "kind": "peer",
        "shown": true,
        "answered": 3,
        "asked": 4,
        "answers": [
          {
            "question_id": "q1",
            "ratings": [],
            "texts": [
              "Clear priorities.",
              "Helpful in reviews.",
              "Calm under pressure."
            ]
          }
        ]
      }
    ],
    "signoff": null,
    "ack": null,
    "comment": null,
    "discuss_requested_at": null,
    "left_on": null,
    "can": {
      "answer_self": false,
      "answer_manager": true,
      "signoff": false,
      "acknowledge": false,
      "comment": false,
      "discuss": false,
      "reopen": false,
      "reassign": false
    }
  }
}

Save review answers#

POST/v1/talent/reviews.answerWrite

Saves your answers as a draft: as self (your own self-review) or as manager (a review you write; with the overall rating). Nothing is shared until you submit. A review whose manager changed moves to the new manager when they open it (the old draft stays the old manager's). In the app only.

Web app only
Refused for API keys and connected apps. Reviews are written in the app only.
MCP tool
talent_reviews_answer 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

  • review_idstringrequired
  • as"self" | "manager"required

    self: your own self-review; manager: a review you write as the manager.

  • answersobject[]required

    Up to 30 items.

    3 fields
    • question_idstringrequired

      1–40 characters.

    • ratinginteger | null

      From 1 to 7.

    • textstring | null

      Up to 5000 characters.

  • ratinginteger | null

    Manager only: the overall rating on the cycle's scale (needed to submit when the cycle has one; refused in a development-only cycle, cycle.overall_rating false).

    From 1 to 7.

Returns

19 fields
  • idstringrequired
  • cycleobjectrequired
    10 fields
    • idstringrequired
    • namestringrequired
    • statusstringrequired
    • release_onstringrequired
    • self_duestring | nullrequired
    • manager_duestringrequired
    • uses_calibrationbooleanrequired
    • second_levelbooleanrequired
    • potential_stepbooleanrequired
    • overall_ratingbooleanrequired

      The manager gives an overall rating (false: a development-only review).

  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • reviewerobject | nullrequired

    null: no reviewer (HR reassigns) or a former manager. Hidden from the person before release.

    2 fields
    • idstringrequired
    • namestringrequired
  • access"hr" | "manager" | "chain" | "self" | "signoff"required
  • releasedboolean | nullrequired

    null for the person before release (they learn nothing about status).

  • stepsobject | nullrequired

    Job tier: HR and managers only.

    3 fields
    • self"pending" | "submitted" | "n/a"required
    • manager"pending" | "submitted" | "n/a"required
    • signoff"pending" | "submitted" | "n/a"required
  • sectionsobject[]required
    5 fields
    • idstringrequired
    • titlestringrequired
    • titlesobject
      4 fields
      • selfstring
      • managerstring
      • peerstring
      • upwardstring
    • show_goalsbooleanrequired
    • questionsobject[]required
      6 fields
      • idstringrequired
      • textstringrequired
      • textsobject

        Wording per step (self in the first person); text when absent.

        4 fields
        • selfstring
        • managerstring
        • peerstring
        • upwardstring
      • kind"rating" | "text" | "both"required
      • requiredbooleanrequired
      • for"self" | "manager" | "peer" | "upward"[]required
  • scaleobjectrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • pointsobject[]required
      3 fields
      • valueintegerrequired
      • labelstringrequired
      • descriptionstringrequired
  • selfobject | nullrequired
    2 fields
    • answersobject[]required
      3 fields
      • question_idstringrequired
      • ratinginteger | nullrequired
      • textstring | nullrequired
    • submitted_atstring | nullrequired
  • managerobject | nullrequired
    3 fields
    • answersobject[]required
      3 fields
      • question_idstringrequired
      • ratinginteger | nullrequired
      • textstring | nullrequired
    • ratinginteger | nullrequired
    • submitted_atstring | nullrequired
  • final_ratinginteger | nullrequired

    The rating after calibration (or the manager's): HR and managers, and the person once released.

  • groupsobject[]required
    5 fields
    • kind"peer" | "upward"required
    • shownbooleanrequired

      false: fewer answers than the anonymity threshold; withheld from everyone.

    • answeredinteger | nullrequired

      How many answered (HR, the reviewer and higher managers); null for the person.

    • askedinteger | nullrequired
    • answersobject[]required

      Unattributed, texts shuffled: never who wrote what.

      3 fields
      • question_idstringrequired
      • ratingsinteger[]required
      • textsstring[]required
  • signoffobject | nullrequired
    3 fields
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstring | nullrequired
    • sent_back_notestring | nullrequired
  • ackobject | nullrequired
    1 field
    • atstringrequired
  • commentobject | nullrequired
    2 fields
    • textstringrequired
    • atstringrequired
  • discuss_requested_atstring | nullrequired
  • left_onstring | nullrequired

    HR and managers: the review closed as "left" on this day.

  • canobjectrequired
    8 fields
    • answer_selfbooleanrequired
    • answer_managerbooleanrequired
    • signoffbooleanrequired
    • acknowledgebooleanrequired
    • commentbooleanrequired
    • discussbooleanrequired
    • reopenbooleanrequired
    • reassignbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/reviews.answer \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "review_id": "rv1",
  "as": "manager",
  "answers": [
    {
      "question_id": "q1",
      "text": "Good progress."
    }
  ],
  "rating": 4
}'
Response
{
  "data": {
    "id": "rv1",
    "cycle": {
      "id": "cy1",
      "name": "Annual review 2026",
      "status": "active",
      "release_on": "2026-12-02",
      "self_due": "2026-11-25",
      "manager_due": "2026-11-30",
      "uses_calibration": true,
      "second_level": false,
      "potential_step": false,
      "overall_rating": true
    },
    "person": {
      "id": "p2",
      "name": "Tomás Silva"
    },
    "reviewer": {
      "id": "p1",
      "name": "Ana Costa"
    },
    "access": "manager",
    "released": false,
    "steps": {
      "self": "submitted",
      "manager": "pending",
      "signoff": "n/a"
    },
    "sections": [
      {
        "id": "s1",
        "title": "Progress",
        "show_goals": true,
        "questions": [
          {
            "id": "q1",
            "text": "Where are the goals now?",
            "kind": "text",
            "required": true,
            "for": [
              "self",
              "manager"
            ]
          }
        ]
      },
      {
        "id": "s2",
        "title": "Overall",
        "show_goals": false,
        "questions": [
          {
            "id": "q3",
            "text": "Overall rating so far.",
            "kind": "rating",
            "required": true,
            "for": [
              "manager"
            ]
          }
        ]
      }
    ],
    "scale": {
      "id": "five",
      "name": "5-point",
      "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."
        }
      ]
    },
    "self": {
      "answers": [
        {
          "question_id": "q1",
          "rating": null,
          "text": "Halfway there."
        }
      ],
      "submitted_at": "2026-11-20T10:00:00.000Z"
    },
    "manager": {
      "answers": [],
      "rating": null,
      "submitted_at": null
    },
    "final_rating": null,
    "groups": [
      {
        "kind": "peer",
        "shown": true,
        "answered": 3,
        "asked": 4,
        "answers": [
          {
            "question_id": "q1",
            "ratings": [],
            "texts": [
              "Clear priorities.",
              "Helpful in reviews.",
              "Calm under pressure."
            ]
          }
        ]
      }
    ],
    "signoff": null,
    "ack": null,
    "comment": null,
    "discuss_requested_at": null,
    "left_on": null,
    "can": {
      "answer_self": false,
      "answer_manager": true,
      "signoff": false,
      "acknowledge": false,
      "comment": false,
      "discuss": false,
      "reopen": false,
      "reassign": false
    }
  }
}

Submit a review#

POST/v1/talent/reviews.submitWrite

Submits your self-review (as self) or the manager review (as manager, with the overall rating when the cycle has one): every required question answered. After a manager submits, the next manager up signs off when the company has second-level sign-off; the person sees it on the release date (after calibration when the cycle uses it). In the app only.

Web app only
Refused for API keys and connected apps. Reviews are submitted in the app only.
MCP tool
talent_reviews_submit 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

  • review_idstringrequired
  • as"self" | "manager"required

    self: your own self-review; manager: a review you write as the manager.

  • answersobject[]required

    Up to 30 items.

    3 fields
    • question_idstringrequired

      1–40 characters.

    • ratinginteger | null

      From 1 to 7.

    • textstring | null

      Up to 5000 characters.

  • ratinginteger | null

    Manager only: the overall rating on the cycle's scale (needed to submit when the cycle has one; refused in a development-only cycle, cycle.overall_rating false).

    From 1 to 7.

Returns

19 fields
  • idstringrequired
  • cycleobjectrequired
    10 fields
    • idstringrequired
    • namestringrequired
    • statusstringrequired
    • release_onstringrequired
    • self_duestring | nullrequired
    • manager_duestringrequired
    • uses_calibrationbooleanrequired
    • second_levelbooleanrequired
    • potential_stepbooleanrequired
    • overall_ratingbooleanrequired

      The manager gives an overall rating (false: a development-only review).

  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • reviewerobject | nullrequired

    null: no reviewer (HR reassigns) or a former manager. Hidden from the person before release.

    2 fields
    • idstringrequired
    • namestringrequired
  • access"hr" | "manager" | "chain" | "self" | "signoff"required
  • releasedboolean | nullrequired

    null for the person before release (they learn nothing about status).

  • stepsobject | nullrequired

    Job tier: HR and managers only.

    3 fields
    • self"pending" | "submitted" | "n/a"required
    • manager"pending" | "submitted" | "n/a"required
    • signoff"pending" | "submitted" | "n/a"required
  • sectionsobject[]required
    5 fields
    • idstringrequired
    • titlestringrequired
    • titlesobject
      4 fields
      • selfstring
      • managerstring
      • peerstring
      • upwardstring
    • show_goalsbooleanrequired
    • questionsobject[]required
      6 fields
      • idstringrequired
      • textstringrequired
      • textsobject

        Wording per step (self in the first person); text when absent.

        4 fields
        • selfstring
        • managerstring
        • peerstring
        • upwardstring
      • kind"rating" | "text" | "both"required
      • requiredbooleanrequired
      • for"self" | "manager" | "peer" | "upward"[]required
  • scaleobjectrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • pointsobject[]required
      3 fields
      • valueintegerrequired
      • labelstringrequired
      • descriptionstringrequired
  • selfobject | nullrequired
    2 fields
    • answersobject[]required
      3 fields
      • question_idstringrequired
      • ratinginteger | nullrequired
      • textstring | nullrequired
    • submitted_atstring | nullrequired
  • managerobject | nullrequired
    3 fields
    • answersobject[]required
      3 fields
      • question_idstringrequired
      • ratinginteger | nullrequired
      • textstring | nullrequired
    • ratinginteger | nullrequired
    • submitted_atstring | nullrequired
  • final_ratinginteger | nullrequired

    The rating after calibration (or the manager's): HR and managers, and the person once released.

  • groupsobject[]required
    5 fields
    • kind"peer" | "upward"required
    • shownbooleanrequired

      false: fewer answers than the anonymity threshold; withheld from everyone.

    • answeredinteger | nullrequired

      How many answered (HR, the reviewer and higher managers); null for the person.

    • askedinteger | nullrequired
    • answersobject[]required

      Unattributed, texts shuffled: never who wrote what.

      3 fields
      • question_idstringrequired
      • ratingsinteger[]required
      • textsstring[]required
  • signoffobject | nullrequired
    3 fields
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstring | nullrequired
    • sent_back_notestring | nullrequired
  • ackobject | nullrequired
    1 field
    • atstringrequired
  • commentobject | nullrequired
    2 fields
    • textstringrequired
    • atstringrequired
  • discuss_requested_atstring | nullrequired
  • left_onstring | nullrequired

    HR and managers: the review closed as "left" on this day.

  • canobjectrequired
    8 fields
    • answer_selfbooleanrequired
    • answer_managerbooleanrequired
    • signoffbooleanrequired
    • acknowledgebooleanrequired
    • commentbooleanrequired
    • discussbooleanrequired
    • reopenbooleanrequired
    • reassignbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/reviews.submit \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "review_id": "rv1",
  "as": "self",
  "answers": [
    {
      "question_id": "q1",
      "text": "Halfway there."
    }
  ]
}'
Response
{
  "data": {
    "id": "rv1",
    "cycle": {
      "id": "cy1",
      "name": "Annual review 2026",
      "status": "active",
      "release_on": "2026-12-02",
      "self_due": "2026-11-25",
      "manager_due": "2026-11-30",
      "uses_calibration": true,
      "second_level": false,
      "potential_step": false,
      "overall_rating": true
    },
    "person": {
      "id": "p2",
      "name": "Tomás Silva"
    },
    "reviewer": {
      "id": "p1",
      "name": "Ana Costa"
    },
    "access": "manager",
    "released": false,
    "steps": {
      "self": "submitted",
      "manager": "pending",
      "signoff": "n/a"
    },
    "sections": [
      {
        "id": "s1",
        "title": "Progress",
        "show_goals": true,
        "questions": [
          {
            "id": "q1",
            "text": "Where are the goals now?",
            "kind": "text",
            "required": true,
            "for": [
              "self",
              "manager"
            ]
          }
        ]
      },
      {
        "id": "s2",
        "title": "Overall",
        "show_goals": false,
        "questions": [
          {
            "id": "q3",
            "text": "Overall rating so far.",
            "kind": "rating",
            "required": true,
            "for": [
              "manager"
            ]
          }
        ]
      }
    ],
    "scale": {
      "id": "five",
      "name": "5-point",
      "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."
        }
      ]
    },
    "self": {
      "answers": [
        {
          "question_id": "q1",
          "rating": null,
          "text": "Halfway there."
        }
      ],
      "submitted_at": "2026-11-20T10:00:00.000Z"
    },
    "manager": {
      "answers": [],
      "rating": null,
      "submitted_at": null
    },
    "final_rating": null,
    "groups": [
      {
        "kind": "peer",
        "shown": true,
        "answered": 3,
        "asked": 4,
        "answers": [
          {
            "question_id": "q1",
            "ratings": [],
            "texts": [
              "Clear priorities.",
              "Helpful in reviews.",
              "Calm under pressure."
            ]
          }
        ]
      }
    ],
    "signoff": null,
    "ack": null,
    "comment": null,
    "discuss_requested_at": null,
    "left_on": null,
    "can": {
      "answer_self": false,
      "answer_manager": true,
      "signoff": false,
      "acknowledge": false,
      "comment": false,
      "discuss": false,
      "reopen": false,
      "reassign": false
    }
  }
}

Sign off a review#

POST/v1/talent/reviews.signoffWrite

Second-level sign-off: the manager of the reviewer approves a submitted review (when Settings → Talent has second-level sign-off on). Send it back with talent_reviews_send_back instead. In the app only.

Web app only
Refused for API keys and connected apps. Sign-off happens in the app only.
MCP tool
talent_reviews_signoff 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

  • review_idstringrequired

Returns

19 fields
  • idstringrequired
  • cycleobjectrequired
    10 fields
    • idstringrequired
    • namestringrequired
    • statusstringrequired
    • release_onstringrequired
    • self_duestring | nullrequired
    • manager_duestringrequired
    • uses_calibrationbooleanrequired
    • second_levelbooleanrequired
    • potential_stepbooleanrequired
    • overall_ratingbooleanrequired

      The manager gives an overall rating (false: a development-only review).

  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • reviewerobject | nullrequired

    null: no reviewer (HR reassigns) or a former manager. Hidden from the person before release.

    2 fields
    • idstringrequired
    • namestringrequired
  • access"hr" | "manager" | "chain" | "self" | "signoff"required
  • releasedboolean | nullrequired

    null for the person before release (they learn nothing about status).

  • stepsobject | nullrequired

    Job tier: HR and managers only.

    3 fields
    • self"pending" | "submitted" | "n/a"required
    • manager"pending" | "submitted" | "n/a"required
    • signoff"pending" | "submitted" | "n/a"required
  • sectionsobject[]required
    5 fields
    • idstringrequired
    • titlestringrequired
    • titlesobject
      4 fields
      • selfstring
      • managerstring
      • peerstring
      • upwardstring
    • show_goalsbooleanrequired
    • questionsobject[]required
      6 fields
      • idstringrequired
      • textstringrequired
      • textsobject

        Wording per step (self in the first person); text when absent.

        4 fields
        • selfstring
        • managerstring
        • peerstring
        • upwardstring
      • kind"rating" | "text" | "both"required
      • requiredbooleanrequired
      • for"self" | "manager" | "peer" | "upward"[]required
  • scaleobjectrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • pointsobject[]required
      3 fields
      • valueintegerrequired
      • labelstringrequired
      • descriptionstringrequired
  • selfobject | nullrequired
    2 fields
    • answersobject[]required
      3 fields
      • question_idstringrequired
      • ratinginteger | nullrequired
      • textstring | nullrequired
    • submitted_atstring | nullrequired
  • managerobject | nullrequired
    3 fields
    • answersobject[]required
      3 fields
      • question_idstringrequired
      • ratinginteger | nullrequired
      • textstring | nullrequired
    • ratinginteger | nullrequired
    • submitted_atstring | nullrequired
  • final_ratinginteger | nullrequired

    The rating after calibration (or the manager's): HR and managers, and the person once released.

  • groupsobject[]required
    5 fields
    • kind"peer" | "upward"required
    • shownbooleanrequired

      false: fewer answers than the anonymity threshold; withheld from everyone.

    • answeredinteger | nullrequired

      How many answered (HR, the reviewer and higher managers); null for the person.

    • askedinteger | nullrequired
    • answersobject[]required

      Unattributed, texts shuffled: never who wrote what.

      3 fields
      • question_idstringrequired
      • ratingsinteger[]required
      • textsstring[]required
  • signoffobject | nullrequired
    3 fields
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstring | nullrequired
    • sent_back_notestring | nullrequired
  • ackobject | nullrequired
    1 field
    • atstringrequired
  • commentobject | nullrequired
    2 fields
    • textstringrequired
    • atstringrequired
  • discuss_requested_atstring | nullrequired
  • left_onstring | nullrequired

    HR and managers: the review closed as "left" on this day.

  • canobjectrequired
    8 fields
    • answer_selfbooleanrequired
    • answer_managerbooleanrequired
    • signoffbooleanrequired
    • acknowledgebooleanrequired
    • commentbooleanrequired
    • discussbooleanrequired
    • reopenbooleanrequired
    • reassignbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/reviews.signoff \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"review_id":"rv1"}'
Response
{
  "data": {
    "id": "rv1",
    "cycle": {
      "id": "cy1",
      "name": "Annual review 2026",
      "status": "active",
      "release_on": "2026-12-02",
      "self_due": "2026-11-25",
      "manager_due": "2026-11-30",
      "uses_calibration": true,
      "second_level": false,
      "potential_step": false,
      "overall_rating": true
    },
    "person": {
      "id": "p2",
      "name": "Tomás Silva"
    },
    "reviewer": {
      "id": "p1",
      "name": "Ana Costa"
    },
    "access": "manager",
    "released": false,
    "steps": {
      "self": "submitted",
      "manager": "pending",
      "signoff": "n/a"
    },
    "sections": [
      {
        "id": "s1",
        "title": "Progress",
        "show_goals": true,
        "questions": [
          {
            "id": "q1",
            "text": "Where are the goals now?",
            "kind": "text",
            "required": true,
            "for": [
              "self",
              "manager"
            ]
          }
        ]
      },
      {
        "id": "s2",
        "title": "Overall",
        "show_goals": false,
        "questions": [
          {
            "id": "q3",
            "text": "Overall rating so far.",
            "kind": "rating",
            "required": true,
            "for": [
              "manager"
            ]
          }
        ]
      }
    ],
    "scale": {
      "id": "five",
      "name": "5-point",
      "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."
        }
      ]
    },
    "self": {
      "answers": [
        {
          "question_id": "q1",
          "rating": null,
          "text": "Halfway there."
        }
      ],
      "submitted_at": "2026-11-20T10:00:00.000Z"
    },
    "manager": {
      "answers": [],
      "rating": null,
      "submitted_at": null
    },
    "final_rating": null,
    "groups": [
      {
        "kind": "peer",
        "shown": true,
        "answered": 3,
        "asked": 4,
        "answers": [
          {
            "question_id": "q1",
            "ratings": [],
            "texts": [
              "Clear priorities.",
              "Helpful in reviews.",
              "Calm under pressure."
            ]
          }
        ]
      }
    ],
    "signoff": null,
    "ack": null,
    "comment": null,
    "discuss_requested_at": null,
    "left_on": null,
    "can": {
      "answer_self": false,
      "answer_manager": true,
      "signoff": false,
      "acknowledge": false,
      "comment": false,
      "discuss": false,
      "reopen": false,
      "reassign": false
    }
  }
}

Send a review back for changes#

POST/v1/talent/reviews.send_backWrite

Second-level sign-off: sends a submitted review back to its manager with a note (10–500 characters); they get an email naming the cycle only, change it and submit again. In the app only.

Web app only
Refused for API keys and connected apps. Sending back happens in the app only.
MCP tool
talent_reviews_send_back 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

  • review_idstringrequired
  • notestringrequired

    10–500 characters.

Returns

19 fields
  • idstringrequired
  • cycleobjectrequired
    10 fields
    • idstringrequired
    • namestringrequired
    • statusstringrequired
    • release_onstringrequired
    • self_duestring | nullrequired
    • manager_duestringrequired
    • uses_calibrationbooleanrequired
    • second_levelbooleanrequired
    • potential_stepbooleanrequired
    • overall_ratingbooleanrequired

      The manager gives an overall rating (false: a development-only review).

  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • reviewerobject | nullrequired

    null: no reviewer (HR reassigns) or a former manager. Hidden from the person before release.

    2 fields
    • idstringrequired
    • namestringrequired
  • access"hr" | "manager" | "chain" | "self" | "signoff"required
  • releasedboolean | nullrequired

    null for the person before release (they learn nothing about status).

  • stepsobject | nullrequired

    Job tier: HR and managers only.

    3 fields
    • self"pending" | "submitted" | "n/a"required
    • manager"pending" | "submitted" | "n/a"required
    • signoff"pending" | "submitted" | "n/a"required
  • sectionsobject[]required
    5 fields
    • idstringrequired
    • titlestringrequired
    • titlesobject
      4 fields
      • selfstring
      • managerstring
      • peerstring
      • upwardstring
    • show_goalsbooleanrequired
    • questionsobject[]required
      6 fields
      • idstringrequired
      • textstringrequired
      • textsobject

        Wording per step (self in the first person); text when absent.

        4 fields
        • selfstring
        • managerstring
        • peerstring
        • upwardstring
      • kind"rating" | "text" | "both"required
      • requiredbooleanrequired
      • for"self" | "manager" | "peer" | "upward"[]required
  • scaleobjectrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • pointsobject[]required
      3 fields
      • valueintegerrequired
      • labelstringrequired
      • descriptionstringrequired
  • selfobject | nullrequired
    2 fields
    • answersobject[]required
      3 fields
      • question_idstringrequired
      • ratinginteger | nullrequired
      • textstring | nullrequired
    • submitted_atstring | nullrequired
  • managerobject | nullrequired
    3 fields
    • answersobject[]required
      3 fields
      • question_idstringrequired
      • ratinginteger | nullrequired
      • textstring | nullrequired
    • ratinginteger | nullrequired
    • submitted_atstring | nullrequired
  • final_ratinginteger | nullrequired

    The rating after calibration (or the manager's): HR and managers, and the person once released.

  • groupsobject[]required
    5 fields
    • kind"peer" | "upward"required
    • shownbooleanrequired

      false: fewer answers than the anonymity threshold; withheld from everyone.

    • answeredinteger | nullrequired

      How many answered (HR, the reviewer and higher managers); null for the person.

    • askedinteger | nullrequired
    • answersobject[]required

      Unattributed, texts shuffled: never who wrote what.

      3 fields
      • question_idstringrequired
      • ratingsinteger[]required
      • textsstring[]required
  • signoffobject | nullrequired
    3 fields
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstring | nullrequired
    • sent_back_notestring | nullrequired
  • ackobject | nullrequired
    1 field
    • atstringrequired
  • commentobject | nullrequired
    2 fields
    • textstringrequired
    • atstringrequired
  • discuss_requested_atstring | nullrequired
  • left_onstring | nullrequired

    HR and managers: the review closed as "left" on this day.

  • canobjectrequired
    8 fields
    • answer_selfbooleanrequired
    • answer_managerbooleanrequired
    • signoffbooleanrequired
    • acknowledgebooleanrequired
    • commentbooleanrequired
    • discussbooleanrequired
    • reopenbooleanrequired
    • reassignbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/reviews.send_back \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"review_id":"rv1","note":"Add an example for the second goal."}'
Response
{
  "data": {
    "id": "rv1",
    "cycle": {
      "id": "cy1",
      "name": "Annual review 2026",
      "status": "active",
      "release_on": "2026-12-02",
      "self_due": "2026-11-25",
      "manager_due": "2026-11-30",
      "uses_calibration": true,
      "second_level": false,
      "potential_step": false,
      "overall_rating": true
    },
    "person": {
      "id": "p2",
      "name": "Tomás Silva"
    },
    "reviewer": {
      "id": "p1",
      "name": "Ana Costa"
    },
    "access": "manager",
    "released": false,
    "steps": {
      "self": "submitted",
      "manager": "pending",
      "signoff": "n/a"
    },
    "sections": [
      {
        "id": "s1",
        "title": "Progress",
        "show_goals": true,
        "questions": [
          {
            "id": "q1",
            "text": "Where are the goals now?",
            "kind": "text",
            "required": true,
            "for": [
              "self",
              "manager"
            ]
          }
        ]
      },
      {
        "id": "s2",
        "title": "Overall",
        "show_goals": false,
        "questions": [
          {
            "id": "q3",
            "text": "Overall rating so far.",
            "kind": "rating",
            "required": true,
            "for": [
              "manager"
            ]
          }
        ]
      }
    ],
    "scale": {
      "id": "five",
      "name": "5-point",
      "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."
        }
      ]
    },
    "self": {
      "answers": [
        {
          "question_id": "q1",
          "rating": null,
          "text": "Halfway there."
        }
      ],
      "submitted_at": "2026-11-20T10:00:00.000Z"
    },
    "manager": {
      "answers": [],
      "rating": null,
      "submitted_at": null
    },
    "final_rating": null,
    "groups": [
      {
        "kind": "peer",
        "shown": true,
        "answered": 3,
        "asked": 4,
        "answers": [
          {
            "question_id": "q1",
            "ratings": [],
            "texts": [
              "Clear priorities.",
              "Helpful in reviews.",
              "Calm under pressure."
            ]
          }
        ]
      }
    ],
    "signoff": null,
    "ack": null,
    "comment": null,
    "discuss_requested_at": null,
    "left_on": null,
    "can": {
      "answer_self": false,
      "answer_manager": true,
      "signoff": false,
      "acknowledge": false,
      "comment": false,
      "discuss": false,
      "reopen": false,
      "reassign": false
    }
  }
}

Give a review to another reviewer#

POST/v1/talent/reviews.reassignWrite

HR gives a review whose manager step is not submitted to another reviewer (a person working here, not the person themselves), with a reason. The previous reviewer's draft stays theirs and is not shown to the new one. Owners, admins and HR.

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

  • review_idstringrequired
  • reviewer_idstringrequired

    1–200 characters.

  • reasonstringrequired

    10–500 characters.

Returns

19 fields
  • idstringrequired
  • cycleobjectrequired
    10 fields
    • idstringrequired
    • namestringrequired
    • statusstringrequired
    • release_onstringrequired
    • self_duestring | nullrequired
    • manager_duestringrequired
    • uses_calibrationbooleanrequired
    • second_levelbooleanrequired
    • potential_stepbooleanrequired
    • overall_ratingbooleanrequired

      The manager gives an overall rating (false: a development-only review).

  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • reviewerobject | nullrequired

    null: no reviewer (HR reassigns) or a former manager. Hidden from the person before release.

    2 fields
    • idstringrequired
    • namestringrequired
  • access"hr" | "manager" | "chain" | "self" | "signoff"required
  • releasedboolean | nullrequired

    null for the person before release (they learn nothing about status).

  • stepsobject | nullrequired

    Job tier: HR and managers only.

    3 fields
    • self"pending" | "submitted" | "n/a"required
    • manager"pending" | "submitted" | "n/a"required
    • signoff"pending" | "submitted" | "n/a"required
  • sectionsobject[]required
    5 fields
    • idstringrequired
    • titlestringrequired
    • titlesobject
      4 fields
      • selfstring
      • managerstring
      • peerstring
      • upwardstring
    • show_goalsbooleanrequired
    • questionsobject[]required
      6 fields
      • idstringrequired
      • textstringrequired
      • textsobject

        Wording per step (self in the first person); text when absent.

        4 fields
        • selfstring
        • managerstring
        • peerstring
        • upwardstring
      • kind"rating" | "text" | "both"required
      • requiredbooleanrequired
      • for"self" | "manager" | "peer" | "upward"[]required
  • scaleobjectrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • pointsobject[]required
      3 fields
      • valueintegerrequired
      • labelstringrequired
      • descriptionstringrequired
  • selfobject | nullrequired
    2 fields
    • answersobject[]required
      3 fields
      • question_idstringrequired
      • ratinginteger | nullrequired
      • textstring | nullrequired
    • submitted_atstring | nullrequired
  • managerobject | nullrequired
    3 fields
    • answersobject[]required
      3 fields
      • question_idstringrequired
      • ratinginteger | nullrequired
      • textstring | nullrequired
    • ratinginteger | nullrequired
    • submitted_atstring | nullrequired
  • final_ratinginteger | nullrequired

    The rating after calibration (or the manager's): HR and managers, and the person once released.

  • groupsobject[]required
    5 fields
    • kind"peer" | "upward"required
    • shownbooleanrequired

      false: fewer answers than the anonymity threshold; withheld from everyone.

    • answeredinteger | nullrequired

      How many answered (HR, the reviewer and higher managers); null for the person.

    • askedinteger | nullrequired
    • answersobject[]required

      Unattributed, texts shuffled: never who wrote what.

      3 fields
      • question_idstringrequired
      • ratingsinteger[]required
      • textsstring[]required
  • signoffobject | nullrequired
    3 fields
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstring | nullrequired
    • sent_back_notestring | nullrequired
  • ackobject | nullrequired
    1 field
    • atstringrequired
  • commentobject | nullrequired
    2 fields
    • textstringrequired
    • atstringrequired
  • discuss_requested_atstring | nullrequired
  • left_onstring | nullrequired

    HR and managers: the review closed as "left" on this day.

  • canobjectrequired
    8 fields
    • answer_selfbooleanrequired
    • answer_managerbooleanrequired
    • signoffbooleanrequired
    • acknowledgebooleanrequired
    • commentbooleanrequired
    • discussbooleanrequired
    • reopenbooleanrequired
    • reassignbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/reviews.reassign \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "review_id": "rv1",
  "reviewer_id": "p3",
  "reason": "Rita managed this period."
}'
Response
{
  "data": {
    "id": "rv1",
    "cycle": {
      "id": "cy1",
      "name": "Annual review 2026",
      "status": "active",
      "release_on": "2026-12-02",
      "self_due": "2026-11-25",
      "manager_due": "2026-11-30",
      "uses_calibration": true,
      "second_level": false,
      "potential_step": false,
      "overall_rating": true
    },
    "person": {
      "id": "p2",
      "name": "Tomás Silva"
    },
    "reviewer": {
      "id": "p1",
      "name": "Ana Costa"
    },
    "access": "manager",
    "released": false,
    "steps": {
      "self": "submitted",
      "manager": "pending",
      "signoff": "n/a"
    },
    "sections": [
      {
        "id": "s1",
        "title": "Progress",
        "show_goals": true,
        "questions": [
          {
            "id": "q1",
            "text": "Where are the goals now?",
            "kind": "text",
            "required": true,
            "for": [
              "self",
              "manager"
            ]
          }
        ]
      },
      {
        "id": "s2",
        "title": "Overall",
        "show_goals": false,
        "questions": [
          {
            "id": "q3",
            "text": "Overall rating so far.",
            "kind": "rating",
            "required": true,
            "for": [
              "manager"
            ]
          }
        ]
      }
    ],
    "scale": {
      "id": "five",
      "name": "5-point",
      "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."
        }
      ]
    },
    "self": {
      "answers": [
        {
          "question_id": "q1",
          "rating": null,
          "text": "Halfway there."
        }
      ],
      "submitted_at": "2026-11-20T10:00:00.000Z"
    },
    "manager": {
      "answers": [],
      "rating": null,
      "submitted_at": null
    },
    "final_rating": null,
    "groups": [
      {
        "kind": "peer",
        "shown": true,
        "answered": 3,
        "asked": 4,
        "answers": [
          {
            "question_id": "q1",
            "ratings": [],
            "texts": [
              "Clear priorities.",
              "Helpful in reviews.",
              "Calm under pressure."
            ]
          }
        ]
      }
    ],
    "signoff": null,
    "ack": null,
    "comment": null,
    "discuss_requested_at": null,
    "left_on": null,
    "can": {
      "answer_self": false,
      "answer_manager": true,
      "signoff": false,
      "acknowledge": false,
      "comment": false,
      "discuss": false,
      "reopen": false,
      "reassign": false
    }
  }
}

Reopen a review step#

POST/v1/talent/reviews.reopenWrite

HR reopens a submitted self or manager step so it can be changed, with a reason, only before the release date and while no locked calibration holds the rating. Reopening the manager step also reopens sign-off. Owners, admins and HR.

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

  • review_idstringrequired
  • step"self" | "manager"required
  • reasonstringrequired

    10–500 characters.

Returns

19 fields
  • idstringrequired
  • cycleobjectrequired
    10 fields
    • idstringrequired
    • namestringrequired
    • statusstringrequired
    • release_onstringrequired
    • self_duestring | nullrequired
    • manager_duestringrequired
    • uses_calibrationbooleanrequired
    • second_levelbooleanrequired
    • potential_stepbooleanrequired
    • overall_ratingbooleanrequired

      The manager gives an overall rating (false: a development-only review).

  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • reviewerobject | nullrequired

    null: no reviewer (HR reassigns) or a former manager. Hidden from the person before release.

    2 fields
    • idstringrequired
    • namestringrequired
  • access"hr" | "manager" | "chain" | "self" | "signoff"required
  • releasedboolean | nullrequired

    null for the person before release (they learn nothing about status).

  • stepsobject | nullrequired

    Job tier: HR and managers only.

    3 fields
    • self"pending" | "submitted" | "n/a"required
    • manager"pending" | "submitted" | "n/a"required
    • signoff"pending" | "submitted" | "n/a"required
  • sectionsobject[]required
    5 fields
    • idstringrequired
    • titlestringrequired
    • titlesobject
      4 fields
      • selfstring
      • managerstring
      • peerstring
      • upwardstring
    • show_goalsbooleanrequired
    • questionsobject[]required
      6 fields
      • idstringrequired
      • textstringrequired
      • textsobject

        Wording per step (self in the first person); text when absent.

        4 fields
        • selfstring
        • managerstring
        • peerstring
        • upwardstring
      • kind"rating" | "text" | "both"required
      • requiredbooleanrequired
      • for"self" | "manager" | "peer" | "upward"[]required
  • scaleobjectrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • pointsobject[]required
      3 fields
      • valueintegerrequired
      • labelstringrequired
      • descriptionstringrequired
  • selfobject | nullrequired
    2 fields
    • answersobject[]required
      3 fields
      • question_idstringrequired
      • ratinginteger | nullrequired
      • textstring | nullrequired
    • submitted_atstring | nullrequired
  • managerobject | nullrequired
    3 fields
    • answersobject[]required
      3 fields
      • question_idstringrequired
      • ratinginteger | nullrequired
      • textstring | nullrequired
    • ratinginteger | nullrequired
    • submitted_atstring | nullrequired
  • final_ratinginteger | nullrequired

    The rating after calibration (or the manager's): HR and managers, and the person once released.

  • groupsobject[]required
    5 fields
    • kind"peer" | "upward"required
    • shownbooleanrequired

      false: fewer answers than the anonymity threshold; withheld from everyone.

    • answeredinteger | nullrequired

      How many answered (HR, the reviewer and higher managers); null for the person.

    • askedinteger | nullrequired
    • answersobject[]required

      Unattributed, texts shuffled: never who wrote what.

      3 fields
      • question_idstringrequired
      • ratingsinteger[]required
      • textsstring[]required
  • signoffobject | nullrequired
    3 fields
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstring | nullrequired
    • sent_back_notestring | nullrequired
  • ackobject | nullrequired
    1 field
    • atstringrequired
  • commentobject | nullrequired
    2 fields
    • textstringrequired
    • atstringrequired
  • discuss_requested_atstring | nullrequired
  • left_onstring | nullrequired

    HR and managers: the review closed as "left" on this day.

  • canobjectrequired
    8 fields
    • answer_selfbooleanrequired
    • answer_managerbooleanrequired
    • signoffbooleanrequired
    • acknowledgebooleanrequired
    • commentbooleanrequired
    • discussbooleanrequired
    • reopenbooleanrequired
    • reassignbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/reviews.reopen \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "review_id": "rv1",
  "step": "manager",
  "reason": "Rating entered by mistake."
}'
Response
{
  "data": {
    "id": "rv1",
    "cycle": {
      "id": "cy1",
      "name": "Annual review 2026",
      "status": "active",
      "release_on": "2026-12-02",
      "self_due": "2026-11-25",
      "manager_due": "2026-11-30",
      "uses_calibration": true,
      "second_level": false,
      "potential_step": false,
      "overall_rating": true
    },
    "person": {
      "id": "p2",
      "name": "Tomás Silva"
    },
    "reviewer": {
      "id": "p1",
      "name": "Ana Costa"
    },
    "access": "manager",
    "released": false,
    "steps": {
      "self": "submitted",
      "manager": "pending",
      "signoff": "n/a"
    },
    "sections": [
      {
        "id": "s1",
        "title": "Progress",
        "show_goals": true,
        "questions": [
          {
            "id": "q1",
            "text": "Where are the goals now?",
            "kind": "text",
            "required": true,
            "for": [
              "self",
              "manager"
            ]
          }
        ]
      },
      {
        "id": "s2",
        "title": "Overall",
        "show_goals": false,
        "questions": [
          {
            "id": "q3",
            "text": "Overall rating so far.",
            "kind": "rating",
            "required": true,
            "for": [
              "manager"
            ]
          }
        ]
      }
    ],
    "scale": {
      "id": "five",
      "name": "5-point",
      "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."
        }
      ]
    },
    "self": {
      "answers": [
        {
          "question_id": "q1",
          "rating": null,
          "text": "Halfway there."
        }
      ],
      "submitted_at": "2026-11-20T10:00:00.000Z"
    },
    "manager": {
      "answers": [],
      "rating": null,
      "submitted_at": null
    },
    "final_rating": null,
    "groups": [
      {
        "kind": "peer",
        "shown": true,
        "answered": 3,
        "asked": 4,
        "answers": [
          {
            "question_id": "q1",
            "ratings": [],
            "texts": [
              "Clear priorities.",
              "Helpful in reviews.",
              "Calm under pressure."
            ]
          }
        ]
      }
    ],
    "signoff": null,
    "ack": null,
    "comment": null,
    "discuss_requested_at": null,
    "left_on": null,
    "can": {
      "answer_self": false,
      "answer_manager": true,
      "signoff": false,
      "acknowledge": false,
      "comment": false,
      "discuss": false,
      "reopen": false,
      "reassign": false
    }
  }
}

Acknowledge my review#

POST/v1/talent/reviews.acknowledgeWrite

Records that you have read your released review. Acknowledging is not agreeing: you can add a comment and ask to discuss it. Your own review only, in the app.

Who can call it
Me key owner admin hr member
MCP tool
talent_reviews_acknowledge on My Workplace
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • review_idstringrequired

Returns

19 fields
  • idstringrequired
  • cycleobjectrequired
    10 fields
    • idstringrequired
    • namestringrequired
    • statusstringrequired
    • release_onstringrequired
    • self_duestring | nullrequired
    • manager_duestringrequired
    • uses_calibrationbooleanrequired
    • second_levelbooleanrequired
    • potential_stepbooleanrequired
    • overall_ratingbooleanrequired

      The manager gives an overall rating (false: a development-only review).

  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • reviewerobject | nullrequired

    null: no reviewer (HR reassigns) or a former manager. Hidden from the person before release.

    2 fields
    • idstringrequired
    • namestringrequired
  • access"hr" | "manager" | "chain" | "self" | "signoff"required
  • releasedboolean | nullrequired

    null for the person before release (they learn nothing about status).

  • stepsobject | nullrequired

    Job tier: HR and managers only.

    3 fields
    • self"pending" | "submitted" | "n/a"required
    • manager"pending" | "submitted" | "n/a"required
    • signoff"pending" | "submitted" | "n/a"required
  • sectionsobject[]required
    5 fields
    • idstringrequired
    • titlestringrequired
    • titlesobject
      4 fields
      • selfstring
      • managerstring
      • peerstring
      • upwardstring
    • show_goalsbooleanrequired
    • questionsobject[]required
      6 fields
      • idstringrequired
      • textstringrequired
      • textsobject

        Wording per step (self in the first person); text when absent.

        4 fields
        • selfstring
        • managerstring
        • peerstring
        • upwardstring
      • kind"rating" | "text" | "both"required
      • requiredbooleanrequired
      • for"self" | "manager" | "peer" | "upward"[]required
  • scaleobjectrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • pointsobject[]required
      3 fields
      • valueintegerrequired
      • labelstringrequired
      • descriptionstringrequired
  • selfobject | nullrequired
    2 fields
    • answersobject[]required
      3 fields
      • question_idstringrequired
      • ratinginteger | nullrequired
      • textstring | nullrequired
    • submitted_atstring | nullrequired
  • managerobject | nullrequired
    3 fields
    • answersobject[]required
      3 fields
      • question_idstringrequired
      • ratinginteger | nullrequired
      • textstring | nullrequired
    • ratinginteger | nullrequired
    • submitted_atstring | nullrequired
  • final_ratinginteger | nullrequired

    The rating after calibration (or the manager's): HR and managers, and the person once released.

  • groupsobject[]required
    5 fields
    • kind"peer" | "upward"required
    • shownbooleanrequired

      false: fewer answers than the anonymity threshold; withheld from everyone.

    • answeredinteger | nullrequired

      How many answered (HR, the reviewer and higher managers); null for the person.

    • askedinteger | nullrequired
    • answersobject[]required

      Unattributed, texts shuffled: never who wrote what.

      3 fields
      • question_idstringrequired
      • ratingsinteger[]required
      • textsstring[]required
  • signoffobject | nullrequired
    3 fields
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstring | nullrequired
    • sent_back_notestring | nullrequired
  • ackobject | nullrequired
    1 field
    • atstringrequired
  • commentobject | nullrequired
    2 fields
    • textstringrequired
    • atstringrequired
  • discuss_requested_atstring | nullrequired
  • left_onstring | nullrequired

    HR and managers: the review closed as "left" on this day.

  • canobjectrequired
    8 fields
    • answer_selfbooleanrequired
    • answer_managerbooleanrequired
    • signoffbooleanrequired
    • acknowledgebooleanrequired
    • commentbooleanrequired
    • discussbooleanrequired
    • reopenbooleanrequired
    • reassignbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/reviews.acknowledge \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"review_id":"rv1"}'
Response
{
  "data": {
    "id": "rv1",
    "cycle": {
      "id": "cy1",
      "name": "Annual review 2026",
      "status": "active",
      "release_on": "2026-12-02",
      "self_due": "2026-11-25",
      "manager_due": "2026-11-30",
      "uses_calibration": true,
      "second_level": false,
      "potential_step": false,
      "overall_rating": true
    },
    "person": {
      "id": "p2",
      "name": "Tomás Silva"
    },
    "reviewer": {
      "id": "p1",
      "name": "Ana Costa"
    },
    "access": "self",
    "released": true,
    "steps": {
      "self": "submitted",
      "manager": "pending",
      "signoff": "n/a"
    },
    "sections": [
      {
        "id": "s1",
        "title": "Progress",
        "show_goals": true,
        "questions": [
          {
            "id": "q1",
            "text": "Where are the goals now?",
            "kind": "text",
            "required": true,
            "for": [
              "self",
              "manager"
            ]
          }
        ]
      },
      {
        "id": "s2",
        "title": "Overall",
        "show_goals": false,
        "questions": [
          {
            "id": "q3",
            "text": "Overall rating so far.",
            "kind": "rating",
            "required": true,
            "for": [
              "manager"
            ]
          }
        ]
      }
    ],
    "scale": {
      "id": "five",
      "name": "5-point",
      "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."
        }
      ]
    },
    "self": {
      "answers": [
        {
          "question_id": "q1",
          "rating": null,
          "text": "Halfway there."
        }
      ],
      "submitted_at": "2026-11-20T10:00:00.000Z"
    },
    "manager": {
      "answers": [],
      "rating": null,
      "submitted_at": null
    },
    "final_rating": null,
    "groups": [
      {
        "kind": "peer",
        "shown": true,
        "answered": 3,
        "asked": 4,
        "answers": [
          {
            "question_id": "q1",
            "ratings": [],
            "texts": [
              "Clear priorities.",
              "Helpful in reviews.",
              "Calm under pressure."
            ]
          }
        ]
      }
    ],
    "signoff": null,
    "ack": {
      "at": "2026-12-02T10:00:00.000Z"
    },
    "comment": null,
    "discuss_requested_at": null,
    "left_on": null,
    "can": {
      "answer_self": false,
      "answer_manager": true,
      "signoff": false,
      "acknowledge": false,
      "comment": false,
      "discuss": false,
      "reopen": false,
      "reassign": false
    }
  }
}

Comment on my review#

POST/v1/talent/reviews.commentWrite

Adds or replaces your comment on your released review (up to 2000 characters; empty removes it). It stays with the review: your manager, their managers and HR read it. Your own review only, in the app.

Who can call it
Me key owner admin hr member
MCP tool
talent_reviews_comment on My Workplace
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • review_idstringrequired
  • textstringrequired

    Up to 2000 characters.

Returns

19 fields
  • idstringrequired
  • cycleobjectrequired
    10 fields
    • idstringrequired
    • namestringrequired
    • statusstringrequired
    • release_onstringrequired
    • self_duestring | nullrequired
    • manager_duestringrequired
    • uses_calibrationbooleanrequired
    • second_levelbooleanrequired
    • potential_stepbooleanrequired
    • overall_ratingbooleanrequired

      The manager gives an overall rating (false: a development-only review).

  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • reviewerobject | nullrequired

    null: no reviewer (HR reassigns) or a former manager. Hidden from the person before release.

    2 fields
    • idstringrequired
    • namestringrequired
  • access"hr" | "manager" | "chain" | "self" | "signoff"required
  • releasedboolean | nullrequired

    null for the person before release (they learn nothing about status).

  • stepsobject | nullrequired

    Job tier: HR and managers only.

    3 fields
    • self"pending" | "submitted" | "n/a"required
    • manager"pending" | "submitted" | "n/a"required
    • signoff"pending" | "submitted" | "n/a"required
  • sectionsobject[]required
    5 fields
    • idstringrequired
    • titlestringrequired
    • titlesobject
      4 fields
      • selfstring
      • managerstring
      • peerstring
      • upwardstring
    • show_goalsbooleanrequired
    • questionsobject[]required
      6 fields
      • idstringrequired
      • textstringrequired
      • textsobject

        Wording per step (self in the first person); text when absent.

        4 fields
        • selfstring
        • managerstring
        • peerstring
        • upwardstring
      • kind"rating" | "text" | "both"required
      • requiredbooleanrequired
      • for"self" | "manager" | "peer" | "upward"[]required
  • scaleobjectrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • pointsobject[]required
      3 fields
      • valueintegerrequired
      • labelstringrequired
      • descriptionstringrequired
  • selfobject | nullrequired
    2 fields
    • answersobject[]required
      3 fields
      • question_idstringrequired
      • ratinginteger | nullrequired
      • textstring | nullrequired
    • submitted_atstring | nullrequired
  • managerobject | nullrequired
    3 fields
    • answersobject[]required
      3 fields
      • question_idstringrequired
      • ratinginteger | nullrequired
      • textstring | nullrequired
    • ratinginteger | nullrequired
    • submitted_atstring | nullrequired
  • final_ratinginteger | nullrequired

    The rating after calibration (or the manager's): HR and managers, and the person once released.

  • groupsobject[]required
    5 fields
    • kind"peer" | "upward"required
    • shownbooleanrequired

      false: fewer answers than the anonymity threshold; withheld from everyone.

    • answeredinteger | nullrequired

      How many answered (HR, the reviewer and higher managers); null for the person.

    • askedinteger | nullrequired
    • answersobject[]required

      Unattributed, texts shuffled: never who wrote what.

      3 fields
      • question_idstringrequired
      • ratingsinteger[]required
      • textsstring[]required
  • signoffobject | nullrequired
    3 fields
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstring | nullrequired
    • sent_back_notestring | nullrequired
  • ackobject | nullrequired
    1 field
    • atstringrequired
  • commentobject | nullrequired
    2 fields
    • textstringrequired
    • atstringrequired
  • discuss_requested_atstring | nullrequired
  • left_onstring | nullrequired

    HR and managers: the review closed as "left" on this day.

  • canobjectrequired
    8 fields
    • answer_selfbooleanrequired
    • answer_managerbooleanrequired
    • signoffbooleanrequired
    • acknowledgebooleanrequired
    • commentbooleanrequired
    • discussbooleanrequired
    • reopenbooleanrequired
    • reassignbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/reviews.comment \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"review_id":"rv1","text":"I see the second half differently."}'
Response
{
  "data": {
    "id": "rv1",
    "cycle": {
      "id": "cy1",
      "name": "Annual review 2026",
      "status": "active",
      "release_on": "2026-12-02",
      "self_due": "2026-11-25",
      "manager_due": "2026-11-30",
      "uses_calibration": true,
      "second_level": false,
      "potential_step": false,
      "overall_rating": true
    },
    "person": {
      "id": "p2",
      "name": "Tomás Silva"
    },
    "reviewer": {
      "id": "p1",
      "name": "Ana Costa"
    },
    "access": "self",
    "released": true,
    "steps": {
      "self": "submitted",
      "manager": "pending",
      "signoff": "n/a"
    },
    "sections": [
      {
        "id": "s1",
        "title": "Progress",
        "show_goals": true,
        "questions": [
          {
            "id": "q1",
            "text": "Where are the goals now?",
            "kind": "text",
            "required": true,
            "for": [
              "self",
              "manager"
            ]
          }
        ]
      },
      {
        "id": "s2",
        "title": "Overall",
        "show_goals": false,
        "questions": [
          {
            "id": "q3",
            "text": "Overall rating so far.",
            "kind": "rating",
            "required": true,
            "for": [
              "manager"
            ]
          }
        ]
      }
    ],
    "scale": {
      "id": "five",
      "name": "5-point",
      "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."
        }
      ]
    },
    "self": {
      "answers": [
        {
          "question_id": "q1",
          "rating": null,
          "text": "Halfway there."
        }
      ],
      "submitted_at": "2026-11-20T10:00:00.000Z"
    },
    "manager": {
      "answers": [],
      "rating": null,
      "submitted_at": null
    },
    "final_rating": null,
    "groups": [
      {
        "kind": "peer",
        "shown": true,
        "answered": 3,
        "asked": 4,
        "answers": [
          {
            "question_id": "q1",
            "ratings": [],
            "texts": [
              "Clear priorities.",
              "Helpful in reviews.",
              "Calm under pressure."
            ]
          }
        ]
      }
    ],
    "signoff": null,
    "ack": null,
    "comment": {
      "text": "I see the second half differently.",
      "at": "2026-12-02T10:00:00.000Z"
    },
    "discuss_requested_at": null,
    "left_on": null,
    "can": {
      "answer_self": false,
      "answer_manager": true,
      "signoff": false,
      "acknowledge": false,
      "comment": false,
      "discuss": false,
      "reopen": false,
      "reassign": false
    }
  }
}

Ask to discuss my review#

POST/v1/talent/reviews.discussWrite

Asks to discuss your released review: adds "Discuss my review" to your next 1:1 with your manager (when your company uses 1:1s) and records the request for your manager and HR. Your own review only, in the app.

Who can call it
Me key owner admin hr member
MCP tool
talent_reviews_discuss on My Workplace
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • review_idstringrequired

Returns

20 fields
  • idstringrequired
  • cycleobjectrequired
    10 fields
    • idstringrequired
    • namestringrequired
    • statusstringrequired
    • release_onstringrequired
    • self_duestring | nullrequired
    • manager_duestringrequired
    • uses_calibrationbooleanrequired
    • second_levelbooleanrequired
    • potential_stepbooleanrequired
    • overall_ratingbooleanrequired

      The manager gives an overall rating (false: a development-only review).

  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • reviewerobject | nullrequired

    null: no reviewer (HR reassigns) or a former manager. Hidden from the person before release.

    2 fields
    • idstringrequired
    • namestringrequired
  • access"hr" | "manager" | "chain" | "self" | "signoff"required
  • releasedboolean | nullrequired

    null for the person before release (they learn nothing about status).

  • stepsobject | nullrequired

    Job tier: HR and managers only.

    3 fields
    • self"pending" | "submitted" | "n/a"required
    • manager"pending" | "submitted" | "n/a"required
    • signoff"pending" | "submitted" | "n/a"required
  • sectionsobject[]required
    5 fields
    • idstringrequired
    • titlestringrequired
    • titlesobject
      4 fields
      • selfstring
      • managerstring
      • peerstring
      • upwardstring
    • show_goalsbooleanrequired
    • questionsobject[]required
      6 fields
      • idstringrequired
      • textstringrequired
      • textsobject

        Wording per step (self in the first person); text when absent.

        4 fields
        • selfstring
        • managerstring
        • peerstring
        • upwardstring
      • kind"rating" | "text" | "both"required
      • requiredbooleanrequired
      • for"self" | "manager" | "peer" | "upward"[]required
  • scaleobjectrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • pointsobject[]required
      3 fields
      • valueintegerrequired
      • labelstringrequired
      • descriptionstringrequired
  • selfobject | nullrequired
    2 fields
    • answersobject[]required
      3 fields
      • question_idstringrequired
      • ratinginteger | nullrequired
      • textstring | nullrequired
    • submitted_atstring | nullrequired
  • managerobject | nullrequired
    3 fields
    • answersobject[]required
      3 fields
      • question_idstringrequired
      • ratinginteger | nullrequired
      • textstring | nullrequired
    • ratinginteger | nullrequired
    • submitted_atstring | nullrequired
  • final_ratinginteger | nullrequired

    The rating after calibration (or the manager's): HR and managers, and the person once released.

  • groupsobject[]required
    5 fields
    • kind"peer" | "upward"required
    • shownbooleanrequired

      false: fewer answers than the anonymity threshold; withheld from everyone.

    • answeredinteger | nullrequired

      How many answered (HR, the reviewer and higher managers); null for the person.

    • askedinteger | nullrequired
    • answersobject[]required

      Unattributed, texts shuffled: never who wrote what.

      3 fields
      • question_idstringrequired
      • ratingsinteger[]required
      • textsstring[]required
  • signoffobject | nullrequired
    3 fields
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • atstring | nullrequired
    • sent_back_notestring | nullrequired
  • ackobject | nullrequired
    1 field
    • atstringrequired
  • commentobject | nullrequired
    2 fields
    • textstringrequired
    • atstringrequired
  • discuss_requested_atstring | nullrequired
  • left_onstring | nullrequired

    HR and managers: the review closed as "left" on this day.

  • canobjectrequired
    8 fields
    • answer_selfbooleanrequired
    • answer_managerbooleanrequired
    • signoffbooleanrequired
    • acknowledgebooleanrequired
    • commentbooleanrequired
    • discussbooleanrequired
    • reopenbooleanrequired
    • reassignbooleanrequired
  • topic_addedbooleanrequired

    false: no 1:1 with your manager to add it to; your manager and HR still see the request.

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/reviews.discuss \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"review_id":"rv1"}'
Response
{
  "data": {
    "id": "rv1",
    "cycle": {
      "id": "cy1",
      "name": "Annual review 2026",
      "status": "active",
      "release_on": "2026-12-02",
      "self_due": "2026-11-25",
      "manager_due": "2026-11-30",
      "uses_calibration": true,
      "second_level": false,
      "potential_step": false,
      "overall_rating": true
    },
    "person": {
      "id": "p2",
      "name": "Tomás Silva"
    },
    "reviewer": {
      "id": "p1",
      "name": "Ana Costa"
    },
    "access": "self",
    "released": true,
    "steps": {
      "self": "submitted",
      "manager": "pending",
      "signoff": "n/a"
    },
    "sections": [
      {
        "id": "s1",
        "title": "Progress",
        "show_goals": true,
        "questions": [
          {
            "id": "q1",
            "text": "Where are the goals now?",
            "kind": "text",
            "required": true,
            "for": [
              "self",
              "manager"
            ]
          }
        ]
      },
      {
        "id": "s2",
        "title": "Overall",
        "show_goals": false,
        "questions": [
          {
            "id": "q3",
            "text": "Overall rating so far.",
            "kind": "rating",
            "required": true,
            "for": [
              "manager"
            ]
          }
        ]
      }
    ],
    "scale": {
      "id": "five",
      "name": "5-point",
      "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."
        }
      ]
    },
    "self": {
      "answers": [
        {
          "question_id": "q1",
          "rating": null,
          "text": "Halfway there."
        }
      ],
      "submitted_at": "2026-11-20T10:00:00.000Z"
    },
    "manager": {
      "answers": [],
      "rating": null,
      "submitted_at": null
    },
    "final_rating": null,
    "groups": [
      {
        "kind": "peer",
        "shown": true,
        "answered": 3,
        "asked": 4,
        "answers": [
          {
            "question_id": "q1",
            "ratings": [],
            "texts": [
              "Clear priorities.",
              "Helpful in reviews.",
              "Calm under pressure."
            ]
          }
        ]
      }
    ],
    "signoff": null,
    "ack": null,
    "comment": null,
    "discuss_requested_at": "2026-12-02T10:00:00.000Z",
    "left_on": null,
    "can": {
      "answer_self": false,
      "answer_manager": true,
      "signoff": false,
      "acknowledge": false,
      "comment": false,
      "discuss": false,
      "reopen": false,
      "reassign": false
    },
    "topic_added": true
  }
}

Peer reviewers of a review#

POST/v1/talent/feedback.nominationsRead

Who gives peer feedback on a review: the person sees whom they chose (and whether their manager has asked them); the reviewer and HR see who is nominated and who is asked, with how many answered — never who answered or declined. In the app only (API keys and AI assistants can't read it). Limits: 3–8 peers; a colleague is asked at most 12 times a cycle (full lists them).

Web app only
Refused for API keys and connected apps. Who gives feedback is shown in the app only.
MCP tool
talent_feedback_nominations on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • review_idstringrequired

Returns

10 fields
  • review_idstringrequired
  • cycleobjectrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • nominate_bystring | nullrequired
    • peer_duestring | nullrequired
  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • peopleobject[]required
    2 fields
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • state"nominated" | "asked"required

      asked: approved (whether they answered or declined is never shown).

  • countsobject | nullrequired

    The reviewer and HR: how many answered (never who).

    2 fields
    • askedintegerrequired
    • answeredintegerrequired
  • minintegerrequired
  • maxintegerrequired
  • fullstring[]required

    People already asked for the most peer reviews this cycle (12): pick someone else.

  • can_nominatebooleanrequired
  • can_decidebooleanrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/feedback.nominations \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"review_id":"rv1"}'
Response
{
  "data": {
    "review_id": "rv1",
    "cycle": {
      "id": "cy1",
      "name": "Annual review 2026",
      "nominate_by": "2026-11-18",
      "peer_due": "2026-11-24"
    },
    "person": {
      "id": "p2",
      "name": "Tomás Silva"
    },
    "people": [
      {
        "person": {
          "id": "p3",
          "name": "Rita Gomes"
        },
        "state": "asked"
      }
    ],
    "counts": {
      "asked": 4,
      "answered": 3
    },
    "min": 3,
    "max": 8,
    "full": [],
    "can_nominate": false,
    "can_decide": true
  }
}

Approve peer reviewers#

POST/v1/talent/feedback.decideWrite

The reviewer approves the person's nominations (approve), removes some (remove) and adds others (add); people asked get an email within the day that says it is anonymous. 8 peers at most. In the app only.

Web app only
Refused for API keys and connected apps. Managers approve peers in the app only.
MCP tool
talent_feedback_decide 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

  • review_idstringrequired
  • approvestring[]

    1–200 characters. Up to 8 items.

  • removestring[]

    1–200 characters. Up to 8 items.

  • addstring[]

    1–200 characters. Up to 8 items.

Returns

10 fields
  • review_idstringrequired
  • cycleobjectrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • nominate_bystring | nullrequired
    • peer_duestring | nullrequired
  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • peopleobject[]required
    2 fields
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • state"nominated" | "asked"required

      asked: approved (whether they answered or declined is never shown).

  • countsobject | nullrequired

    The reviewer and HR: how many answered (never who).

    2 fields
    • askedintegerrequired
    • answeredintegerrequired
  • minintegerrequired
  • maxintegerrequired
  • fullstring[]required

    People already asked for the most peer reviews this cycle (12): pick someone else.

  • can_nominatebooleanrequired
  • can_decidebooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/feedback.decide \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"review_id":"rv1","approve":["p3"],"remove":["p4"],"add":["p6"]}'
Response
{
  "data": {
    "review_id": "rv1",
    "cycle": {
      "id": "cy1",
      "name": "Annual review 2026",
      "nominate_by": "2026-11-18",
      "peer_due": "2026-11-24"
    },
    "person": {
      "id": "p2",
      "name": "Tomás Silva"
    },
    "people": [
      {
        "person": {
          "id": "p3",
          "name": "Rita Gomes"
        },
        "state": "asked"
      }
    ],
    "counts": {
      "asked": 4,
      "answered": 3
    },
    "min": 3,
    "max": 8,
    "full": [],
    "can_nominate": false,
    "can_decide": true
  }
}

Add peer reviewers (HR)#

POST/v1/talent/feedback.addWrite

HR asks more colleagues for peer feedback on a review (within the caps). Owners, admins and HR.

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

  • review_idstringrequired
  • person_idsstring[]required

    1–200 characters. 1–8 items.

Returns

10 fields
  • review_idstringrequired
  • cycleobjectrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • nominate_bystring | nullrequired
    • peer_duestring | nullrequired
  • personobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • peopleobject[]required
    2 fields
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • state"nominated" | "asked"required

      asked: approved (whether they answered or declined is never shown).

  • countsobject | nullrequired

    The reviewer and HR: how many answered (never who).

    2 fields
    • askedintegerrequired
    • answeredintegerrequired
  • minintegerrequired
  • maxintegerrequired
  • fullstring[]required

    People already asked for the most peer reviews this cycle (12): pick someone else.

  • can_nominatebooleanrequired
  • can_decidebooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/feedback.add \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"review_id":"rv1","person_ids":["p6"]}'
Response
{
  "data": {
    "review_id": "rv1",
    "cycle": {
      "id": "cy1",
      "name": "Annual review 2026",
      "nominate_by": "2026-11-18",
      "peer_due": "2026-11-24"
    },
    "person": {
      "id": "p2",
      "name": "Tomás Silva"
    },
    "people": [
      {
        "person": {
          "id": "p3",
          "name": "Rita Gomes"
        },
        "state": "asked"
      }
    ],
    "counts": {
      "asked": 4,
      "answered": 3
    },
    "min": 3,
    "max": 8,
    "full": [],
    "can_nominate": false,
    "can_decide": true
  }
}

List goals#

POST/v1/talent/goals.listRead

Goals you can see: company and team goals (everyone but viewers), person goals of yourself, the people you manage (all levels down) and, for HR, everyone; others' person goals only when shared with the company. Filters: level, unit_id, person_id, period (goals overlapping from–to), status. API keys and AI assistants see company, team and shared goals only.

Who can call it
Manage key owner admin hr
Me key owner admin hr member
Keys and apps
Company, team and shared goals only; never private personal goals.
MCP tool
talent_goals_list on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • level"company" | "team" | "person"
  • unit_idstring

    1–200 characters.

  • person_idstring

    1–200 characters.

  • fromstring

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

  • tostring

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

  • status"on_track" | "at_risk" | "off_track" | "done" | "dropped"

Returns

  • itemsobject[]required
    19 fields
    • idstringrequired
    • level"company" | "team" | "person"required
    • ownerobjectrequired
      2 fields
      • unitobject | nullrequired
        2 fields
        • idstringrequired
        • namestring | nullrequired
      • personobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
    • owner_leftbooleanrequired

      The owner no longer works here: the goal stays, with no owner.

    • parentobject | nullrequired

      The goal it aligns to (null when you can't see it).

      2 fields
      • idstringrequired
      • titlestringrequired
    • depthintegerrequired
    • titlestringrequired
    • descriptionstringrequired
    • periodobjectrequired
      3 fields
      • startstringrequired
      • endstringrequired
      • labelstringrequired
    • key_resultsobject[]required
      6 fields
      • idstringrequired
      • titlestringrequired
      • kind"number" | "percent" | "money" | "done"required
      • startnumberrequired
      • targetnumberrequired
      • currentnumberrequired
    • manual_progressnumber | nullrequired
    • progressnumberrequired
    • status"on_track" | "at_risk" | "off_track" | "done" | "dropped"required
    • sharedbooleanrequired
    • targets_lockedbooleanrequired
    • committedbooleanrequired

      HR marked it a committed goal (not a stretch OKR): only committed goals can count toward a bonus, when a bonus plan weights goals in.

    • childrenintegerrequired

      Goals aligned to it that you can see.

    • canobjectrequired
      3 fields
      • editbooleanrequired
      • progressbooleanrequired
      • lockbooleanrequired
    • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/goals.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"level":"team","from":"2026-10-01","to":"2026-12-31"}'
Response
{
  "data": {
    "items": [
      {
        "id": "g1",
        "level": "team",
        "owner": {
          "unit": {
            "id": "u1",
            "name": "Customer care"
          },
          "person": null
        },
        "owner_left": false,
        "parent": {
          "id": "g0",
          "title": "Customers love us"
        },
        "depth": 2,
        "title": "Answer within an hour",
        "description": "",
        "period": {
          "start": "2026-10-01",
          "end": "2026-12-31",
          "label": "2026 Q4"
        },
        "key_results": [
          {
            "id": "kr1",
            "title": "Median first reply (min)",
            "kind": "number",
            "start": 120,
            "target": 60,
            "current": 90
          }
        ],
        "manual_progress": null,
        "progress": 50,
        "status": "at_risk",
        "shared": false,
        "targets_locked": false,
        "committed": false,
        "children": 3,
        "can": {
          "edit": true,
          "progress": true,
          "lock": true
        },
        "updated_at": "2026-11-14T10:00:00.000Z"
      }
    ]
  }
}

Get a goal#

POST/v1/talent/goals.getRead

One goal with its key results, the goals aligned to it you can see, and its updates (who, progress, note, from a 1:1, a check-in or by hand). API keys and AI assistants read company, team and shared goals only.

Who can call it
Manage key owner admin hr
Me key owner admin hr member
Keys and apps
Company, team and shared goals only.
MCP tool
talent_goals_get on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • goal_idstringrequired

    1–200 characters.

Returns

21 fields
  • idstringrequired
  • level"company" | "team" | "person"required
  • ownerobjectrequired
    2 fields
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestring | nullrequired
    • personobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
  • owner_leftbooleanrequired

    The owner no longer works here: the goal stays, with no owner.

  • parentobject | nullrequired

    The goal it aligns to (null when you can't see it).

    2 fields
    • idstringrequired
    • titlestringrequired
  • depthintegerrequired
  • titlestringrequired
  • descriptionstringrequired
  • periodobjectrequired
    3 fields
    • startstringrequired
    • endstringrequired
    • labelstringrequired
  • key_resultsobject[]required
    6 fields
    • idstringrequired
    • titlestringrequired
    • kind"number" | "percent" | "money" | "done"required
    • startnumberrequired
    • targetnumberrequired
    • currentnumberrequired
  • manual_progressnumber | nullrequired
  • progressnumberrequired
  • status"on_track" | "at_risk" | "off_track" | "done" | "dropped"required
  • sharedbooleanrequired
  • targets_lockedbooleanrequired
  • committedbooleanrequired

    HR marked it a committed goal (not a stretch OKR): only committed goals can count toward a bonus, when a bonus plan weights goals in.

  • childrenintegerrequired

    Goals aligned to it that you can see.

  • canobjectrequired
    3 fields
    • editbooleanrequired
    • progressbooleanrequired
    • lockbooleanrequired
  • updated_atstringrequired
  • alignedobject[]required
    19 fields
    • idstringrequired
    • level"company" | "team" | "person"required
    • ownerobjectrequired
      2 fields
      • unitobject | nullrequired
        2 fields
        • idstringrequired
        • namestring | nullrequired
      • personobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
    • owner_leftbooleanrequired

      The owner no longer works here: the goal stays, with no owner.

    • parentobject | nullrequired

      The goal it aligns to (null when you can't see it).

      2 fields
      • idstringrequired
      • titlestringrequired
    • depthintegerrequired
    • titlestringrequired
    • descriptionstringrequired
    • periodobjectrequired
      3 fields
      • startstringrequired
      • endstringrequired
      • labelstringrequired
    • key_resultsobject[]required
      6 fields
      • idstringrequired
      • titlestringrequired
      • kind"number" | "percent" | "money" | "done"required
      • startnumberrequired
      • targetnumberrequired
      • currentnumberrequired
    • manual_progressnumber | nullrequired
    • progressnumberrequired
    • status"on_track" | "at_risk" | "off_track" | "done" | "dropped"required
    • sharedbooleanrequired
    • targets_lockedbooleanrequired
    • committedbooleanrequired

      HR marked it a committed goal (not a stretch OKR): only committed goals can count toward a bonus, when a bonus plan weights goals in.

    • childrenintegerrequired

      Goals aligned to it that you can see.

    • canobjectrequired
      3 fields
      • editbooleanrequired
      • progressbooleanrequired
      • lockbooleanrequired
    • updated_atstringrequired
  • updatesobject[]required
    6 fields
    • idstringrequired
    • byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • progressnumberrequired
    • notestring | nullrequired
    • via"manual" | "one_on_one" | "check_in"required
    • atstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/goals.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"goal_id":"g1"}'
Response
{
  "data": {
    "id": "g1",
    "level": "team",
    "owner": {
      "unit": {
        "id": "u1",
        "name": "Customer care"
      },
      "person": null
    },
    "owner_left": false,
    "parent": {
      "id": "g0",
      "title": "Customers love us"
    },
    "depth": 2,
    "title": "Answer within an hour",
    "description": "",
    "period": {
      "start": "2026-10-01",
      "end": "2026-12-31",
      "label": "2026 Q4"
    },
    "key_results": [
      {
        "id": "kr1",
        "title": "Median first reply (min)",
        "kind": "number",
        "start": 120,
        "target": 60,
        "current": 90
      }
    ],
    "manual_progress": null,
    "progress": 50,
    "status": "at_risk",
    "shared": false,
    "targets_locked": false,
    "committed": false,
    "children": 3,
    "can": {
      "edit": true,
      "progress": true,
      "lock": true
    },
    "updated_at": "2026-11-14T10:00:00.000Z",
    "aligned": [],
    "updates": [
      {
        "id": "gu1",
        "by": {
          "id": "p1",
          "name": "Ana Costa"
        },
        "progress": 50,
        "note": null,
        "via": "one_on_one",
        "at": "2026-11-14T10:00:00.000Z"
      }
    ]
  }
}

Create a goal#

POST/v1/talent/goals.createWrite

Creates a goal: level company (owners, admins and HR), team (owner_unit_id; HR or a manager of people in that team) or person (owner_person_id, default you; the person or their direct manager — higher managers read them). parent_id aligns it to a goal one level up (at most 4 levels). title, description, period {start, end, label}, 0–5 key_results (number, percent, money or done, with start, target and current) or manual_progress (0–100) when there are none, shared (a person goal everyone may see). 20 goals per owner per period.

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

  • level"company" | "team" | "person"required
  • owner_unit_idstring

    1–200 characters.

  • owner_person_idstring

    1–200 characters.

  • parent_idstring | null

    1–200 characters.

  • titlestringrequired

    1–200 characters.

  • descriptionstring

    Up to 5000 characters. Default "".

  • periodobjectrequired
    3 fields
    • startstringrequired

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

    • endstringrequired

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

    • labelstringrequired

      e.g. "2026 Q4", "H1 2027", "2027".

      1–40 characters.

  • key_resultsobject[]

    Up to 5 items.

    6 fields
    • idstring

      Keep the id when editing.

      Pattern ^[a-z0-9_-]{1,40}$.

    • titlestringrequired

      1–200 characters.

    • kind"number" | "percent" | "money" | "done"required

      number, percent, money (an amount, no currency conversion) or done (0 or 1).

    • startnumberrequired
    • targetnumberrequired
    • currentnumber
  • manual_progressnumber | null

    From 0 to 100.

  • sharedboolean

    Default false.

Returns

19 fields
  • idstringrequired
  • level"company" | "team" | "person"required
  • ownerobjectrequired
    2 fields
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestring | nullrequired
    • personobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
  • owner_leftbooleanrequired

    The owner no longer works here: the goal stays, with no owner.

  • parentobject | nullrequired

    The goal it aligns to (null when you can't see it).

    2 fields
    • idstringrequired
    • titlestringrequired
  • depthintegerrequired
  • titlestringrequired
  • descriptionstringrequired
  • periodobjectrequired
    3 fields
    • startstringrequired
    • endstringrequired
    • labelstringrequired
  • key_resultsobject[]required
    6 fields
    • idstringrequired
    • titlestringrequired
    • kind"number" | "percent" | "money" | "done"required
    • startnumberrequired
    • targetnumberrequired
    • currentnumberrequired
  • manual_progressnumber | nullrequired
  • progressnumberrequired
  • status"on_track" | "at_risk" | "off_track" | "done" | "dropped"required
  • sharedbooleanrequired
  • targets_lockedbooleanrequired
  • committedbooleanrequired

    HR marked it a committed goal (not a stretch OKR): only committed goals can count toward a bonus, when a bonus plan weights goals in.

  • childrenintegerrequired

    Goals aligned to it that you can see.

  • canobjectrequired
    3 fields
    • editbooleanrequired
    • progressbooleanrequired
    • lockbooleanrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/goals.create \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "level": "team",
  "owner_unit_id": "u1",
  "parent_id": "g0",
  "title": "Answer within an hour",
  "period": {
    "start": "2026-10-01",
    "end": "2026-12-31",
    "label": "2026 Q4"
  },
  "key_results": [
    {
      "title": "Median first reply (min)",
      "kind": "number",
      "start": 120,
      "target": 60
    }
  ]
}'
Response
{
  "data": {
    "id": "g1",
    "level": "team",
    "owner": {
      "unit": {
        "id": "u1",
        "name": "Customer care"
      },
      "person": null
    },
    "owner_left": false,
    "parent": {
      "id": "g0",
      "title": "Customers love us"
    },
    "depth": 2,
    "title": "Answer within an hour",
    "description": "",
    "period": {
      "start": "2026-10-01",
      "end": "2026-12-31",
      "label": "2026 Q4"
    },
    "key_results": [
      {
        "id": "kr1",
        "title": "Median first reply (min)",
        "kind": "number",
        "start": 120,
        "target": 60,
        "current": 90
      }
    ],
    "manual_progress": null,
    "progress": 50,
    "status": "at_risk",
    "shared": false,
    "targets_locked": false,
    "committed": false,
    "children": 3,
    "can": {
      "edit": true,
      "progress": true,
      "lock": true
    },
    "updated_at": "2026-11-14T10:00:00.000Z"
  }
}

Change a goal#

POST/v1/talent/goals.updateWrite

Changes a goal (only what is given): title, description, period, key_results (the full list; targets can't change once locked unless you may lock), shared, targets_locked (the manager chain or HR lock a goal's targets for the period), committed (HR only, person goals: a committed goal rather than a stretch OKR; only committed goals can count toward a bonus). Who may: as for creating it.

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

  • goal_idstringrequired

    1–200 characters.

  • titlestring

    1–200 characters.

  • descriptionstring

    Up to 5000 characters.

  • periodobject
    3 fields
    • startstringrequired

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

    • endstringrequired

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

    • labelstringrequired

      e.g. "2026 Q4", "H1 2027", "2027".

      1–40 characters.

  • key_resultsobject[]

    Up to 5 items.

    6 fields
    • idstring

      Keep the id when editing.

      Pattern ^[a-z0-9_-]{1,40}$.

    • titlestringrequired

      1–200 characters.

    • kind"number" | "percent" | "money" | "done"required

      number, percent, money (an amount, no currency conversion) or done (0 or 1).

    • startnumberrequired
    • targetnumberrequired
    • currentnumber
  • sharedboolean
  • targets_lockedboolean
  • committedboolean

Returns

19 fields
  • idstringrequired
  • level"company" | "team" | "person"required
  • ownerobjectrequired
    2 fields
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestring | nullrequired
    • personobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
  • owner_leftbooleanrequired

    The owner no longer works here: the goal stays, with no owner.

  • parentobject | nullrequired

    The goal it aligns to (null when you can't see it).

    2 fields
    • idstringrequired
    • titlestringrequired
  • depthintegerrequired
  • titlestringrequired
  • descriptionstringrequired
  • periodobjectrequired
    3 fields
    • startstringrequired
    • endstringrequired
    • labelstringrequired
  • key_resultsobject[]required
    6 fields
    • idstringrequired
    • titlestringrequired
    • kind"number" | "percent" | "money" | "done"required
    • startnumberrequired
    • targetnumberrequired
    • currentnumberrequired
  • manual_progressnumber | nullrequired
  • progressnumberrequired
  • status"on_track" | "at_risk" | "off_track" | "done" | "dropped"required
  • sharedbooleanrequired
  • targets_lockedbooleanrequired
  • committedbooleanrequired

    HR marked it a committed goal (not a stretch OKR): only committed goals can count toward a bonus, when a bonus plan weights goals in.

  • childrenintegerrequired

    Goals aligned to it that you can see.

  • canobjectrequired
    3 fields
    • editbooleanrequired
    • progressbooleanrequired
    • lockbooleanrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/goals.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"goal_id":"g1","targets_locked":true}'
Response
{
  "data": {
    "id": "g1",
    "level": "team",
    "owner": {
      "unit": {
        "id": "u1",
        "name": "Customer care"
      },
      "person": null
    },
    "owner_left": false,
    "parent": {
      "id": "g0",
      "title": "Customers love us"
    },
    "depth": 2,
    "title": "Answer within an hour",
    "description": "",
    "period": {
      "start": "2026-10-01",
      "end": "2026-12-31",
      "label": "2026 Q4"
    },
    "key_results": [
      {
        "id": "kr1",
        "title": "Median first reply (min)",
        "kind": "number",
        "start": 120,
        "target": 60,
        "current": 90
      }
    ],
    "manual_progress": null,
    "progress": 50,
    "status": "at_risk",
    "shared": false,
    "targets_locked": true,
    "committed": false,
    "children": 3,
    "can": {
      "edit": true,
      "progress": true,
      "lock": true
    },
    "updated_at": "2026-11-14T10:00:00.000Z"
  }
}

Update a goal's progress#

POST/v1/talent/goals.progressWrite

Records progress on a goal: kr_values (key result id and current value), or manual_progress (0–100) for a goal without key results, status (on_track, at_risk, off_track), a note, and where it came from (via manual, one_on_one with ref_id = the meeting, check_in with ref_id = the check-in). The goal's owner, their managers, the team's managers or HR. Up to 500 updates per goal.

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

  • goal_idstringrequired

    1–200 characters.

  • kr_valuesobject[]

    Up to 5 items.

    2 fields
    • idstringrequired
    • currentnumberrequired
  • manual_progressnumber

    From 0 to 100.

  • status"on_track" | "at_risk" | "off_track"
  • notestring | null

    Up to 1000 characters.

  • via"manual" | "one_on_one" | "check_in"

    Default "manual".

  • ref_idstring | null

    1–200 characters.

Returns

19 fields
  • idstringrequired
  • level"company" | "team" | "person"required
  • ownerobjectrequired
    2 fields
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestring | nullrequired
    • personobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
  • owner_leftbooleanrequired

    The owner no longer works here: the goal stays, with no owner.

  • parentobject | nullrequired

    The goal it aligns to (null when you can't see it).

    2 fields
    • idstringrequired
    • titlestringrequired
  • depthintegerrequired
  • titlestringrequired
  • descriptionstringrequired
  • periodobjectrequired
    3 fields
    • startstringrequired
    • endstringrequired
    • labelstringrequired
  • key_resultsobject[]required
    6 fields
    • idstringrequired
    • titlestringrequired
    • kind"number" | "percent" | "money" | "done"required
    • startnumberrequired
    • targetnumberrequired
    • currentnumberrequired
  • manual_progressnumber | nullrequired
  • progressnumberrequired
  • status"on_track" | "at_risk" | "off_track" | "done" | "dropped"required
  • sharedbooleanrequired
  • targets_lockedbooleanrequired
  • committedbooleanrequired

    HR marked it a committed goal (not a stretch OKR): only committed goals can count toward a bonus, when a bonus plan weights goals in.

  • childrenintegerrequired

    Goals aligned to it that you can see.

  • canobjectrequired
    3 fields
    • editbooleanrequired
    • progressbooleanrequired
    • lockbooleanrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/goals.progress \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "goal_id": "g1",
  "kr_values": [
    {
      "id": "kr1",
      "current": 90
    }
  ],
  "status": "at_risk",
  "via": "one_on_one",
  "ref_id": "m1"
}'
Response
{
  "data": {
    "id": "g1",
    "level": "team",
    "owner": {
      "unit": {
        "id": "u1",
        "name": "Customer care"
      },
      "person": null
    },
    "owner_left": false,
    "parent": {
      "id": "g0",
      "title": "Customers love us"
    },
    "depth": 2,
    "title": "Answer within an hour",
    "description": "",
    "period": {
      "start": "2026-10-01",
      "end": "2026-12-31",
      "label": "2026 Q4"
    },
    "key_results": [
      {
        "id": "kr1",
        "title": "Median first reply (min)",
        "kind": "number",
        "start": 120,
        "target": 60,
        "current": 90
      }
    ],
    "manual_progress": null,
    "progress": 50,
    "status": "at_risk",
    "shared": false,
    "targets_locked": false,
    "committed": false,
    "children": 3,
    "can": {
      "edit": true,
      "progress": true,
      "lock": true
    },
    "updated_at": "2026-11-14T10:00:00.000Z"
  }
}

Close or reopen a goal#

POST/v1/talent/goals.closeWrite

Marks a goal done or dropped, or reopens it (on_track). Who may: as for changing it.

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

Input

  • goal_idstringrequired

    1–200 characters.

  • status"done" | "dropped" | "on_track"required

Returns

19 fields
  • idstringrequired
  • level"company" | "team" | "person"required
  • ownerobjectrequired
    2 fields
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestring | nullrequired
    • personobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
  • owner_leftbooleanrequired

    The owner no longer works here: the goal stays, with no owner.

  • parentobject | nullrequired

    The goal it aligns to (null when you can't see it).

    2 fields
    • idstringrequired
    • titlestringrequired
  • depthintegerrequired
  • titlestringrequired
  • descriptionstringrequired
  • periodobjectrequired
    3 fields
    • startstringrequired
    • endstringrequired
    • labelstringrequired
  • key_resultsobject[]required
    6 fields
    • idstringrequired
    • titlestringrequired
    • kind"number" | "percent" | "money" | "done"required
    • startnumberrequired
    • targetnumberrequired
    • currentnumberrequired
  • manual_progressnumber | nullrequired
  • progressnumberrequired
  • status"on_track" | "at_risk" | "off_track" | "done" | "dropped"required
  • sharedbooleanrequired
  • targets_lockedbooleanrequired
  • committedbooleanrequired

    HR marked it a committed goal (not a stretch OKR): only committed goals can count toward a bonus, when a bonus plan weights goals in.

  • childrenintegerrequired

    Goals aligned to it that you can see.

  • canobjectrequired
    3 fields
    • editbooleanrequired
    • progressbooleanrequired
    • lockbooleanrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/goals.close \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"goal_id":"g1","status":"done"}'
Response
{
  "data": {
    "id": "g1",
    "level": "team",
    "owner": {
      "unit": {
        "id": "u1",
        "name": "Customer care"
      },
      "person": null
    },
    "owner_left": false,
    "parent": {
      "id": "g0",
      "title": "Customers love us"
    },
    "depth": 2,
    "title": "Answer within an hour",
    "description": "",
    "period": {
      "start": "2026-10-01",
      "end": "2026-12-31",
      "label": "2026 Q4"
    },
    "key_results": [
      {
        "id": "kr1",
        "title": "Median first reply (min)",
        "kind": "number",
        "start": 120,
        "target": 60,
        "current": 90
      }
    ],
    "manual_progress": null,
    "progress": 50,
    "status": "done",
    "shared": false,
    "targets_locked": false,
    "committed": false,
    "children": 3,
    "can": {
      "edit": true,
      "progress": true,
      "lock": true
    },
    "updated_at": "2026-11-14T10:00:00.000Z"
  }
}

Align a goal#

POST/v1/talent/goals.alignWrite

Aligns a goal to a goal one level up (parent_id), or removes the alignment (null). At most 4 levels; goals aligned to it move with it. Who may: as for changing it.

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

Input

  • goal_idstringrequired

    1–200 characters.

  • parent_idstring | nullrequired

    1–200 characters.

Returns

19 fields
  • idstringrequired
  • level"company" | "team" | "person"required
  • ownerobjectrequired
    2 fields
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestring | nullrequired
    • personobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
  • owner_leftbooleanrequired

    The owner no longer works here: the goal stays, with no owner.

  • parentobject | nullrequired

    The goal it aligns to (null when you can't see it).

    2 fields
    • idstringrequired
    • titlestringrequired
  • depthintegerrequired
  • titlestringrequired
  • descriptionstringrequired
  • periodobjectrequired
    3 fields
    • startstringrequired
    • endstringrequired
    • labelstringrequired
  • key_resultsobject[]required
    6 fields
    • idstringrequired
    • titlestringrequired
    • kind"number" | "percent" | "money" | "done"required
    • startnumberrequired
    • targetnumberrequired
    • currentnumberrequired
  • manual_progressnumber | nullrequired
  • progressnumberrequired
  • status"on_track" | "at_risk" | "off_track" | "done" | "dropped"required
  • sharedbooleanrequired
  • targets_lockedbooleanrequired
  • committedbooleanrequired

    HR marked it a committed goal (not a stretch OKR): only committed goals can count toward a bonus, when a bonus plan weights goals in.

  • childrenintegerrequired

    Goals aligned to it that you can see.

  • canobjectrequired
    3 fields
    • editbooleanrequired
    • progressbooleanrequired
    • lockbooleanrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/goals.align \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"goal_id":"g1","parent_id":null}'
Response
{
  "data": {
    "id": "g1",
    "level": "team",
    "owner": {
      "unit": {
        "id": "u1",
        "name": "Customer care"
      },
      "person": null
    },
    "owner_left": false,
    "parent": {
      "id": "g0",
      "title": "Customers love us"
    },
    "depth": 2,
    "title": "Answer within an hour",
    "description": "",
    "period": {
      "start": "2026-10-01",
      "end": "2026-12-31",
      "label": "2026 Q4"
    },
    "key_results": [
      {
        "id": "kr1",
        "title": "Median first reply (min)",
        "kind": "number",
        "start": 120,
        "target": 60,
        "current": 90
      }
    ],
    "manual_progress": null,
    "progress": 50,
    "status": "at_risk",
    "shared": false,
    "targets_locked": false,
    "committed": false,
    "children": 3,
    "can": {
      "edit": true,
      "progress": true,
      "lock": true
    },
    "updated_at": "2026-11-14T10:00:00.000Z"
  }
}

Whether goal suggestions can be asked for#

POST/v1/talent/goals.suggest_statusRead

Whether you can ask for AI suggestions of measures for a goal: switched on by the company (an owner accepted the AI features addendum), how many you have left today (of 20) and about how many AI credits one uses. In the app only.

Web app only
Refused for API keys and connected apps. Whether goal suggestions can be asked for is read in the app only.
MCP tool
talent_goals_suggest_status on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • availablebooleanrequired
  • reason"unavailable" | "off" | "addendum"required

    unavailable: not on this server; off: the company has not switched it on; addendum: the AI features addendum needs an owner's acceptance again.

  • per_dayintegerrequired
  • left_todayintegerrequired
  • creditsobjectrequired

    AI credits a suggestion typically uses, and the most one can.

    2 fields
    • estimateintegerrequired
    • maxintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/goals.suggest_status \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "available": true,
    "reason": null,
    "per_day": 20,
    "left_today": 18,
    "credits": {
      "estimate": 1,
      "max": 1
    }
  }
}

Suggest measures for a goal#

POST/v1/talent/goals.suggest_measuresWrite

Suggests up to 5 measurable key results (title, number/percent/money/done, start and target) for a goal you are writing, from its title and description only: they are sent to a language model on Google Cloud Vertex AI in the EU; never ratings, reviews or anything about how a person performs. Written by an AI (ai_generated): nothing is saved; add the ones you want with talent_goals_update or talent_goals_create. Uses AI credits of the company by the tokens used (about 0; at most 0); nothing when it fails or suggests nothing. At most 20 a day per person. Only when the company switched goal suggestions on. A dry run says the cost without asking. In the app only.

Web app only
Refused for API keys and connected apps. AI suggestions of measures for a goal are asked for in the app only (an AI calling an AI would spend credits).
MCP tool
talent_goals_suggest_measures 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

  • titlestringrequired

    3–200 characters.

  • descriptionstring

    Up to 1000 characters.

  • level"company" | "team" | "person"
  • language"en" | "pt" | "es" | "de" | "fr" | "it"

    Your app language: suggestions are written in it.

Returns

  • suggestionsobject[]required
    4 fields
    • titlestringrequired
    • kind"number" | "percent" | "money" | "done"required
    • startnumberrequired
    • targetnumberrequired
  • ai_generatedtruerequired
  • ai_creditsobjectrequired
    2 fields
    • costintegerrequired

      What this used (a dry run: what it would use, about).

    • leftinteger | nullrequired
  • left_todayintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/goals.suggest_measures \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "title": "Answer every chat faster",
  "description": "Contact centre, Spanish queue.",
  "level": "team",
  "language": "pt"
}'
Response
{
  "data": {
    "suggestions": [
      {
        "title": "Median first reply (min)",
        "kind": "number",
        "start": 6,
        "target": 2
      },
      {
        "title": "CSAT",
        "kind": "percent",
        "start": 80,
        "target": 90
      },
      {
        "title": "Runbook published",
        "kind": "done",
        "start": 0,
        "target": 1
      }
    ],
    "ai_generated": true,
    "ai_credits": {
      "cost": 1,
      "left": 1240
    },
    "left_today": 17
  }
}

Remind people in a review cycle#

POST/v1/talent/cycles.remindWrite

Emails everyone with a step past its due date in a running cycle (self-reviews, manager reviews, sign-offs; and feedback requests past the peer date): one email per person naming the cycle and the date, never whose review. Once a day per cycle. Owners, admins and HR.

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

Input

  • cycle_idstringrequired

Returns

  • remindedintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/cycles.remind \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"cycle_id":"cy1"}'
Response
{
  "data": {
    "reminded": 14
  }
}

Check ratings by sex#

POST/v1/talent/cycles.sex_checkWrite

For a launched review cycle (cycle_id): how ratings, potential and calibration moves are spread between women and men (EU Pay Transparency Directive: progression criteria must be objective and gender-neutral), for the whole cycle and each calibration session. Shares per rating and potential level, mean rating and gap, top and bottom ratings, High potential, moves up and down. Flags (a reason to look, not proof of bias): a women-to-men ratio outside 0.8–1.25, or a mean gap of 5 % of the scale's range or more. Groups with fewer than 5 women or men are hidden. Uses sex recorded for equal-pay reporting; counts only, never per person. Owners, admins and HR, in the app only; each run is recorded in Activity; nothing is stored.

Web app only
Refused for API keys and connected apps. Ratings by sex are checked in the app only.
MCP tool
talent_cycles_sex_check on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • cycle_idstringrequired

Returns

  • cycleobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • scaleobject[]required
    2 fields
    • valueintegerrequired
    • labelstringrequired
  • recordedobjectrequired

    People in the check by recorded sex; not_included: another, prefers not to say or not recorded.

    3 fields
    • womenintegerrequired
    • menintegerrequired
    • not_includedintegerrequired
  • min_groupintegerrequired
  • totalobjectrequired
    9 fields
    • womeninteger | nullrequired
    • meninteger | nullrequired
    • not_includedinteger | nullrequired

      null when the group is hidden (its counts would say who is a woman or a man).

    • suppressedbooleanrequired

      Fewer than min_group women or men here (or hidden so another hidden group can't be worked out): no figures.

    • ratingobject | nullrequired
      7 fields
      • levelsobject[]required
        3 fields
        • valueintegerrequired
        • women_pctnumberrequired
        • men_pctnumberrequired
      • women_meannumberrequired
      • men_meannumberrequired
      • gap_pointsnumberrequired

        Men's mean rating − women's: positive when women are rated lower.

      • gap_pct_of_rangenumberrequired

        The gap as % of the scale's range (flagged from 5 %).

      • topobjectrequired
        3 fields
        • women_pctnumberrequired
        • men_pctnumberrequired
        • rationumber | nullrequired
      • bottomobjectrequired
        3 fields
        • women_pctnumberrequired
        • men_pctnumberrequired
        • rationumber | nullrequired
    • potentialobject | nullrequired
      2 fields
      • levelsobject[]required
        3 fields
        • level"low" | "moderate" | "high"required
        • women_pctnumberrequired
        • men_pctnumberrequired
      • highobjectrequired
        3 fields
        • women_pctnumberrequired
        • men_pctnumberrequired
        • rationumber | nullrequired
    • movesobject | nullrequired

      Calibration moves as shares of each sex (ratio: women's rate ÷ men's; null with fewer than 5 such moves).

      4 fields
      • rating_upobjectrequired
        3 fields
        • women_pctnumberrequired
        • men_pctnumberrequired
        • rationumber | nullrequired
      • rating_downobjectrequired
        3 fields
        • women_pctnumberrequired
        • men_pctnumberrequired
        • rationumber | nullrequired
      • potential_upobjectrequired
        3 fields
        • women_pctnumberrequired
        • men_pctnumberrequired
        • rationumber | nullrequired
      • potential_downobjectrequired
        3 fields
        • women_pctnumberrequired
        • men_pctnumberrequired
        • rationumber | nullrequired
    • raiseobject | nullrequired
      2 fields
      • levelsobject[]required
        3 fields
        • valueinteger | nullrequired
        • women_meannumber | nullrequired
        • men_meannumber | nullrequired
      • gap_ppnumber | nullrequired
    • flagsstring (enum)[]required

      One of: rating_gap, top_rating, bottom_rating, high_potential, rating_up, rating_down, potential_up, potential_down, raise_gap.

  • sessionsobject[]required
    11 fields
    • womeninteger | nullrequired
    • meninteger | nullrequired
    • not_includedinteger | nullrequired

      null when the group is hidden (its counts would say who is a woman or a man).

    • suppressedbooleanrequired

      Fewer than min_group women or men here (or hidden so another hidden group can't be worked out): no figures.

    • ratingobject | nullrequired
      7 fields
      • levelsobject[]required
        3 fields
        • valueintegerrequired
        • women_pctnumberrequired
        • men_pctnumberrequired
      • women_meannumberrequired
      • men_meannumberrequired
      • gap_pointsnumberrequired

        Men's mean rating − women's: positive when women are rated lower.

      • gap_pct_of_rangenumberrequired

        The gap as % of the scale's range (flagged from 5 %).

      • topobjectrequired
        3 fields
        • women_pctnumberrequired
        • men_pctnumberrequired
        • rationumber | nullrequired
      • bottomobjectrequired
        3 fields
        • women_pctnumberrequired
        • men_pctnumberrequired
        • rationumber | nullrequired
    • potentialobject | nullrequired
      2 fields
      • levelsobject[]required
        3 fields
        • level"low" | "moderate" | "high"required
        • women_pctnumberrequired
        • men_pctnumberrequired
      • highobjectrequired
        3 fields
        • women_pctnumberrequired
        • men_pctnumberrequired
        • rationumber | nullrequired
    • movesobject | nullrequired

      Calibration moves as shares of each sex (ratio: women's rate ÷ men's; null with fewer than 5 such moves).

      4 fields
      • rating_upobjectrequired
        3 fields
        • women_pctnumberrequired
        • men_pctnumberrequired
        • rationumber | nullrequired
      • rating_downobjectrequired
        3 fields
        • women_pctnumberrequired
        • men_pctnumberrequired
        • rationumber | nullrequired
      • potential_upobjectrequired
        3 fields
        • women_pctnumberrequired
        • men_pctnumberrequired
        • rationumber | nullrequired
      • potential_downobjectrequired
        3 fields
        • women_pctnumberrequired
        • men_pctnumberrequired
        • rationumber | nullrequired
    • raiseobject | nullrequired
      2 fields
      • levelsobject[]required
        3 fields
        • valueinteger | nullrequired
        • women_meannumber | nullrequired
        • men_meannumber | nullrequired
      • gap_ppnumber | nullrequired
    • flagsstring (enum)[]required

      One of: rating_gap, top_rating, bottom_rating, high_potential, rating_up, rating_down, potential_up, potential_down, raise_gap.

    • idstringrequired
    • namestringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/talent/cycles.sex_check \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"cycle_id":"cy1"}'
Response
{
  "data": {
    "cycle": {
      "id": "cy1",
      "name": "Annual review 2026"
    },
    "scale": [
      {
        "value": 1,
        "label": "Well below expectations"
      },
      {
        "value": 2,
        "label": "Below expectations"
      },
      {
        "value": 3,
        "label": "Meets expectations"
      },
      {
        "value": 4,
        "label": "Exceeds expectations"
      },
      {
        "value": 5,
        "label": "Outstanding"
      }
    ],
    "recorded": {
      "women": 18,
      "men": 22,
      "not_included": 3
    },
    "min_group": 5,
    "total": {
      "women": 18,
      "men": 22,
      "not_included": 3,
      "suppressed": false,
      "rating": {
        "levels": [
          {
            "value": 1,
            "women_pct": 0,
            "men_pct": 4.5
          },
          {
            "value": 2,
            "women_pct": 16.7,
            "men_pct": 9.1
          },
          {
            "value": 3,
            "women_pct": 50,
            "men_pct": 45.5
          },
          {
            "value": 4,
            "women_pct": 27.8,
            "men_pct": 31.8
          },
          {
            "value": 5,
            "women_pct": 5.6,
            "men_pct": 9.1
          }
        ],
        "women_mean": 3.22,
        "men_mean": 3.32,
        "gap_points": 0.1,
        "gap_pct_of_range": 2.5,
        "top": {
          "women_pct": 33.3,
          "men_pct": 40.9,
          "ratio": 0.815
        },
        "bottom": {
          "women_pct": 16.7,
          "men_pct": 13.6,
          "ratio": 1.228
        }
      },
      "potential": {
        "levels": [
          {
            "level": "low",
            "women_pct": 22.2,
            "men_pct": 18.2
          },
          {
            "level": "moderate",
            "women_pct": 61.1,
            "men_pct": 50
          },
          {
            "level": "high",
            "women_pct": 16.7,
            "men_pct": 31.8
          }
        ],
        "high": {
          "women_pct": 16.7,
          "men_pct": 31.8,
          "ratio": 0.525
        }
      },
      "moves": {
        "rating_up": {
          "women_pct": 40,
          "men_pct": 45,
          "ratio": 0.889
        },
        "rating_down": {
          "women_pct": 11.1,
          "men_pct": 4.5,
          "ratio": null
        },
        "potential_up": {
          "women_pct": 5.6,
          "men_pct": 13.6,
          "ratio": 0.408
        },
        "potential_down": {
          "women_pct": 0,
          "men_pct": 0,
          "ratio": null
        }
      },
      "raise": null,
      "flags": [
        "high_potential",
        "potential_up"
      ]
    },
    "sessions": [
      {
        "women": 18,
        "men": 22,
        "not_included": 3,
        "suppressed": false,
        "rating": {
          "levels": [
            {
              "value": 1,
              "women_pct": 0,
              "men_pct": 4.5
            },
            {
              "value": 2,
              "women_pct": 16.7,
              "men_pct": 9.1
            },
            {
              "value": 3,
              "women_pct": 50,
              "men_pct": 45.5
            },
            {
              "value": 4,
              "women_pct": 27.8,
              "men_pct": 31.8
            },
            {
              "value": 5,
              "women_pct": 5.6,
              "men_pct": 9.1
            }
          ],
          "women_mean": 3.22,
          "men_mean": 3.32,
          "gap_points": 0.1,
          "gap_pct_of_range": 2.5,
          "top": {
            "women_pct": 33.3,
            "men_pct": 40.9,
            "ratio": 0.815
          },
          "bottom": {
            "women_pct": 16.7,
            "men_pct": 13.6,
            "ratio": 1.228
          }
        },
        "potential": {
          "levels": [
            {
              "level": "low",
              "women_pct": 22.2,
              "men_pct": 18.2
            },
            {
              "level": "moderate",
              "women_pct": 61.1,
              "men_pct": 50
            },
            {
              "level": "high",
              "women_pct": 16.7,
              "men_pct": 31.8
            }
          ],
          "high": {
            "women_pct": 16.7,
            "men_pct": 31.8,
            "ratio": 0.525
          }
        },
        "moves": {
          "rating_up": {
            "women_pct": 40,
            "men_pct": 45,
            "ratio": 0.889
          },
          "rating_down": {
            "women_pct": 11.1,
            "men_pct": 4.5,
            "ratio": null
          },
          "potential_up": {
            "women_pct": 5.6,
            "men_pct": 13.6,
            "ratio": 0.408
          },
          "potential_down": {
            "women_pct": 0,
            "men_pct": 0,
            "ratio": null
          }
        },
        "raise": null,
        "flags": [
          "high_potential",
          "potential_up"
        ],
        "id": "cal1",
        "name": "Contact centre"
      },
      {
        "id": "cal2",
        "name": "Sales",
        "women": null,
        "men": null,
        "not_included": null,
        "suppressed": true,
        "rating": null,
        "potential": null,
        "moves": null,
        "raise": null,
        "flags": []
      }
    ]
  }
}

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

Developer docs