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_geton HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
10 fields
scalesobject[]required3 fields
idstringrequirednamestringrequiredpointsobject[]required3 fields
valueintegerrequiredlabelstringrequireddescriptionstringrequired
default_scale_idstringrequiredtarget_curveobjectrequiredPer 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_minintegerrequiredPeer and upward answers show only with at least this many (3–10).
second_level_signoffbooleanrequiredpotential_guidanceobjectrequired3 fields
aspirationstringrequiredabilitystringrequiredengagementstringrequired
retention_yearsintegerrequiredconsultationobject | nullrequiredHR only.
2 fields
notesobject[]requiredThe works council checklist for the countries of your legal entities (informational).
3 fields
countrystring | nullrequiredtextstringrequiredbasisstringrequired
doneobject | nullrequiredTicked "Done or not needed": who (person id) and when.
2 fields
bystring | nullrequiredatstringrequired
profilesobjectrequired2 fields
onbooleanrequiredTalent profiles are on (off by default): each person's education, certificates and experience with their history, courses and skills.
colleaguesbooleanrequiredPeople may choose to show their profile to colleagues (on by default); off: profiles are HR and managers only.
goal_suggestionsobjectrequired4 fields
onbooleanrequiredAI suggestions of measures for goals are switched on for the company.
availablebooleanrequiredThis server can make them (a language model is configured).
addendum_acceptedboolean | nullrequiredHR only: an owner accepted the AI features addendum for goal suggestions (needed to switch on).
addendum_versionstring | nullrequiredHR only: the addendum version to accept.
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/talent/settings.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/talent/settings.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/settings.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"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_updateon HR Assistant- Preview
?dry_run=trueruns 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
idstringrequiredA short id, e.g. "five" or "four_point".
Pattern
^[a-z0-9_-]{1,40}$.namestringrequired1–60 characters.
pointsobject[]required3 to 7 points, lowest first, valued 1, 2, 3…
3–7 items.
3 fields
valueintegerrequiredFrom 1 to 7.
labelstringrequiredWhat the point is called, e.g. "Meets expectations".
1–60 characters.
descriptionstringrequiredOne line shown in the form under the label.
Up to 200 characters.
default_scale_idstringtarget_curveobjectanonymity_minintegerFrom 3 to 10.
second_level_signoffbooleanpotential_guidanceobject3 fields
aspirationstringrequired1–300 characters.
abilitystringrequired1–300 characters.
engagementstringrequired1–300 characters.
retention_yearsintegerFrom 1 to 10.
consultation_donetrueprofilesobject2 fields
onbooleanSwitch talent profiles on or off. Off hides every profile; nothing is deleted.
colleaguesbooleanLet people show their profile to colleagues (each person still chooses; off: HR and managers only).
goal_suggestionsbooleanSwitch 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_addendumobjectOwners only: accept the AI features addendum for goal suggestions (the version shown in Settings → Talent).
2 fields
versionstringrequiredlang"en" | "de" | "es" | "fr" | "it" | "pt"Default
"en".
Returns
10 fields
scalesobject[]required3 fields
idstringrequirednamestringrequiredpointsobject[]required3 fields
valueintegerrequiredlabelstringrequireddescriptionstringrequired
default_scale_idstringrequiredtarget_curveobjectrequiredPer 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_minintegerrequiredPeer and upward answers show only with at least this many (3–10).
second_level_signoffbooleanrequiredpotential_guidanceobjectrequired3 fields
aspirationstringrequiredabilitystringrequiredengagementstringrequired
retention_yearsintegerrequiredconsultationobject | nullrequiredHR only.
2 fields
notesobject[]requiredThe works council checklist for the countries of your legal entities (informational).
3 fields
countrystring | nullrequiredtextstringrequiredbasisstringrequired
doneobject | nullrequiredTicked "Done or not needed": who (person id) and when.
2 fields
bystring | nullrequiredatstringrequired
profilesobjectrequired2 fields
onbooleanrequiredTalent profiles are on (off by default): each person's education, certificates and experience with their history, courses and skills.
colleaguesbooleanrequiredPeople may choose to show their profile to colleagues (on by default); off: profiles are HR and managers only.
goal_suggestionsobjectrequired4 fields
onbooleanrequiredAI suggestions of measures for goals are switched on for the company.
availablebooleanrequiredThis server can make them (a language model is configured).
addendum_acceptedboolean | nullrequiredHR only: an owner accepted the AI features addendum for goal suggestions (needed to switch on).
addendum_versionstring | nullrequiredHR only: the addendum version to accept.
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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
}'const res = await fetch('https://api.bizisy.com/v1/talent/settings.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"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
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/settings.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"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,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
archivedboolean
Returns
itemsobject[]required11 fields
idstringrequiredA saved template's id, or starter:<name> for a starter not saved yet.
namestringrequiredstarterstring | nullrequiredsavedbooleanrequiredarchivedbooleanrequiredstepsobjectrequired4 fields
selfbooleanrequiredmanagerbooleanrequiredpeerbooleanrequiredupwardbooleanrequired
sectionsobject[]required5 fields
idstringrequiredtitlestringrequiredtitlesobject4 fields
selfstringmanagerstringpeerstringupwardstring
show_goalsbooleanrequiredquestionsobject[]required6 fields
idstringrequiredtextstringrequiredtextsobjectWording per step (self in the first person); text when absent.
4 fields
selfstringmanagerstringpeerstringupwardstring
kind"rating" | "text" | "both"requiredrequiredbooleanrequiredfor"self" | "manager" | "peer" | "upward"[]required
scale_idstringrequiredquestionsintegerrequiredoverall_ratingbooleanrequiredThe manager gives an overall rating (false: development only).
updated_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/talent/templates.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"archived":true}'const res = await fetch('https://api.bizisy.com/v1/talent/templates.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"archived": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/templates.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"archived": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
template_idstringrequired
Returns
11 fields
idstringrequiredA saved template's id, or starter:<name> for a starter not saved yet.
namestringrequiredstarterstring | nullrequiredsavedbooleanrequiredarchivedbooleanrequiredstepsobjectrequired4 fields
selfbooleanrequiredmanagerbooleanrequiredpeerbooleanrequiredupwardbooleanrequired
sectionsobject[]required5 fields
idstringrequiredtitlestringrequiredtitlesobject4 fields
selfstringmanagerstringpeerstringupwardstring
show_goalsbooleanrequiredquestionsobject[]required6 fields
idstringrequiredtextstringrequiredtextsobjectWording per step (self in the first person); text when absent.
4 fields
selfstringmanagerstringpeerstringupwardstring
kind"rating" | "text" | "both"requiredrequiredbooleanrequiredfor"self" | "manager" | "peer" | "upward"[]required
scale_idstringrequiredquestionsintegerrequiredoverall_ratingbooleanrequiredThe manager gives an overall rating (false: development only).
updated_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/talent/templates.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"template_id": "starter:annual"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/templates.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"template_id": "starter:annual",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_saveon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
namestringrequired1–120 characters.
stepsobjectrequiredWhich steps run; the manager step is always on.
4 fields
selfbooleanrequiredmanagerbooleanrequiredpeerbooleanrequiredupwardbooleanrequired
sectionsobject[]required1–10 items.
5 fields
idstringPattern
^[a-z0-9_-]{1,40}$.titlestringrequired1–120 characters.
titlesobjectSection title per step when it differs (self: "How you work"). Empty or left out: title.
4 fields
selfstringUp to 120 characters.
managerstringUp to 120 characters.
peerstringUp to 120 characters.
upwardstringUp to 120 characters.
show_goalsbooleanShow the person's goals for the review period here (read only).
Default
false.questionsobject[]requiredUp to 30 items.
6 fields
idstringKeep the id when editing a question; leave out for a new one.
Pattern
^[a-z0-9_-]{1,40}$.textstringrequiredThe question as the manager and peers read it (about "them").
1–500 characters.
textsobjectWording per step when it differs, e.g. self: "What should you keep doing?" (first person). Empty or left out: text.
4 fields
selfstringUp to 500 characters.
managerstringUp to 500 characters.
peerstringUp to 500 characters.
upwardstringUp to 500 characters.
kind"rating" | "text" | "both"requiredrating (a point on the scale), text, or both.
requiredbooleanDefault
true.for"self" | "manager" | "peer" | "upward"[]requiredWhich steps answer it: self, manager, peer, upward.
At least 1 item.
scale_idstringrequiredA scale from talent_settings_get.
overall_ratingbooleanThe 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
idstringrequiredA saved template's id, or starter:<name> for a starter not saved yet.
namestringrequiredstarterstring | nullrequiredsavedbooleanrequiredarchivedbooleanrequiredstepsobjectrequired4 fields
selfbooleanrequiredmanagerbooleanrequiredpeerbooleanrequiredupwardbooleanrequired
sectionsobject[]required5 fields
idstringrequiredtitlestringrequiredtitlesobject4 fields
selfstringmanagerstringpeerstringupwardstring
show_goalsbooleanrequiredquestionsobject[]required6 fields
idstringrequiredtextstringrequiredtextsobjectWording per step (self in the first person); text when absent.
4 fields
selfstringmanagerstringpeerstringupwardstring
kind"rating" | "text" | "both"requiredrequiredbooleanrequiredfor"self" | "manager" | "peer" | "upward"[]required
scale_idstringrequiredquestionsintegerrequiredoverall_ratingbooleanrequiredThe 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 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"
]
}
]
}
]
}'const res = await fetch('https://api.bizisy.com/v1/talent/templates.save', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"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"
]
}
]
}
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/templates.save",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"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",
],
},
],
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_archiveon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
template_idstringrequiredarchivedbooleanDefault
true.
Returns
11 fields
idstringrequiredA saved template's id, or starter:<name> for a starter not saved yet.
namestringrequiredstarterstring | nullrequiredsavedbooleanrequiredarchivedbooleanrequiredstepsobjectrequired4 fields
selfbooleanrequiredmanagerbooleanrequiredpeerbooleanrequiredupwardbooleanrequired
sectionsobject[]required5 fields
idstringrequiredtitlestringrequiredtitlesobject4 fields
selfstringmanagerstringpeerstringupwardstring
show_goalsbooleanrequiredquestionsobject[]required6 fields
idstringrequiredtextstringrequiredtextsobjectWording per step (self in the first person); text when absent.
4 fields
selfstringmanagerstringpeerstringupwardstring
kind"rating" | "text" | "both"requiredrequiredbooleanrequiredfor"self" | "manager" | "peer" | "upward"[]required
scale_idstringrequiredquestionsintegerrequiredoverall_ratingbooleanrequiredThe 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 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}'const res = await fetch('https://api.bizisy.com/v1/talent/templates.archive', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"template_id": "tpl1",
"archived": false
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/templates.archive",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"template_id": "tpl1",
"archived": False,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_liston HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
status"draft" | "launching" | "active" | "closed" | "cancelled"
Returns
itemsobject[]required21 fields
idstringrequirednamestringrequiredstatus"draft" | "launching" | "active" | "closed" | "cancelled"requiredtemplateobjectrequired6 fields
idstring | nullrequirednamestringrequiredstepsobjectrequired4 fields
selfbooleanrequiredmanagerbooleanrequiredpeerbooleanrequiredupwardbooleanrequired
sectionsobject[]required5 fields
idstringrequiredtitlestringrequiredtitlesobject4 fields
selfstringmanagerstringpeerstringupwardstring
show_goalsbooleanrequiredquestionsobject[]required6 fields
idstringrequiredtextstringrequiredtextsobjectWording per step (self in the first person); text when absent.
kind"rating" | "text" | "both"requiredrequiredbooleanrequiredfor"self" | "manager" | "peer" | "upward"[]required
scale_idstringrequiredoverall_ratingbooleanrequiredThe manager gives an overall rating (false: development only: no calibration, salary reviews use "No rating").
scaleobjectrequired3 fields
idstringrequirednamestringrequiredpointsobject[]required3 fields
valueintegerrequiredlabelstringrequireddescriptionstringrequired
datesobjectrequired7 fields
startstringrequirednominate_bystring | nullrequiredself_duestring | nullrequiredpeer_duestring | nullrequiredmanager_duestringrequiredcalibrate_bystring | nullrequiredrelease_onstringrequired
upwardbooleanrequiredpotential_stepbooleanrequireduses_calibrationbooleanrequiredsecond_levelbooleanrequiredpopulationobject | nullrequiredHR only.
7 fields
unit_idsstring[]requiredlocation_idsstring[]requiredtitle_idsstring[]requiredlevel_idsstring[]requiredperson_idsstring[]requiredmin_tenure_daysintegerrequiredas_ofstringrequired
launchobject | nullrequiredReviews written so far while launching.
2 fields
doneintegerrequiredtotalintegerrequired
scheduled_onstring | nullrequiredA draft launched "on the start date": Bizisy launches it on this day (HR only).
schedule_problemstring | nullrequiredWhy a scheduled launch couldn't run on its day; the cycle stays a draft (HR only).
progressobject | nullrequiredHR: the whole cycle; a manager: the reviews they write. Null for people in the cycle.
8 fields
reviewsintegerrequiredselfobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
managerobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
signoffobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
peersobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
leftintegerrequiredoverdueintegerrequiredreleasedintegerrequired
by_teamobject[] | nullrequiredHR only.
6 fields
unit_idstring | nullrequirednamestring | nullrequiredreviewsintegerrequiredselfintegerrequiredmanagerintegerrequiredsignoffintegerrequired
overdueobject[] | nullrequiredHR only: reviews past a due date.
4 fields
review_idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
step"self" | "manager" | "signoff"requiredduestringrequired
previewobject | nullrequiredDrafts, HR only: who it would review and what it would send.
7 fields
totalintegerrequiredPeople the cycle would review.
by_teamobject[]required3 fields
unit_idstring | nullrequirednamestring | nullrequiredcountintegerrequired
excludedobject[]required2 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
reason"not_employed" | "tenure"required
no_managerobject[]requiredIn the cycle without a manager to review them: HR reassigns.
2 fields
idstringrequirednamestringrequired
emailsobjectrequired2 fields
startedintegerrequiredupwardintegerrequired
consultationobject[]required3 fields
countrystring | nullrequiredtextstringrequiredbasisstringrequired
consultation_donebooleanrequired
role"hr" | "manager" | "person"requiredcreated_atstringrequiredclosed_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/talent/cycles.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status":"active"}'const res = await fetch('https://api.bizisy.com/v1/talent/cycles.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"status": "active"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/cycles.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"status": "active",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_geton HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
cycle_idstringrequired
Returns
21 fields
idstringrequirednamestringrequiredstatus"draft" | "launching" | "active" | "closed" | "cancelled"requiredtemplateobjectrequired6 fields
idstring | nullrequirednamestringrequiredstepsobjectrequired4 fields
selfbooleanrequiredmanagerbooleanrequiredpeerbooleanrequiredupwardbooleanrequired
sectionsobject[]required5 fields
idstringrequiredtitlestringrequiredtitlesobject4 fields
selfstringmanagerstringpeerstringupwardstring
show_goalsbooleanrequiredquestionsobject[]required6 fields
idstringrequiredtextstringrequiredtextsobjectWording per step (self in the first person); text when absent.
4 fields
selfstringmanagerstringpeerstringupwardstring
kind"rating" | "text" | "both"requiredrequiredbooleanrequiredfor"self" | "manager" | "peer" | "upward"[]required
scale_idstringrequiredoverall_ratingbooleanrequiredThe manager gives an overall rating (false: development only: no calibration, salary reviews use "No rating").
scaleobjectrequired3 fields
idstringrequirednamestringrequiredpointsobject[]required3 fields
valueintegerrequiredlabelstringrequireddescriptionstringrequired
datesobjectrequired7 fields
startstringrequirednominate_bystring | nullrequiredself_duestring | nullrequiredpeer_duestring | nullrequiredmanager_duestringrequiredcalibrate_bystring | nullrequiredrelease_onstringrequired
upwardbooleanrequiredpotential_stepbooleanrequireduses_calibrationbooleanrequiredsecond_levelbooleanrequiredpopulationobject | nullrequiredHR only.
7 fields
unit_idsstring[]requiredlocation_idsstring[]requiredtitle_idsstring[]requiredlevel_idsstring[]requiredperson_idsstring[]requiredmin_tenure_daysintegerrequiredas_ofstringrequired
launchobject | nullrequiredReviews written so far while launching.
2 fields
doneintegerrequiredtotalintegerrequired
scheduled_onstring | nullrequiredA draft launched "on the start date": Bizisy launches it on this day (HR only).
schedule_problemstring | nullrequiredWhy a scheduled launch couldn't run on its day; the cycle stays a draft (HR only).
progressobject | nullrequiredHR: the whole cycle; a manager: the reviews they write. Null for people in the cycle.
8 fields
reviewsintegerrequiredselfobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
managerobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
signoffobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
peersobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
leftintegerrequiredoverdueintegerrequiredreleasedintegerrequired
by_teamobject[] | nullrequiredHR only.
6 fields
unit_idstring | nullrequirednamestring | nullrequiredreviewsintegerrequiredselfintegerrequiredmanagerintegerrequiredsignoffintegerrequired
overdueobject[] | nullrequiredHR only: reviews past a due date.
4 fields
review_idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
step"self" | "manager" | "signoff"requiredduestringrequired
previewobject | nullrequiredDrafts, HR only: who it would review and what it would send.
7 fields
totalintegerrequiredPeople the cycle would review.
by_teamobject[]required3 fields
unit_idstring | nullrequirednamestring | nullrequiredcountintegerrequired
excludedobject[]required2 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
reason"not_employed" | "tenure"required
no_managerobject[]requiredIn the cycle without a manager to review them: HR reassigns.
2 fields
idstringrequirednamestringrequired
emailsobjectrequired2 fields
startedintegerrequiredupwardintegerrequired
consultationobject[]required3 fields
countrystring | nullrequiredtextstringrequiredbasisstringrequired
consultation_donebooleanrequired
role"hr" | "manager" | "person"requiredcreated_atstringrequiredclosed_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/talent/cycles.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"cycle_id":"cy1"}'const res = await fetch('https://api.bizisy.com/v1/talent/cycles.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"cycle_id": "cy1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/cycles.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"cycle_id": "cy1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_createon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
namestringrequirede.g. "Annual review 2026".
1–120 characters.
template_idstringrequiredA template id or starter:<name> (talent_templates_list); the cycle keeps a copy.
populationobject7 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_daysintegerLeave out people who joined fewer than this many days before the as-of date (default 90).
From 0 to 730. Default
90.as_ofstringEmployed on this day (default today).
Pattern
^\d{4}-\d{2}-\d{2}$.
datesobjectrequired7 fields
startstringrequiredPattern
^\d{4}-\d{2}-\d{2}$.nominate_bystring | nullPattern
^\d{4}-\d{2}-\d{2}$.self_duestring | nullPattern
^\d{4}-\d{2}-\d{2}$.peer_duestring | nullPattern
^\d{4}-\d{2}-\d{2}$.manager_duestringrequiredPattern
^\d{4}-\d{2}-\d{2}$.calibrate_bystring | nullPattern
^\d{4}-\d{2}-\d{2}$.release_onstringrequiredPeople see their review from this day, once signed off (and calibrated when the cycle uses calibration).
Pattern
^\d{4}-\d{2}-\d{2}$.
upwardbooleanReports give upward feedback on their manager (the template's upward step).
potential_stepbooleanThe manager step also asks for the person's potential.
uses_calibrationbooleanRatings are released only after a locked calibration session.
Returns
21 fields
idstringrequirednamestringrequiredstatus"draft" | "launching" | "active" | "closed" | "cancelled"requiredtemplateobjectrequired6 fields
idstring | nullrequirednamestringrequiredstepsobjectrequired4 fields
selfbooleanrequiredmanagerbooleanrequiredpeerbooleanrequiredupwardbooleanrequired
sectionsobject[]required5 fields
idstringrequiredtitlestringrequiredtitlesobject4 fields
selfstringmanagerstringpeerstringupwardstring
show_goalsbooleanrequiredquestionsobject[]required6 fields
idstringrequiredtextstringrequiredtextsobjectWording per step (self in the first person); text when absent.
4 fields
selfstringmanagerstringpeerstringupwardstring
kind"rating" | "text" | "both"requiredrequiredbooleanrequiredfor"self" | "manager" | "peer" | "upward"[]required
scale_idstringrequiredoverall_ratingbooleanrequiredThe manager gives an overall rating (false: development only: no calibration, salary reviews use "No rating").
scaleobjectrequired3 fields
idstringrequirednamestringrequiredpointsobject[]required3 fields
valueintegerrequiredlabelstringrequireddescriptionstringrequired
datesobjectrequired7 fields
startstringrequirednominate_bystring | nullrequiredself_duestring | nullrequiredpeer_duestring | nullrequiredmanager_duestringrequiredcalibrate_bystring | nullrequiredrelease_onstringrequired
upwardbooleanrequiredpotential_stepbooleanrequireduses_calibrationbooleanrequiredsecond_levelbooleanrequiredpopulationobject | nullrequiredHR only.
7 fields
unit_idsstring[]requiredlocation_idsstring[]requiredtitle_idsstring[]requiredlevel_idsstring[]requiredperson_idsstring[]requiredmin_tenure_daysintegerrequiredas_ofstringrequired
launchobject | nullrequiredReviews written so far while launching.
2 fields
doneintegerrequiredtotalintegerrequired
scheduled_onstring | nullrequiredA draft launched "on the start date": Bizisy launches it on this day (HR only).
schedule_problemstring | nullrequiredWhy a scheduled launch couldn't run on its day; the cycle stays a draft (HR only).
progressobject | nullrequiredHR: the whole cycle; a manager: the reviews they write. Null for people in the cycle.
8 fields
reviewsintegerrequiredselfobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
managerobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
signoffobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
peersobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
leftintegerrequiredoverdueintegerrequiredreleasedintegerrequired
by_teamobject[] | nullrequiredHR only.
6 fields
unit_idstring | nullrequirednamestring | nullrequiredreviewsintegerrequiredselfintegerrequiredmanagerintegerrequiredsignoffintegerrequired
overdueobject[] | nullrequiredHR only: reviews past a due date.
4 fields
review_idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
step"self" | "manager" | "signoff"requiredduestringrequired
previewobject | nullrequiredDrafts, HR only: who it would review and what it would send.
7 fields
totalintegerrequiredPeople the cycle would review.
by_teamobject[]required3 fields
unit_idstring | nullrequirednamestring | nullrequiredcountintegerrequired
excludedobject[]required2 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
reason"not_employed" | "tenure"required
no_managerobject[]requiredIn the cycle without a manager to review them: HR reassigns.
2 fields
idstringrequirednamestringrequired
emailsobjectrequired2 fields
startedintegerrequiredupwardintegerrequired
consultationobject[]required3 fields
countrystring | nullrequiredtextstringrequiredbasisstringrequired
consultation_donebooleanrequired
role"hr" | "manager" | "person"requiredcreated_atstringrequiredclosed_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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
}'const res = await fetch('https://api.bizisy.com/v1/talent/cycles.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"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
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/cycles.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"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,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
namestringe.g. "Annual review 2026".
1–120 characters.
template_idstringA template id or starter:<name> (talent_templates_list); the cycle keeps a copy.
populationobject7 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_daysintegerLeave out people who joined fewer than this many days before the as-of date (default 90).
From 0 to 730. Default
90.as_ofstringEmployed on this day (default today).
Pattern
^\d{4}-\d{2}-\d{2}$.
datesobject7 fields
startstringrequiredPattern
^\d{4}-\d{2}-\d{2}$.nominate_bystring | nullPattern
^\d{4}-\d{2}-\d{2}$.self_duestring | nullPattern
^\d{4}-\d{2}-\d{2}$.peer_duestring | nullPattern
^\d{4}-\d{2}-\d{2}$.manager_duestringrequiredPattern
^\d{4}-\d{2}-\d{2}$.calibrate_bystring | nullPattern
^\d{4}-\d{2}-\d{2}$.release_onstringrequiredPeople see their review from this day, once signed off (and calibrated when the cycle uses calibration).
Pattern
^\d{4}-\d{2}-\d{2}$.
upwardbooleanReports give upward feedback on their manager (the template's upward step).
potential_stepbooleanThe manager step also asks for the person's potential.
uses_calibrationbooleanRatings are released only after a locked calibration session.
cycle_idstringrequired
Returns
21 fields
idstringrequirednamestringrequiredstatus"draft" | "launching" | "active" | "closed" | "cancelled"requiredtemplateobjectrequired6 fields
idstring | nullrequirednamestringrequiredstepsobjectrequired4 fields
selfbooleanrequiredmanagerbooleanrequiredpeerbooleanrequiredupwardbooleanrequired
sectionsobject[]required5 fields
idstringrequiredtitlestringrequiredtitlesobject4 fields
selfstringmanagerstringpeerstringupwardstring
show_goalsbooleanrequiredquestionsobject[]required6 fields
idstringrequiredtextstringrequiredtextsobjectWording per step (self in the first person); text when absent.
4 fields
selfstringmanagerstringpeerstringupwardstring
kind"rating" | "text" | "both"requiredrequiredbooleanrequiredfor"self" | "manager" | "peer" | "upward"[]required
scale_idstringrequiredoverall_ratingbooleanrequiredThe manager gives an overall rating (false: development only: no calibration, salary reviews use "No rating").
scaleobjectrequired3 fields
idstringrequirednamestringrequiredpointsobject[]required3 fields
valueintegerrequiredlabelstringrequireddescriptionstringrequired
datesobjectrequired7 fields
startstringrequirednominate_bystring | nullrequiredself_duestring | nullrequiredpeer_duestring | nullrequiredmanager_duestringrequiredcalibrate_bystring | nullrequiredrelease_onstringrequired
upwardbooleanrequiredpotential_stepbooleanrequireduses_calibrationbooleanrequiredsecond_levelbooleanrequiredpopulationobject | nullrequiredHR only.
7 fields
unit_idsstring[]requiredlocation_idsstring[]requiredtitle_idsstring[]requiredlevel_idsstring[]requiredperson_idsstring[]requiredmin_tenure_daysintegerrequiredas_ofstringrequired
launchobject | nullrequiredReviews written so far while launching.
2 fields
doneintegerrequiredtotalintegerrequired
scheduled_onstring | nullrequiredA draft launched "on the start date": Bizisy launches it on this day (HR only).
schedule_problemstring | nullrequiredWhy a scheduled launch couldn't run on its day; the cycle stays a draft (HR only).
progressobject | nullrequiredHR: the whole cycle; a manager: the reviews they write. Null for people in the cycle.
8 fields
reviewsintegerrequiredselfobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
managerobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
signoffobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
peersobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
leftintegerrequiredoverdueintegerrequiredreleasedintegerrequired
by_teamobject[] | nullrequiredHR only.
6 fields
unit_idstring | nullrequirednamestring | nullrequiredreviewsintegerrequiredselfintegerrequiredmanagerintegerrequiredsignoffintegerrequired
overdueobject[] | nullrequiredHR only: reviews past a due date.
4 fields
review_idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
step"self" | "manager" | "signoff"requiredduestringrequired
previewobject | nullrequiredDrafts, HR only: who it would review and what it would send.
7 fields
totalintegerrequiredPeople the cycle would review.
by_teamobject[]required3 fields
unit_idstring | nullrequirednamestring | nullrequiredcountintegerrequired
excludedobject[]required2 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
reason"not_employed" | "tenure"required
no_managerobject[]requiredIn the cycle without a manager to review them: HR reassigns.
2 fields
idstringrequirednamestringrequired
emailsobjectrequired2 fields
startedintegerrequiredupwardintegerrequired
consultationobject[]required3 fields
countrystring | nullrequiredtextstringrequiredbasisstringrequired
consultation_donebooleanrequired
role"hr" | "manager" | "person"requiredcreated_atstringrequiredclosed_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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)"}'const res = await fetch('https://api.bizisy.com/v1/talent/cycles.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"cycle_id": "cy1",
"name": "Annual review 2026 (all sites)"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/cycles.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"cycle_id": "cy1",
"name": "Annual review 2026 (all sites)",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_launchon HR Assistant- Preview
?dry_run=trueruns 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_idstringrequiredwhen"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
idstringrequirednamestringrequiredstatus"draft" | "launching" | "active" | "closed" | "cancelled"requiredtemplateobjectrequired6 fields
idstring | nullrequirednamestringrequiredstepsobjectrequired4 fields
selfbooleanrequiredmanagerbooleanrequiredpeerbooleanrequiredupwardbooleanrequired
sectionsobject[]required5 fields
idstringrequiredtitlestringrequiredtitlesobject4 fields
selfstringmanagerstringpeerstringupwardstring
show_goalsbooleanrequiredquestionsobject[]required6 fields
idstringrequiredtextstringrequiredtextsobjectWording per step (self in the first person); text when absent.
4 fields
selfstringmanagerstringpeerstringupwardstring
kind"rating" | "text" | "both"requiredrequiredbooleanrequiredfor"self" | "manager" | "peer" | "upward"[]required
scale_idstringrequiredoverall_ratingbooleanrequiredThe manager gives an overall rating (false: development only: no calibration, salary reviews use "No rating").
scaleobjectrequired3 fields
idstringrequirednamestringrequiredpointsobject[]required3 fields
valueintegerrequiredlabelstringrequireddescriptionstringrequired
datesobjectrequired7 fields
startstringrequirednominate_bystring | nullrequiredself_duestring | nullrequiredpeer_duestring | nullrequiredmanager_duestringrequiredcalibrate_bystring | nullrequiredrelease_onstringrequired
upwardbooleanrequiredpotential_stepbooleanrequireduses_calibrationbooleanrequiredsecond_levelbooleanrequiredpopulationobject | nullrequiredHR only.
7 fields
unit_idsstring[]requiredlocation_idsstring[]requiredtitle_idsstring[]requiredlevel_idsstring[]requiredperson_idsstring[]requiredmin_tenure_daysintegerrequiredas_ofstringrequired
launchobject | nullrequiredReviews written so far while launching.
2 fields
doneintegerrequiredtotalintegerrequired
scheduled_onstring | nullrequiredA draft launched "on the start date": Bizisy launches it on this day (HR only).
schedule_problemstring | nullrequiredWhy a scheduled launch couldn't run on its day; the cycle stays a draft (HR only).
progressobject | nullrequiredHR: the whole cycle; a manager: the reviews they write. Null for people in the cycle.
8 fields
reviewsintegerrequiredselfobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
managerobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
signoffobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
peersobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
leftintegerrequiredoverdueintegerrequiredreleasedintegerrequired
by_teamobject[] | nullrequiredHR only.
6 fields
unit_idstring | nullrequirednamestring | nullrequiredreviewsintegerrequiredselfintegerrequiredmanagerintegerrequiredsignoffintegerrequired
overdueobject[] | nullrequiredHR only: reviews past a due date.
4 fields
review_idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
step"self" | "manager" | "signoff"requiredduestringrequired
previewobject | nullrequiredDrafts, HR only: who it would review and what it would send.
7 fields
totalintegerrequiredPeople the cycle would review.
by_teamobject[]required3 fields
unit_idstring | nullrequirednamestring | nullrequiredcountintegerrequired
excludedobject[]required2 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
reason"not_employed" | "tenure"required
no_managerobject[]requiredIn the cycle without a manager to review them: HR reassigns.
2 fields
idstringrequirednamestringrequired
emailsobjectrequired2 fields
startedintegerrequiredupwardintegerrequired
consultationobject[]required3 fields
countrystring | nullrequiredtextstringrequiredbasisstringrequired
consultation_donebooleanrequired
role"hr" | "manager" | "person"requiredcreated_atstringrequiredclosed_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/talent/cycles.launch', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"cycle_id": "cy1",
"when": "start"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/cycles.launch",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"cycle_id": "cy1",
"when": "start",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_continueon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
cycle_idstringrequired
Returns
doneintegerrequiredtotalintegerrequiredstatus"draft" | "launching" | "active" | "closed" | "cancelled"required
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/talent/cycles.launch_continue', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"cycle_id": "cy1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/cycles.launch_continue",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"cycle_id": "cy1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_cancelon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
cycle_idstringrequired
Returns
21 fields
idstringrequirednamestringrequiredstatus"draft" | "launching" | "active" | "closed" | "cancelled"requiredtemplateobjectrequired6 fields
idstring | nullrequirednamestringrequiredstepsobjectrequired4 fields
selfbooleanrequiredmanagerbooleanrequiredpeerbooleanrequiredupwardbooleanrequired
sectionsobject[]required5 fields
idstringrequiredtitlestringrequiredtitlesobject4 fields
selfstringmanagerstringpeerstringupwardstring
show_goalsbooleanrequiredquestionsobject[]required6 fields
idstringrequiredtextstringrequiredtextsobjectWording per step (self in the first person); text when absent.
4 fields
selfstringmanagerstringpeerstringupwardstring
kind"rating" | "text" | "both"requiredrequiredbooleanrequiredfor"self" | "manager" | "peer" | "upward"[]required
scale_idstringrequiredoverall_ratingbooleanrequiredThe manager gives an overall rating (false: development only: no calibration, salary reviews use "No rating").
scaleobjectrequired3 fields
idstringrequirednamestringrequiredpointsobject[]required3 fields
valueintegerrequiredlabelstringrequireddescriptionstringrequired
datesobjectrequired7 fields
startstringrequirednominate_bystring | nullrequiredself_duestring | nullrequiredpeer_duestring | nullrequiredmanager_duestringrequiredcalibrate_bystring | nullrequiredrelease_onstringrequired
upwardbooleanrequiredpotential_stepbooleanrequireduses_calibrationbooleanrequiredsecond_levelbooleanrequiredpopulationobject | nullrequiredHR only.
7 fields
unit_idsstring[]requiredlocation_idsstring[]requiredtitle_idsstring[]requiredlevel_idsstring[]requiredperson_idsstring[]requiredmin_tenure_daysintegerrequiredas_ofstringrequired
launchobject | nullrequiredReviews written so far while launching.
2 fields
doneintegerrequiredtotalintegerrequired
scheduled_onstring | nullrequiredA draft launched "on the start date": Bizisy launches it on this day (HR only).
schedule_problemstring | nullrequiredWhy a scheduled launch couldn't run on its day; the cycle stays a draft (HR only).
progressobject | nullrequiredHR: the whole cycle; a manager: the reviews they write. Null for people in the cycle.
8 fields
reviewsintegerrequiredselfobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
managerobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
signoffobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
peersobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
leftintegerrequiredoverdueintegerrequiredreleasedintegerrequired
by_teamobject[] | nullrequiredHR only.
6 fields
unit_idstring | nullrequirednamestring | nullrequiredreviewsintegerrequiredselfintegerrequiredmanagerintegerrequiredsignoffintegerrequired
overdueobject[] | nullrequiredHR only: reviews past a due date.
4 fields
review_idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
step"self" | "manager" | "signoff"requiredduestringrequired
previewobject | nullrequiredDrafts, HR only: who it would review and what it would send.
7 fields
totalintegerrequiredPeople the cycle would review.
by_teamobject[]required3 fields
unit_idstring | nullrequirednamestring | nullrequiredcountintegerrequired
excludedobject[]required2 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
reason"not_employed" | "tenure"required
no_managerobject[]requiredIn the cycle without a manager to review them: HR reassigns.
2 fields
idstringrequirednamestringrequired
emailsobjectrequired2 fields
startedintegerrequiredupwardintegerrequired
consultationobject[]required3 fields
countrystring | nullrequiredtextstringrequiredbasisstringrequired
consultation_donebooleanrequired
role"hr" | "manager" | "person"requiredcreated_atstringrequiredclosed_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/talent/cycles.cancel', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"cycle_id": "cy1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/cycles.cancel",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"cycle_id": "cy1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_closeon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
cycle_idstringrequired
Returns
21 fields
idstringrequirednamestringrequiredstatus"draft" | "launching" | "active" | "closed" | "cancelled"requiredtemplateobjectrequired6 fields
idstring | nullrequirednamestringrequiredstepsobjectrequired4 fields
selfbooleanrequiredmanagerbooleanrequiredpeerbooleanrequiredupwardbooleanrequired
sectionsobject[]required5 fields
idstringrequiredtitlestringrequiredtitlesobject4 fields
selfstringmanagerstringpeerstringupwardstring
show_goalsbooleanrequiredquestionsobject[]required6 fields
idstringrequiredtextstringrequiredtextsobjectWording per step (self in the first person); text when absent.
4 fields
selfstringmanagerstringpeerstringupwardstring
kind"rating" | "text" | "both"requiredrequiredbooleanrequiredfor"self" | "manager" | "peer" | "upward"[]required
scale_idstringrequiredoverall_ratingbooleanrequiredThe manager gives an overall rating (false: development only: no calibration, salary reviews use "No rating").
scaleobjectrequired3 fields
idstringrequirednamestringrequiredpointsobject[]required3 fields
valueintegerrequiredlabelstringrequireddescriptionstringrequired
datesobjectrequired7 fields
startstringrequirednominate_bystring | nullrequiredself_duestring | nullrequiredpeer_duestring | nullrequiredmanager_duestringrequiredcalibrate_bystring | nullrequiredrelease_onstringrequired
upwardbooleanrequiredpotential_stepbooleanrequireduses_calibrationbooleanrequiredsecond_levelbooleanrequiredpopulationobject | nullrequiredHR only.
7 fields
unit_idsstring[]requiredlocation_idsstring[]requiredtitle_idsstring[]requiredlevel_idsstring[]requiredperson_idsstring[]requiredmin_tenure_daysintegerrequiredas_ofstringrequired
launchobject | nullrequiredReviews written so far while launching.
2 fields
doneintegerrequiredtotalintegerrequired
scheduled_onstring | nullrequiredA draft launched "on the start date": Bizisy launches it on this day (HR only).
schedule_problemstring | nullrequiredWhy a scheduled launch couldn't run on its day; the cycle stays a draft (HR only).
progressobject | nullrequiredHR: the whole cycle; a manager: the reviews they write. Null for people in the cycle.
8 fields
reviewsintegerrequiredselfobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
managerobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
signoffobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
peersobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
leftintegerrequiredoverdueintegerrequiredreleasedintegerrequired
by_teamobject[] | nullrequiredHR only.
6 fields
unit_idstring | nullrequirednamestring | nullrequiredreviewsintegerrequiredselfintegerrequiredmanagerintegerrequiredsignoffintegerrequired
overdueobject[] | nullrequiredHR only: reviews past a due date.
4 fields
review_idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
step"self" | "manager" | "signoff"requiredduestringrequired
previewobject | nullrequiredDrafts, HR only: who it would review and what it would send.
7 fields
totalintegerrequiredPeople the cycle would review.
by_teamobject[]required3 fields
unit_idstring | nullrequirednamestring | nullrequiredcountintegerrequired
excludedobject[]required2 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
reason"not_employed" | "tenure"required
no_managerobject[]requiredIn the cycle without a manager to review them: HR reassigns.
2 fields
idstringrequirednamestringrequired
emailsobjectrequired2 fields
startedintegerrequiredupwardintegerrequired
consultationobject[]required3 fields
countrystring | nullrequiredtextstringrequiredbasisstringrequired
consultation_donebooleanrequired
role"hr" | "manager" | "person"requiredcreated_atstringrequiredclosed_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/talent/cycles.close', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"cycle_id": "cy1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/cycles.close",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"cycle_id": "cy1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_emailon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
kind"cycle_started" | "peers_to_approve" | "feedback_asked" | "reminder" | "calibration_opened" | "review_ready"requiredcycle_namestringrequired1–120 characters.
datestring | nullPattern
^\d{4}-\d{2}-\d{2}$.peersboolean
Returns
kind"cycle_started" | "peers_to_approve" | "feedback_asked" | "reminder" | "calibration_opened" | "review_ready"requiredsubjectstringrequiredhtmlstringrequiredThe whole email as one HTML document.
textstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
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
}'const res = await fetch('https://api.bizisy.com/v1/talent/cycles.preview_email', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"kind": "cycle_started",
"cycle_name": "Annual review 2026",
"date": "2026-12-04",
"peers": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/cycles.preview_email",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"kind": "cycle_started",
"cycle_name": "Annual review 2026",
"date": "2026-12-04",
"peers": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_liston HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
cycle_idstring1–200 characters.
person_idstring1–200 characters.
mine"write" | "signoff"
Returns
itemsobject[]required9 fields
idstringrequiredcycleobjectrequired2 fields
idstringrequirednamestringrequired
personobjectrequired3 fields
idstringrequirednamestringrequiredteamstring | nullrequired
reviewerobject | nullrequired2 fields
idstringrequirednamestringrequired
stepsobjectrequired3 fields
self"pending" | "submitted" | "n/a"requiredmanager"pending" | "submitted" | "n/a"requiredsignoff"pending" | "submitted" | "n/a"required
left_onstring | nullrequiredreleasedbooleanrequiredpeersobjectrequired3 fields
askedintegerrequiredansweredintegerrequirednominatedintegerrequired
role"hr" | "manager" | "chain" | "signoff"required
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/talent/reviews.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"cycle_id": "cy1",
"mine": "write"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/reviews.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"cycle_id": "cy1",
"mine": "write",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_geton HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
review_idstringrequired
Returns
19 fields
idstringrequiredcycleobjectrequired10 fields
idstringrequirednamestringrequiredstatusstringrequiredrelease_onstringrequiredself_duestring | nullrequiredmanager_duestringrequireduses_calibrationbooleanrequiredsecond_levelbooleanrequiredpotential_stepbooleanrequiredoverall_ratingbooleanrequiredThe manager gives an overall rating (false: a development-only review).
personobjectrequired2 fields
idstringrequirednamestringrequired
reviewerobject | nullrequirednull: no reviewer (HR reassigns) or a former manager. Hidden from the person before release.
2 fields
idstringrequirednamestringrequired
access"hr" | "manager" | "chain" | "self" | "signoff"requiredreleasedboolean | nullrequirednull for the person before release (they learn nothing about status).
stepsobject | nullrequiredJob tier: HR and managers only.
3 fields
self"pending" | "submitted" | "n/a"requiredmanager"pending" | "submitted" | "n/a"requiredsignoff"pending" | "submitted" | "n/a"required
sectionsobject[]required5 fields
idstringrequiredtitlestringrequiredtitlesobject4 fields
selfstringmanagerstringpeerstringupwardstring
show_goalsbooleanrequiredquestionsobject[]required6 fields
idstringrequiredtextstringrequiredtextsobjectWording per step (self in the first person); text when absent.
4 fields
selfstringmanagerstringpeerstringupwardstring
kind"rating" | "text" | "both"requiredrequiredbooleanrequiredfor"self" | "manager" | "peer" | "upward"[]required
scaleobjectrequired3 fields
idstringrequirednamestringrequiredpointsobject[]required3 fields
valueintegerrequiredlabelstringrequireddescriptionstringrequired
selfobject | nullrequired2 fields
answersobject[]required3 fields
question_idstringrequiredratinginteger | nullrequiredtextstring | nullrequired
submitted_atstring | nullrequired
managerobject | nullrequired3 fields
answersobject[]required3 fields
question_idstringrequiredratinginteger | nullrequiredtextstring | nullrequired
ratinginteger | nullrequiredsubmitted_atstring | nullrequired
final_ratinginteger | nullrequiredThe rating after calibration (or the manager's): HR and managers, and the person once released.
groupsobject[]required5 fields
kind"peer" | "upward"requiredshownbooleanrequiredfalse: fewer answers than the anonymity threshold; withheld from everyone.
answeredinteger | nullrequiredHow many answered (HR, the reviewer and higher managers); null for the person.
askedinteger | nullrequiredanswersobject[]requiredUnattributed, texts shuffled: never who wrote what.
3 fields
question_idstringrequiredratingsinteger[]requiredtextsstring[]required
signoffobject | nullrequired3 fields
byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstring | nullrequiredsent_back_notestring | nullrequired
ackobject | nullrequired1 field
atstringrequired
commentobject | nullrequired2 fields
textstringrequiredatstringrequired
discuss_requested_atstring | nullrequiredleft_onstring | nullrequiredHR and managers: the review closed as "left" on this day.
canobjectrequired8 fields
answer_selfbooleanrequiredanswer_managerbooleanrequiredsignoffbooleanrequiredacknowledgebooleanrequiredcommentbooleanrequireddiscussbooleanrequiredreopenbooleanrequiredreassignbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/talent/reviews.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"review_id":"rv1"}'const res = await fetch('https://api.bizisy.com/v1/talent/reviews.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"review_id": "rv1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/reviews.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"review_id": "rv1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_answeron HR Assistant, My Workplace- Preview
?dry_run=trueruns 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_idstringrequiredas"self" | "manager"requiredself: your own self-review; manager: a review you write as the manager.
answersobject[]requiredUp to 30 items.
3 fields
question_idstringrequired1–40 characters.
ratinginteger | nullFrom 1 to 7.
textstring | nullUp to 5000 characters.
ratinginteger | nullManager 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
idstringrequiredcycleobjectrequired10 fields
idstringrequirednamestringrequiredstatusstringrequiredrelease_onstringrequiredself_duestring | nullrequiredmanager_duestringrequireduses_calibrationbooleanrequiredsecond_levelbooleanrequiredpotential_stepbooleanrequiredoverall_ratingbooleanrequiredThe manager gives an overall rating (false: a development-only review).
personobjectrequired2 fields
idstringrequirednamestringrequired
reviewerobject | nullrequirednull: no reviewer (HR reassigns) or a former manager. Hidden from the person before release.
2 fields
idstringrequirednamestringrequired
access"hr" | "manager" | "chain" | "self" | "signoff"requiredreleasedboolean | nullrequirednull for the person before release (they learn nothing about status).
stepsobject | nullrequiredJob tier: HR and managers only.
3 fields
self"pending" | "submitted" | "n/a"requiredmanager"pending" | "submitted" | "n/a"requiredsignoff"pending" | "submitted" | "n/a"required
sectionsobject[]required5 fields
idstringrequiredtitlestringrequiredtitlesobject4 fields
selfstringmanagerstringpeerstringupwardstring
show_goalsbooleanrequiredquestionsobject[]required6 fields
idstringrequiredtextstringrequiredtextsobjectWording per step (self in the first person); text when absent.
4 fields
selfstringmanagerstringpeerstringupwardstring
kind"rating" | "text" | "both"requiredrequiredbooleanrequiredfor"self" | "manager" | "peer" | "upward"[]required
scaleobjectrequired3 fields
idstringrequirednamestringrequiredpointsobject[]required3 fields
valueintegerrequiredlabelstringrequireddescriptionstringrequired
selfobject | nullrequired2 fields
answersobject[]required3 fields
question_idstringrequiredratinginteger | nullrequiredtextstring | nullrequired
submitted_atstring | nullrequired
managerobject | nullrequired3 fields
answersobject[]required3 fields
question_idstringrequiredratinginteger | nullrequiredtextstring | nullrequired
ratinginteger | nullrequiredsubmitted_atstring | nullrequired
final_ratinginteger | nullrequiredThe rating after calibration (or the manager's): HR and managers, and the person once released.
groupsobject[]required5 fields
kind"peer" | "upward"requiredshownbooleanrequiredfalse: fewer answers than the anonymity threshold; withheld from everyone.
answeredinteger | nullrequiredHow many answered (HR, the reviewer and higher managers); null for the person.
askedinteger | nullrequiredanswersobject[]requiredUnattributed, texts shuffled: never who wrote what.
3 fields
question_idstringrequiredratingsinteger[]requiredtextsstring[]required
signoffobject | nullrequired3 fields
byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstring | nullrequiredsent_back_notestring | nullrequired
ackobject | nullrequired1 field
atstringrequired
commentobject | nullrequired2 fields
textstringrequiredatstringrequired
discuss_requested_atstring | nullrequiredleft_onstring | nullrequiredHR and managers: the review closed as "left" on this day.
canobjectrequired8 fields
answer_selfbooleanrequiredanswer_managerbooleanrequiredsignoffbooleanrequiredacknowledgebooleanrequiredcommentbooleanrequireddiscussbooleanrequiredreopenbooleanrequiredreassignbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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
}'const res = await fetch('https://api.bizisy.com/v1/talent/reviews.answer', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"review_id": "rv1",
"as": "manager",
"answers": [
{
"question_id": "q1",
"text": "Good progress."
}
],
"rating": 4
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/reviews.answer",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"review_id": "rv1",
"as": "manager",
"answers": [
{
"question_id": "q1",
"text": "Good progress.",
},
],
"rating": 4,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_submiton HR Assistant, My Workplace- Preview
?dry_run=trueruns 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_idstringrequiredas"self" | "manager"requiredself: your own self-review; manager: a review you write as the manager.
answersobject[]requiredUp to 30 items.
3 fields
question_idstringrequired1–40 characters.
ratinginteger | nullFrom 1 to 7.
textstring | nullUp to 5000 characters.
ratinginteger | nullManager 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
idstringrequiredcycleobjectrequired10 fields
idstringrequirednamestringrequiredstatusstringrequiredrelease_onstringrequiredself_duestring | nullrequiredmanager_duestringrequireduses_calibrationbooleanrequiredsecond_levelbooleanrequiredpotential_stepbooleanrequiredoverall_ratingbooleanrequiredThe manager gives an overall rating (false: a development-only review).
personobjectrequired2 fields
idstringrequirednamestringrequired
reviewerobject | nullrequirednull: no reviewer (HR reassigns) or a former manager. Hidden from the person before release.
2 fields
idstringrequirednamestringrequired
access"hr" | "manager" | "chain" | "self" | "signoff"requiredreleasedboolean | nullrequirednull for the person before release (they learn nothing about status).
stepsobject | nullrequiredJob tier: HR and managers only.
3 fields
self"pending" | "submitted" | "n/a"requiredmanager"pending" | "submitted" | "n/a"requiredsignoff"pending" | "submitted" | "n/a"required
sectionsobject[]required5 fields
idstringrequiredtitlestringrequiredtitlesobject4 fields
selfstringmanagerstringpeerstringupwardstring
show_goalsbooleanrequiredquestionsobject[]required6 fields
idstringrequiredtextstringrequiredtextsobjectWording per step (self in the first person); text when absent.
4 fields
selfstringmanagerstringpeerstringupwardstring
kind"rating" | "text" | "both"requiredrequiredbooleanrequiredfor"self" | "manager" | "peer" | "upward"[]required
scaleobjectrequired3 fields
idstringrequirednamestringrequiredpointsobject[]required3 fields
valueintegerrequiredlabelstringrequireddescriptionstringrequired
selfobject | nullrequired2 fields
answersobject[]required3 fields
question_idstringrequiredratinginteger | nullrequiredtextstring | nullrequired
submitted_atstring | nullrequired
managerobject | nullrequired3 fields
answersobject[]required3 fields
question_idstringrequiredratinginteger | nullrequiredtextstring | nullrequired
ratinginteger | nullrequiredsubmitted_atstring | nullrequired
final_ratinginteger | nullrequiredThe rating after calibration (or the manager's): HR and managers, and the person once released.
groupsobject[]required5 fields
kind"peer" | "upward"requiredshownbooleanrequiredfalse: fewer answers than the anonymity threshold; withheld from everyone.
answeredinteger | nullrequiredHow many answered (HR, the reviewer and higher managers); null for the person.
askedinteger | nullrequiredanswersobject[]requiredUnattributed, texts shuffled: never who wrote what.
3 fields
question_idstringrequiredratingsinteger[]requiredtextsstring[]required
signoffobject | nullrequired3 fields
byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstring | nullrequiredsent_back_notestring | nullrequired
ackobject | nullrequired1 field
atstringrequired
commentobject | nullrequired2 fields
textstringrequiredatstringrequired
discuss_requested_atstring | nullrequiredleft_onstring | nullrequiredHR and managers: the review closed as "left" on this day.
canobjectrequired8 fields
answer_selfbooleanrequiredanswer_managerbooleanrequiredsignoffbooleanrequiredacknowledgebooleanrequiredcommentbooleanrequireddiscussbooleanrequiredreopenbooleanrequiredreassignbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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."
}
]
}'const res = await fetch('https://api.bizisy.com/v1/talent/reviews.submit', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"review_id": "rv1",
"as": "self",
"answers": [
{
"question_id": "q1",
"text": "Halfway there."
}
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/reviews.submit",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"review_id": "rv1",
"as": "self",
"answers": [
{
"question_id": "q1",
"text": "Halfway there.",
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_signoffon HR Assistant, My Workplace- Preview
?dry_run=trueruns 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
idstringrequiredcycleobjectrequired10 fields
idstringrequirednamestringrequiredstatusstringrequiredrelease_onstringrequiredself_duestring | nullrequiredmanager_duestringrequireduses_calibrationbooleanrequiredsecond_levelbooleanrequiredpotential_stepbooleanrequiredoverall_ratingbooleanrequiredThe manager gives an overall rating (false: a development-only review).
personobjectrequired2 fields
idstringrequirednamestringrequired
reviewerobject | nullrequirednull: no reviewer (HR reassigns) or a former manager. Hidden from the person before release.
2 fields
idstringrequirednamestringrequired
access"hr" | "manager" | "chain" | "self" | "signoff"requiredreleasedboolean | nullrequirednull for the person before release (they learn nothing about status).
stepsobject | nullrequiredJob tier: HR and managers only.
3 fields
self"pending" | "submitted" | "n/a"requiredmanager"pending" | "submitted" | "n/a"requiredsignoff"pending" | "submitted" | "n/a"required
sectionsobject[]required5 fields
idstringrequiredtitlestringrequiredtitlesobject4 fields
selfstringmanagerstringpeerstringupwardstring
show_goalsbooleanrequiredquestionsobject[]required6 fields
idstringrequiredtextstringrequiredtextsobjectWording per step (self in the first person); text when absent.
4 fields
selfstringmanagerstringpeerstringupwardstring
kind"rating" | "text" | "both"requiredrequiredbooleanrequiredfor"self" | "manager" | "peer" | "upward"[]required
scaleobjectrequired3 fields
idstringrequirednamestringrequiredpointsobject[]required3 fields
valueintegerrequiredlabelstringrequireddescriptionstringrequired
selfobject | nullrequired2 fields
answersobject[]required3 fields
question_idstringrequiredratinginteger | nullrequiredtextstring | nullrequired
submitted_atstring | nullrequired
managerobject | nullrequired3 fields
answersobject[]required3 fields
question_idstringrequiredratinginteger | nullrequiredtextstring | nullrequired
ratinginteger | nullrequiredsubmitted_atstring | nullrequired
final_ratinginteger | nullrequiredThe rating after calibration (or the manager's): HR and managers, and the person once released.
groupsobject[]required5 fields
kind"peer" | "upward"requiredshownbooleanrequiredfalse: fewer answers than the anonymity threshold; withheld from everyone.
answeredinteger | nullrequiredHow many answered (HR, the reviewer and higher managers); null for the person.
askedinteger | nullrequiredanswersobject[]requiredUnattributed, texts shuffled: never who wrote what.
3 fields
question_idstringrequiredratingsinteger[]requiredtextsstring[]required
signoffobject | nullrequired3 fields
byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstring | nullrequiredsent_back_notestring | nullrequired
ackobject | nullrequired1 field
atstringrequired
commentobject | nullrequired2 fields
textstringrequiredatstringrequired
discuss_requested_atstring | nullrequiredleft_onstring | nullrequiredHR and managers: the review closed as "left" on this day.
canobjectrequired8 fields
answer_selfbooleanrequiredanswer_managerbooleanrequiredsignoffbooleanrequiredacknowledgebooleanrequiredcommentbooleanrequireddiscussbooleanrequiredreopenbooleanrequiredreassignbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/talent/reviews.signoff', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"review_id": "rv1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/reviews.signoff",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"review_id": "rv1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_backon HR Assistant, My Workplace- Preview
?dry_run=trueruns 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_idstringrequirednotestringrequired10–500 characters.
Returns
19 fields
idstringrequiredcycleobjectrequired10 fields
idstringrequirednamestringrequiredstatusstringrequiredrelease_onstringrequiredself_duestring | nullrequiredmanager_duestringrequireduses_calibrationbooleanrequiredsecond_levelbooleanrequiredpotential_stepbooleanrequiredoverall_ratingbooleanrequiredThe manager gives an overall rating (false: a development-only review).
personobjectrequired2 fields
idstringrequirednamestringrequired
reviewerobject | nullrequirednull: no reviewer (HR reassigns) or a former manager. Hidden from the person before release.
2 fields
idstringrequirednamestringrequired
access"hr" | "manager" | "chain" | "self" | "signoff"requiredreleasedboolean | nullrequirednull for the person before release (they learn nothing about status).
stepsobject | nullrequiredJob tier: HR and managers only.
3 fields
self"pending" | "submitted" | "n/a"requiredmanager"pending" | "submitted" | "n/a"requiredsignoff"pending" | "submitted" | "n/a"required
sectionsobject[]required5 fields
idstringrequiredtitlestringrequiredtitlesobject4 fields
selfstringmanagerstringpeerstringupwardstring
show_goalsbooleanrequiredquestionsobject[]required6 fields
idstringrequiredtextstringrequiredtextsobjectWording per step (self in the first person); text when absent.
4 fields
selfstringmanagerstringpeerstringupwardstring
kind"rating" | "text" | "both"requiredrequiredbooleanrequiredfor"self" | "manager" | "peer" | "upward"[]required
scaleobjectrequired3 fields
idstringrequirednamestringrequiredpointsobject[]required3 fields
valueintegerrequiredlabelstringrequireddescriptionstringrequired
selfobject | nullrequired2 fields
answersobject[]required3 fields
question_idstringrequiredratinginteger | nullrequiredtextstring | nullrequired
submitted_atstring | nullrequired
managerobject | nullrequired3 fields
answersobject[]required3 fields
question_idstringrequiredratinginteger | nullrequiredtextstring | nullrequired
ratinginteger | nullrequiredsubmitted_atstring | nullrequired
final_ratinginteger | nullrequiredThe rating after calibration (or the manager's): HR and managers, and the person once released.
groupsobject[]required5 fields
kind"peer" | "upward"requiredshownbooleanrequiredfalse: fewer answers than the anonymity threshold; withheld from everyone.
answeredinteger | nullrequiredHow many answered (HR, the reviewer and higher managers); null for the person.
askedinteger | nullrequiredanswersobject[]requiredUnattributed, texts shuffled: never who wrote what.
3 fields
question_idstringrequiredratingsinteger[]requiredtextsstring[]required
signoffobject | nullrequired3 fields
byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstring | nullrequiredsent_back_notestring | nullrequired
ackobject | nullrequired1 field
atstringrequired
commentobject | nullrequired2 fields
textstringrequiredatstringrequired
discuss_requested_atstring | nullrequiredleft_onstring | nullrequiredHR and managers: the review closed as "left" on this day.
canobjectrequired8 fields
answer_selfbooleanrequiredanswer_managerbooleanrequiredsignoffbooleanrequiredacknowledgebooleanrequiredcommentbooleanrequireddiscussbooleanrequiredreopenbooleanrequiredreassignbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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."}'const res = await fetch('https://api.bizisy.com/v1/talent/reviews.send_back', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"review_id": "rv1",
"note": "Add an example for the second goal."
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/reviews.send_back",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"review_id": "rv1",
"note": "Add an example for the second goal.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_reassignon HR Assistant- Preview
?dry_run=trueruns 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_idstringrequiredreviewer_idstringrequired1–200 characters.
reasonstringrequired10–500 characters.
Returns
19 fields
idstringrequiredcycleobjectrequired10 fields
idstringrequirednamestringrequiredstatusstringrequiredrelease_onstringrequiredself_duestring | nullrequiredmanager_duestringrequireduses_calibrationbooleanrequiredsecond_levelbooleanrequiredpotential_stepbooleanrequiredoverall_ratingbooleanrequiredThe manager gives an overall rating (false: a development-only review).
personobjectrequired2 fields
idstringrequirednamestringrequired
reviewerobject | nullrequirednull: no reviewer (HR reassigns) or a former manager. Hidden from the person before release.
2 fields
idstringrequirednamestringrequired
access"hr" | "manager" | "chain" | "self" | "signoff"requiredreleasedboolean | nullrequirednull for the person before release (they learn nothing about status).
stepsobject | nullrequiredJob tier: HR and managers only.
3 fields
self"pending" | "submitted" | "n/a"requiredmanager"pending" | "submitted" | "n/a"requiredsignoff"pending" | "submitted" | "n/a"required
sectionsobject[]required5 fields
idstringrequiredtitlestringrequiredtitlesobject4 fields
selfstringmanagerstringpeerstringupwardstring
show_goalsbooleanrequiredquestionsobject[]required6 fields
idstringrequiredtextstringrequiredtextsobjectWording per step (self in the first person); text when absent.
4 fields
selfstringmanagerstringpeerstringupwardstring
kind"rating" | "text" | "both"requiredrequiredbooleanrequiredfor"self" | "manager" | "peer" | "upward"[]required
scaleobjectrequired3 fields
idstringrequirednamestringrequiredpointsobject[]required3 fields
valueintegerrequiredlabelstringrequireddescriptionstringrequired
selfobject | nullrequired2 fields
answersobject[]required3 fields
question_idstringrequiredratinginteger | nullrequiredtextstring | nullrequired
submitted_atstring | nullrequired
managerobject | nullrequired3 fields
answersobject[]required3 fields
question_idstringrequiredratinginteger | nullrequiredtextstring | nullrequired
ratinginteger | nullrequiredsubmitted_atstring | nullrequired
final_ratinginteger | nullrequiredThe rating after calibration (or the manager's): HR and managers, and the person once released.
groupsobject[]required5 fields
kind"peer" | "upward"requiredshownbooleanrequiredfalse: fewer answers than the anonymity threshold; withheld from everyone.
answeredinteger | nullrequiredHow many answered (HR, the reviewer and higher managers); null for the person.
askedinteger | nullrequiredanswersobject[]requiredUnattributed, texts shuffled: never who wrote what.
3 fields
question_idstringrequiredratingsinteger[]requiredtextsstring[]required
signoffobject | nullrequired3 fields
byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstring | nullrequiredsent_back_notestring | nullrequired
ackobject | nullrequired1 field
atstringrequired
commentobject | nullrequired2 fields
textstringrequiredatstringrequired
discuss_requested_atstring | nullrequiredleft_onstring | nullrequiredHR and managers: the review closed as "left" on this day.
canobjectrequired8 fields
answer_selfbooleanrequiredanswer_managerbooleanrequiredsignoffbooleanrequiredacknowledgebooleanrequiredcommentbooleanrequireddiscussbooleanrequiredreopenbooleanrequiredreassignbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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."
}'const res = await fetch('https://api.bizisy.com/v1/talent/reviews.reassign', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"review_id": "rv1",
"reviewer_id": "p3",
"reason": "Rita managed this period."
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/reviews.reassign",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"review_id": "rv1",
"reviewer_id": "p3",
"reason": "Rita managed this period.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_reopenon HR Assistant- Preview
?dry_run=trueruns 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_idstringrequiredstep"self" | "manager"requiredreasonstringrequired10–500 characters.
Returns
19 fields
idstringrequiredcycleobjectrequired10 fields
idstringrequirednamestringrequiredstatusstringrequiredrelease_onstringrequiredself_duestring | nullrequiredmanager_duestringrequireduses_calibrationbooleanrequiredsecond_levelbooleanrequiredpotential_stepbooleanrequiredoverall_ratingbooleanrequiredThe manager gives an overall rating (false: a development-only review).
personobjectrequired2 fields
idstringrequirednamestringrequired
reviewerobject | nullrequirednull: no reviewer (HR reassigns) or a former manager. Hidden from the person before release.
2 fields
idstringrequirednamestringrequired
access"hr" | "manager" | "chain" | "self" | "signoff"requiredreleasedboolean | nullrequirednull for the person before release (they learn nothing about status).
stepsobject | nullrequiredJob tier: HR and managers only.
3 fields
self"pending" | "submitted" | "n/a"requiredmanager"pending" | "submitted" | "n/a"requiredsignoff"pending" | "submitted" | "n/a"required
sectionsobject[]required5 fields
idstringrequiredtitlestringrequiredtitlesobject4 fields
selfstringmanagerstringpeerstringupwardstring
show_goalsbooleanrequiredquestionsobject[]required6 fields
idstringrequiredtextstringrequiredtextsobjectWording per step (self in the first person); text when absent.
4 fields
selfstringmanagerstringpeerstringupwardstring
kind"rating" | "text" | "both"requiredrequiredbooleanrequiredfor"self" | "manager" | "peer" | "upward"[]required
scaleobjectrequired3 fields
idstringrequirednamestringrequiredpointsobject[]required3 fields
valueintegerrequiredlabelstringrequireddescriptionstringrequired
selfobject | nullrequired2 fields
answersobject[]required3 fields
question_idstringrequiredratinginteger | nullrequiredtextstring | nullrequired
submitted_atstring | nullrequired
managerobject | nullrequired3 fields
answersobject[]required3 fields
question_idstringrequiredratinginteger | nullrequiredtextstring | nullrequired
ratinginteger | nullrequiredsubmitted_atstring | nullrequired
final_ratinginteger | nullrequiredThe rating after calibration (or the manager's): HR and managers, and the person once released.
groupsobject[]required5 fields
kind"peer" | "upward"requiredshownbooleanrequiredfalse: fewer answers than the anonymity threshold; withheld from everyone.
answeredinteger | nullrequiredHow many answered (HR, the reviewer and higher managers); null for the person.
askedinteger | nullrequiredanswersobject[]requiredUnattributed, texts shuffled: never who wrote what.
3 fields
question_idstringrequiredratingsinteger[]requiredtextsstring[]required
signoffobject | nullrequired3 fields
byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstring | nullrequiredsent_back_notestring | nullrequired
ackobject | nullrequired1 field
atstringrequired
commentobject | nullrequired2 fields
textstringrequiredatstringrequired
discuss_requested_atstring | nullrequiredleft_onstring | nullrequiredHR and managers: the review closed as "left" on this day.
canobjectrequired8 fields
answer_selfbooleanrequiredanswer_managerbooleanrequiredsignoffbooleanrequiredacknowledgebooleanrequiredcommentbooleanrequireddiscussbooleanrequiredreopenbooleanrequiredreassignbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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."
}'const res = await fetch('https://api.bizisy.com/v1/talent/reviews.reopen', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"review_id": "rv1",
"step": "manager",
"reason": "Rating entered by mistake."
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/reviews.reopen",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"review_id": "rv1",
"step": "manager",
"reason": "Rating entered by mistake.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_acknowledgeon My Workplace- Preview
?dry_run=trueruns 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
idstringrequiredcycleobjectrequired10 fields
idstringrequirednamestringrequiredstatusstringrequiredrelease_onstringrequiredself_duestring | nullrequiredmanager_duestringrequireduses_calibrationbooleanrequiredsecond_levelbooleanrequiredpotential_stepbooleanrequiredoverall_ratingbooleanrequiredThe manager gives an overall rating (false: a development-only review).
personobjectrequired2 fields
idstringrequirednamestringrequired
reviewerobject | nullrequirednull: no reviewer (HR reassigns) or a former manager. Hidden from the person before release.
2 fields
idstringrequirednamestringrequired
access"hr" | "manager" | "chain" | "self" | "signoff"requiredreleasedboolean | nullrequirednull for the person before release (they learn nothing about status).
stepsobject | nullrequiredJob tier: HR and managers only.
3 fields
self"pending" | "submitted" | "n/a"requiredmanager"pending" | "submitted" | "n/a"requiredsignoff"pending" | "submitted" | "n/a"required
sectionsobject[]required5 fields
idstringrequiredtitlestringrequiredtitlesobject4 fields
selfstringmanagerstringpeerstringupwardstring
show_goalsbooleanrequiredquestionsobject[]required6 fields
idstringrequiredtextstringrequiredtextsobjectWording per step (self in the first person); text when absent.
4 fields
selfstringmanagerstringpeerstringupwardstring
kind"rating" | "text" | "both"requiredrequiredbooleanrequiredfor"self" | "manager" | "peer" | "upward"[]required
scaleobjectrequired3 fields
idstringrequirednamestringrequiredpointsobject[]required3 fields
valueintegerrequiredlabelstringrequireddescriptionstringrequired
selfobject | nullrequired2 fields
answersobject[]required3 fields
question_idstringrequiredratinginteger | nullrequiredtextstring | nullrequired
submitted_atstring | nullrequired
managerobject | nullrequired3 fields
answersobject[]required3 fields
question_idstringrequiredratinginteger | nullrequiredtextstring | nullrequired
ratinginteger | nullrequiredsubmitted_atstring | nullrequired
final_ratinginteger | nullrequiredThe rating after calibration (or the manager's): HR and managers, and the person once released.
groupsobject[]required5 fields
kind"peer" | "upward"requiredshownbooleanrequiredfalse: fewer answers than the anonymity threshold; withheld from everyone.
answeredinteger | nullrequiredHow many answered (HR, the reviewer and higher managers); null for the person.
askedinteger | nullrequiredanswersobject[]requiredUnattributed, texts shuffled: never who wrote what.
3 fields
question_idstringrequiredratingsinteger[]requiredtextsstring[]required
signoffobject | nullrequired3 fields
byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstring | nullrequiredsent_back_notestring | nullrequired
ackobject | nullrequired1 field
atstringrequired
commentobject | nullrequired2 fields
textstringrequiredatstringrequired
discuss_requested_atstring | nullrequiredleft_onstring | nullrequiredHR and managers: the review closed as "left" on this day.
canobjectrequired8 fields
answer_selfbooleanrequiredanswer_managerbooleanrequiredsignoffbooleanrequiredacknowledgebooleanrequiredcommentbooleanrequireddiscussbooleanrequiredreopenbooleanrequiredreassignbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/talent/reviews.acknowledge', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"review_id": "rv1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/reviews.acknowledge",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"review_id": "rv1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_commenton My Workplace- Preview
?dry_run=trueruns 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_idstringrequiredtextstringrequiredUp to 2000 characters.
Returns
19 fields
idstringrequiredcycleobjectrequired10 fields
idstringrequirednamestringrequiredstatusstringrequiredrelease_onstringrequiredself_duestring | nullrequiredmanager_duestringrequireduses_calibrationbooleanrequiredsecond_levelbooleanrequiredpotential_stepbooleanrequiredoverall_ratingbooleanrequiredThe manager gives an overall rating (false: a development-only review).
personobjectrequired2 fields
idstringrequirednamestringrequired
reviewerobject | nullrequirednull: no reviewer (HR reassigns) or a former manager. Hidden from the person before release.
2 fields
idstringrequirednamestringrequired
access"hr" | "manager" | "chain" | "self" | "signoff"requiredreleasedboolean | nullrequirednull for the person before release (they learn nothing about status).
stepsobject | nullrequiredJob tier: HR and managers only.
3 fields
self"pending" | "submitted" | "n/a"requiredmanager"pending" | "submitted" | "n/a"requiredsignoff"pending" | "submitted" | "n/a"required
sectionsobject[]required5 fields
idstringrequiredtitlestringrequiredtitlesobject4 fields
selfstringmanagerstringpeerstringupwardstring
show_goalsbooleanrequiredquestionsobject[]required6 fields
idstringrequiredtextstringrequiredtextsobjectWording per step (self in the first person); text when absent.
4 fields
selfstringmanagerstringpeerstringupwardstring
kind"rating" | "text" | "both"requiredrequiredbooleanrequiredfor"self" | "manager" | "peer" | "upward"[]required
scaleobjectrequired3 fields
idstringrequirednamestringrequiredpointsobject[]required3 fields
valueintegerrequiredlabelstringrequireddescriptionstringrequired
selfobject | nullrequired2 fields
answersobject[]required3 fields
question_idstringrequiredratinginteger | nullrequiredtextstring | nullrequired
submitted_atstring | nullrequired
managerobject | nullrequired3 fields
answersobject[]required3 fields
question_idstringrequiredratinginteger | nullrequiredtextstring | nullrequired
ratinginteger | nullrequiredsubmitted_atstring | nullrequired
final_ratinginteger | nullrequiredThe rating after calibration (or the manager's): HR and managers, and the person once released.
groupsobject[]required5 fields
kind"peer" | "upward"requiredshownbooleanrequiredfalse: fewer answers than the anonymity threshold; withheld from everyone.
answeredinteger | nullrequiredHow many answered (HR, the reviewer and higher managers); null for the person.
askedinteger | nullrequiredanswersobject[]requiredUnattributed, texts shuffled: never who wrote what.
3 fields
question_idstringrequiredratingsinteger[]requiredtextsstring[]required
signoffobject | nullrequired3 fields
byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstring | nullrequiredsent_back_notestring | nullrequired
ackobject | nullrequired1 field
atstringrequired
commentobject | nullrequired2 fields
textstringrequiredatstringrequired
discuss_requested_atstring | nullrequiredleft_onstring | nullrequiredHR and managers: the review closed as "left" on this day.
canobjectrequired8 fields
answer_selfbooleanrequiredanswer_managerbooleanrequiredsignoffbooleanrequiredacknowledgebooleanrequiredcommentbooleanrequireddiscussbooleanrequiredreopenbooleanrequiredreassignbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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."}'const res = await fetch('https://api.bizisy.com/v1/talent/reviews.comment', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"review_id": "rv1",
"text": "I see the second half differently."
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/reviews.comment",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"review_id": "rv1",
"text": "I see the second half differently.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_discusson My Workplace- Preview
?dry_run=trueruns 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
idstringrequiredcycleobjectrequired10 fields
idstringrequirednamestringrequiredstatusstringrequiredrelease_onstringrequiredself_duestring | nullrequiredmanager_duestringrequireduses_calibrationbooleanrequiredsecond_levelbooleanrequiredpotential_stepbooleanrequiredoverall_ratingbooleanrequiredThe manager gives an overall rating (false: a development-only review).
personobjectrequired2 fields
idstringrequirednamestringrequired
reviewerobject | nullrequirednull: no reviewer (HR reassigns) or a former manager. Hidden from the person before release.
2 fields
idstringrequirednamestringrequired
access"hr" | "manager" | "chain" | "self" | "signoff"requiredreleasedboolean | nullrequirednull for the person before release (they learn nothing about status).
stepsobject | nullrequiredJob tier: HR and managers only.
3 fields
self"pending" | "submitted" | "n/a"requiredmanager"pending" | "submitted" | "n/a"requiredsignoff"pending" | "submitted" | "n/a"required
sectionsobject[]required5 fields
idstringrequiredtitlestringrequiredtitlesobject4 fields
selfstringmanagerstringpeerstringupwardstring
show_goalsbooleanrequiredquestionsobject[]required6 fields
idstringrequiredtextstringrequiredtextsobjectWording per step (self in the first person); text when absent.
4 fields
selfstringmanagerstringpeerstringupwardstring
kind"rating" | "text" | "both"requiredrequiredbooleanrequiredfor"self" | "manager" | "peer" | "upward"[]required
scaleobjectrequired3 fields
idstringrequirednamestringrequiredpointsobject[]required3 fields
valueintegerrequiredlabelstringrequireddescriptionstringrequired
selfobject | nullrequired2 fields
answersobject[]required3 fields
question_idstringrequiredratinginteger | nullrequiredtextstring | nullrequired
submitted_atstring | nullrequired
managerobject | nullrequired3 fields
answersobject[]required3 fields
question_idstringrequiredratinginteger | nullrequiredtextstring | nullrequired
ratinginteger | nullrequiredsubmitted_atstring | nullrequired
final_ratinginteger | nullrequiredThe rating after calibration (or the manager's): HR and managers, and the person once released.
groupsobject[]required5 fields
kind"peer" | "upward"requiredshownbooleanrequiredfalse: fewer answers than the anonymity threshold; withheld from everyone.
answeredinteger | nullrequiredHow many answered (HR, the reviewer and higher managers); null for the person.
askedinteger | nullrequiredanswersobject[]requiredUnattributed, texts shuffled: never who wrote what.
3 fields
question_idstringrequiredratingsinteger[]requiredtextsstring[]required
signoffobject | nullrequired3 fields
byobject | nullrequired2 fields
idstringrequirednamestringrequired
atstring | nullrequiredsent_back_notestring | nullrequired
ackobject | nullrequired1 field
atstringrequired
commentobject | nullrequired2 fields
textstringrequiredatstringrequired
discuss_requested_atstring | nullrequiredleft_onstring | nullrequiredHR and managers: the review closed as "left" on this day.
canobjectrequired8 fields
answer_selfbooleanrequiredanswer_managerbooleanrequiredsignoffbooleanrequiredacknowledgebooleanrequiredcommentbooleanrequireddiscussbooleanrequiredreopenbooleanrequiredreassignbooleanrequired
topic_addedbooleanrequiredfalse: 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 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"}'const res = await fetch('https://api.bizisy.com/v1/talent/reviews.discuss', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"review_id": "rv1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/reviews.discuss",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"review_id": "rv1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_nominationson HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
review_idstringrequired
Returns
10 fields
review_idstringrequiredcycleobjectrequired4 fields
idstringrequirednamestringrequirednominate_bystring | nullrequiredpeer_duestring | nullrequired
personobjectrequired2 fields
idstringrequirednamestringrequired
peopleobject[]required2 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
state"nominated" | "asked"requiredasked: approved (whether they answered or declined is never shown).
countsobject | nullrequiredThe reviewer and HR: how many answered (never who).
2 fields
askedintegerrequiredansweredintegerrequired
minintegerrequiredmaxintegerrequiredfullstring[]requiredPeople already asked for the most peer reviews this cycle (12): pick someone else.
can_nominatebooleanrequiredcan_decidebooleanrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/talent/feedback.nominations \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"review_id":"rv1"}'const res = await fetch('https://api.bizisy.com/v1/talent/feedback.nominations', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"review_id": "rv1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/feedback.nominations",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"review_id": "rv1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_decideon HR Assistant, My Workplace- Preview
?dry_run=trueruns 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_idstringrequiredapprovestring[]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_idstringrequiredcycleobjectrequired4 fields
idstringrequirednamestringrequirednominate_bystring | nullrequiredpeer_duestring | nullrequired
personobjectrequired2 fields
idstringrequirednamestringrequired
peopleobject[]required2 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
state"nominated" | "asked"requiredasked: approved (whether they answered or declined is never shown).
countsobject | nullrequiredThe reviewer and HR: how many answered (never who).
2 fields
askedintegerrequiredansweredintegerrequired
minintegerrequiredmaxintegerrequiredfullstring[]requiredPeople already asked for the most peer reviews this cycle (12): pick someone else.
can_nominatebooleanrequiredcan_decidebooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"]}'const res = await fetch('https://api.bizisy.com/v1/talent/feedback.decide', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"review_id": "rv1",
"approve": [
"p3"
],
"remove": [
"p4"
],
"add": [
"p6"
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/feedback.decide",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"review_id": "rv1",
"approve": [
"p3",
],
"remove": [
"p4",
],
"add": [
"p6",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_addon HR Assistant- Preview
?dry_run=trueruns 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_idstringrequiredperson_idsstring[]required1–200 characters. 1–8 items.
Returns
10 fields
review_idstringrequiredcycleobjectrequired4 fields
idstringrequirednamestringrequirednominate_bystring | nullrequiredpeer_duestring | nullrequired
personobjectrequired2 fields
idstringrequirednamestringrequired
peopleobject[]required2 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
state"nominated" | "asked"requiredasked: approved (whether they answered or declined is never shown).
countsobject | nullrequiredThe reviewer and HR: how many answered (never who).
2 fields
askedintegerrequiredansweredintegerrequired
minintegerrequiredmaxintegerrequiredfullstring[]requiredPeople already asked for the most peer reviews this cycle (12): pick someone else.
can_nominatebooleanrequiredcan_decidebooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"]}'const res = await fetch('https://api.bizisy.com/v1/talent/feedback.add', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"review_id": "rv1",
"person_ids": [
"p6"
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/feedback.add",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"review_id": "rv1",
"person_ids": [
"p6",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_liston HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
level"company" | "team" | "person"unit_idstring1–200 characters.
person_idstring1–200 characters.
fromstringPattern
^\d{4}-\d{2}-\d{2}$.tostringPattern
^\d{4}-\d{2}-\d{2}$.status"on_track" | "at_risk" | "off_track" | "done" | "dropped"
Returns
itemsobject[]required19 fields
idstringrequiredlevel"company" | "team" | "person"requiredownerobjectrequired2 fields
unitobject | nullrequired2 fields
idstringrequirednamestring | nullrequired
personobject | nullrequired2 fields
idstringrequirednamestringrequired
owner_leftbooleanrequiredThe owner no longer works here: the goal stays, with no owner.
parentobject | nullrequiredThe goal it aligns to (null when you can't see it).
2 fields
idstringrequiredtitlestringrequired
depthintegerrequiredtitlestringrequireddescriptionstringrequiredperiodobjectrequired3 fields
startstringrequiredendstringrequiredlabelstringrequired
key_resultsobject[]required6 fields
idstringrequiredtitlestringrequiredkind"number" | "percent" | "money" | "done"requiredstartnumberrequiredtargetnumberrequiredcurrentnumberrequired
manual_progressnumber | nullrequiredprogressnumberrequiredstatus"on_track" | "at_risk" | "off_track" | "done" | "dropped"requiredsharedbooleanrequiredtargets_lockedbooleanrequiredcommittedbooleanrequiredHR marked it a committed goal (not a stretch OKR): only committed goals can count toward a bonus, when a bonus plan weights goals in.
childrenintegerrequiredGoals aligned to it that you can see.
canobjectrequired3 fields
editbooleanrequiredprogressbooleanrequiredlockbooleanrequired
updated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/talent/goals.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"level": "team",
"from": "2026-10-01",
"to": "2026-12-31"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/goals.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"level": "team",
"from": "2026-10-01",
"to": "2026-12-31",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_geton HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
goal_idstringrequired1–200 characters.
Returns
21 fields
idstringrequiredlevel"company" | "team" | "person"requiredownerobjectrequired2 fields
unitobject | nullrequired2 fields
idstringrequirednamestring | nullrequired
personobject | nullrequired2 fields
idstringrequirednamestringrequired
owner_leftbooleanrequiredThe owner no longer works here: the goal stays, with no owner.
parentobject | nullrequiredThe goal it aligns to (null when you can't see it).
2 fields
idstringrequiredtitlestringrequired
depthintegerrequiredtitlestringrequireddescriptionstringrequiredperiodobjectrequired3 fields
startstringrequiredendstringrequiredlabelstringrequired
key_resultsobject[]required6 fields
idstringrequiredtitlestringrequiredkind"number" | "percent" | "money" | "done"requiredstartnumberrequiredtargetnumberrequiredcurrentnumberrequired
manual_progressnumber | nullrequiredprogressnumberrequiredstatus"on_track" | "at_risk" | "off_track" | "done" | "dropped"requiredsharedbooleanrequiredtargets_lockedbooleanrequiredcommittedbooleanrequiredHR marked it a committed goal (not a stretch OKR): only committed goals can count toward a bonus, when a bonus plan weights goals in.
childrenintegerrequiredGoals aligned to it that you can see.
canobjectrequired3 fields
editbooleanrequiredprogressbooleanrequiredlockbooleanrequired
updated_atstringrequiredalignedobject[]required19 fields
idstringrequiredlevel"company" | "team" | "person"requiredownerobjectrequired2 fields
unitobject | nullrequired2 fields
idstringrequirednamestring | nullrequired
personobject | nullrequired2 fields
idstringrequirednamestringrequired
owner_leftbooleanrequiredThe owner no longer works here: the goal stays, with no owner.
parentobject | nullrequiredThe goal it aligns to (null when you can't see it).
2 fields
idstringrequiredtitlestringrequired
depthintegerrequiredtitlestringrequireddescriptionstringrequiredperiodobjectrequired3 fields
startstringrequiredendstringrequiredlabelstringrequired
key_resultsobject[]required6 fields
idstringrequiredtitlestringrequiredkind"number" | "percent" | "money" | "done"requiredstartnumberrequiredtargetnumberrequiredcurrentnumberrequired
manual_progressnumber | nullrequiredprogressnumberrequiredstatus"on_track" | "at_risk" | "off_track" | "done" | "dropped"requiredsharedbooleanrequiredtargets_lockedbooleanrequiredcommittedbooleanrequiredHR marked it a committed goal (not a stretch OKR): only committed goals can count toward a bonus, when a bonus plan weights goals in.
childrenintegerrequiredGoals aligned to it that you can see.
canobjectrequired3 fields
editbooleanrequiredprogressbooleanrequiredlockbooleanrequired
updated_atstringrequired
updatesobject[]required6 fields
idstringrequiredbyobject | nullrequired2 fields
idstringrequirednamestringrequired
progressnumberrequirednotestring | nullrequiredvia"manual" | "one_on_one" | "check_in"requiredatstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/talent/goals.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"goal_id":"g1"}'const res = await fetch('https://api.bizisy.com/v1/talent/goals.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"goal_id": "g1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/goals.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"goal_id": "g1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_createon HR Assistant, My Workplace- Preview
?dry_run=trueruns 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"requiredowner_unit_idstring1–200 characters.
owner_person_idstring1–200 characters.
parent_idstring | null1–200 characters.
titlestringrequired1–200 characters.
descriptionstringUp to 5000 characters. Default
"".periodobjectrequired3 fields
startstringrequiredPattern
^\d{4}-\d{2}-\d{2}$.endstringrequiredPattern
^\d{4}-\d{2}-\d{2}$.labelstringrequirede.g. "2026 Q4", "H1 2027", "2027".
1–40 characters.
key_resultsobject[]Up to 5 items.
6 fields
idstringKeep the id when editing.
Pattern
^[a-z0-9_-]{1,40}$.titlestringrequired1–200 characters.
kind"number" | "percent" | "money" | "done"requirednumber, percent, money (an amount, no currency conversion) or done (0 or 1).
startnumberrequiredtargetnumberrequiredcurrentnumber
manual_progressnumber | nullFrom 0 to 100.
sharedbooleanDefault
false.
Returns
19 fields
idstringrequiredlevel"company" | "team" | "person"requiredownerobjectrequired2 fields
unitobject | nullrequired2 fields
idstringrequirednamestring | nullrequired
personobject | nullrequired2 fields
idstringrequirednamestringrequired
owner_leftbooleanrequiredThe owner no longer works here: the goal stays, with no owner.
parentobject | nullrequiredThe goal it aligns to (null when you can't see it).
2 fields
idstringrequiredtitlestringrequired
depthintegerrequiredtitlestringrequireddescriptionstringrequiredperiodobjectrequired3 fields
startstringrequiredendstringrequiredlabelstringrequired
key_resultsobject[]required6 fields
idstringrequiredtitlestringrequiredkind"number" | "percent" | "money" | "done"requiredstartnumberrequiredtargetnumberrequiredcurrentnumberrequired
manual_progressnumber | nullrequiredprogressnumberrequiredstatus"on_track" | "at_risk" | "off_track" | "done" | "dropped"requiredsharedbooleanrequiredtargets_lockedbooleanrequiredcommittedbooleanrequiredHR marked it a committed goal (not a stretch OKR): only committed goals can count toward a bonus, when a bonus plan weights goals in.
childrenintegerrequiredGoals aligned to it that you can see.
canobjectrequired3 fields
editbooleanrequiredprogressbooleanrequiredlockbooleanrequired
updated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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
}
]
}'const res = await fetch('https://api.bizisy.com/v1/talent/goals.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"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
}
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/goals.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"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,
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_updateon HR Assistant, My Workplace- Preview
?dry_run=trueruns 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_idstringrequired1–200 characters.
titlestring1–200 characters.
descriptionstringUp to 5000 characters.
periodobject3 fields
startstringrequiredPattern
^\d{4}-\d{2}-\d{2}$.endstringrequiredPattern
^\d{4}-\d{2}-\d{2}$.labelstringrequirede.g. "2026 Q4", "H1 2027", "2027".
1–40 characters.
key_resultsobject[]Up to 5 items.
6 fields
idstringKeep the id when editing.
Pattern
^[a-z0-9_-]{1,40}$.titlestringrequired1–200 characters.
kind"number" | "percent" | "money" | "done"requirednumber, percent, money (an amount, no currency conversion) or done (0 or 1).
startnumberrequiredtargetnumberrequiredcurrentnumber
sharedbooleantargets_lockedbooleancommittedboolean
Returns
19 fields
idstringrequiredlevel"company" | "team" | "person"requiredownerobjectrequired2 fields
unitobject | nullrequired2 fields
idstringrequirednamestring | nullrequired
personobject | nullrequired2 fields
idstringrequirednamestringrequired
owner_leftbooleanrequiredThe owner no longer works here: the goal stays, with no owner.
parentobject | nullrequiredThe goal it aligns to (null when you can't see it).
2 fields
idstringrequiredtitlestringrequired
depthintegerrequiredtitlestringrequireddescriptionstringrequiredperiodobjectrequired3 fields
startstringrequiredendstringrequiredlabelstringrequired
key_resultsobject[]required6 fields
idstringrequiredtitlestringrequiredkind"number" | "percent" | "money" | "done"requiredstartnumberrequiredtargetnumberrequiredcurrentnumberrequired
manual_progressnumber | nullrequiredprogressnumberrequiredstatus"on_track" | "at_risk" | "off_track" | "done" | "dropped"requiredsharedbooleanrequiredtargets_lockedbooleanrequiredcommittedbooleanrequiredHR marked it a committed goal (not a stretch OKR): only committed goals can count toward a bonus, when a bonus plan weights goals in.
childrenintegerrequiredGoals aligned to it that you can see.
canobjectrequired3 fields
editbooleanrequiredprogressbooleanrequiredlockbooleanrequired
updated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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}'const res = await fetch('https://api.bizisy.com/v1/talent/goals.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"goal_id": "g1",
"targets_locked": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/goals.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"goal_id": "g1",
"targets_locked": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_progresson HR Assistant, My Workplace- Preview
?dry_run=trueruns 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_idstringrequired1–200 characters.
kr_valuesobject[]Up to 5 items.
2 fields
idstringrequiredcurrentnumberrequired
manual_progressnumberFrom 0 to 100.
status"on_track" | "at_risk" | "off_track"notestring | nullUp to 1000 characters.
via"manual" | "one_on_one" | "check_in"Default
"manual".ref_idstring | null1–200 characters.
Returns
19 fields
idstringrequiredlevel"company" | "team" | "person"requiredownerobjectrequired2 fields
unitobject | nullrequired2 fields
idstringrequirednamestring | nullrequired
personobject | nullrequired2 fields
idstringrequirednamestringrequired
owner_leftbooleanrequiredThe owner no longer works here: the goal stays, with no owner.
parentobject | nullrequiredThe goal it aligns to (null when you can't see it).
2 fields
idstringrequiredtitlestringrequired
depthintegerrequiredtitlestringrequireddescriptionstringrequiredperiodobjectrequired3 fields
startstringrequiredendstringrequiredlabelstringrequired
key_resultsobject[]required6 fields
idstringrequiredtitlestringrequiredkind"number" | "percent" | "money" | "done"requiredstartnumberrequiredtargetnumberrequiredcurrentnumberrequired
manual_progressnumber | nullrequiredprogressnumberrequiredstatus"on_track" | "at_risk" | "off_track" | "done" | "dropped"requiredsharedbooleanrequiredtargets_lockedbooleanrequiredcommittedbooleanrequiredHR marked it a committed goal (not a stretch OKR): only committed goals can count toward a bonus, when a bonus plan weights goals in.
childrenintegerrequiredGoals aligned to it that you can see.
canobjectrequired3 fields
editbooleanrequiredprogressbooleanrequiredlockbooleanrequired
updated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"
}'const res = await fetch('https://api.bizisy.com/v1/talent/goals.progress', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"goal_id": "g1",
"kr_values": [
{
"id": "kr1",
"current": 90
}
],
"status": "at_risk",
"via": "one_on_one",
"ref_id": "m1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/goals.progress",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"goal_id": "g1",
"kr_values": [
{
"id": "kr1",
"current": 90,
},
],
"status": "at_risk",
"via": "one_on_one",
"ref_id": "m1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_closeon HR Assistant, My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
goal_idstringrequired1–200 characters.
status"done" | "dropped" | "on_track"required
Returns
19 fields
idstringrequiredlevel"company" | "team" | "person"requiredownerobjectrequired2 fields
unitobject | nullrequired2 fields
idstringrequirednamestring | nullrequired
personobject | nullrequired2 fields
idstringrequirednamestringrequired
owner_leftbooleanrequiredThe owner no longer works here: the goal stays, with no owner.
parentobject | nullrequiredThe goal it aligns to (null when you can't see it).
2 fields
idstringrequiredtitlestringrequired
depthintegerrequiredtitlestringrequireddescriptionstringrequiredperiodobjectrequired3 fields
startstringrequiredendstringrequiredlabelstringrequired
key_resultsobject[]required6 fields
idstringrequiredtitlestringrequiredkind"number" | "percent" | "money" | "done"requiredstartnumberrequiredtargetnumberrequiredcurrentnumberrequired
manual_progressnumber | nullrequiredprogressnumberrequiredstatus"on_track" | "at_risk" | "off_track" | "done" | "dropped"requiredsharedbooleanrequiredtargets_lockedbooleanrequiredcommittedbooleanrequiredHR marked it a committed goal (not a stretch OKR): only committed goals can count toward a bonus, when a bonus plan weights goals in.
childrenintegerrequiredGoals aligned to it that you can see.
canobjectrequired3 fields
editbooleanrequiredprogressbooleanrequiredlockbooleanrequired
updated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/talent/goals.close', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"goal_id": "g1",
"status": "done"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/goals.close",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"goal_id": "g1",
"status": "done",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_alignon HR Assistant, My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
goal_idstringrequired1–200 characters.
parent_idstring | nullrequired1–200 characters.
Returns
19 fields
idstringrequiredlevel"company" | "team" | "person"requiredownerobjectrequired2 fields
unitobject | nullrequired2 fields
idstringrequirednamestring | nullrequired
personobject | nullrequired2 fields
idstringrequirednamestringrequired
owner_leftbooleanrequiredThe owner no longer works here: the goal stays, with no owner.
parentobject | nullrequiredThe goal it aligns to (null when you can't see it).
2 fields
idstringrequiredtitlestringrequired
depthintegerrequiredtitlestringrequireddescriptionstringrequiredperiodobjectrequired3 fields
startstringrequiredendstringrequiredlabelstringrequired
key_resultsobject[]required6 fields
idstringrequiredtitlestringrequiredkind"number" | "percent" | "money" | "done"requiredstartnumberrequiredtargetnumberrequiredcurrentnumberrequired
manual_progressnumber | nullrequiredprogressnumberrequiredstatus"on_track" | "at_risk" | "off_track" | "done" | "dropped"requiredsharedbooleanrequiredtargets_lockedbooleanrequiredcommittedbooleanrequiredHR marked it a committed goal (not a stretch OKR): only committed goals can count toward a bonus, when a bonus plan weights goals in.
childrenintegerrequiredGoals aligned to it that you can see.
canobjectrequired3 fields
editbooleanrequiredprogressbooleanrequiredlockbooleanrequired
updated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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}'const res = await fetch('https://api.bizisy.com/v1/talent/goals.align', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"goal_id": "g1",
"parent_id": null
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/goals.align",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"goal_id": "g1",
"parent_id": None,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_statuson HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
availablebooleanrequiredreason"unavailable" | "off" | "addendum"requiredunavailable: not on this server; off: the company has not switched it on; addendum: the AI features addendum needs an owner's acceptance again.
per_dayintegerrequiredleft_todayintegerrequiredcreditsobjectrequiredAI credits a suggestion typically uses, and the most one can.
2 fields
estimateintegerrequiredmaxintegerrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/talent/goals.suggest_status \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/talent/goals.suggest_status', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/goals.suggest_status",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"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_measureson HR Assistant, My Workplace- Preview
?dry_run=trueruns 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
titlestringrequired3–200 characters.
descriptionstringUp to 1000 characters.
level"company" | "team" | "person"language"en" | "pt" | "es" | "de" | "fr" | "it"Your app language: suggestions are written in it.
Returns
suggestionsobject[]required4 fields
titlestringrequiredkind"number" | "percent" | "money" | "done"requiredstartnumberrequiredtargetnumberrequired
ai_generatedtruerequiredai_creditsobjectrequired2 fields
costintegerrequiredWhat 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 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"
}'const res = await fetch('https://api.bizisy.com/v1/talent/goals.suggest_measures', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"title": "Answer every chat faster",
"description": "Contact centre, Spanish queue.",
"level": "team",
"language": "pt"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/goals.suggest_measures",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"title": "Answer every chat faster",
"description": "Contact centre, Spanish queue.",
"level": "team",
"language": "pt",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_remindon HR Assistant- Preview
?dry_run=trueruns 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 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"}'const res = await fetch('https://api.bizisy.com/v1/talent/cycles.remind', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"cycle_id": "cy1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/cycles.remind",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"cycle_id": "cy1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_checkon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
cycle_idstringrequired
Returns
cycleobjectrequired2 fields
idstringrequirednamestringrequired
scaleobject[]required2 fields
valueintegerrequiredlabelstringrequired
recordedobjectrequiredPeople in the check by recorded sex; not_included: another, prefers not to say or not recorded.
3 fields
womenintegerrequiredmenintegerrequirednot_includedintegerrequired
min_groupintegerrequiredtotalobjectrequired9 fields
womeninteger | nullrequiredmeninteger | nullrequirednot_includedinteger | nullrequirednull when the group is hidden (its counts would say who is a woman or a man).
suppressedbooleanrequiredFewer than min_group women or men here (or hidden so another hidden group can't be worked out): no figures.
ratingobject | nullrequired7 fields
levelsobject[]required3 fields
valueintegerrequiredwomen_pctnumberrequiredmen_pctnumberrequired
women_meannumberrequiredmen_meannumberrequiredgap_pointsnumberrequiredMen's mean rating − women's: positive when women are rated lower.
gap_pct_of_rangenumberrequiredThe gap as % of the scale's range (flagged from 5 %).
topobjectrequired3 fields
women_pctnumberrequiredmen_pctnumberrequiredrationumber | nullrequired
bottomobjectrequired3 fields
women_pctnumberrequiredmen_pctnumberrequiredrationumber | nullrequired
potentialobject | nullrequired2 fields
levelsobject[]required3 fields
level"low" | "moderate" | "high"requiredwomen_pctnumberrequiredmen_pctnumberrequired
highobjectrequired3 fields
women_pctnumberrequiredmen_pctnumberrequiredrationumber | nullrequired
movesobject | nullrequiredCalibration moves as shares of each sex (ratio: women's rate ÷ men's; null with fewer than 5 such moves).
4 fields
rating_upobjectrequired3 fields
women_pctnumberrequiredmen_pctnumberrequiredrationumber | nullrequired
rating_downobjectrequired3 fields
women_pctnumberrequiredmen_pctnumberrequiredrationumber | nullrequired
potential_upobjectrequired3 fields
women_pctnumberrequiredmen_pctnumberrequiredrationumber | nullrequired
potential_downobjectrequired3 fields
women_pctnumberrequiredmen_pctnumberrequiredrationumber | nullrequired
raiseobject | nullrequired2 fields
levelsobject[]required3 fields
valueinteger | nullrequiredwomen_meannumber | nullrequiredmen_meannumber | nullrequired
gap_ppnumber | nullrequired
flagsstring (enum)[]requiredOne of:
rating_gap,top_rating,bottom_rating,high_potential,rating_up,rating_down,potential_up,potential_down,raise_gap.
sessionsobject[]required11 fields
womeninteger | nullrequiredmeninteger | nullrequirednot_includedinteger | nullrequirednull when the group is hidden (its counts would say who is a woman or a man).
suppressedbooleanrequiredFewer than min_group women or men here (or hidden so another hidden group can't be worked out): no figures.
ratingobject | nullrequired7 fields
levelsobject[]required3 fields
valueintegerrequiredwomen_pctnumberrequiredmen_pctnumberrequired
women_meannumberrequiredmen_meannumberrequiredgap_pointsnumberrequiredMen's mean rating − women's: positive when women are rated lower.
gap_pct_of_rangenumberrequiredThe gap as % of the scale's range (flagged from 5 %).
topobjectrequired3 fields
women_pctnumberrequiredmen_pctnumberrequiredrationumber | nullrequired
bottomobjectrequired3 fields
women_pctnumberrequiredmen_pctnumberrequiredrationumber | nullrequired
potentialobject | nullrequired2 fields
levelsobject[]required3 fields
level"low" | "moderate" | "high"requiredwomen_pctnumberrequiredmen_pctnumberrequired
highobjectrequired3 fields
women_pctnumberrequiredmen_pctnumberrequiredrationumber | nullrequired
movesobject | nullrequiredCalibration moves as shares of each sex (ratio: women's rate ÷ men's; null with fewer than 5 such moves).
4 fields
rating_upobjectrequired3 fields
women_pctnumberrequiredmen_pctnumberrequiredrationumber | nullrequired
rating_downobjectrequired3 fields
women_pctnumberrequiredmen_pctnumberrequiredrationumber | nullrequired
potential_upobjectrequired3 fields
women_pctnumberrequiredmen_pctnumberrequiredrationumber | nullrequired
potential_downobjectrequired3 fields
women_pctnumberrequiredmen_pctnumberrequiredrationumber | nullrequired
raiseobject | nullrequired2 fields
levelsobject[]required3 fields
valueinteger | nullrequiredwomen_meannumber | nullrequiredmen_meannumber | nullrequired
gap_ppnumber | nullrequired
flagsstring (enum)[]requiredOne of:
rating_gap,top_rating,bottom_rating,high_potential,rating_up,rating_down,potential_up,potential_down,raise_gap.idstringrequirednamestringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/talent/cycles.sex_check', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"cycle_id": "cy1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/talent/cycles.sex_check",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"cycle_id": "cy1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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.