API reference
Surveys
Surveys and forms with pages, logic, piping, scoring and translations, named or confidential; send them to everyone, teams, locations, entities or saved groups, now or at a time; results by group within the confidentiality thresholds, CSV, XLSX, SPSS and JSON exports, a Google Sheets link, lifecycle surveys (start, exit, move, return), actions from results, a public link anyone can answer without signing in (with its embed, kiosk and abuse limits), themes with background images, AI drafts, question checks, comment themes and questions about results, and replies to comments that never identify their author.
39 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
List surveys#
POST/v1/surveys/surveys.listRead
The company's surveys, newest first, with their status (draft, scheduled, open, closed), mode, how many people they went to and how many answered (a confidential survey says "under N" until N answered). archived true lists archived ones. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_surveys_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
archivedbooleantrue: only archived surveys.
status"draft" | "scheduled" | "open" | "closed"
Returns
itemsobject[]required21 fields
idstringrequiredtitlestringrequiredmode"named" | "confidential" | "anonymous"requiredstatus"draft" | "scheduled" | "open" | "closed"requiredarchivedbooleanrequiredquestionsintegerrequiredlanguagestringrequiredlanguagesstring[]requiredrecipientsintegerrequiredansweredinteger | nullrequirednull while fewer than the threshold answered a confidential survey (see answered_under).
answered_underinteger | nullrequiredConfidential: "under N" when fewer than N answered.
open_atstring | nullrequiredopened_atstring | nullrequiredclose_atstring | nullrequiredclosed_atstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredkind"custom" | "listening"requiredseries_idstring | nullrequiredRecurring surveys: the series (its first round's id); null for a one-off.
round_nointegerrequiredWhich round of its series (1 for a one-off).
recurringbooleanrequiredThe series still sends new rounds (stop it with surveys_series_stop).
totalintegerrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/surveys.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"archived":true}'const res = await fetch('https://api.bizisy.com/v1/surveys/surveys.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/surveys/surveys.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": "s1",
"title": "Team pulse",
"mode": "confidential",
"status": "open",
"archived": false,
"questions": 3,
"language": "en",
"languages": [
"pt-PT"
],
"recipients": 24,
"answered": 12,
"answered_under": null,
"open_at": "2026-11-13T09:00:00.000Z",
"opened_at": "2026-11-13T09:00:00.000Z",
"close_at": "2026-11-27T18:00:00.000Z",
"closed_at": null,
"created_at": "2026-11-12T10:00:00.000Z",
"updated_at": "2026-11-13T10:00:00.000Z",
"kind": "listening",
"series_id": "s1",
"round_no": 2,
"recurring": true
}
],
"total": 1
}
}Get a survey#
POST/v1/surveys/surveys.getRead
One survey with its questions (definition), mode, thresholds, audience, schedule and reminders, and the problems that stop it from opening (empty: ready). Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_surveys_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
survey_idstringrequired1–64 characters.
Returns
38 fields
idstringrequiredtitlestringrequiredmode"named" | "confidential" | "anonymous"requiredstatus"draft" | "scheduled" | "open" | "closed"requiredarchivedbooleanrequiredquestionsintegerrequiredlanguagestringrequiredlanguagesstring[]requiredrecipientsintegerrequiredansweredinteger | nullrequirednull while fewer than the threshold answered a confidential survey (see answered_under).
answered_underinteger | nullrequiredConfidential: "under N" when fewer than N answered.
open_atstring | nullrequiredopened_atstring | nullrequiredclose_atstring | nullrequiredclosed_atstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredkind"custom" | "listening"requiredseries_idstring | nullrequiredRecurring surveys: the series (its first round's id); null for a one-off.
round_nointegerrequiredWhich round of its series (1 for a one-off).
recurringbooleanrequiredThe series still sends new rounds (stop it with surveys_series_stop).
definitionobjectrequiredThe survey: pages of questions (types: single, multi, dropdown, nps 0–10, likert 5/7, star, emoji, slider, ranking, matrix, short_text, long_text, number, date, yes_no, people (named surveys only), location, statement, consent), show_if conditions, jumps after a page (to a later page or "end"), piping in texts and choices ({{answer:<question id>}}, {{person:first_name|team|location}}, {{var:<variable id>}}), variables fed by score_into, outcomes shown at the end, translations per language keyed like "q:<question id>:title" or "c:<question id>:<choice id>".
12 fields
languagestringrequiredPattern
^[a-z]{2}(-[A-Z]{2})?$.languagesstring[]requiredUp to 10 items. Pattern
^[a-z]{2}(-[A-Z]{2})?$.translationsobjectrequiredcoverobjectrequired3 fields
showbooleanrequiredtitlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
thanksobjectrequired5 fields
titlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
link_urlstring | nullUp to 500 characters. Pattern
^https:\/\/[^\s]+$.link_labelstring | nullUp to 80 characters.
redirect_urlstring | nullUp to 500 characters. Pattern
^https:\/\/[^\s]+$.
layout"one" | "page"requiredprogressbooleanrequiredlogobooleanrequiredthemeobjectHow the answering screen looks (the Design tab).
7 fields
palettestring (enum)company (Settings → Appearance) or one of the palettes.
One of:
company,emerald,violet,indigo,ocean,amber,rose,graphite,terracotta.surface"plain" | "soft" | "tinted" | "dark"The page behind the questions: plain, soft, tinted or dark.
font"default" | "friendly" | "display" | "serif"buttons"rounded" | "pill" | "square"imagestring | nullA background image id from surveys_design_image_upload.
Pattern
^[0-9a-z]{26}$.image_dimintegerHow much the image is veiled under the text, 45–85 (%; default 65): the text stays readable.
From 45 to 85.
brandingboolean"Powered by Bizisy" at the bottom (default true).
pagesobject[]required1–50 items.
6 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.titlestring | nullUp to 300 characters.
descriptionstring | nullUp to 2000 characters.
questionsobject[]requiredUp to 200 items.
22 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.typestring (enum)requiredOne of:
single,multi,dropdown,nps,likert,star,emoji,slider,ranking,matrix,short_text,long_text,number,date,yes_no,people,location,statement,consent.titlestringrequiredUp to 1000 characters.
descriptionstring | nullUp to 2000 characters.
requiredbooleanrequired_messagestring | nullUp to 200 characters.
choicesobject[]Up to 100 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.labelstringrequiredUp to 500 characters.
scorenumber | nullquotainteger | nullFrom 1 to 100000.
otherbooleanrandomizebooleanmax_picksinteger | nullFrom 1 to 100.
points5 | 7minnumber | nullmaxnumber | nullstepnumber | nullAt least 0.
low_labelstring | nullUp to 80 characters.
high_labelstring | nullUp to 80 characters.
rowsobject[]Up to 100 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.labelstringrequiredUp to 500 characters.
scorenumber | nullquotainteger | nullFrom 1 to 100000.
max_lengthinteger | nullFrom 1 to 5000.
show_ifobject | null2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
score_intoobject | null2 fields
variablestringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.weightnumber
library_idstring | nullThe library item it was copied from (surveys_library_list): rounds and trends compare by it.
Pattern
^lib\.[a-z]+\.[a-z]+$.driverstring | nullThe engagement driver it measures (engagement, recognition, growth, manager, workload, autonomy, belonging, purpose, communication, wellbeing, fairness).
Pattern
^[a-z_]{2,30}$.
randomize_questionsbooleanjumpsobject[]Up to 20 items.
2 fields
whenobjectrequired2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
tostring | "end"required
variablesobject[]requiredUp to 20 items.
3 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.namestringrequiredUp to 80 characters.
initialnumber
outcomesobject[]requiredUp to 20 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.titlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
whenobjectrequired2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
5 fields
qstringPattern
^[A-Za-z0-9_-]{1,40}$.vstringPattern
^[A-Za-z0-9_-]{1,40}$.f"team" | "location" | "entity" | "language"opstring (enum)requiredOne of:
eq,neq,gt,gte,lt,lte,includes,excludes,answered,not_answered.valuestring | number | boolean | "null"
thresholdintegerrequiredcomment_thresholdintegerrequiredaudienceobjectrequired5 fields
everyonebooleanDefault
false.unit_idsstring[]1–64 characters. Up to 200 items.
location_idsstring[]1–64 characters. Up to 200 items.
entity_idsstring[]1–64 characters. Up to 50 items.
group_idsstring[]1–64 characters. Up to 50 items.
reminder_daysinteger[]requiredproblemsobject[]requiredWhat stops it from opening (empty: ready).
2 fields
atstringrequiredmessagestringrequired
lockedbooleanrequiredOpened once: the mode and questions are fixed; translations, reminders and the close date can still change.
manager_viewbooleanrequiredManagers see their own line's results in My workspace (above the threshold, never a sub-line that could be worked out).
recurrenceobject | nullrequiredThe series' schedule (on its first round).
2 fields
every"week" | "two_weeks" | "month" | "quarter" | "half_year" | "year"requiredopen_daysintegerFrom 1 to 60. Default
7.
anonymous_bands"team" | "location" | "tenure"[]requiredAnonymous surveys: the coarse bands kept with each answer.
fatigue_skippedintegerrequiredPeople left out at sending: they already had their surveys this month.
triggerobject | nullrequiredLifecycle: sent to each person in the audience at a moment of their working life (start, exit, move, return), from the day it opens.
2 fields
kind"start" | "exit" | "move" | "return"requiredstart: days after the first day; exit: days before the last day (only once the person was told, while they still have access); move: days after a change of team, location, title or manager; return: days after coming back from a leave of at least 28 days.
daysintegerrequiredFrom 0 to 365.
slackbooleanrequiredInvitations and reminders also go as Slack direct messages where the company connected Slack.
retention_monthsintegerrequiredAnswers are deleted this many months after it closes; the group results are kept.
purged_atstring | nullrequiredWhen its answers were deleted (retention); results then come from the kept group results.
publicobject | nullrequiredIts public link (surveys_public_set); null: never set.
10 fields
onbooleanrequiredidstringrequiredrespondent"anonymous" | "named"requiredmax_answersintegerrequiredone_per_browserbooleanrequiredkioskbooleanrequiredembed_domainsstring[]requiredansweredintegerrequiredswitched_off_by_bizisybooleanrequiredreportsintegerrequired
councilobjectrequiredThe works council's approval (when the company asks for it, surveys_settings_get council_approval).
3 fields
status"not_asked" | "waiting" | "approved" | "returned"requiredapproved_for_this_versionbooleanrequiredentriesobject[]required4 fields
kind"asked" | "approved" | "returned" | "comment"requiredbystringrequiredtextstring | nullrequiredatstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/surveys.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"survey_id":"s1"}'const res = await fetch('https://api.bizisy.com/v1/surveys/surveys.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"survey_id": "s1"
}),
});
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/surveys/surveys.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"survey_id": "s1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "s1",
"title": "Team pulse",
"mode": "confidential",
"status": "open",
"archived": false,
"questions": 3,
"language": "en",
"languages": [
"pt-PT"
],
"recipients": 24,
"answered": 12,
"answered_under": null,
"open_at": "2026-11-13T09:00:00.000Z",
"opened_at": "2026-11-13T09:00:00.000Z",
"close_at": "2026-11-27T18:00:00.000Z",
"closed_at": null,
"created_at": "2026-11-12T10:00:00.000Z",
"updated_at": "2026-11-13T10:00:00.000Z",
"kind": "listening",
"series_id": "s1",
"round_no": 2,
"recurring": true,
"definition": {
"language": "en",
"languages": [
"pt-PT"
],
"translations": {
"pt-PT": {
"q:q1:title": "Recomendaria a empresa?"
}
},
"cover": {
"show": true,
"title": "Team pulse",
"body": "Five questions, two minutes."
},
"thanks": {
"title": "Thank you!",
"body": null,
"link_url": null,
"link_label": null,
"redirect_url": null
},
"layout": "one",
"progress": true,
"logo": true,
"pages": [
{
"id": "p1",
"title": null,
"description": null,
"questions": [
{
"id": "q1",
"type": "nps",
"title": "How likely are you to recommend us as a place to work?",
"required": true,
"low_label": "Not at all",
"high_label": "Very likely"
},
{
"id": "q2",
"type": "single",
"title": "Lunch, {{person:first_name}}?",
"choices": [
{
"id": "c1",
"label": "Fish",
"quota": 20
},
{
"id": "c2",
"label": "Veg"
}
],
"other": true
},
{
"id": "q3",
"type": "long_text",
"title": "What would you change?",
"show_if": {
"match": "all",
"rules": [
{
"q": "q1",
"op": "lte",
"value": 6
}
]
}
}
],
"jumps": []
}
],
"variables": [],
"outcomes": []
},
"threshold": 5,
"comment_threshold": 10,
"audience": {
"everyone": true,
"unit_ids": [],
"location_ids": [],
"entity_ids": [],
"group_ids": []
},
"reminder_days": [
3,
6
],
"problems": [],
"locked": true,
"manager_view": true,
"recurrence": {
"every": "quarter",
"open_days": 10
},
"anonymous_bands": [],
"fatigue_skipped": 2,
"trigger": null,
"slack": false,
"retention_months": 24,
"purged_at": null,
"council": {
"status": "approved",
"approved_for_this_version": true,
"entries": [
{
"kind": "approved",
"by": "Rita Conselho",
"text": null,
"at": "2026-11-12T15:00:00.000Z"
}
]
},
"public": null
}
}Create a survey#
POST/v1/surveys/surveys.createWrite
Creates a draft survey: a title (for HR; the cover title is what people see), the mode (default confidential) and optionally the whole definition (pages, questions, logic, scoring, translations). Without a definition it starts with a cover, one empty page and a thank-you screen in the given language. Up to 500 per company. Nothing is sent until surveys_surveys_open. Supports dry_run. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_surveys_createon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
titlestringrequired1–160 characters.
mode"named" | "confidential" | "anonymous"named: answers carry the person's name (event sign-ups, forms). confidential: Bizisy knows who answered (for reminders and segments) but nobody ever sees one person's answers or a group smaller than the threshold. anonymous: no link from an answer to a person at all (one-time tokens; only the coarse bands chosen in anonymous_bands are kept; reminders go to everyone). Locked once the survey opens.
Default
"confidential".languagestringThe language HR writes it in (en, pt-PT, es-ES, de-DE, fr-FR, it-IT).
Pattern
^[a-z]{2}(-[A-Z]{2})?$. Default"en".definitionobjectThe survey: pages of questions (types: single, multi, dropdown, nps 0–10, likert 5/7, star, emoji, slider, ranking, matrix, short_text, long_text, number, date, yes_no, people (named surveys only), location, statement, consent), show_if conditions, jumps after a page (to a later page or "end"), piping in texts and choices ({{answer:<question id>}}, {{person:first_name|team|location}}, {{var:<variable id>}}), variables fed by score_into, outcomes shown at the end, translations per language keyed like "q:<question id>:title" or "c:<question id>:<choice id>".
12 fields
languagestringrequiredPattern
^[a-z]{2}(-[A-Z]{2})?$.languagesstring[]requiredUp to 10 items. Pattern
^[a-z]{2}(-[A-Z]{2})?$.translationsobjectrequiredcoverobjectrequired3 fields
showbooleanrequiredtitlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
thanksobjectrequired5 fields
titlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
link_urlstring | nullUp to 500 characters. Pattern
^https:\/\/[^\s]+$.link_labelstring | nullUp to 80 characters.
redirect_urlstring | nullUp to 500 characters. Pattern
^https:\/\/[^\s]+$.
layout"one" | "page"requiredprogressbooleanrequiredlogobooleanrequiredthemeobjectHow the answering screen looks (the Design tab).
7 fields
palettestring (enum)company (Settings → Appearance) or one of the palettes.
One of:
company,emerald,violet,indigo,ocean,amber,rose,graphite,terracotta.surface"plain" | "soft" | "tinted" | "dark"The page behind the questions: plain, soft, tinted or dark.
font"default" | "friendly" | "display" | "serif"buttons"rounded" | "pill" | "square"imagestring | nullA background image id from surveys_design_image_upload.
Pattern
^[0-9a-z]{26}$.image_dimintegerHow much the image is veiled under the text, 45–85 (%; default 65): the text stays readable.
From 45 to 85.
brandingboolean"Powered by Bizisy" at the bottom (default true).
pagesobject[]required1–50 items.
6 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.titlestring | nullUp to 300 characters.
descriptionstring | nullUp to 2000 characters.
questionsobject[]requiredUp to 200 items.
22 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.typestring (enum)requiredOne of:
single,multi,dropdown,nps,likert,star,emoji,slider,ranking,matrix,short_text,long_text,number,date,yes_no,people,location,statement,consent.titlestringrequiredUp to 1000 characters.
descriptionstring | nullUp to 2000 characters.
requiredbooleanrequired_messagestring | nullUp to 200 characters.
choicesobject[]Up to 100 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.labelstringrequiredUp to 500 characters.
scorenumber | nullquotainteger | nullFrom 1 to 100000.
otherbooleanrandomizebooleanmax_picksinteger | nullFrom 1 to 100.
points5 | 7minnumber | nullmaxnumber | nullstepnumber | nullAt least 0.
low_labelstring | nullUp to 80 characters.
high_labelstring | nullUp to 80 characters.
rowsobject[]Up to 100 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.labelstringrequiredUp to 500 characters.
scorenumber | nullquotainteger | nullFrom 1 to 100000.
max_lengthinteger | nullFrom 1 to 5000.
show_ifobject | null2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
score_intoobject | null2 fields
variablestringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.weightnumber
library_idstring | nullThe library item it was copied from (surveys_library_list): rounds and trends compare by it.
Pattern
^lib\.[a-z]+\.[a-z]+$.driverstring | nullThe engagement driver it measures (engagement, recognition, growth, manager, workload, autonomy, belonging, purpose, communication, wellbeing, fairness).
Pattern
^[a-z_]{2,30}$.
randomize_questionsbooleanjumpsobject[]Up to 20 items.
2 fields
whenobjectrequired2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
tostring | "end"required
variablesobject[]requiredUp to 20 items.
3 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.namestringrequiredUp to 80 characters.
initialnumber
outcomesobject[]requiredUp to 20 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.titlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
whenobjectrequired2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
5 fields
qstringPattern
^[A-Za-z0-9_-]{1,40}$.vstringPattern
^[A-Za-z0-9_-]{1,40}$.f"team" | "location" | "entity" | "language"opstring (enum)requiredOne of:
eq,neq,gt,gte,lt,lte,includes,excludes,answered,not_answered.valuestring | number | boolean | "null"
template"enps" | "engagement" | "pulse"Start from a listening template (enps, engagement with drivers, pulse): sourced library questions in the six languages. Ignored with a definition.
audienceobject5 fields
everyonebooleanDefault
false.unit_idsstring[]1–64 characters. Up to 200 items.
location_idsstring[]1–64 characters. Up to 200 items.
entity_idsstring[]1–64 characters. Up to 50 items.
group_idsstring[]1–64 characters. Up to 50 items.
Returns
38 fields
idstringrequiredtitlestringrequiredmode"named" | "confidential" | "anonymous"requiredstatus"draft" | "scheduled" | "open" | "closed"requiredarchivedbooleanrequiredquestionsintegerrequiredlanguagestringrequiredlanguagesstring[]requiredrecipientsintegerrequiredansweredinteger | nullrequirednull while fewer than the threshold answered a confidential survey (see answered_under).
answered_underinteger | nullrequiredConfidential: "under N" when fewer than N answered.
open_atstring | nullrequiredopened_atstring | nullrequiredclose_atstring | nullrequiredclosed_atstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredkind"custom" | "listening"requiredseries_idstring | nullrequiredRecurring surveys: the series (its first round's id); null for a one-off.
round_nointegerrequiredWhich round of its series (1 for a one-off).
recurringbooleanrequiredThe series still sends new rounds (stop it with surveys_series_stop).
definitionobjectrequiredThe survey: pages of questions (types: single, multi, dropdown, nps 0–10, likert 5/7, star, emoji, slider, ranking, matrix, short_text, long_text, number, date, yes_no, people (named surveys only), location, statement, consent), show_if conditions, jumps after a page (to a later page or "end"), piping in texts and choices ({{answer:<question id>}}, {{person:first_name|team|location}}, {{var:<variable id>}}), variables fed by score_into, outcomes shown at the end, translations per language keyed like "q:<question id>:title" or "c:<question id>:<choice id>".
12 fields
languagestringrequiredPattern
^[a-z]{2}(-[A-Z]{2})?$.languagesstring[]requiredUp to 10 items. Pattern
^[a-z]{2}(-[A-Z]{2})?$.translationsobjectrequiredcoverobjectrequired3 fields
showbooleanrequiredtitlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
thanksobjectrequired5 fields
titlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
link_urlstring | nullUp to 500 characters. Pattern
^https:\/\/[^\s]+$.link_labelstring | nullUp to 80 characters.
redirect_urlstring | nullUp to 500 characters. Pattern
^https:\/\/[^\s]+$.
layout"one" | "page"requiredprogressbooleanrequiredlogobooleanrequiredthemeobjectHow the answering screen looks (the Design tab).
7 fields
palettestring (enum)company (Settings → Appearance) or one of the palettes.
One of:
company,emerald,violet,indigo,ocean,amber,rose,graphite,terracotta.surface"plain" | "soft" | "tinted" | "dark"The page behind the questions: plain, soft, tinted or dark.
font"default" | "friendly" | "display" | "serif"buttons"rounded" | "pill" | "square"imagestring | nullA background image id from surveys_design_image_upload.
Pattern
^[0-9a-z]{26}$.image_dimintegerHow much the image is veiled under the text, 45–85 (%; default 65): the text stays readable.
From 45 to 85.
brandingboolean"Powered by Bizisy" at the bottom (default true).
pagesobject[]required1–50 items.
6 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.titlestring | nullUp to 300 characters.
descriptionstring | nullUp to 2000 characters.
questionsobject[]requiredUp to 200 items.
22 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.typestring (enum)requiredOne of:
single,multi,dropdown,nps,likert,star,emoji,slider,ranking,matrix,short_text,long_text,number,date,yes_no,people,location,statement,consent.titlestringrequiredUp to 1000 characters.
descriptionstring | nullUp to 2000 characters.
requiredbooleanrequired_messagestring | nullUp to 200 characters.
choicesobject[]Up to 100 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.labelstringrequiredUp to 500 characters.
scorenumber | nullquotainteger | nullFrom 1 to 100000.
otherbooleanrandomizebooleanmax_picksinteger | nullFrom 1 to 100.
points5 | 7minnumber | nullmaxnumber | nullstepnumber | nullAt least 0.
low_labelstring | nullUp to 80 characters.
high_labelstring | nullUp to 80 characters.
rowsobject[]Up to 100 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.labelstringrequiredUp to 500 characters.
scorenumber | nullquotainteger | nullFrom 1 to 100000.
max_lengthinteger | nullFrom 1 to 5000.
show_ifobject | null2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
score_intoobject | null2 fields
variablestringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.weightnumber
library_idstring | nullThe library item it was copied from (surveys_library_list): rounds and trends compare by it.
Pattern
^lib\.[a-z]+\.[a-z]+$.driverstring | nullThe engagement driver it measures (engagement, recognition, growth, manager, workload, autonomy, belonging, purpose, communication, wellbeing, fairness).
Pattern
^[a-z_]{2,30}$.
randomize_questionsbooleanjumpsobject[]Up to 20 items.
2 fields
whenobjectrequired2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
tostring | "end"required
variablesobject[]requiredUp to 20 items.
3 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.namestringrequiredUp to 80 characters.
initialnumber
outcomesobject[]requiredUp to 20 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.titlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
whenobjectrequired2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
5 fields
qstringPattern
^[A-Za-z0-9_-]{1,40}$.vstringPattern
^[A-Za-z0-9_-]{1,40}$.f"team" | "location" | "entity" | "language"opstring (enum)requiredOne of:
eq,neq,gt,gte,lt,lte,includes,excludes,answered,not_answered.valuestring | number | boolean | "null"
thresholdintegerrequiredcomment_thresholdintegerrequiredaudienceobjectrequired5 fields
everyonebooleanDefault
false.unit_idsstring[]1–64 characters. Up to 200 items.
location_idsstring[]1–64 characters. Up to 200 items.
entity_idsstring[]1–64 characters. Up to 50 items.
group_idsstring[]1–64 characters. Up to 50 items.
reminder_daysinteger[]requiredproblemsobject[]requiredWhat stops it from opening (empty: ready).
2 fields
atstringrequiredmessagestringrequired
lockedbooleanrequiredOpened once: the mode and questions are fixed; translations, reminders and the close date can still change.
manager_viewbooleanrequiredManagers see their own line's results in My workspace (above the threshold, never a sub-line that could be worked out).
recurrenceobject | nullrequiredThe series' schedule (on its first round).
2 fields
every"week" | "two_weeks" | "month" | "quarter" | "half_year" | "year"requiredopen_daysintegerFrom 1 to 60. Default
7.
anonymous_bands"team" | "location" | "tenure"[]requiredAnonymous surveys: the coarse bands kept with each answer.
fatigue_skippedintegerrequiredPeople left out at sending: they already had their surveys this month.
triggerobject | nullrequiredLifecycle: sent to each person in the audience at a moment of their working life (start, exit, move, return), from the day it opens.
2 fields
kind"start" | "exit" | "move" | "return"requiredstart: days after the first day; exit: days before the last day (only once the person was told, while they still have access); move: days after a change of team, location, title or manager; return: days after coming back from a leave of at least 28 days.
daysintegerrequiredFrom 0 to 365.
slackbooleanrequiredInvitations and reminders also go as Slack direct messages where the company connected Slack.
retention_monthsintegerrequiredAnswers are deleted this many months after it closes; the group results are kept.
purged_atstring | nullrequiredWhen its answers were deleted (retention); results then come from the kept group results.
publicobject | nullrequiredIts public link (surveys_public_set); null: never set.
10 fields
onbooleanrequiredidstringrequiredrespondent"anonymous" | "named"requiredmax_answersintegerrequiredone_per_browserbooleanrequiredkioskbooleanrequiredembed_domainsstring[]requiredansweredintegerrequiredswitched_off_by_bizisybooleanrequiredreportsintegerrequired
councilobjectrequiredThe works council's approval (when the company asks for it, surveys_settings_get council_approval).
3 fields
status"not_asked" | "waiting" | "approved" | "returned"requiredapproved_for_this_versionbooleanrequiredentriesobject[]required4 fields
kind"asked" | "approved" | "returned" | "comment"requiredbystringrequiredtextstring | nullrequiredatstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/surveys.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"title": "Canteen",
"mode": "named",
"language": "pt-PT",
"definition": {
"language": "en",
"languages": [
"pt-PT"
],
"translations": {
"pt-PT": {
"q:q1:title": "Recomendaria a empresa?"
}
},
"cover": {
"show": true,
"title": "Team pulse",
"body": "Five questions, two minutes."
},
"thanks": {
"title": "Thank you!",
"body": null,
"link_url": null,
"link_label": null,
"redirect_url": null
},
"layout": "one",
"progress": true,
"logo": true,
"pages": [
{
"id": "p1",
"title": null,
"description": null,
"questions": [
{
"id": "q1",
"type": "nps",
"title": "How likely are you to recommend us as a place to work?",
"required": true,
"low_label": "Not at all",
"high_label": "Very likely"
},
{
"id": "q2",
"type": "single",
"title": "Lunch, {{person:first_name}}?",
"choices": [
{
"id": "c1",
"label": "Fish",
"quota": 20
},
{
"id": "c2",
"label": "Veg"
}
],
"other": true
},
{
"id": "q3",
"type": "long_text",
"title": "What would you change?",
"show_if": {
"match": "all",
"rules": [
{
"q": "q1",
"op": "lte",
"value": 6
}
]
}
}
],
"jumps": []
}
],
"variables": [],
"outcomes": []
}
}'const res = await fetch('https://api.bizisy.com/v1/surveys/surveys.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"title": "Canteen",
"mode": "named",
"language": "pt-PT",
"definition": {
"language": "en",
"languages": [
"pt-PT"
],
"translations": {
"pt-PT": {
"q:q1:title": "Recomendaria a empresa?"
}
},
"cover": {
"show": true,
"title": "Team pulse",
"body": "Five questions, two minutes."
},
"thanks": {
"title": "Thank you!",
"body": null,
"link_url": null,
"link_label": null,
"redirect_url": null
},
"layout": "one",
"progress": true,
"logo": true,
"pages": [
{
"id": "p1",
"title": null,
"description": null,
"questions": [
{
"id": "q1",
"type": "nps",
"title": "How likely are you to recommend us as a place to work?",
"required": true,
"low_label": "Not at all",
"high_label": "Very likely"
},
{
"id": "q2",
"type": "single",
"title": "Lunch, {{person:first_name}}?",
"choices": [
{
"id": "c1",
"label": "Fish",
"quota": 20
},
{
"id": "c2",
"label": "Veg"
}
],
"other": true
},
{
"id": "q3",
"type": "long_text",
"title": "What would you change?",
"show_if": {
"match": "all",
"rules": [
{
"q": "q1",
"op": "lte",
"value": 6
}
]
}
}
],
"jumps": []
}
],
"variables": [],
"outcomes": []
}
}),
});
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/surveys/surveys.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"title": "Canteen",
"mode": "named",
"language": "pt-PT",
"definition": {
"language": "en",
"languages": [
"pt-PT",
],
"translations": {
"pt-PT": {
"q:q1:title": "Recomendaria a empresa?",
},
},
"cover": {
"show": True,
"title": "Team pulse",
"body": "Five questions, two minutes.",
},
"thanks": {
"title": "Thank you!",
"body": None,
"link_url": None,
"link_label": None,
"redirect_url": None,
},
"layout": "one",
"progress": True,
"logo": True,
"pages": [
{
"id": "p1",
"title": None,
"description": None,
"questions": [
{
"id": "q1",
"type": "nps",
"title": "How likely are you to recommend us as a place to work?",
"required": True,
"low_label": "Not at all",
"high_label": "Very likely",
},
{
"id": "q2",
"type": "single",
"title": "Lunch, {{person:first_name}}?",
"choices": [
{
"id": "c1",
"label": "Fish",
"quota": 20,
},
{
"id": "c2",
"label": "Veg",
},
],
"other": True,
},
{
"id": "q3",
"type": "long_text",
"title": "What would you change?",
"show_if": {
"match": "all",
"rules": [
{
"q": "q1",
"op": "lte",
"value": 6,
},
],
},
},
],
"jumps": [],
},
],
"variables": [],
"outcomes": [],
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "s1",
"title": "Canteen",
"mode": "named",
"status": "draft",
"archived": false,
"questions": 3,
"language": "pt-PT",
"languages": [
"pt-PT"
],
"recipients": 0,
"answered": 0,
"answered_under": null,
"open_at": null,
"opened_at": null,
"close_at": "2026-11-27T18:00:00.000Z",
"closed_at": null,
"created_at": "2026-11-12T10:00:00.000Z",
"updated_at": "2026-11-13T10:00:00.000Z",
"kind": "listening",
"series_id": "s1",
"round_no": 2,
"recurring": true,
"definition": {
"language": "en",
"languages": [
"pt-PT"
],
"translations": {
"pt-PT": {
"q:q1:title": "Recomendaria a empresa?"
}
},
"cover": {
"show": true,
"title": "Team pulse",
"body": "Five questions, two minutes."
},
"thanks": {
"title": "Thank you!",
"body": null,
"link_url": null,
"link_label": null,
"redirect_url": null
},
"layout": "one",
"progress": true,
"logo": true,
"pages": [
{
"id": "p1",
"title": null,
"description": null,
"questions": [
{
"id": "q1",
"type": "nps",
"title": "How likely are you to recommend us as a place to work?",
"required": true,
"low_label": "Not at all",
"high_label": "Very likely"
},
{
"id": "q2",
"type": "single",
"title": "Lunch, {{person:first_name}}?",
"choices": [
{
"id": "c1",
"label": "Fish",
"quota": 20
},
{
"id": "c2",
"label": "Veg"
}
],
"other": true
},
{
"id": "q3",
"type": "long_text",
"title": "What would you change?",
"show_if": {
"match": "all",
"rules": [
{
"q": "q1",
"op": "lte",
"value": 6
}
]
}
}
],
"jumps": []
}
],
"variables": [],
"outcomes": []
},
"threshold": 5,
"comment_threshold": 10,
"audience": {
"everyone": true,
"unit_ids": [],
"location_ids": [],
"entity_ids": [],
"group_ids": []
},
"reminder_days": [
3,
6
],
"problems": [],
"locked": false,
"manager_view": true,
"recurrence": {
"every": "quarter",
"open_days": 10
},
"anonymous_bands": [],
"fatigue_skipped": 2,
"trigger": null,
"slack": false,
"retention_months": 24,
"purged_at": null,
"council": {
"status": "approved",
"approved_for_this_version": true,
"entries": [
{
"kind": "approved",
"by": "Rita Conselho",
"text": null,
"at": "2026-11-12T15:00:00.000Z"
}
]
},
"public": null
}
}Change a survey#
POST/v1/surveys/surveys.updateWrite
Changes a survey; send only what changes. Before it opens: everything (title, mode, definition, thresholds — at least 3, comments at least the threshold —, audience, reminder days, close date). Once it has opened: the mode, questions, thresholds and audience are fixed; translations (definition.languages and definition.translations), the look (definition.theme), the title, reminders and the close date can still change. A closed survey keeps its close date. Supports dry_run. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_surveys_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
survey_idstringrequired1–64 characters.
titlestring1–160 characters.
mode"named" | "confidential" | "anonymous"named: answers carry the person's name (event sign-ups, forms). confidential: Bizisy knows who answered (for reminders and segments) but nobody ever sees one person's answers or a group smaller than the threshold. anonymous: no link from an answer to a person at all (one-time tokens; only the coarse bands chosen in anonymous_bands are kept; reminders go to everyone). Locked once the survey opens.
definitionobjectThe survey: pages of questions (types: single, multi, dropdown, nps 0–10, likert 5/7, star, emoji, slider, ranking, matrix, short_text, long_text, number, date, yes_no, people (named surveys only), location, statement, consent), show_if conditions, jumps after a page (to a later page or "end"), piping in texts and choices ({{answer:<question id>}}, {{person:first_name|team|location}}, {{var:<variable id>}}), variables fed by score_into, outcomes shown at the end, translations per language keyed like "q:<question id>:title" or "c:<question id>:<choice id>".
12 fields
languagestringrequiredPattern
^[a-z]{2}(-[A-Z]{2})?$.languagesstring[]requiredUp to 10 items. Pattern
^[a-z]{2}(-[A-Z]{2})?$.translationsobjectrequiredcoverobjectrequired3 fields
showbooleanrequiredtitlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
thanksobjectrequired5 fields
titlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
link_urlstring | nullUp to 500 characters. Pattern
^https:\/\/[^\s]+$.link_labelstring | nullUp to 80 characters.
redirect_urlstring | nullUp to 500 characters. Pattern
^https:\/\/[^\s]+$.
layout"one" | "page"requiredprogressbooleanrequiredlogobooleanrequiredthemeobjectHow the answering screen looks (the Design tab).
7 fields
palettestring (enum)company (Settings → Appearance) or one of the palettes.
One of:
company,emerald,violet,indigo,ocean,amber,rose,graphite,terracotta.surface"plain" | "soft" | "tinted" | "dark"The page behind the questions: plain, soft, tinted or dark.
font"default" | "friendly" | "display" | "serif"buttons"rounded" | "pill" | "square"imagestring | nullA background image id from surveys_design_image_upload.
Pattern
^[0-9a-z]{26}$.image_dimintegerHow much the image is veiled under the text, 45–85 (%; default 65): the text stays readable.
From 45 to 85.
brandingboolean"Powered by Bizisy" at the bottom (default true).
pagesobject[]required1–50 items.
6 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.titlestring | nullUp to 300 characters.
descriptionstring | nullUp to 2000 characters.
questionsobject[]requiredUp to 200 items.
22 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.typestring (enum)requiredOne of:
single,multi,dropdown,nps,likert,star,emoji,slider,ranking,matrix,short_text,long_text,number,date,yes_no,people,location,statement,consent.titlestringrequiredUp to 1000 characters.
descriptionstring | nullUp to 2000 characters.
requiredbooleanrequired_messagestring | nullUp to 200 characters.
choicesobject[]Up to 100 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.labelstringrequiredUp to 500 characters.
scorenumber | nullquotainteger | nullFrom 1 to 100000.
otherbooleanrandomizebooleanmax_picksinteger | nullFrom 1 to 100.
points5 | 7minnumber | nullmaxnumber | nullstepnumber | nullAt least 0.
low_labelstring | nullUp to 80 characters.
high_labelstring | nullUp to 80 characters.
rowsobject[]Up to 100 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.labelstringrequiredUp to 500 characters.
scorenumber | nullquotainteger | nullFrom 1 to 100000.
max_lengthinteger | nullFrom 1 to 5000.
show_ifobject | null2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
score_intoobject | null2 fields
variablestringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.weightnumber
library_idstring | nullThe library item it was copied from (surveys_library_list): rounds and trends compare by it.
Pattern
^lib\.[a-z]+\.[a-z]+$.driverstring | nullThe engagement driver it measures (engagement, recognition, growth, manager, workload, autonomy, belonging, purpose, communication, wellbeing, fairness).
Pattern
^[a-z_]{2,30}$.
randomize_questionsbooleanjumpsobject[]Up to 20 items.
2 fields
whenobjectrequired2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
tostring | "end"required
variablesobject[]requiredUp to 20 items.
3 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.namestringrequiredUp to 80 characters.
initialnumber
outcomesobject[]requiredUp to 20 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.titlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
whenobjectrequired2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
5 fields
qstringPattern
^[A-Za-z0-9_-]{1,40}$.vstringPattern
^[A-Za-z0-9_-]{1,40}$.f"team" | "location" | "entity" | "language"opstring (enum)requiredOne of:
eq,neq,gt,gte,lt,lte,includes,excludes,answered,not_answered.valuestring | number | boolean | "null"
thresholdintegerFrom 3 to 50.
comment_thresholdintegerFrom 3 to 100.
audienceobject5 fields
everyonebooleanDefault
false.unit_idsstring[]1–64 characters. Up to 200 items.
location_idsstring[]1–64 characters. Up to 200 items.
entity_idsstring[]1–64 characters. Up to 50 items.
group_idsstring[]1–64 characters. Up to 50 items.
reminder_daysinteger[]Days after opening on which those who haven't answered are reminded (at most 2, e.g. [3, 6]).
From 1 to 60. Up to 2 items.
close_atdate-time | nullWhen it closes by itself (null: when you close it).
ISO 8601 date and time (UTC).
manager_viewbooleanManagers read their own line's results (confidential and anonymous surveys: above the threshold only). Fixed once it opens.
anonymous_bands"team" | "location" | "tenure"[]Anonymous surveys: which coarse bands to keep with answers (team, location, tenure). Fixed once it opens.
Up to 3 items.
triggerobject | nullLifecycle: send it to each person in the audience at a moment of their working life instead of to everyone at once (null: send once). Fixed once it opens.
2 fields
kind"start" | "exit" | "move" | "return"requiredstart: days after the first day; exit: days before the last day (only once the person was told, while they still have access); move: days after a change of team, location, title or manager; return: days after coming back from a leave of at least 28 days.
daysintegerrequiredFrom 0 to 365.
slackbooleanAlso send invitations and reminders as Slack direct messages where the company connected Slack (held outside working time like emails).
retention_monthsintegerDelete the answers this many months after it closes (6–120; default 24); the group results are kept. Can change any time before the answers are deleted.
From 6 to 120.
Returns
38 fields
idstringrequiredtitlestringrequiredmode"named" | "confidential" | "anonymous"requiredstatus"draft" | "scheduled" | "open" | "closed"requiredarchivedbooleanrequiredquestionsintegerrequiredlanguagestringrequiredlanguagesstring[]requiredrecipientsintegerrequiredansweredinteger | nullrequirednull while fewer than the threshold answered a confidential survey (see answered_under).
answered_underinteger | nullrequiredConfidential: "under N" when fewer than N answered.
open_atstring | nullrequiredopened_atstring | nullrequiredclose_atstring | nullrequiredclosed_atstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredkind"custom" | "listening"requiredseries_idstring | nullrequiredRecurring surveys: the series (its first round's id); null for a one-off.
round_nointegerrequiredWhich round of its series (1 for a one-off).
recurringbooleanrequiredThe series still sends new rounds (stop it with surveys_series_stop).
definitionobjectrequiredThe survey: pages of questions (types: single, multi, dropdown, nps 0–10, likert 5/7, star, emoji, slider, ranking, matrix, short_text, long_text, number, date, yes_no, people (named surveys only), location, statement, consent), show_if conditions, jumps after a page (to a later page or "end"), piping in texts and choices ({{answer:<question id>}}, {{person:first_name|team|location}}, {{var:<variable id>}}), variables fed by score_into, outcomes shown at the end, translations per language keyed like "q:<question id>:title" or "c:<question id>:<choice id>".
12 fields
languagestringrequiredPattern
^[a-z]{2}(-[A-Z]{2})?$.languagesstring[]requiredUp to 10 items. Pattern
^[a-z]{2}(-[A-Z]{2})?$.translationsobjectrequiredcoverobjectrequired3 fields
showbooleanrequiredtitlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
thanksobjectrequired5 fields
titlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
link_urlstring | nullUp to 500 characters. Pattern
^https:\/\/[^\s]+$.link_labelstring | nullUp to 80 characters.
redirect_urlstring | nullUp to 500 characters. Pattern
^https:\/\/[^\s]+$.
layout"one" | "page"requiredprogressbooleanrequiredlogobooleanrequiredthemeobjectHow the answering screen looks (the Design tab).
7 fields
palettestring (enum)company (Settings → Appearance) or one of the palettes.
One of:
company,emerald,violet,indigo,ocean,amber,rose,graphite,terracotta.surface"plain" | "soft" | "tinted" | "dark"The page behind the questions: plain, soft, tinted or dark.
font"default" | "friendly" | "display" | "serif"buttons"rounded" | "pill" | "square"imagestring | nullA background image id from surveys_design_image_upload.
Pattern
^[0-9a-z]{26}$.image_dimintegerHow much the image is veiled under the text, 45–85 (%; default 65): the text stays readable.
From 45 to 85.
brandingboolean"Powered by Bizisy" at the bottom (default true).
pagesobject[]required1–50 items.
6 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.titlestring | nullUp to 300 characters.
descriptionstring | nullUp to 2000 characters.
questionsobject[]requiredUp to 200 items.
22 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.typestring (enum)requiredOne of:
single,multi,dropdown,nps,likert,star,emoji,slider,ranking,matrix,short_text,long_text,number,date,yes_no,people,location,statement,consent.titlestringrequiredUp to 1000 characters.
descriptionstring | nullUp to 2000 characters.
requiredbooleanrequired_messagestring | nullUp to 200 characters.
choicesobject[]Up to 100 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.labelstringrequiredUp to 500 characters.
scorenumber | nullquotainteger | nullFrom 1 to 100000.
otherbooleanrandomizebooleanmax_picksinteger | nullFrom 1 to 100.
points5 | 7minnumber | nullmaxnumber | nullstepnumber | nullAt least 0.
low_labelstring | nullUp to 80 characters.
high_labelstring | nullUp to 80 characters.
rowsobject[]Up to 100 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.labelstringrequiredUp to 500 characters.
scorenumber | nullquotainteger | nullFrom 1 to 100000.
max_lengthinteger | nullFrom 1 to 5000.
show_ifobject | null2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
score_intoobject | null2 fields
variablestringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.weightnumber
library_idstring | nullThe library item it was copied from (surveys_library_list): rounds and trends compare by it.
Pattern
^lib\.[a-z]+\.[a-z]+$.driverstring | nullThe engagement driver it measures (engagement, recognition, growth, manager, workload, autonomy, belonging, purpose, communication, wellbeing, fairness).
Pattern
^[a-z_]{2,30}$.
randomize_questionsbooleanjumpsobject[]Up to 20 items.
2 fields
whenobjectrequired2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
tostring | "end"required
variablesobject[]requiredUp to 20 items.
3 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.namestringrequiredUp to 80 characters.
initialnumber
outcomesobject[]requiredUp to 20 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.titlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
whenobjectrequired2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
5 fields
qstringPattern
^[A-Za-z0-9_-]{1,40}$.vstringPattern
^[A-Za-z0-9_-]{1,40}$.f"team" | "location" | "entity" | "language"opstring (enum)requiredOne of:
eq,neq,gt,gte,lt,lte,includes,excludes,answered,not_answered.valuestring | number | boolean | "null"
thresholdintegerrequiredcomment_thresholdintegerrequiredaudienceobjectrequired5 fields
everyonebooleanDefault
false.unit_idsstring[]1–64 characters. Up to 200 items.
location_idsstring[]1–64 characters. Up to 200 items.
entity_idsstring[]1–64 characters. Up to 50 items.
group_idsstring[]1–64 characters. Up to 50 items.
reminder_daysinteger[]requiredproblemsobject[]requiredWhat stops it from opening (empty: ready).
2 fields
atstringrequiredmessagestringrequired
lockedbooleanrequiredOpened once: the mode and questions are fixed; translations, reminders and the close date can still change.
manager_viewbooleanrequiredManagers see their own line's results in My workspace (above the threshold, never a sub-line that could be worked out).
recurrenceobject | nullrequiredThe series' schedule (on its first round).
2 fields
every"week" | "two_weeks" | "month" | "quarter" | "half_year" | "year"requiredopen_daysintegerFrom 1 to 60. Default
7.
anonymous_bands"team" | "location" | "tenure"[]requiredAnonymous surveys: the coarse bands kept with each answer.
fatigue_skippedintegerrequiredPeople left out at sending: they already had their surveys this month.
triggerobject | nullrequiredLifecycle: sent to each person in the audience at a moment of their working life (start, exit, move, return), from the day it opens.
2 fields
kind"start" | "exit" | "move" | "return"requiredstart: days after the first day; exit: days before the last day (only once the person was told, while they still have access); move: days after a change of team, location, title or manager; return: days after coming back from a leave of at least 28 days.
daysintegerrequiredFrom 0 to 365.
slackbooleanrequiredInvitations and reminders also go as Slack direct messages where the company connected Slack.
retention_monthsintegerrequiredAnswers are deleted this many months after it closes; the group results are kept.
purged_atstring | nullrequiredWhen its answers were deleted (retention); results then come from the kept group results.
publicobject | nullrequiredIts public link (surveys_public_set); null: never set.
10 fields
onbooleanrequiredidstringrequiredrespondent"anonymous" | "named"requiredmax_answersintegerrequiredone_per_browserbooleanrequiredkioskbooleanrequiredembed_domainsstring[]requiredansweredintegerrequiredswitched_off_by_bizisybooleanrequiredreportsintegerrequired
councilobjectrequiredThe works council's approval (when the company asks for it, surveys_settings_get council_approval).
3 fields
status"not_asked" | "waiting" | "approved" | "returned"requiredapproved_for_this_versionbooleanrequiredentriesobject[]required4 fields
kind"asked" | "approved" | "returned" | "comment"requiredbystringrequiredtextstring | nullrequiredatstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/surveys.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"survey_id": "s1",
"definition": {
"language": "en",
"languages": [
"pt-PT"
],
"translations": {
"pt-PT": {
"q:q1:title": "Recomendaria a empresa?"
}
},
"cover": {
"show": true,
"title": "Team pulse",
"body": "Five questions, two minutes."
},
"thanks": {
"title": "Thank you!",
"body": null,
"link_url": null,
"link_label": null,
"redirect_url": null
},
"layout": "one",
"progress": true,
"logo": true,
"pages": [
{
"id": "p1",
"title": null,
"description": null,
"questions": [
{
"id": "q1",
"type": "nps",
"title": "How likely are you to recommend us as a place to work?",
"required": true,
"low_label": "Not at all",
"high_label": "Very likely"
},
{
"id": "q2",
"type": "single",
"title": "Lunch, {{person:first_name}}?",
"choices": [
{
"id": "c1",
"label": "Fish",
"quota": 20
},
{
"id": "c2",
"label": "Veg"
}
],
"other": true
},
{
"id": "q3",
"type": "long_text",
"title": "What would you change?",
"show_if": {
"match": "all",
"rules": [
{
"q": "q1",
"op": "lte",
"value": 6
}
]
}
}
],
"jumps": []
}
],
"variables": [],
"outcomes": []
},
"threshold": 6,
"comment_threshold": 10,
"audience": {
"everyone": false,
"unit_ids": [
"u1"
],
"location_ids": [],
"entity_ids": [],
"group_ids": []
},
"reminder_days": [
3
],
"close_at": null
}'const res = await fetch('https://api.bizisy.com/v1/surveys/surveys.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"survey_id": "s1",
"definition": {
"language": "en",
"languages": [
"pt-PT"
],
"translations": {
"pt-PT": {
"q:q1:title": "Recomendaria a empresa?"
}
},
"cover": {
"show": true,
"title": "Team pulse",
"body": "Five questions, two minutes."
},
"thanks": {
"title": "Thank you!",
"body": null,
"link_url": null,
"link_label": null,
"redirect_url": null
},
"layout": "one",
"progress": true,
"logo": true,
"pages": [
{
"id": "p1",
"title": null,
"description": null,
"questions": [
{
"id": "q1",
"type": "nps",
"title": "How likely are you to recommend us as a place to work?",
"required": true,
"low_label": "Not at all",
"high_label": "Very likely"
},
{
"id": "q2",
"type": "single",
"title": "Lunch, {{person:first_name}}?",
"choices": [
{
"id": "c1",
"label": "Fish",
"quota": 20
},
{
"id": "c2",
"label": "Veg"
}
],
"other": true
},
{
"id": "q3",
"type": "long_text",
"title": "What would you change?",
"show_if": {
"match": "all",
"rules": [
{
"q": "q1",
"op": "lte",
"value": 6
}
]
}
}
],
"jumps": []
}
],
"variables": [],
"outcomes": []
},
"threshold": 6,
"comment_threshold": 10,
"audience": {
"everyone": false,
"unit_ids": [
"u1"
],
"location_ids": [],
"entity_ids": [],
"group_ids": []
},
"reminder_days": [
3
],
"close_at": 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/surveys/surveys.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"survey_id": "s1",
"definition": {
"language": "en",
"languages": [
"pt-PT",
],
"translations": {
"pt-PT": {
"q:q1:title": "Recomendaria a empresa?",
},
},
"cover": {
"show": True,
"title": "Team pulse",
"body": "Five questions, two minutes.",
},
"thanks": {
"title": "Thank you!",
"body": None,
"link_url": None,
"link_label": None,
"redirect_url": None,
},
"layout": "one",
"progress": True,
"logo": True,
"pages": [
{
"id": "p1",
"title": None,
"description": None,
"questions": [
{
"id": "q1",
"type": "nps",
"title": "How likely are you to recommend us as a place to work?",
"required": True,
"low_label": "Not at all",
"high_label": "Very likely",
},
{
"id": "q2",
"type": "single",
"title": "Lunch, {{person:first_name}}?",
"choices": [
{
"id": "c1",
"label": "Fish",
"quota": 20,
},
{
"id": "c2",
"label": "Veg",
},
],
"other": True,
},
{
"id": "q3",
"type": "long_text",
"title": "What would you change?",
"show_if": {
"match": "all",
"rules": [
{
"q": "q1",
"op": "lte",
"value": 6,
},
],
},
},
],
"jumps": [],
},
],
"variables": [],
"outcomes": [],
},
"threshold": 6,
"comment_threshold": 10,
"audience": {
"everyone": False,
"unit_ids": [
"u1",
],
"location_ids": [],
"entity_ids": [],
"group_ids": [],
},
"reminder_days": [
3,
],
"close_at": None,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "s1",
"title": "Team pulse",
"mode": "confidential",
"status": "open",
"archived": false,
"questions": 3,
"language": "en",
"languages": [
"pt-PT"
],
"recipients": 24,
"answered": 12,
"answered_under": null,
"open_at": "2026-11-13T09:00:00.000Z",
"opened_at": "2026-11-13T09:00:00.000Z",
"close_at": null,
"closed_at": null,
"created_at": "2026-11-12T10:00:00.000Z",
"updated_at": "2026-11-13T10:00:00.000Z",
"kind": "listening",
"series_id": "s1",
"round_no": 2,
"recurring": true,
"definition": {
"language": "en",
"languages": [
"pt-PT"
],
"translations": {
"pt-PT": {
"q:q1:title": "Recomendaria a empresa?"
}
},
"cover": {
"show": true,
"title": "Team pulse",
"body": "Five questions, two minutes."
},
"thanks": {
"title": "Thank you!",
"body": null,
"link_url": null,
"link_label": null,
"redirect_url": null
},
"layout": "one",
"progress": true,
"logo": true,
"pages": [
{
"id": "p1",
"title": null,
"description": null,
"questions": [
{
"id": "q1",
"type": "nps",
"title": "How likely are you to recommend us as a place to work?",
"required": true,
"low_label": "Not at all",
"high_label": "Very likely"
},
{
"id": "q2",
"type": "single",
"title": "Lunch, {{person:first_name}}?",
"choices": [
{
"id": "c1",
"label": "Fish",
"quota": 20
},
{
"id": "c2",
"label": "Veg"
}
],
"other": true
},
{
"id": "q3",
"type": "long_text",
"title": "What would you change?",
"show_if": {
"match": "all",
"rules": [
{
"q": "q1",
"op": "lte",
"value": 6
}
]
}
}
],
"jumps": []
}
],
"variables": [],
"outcomes": []
},
"threshold": 6,
"comment_threshold": 10,
"audience": {
"everyone": true,
"unit_ids": [],
"location_ids": [],
"entity_ids": [],
"group_ids": []
},
"reminder_days": [
3,
6
],
"problems": [],
"locked": true,
"manager_view": true,
"recurrence": {
"every": "quarter",
"open_days": 10
},
"anonymous_bands": [],
"fatigue_skipped": 2,
"trigger": null,
"slack": false,
"retention_months": 24,
"purged_at": null,
"council": {
"status": "approved",
"approved_for_this_version": true,
"entries": [
{
"kind": "approved",
"by": "Rita Conselho",
"text": null,
"at": "2026-11-12T15:00:00.000Z"
}
]
},
"public": null
}
}Duplicate a survey#
POST/v1/surveys/surveys.duplicateWrite
A new draft with the same questions, translations, mode, thresholds, audience and reminders (never the answers). To send a survey again, or to change one that has opened. Supports dry_run. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_surveys_duplicateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
survey_idstringrequired1–64 characters.
titlestring1–160 characters.
Returns
38 fields
idstringrequiredtitlestringrequiredmode"named" | "confidential" | "anonymous"requiredstatus"draft" | "scheduled" | "open" | "closed"requiredarchivedbooleanrequiredquestionsintegerrequiredlanguagestringrequiredlanguagesstring[]requiredrecipientsintegerrequiredansweredinteger | nullrequirednull while fewer than the threshold answered a confidential survey (see answered_under).
answered_underinteger | nullrequiredConfidential: "under N" when fewer than N answered.
open_atstring | nullrequiredopened_atstring | nullrequiredclose_atstring | nullrequiredclosed_atstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredkind"custom" | "listening"requiredseries_idstring | nullrequiredRecurring surveys: the series (its first round's id); null for a one-off.
round_nointegerrequiredWhich round of its series (1 for a one-off).
recurringbooleanrequiredThe series still sends new rounds (stop it with surveys_series_stop).
definitionobjectrequiredThe survey: pages of questions (types: single, multi, dropdown, nps 0–10, likert 5/7, star, emoji, slider, ranking, matrix, short_text, long_text, number, date, yes_no, people (named surveys only), location, statement, consent), show_if conditions, jumps after a page (to a later page or "end"), piping in texts and choices ({{answer:<question id>}}, {{person:first_name|team|location}}, {{var:<variable id>}}), variables fed by score_into, outcomes shown at the end, translations per language keyed like "q:<question id>:title" or "c:<question id>:<choice id>".
12 fields
languagestringrequiredPattern
^[a-z]{2}(-[A-Z]{2})?$.languagesstring[]requiredUp to 10 items. Pattern
^[a-z]{2}(-[A-Z]{2})?$.translationsobjectrequiredcoverobjectrequired3 fields
showbooleanrequiredtitlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
thanksobjectrequired5 fields
titlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
link_urlstring | nullUp to 500 characters. Pattern
^https:\/\/[^\s]+$.link_labelstring | nullUp to 80 characters.
redirect_urlstring | nullUp to 500 characters. Pattern
^https:\/\/[^\s]+$.
layout"one" | "page"requiredprogressbooleanrequiredlogobooleanrequiredthemeobjectHow the answering screen looks (the Design tab).
7 fields
palettestring (enum)company (Settings → Appearance) or one of the palettes.
One of:
company,emerald,violet,indigo,ocean,amber,rose,graphite,terracotta.surface"plain" | "soft" | "tinted" | "dark"The page behind the questions: plain, soft, tinted or dark.
font"default" | "friendly" | "display" | "serif"buttons"rounded" | "pill" | "square"imagestring | nullA background image id from surveys_design_image_upload.
Pattern
^[0-9a-z]{26}$.image_dimintegerHow much the image is veiled under the text, 45–85 (%; default 65): the text stays readable.
From 45 to 85.
brandingboolean"Powered by Bizisy" at the bottom (default true).
pagesobject[]required1–50 items.
6 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.titlestring | nullUp to 300 characters.
descriptionstring | nullUp to 2000 characters.
questionsobject[]requiredUp to 200 items.
22 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.typestring (enum)requiredOne of:
single,multi,dropdown,nps,likert,star,emoji,slider,ranking,matrix,short_text,long_text,number,date,yes_no,people,location,statement,consent.titlestringrequiredUp to 1000 characters.
descriptionstring | nullUp to 2000 characters.
requiredbooleanrequired_messagestring | nullUp to 200 characters.
choicesobject[]Up to 100 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.labelstringrequiredUp to 500 characters.
scorenumber | nullquotainteger | nullFrom 1 to 100000.
otherbooleanrandomizebooleanmax_picksinteger | nullFrom 1 to 100.
points5 | 7minnumber | nullmaxnumber | nullstepnumber | nullAt least 0.
low_labelstring | nullUp to 80 characters.
high_labelstring | nullUp to 80 characters.
rowsobject[]Up to 100 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.labelstringrequiredUp to 500 characters.
scorenumber | nullquotainteger | nullFrom 1 to 100000.
max_lengthinteger | nullFrom 1 to 5000.
show_ifobject | null2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
score_intoobject | null2 fields
variablestringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.weightnumber
library_idstring | nullThe library item it was copied from (surveys_library_list): rounds and trends compare by it.
Pattern
^lib\.[a-z]+\.[a-z]+$.driverstring | nullThe engagement driver it measures (engagement, recognition, growth, manager, workload, autonomy, belonging, purpose, communication, wellbeing, fairness).
Pattern
^[a-z_]{2,30}$.
randomize_questionsbooleanjumpsobject[]Up to 20 items.
2 fields
whenobjectrequired2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
tostring | "end"required
variablesobject[]requiredUp to 20 items.
3 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.namestringrequiredUp to 80 characters.
initialnumber
outcomesobject[]requiredUp to 20 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.titlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
whenobjectrequired2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
5 fields
qstringPattern
^[A-Za-z0-9_-]{1,40}$.vstringPattern
^[A-Za-z0-9_-]{1,40}$.f"team" | "location" | "entity" | "language"opstring (enum)requiredOne of:
eq,neq,gt,gte,lt,lte,includes,excludes,answered,not_answered.valuestring | number | boolean | "null"
thresholdintegerrequiredcomment_thresholdintegerrequiredaudienceobjectrequired5 fields
everyonebooleanDefault
false.unit_idsstring[]1–64 characters. Up to 200 items.
location_idsstring[]1–64 characters. Up to 200 items.
entity_idsstring[]1–64 characters. Up to 50 items.
group_idsstring[]1–64 characters. Up to 50 items.
reminder_daysinteger[]requiredproblemsobject[]requiredWhat stops it from opening (empty: ready).
2 fields
atstringrequiredmessagestringrequired
lockedbooleanrequiredOpened once: the mode and questions are fixed; translations, reminders and the close date can still change.
manager_viewbooleanrequiredManagers see their own line's results in My workspace (above the threshold, never a sub-line that could be worked out).
recurrenceobject | nullrequiredThe series' schedule (on its first round).
2 fields
every"week" | "two_weeks" | "month" | "quarter" | "half_year" | "year"requiredopen_daysintegerFrom 1 to 60. Default
7.
anonymous_bands"team" | "location" | "tenure"[]requiredAnonymous surveys: the coarse bands kept with each answer.
fatigue_skippedintegerrequiredPeople left out at sending: they already had their surveys this month.
triggerobject | nullrequiredLifecycle: sent to each person in the audience at a moment of their working life (start, exit, move, return), from the day it opens.
2 fields
kind"start" | "exit" | "move" | "return"requiredstart: days after the first day; exit: days before the last day (only once the person was told, while they still have access); move: days after a change of team, location, title or manager; return: days after coming back from a leave of at least 28 days.
daysintegerrequiredFrom 0 to 365.
slackbooleanrequiredInvitations and reminders also go as Slack direct messages where the company connected Slack.
retention_monthsintegerrequiredAnswers are deleted this many months after it closes; the group results are kept.
purged_atstring | nullrequiredWhen its answers were deleted (retention); results then come from the kept group results.
publicobject | nullrequiredIts public link (surveys_public_set); null: never set.
10 fields
onbooleanrequiredidstringrequiredrespondent"anonymous" | "named"requiredmax_answersintegerrequiredone_per_browserbooleanrequiredkioskbooleanrequiredembed_domainsstring[]requiredansweredintegerrequiredswitched_off_by_bizisybooleanrequiredreportsintegerrequired
councilobjectrequiredThe works council's approval (when the company asks for it, surveys_settings_get council_approval).
3 fields
status"not_asked" | "waiting" | "approved" | "returned"requiredapproved_for_this_versionbooleanrequiredentriesobject[]required4 fields
kind"asked" | "approved" | "returned" | "comment"requiredbystringrequiredtextstring | nullrequiredatstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/surveys.duplicate \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"survey_id":"s1"}'const res = await fetch('https://api.bizisy.com/v1/surveys/surveys.duplicate', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"survey_id": "s1"
}),
});
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/surveys/surveys.duplicate",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"survey_id": "s1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "s2",
"title": "Team pulse",
"mode": "confidential",
"status": "draft",
"archived": false,
"questions": 3,
"language": "en",
"languages": [
"pt-PT"
],
"recipients": 0,
"answered": 0,
"answered_under": null,
"open_at": null,
"opened_at": null,
"close_at": "2026-11-27T18:00:00.000Z",
"closed_at": null,
"created_at": "2026-11-12T10:00:00.000Z",
"updated_at": "2026-11-13T10:00:00.000Z",
"kind": "listening",
"series_id": "s1",
"round_no": 2,
"recurring": true,
"definition": {
"language": "en",
"languages": [
"pt-PT"
],
"translations": {
"pt-PT": {
"q:q1:title": "Recomendaria a empresa?"
}
},
"cover": {
"show": true,
"title": "Team pulse",
"body": "Five questions, two minutes."
},
"thanks": {
"title": "Thank you!",
"body": null,
"link_url": null,
"link_label": null,
"redirect_url": null
},
"layout": "one",
"progress": true,
"logo": true,
"pages": [
{
"id": "p1",
"title": null,
"description": null,
"questions": [
{
"id": "q1",
"type": "nps",
"title": "How likely are you to recommend us as a place to work?",
"required": true,
"low_label": "Not at all",
"high_label": "Very likely"
},
{
"id": "q2",
"type": "single",
"title": "Lunch, {{person:first_name}}?",
"choices": [
{
"id": "c1",
"label": "Fish",
"quota": 20
},
{
"id": "c2",
"label": "Veg"
}
],
"other": true
},
{
"id": "q3",
"type": "long_text",
"title": "What would you change?",
"show_if": {
"match": "all",
"rules": [
{
"q": "q1",
"op": "lte",
"value": 6
}
]
}
}
],
"jumps": []
}
],
"variables": [],
"outcomes": []
},
"threshold": 5,
"comment_threshold": 10,
"audience": {
"everyone": true,
"unit_ids": [],
"location_ids": [],
"entity_ids": [],
"group_ids": []
},
"reminder_days": [
3,
6
],
"problems": [],
"locked": false,
"manager_view": true,
"recurrence": {
"every": "quarter",
"open_days": 10
},
"anonymous_bands": [],
"fatigue_skipped": 2,
"trigger": null,
"slack": false,
"retention_months": 24,
"purged_at": null,
"council": {
"status": "approved",
"approved_for_this_version": true,
"entries": [
{
"kind": "approved",
"by": "Rita Conselho",
"text": null,
"at": "2026-11-12T15:00:00.000Z"
}
]
},
"public": null
}
}Count a survey audience#
POST/v1/surveys/audience.countRead
How many people an audience reaches today (people working now in the chosen teams with their sub-teams, locations, legal entities or saved groups; everyone: all of them), and how many of them already got the company's monthly number of surveys (the fatigue guard leaves them out). What surveys_surveys_open would send to. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_audience_counton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
audienceobjectrequired5 fields
everyonebooleanDefault
false.unit_idsstring[]1–64 characters. Up to 200 items.
location_idsstring[]1–64 characters. Up to 200 items.
entity_idsstring[]1–64 characters. Up to 50 items.
group_idsstring[]1–64 characters. Up to 50 items.
Returns
peopleintegerrequiredat_capintegerrequiredOf them, people who already got the company's monthly number of surveys: left out unless ignore_fatigue.
max_per_monthintegerrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/audience.count \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"audience": {
"everyone": true,
"unit_ids": [],
"location_ids": [],
"entity_ids": [],
"group_ids": []
}
}'const res = await fetch('https://api.bizisy.com/v1/surveys/audience.count', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"audience": {
"everyone": true,
"unit_ids": [],
"location_ids": [],
"entity_ids": [],
"group_ids": []
}
}),
});
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/surveys/audience.count",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"audience": {
"everyone": True,
"unit_ids": [],
"location_ids": [],
"entity_ids": [],
"group_ids": [],
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"people": 24,
"at_cap": 3,
"max_per_month": 2
}
}Send a survey#
POST/v1/surveys/surveys.openWrite
Sends a draft survey to its audience: now (no open_at, or a time already past) or at open_at (scheduled; the hourly sweep opens it, and surveys_surveys_close cancels the schedule). recurrence makes it a series: a new round every week, two weeks, month, quarter, half year or year, each open for open_days (default 7), with trends across rounds; stop it with surveys_series_stop. Fatigue guard: people who already got the company's monthly number of surveys (Settings, default 2) are left out unless ignore_fatigue. Each person gets it in My workspace → Surveys, an in-app notice and push, and an email unless the company switched survey emails off (held outside working time by the right to disconnect). close_at closes it by itself (default: never). Refused while surveys_surveys_get lists problems or nobody is in the audience. From then on the mode and questions are fixed. Supports dry_run (says how many it would reach). Owners, admins and HR, in the app or by API.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_surveys_openon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
survey_idstringrequired1–64 characters.
open_atdate-timeAn ISO date and time, e.g. 2026-12-01T09:00:00Z.
ISO 8601 date and time (UTC).
close_atdate-time | nullAn ISO date and time, e.g. 2026-12-01T09:00:00Z.
ISO 8601 date and time (UTC).
recurrenceobject | null2 fields
every"week" | "two_weeks" | "month" | "quarter" | "half_year" | "year"requiredopen_daysintegerFrom 1 to 60. Default
7.
ignore_fatigueboolean
Returns
38 fields
idstringrequiredtitlestringrequiredmode"named" | "confidential" | "anonymous"requiredstatus"draft" | "scheduled" | "open" | "closed"requiredarchivedbooleanrequiredquestionsintegerrequiredlanguagestringrequiredlanguagesstring[]requiredrecipientsintegerrequiredansweredinteger | nullrequirednull while fewer than the threshold answered a confidential survey (see answered_under).
answered_underinteger | nullrequiredConfidential: "under N" when fewer than N answered.
open_atstring | nullrequiredopened_atstring | nullrequiredclose_atstring | nullrequiredclosed_atstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredkind"custom" | "listening"requiredseries_idstring | nullrequiredRecurring surveys: the series (its first round's id); null for a one-off.
round_nointegerrequiredWhich round of its series (1 for a one-off).
recurringbooleanrequiredThe series still sends new rounds (stop it with surveys_series_stop).
definitionobjectrequiredThe survey: pages of questions (types: single, multi, dropdown, nps 0–10, likert 5/7, star, emoji, slider, ranking, matrix, short_text, long_text, number, date, yes_no, people (named surveys only), location, statement, consent), show_if conditions, jumps after a page (to a later page or "end"), piping in texts and choices ({{answer:<question id>}}, {{person:first_name|team|location}}, {{var:<variable id>}}), variables fed by score_into, outcomes shown at the end, translations per language keyed like "q:<question id>:title" or "c:<question id>:<choice id>".
12 fields
languagestringrequiredPattern
^[a-z]{2}(-[A-Z]{2})?$.languagesstring[]requiredUp to 10 items. Pattern
^[a-z]{2}(-[A-Z]{2})?$.translationsobjectrequiredcoverobjectrequired3 fields
showbooleanrequiredtitlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
thanksobjectrequired5 fields
titlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
link_urlstring | nullUp to 500 characters. Pattern
^https:\/\/[^\s]+$.link_labelstring | nullUp to 80 characters.
redirect_urlstring | nullUp to 500 characters. Pattern
^https:\/\/[^\s]+$.
layout"one" | "page"requiredprogressbooleanrequiredlogobooleanrequiredthemeobjectHow the answering screen looks (the Design tab).
7 fields
palettestring (enum)company (Settings → Appearance) or one of the palettes.
One of:
company,emerald,violet,indigo,ocean,amber,rose,graphite,terracotta.surface"plain" | "soft" | "tinted" | "dark"The page behind the questions: plain, soft, tinted or dark.
font"default" | "friendly" | "display" | "serif"buttons"rounded" | "pill" | "square"imagestring | nullA background image id from surveys_design_image_upload.
Pattern
^[0-9a-z]{26}$.image_dimintegerHow much the image is veiled under the text, 45–85 (%; default 65): the text stays readable.
From 45 to 85.
brandingboolean"Powered by Bizisy" at the bottom (default true).
pagesobject[]required1–50 items.
6 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.titlestring | nullUp to 300 characters.
descriptionstring | nullUp to 2000 characters.
questionsobject[]requiredUp to 200 items.
22 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.typestring (enum)requiredOne of:
single,multi,dropdown,nps,likert,star,emoji,slider,ranking,matrix,short_text,long_text,number,date,yes_no,people,location,statement,consent.titlestringrequiredUp to 1000 characters.
descriptionstring | nullUp to 2000 characters.
requiredbooleanrequired_messagestring | nullUp to 200 characters.
choicesobject[]Up to 100 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.labelstringrequiredUp to 500 characters.
scorenumber | nullquotainteger | nullFrom 1 to 100000.
otherbooleanrandomizebooleanmax_picksinteger | nullFrom 1 to 100.
points5 | 7minnumber | nullmaxnumber | nullstepnumber | nullAt least 0.
low_labelstring | nullUp to 80 characters.
high_labelstring | nullUp to 80 characters.
rowsobject[]Up to 100 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.labelstringrequiredUp to 500 characters.
scorenumber | nullquotainteger | nullFrom 1 to 100000.
max_lengthinteger | nullFrom 1 to 5000.
show_ifobject | null2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
score_intoobject | null2 fields
variablestringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.weightnumber
library_idstring | nullThe library item it was copied from (surveys_library_list): rounds and trends compare by it.
Pattern
^lib\.[a-z]+\.[a-z]+$.driverstring | nullThe engagement driver it measures (engagement, recognition, growth, manager, workload, autonomy, belonging, purpose, communication, wellbeing, fairness).
Pattern
^[a-z_]{2,30}$.
randomize_questionsbooleanjumpsobject[]Up to 20 items.
2 fields
whenobjectrequired2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
tostring | "end"required
variablesobject[]requiredUp to 20 items.
3 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.namestringrequiredUp to 80 characters.
initialnumber
outcomesobject[]requiredUp to 20 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.titlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
whenobjectrequired2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
5 fields
qstringPattern
^[A-Za-z0-9_-]{1,40}$.vstringPattern
^[A-Za-z0-9_-]{1,40}$.f"team" | "location" | "entity" | "language"opstring (enum)requiredOne of:
eq,neq,gt,gte,lt,lte,includes,excludes,answered,not_answered.valuestring | number | boolean | "null"
thresholdintegerrequiredcomment_thresholdintegerrequiredaudienceobjectrequired5 fields
everyonebooleanDefault
false.unit_idsstring[]1–64 characters. Up to 200 items.
location_idsstring[]1–64 characters. Up to 200 items.
entity_idsstring[]1–64 characters. Up to 50 items.
group_idsstring[]1–64 characters. Up to 50 items.
reminder_daysinteger[]requiredproblemsobject[]requiredWhat stops it from opening (empty: ready).
2 fields
atstringrequiredmessagestringrequired
lockedbooleanrequiredOpened once: the mode and questions are fixed; translations, reminders and the close date can still change.
manager_viewbooleanrequiredManagers see their own line's results in My workspace (above the threshold, never a sub-line that could be worked out).
recurrenceobject | nullrequiredThe series' schedule (on its first round).
2 fields
every"week" | "two_weeks" | "month" | "quarter" | "half_year" | "year"requiredopen_daysintegerFrom 1 to 60. Default
7.
anonymous_bands"team" | "location" | "tenure"[]requiredAnonymous surveys: the coarse bands kept with each answer.
fatigue_skippedintegerrequiredPeople left out at sending: they already had their surveys this month.
triggerobject | nullrequiredLifecycle: sent to each person in the audience at a moment of their working life (start, exit, move, return), from the day it opens.
2 fields
kind"start" | "exit" | "move" | "return"requiredstart: days after the first day; exit: days before the last day (only once the person was told, while they still have access); move: days after a change of team, location, title or manager; return: days after coming back from a leave of at least 28 days.
daysintegerrequiredFrom 0 to 365.
slackbooleanrequiredInvitations and reminders also go as Slack direct messages where the company connected Slack.
retention_monthsintegerrequiredAnswers are deleted this many months after it closes; the group results are kept.
purged_atstring | nullrequiredWhen its answers were deleted (retention); results then come from the kept group results.
publicobject | nullrequiredIts public link (surveys_public_set); null: never set.
10 fields
onbooleanrequiredidstringrequiredrespondent"anonymous" | "named"requiredmax_answersintegerrequiredone_per_browserbooleanrequiredkioskbooleanrequiredembed_domainsstring[]requiredansweredintegerrequiredswitched_off_by_bizisybooleanrequiredreportsintegerrequired
councilobjectrequiredThe works council's approval (when the company asks for it, surveys_settings_get council_approval).
3 fields
status"not_asked" | "waiting" | "approved" | "returned"requiredapproved_for_this_versionbooleanrequiredentriesobject[]required4 fields
kind"asked" | "approved" | "returned" | "comment"requiredbystringrequiredtextstring | nullrequiredatstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/surveys.open \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"survey_id": "s1",
"open_at": "2026-12-01T09:00:00Z",
"close_at": "2026-12-15T18:00:00Z"
}'const res = await fetch('https://api.bizisy.com/v1/surveys/surveys.open', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"survey_id": "s1",
"open_at": "2026-12-01T09:00:00Z",
"close_at": "2026-12-15T18:00:00Z"
}),
});
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/surveys/surveys.open",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"survey_id": "s1",
"open_at": "2026-12-01T09:00:00Z",
"close_at": "2026-12-15T18:00:00Z",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "s1",
"title": "Team pulse",
"mode": "confidential",
"status": "open",
"archived": false,
"questions": 3,
"language": "en",
"languages": [
"pt-PT"
],
"recipients": 24,
"answered": 12,
"answered_under": null,
"open_at": "2026-12-01T09:00:00Z",
"opened_at": "2026-11-13T09:00:00.000Z",
"close_at": "2026-12-15T18:00:00Z",
"closed_at": null,
"created_at": "2026-11-12T10:00:00.000Z",
"updated_at": "2026-11-13T10:00:00.000Z",
"kind": "listening",
"series_id": "s1",
"round_no": 2,
"recurring": true,
"definition": {
"language": "en",
"languages": [
"pt-PT"
],
"translations": {
"pt-PT": {
"q:q1:title": "Recomendaria a empresa?"
}
},
"cover": {
"show": true,
"title": "Team pulse",
"body": "Five questions, two minutes."
},
"thanks": {
"title": "Thank you!",
"body": null,
"link_url": null,
"link_label": null,
"redirect_url": null
},
"layout": "one",
"progress": true,
"logo": true,
"pages": [
{
"id": "p1",
"title": null,
"description": null,
"questions": [
{
"id": "q1",
"type": "nps",
"title": "How likely are you to recommend us as a place to work?",
"required": true,
"low_label": "Not at all",
"high_label": "Very likely"
},
{
"id": "q2",
"type": "single",
"title": "Lunch, {{person:first_name}}?",
"choices": [
{
"id": "c1",
"label": "Fish",
"quota": 20
},
{
"id": "c2",
"label": "Veg"
}
],
"other": true
},
{
"id": "q3",
"type": "long_text",
"title": "What would you change?",
"show_if": {
"match": "all",
"rules": [
{
"q": "q1",
"op": "lte",
"value": 6
}
]
}
}
],
"jumps": []
}
],
"variables": [],
"outcomes": []
},
"threshold": 5,
"comment_threshold": 10,
"audience": {
"everyone": true,
"unit_ids": [],
"location_ids": [],
"entity_ids": [],
"group_ids": []
},
"reminder_days": [
3,
6
],
"problems": [],
"locked": true,
"manager_view": true,
"recurrence": {
"every": "quarter",
"open_days": 10
},
"anonymous_bands": [],
"fatigue_skipped": 2,
"trigger": null,
"slack": false,
"retention_months": 24,
"purged_at": null,
"council": {
"status": "approved",
"approved_for_this_version": true,
"entries": [
{
"kind": "approved",
"by": "Rita Conselho",
"text": null,
"at": "2026-11-12T15:00:00.000Z"
}
]
},
"public": null
}
}Close a survey#
POST/v1/surveys/surveys.closeWrite
Closes an open survey now: no more answers or reminders; results stay. On a scheduled survey it cancels the schedule (back to draft). Supports dry_run. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_surveys_closeon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
survey_idstringrequired1–64 characters.
Returns
38 fields
idstringrequiredtitlestringrequiredmode"named" | "confidential" | "anonymous"requiredstatus"draft" | "scheduled" | "open" | "closed"requiredarchivedbooleanrequiredquestionsintegerrequiredlanguagestringrequiredlanguagesstring[]requiredrecipientsintegerrequiredansweredinteger | nullrequirednull while fewer than the threshold answered a confidential survey (see answered_under).
answered_underinteger | nullrequiredConfidential: "under N" when fewer than N answered.
open_atstring | nullrequiredopened_atstring | nullrequiredclose_atstring | nullrequiredclosed_atstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredkind"custom" | "listening"requiredseries_idstring | nullrequiredRecurring surveys: the series (its first round's id); null for a one-off.
round_nointegerrequiredWhich round of its series (1 for a one-off).
recurringbooleanrequiredThe series still sends new rounds (stop it with surveys_series_stop).
definitionobjectrequiredThe survey: pages of questions (types: single, multi, dropdown, nps 0–10, likert 5/7, star, emoji, slider, ranking, matrix, short_text, long_text, number, date, yes_no, people (named surveys only), location, statement, consent), show_if conditions, jumps after a page (to a later page or "end"), piping in texts and choices ({{answer:<question id>}}, {{person:first_name|team|location}}, {{var:<variable id>}}), variables fed by score_into, outcomes shown at the end, translations per language keyed like "q:<question id>:title" or "c:<question id>:<choice id>".
12 fields
languagestringrequiredPattern
^[a-z]{2}(-[A-Z]{2})?$.languagesstring[]requiredUp to 10 items. Pattern
^[a-z]{2}(-[A-Z]{2})?$.translationsobjectrequiredcoverobjectrequired3 fields
showbooleanrequiredtitlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
thanksobjectrequired5 fields
titlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
link_urlstring | nullUp to 500 characters. Pattern
^https:\/\/[^\s]+$.link_labelstring | nullUp to 80 characters.
redirect_urlstring | nullUp to 500 characters. Pattern
^https:\/\/[^\s]+$.
layout"one" | "page"requiredprogressbooleanrequiredlogobooleanrequiredthemeobjectHow the answering screen looks (the Design tab).
7 fields
palettestring (enum)company (Settings → Appearance) or one of the palettes.
One of:
company,emerald,violet,indigo,ocean,amber,rose,graphite,terracotta.surface"plain" | "soft" | "tinted" | "dark"The page behind the questions: plain, soft, tinted or dark.
font"default" | "friendly" | "display" | "serif"buttons"rounded" | "pill" | "square"imagestring | nullA background image id from surveys_design_image_upload.
Pattern
^[0-9a-z]{26}$.image_dimintegerHow much the image is veiled under the text, 45–85 (%; default 65): the text stays readable.
From 45 to 85.
brandingboolean"Powered by Bizisy" at the bottom (default true).
pagesobject[]required1–50 items.
6 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.titlestring | nullUp to 300 characters.
descriptionstring | nullUp to 2000 characters.
questionsobject[]requiredUp to 200 items.
22 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.typestring (enum)requiredOne of:
single,multi,dropdown,nps,likert,star,emoji,slider,ranking,matrix,short_text,long_text,number,date,yes_no,people,location,statement,consent.titlestringrequiredUp to 1000 characters.
descriptionstring | nullUp to 2000 characters.
requiredbooleanrequired_messagestring | nullUp to 200 characters.
choicesobject[]Up to 100 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.labelstringrequiredUp to 500 characters.
scorenumber | nullquotainteger | nullFrom 1 to 100000.
otherbooleanrandomizebooleanmax_picksinteger | nullFrom 1 to 100.
points5 | 7minnumber | nullmaxnumber | nullstepnumber | nullAt least 0.
low_labelstring | nullUp to 80 characters.
high_labelstring | nullUp to 80 characters.
rowsobject[]Up to 100 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.labelstringrequiredUp to 500 characters.
scorenumber | nullquotainteger | nullFrom 1 to 100000.
max_lengthinteger | nullFrom 1 to 5000.
show_ifobject | null2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
score_intoobject | null2 fields
variablestringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.weightnumber
library_idstring | nullThe library item it was copied from (surveys_library_list): rounds and trends compare by it.
Pattern
^lib\.[a-z]+\.[a-z]+$.driverstring | nullThe engagement driver it measures (engagement, recognition, growth, manager, workload, autonomy, belonging, purpose, communication, wellbeing, fairness).
Pattern
^[a-z_]{2,30}$.
randomize_questionsbooleanjumpsobject[]Up to 20 items.
2 fields
whenobjectrequired2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
tostring | "end"required
variablesobject[]requiredUp to 20 items.
3 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.namestringrequiredUp to 80 characters.
initialnumber
outcomesobject[]requiredUp to 20 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.titlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
whenobjectrequired2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
5 fields
qstringPattern
^[A-Za-z0-9_-]{1,40}$.vstringPattern
^[A-Za-z0-9_-]{1,40}$.f"team" | "location" | "entity" | "language"opstring (enum)requiredOne of:
eq,neq,gt,gte,lt,lte,includes,excludes,answered,not_answered.valuestring | number | boolean | "null"
thresholdintegerrequiredcomment_thresholdintegerrequiredaudienceobjectrequired5 fields
everyonebooleanDefault
false.unit_idsstring[]1–64 characters. Up to 200 items.
location_idsstring[]1–64 characters. Up to 200 items.
entity_idsstring[]1–64 characters. Up to 50 items.
group_idsstring[]1–64 characters. Up to 50 items.
reminder_daysinteger[]requiredproblemsobject[]requiredWhat stops it from opening (empty: ready).
2 fields
atstringrequiredmessagestringrequired
lockedbooleanrequiredOpened once: the mode and questions are fixed; translations, reminders and the close date can still change.
manager_viewbooleanrequiredManagers see their own line's results in My workspace (above the threshold, never a sub-line that could be worked out).
recurrenceobject | nullrequiredThe series' schedule (on its first round).
2 fields
every"week" | "two_weeks" | "month" | "quarter" | "half_year" | "year"requiredopen_daysintegerFrom 1 to 60. Default
7.
anonymous_bands"team" | "location" | "tenure"[]requiredAnonymous surveys: the coarse bands kept with each answer.
fatigue_skippedintegerrequiredPeople left out at sending: they already had their surveys this month.
triggerobject | nullrequiredLifecycle: sent to each person in the audience at a moment of their working life (start, exit, move, return), from the day it opens.
2 fields
kind"start" | "exit" | "move" | "return"requiredstart: days after the first day; exit: days before the last day (only once the person was told, while they still have access); move: days after a change of team, location, title or manager; return: days after coming back from a leave of at least 28 days.
daysintegerrequiredFrom 0 to 365.
slackbooleanrequiredInvitations and reminders also go as Slack direct messages where the company connected Slack.
retention_monthsintegerrequiredAnswers are deleted this many months after it closes; the group results are kept.
purged_atstring | nullrequiredWhen its answers were deleted (retention); results then come from the kept group results.
publicobject | nullrequiredIts public link (surveys_public_set); null: never set.
10 fields
onbooleanrequiredidstringrequiredrespondent"anonymous" | "named"requiredmax_answersintegerrequiredone_per_browserbooleanrequiredkioskbooleanrequiredembed_domainsstring[]requiredansweredintegerrequiredswitched_off_by_bizisybooleanrequiredreportsintegerrequired
councilobjectrequiredThe works council's approval (when the company asks for it, surveys_settings_get council_approval).
3 fields
status"not_asked" | "waiting" | "approved" | "returned"requiredapproved_for_this_versionbooleanrequiredentriesobject[]required4 fields
kind"asked" | "approved" | "returned" | "comment"requiredbystringrequiredtextstring | nullrequiredatstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/surveys.close \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"survey_id":"s1"}'const res = await fetch('https://api.bizisy.com/v1/surveys/surveys.close', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"survey_id": "s1"
}),
});
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/surveys/surveys.close",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"survey_id": "s1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "s1",
"title": "Team pulse",
"mode": "confidential",
"status": "closed",
"archived": false,
"questions": 3,
"language": "en",
"languages": [
"pt-PT"
],
"recipients": 24,
"answered": 12,
"answered_under": null,
"open_at": "2026-11-13T09:00:00.000Z",
"opened_at": "2026-11-13T09:00:00.000Z",
"close_at": "2026-11-27T18:00:00.000Z",
"closed_at": "2026-11-20T10:00:00.000Z",
"created_at": "2026-11-12T10:00:00.000Z",
"updated_at": "2026-11-13T10:00:00.000Z",
"kind": "listening",
"series_id": "s1",
"round_no": 2,
"recurring": true,
"definition": {
"language": "en",
"languages": [
"pt-PT"
],
"translations": {
"pt-PT": {
"q:q1:title": "Recomendaria a empresa?"
}
},
"cover": {
"show": true,
"title": "Team pulse",
"body": "Five questions, two minutes."
},
"thanks": {
"title": "Thank you!",
"body": null,
"link_url": null,
"link_label": null,
"redirect_url": null
},
"layout": "one",
"progress": true,
"logo": true,
"pages": [
{
"id": "p1",
"title": null,
"description": null,
"questions": [
{
"id": "q1",
"type": "nps",
"title": "How likely are you to recommend us as a place to work?",
"required": true,
"low_label": "Not at all",
"high_label": "Very likely"
},
{
"id": "q2",
"type": "single",
"title": "Lunch, {{person:first_name}}?",
"choices": [
{
"id": "c1",
"label": "Fish",
"quota": 20
},
{
"id": "c2",
"label": "Veg"
}
],
"other": true
},
{
"id": "q3",
"type": "long_text",
"title": "What would you change?",
"show_if": {
"match": "all",
"rules": [
{
"q": "q1",
"op": "lte",
"value": 6
}
]
}
}
],
"jumps": []
}
],
"variables": [],
"outcomes": []
},
"threshold": 5,
"comment_threshold": 10,
"audience": {
"everyone": true,
"unit_ids": [],
"location_ids": [],
"entity_ids": [],
"group_ids": []
},
"reminder_days": [
3,
6
],
"problems": [],
"locked": true,
"manager_view": true,
"recurrence": {
"every": "quarter",
"open_days": 10
},
"anonymous_bands": [],
"fatigue_skipped": 2,
"trigger": null,
"slack": false,
"retention_months": 24,
"purged_at": null,
"council": {
"status": "approved",
"approved_for_this_version": true,
"entries": [
{
"kind": "approved",
"by": "Rita Conselho",
"text": null,
"at": "2026-11-12T15:00:00.000Z"
}
]
},
"public": null
}
}Archive a survey#
POST/v1/surveys/surveys.archiveWrite
Archives a draft or closed survey (archived false brings it back); its results stay. An open or scheduled one must be closed first. Supports dry_run. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_surveys_archiveon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
survey_idstringrequired1–64 characters.
archivedbooleanDefault
true.
Returns
38 fields
idstringrequiredtitlestringrequiredmode"named" | "confidential" | "anonymous"requiredstatus"draft" | "scheduled" | "open" | "closed"requiredarchivedbooleanrequiredquestionsintegerrequiredlanguagestringrequiredlanguagesstring[]requiredrecipientsintegerrequiredansweredinteger | nullrequirednull while fewer than the threshold answered a confidential survey (see answered_under).
answered_underinteger | nullrequiredConfidential: "under N" when fewer than N answered.
open_atstring | nullrequiredopened_atstring | nullrequiredclose_atstring | nullrequiredclosed_atstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredkind"custom" | "listening"requiredseries_idstring | nullrequiredRecurring surveys: the series (its first round's id); null for a one-off.
round_nointegerrequiredWhich round of its series (1 for a one-off).
recurringbooleanrequiredThe series still sends new rounds (stop it with surveys_series_stop).
definitionobjectrequiredThe survey: pages of questions (types: single, multi, dropdown, nps 0–10, likert 5/7, star, emoji, slider, ranking, matrix, short_text, long_text, number, date, yes_no, people (named surveys only), location, statement, consent), show_if conditions, jumps after a page (to a later page or "end"), piping in texts and choices ({{answer:<question id>}}, {{person:first_name|team|location}}, {{var:<variable id>}}), variables fed by score_into, outcomes shown at the end, translations per language keyed like "q:<question id>:title" or "c:<question id>:<choice id>".
12 fields
languagestringrequiredPattern
^[a-z]{2}(-[A-Z]{2})?$.languagesstring[]requiredUp to 10 items. Pattern
^[a-z]{2}(-[A-Z]{2})?$.translationsobjectrequiredcoverobjectrequired3 fields
showbooleanrequiredtitlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
thanksobjectrequired5 fields
titlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
link_urlstring | nullUp to 500 characters. Pattern
^https:\/\/[^\s]+$.link_labelstring | nullUp to 80 characters.
redirect_urlstring | nullUp to 500 characters. Pattern
^https:\/\/[^\s]+$.
layout"one" | "page"requiredprogressbooleanrequiredlogobooleanrequiredthemeobjectHow the answering screen looks (the Design tab).
7 fields
palettestring (enum)company (Settings → Appearance) or one of the palettes.
One of:
company,emerald,violet,indigo,ocean,amber,rose,graphite,terracotta.surface"plain" | "soft" | "tinted" | "dark"The page behind the questions: plain, soft, tinted or dark.
font"default" | "friendly" | "display" | "serif"buttons"rounded" | "pill" | "square"imagestring | nullA background image id from surveys_design_image_upload.
Pattern
^[0-9a-z]{26}$.image_dimintegerHow much the image is veiled under the text, 45–85 (%; default 65): the text stays readable.
From 45 to 85.
brandingboolean"Powered by Bizisy" at the bottom (default true).
pagesobject[]required1–50 items.
6 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.titlestring | nullUp to 300 characters.
descriptionstring | nullUp to 2000 characters.
questionsobject[]requiredUp to 200 items.
22 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.typestring (enum)requiredOne of:
single,multi,dropdown,nps,likert,star,emoji,slider,ranking,matrix,short_text,long_text,number,date,yes_no,people,location,statement,consent.titlestringrequiredUp to 1000 characters.
descriptionstring | nullUp to 2000 characters.
requiredbooleanrequired_messagestring | nullUp to 200 characters.
choicesobject[]Up to 100 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.labelstringrequiredUp to 500 characters.
scorenumber | nullquotainteger | nullFrom 1 to 100000.
otherbooleanrandomizebooleanmax_picksinteger | nullFrom 1 to 100.
points5 | 7minnumber | nullmaxnumber | nullstepnumber | nullAt least 0.
low_labelstring | nullUp to 80 characters.
high_labelstring | nullUp to 80 characters.
rowsobject[]Up to 100 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.labelstringrequiredUp to 500 characters.
scorenumber | nullquotainteger | nullFrom 1 to 100000.
max_lengthinteger | nullFrom 1 to 5000.
show_ifobject | null2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
score_intoobject | null2 fields
variablestringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.weightnumber
library_idstring | nullThe library item it was copied from (surveys_library_list): rounds and trends compare by it.
Pattern
^lib\.[a-z]+\.[a-z]+$.driverstring | nullThe engagement driver it measures (engagement, recognition, growth, manager, workload, autonomy, belonging, purpose, communication, wellbeing, fairness).
Pattern
^[a-z_]{2,30}$.
randomize_questionsbooleanjumpsobject[]Up to 20 items.
2 fields
whenobjectrequired2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
tostring | "end"required
variablesobject[]requiredUp to 20 items.
3 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.namestringrequiredUp to 80 characters.
initialnumber
outcomesobject[]requiredUp to 20 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.titlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
whenobjectrequired2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
5 fields
qstringPattern
^[A-Za-z0-9_-]{1,40}$.vstringPattern
^[A-Za-z0-9_-]{1,40}$.f"team" | "location" | "entity" | "language"opstring (enum)requiredOne of:
eq,neq,gt,gte,lt,lte,includes,excludes,answered,not_answered.valuestring | number | boolean | "null"
thresholdintegerrequiredcomment_thresholdintegerrequiredaudienceobjectrequired5 fields
everyonebooleanDefault
false.unit_idsstring[]1–64 characters. Up to 200 items.
location_idsstring[]1–64 characters. Up to 200 items.
entity_idsstring[]1–64 characters. Up to 50 items.
group_idsstring[]1–64 characters. Up to 50 items.
reminder_daysinteger[]requiredproblemsobject[]requiredWhat stops it from opening (empty: ready).
2 fields
atstringrequiredmessagestringrequired
lockedbooleanrequiredOpened once: the mode and questions are fixed; translations, reminders and the close date can still change.
manager_viewbooleanrequiredManagers see their own line's results in My workspace (above the threshold, never a sub-line that could be worked out).
recurrenceobject | nullrequiredThe series' schedule (on its first round).
2 fields
every"week" | "two_weeks" | "month" | "quarter" | "half_year" | "year"requiredopen_daysintegerFrom 1 to 60. Default
7.
anonymous_bands"team" | "location" | "tenure"[]requiredAnonymous surveys: the coarse bands kept with each answer.
fatigue_skippedintegerrequiredPeople left out at sending: they already had their surveys this month.
triggerobject | nullrequiredLifecycle: sent to each person in the audience at a moment of their working life (start, exit, move, return), from the day it opens.
2 fields
kind"start" | "exit" | "move" | "return"requiredstart: days after the first day; exit: days before the last day (only once the person was told, while they still have access); move: days after a change of team, location, title or manager; return: days after coming back from a leave of at least 28 days.
daysintegerrequiredFrom 0 to 365.
slackbooleanrequiredInvitations and reminders also go as Slack direct messages where the company connected Slack.
retention_monthsintegerrequiredAnswers are deleted this many months after it closes; the group results are kept.
purged_atstring | nullrequiredWhen its answers were deleted (retention); results then come from the kept group results.
publicobject | nullrequiredIts public link (surveys_public_set); null: never set.
10 fields
onbooleanrequiredidstringrequiredrespondent"anonymous" | "named"requiredmax_answersintegerrequiredone_per_browserbooleanrequiredkioskbooleanrequiredembed_domainsstring[]requiredansweredintegerrequiredswitched_off_by_bizisybooleanrequiredreportsintegerrequired
councilobjectrequiredThe works council's approval (when the company asks for it, surveys_settings_get council_approval).
3 fields
status"not_asked" | "waiting" | "approved" | "returned"requiredapproved_for_this_versionbooleanrequiredentriesobject[]required4 fields
kind"asked" | "approved" | "returned" | "comment"requiredbystringrequiredtextstring | nullrequiredatstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/surveys.archive \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"survey_id":"s1","archived":false}'const res = await fetch('https://api.bizisy.com/v1/surveys/surveys.archive', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"survey_id": "s1",
"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/surveys/surveys.archive",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"survey_id": "s1",
"archived": False,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "s1",
"title": "Team pulse",
"mode": "confidential",
"status": "closed",
"archived": false,
"questions": 3,
"language": "en",
"languages": [
"pt-PT"
],
"recipients": 24,
"answered": 12,
"answered_under": null,
"open_at": "2026-11-13T09:00:00.000Z",
"opened_at": "2026-11-13T09:00:00.000Z",
"close_at": "2026-11-27T18:00:00.000Z",
"closed_at": null,
"created_at": "2026-11-12T10:00:00.000Z",
"updated_at": "2026-11-13T10:00:00.000Z",
"kind": "listening",
"series_id": "s1",
"round_no": 2,
"recurring": true,
"definition": {
"language": "en",
"languages": [
"pt-PT"
],
"translations": {
"pt-PT": {
"q:q1:title": "Recomendaria a empresa?"
}
},
"cover": {
"show": true,
"title": "Team pulse",
"body": "Five questions, two minutes."
},
"thanks": {
"title": "Thank you!",
"body": null,
"link_url": null,
"link_label": null,
"redirect_url": null
},
"layout": "one",
"progress": true,
"logo": true,
"pages": [
{
"id": "p1",
"title": null,
"description": null,
"questions": [
{
"id": "q1",
"type": "nps",
"title": "How likely are you to recommend us as a place to work?",
"required": true,
"low_label": "Not at all",
"high_label": "Very likely"
},
{
"id": "q2",
"type": "single",
"title": "Lunch, {{person:first_name}}?",
"choices": [
{
"id": "c1",
"label": "Fish",
"quota": 20
},
{
"id": "c2",
"label": "Veg"
}
],
"other": true
},
{
"id": "q3",
"type": "long_text",
"title": "What would you change?",
"show_if": {
"match": "all",
"rules": [
{
"q": "q1",
"op": "lte",
"value": 6
}
]
}
}
],
"jumps": []
}
],
"variables": [],
"outcomes": []
},
"threshold": 5,
"comment_threshold": 10,
"audience": {
"everyone": true,
"unit_ids": [],
"location_ids": [],
"entity_ids": [],
"group_ids": []
},
"reminder_days": [
3,
6
],
"problems": [],
"locked": true,
"manager_view": true,
"recurrence": {
"every": "quarter",
"open_days": 10
},
"anonymous_bands": [],
"fatigue_skipped": 2,
"trigger": null,
"slack": false,
"retention_months": 24,
"purged_at": null,
"council": {
"status": "approved",
"approved_for_this_version": true,
"entries": [
{
"kind": "approved",
"by": "Rita Conselho",
"text": null,
"at": "2026-11-12T15:00:00.000Z"
}
]
},
"public": null
}
}Survey results#
POST/v1/surveys/results.getRead
A survey's results, live while it is open: response rate overall and by team (with sub-teams), location and legal entity, and per question the answer counts and shares, averages, eNPS for 0–10 questions, rankings and comments. segment narrows everything to one team, location or entity. Confidential surveys never show a group smaller than the threshold (hidden: true, "under N"), nor a group that subtracting others from its parent would reveal, and publish results in steps of the threshold (included: how many answers count so far) so one answer never moves them; comments only from the comment threshold up and masked (emails, phone numbers, names), the same for every reader, API keys and AI apps included. Only submitted answers count. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Groups under the survey's threshold are hidden, the same as in the app.
- MCP tool
surveys_results_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
survey_idstringrequired1–64 characters.
segmentobject2 fields
kindstring (enum)requiredOne of:
team,manager,location,entity,tenure,field,source.idstringrequired1–160 characters.
langstringLanguage of labels and headers (en, pt-PT, es-ES, de-DE, fr-FR, it-IT); the survey's texts in it when translated.
Pattern
^[a-z]{2}(-[A-Z]{2})?$.
Returns
14 fields
survey_idstringrequiredtitlestringrequiredmode"named" | "confidential" | "anonymous"requiredstatusstringrequiredthresholdintegerrequiredcomment_thresholdintegerrequiredsegmentobject | nullrequired3 fields
kindstring (enum)requiredOne of:
team,manager,location,entity,tenure,field,source.idstringrequired1–160 characters.
namestringrequired
respondentsinteger | nullrequiredSubmitted answers in this view (null when hidden).
hiddenbooleanrequiredtrue: the numbers are withheld (fewer people than the threshold, or the next-smallest rule).
underinteger | nullrequiredHidden because fewer than N answered: N. Hidden with under null: shown, it would let someone work out a smaller hidden group by subtraction.
includedinteger | nullrequiredHow many of those answers the results include. Confidential surveys publish in steps of the threshold (never moved by one answer); null when hidden.
rateobjectrequired6 fields
invitedintegerrequiredansweredinteger | nullrequiredratenumber | nullrequired0–1; null when hidden or nobody invited.
hiddenbooleanrequiredtrue: the numbers are withheld (fewer people than the threshold, or the next-smallest rule).
underinteger | nullrequiredHidden because fewer than N answered: N. Hidden with under null: shown, it would let someone work out a smaller hidden group by subtraction.
byobject[]required8 fields
invitedintegerrequiredansweredinteger | nullrequiredratenumber | nullrequired0–1; null when hidden or nobody invited.
hiddenbooleanrequiredtrue: the numbers are withheld (fewer people than the threshold, or the next-smallest rule).
underinteger | nullrequiredHidden because fewer than N answered: N. Hidden with under null: shown, it would let someone work out a smaller hidden group by subtraction.
kindstring (enum)requiredOne of:
team,manager,location,entity,tenure,field,source.idstringrequirednamestringrequired
questionsobject[]required18 fields
idstringrequiredtypestringrequiredtitlestringrequiredpageintegerrequiredninteger | nullrequiredHow many answered it (null when hidden).
hiddenbooleanrequiredtrue: the numbers are withheld (fewer people than the threshold, or the next-smallest rule).
underinteger | nullrequiredHidden because fewer than N answered: N. Hidden with under null: shown, it would let someone work out a smaller hidden group by subtraction.
optionsobject[] | nullrequiredChoices, scale points, yes/no, locations: count and share.
4 fields
idstringrequiredlabelstringrequiredcountintegerrequiredsharenumberrequired0–1 of those who answered the question.
rowsobject[] | nullrequiredMatrix: per row.
3 fields
idstringrequiredlabelstringrequiredoptionsobject[]required4 fields
idstringrequiredlabelstringrequiredcountintegerrequiredsharenumberrequired0–1 of those who answered the question.
rankingobject[] | nullrequired3 fields
idstringrequiredlabelstringrequiredaverage_ranknumberrequired
meannumber | nullrequiredminnumber | nullrequiredmaxnumber | nullrequiredenpsobject | nullrequired0–10 questions: eNPS = % promoters (9–10) − % detractors (0–6).
5 fields
scoreintegerrequiredpromotersintegerrequiredpassivesintegerrequireddetractorsintegerrequirednintegerrequired
commentsstring[] | nullrequiredFree-text answers (confidential: masked, in alphabetical order, only from the comment threshold up; null when hidden).
comments_hiddenbooleanrequiredcomments_underinteger | nullrequiredcomment_idsstring | null[] | nullEach comment's opaque id, in the same order (reply with surveys_comments_reply); null for comments sent before replies existed.
publicobject | nullIts public link: answers through it (filter them with the segment source:public; source:people for the company's own). Absent: no link.
1 field
answeredintegerrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/results.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"survey_id":"s1","segment":{"kind":"team","id":"u1"},"lang":"pt-PT"}'const res = await fetch('https://api.bizisy.com/v1/surveys/results.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"survey_id": "s1",
"segment": {
"kind": "team",
"id": "u1"
},
"lang": "pt-PT"
}),
});
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/surveys/results.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"survey_id": "s1",
"segment": {
"kind": "team",
"id": "u1",
},
"lang": "pt-PT",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"survey_id": "s1",
"title": "Team pulse",
"mode": "confidential",
"status": "open",
"threshold": 5,
"comment_threshold": 10,
"segment": null,
"respondents": 12,
"included": 10,
"hidden": false,
"under": null,
"rate": {
"invited": 24,
"answered": 12,
"rate": 0.5,
"hidden": false,
"under": null,
"by": [
{
"kind": "team",
"id": "u1",
"name": "Ops",
"invited": 14,
"answered": 9,
"rate": 0.6429,
"hidden": false,
"under": null
},
{
"kind": "team",
"id": "u2",
"name": "Sales",
"invited": 10,
"answered": null,
"rate": null,
"hidden": true,
"under": 5
}
]
},
"questions": [
{
"id": "q1",
"type": "nps",
"title": "How likely are you to recommend us as a place to work?",
"page": 1,
"n": 12,
"hidden": false,
"under": null,
"options": [
{
"id": "0",
"label": "0",
"count": 0,
"share": 0
},
{
"id": "1",
"label": "1",
"count": 0,
"share": 0
},
{
"id": "2",
"label": "2",
"count": 0,
"share": 0
},
{
"id": "3",
"label": "3",
"count": 2,
"share": 0.1667
},
{
"id": "4",
"label": "4",
"count": 0,
"share": 0
},
{
"id": "5",
"label": "5",
"count": 0,
"share": 0
},
{
"id": "6",
"label": "6",
"count": 0,
"share": 0
},
{
"id": "7",
"label": "7",
"count": 4,
"share": 0.3333
},
{
"id": "8",
"label": "8",
"count": 0,
"share": 0
},
{
"id": "9",
"label": "9",
"count": 3,
"share": 0.25
},
{
"id": "10",
"label": "10",
"count": 3,
"share": 0.25
}
],
"rows": null,
"ranking": null,
"mean": 7.17,
"min": 3,
"max": 10,
"enps": {
"score": 33,
"promoters": 6,
"passives": 4,
"detractors": 2,
"n": 12
},
"comments": null,
"comments_hidden": false,
"comments_under": null
}
]
}
}A named survey's responses#
POST/v1/surveys/results.responsesRead
Each submitted response of a NAMED survey: the person, when, the language and every answer as text, in question order. Confidential surveys never show one person's answers (forbidden): use surveys_results_get. Owners, admins and HR; API keys and AI apps too (named surveys only).
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Named surveys only: a confidential survey never shows one person's answers to anyone, machines included.
- MCP tool
surveys_results_responseson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
survey_idstringrequired1–64 characters.
langstringLanguage of labels and headers (en, pt-PT, es-ES, de-DE, fr-FR, it-IT); the survey's texts in it when translated.
Pattern
^[a-z]{2}(-[A-Z]{2})?$.
Returns
questionsobject[]required2 fields
idstringrequiredtitlestringrequired
rowsobject[]required5 fields
person_idstringrequirednamestringrequiredsubmitted_atstringrequiredlanguagestringrequiredanswersstring[]required
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/results.responses \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"survey_id":"s3"}'const res = await fetch('https://api.bizisy.com/v1/surveys/results.responses', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"survey_id": "s3"
}),
});
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/surveys/results.responses",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"survey_id": "s3",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"questions": [
{
"id": "q1",
"title": "Recommend?"
}
],
"rows": [
{
"person_id": "p2",
"name": "Bea Silva",
"submitted_at": "2026-11-13T10:00:00.000Z",
"language": "en",
"answers": [
"9"
]
}
]
}
}Export survey results#
POST/v1/surveys/results.exportRead
Downloads a survey's results as CSV, XLSX, SPSS (.sav, with value labels) or JSON. Named surveys: one row (SPSS: one case) per response (person, work email, when, language, each answer; SPSS codes choices and scales as numbers with value labels), plus the summary sheet in XLSX. Confidential and anonymous surveys: the summary only (question, answer, count, share; groups under the threshold say "under N"; comments only from the comment threshold up, masked), never one person's answers; JSON is then the same as surveys_results_get. segment narrows it like surveys_results_get. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_results_exporton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
survey_idstringrequired1–64 characters.
format"csv" | "xlsx" | "sav" | "json"Default
"xlsx".segmentobject2 fields
kindstring (enum)requiredOne of:
team,manager,location,entity,tenure,field,source.idstringrequired1–160 characters.
langstringLanguage of labels and headers (en, pt-PT, es-ES, de-DE, fr-FR, it-IT); the survey's texts in it when translated.
Pattern
^[a-z]{2}(-[A-Z]{2})?$.
Returns
fileobjectrequired6 fields
namestringrequiredcontent_typestringrequiredencoding"utf8" | "base64"requiredcontentstringrequiredbytesintegerrequiredsha256stringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/results.export \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"survey_id": "s1",
"format": "csv",
"segment": {
"kind": "location",
"id": "l1"
}
}'const res = await fetch('https://api.bizisy.com/v1/surveys/results.export', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"survey_id": "s1",
"format": "csv",
"segment": {
"kind": "location",
"id": "l1"
}
}),
});
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/surveys/results.export",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"survey_id": "s1",
"format": "csv",
"segment": {
"kind": "location",
"id": "l1",
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"file": {
"name": "team-pulse.csv",
"content_type": "text/csv; charset=utf-8",
"encoding": "utf8",
"content": "Question,Answer,Count,Share\r\n",
"bytes": 28,
"sha256": "0000000000000000000000000000000000000000000000000000000000000000"
}
}
}Survey heatmap#
POST/v1/surveys/results.heatmapRead
Drivers and scale questions × the groups of one breakdown: team (with sub-teams), manager (a manager's whole line), location, entity, tenure band, or a custom field marked for people analytics (by: field, field_key). Values: eNPS (−100…100) for 0–10 questions, else 0–100 (the scale's low end = 0); previous and change compare with the last round of a recurring survey. filter narrows to one group first: the floor doubles. Hidden cells say why (under: N fewer than N answered; under null: hidden so a smaller group can't be worked out by subtraction, including a manager's line minus a sub-line). Built from the published snapshot. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_results_heatmapon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
survey_idstringrequired1–64 characters.
bystring (enum)One of:
team,manager,location,entity,tenure,field,source. Default"team".field_keystringUp to 60 characters.
filterobject2 fields
kindstring (enum)requiredOne of:
team,manager,location,entity,tenure,field,source.idstringrequired1–160 characters.
langstringPattern
^[a-z]{2}(-[A-Z]{2})?$.
Returns
9 fields
survey_idstringrequiredbystring (enum)requiredOne of:
team,manager,location,entity,tenure,field,source.field_keystring | nullrequiredfilterobject | nullrequired3 fields
kindstring (enum)requiredOne of:
team,manager,location,entity,tenure,field,source.idstringrequired1–160 characters.
namestringrequired
filter_hiddenbooleanrequiredThe filter group itself is under the threshold: nothing shows.
floorintegerrequiredThe smallest group a cell shows (doubled with a filter).
previousobject | nullrequiredThe round changes compare with.
2 fields
survey_idstringrequiredround_nointegerrequired
columnsobject[]required5 fields
idstringrequirednamestringrequiredninteger | nullrequiredhiddenbooleanrequiredunderinteger | nullrequired
rowsobject[]required6 fields
keystringrequireddriver:<name>, a library id, or q:<question id>.
kind"driver" | "enps" | "question"requiredtitlestringrequireddriverstring | nullrequiredoverallnumber | nullrequiredcellsobject[]required6 fields
column_idstringrequiredvaluenumber | nullrequiredpreviousnumber | nullrequiredchangenumber | nullrequiredhiddenbooleanrequiredunderinteger | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/results.heatmap \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"survey_id":"s1","by":"manager","filter":{"kind":"location","id":"l1"}}'const res = await fetch('https://api.bizisy.com/v1/surveys/results.heatmap', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"survey_id": "s1",
"by": "manager",
"filter": {
"kind": "location",
"id": "l1"
}
}),
});
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/surveys/results.heatmap",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"survey_id": "s1",
"by": "manager",
"filter": {
"kind": "location",
"id": "l1",
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"survey_id": "s1",
"by": "manager",
"field_key": null,
"filter": null,
"filter_hidden": false,
"floor": 5,
"previous": {
"survey_id": "s0",
"round_no": 1
},
"columns": [
{
"id": "u1",
"name": "Ops",
"n": 12,
"hidden": false,
"under": null
},
{
"id": "u2",
"name": "Sales",
"n": null,
"hidden": true,
"under": 5
}
],
"rows": [
{
"key": "driver:workload",
"kind": "driver",
"title": "workload",
"driver": "workload",
"overall": 61.5,
"cells": [
{
"column_id": "u1",
"value": 58.3,
"previous": 50,
"change": 8.3,
"hidden": false,
"under": null
},
{
"column_id": "u2",
"value": null,
"previous": null,
"change": null,
"hidden": true,
"under": 5
}
]
}
]
}
}Survey trend across rounds#
POST/v1/surveys/results.trendRead
For a recurring survey, every round's eNPS, driver and question values (same rules as the heatmap; segment narrows them, released with each round's own snapshot). A one-off survey returns its single round. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_results_trendon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
survey_idstringrequired1–64 characters.
segmentobject2 fields
kindstring (enum)requiredOne of:
team,manager,location,entity,tenure,field,source.idstringrequired1–160 characters.
langstringPattern
^[a-z]{2}(-[A-Z]{2})?$.
Returns
series_idstring | nullrequiredroundsobject[]required7 fields
survey_idstringrequiredround_nointegerrequiredopened_atstring | nullrequiredstatusstringrequiredrespondentsinteger | nullrequiredhiddenbooleanrequiredvaluesobjectrequiredRow key → value in that round (null: hidden or not asked).
rowsobject[]required3 fields
keystringrequiredkind"driver" | "enps" | "question"requiredtitlestringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/results.trend \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"survey_id":"s1"}'const res = await fetch('https://api.bizisy.com/v1/surveys/results.trend', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"survey_id": "s1"
}),
});
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/surveys/results.trend",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"survey_id": "s1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"series_id": "s0",
"rows": [
{
"key": "lib.enps.recommend",
"kind": "enps",
"title": "Recommend?"
}
],
"rounds": [
{
"survey_id": "s0",
"round_no": 1,
"opened_at": "2026-08-01T09:00:00.000Z",
"status": "closed",
"respondents": 20,
"hidden": false,
"values": {
"lib.enps.recommend": 12
}
}
]
}
}What matters most here#
POST/v1/surveys/results.driversRead
For a listening survey with drivers: how strongly each driver goes with the outcome (eNPS, else the engagement driver), as a correlation across the published answers (at least 10 and the threshold). It shows association, not cause. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_results_driverson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
survey_idstringrequired1–64 characters.
Returns
outcome"enps" | "engagement"requiredWhat the drivers are compared with: the 0–10 question, else the engagement driver.
ninteger | nullrequiredenoughbooleanrequiredAt least 10 answers and the threshold: below that no correlation is shown.
driversobject[]required3 fields
driverstringrequiredrnumber | nullrequiredCorrelation with the outcome (−1 to 1).
scorenumber | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/results.drivers \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"survey_id":"s1"}'const res = await fetch('https://api.bizisy.com/v1/surveys/results.drivers', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"survey_id": "s1"
}),
});
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/surveys/results.drivers",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"survey_id": "s1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"outcome": "enps",
"n": 20,
"enough": true,
"drivers": [
{
"driver": "growth",
"r": 0.62,
"score": 58
}
]
}
}Survey question library#
POST/v1/surveys/library.listRead
The question library: sourced listening questions with stable ids (lib.<area>.<name>), the engagement driver each measures (engagement, recognition, growth, manager, workload, autonomy, belonging, purpose, communication, wellbeing, fairness), its type and the research it rests on, in the language asked (en, pt-PT, es-ES, de-DE, fr-FR, it-IT); and the templates (enps, engagement, pulse) surveys_surveys_create can start from. Copy a question into a survey keeping its library_id so rounds compare. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_library_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
language"en" | "pt-PT" | "es-ES" | "de-DE" | "fr-FR" | "it-IT"Default
"en".
Returns
itemsobject[]required6 fields
idstringrequireddriverstring | nullrequiredtypestringrequiredtitlestringrequiredsourceobjectrequired2 fields
citestringrequiredurlstringrequired
questionobjectrequiredReady to add to a survey's page.
templates"enps" | "engagement" | "pulse"[]required
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/library.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"language":"pt-PT"}'const res = await fetch('https://api.bizisy.com/v1/surveys/library.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"language": "pt-PT"
}),
});
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/surveys/library.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"language": "pt-PT",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"items": [
{
"id": "lib.enps.recommend",
"driver": null,
"type": "nps",
"title": "Recommend?",
"source": {
"cite": "Reichheld 2003",
"url": "https://hbr.org/2003/12/the-one-number-you-need-to-grow"
},
"question": {
"id": "enps_recommend",
"type": "nps",
"title": "Recommend?"
}
}
],
"templates": [
"enps",
"engagement",
"pulse"
]
}
}Survey settings#
POST/v1/surveys/settings.getRead
The company's survey settings: max_per_month, the fatigue guard (default 2): people who already got that many surveys this calendar month are left out of the next one unless HR sends it anyway. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_settings_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
max_per_monthintegerrequiredSurveys a person gets at most per calendar month (fatigue guard; 0: no limit).
aibooleanrequiredSurveys' AI is on: drafts, translation drafts, question checks, comment themes and questions about results, on Ask HR's model (Vertex AI, EU), paid with AI credits; comments are masked before they are sent and never used for training.
slack_connectedbooleanrequiredSlack is connected (Integrations): surveys can also go as Slack direct messages (surveys_surveys_update slack).
council_approvalbooleanrequiredSurveys wait for the works council's approval before they are sent (a login with Surveys at Approve decides).
privacy_urlstring | nullrequiredThe company's privacy notice, linked on every public survey (required before a public link is switched on).
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/settings.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/surveys/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/surveys/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": {
"max_per_month": 2,
"ai": true,
"slack_connected": true,
"council_approval": false,
"privacy_url": "https://acme.example/privacy"
}
}Change survey settings#
POST/v1/surveys/settings.updateWrite
Changes the fatigue guard (max_per_month, 0 to 12; 0 turns it off) and switches surveys' AI on or off (ai). Send only what changes. Supports dry_run. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_settings_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
max_per_monthintegerFrom 0 to 12.
aibooleancouncil_approvalbooleanSurveys wait for the works council's approval before they are sent.
privacy_urlURL | nullThe company's privacy notice (https://), linked on every public survey.
Up to 500 characters.
Returns
max_per_monthintegerrequiredSurveys a person gets at most per calendar month (fatigue guard; 0: no limit).
aibooleanrequiredSurveys' AI is on: drafts, translation drafts, question checks, comment themes and questions about results, on Ask HR's model (Vertex AI, EU), paid with AI credits; comments are masked before they are sent and never used for training.
slack_connectedbooleanrequiredSlack is connected (Integrations): surveys can also go as Slack direct messages (surveys_surveys_update slack).
council_approvalbooleanrequiredSurveys wait for the works council's approval before they are sent (a login with Surveys at Approve decides).
privacy_urlstring | nullrequiredThe company's privacy notice, linked on every public survey (required before a public link is switched on).
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/settings.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"privacy_url":"https://acme.example/privacy"}'const res = await fetch('https://api.bizisy.com/v1/surveys/settings.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"privacy_url": "https://acme.example/privacy"
}),
});
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/surveys/settings.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"privacy_url": "https://acme.example/privacy",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"max_per_month": 3,
"ai": true,
"slack_connected": true,
"council_approval": false,
"privacy_url": "https://acme.example/privacy"
}
}Stop a recurring survey#
POST/v1/surveys/series.stopWrite
Stops a recurring survey from sending new rounds. Rounds already sent stay, with their results and trends; an open round stays open until it closes. Supports dry_run. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_series_stopon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
survey_idstringrequiredAny round of the series.
1–64 characters.
Returns
38 fields
idstringrequiredtitlestringrequiredmode"named" | "confidential" | "anonymous"requiredstatus"draft" | "scheduled" | "open" | "closed"requiredarchivedbooleanrequiredquestionsintegerrequiredlanguagestringrequiredlanguagesstring[]requiredrecipientsintegerrequiredansweredinteger | nullrequirednull while fewer than the threshold answered a confidential survey (see answered_under).
answered_underinteger | nullrequiredConfidential: "under N" when fewer than N answered.
open_atstring | nullrequiredopened_atstring | nullrequiredclose_atstring | nullrequiredclosed_atstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredkind"custom" | "listening"requiredseries_idstring | nullrequiredRecurring surveys: the series (its first round's id); null for a one-off.
round_nointegerrequiredWhich round of its series (1 for a one-off).
recurringbooleanrequiredThe series still sends new rounds (stop it with surveys_series_stop).
definitionobjectrequiredThe survey: pages of questions (types: single, multi, dropdown, nps 0–10, likert 5/7, star, emoji, slider, ranking, matrix, short_text, long_text, number, date, yes_no, people (named surveys only), location, statement, consent), show_if conditions, jumps after a page (to a later page or "end"), piping in texts and choices ({{answer:<question id>}}, {{person:first_name|team|location}}, {{var:<variable id>}}), variables fed by score_into, outcomes shown at the end, translations per language keyed like "q:<question id>:title" or "c:<question id>:<choice id>".
12 fields
languagestringrequiredPattern
^[a-z]{2}(-[A-Z]{2})?$.languagesstring[]requiredUp to 10 items. Pattern
^[a-z]{2}(-[A-Z]{2})?$.translationsobjectrequiredcoverobjectrequired3 fields
showbooleanrequiredtitlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
thanksobjectrequired5 fields
titlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
link_urlstring | nullUp to 500 characters. Pattern
^https:\/\/[^\s]+$.link_labelstring | nullUp to 80 characters.
redirect_urlstring | nullUp to 500 characters. Pattern
^https:\/\/[^\s]+$.
layout"one" | "page"requiredprogressbooleanrequiredlogobooleanrequiredthemeobjectHow the answering screen looks (the Design tab).
7 fields
palettestring (enum)company (Settings → Appearance) or one of the palettes.
One of:
company,emerald,violet,indigo,ocean,amber,rose,graphite,terracotta.surface"plain" | "soft" | "tinted" | "dark"The page behind the questions: plain, soft, tinted or dark.
font"default" | "friendly" | "display" | "serif"buttons"rounded" | "pill" | "square"imagestring | nullA background image id from surveys_design_image_upload.
Pattern
^[0-9a-z]{26}$.image_dimintegerHow much the image is veiled under the text, 45–85 (%; default 65): the text stays readable.
From 45 to 85.
brandingboolean"Powered by Bizisy" at the bottom (default true).
pagesobject[]required1–50 items.
6 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.titlestring | nullUp to 300 characters.
descriptionstring | nullUp to 2000 characters.
questionsobject[]requiredUp to 200 items.
22 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.typestring (enum)requiredOne of:
single,multi,dropdown,nps,likert,star,emoji,slider,ranking,matrix,short_text,long_text,number,date,yes_no,people,location,statement,consent.titlestringrequiredUp to 1000 characters.
descriptionstring | nullUp to 2000 characters.
requiredbooleanrequired_messagestring | nullUp to 200 characters.
choicesobject[]Up to 100 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.labelstringrequiredUp to 500 characters.
scorenumber | nullquotainteger | nullFrom 1 to 100000.
otherbooleanrandomizebooleanmax_picksinteger | nullFrom 1 to 100.
points5 | 7minnumber | nullmaxnumber | nullstepnumber | nullAt least 0.
low_labelstring | nullUp to 80 characters.
high_labelstring | nullUp to 80 characters.
rowsobject[]Up to 100 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.labelstringrequiredUp to 500 characters.
scorenumber | nullquotainteger | nullFrom 1 to 100000.
max_lengthinteger | nullFrom 1 to 5000.
show_ifobject | null2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
score_intoobject | null2 fields
variablestringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.weightnumber
library_idstring | nullThe library item it was copied from (surveys_library_list): rounds and trends compare by it.
Pattern
^lib\.[a-z]+\.[a-z]+$.driverstring | nullThe engagement driver it measures (engagement, recognition, growth, manager, workload, autonomy, belonging, purpose, communication, wellbeing, fairness).
Pattern
^[a-z_]{2,30}$.
randomize_questionsbooleanjumpsobject[]Up to 20 items.
2 fields
whenobjectrequired2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
tostring | "end"required
variablesobject[]requiredUp to 20 items.
3 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.namestringrequiredUp to 80 characters.
initialnumber
outcomesobject[]requiredUp to 20 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.titlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
whenobjectrequired2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
5 fields
qstringPattern
^[A-Za-z0-9_-]{1,40}$.vstringPattern
^[A-Za-z0-9_-]{1,40}$.f"team" | "location" | "entity" | "language"opstring (enum)requiredOne of:
eq,neq,gt,gte,lt,lte,includes,excludes,answered,not_answered.valuestring | number | boolean | "null"
thresholdintegerrequiredcomment_thresholdintegerrequiredaudienceobjectrequired5 fields
everyonebooleanDefault
false.unit_idsstring[]1–64 characters. Up to 200 items.
location_idsstring[]1–64 characters. Up to 200 items.
entity_idsstring[]1–64 characters. Up to 50 items.
group_idsstring[]1–64 characters. Up to 50 items.
reminder_daysinteger[]requiredproblemsobject[]requiredWhat stops it from opening (empty: ready).
2 fields
atstringrequiredmessagestringrequired
lockedbooleanrequiredOpened once: the mode and questions are fixed; translations, reminders and the close date can still change.
manager_viewbooleanrequiredManagers see their own line's results in My workspace (above the threshold, never a sub-line that could be worked out).
recurrenceobject | nullrequiredThe series' schedule (on its first round).
2 fields
every"week" | "two_weeks" | "month" | "quarter" | "half_year" | "year"requiredopen_daysintegerFrom 1 to 60. Default
7.
anonymous_bands"team" | "location" | "tenure"[]requiredAnonymous surveys: the coarse bands kept with each answer.
fatigue_skippedintegerrequiredPeople left out at sending: they already had their surveys this month.
triggerobject | nullrequiredLifecycle: sent to each person in the audience at a moment of their working life (start, exit, move, return), from the day it opens.
2 fields
kind"start" | "exit" | "move" | "return"requiredstart: days after the first day; exit: days before the last day (only once the person was told, while they still have access); move: days after a change of team, location, title or manager; return: days after coming back from a leave of at least 28 days.
daysintegerrequiredFrom 0 to 365.
slackbooleanrequiredInvitations and reminders also go as Slack direct messages where the company connected Slack.
retention_monthsintegerrequiredAnswers are deleted this many months after it closes; the group results are kept.
purged_atstring | nullrequiredWhen its answers were deleted (retention); results then come from the kept group results.
publicobject | nullrequiredIts public link (surveys_public_set); null: never set.
10 fields
onbooleanrequiredidstringrequiredrespondent"anonymous" | "named"requiredmax_answersintegerrequiredone_per_browserbooleanrequiredkioskbooleanrequiredembed_domainsstring[]requiredansweredintegerrequiredswitched_off_by_bizisybooleanrequiredreportsintegerrequired
councilobjectrequiredThe works council's approval (when the company asks for it, surveys_settings_get council_approval).
3 fields
status"not_asked" | "waiting" | "approved" | "returned"requiredapproved_for_this_versionbooleanrequiredentriesobject[]required4 fields
kind"asked" | "approved" | "returned" | "comment"requiredbystringrequiredtextstring | nullrequiredatstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/series.stop \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"survey_id":"s1"}'const res = await fetch('https://api.bizisy.com/v1/surveys/series.stop', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"survey_id": "s1"
}),
});
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/surveys/series.stop",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"survey_id": "s1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "s1",
"title": "Team pulse",
"mode": "confidential",
"status": "open",
"archived": false,
"questions": 3,
"language": "en",
"languages": [
"pt-PT"
],
"recipients": 24,
"answered": 12,
"answered_under": null,
"open_at": "2026-11-13T09:00:00.000Z",
"opened_at": "2026-11-13T09:00:00.000Z",
"close_at": "2026-11-27T18:00:00.000Z",
"closed_at": null,
"created_at": "2026-11-12T10:00:00.000Z",
"updated_at": "2026-11-13T10:00:00.000Z",
"kind": "listening",
"series_id": "s1",
"round_no": 2,
"recurring": false,
"definition": {
"language": "en",
"languages": [
"pt-PT"
],
"translations": {
"pt-PT": {
"q:q1:title": "Recomendaria a empresa?"
}
},
"cover": {
"show": true,
"title": "Team pulse",
"body": "Five questions, two minutes."
},
"thanks": {
"title": "Thank you!",
"body": null,
"link_url": null,
"link_label": null,
"redirect_url": null
},
"layout": "one",
"progress": true,
"logo": true,
"pages": [
{
"id": "p1",
"title": null,
"description": null,
"questions": [
{
"id": "q1",
"type": "nps",
"title": "How likely are you to recommend us as a place to work?",
"required": true,
"low_label": "Not at all",
"high_label": "Very likely"
},
{
"id": "q2",
"type": "single",
"title": "Lunch, {{person:first_name}}?",
"choices": [
{
"id": "c1",
"label": "Fish",
"quota": 20
},
{
"id": "c2",
"label": "Veg"
}
],
"other": true
},
{
"id": "q3",
"type": "long_text",
"title": "What would you change?",
"show_if": {
"match": "all",
"rules": [
{
"q": "q1",
"op": "lte",
"value": 6
}
]
}
}
],
"jumps": []
}
],
"variables": [],
"outcomes": []
},
"threshold": 5,
"comment_threshold": 10,
"audience": {
"everyone": true,
"unit_ids": [],
"location_ids": [],
"entity_ids": [],
"group_ids": []
},
"reminder_days": [
3,
6
],
"problems": [],
"locked": true,
"manager_view": true,
"recurrence": null,
"anonymous_bands": [],
"fatigue_skipped": 2,
"trigger": null,
"slack": false,
"retention_months": 24,
"purged_at": null,
"council": {
"status": "approved",
"approved_for_this_version": true,
"entries": [
{
"kind": "approved",
"by": "Rita Conselho",
"text": null,
"at": "2026-11-12T15:00:00.000Z"
}
]
},
"public": null
}
}Surveys AI: availability#
POST/v1/surveys/ai.statusRead
Whether surveys' AI can be used (on this server, and switched on for the company in Surveys → Settings), and about how many AI credits a request uses. Owners, admins and HR, in the app.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_ai_statuson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
availablebooleanrequiredreason"unavailable" | "off"requiredcreditsintegerrequiredAbout how many AI credits a typical request uses.
left_todayintegerrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/ai.status \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/surveys/ai.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/surveys/ai.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,
"credits": 3,
"left_today": 198
}
}Draft a survey with AI#
POST/v1/surveys/ai.draftWrite
Drafts a survey from a sentence ("a 5-minute exit survey with a reason for leaving and a question for people who would come back"): pages, question types, simple logic and, with languages, translation drafts. Only the sentence goes to the AI (Ask HR's model, Vertex AI in the EU). Nothing is saved: create it with surveys_surveys_create after reading it. Uses AI credits. Owners, admins and HR, in the app.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_ai_drafton 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
sentencestringrequired10–1000 characters.
language"en" | "pt-PT" | "es-ES" | "de-DE" | "fr-FR" | "it-IT"Default
"en".mode"named" | "confidential" | "anonymous"Default
"confidential".languages"en" | "pt-PT" | "es-ES" | "de-DE" | "fr-FR" | "it-IT"[]Up to 5 items.
Returns
titlestringrequireddefinitionobjectrequiredThe survey: pages of questions (types: single, multi, dropdown, nps 0–10, likert 5/7, star, emoji, slider, ranking, matrix, short_text, long_text, number, date, yes_no, people (named surveys only), location, statement, consent), show_if conditions, jumps after a page (to a later page or "end"), piping in texts and choices ({{answer:<question id>}}, {{person:first_name|team|location}}, {{var:<variable id>}}), variables fed by score_into, outcomes shown at the end, translations per language keyed like "q:<question id>:title" or "c:<question id>:<choice id>".
12 fields
languagestringrequiredPattern
^[a-z]{2}(-[A-Z]{2})?$.languagesstring[]requiredUp to 10 items. Pattern
^[a-z]{2}(-[A-Z]{2})?$.translationsobjectrequiredcoverobjectrequired3 fields
showbooleanrequiredtitlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
thanksobjectrequired5 fields
titlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
link_urlstring | nullUp to 500 characters. Pattern
^https:\/\/[^\s]+$.link_labelstring | nullUp to 80 characters.
redirect_urlstring | nullUp to 500 characters. Pattern
^https:\/\/[^\s]+$.
layout"one" | "page"requiredprogressbooleanrequiredlogobooleanrequiredthemeobjectHow the answering screen looks (the Design tab).
7 fields
palettestring (enum)company (Settings → Appearance) or one of the palettes.
One of:
company,emerald,violet,indigo,ocean,amber,rose,graphite,terracotta.surface"plain" | "soft" | "tinted" | "dark"The page behind the questions: plain, soft, tinted or dark.
font"default" | "friendly" | "display" | "serif"buttons"rounded" | "pill" | "square"imagestring | nullA background image id from surveys_design_image_upload.
Pattern
^[0-9a-z]{26}$.image_dimintegerHow much the image is veiled under the text, 45–85 (%; default 65): the text stays readable.
From 45 to 85.
brandingboolean"Powered by Bizisy" at the bottom (default true).
pagesobject[]required1–50 items.
6 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.titlestring | nullUp to 300 characters.
descriptionstring | nullUp to 2000 characters.
questionsobject[]requiredUp to 200 items.
22 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.typestring (enum)requiredOne of:
single,multi,dropdown,nps,likert,star,emoji,slider,ranking,matrix,short_text,long_text,number,date,yes_no,people,location,statement,consent.titlestringrequiredUp to 1000 characters.
descriptionstring | nullUp to 2000 characters.
requiredbooleanrequired_messagestring | nullUp to 200 characters.
choicesobject[]Up to 100 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.labelstringrequiredUp to 500 characters.
scorenumber | nullquotainteger | nullFrom 1 to 100000.
otherbooleanrandomizebooleanmax_picksinteger | nullFrom 1 to 100.
points5 | 7minnumber | nullmaxnumber | nullstepnumber | nullAt least 0.
low_labelstring | nullUp to 80 characters.
high_labelstring | nullUp to 80 characters.
rowsobject[]Up to 100 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.labelstringrequiredUp to 500 characters.
scorenumber | nullquotainteger | nullFrom 1 to 100000.
max_lengthinteger | nullFrom 1 to 5000.
show_ifobject | null2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
score_intoobject | null2 fields
variablestringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.weightnumber
library_idstring | nullThe library item it was copied from (surveys_library_list): rounds and trends compare by it.
Pattern
^lib\.[a-z]+\.[a-z]+$.driverstring | nullThe engagement driver it measures (engagement, recognition, growth, manager, workload, autonomy, belonging, purpose, communication, wellbeing, fairness).
Pattern
^[a-z_]{2,30}$.
randomize_questionsbooleanjumpsobject[]Up to 20 items.
2 fields
whenobjectrequired2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
tostring | "end"required
variablesobject[]requiredUp to 20 items.
3 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.namestringrequiredUp to 80 characters.
initialnumber
outcomesobject[]requiredUp to 20 items.
4 fields
idstringrequiredPattern
^[A-Za-z0-9_-]{1,40}$.titlestringrequiredUp to 300 characters.
bodystring | nullUp to 5000 characters.
whenobjectrequired2 fields
match"all" | "any"requiredrulesobject[]requiredUp to 20 items.
5 fields
qstringPattern
^[A-Za-z0-9_-]{1,40}$.vstringPattern
^[A-Za-z0-9_-]{1,40}$.f"team" | "location" | "entity" | "language"opstring (enum)requiredOne of:
eq,neq,gt,gte,lt,lte,includes,excludes,answered,not_answered.valuestring | number | boolean | "null"
warningsobject[]required3 fields
question_idstringrequiredkindstringrequirednotestringrequired
ai_generatedtruerequiredai_creditsobjectrequired2 fields
costintegerrequiredAI credits this used.
leftinteger | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/ai.draft \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"sentence": "A short exit survey with a reason for leaving",
"languages": [
"pt-PT"
]
}'const res = await fetch('https://api.bizisy.com/v1/surveys/ai.draft', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"sentence": "A short exit survey with a reason for leaving",
"languages": [
"pt-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/surveys/ai.draft",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"sentence": "A short exit survey with a reason for leaving",
"languages": [
"pt-PT",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"title": "Exit survey",
"definition": {
"language": "en",
"languages": [
"pt-PT"
],
"translations": {
"pt-PT": {
"q:q1:title": "Recomendaria a empresa?"
}
},
"cover": {
"show": true,
"title": "Team pulse",
"body": "Five questions, two minutes."
},
"thanks": {
"title": "Thank you!",
"body": null,
"link_url": null,
"link_label": null,
"redirect_url": null
},
"layout": "one",
"progress": true,
"logo": true,
"pages": [
{
"id": "p1",
"title": null,
"description": null,
"questions": [
{
"id": "q1",
"type": "nps",
"title": "How likely are you to recommend us as a place to work?",
"required": true,
"low_label": "Not at all",
"high_label": "Very likely"
},
{
"id": "q2",
"type": "single",
"title": "Lunch, {{person:first_name}}?",
"choices": [
{
"id": "c1",
"label": "Fish",
"quota": 20
},
{
"id": "c2",
"label": "Veg"
}
],
"other": true
},
{
"id": "q3",
"type": "long_text",
"title": "What would you change?",
"show_if": {
"match": "all",
"rules": [
{
"q": "q1",
"op": "lte",
"value": 6
}
]
}
}
],
"jumps": []
}
],
"variables": [],
"outcomes": []
},
"warnings": [],
"ai_generated": true,
"ai_credits": {
"cost": 4,
"left": 496
}
}
}Write one survey question with AI#
POST/v1/surveys/ai.questionWrite
Writes one question from a description ("ask how they rate onboarding, 1 to 5 stars"): its type, wording and choices, in the survey's language. Only the description goes to the AI. Nothing is saved: add it to the survey with surveys_surveys_update. Uses AI credits. Owners, admins and HR, in the app.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_ai_questionon 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
descriptionstringrequired4–1000 characters.
language"en" | "pt-PT" | "es-ES" | "de-DE" | "fr-FR" | "it-IT"Default
"en".mode"named" | "confidential" | "anonymous"Default
"confidential".
Returns
questionanyA question of the survey definition (type, title, choices…), with a fresh id.
warningsobject[]required2 fields
kindstringrequirednotestringrequired
ai_generatedtruerequiredai_creditsobjectrequired2 fields
costintegerrequiredAI credits this used.
leftinteger | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/ai.question \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"description":"rate onboarding from poor to excellent","language":"en"}'const res = await fetch('https://api.bizisy.com/v1/surveys/ai.question', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"description": "rate onboarding from poor to excellent",
"language": "en"
}),
});
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/surveys/ai.question",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"description": "rate onboarding from poor to excellent",
"language": "en",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"question": {
"id": "qk3m9x",
"type": "likert",
"title": "How would you rate your onboarding?",
"points": 5,
"low_label": "Poor",
"high_label": "Excellent"
},
"warnings": [],
"ai_generated": true,
"ai_credits": {
"cost": 1,
"left": 495
}
}
}Draft a survey's translation with AI#
POST/v1/surveys/ai.translateWrite
Drafts the translation of every text of a survey into one language (the keys of definition.translations). Only the survey's own texts go to the AI. Nothing is saved: review it and save with surveys_surveys_update. Uses AI credits. Owners, admins and HR, in the app.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_ai_translateon 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
survey_idstringrequired1–64 characters.
language"en" | "pt-PT" | "es-ES" | "de-DE" | "fr-FR" | "it-IT"required
Returns
languagestringrequiredtranslationsobjectrequiredai_generatedtruerequiredai_creditsobjectrequired2 fields
costintegerrequiredAI credits this used.
leftinteger | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/ai.translate \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"survey_id":"s1","language":"pt-PT"}'const res = await fetch('https://api.bizisy.com/v1/surveys/ai.translate', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"survey_id": "s1",
"language": "pt-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/surveys/ai.translate",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"survey_id": "s1",
"language": "pt-PT",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"language": "pt-PT",
"translations": {
"cover:title": "Pulso da equipa"
},
"ai_generated": true,
"ai_credits": {
"cost": 2,
"left": 493
}
}
}Check a survey's questions#
POST/v1/surveys/surveys.checkWrite
Warnings before sending, never blocks: questions that can identify someone in a confidential or anonymous survey (always checked, no AI: a colleague or location question, "which team are you in", asking for a name or email), and with ai true also leading, double-barrelled and loaded wording, by the AI (only the questions go to it; uses AI credits). A dry run checks the rules only. Owners, admins and HR, in the app.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_surveys_checkon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
survey_idstringrequired1–64 characters.
aibooleanDefault
false.
Returns
warningsobject[]required5 fields
question_idstringrequiredkind"identifying" | "leading" | "double_barrelled" | "loaded"requirednotestringrequiredsuggestionstring | nullrequiredby"rule" | "ai"required
ai_usedbooleanrequiredai_creditsobjectrequired2 fields
costintegerrequiredAI credits this used.
leftinteger | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/surveys.check \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"survey_id":"s1","ai":true}'const res = await fetch('https://api.bizisy.com/v1/surveys/surveys.check', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"survey_id": "s1",
"ai": 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/surveys/surveys.check",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"survey_id": "s1",
"ai": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"warnings": [
{
"question_id": "q1",
"kind": "leading",
"note": "It suggests the answer.",
"suggestion": "How would you rate it?",
"by": "ai"
}
],
"ai_used": true,
"ai_credits": {
"cost": 1,
"left": 492
}
}
}Comment themes#
POST/v1/surveys/results.themesRead
The themes and sentiment AI found in a survey's comments, stored per round and made only from the published answers once their comments reach the comment threshold (so they change in steps, never with one comment); quotes are masked and appear only above that threshold; share and previous_share compare with the last round of a recurring survey. stale: refresh with surveys_ai_themes_refresh. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_results_themeson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
survey_idstringrequired1–64 characters.
Returns
9 fields
survey_idstringrequiredenoughbooleanrequiredEnough published comments to find themes (the comment threshold).
stalebooleanrequiredThe published answers grew since the themes were made: refresh with surveys_ai_themes_refresh.
comments_ninteger | nullrequiredthemesobject[]required6 fields
labelstringrequiredsentiment"positive" | "mixed" | "negative"requiredcountintegerrequiredsharenumberrequiredquotesstring[]requiredprevious_sharenumber | nullrequired
summarystring | nullrequiredprevious_roundinteger | nullrequiredcreated_atstring | nullrequiredai_generatedtruerequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/results.themes \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"survey_id":"s1"}'const res = await fetch('https://api.bizisy.com/v1/surveys/results.themes', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"survey_id": "s1"
}),
});
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/surveys/results.themes",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"survey_id": "s1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"survey_id": "s1",
"enough": true,
"stale": false,
"comments_n": 20,
"summary": "Workload and meetings stand out.",
"previous_round": 2,
"created_at": "2026-11-14T10:00:00.000Z",
"ai_generated": true,
"themes": [
{
"label": "Too many meetings",
"sentiment": "negative",
"count": 8,
"share": 0.4,
"quotes": [
"Too many meetings on Mondays."
],
"previous_share": 0.25
}
]
}
}Find comment themes with AI#
POST/v1/surveys/ai.themes_refreshWrite
Finds the themes and sentiment of a survey's comments with AI and stores them: only the published comments, only from the comment threshold up, with names, emails and phone numbers masked before they are sent. Refused when there are not enough comments or nothing changed since the last time. Uses AI credits. Owners, admins and HR, in the app.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_ai_themes_refreshon 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
survey_idstringrequired1–64 characters.
Returns
9 fields
survey_idstringrequiredenoughbooleanrequiredEnough published comments to find themes (the comment threshold).
stalebooleanrequiredThe published answers grew since the themes were made: refresh with surveys_ai_themes_refresh.
comments_ninteger | nullrequiredthemesobject[]required6 fields
labelstringrequiredsentiment"positive" | "mixed" | "negative"requiredcountintegerrequiredsharenumberrequiredquotesstring[]requiredprevious_sharenumber | nullrequired
summarystring | nullrequiredprevious_roundinteger | nullrequiredcreated_atstring | nullrequiredai_generatedtruerequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/ai.themes_refresh \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"survey_id":"s1"}'const res = await fetch('https://api.bizisy.com/v1/surveys/ai.themes_refresh', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"survey_id": "s1"
}),
});
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/surveys/ai.themes_refresh",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"survey_id": "s1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"survey_id": "s1",
"enough": true,
"stale": false,
"comments_n": 20,
"summary": "Workload and meetings stand out.",
"previous_round": 2,
"created_at": "2026-11-14T10:00:00.000Z",
"ai_generated": true,
"themes": [
{
"label": "Too many meetings",
"sentiment": "negative",
"count": 8,
"share": 0.4,
"quotes": [
"Too many meetings on Mondays."
],
"previous_share": 0.25
}
]
}
}Ask about a survey's results#
POST/v1/surveys/ai.askWrite
Answers a question about a survey's results in a sentence ("how did eNPS move in Porto?"), from the same released numbers the results screen shows (overall, response rate by group, the heatmap by team and location, stored comment themes): the AI never reads answers or hidden groups, and is told never to work them out. Uses AI credits. Owners, admins and HR, in the app.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_ai_askon 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
survey_idstringrequired1–64 characters.
questionstringrequired3–500 characters.
lang"en" | "pt-PT" | "es-ES" | "de-DE" | "fr-FR" | "it-IT"
Returns
answerstringrequiredai_generatedtruerequiredai_creditsobjectrequired2 fields
costintegerrequiredAI credits this used.
leftinteger | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/ai.ask \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"survey_id":"s1","question":"How did eNPS move in Porto?"}'const res = await fetch('https://api.bizisy.com/v1/surveys/ai.ask', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"survey_id": "s1",
"question": "How did eNPS move in Porto?"
}),
});
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/surveys/ai.ask",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"survey_id": "s1",
"question": "How did eNPS move in Porto?",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"answer": "eNPS in Porto is hidden: fewer than 5 people there answered.",
"ai_generated": true,
"ai_credits": {
"cost": 1,
"left": 490
}
}
}Reply to a survey comment#
POST/v1/surveys/comments.replyWrite
Replies to a comment the results show (its comment_id from surveys_results_get). Its author reads it in My workspace and can answer, without being identified: nobody, Bizisy included, shows HR who wrote it; anonymous authors see it only on the device they answered on. At most 20 messages a conversation and 300 replies a survey a day. Owners, admins and HR, in the app.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_comments_replyon 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
survey_idstringrequired1–64 characters.
comment_idstringrequired8–40 characters.
textstringrequired1–2000 characters.
Returns
8 fields
idstringrequiredsurvey_idstringrequiredquestion_idstringrequiredcomment_idstringrequiredquotestringrequiredmessagesobject[]required3 fields
from"hr" | "manager" | "person"requiredtextstringrequiredatstringrequired
unreadbooleanrequiredThe other side wrote last and it has not been read here.
updated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/comments.reply \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"survey_id": "s1",
"comment_id": "c8x2k4m9q1zt",
"text": "Thank you, can you say more?"
}'const res = await fetch('https://api.bizisy.com/v1/surveys/comments.reply', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"survey_id": "s1",
"comment_id": "c8x2k4m9q1zt",
"text": "Thank you, can you say more?"
}),
});
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/surveys/comments.reply",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"survey_id": "s1",
"comment_id": "c8x2k4m9q1zt",
"text": "Thank you, can you say more?",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "t1",
"survey_id": "s1",
"question_id": "why",
"comment_id": "c8x2k4m9q1zt",
"quote": "More focus time, please.",
"messages": [
{
"from": "hr",
"text": "Thank you, can you say more?",
"at": "2026-11-14T10:00:00.000Z"
}
],
"unread": false,
"updated_at": "2026-11-14T10:00:00.000Z"
}
}Conversations on a survey's comments#
POST/v1/surveys/comments.threadsRead
The conversations HR and managers started on a survey's comments, newest first, with the author's answers (never who they are). Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_comments_threadson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
survey_idstringrequired1–64 characters.
Returns
itemsobject[]required8 fields
idstringrequiredsurvey_idstringrequiredquestion_idstringrequiredcomment_idstringrequiredquotestringrequiredmessagesobject[]required3 fields
from"hr" | "manager" | "person"requiredtextstringrequiredatstringrequired
unreadbooleanrequiredThe other side wrote last and it has not been read here.
updated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/comments.threads \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"survey_id":"s1"}'const res = await fetch('https://api.bizisy.com/v1/surveys/comments.threads', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"survey_id": "s1"
}),
});
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/surveys/comments.threads",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"survey_id": "s1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"items": [
{
"id": "t1",
"survey_id": "s1",
"question_id": "why",
"comment_id": "c8x2k4m9q1zt",
"quote": "More focus time, please.",
"messages": [
{
"from": "hr",
"text": "Thank you, can you say more?",
"at": "2026-11-14T10:00:00.000Z"
}
],
"unread": false,
"updated_at": "2026-11-14T10:00:00.000Z"
}
]
}
}List survey background images#
POST/v1/surveys/design.imagesRead
The background images uploaded for surveys (newest first), to reuse in a survey's theme (definition.theme.image = id). available is false when this server has no image store. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_design_imageson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
availablebooleanrequiredmaxintegerrequireditemsobject[]required3 fields
idstringrequiredurlstringrequiredcreated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/design.images \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/surveys/design.images', {
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/surveys/design.images",
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,
"max": 30,
"items": [
{
"id": "01jd4z3m5q8w2x6v9b7n1c0k3e",
"url": "https://acme.bizisy.com/api/surveys/images/01jd4z3m5q8w2x6v9b7n1c0k3e",
"created_at": "2026-11-12T10:00:00.000Z"
}
]
}
}Upload a survey background image#
POST/v1/surveys/design.image_uploadWrite
Uploads a background image for surveys (image_base64: the file as base64; a data: URL is accepted): JPEG, PNG or WebP, at most 2 MB and 24 megapixels. The server checks the bytes, crops it to 1920×1280, re-encodes it as WebP and drops all metadata (location, camera). Returns its id: set it as definition.theme.image with surveys_surveys_update. At most 30 per company. Supports dry_run (checks the image, saves nothing). rate_limited means the server is busy with other images: retry in a few seconds. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_design_image_uploadon 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
- Body limit
- 3 MiB (other actions: 2 MiB)
Input
image_base64stringrequiredThe image as base64: JPEG, PNG or WebP, at most 2 MB.
1–2900000 characters.
Returns
idstringrequiredurlstringrequiredcreated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled payload_too_large rate_limited internal
curl https://api.bizisy.com/v1/surveys/design.image_upload \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"image_base64":"iVBORw0KGgo…"}'const res = await fetch('https://api.bizisy.com/v1/surveys/design.image_upload', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"image_base64": "iVBORw0KGgo…"
}),
});
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/surveys/design.image_upload",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"image_base64": "iVBORw0KGgo…",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "01jd4z3m5q8w2x6v9b7n1c0k3e",
"url": "https://acme.bizisy.com/api/surveys/images/01jd4z3m5q8w2x6v9b7n1c0k3e",
"created_at": "2026-11-12T10:00:00.000Z"
}
}A survey's Google Sheets link#
POST/v1/surveys/feeds.getRead
Whether a survey has a live results address for Google Sheets (=IMPORTDATA), when it was made and last read. The address itself is shown once, when it is made. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_feeds_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
survey_idstringrequired1–64 characters.
Returns
activebooleanrequiredcreated_atstring | nullrequiredlast_used_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/feeds.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"survey_id":"s1"}'const res = await fetch('https://api.bizisy.com/v1/surveys/feeds.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"survey_id": "s1"
}),
});
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/surveys/feeds.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"survey_id": "s1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"active": true,
"created_at": "2026-11-13T10:00:00.000Z",
"last_used_at": "2026-11-14T08:00:00.000Z"
}
}Make a Google Sheets link for a survey#
POST/v1/surveys/feeds.createWrite
Makes the survey's live results address for Google Sheets: paste the formula (=IMPORTDATA("…")) in a sheet and it refreshes about every hour. It serves only the released results (the summary, as surveys_results_get shows them, never one person's answers, not even in a named survey). Anyone with the address can read those results: share the sheet, not the address. Makes a new address and stops the old one. The address is shown only now. In the app (not by API key). Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_feeds_createon 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
survey_idstringrequired1–64 characters.
Returns
activebooleanrequiredcreated_atstring | nullrequiredlast_used_atstring | nullrequiredtokenstring | nullrequiredShown once (null on a dry run).
pathstring | nullrequiredThe address on the company's domain (=IMPORTDATA("https://<company>.bizisy.com<path>")).
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/feeds.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"survey_id":"s1"}'const res = await fetch('https://api.bizisy.com/v1/surveys/feeds.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"survey_id": "s1"
}),
});
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/surveys/feeds.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"survey_id": "s1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"active": true,
"created_at": "2026-11-13T10:00:00.000Z",
"last_used_at": null,
"token": "bzsv_01jd4z3m5q8w2x6v9b7n1c0k3e_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"path": "https://acme.bizisy.com/api/surveys/feed/bzsv_01jd4z3m5q8w2x6v9b7n1c0k3e_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}Stop a survey's Google Sheets link#
POST/v1/surveys/feeds.revokeDestructive
Stops the survey's live results address at once (sheets using it stop updating). Succeeds when there is none. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_feeds_revokeon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
survey_idstringrequired1–64 characters.
Returns
activebooleanrequiredcreated_atstring | nullrequiredlast_used_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/feeds.revoke \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"survey_id":"s1"}'const res = await fetch('https://api.bizisy.com/v1/surveys/feeds.revoke', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"survey_id": "s1"
}),
});
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/surveys/feeds.revoke",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"survey_id": "s1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"active": false,
"created_at": null,
"last_used_at": null
}
}Actions from survey results#
POST/v1/surveys/actions.listRead
The actions planned from a survey's results (or every survey's, without survey_id), open first: the owner, due date, the group and the number it should move, its value then (baseline) and in the latest later round of a recurring survey (check; null when that group is hidden there). Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_actions_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
survey_idstring1–64 characters.
Returns
itemsobject[]required14 fields
idstringrequiredsurvey_idstringrequiredsurvey_titlestringrequiredround_nointegerrequiredsegmentobject | nullrequired3 fields
kindstringrequiredidstringrequirednamestringrequired
metricobjectrequired2 fields
keystringrequiredtitlestringrequired
baselinenumber | nullrequiredtitlestringrequiredownerobjectrequired2 fields
idstringrequirednamestringrequired
duestring | nullrequiredstatus"open" | "done"requiredcheckobject | nullrequiredThe latest later round with results: the same number for the same group (null value: hidden there).
3 fields
round_nointegerrequiredsurvey_idstringrequiredvaluenumber | nullrequired
created_atstringrequireddone_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/actions.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"survey_id":"s1"}'const res = await fetch('https://api.bizisy.com/v1/surveys/actions.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"survey_id": "s1"
}),
});
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/surveys/actions.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"survey_id": "s1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"items": [
{
"id": "a1",
"survey_id": "s1",
"survey_title": "Team pulse",
"round_no": 3,
"segment": {
"kind": "team",
"id": "u1",
"name": "Engineering"
},
"metric": {
"key": "enps",
"title": "eNPS"
},
"baseline": 18,
"title": "Weekly focus time",
"owner": {
"id": "p2",
"name": "Bea Silva"
},
"due": "2026-12-31",
"status": "open",
"check": {
"round_no": 4,
"survey_id": "s9",
"value": 31
},
"created_at": "2026-11-13T10:00:00.000Z",
"done_at": null
}
]
}
}Plan an action from survey results#
POST/v1/surveys/actions.createWrite
Plans an action from a survey's results: a title, its owner (person_id: anyone in the company; they see it on their Home), an optional due date, the group it is about (segment, as in surveys_results_get; none: everyone) and the number it should move (metric: enps, or q:<question id> for a scale question's average). Its value now is kept as the baseline (null when that group is hidden). At most 50 per survey. Supports dry_run. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_actions_createon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
survey_idstringrequired1–64 characters.
titlestringrequired3–200 characters.
owner_idstringrequired1–64 characters.
duestring | nullPattern
^\d{4}-\d{2}-\d{2}$.segmentobject | null2 fields
kindstring (enum)requiredOne of:
team,manager,location,entity,tenure,field,source.idstringrequired1–160 characters.
metricstringrequiredenps, or q:<question id> (a scale question).
Pattern
^(enps|q:[A-Za-z0-9_-]{1,40})$.
Returns
14 fields
idstringrequiredsurvey_idstringrequiredsurvey_titlestringrequiredround_nointegerrequiredsegmentobject | nullrequired3 fields
kindstringrequiredidstringrequirednamestringrequired
metricobjectrequired2 fields
keystringrequiredtitlestringrequired
baselinenumber | nullrequiredtitlestringrequiredownerobjectrequired2 fields
idstringrequirednamestringrequired
duestring | nullrequiredstatus"open" | "done"requiredcheckobject | nullrequiredThe latest later round with results: the same number for the same group (null value: hidden there).
3 fields
round_nointegerrequiredsurvey_idstringrequiredvaluenumber | nullrequired
created_atstringrequireddone_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/actions.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"survey_id": "s1",
"title": "Talk with the night shift",
"owner_id": "p3",
"metric": "q:workload",
"segment": {
"kind": "team",
"id": "u1"
}
}'const res = await fetch('https://api.bizisy.com/v1/surveys/actions.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"survey_id": "s1",
"title": "Talk with the night shift",
"owner_id": "p3",
"metric": "q:workload",
"segment": {
"kind": "team",
"id": "u1"
}
}),
});
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/surveys/actions.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"survey_id": "s1",
"title": "Talk with the night shift",
"owner_id": "p3",
"metric": "q:workload",
"segment": {
"kind": "team",
"id": "u1",
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "a1",
"survey_id": "s1",
"survey_title": "Team pulse",
"round_no": 3,
"segment": {
"kind": "team",
"id": "u1",
"name": "Engineering"
},
"metric": {
"key": "enps",
"title": "eNPS"
},
"baseline": 18,
"title": "Talk with the night shift",
"owner": {
"id": "p2",
"name": "Bea Silva"
},
"due": "2026-12-31",
"status": "open",
"check": {
"round_no": 4,
"survey_id": "s9",
"value": 31
},
"created_at": "2026-11-13T10:00:00.000Z",
"done_at": null
}
}Change an action from survey results#
POST/v1/surveys/actions.updateWrite
Changes an action: title, owner, due date, or status (done, or open again). Send only what changes. Supports dry_run. Owners, admins and HR; the owner may mark their own action done or open.
- Who can call it
- Manage key owner admin hr
Me key owner admin hr member - MCP tool
surveys_actions_updateon HR Assistant, My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
action_idstringrequired1–64 characters.
titlestring3–200 characters.
owner_idstring1–64 characters.
duestring | nullPattern
^\d{4}-\d{2}-\d{2}$.status"open" | "done"
Returns
14 fields
idstringrequiredsurvey_idstringrequiredsurvey_titlestringrequiredround_nointegerrequiredsegmentobject | nullrequired3 fields
kindstringrequiredidstringrequirednamestringrequired
metricobjectrequired2 fields
keystringrequiredtitlestringrequired
baselinenumber | nullrequiredtitlestringrequiredownerobjectrequired2 fields
idstringrequirednamestringrequired
duestring | nullrequiredstatus"open" | "done"requiredcheckobject | nullrequiredThe latest later round with results: the same number for the same group (null value: hidden there).
3 fields
round_nointegerrequiredsurvey_idstringrequiredvaluenumber | nullrequired
created_atstringrequireddone_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/actions.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"action_id":"a1","status":"done"}'const res = await fetch('https://api.bizisy.com/v1/surveys/actions.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"action_id": "a1",
"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/surveys/actions.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"action_id": "a1",
"status": "done",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "a1",
"survey_id": "s1",
"survey_title": "Team pulse",
"round_no": 3,
"segment": {
"kind": "team",
"id": "u1",
"name": "Engineering"
},
"metric": {
"key": "enps",
"title": "eNPS"
},
"baseline": 18,
"title": "Weekly focus time",
"owner": {
"id": "p2",
"name": "Bea Silva"
},
"due": "2026-12-31",
"status": "done",
"check": {
"round_no": 4,
"survey_id": "s9",
"value": 31
},
"created_at": "2026-11-13T10:00:00.000Z",
"done_at": "2026-11-20T10:00:00.000Z"
}
}Delete an action from survey results#
POST/v1/surveys/actions.deleteDestructive
Deletes an action. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_actions_deleteon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
action_idstringrequired1–64 characters.
Returns
deletedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/actions.delete \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"action_id":"a1"}'const res = await fetch('https://api.bizisy.com/v1/surveys/actions.delete', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"action_id": "a1"
}),
});
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/surveys/actions.delete",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"action_id": "a1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"deleted": true
}
}Set a survey's public link#
POST/v1/surveys/public.setWrite
Switches a survey's public link on or off and sets it: respondent (anonymous, default; or named: people give their name and, if they like, an email, not verified), max_answers (default 1000, up to 50,000), one_per_browser (default on), kiosk (allow a shared screen that resets after each answer), embed_domains (sites that may embed it in an iframe, up to 10; empty: no embedding). The link is https://{company address}/f/{id}. Only one-off custom surveys that are anonymous or named, with no people or location questions and nothing asking for passwords, card numbers or bank details, once the company's privacy notice link is set (surveys_settings_update privacy_url); it needs a close date when sent. The respondent setting is fixed once someone answered. A link Bizisy switched off stays off. Owners, admins and HR, in the app only.
- Web app only
- Refused for API keys and connected apps. A public link is switched on in the app, where its rules are shown.
- MCP tool
surveys_public_seton 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
survey_idstringrequired1–64 characters.
onbooleanrespondent"anonymous" | "named"max_answersintegerFrom 1 to 50000.
one_per_browserbooleankioskbooleanembed_domainsstring[]3–253 characters. Up to 10 items.
Returns
12 fields
onbooleanrequiredidstringrequiredurlstring | nullrequiredThe link (null until the server knows the company's address).
respondent"anonymous" | "named"requiredanonymous: nothing about who answers; named: they give their name (and an email if they like), not verified.
max_answersintegerrequiredone_per_browserbooleanrequiredkioskbooleanrequiredKiosk mode allowed: a shared screen (…/f/{id}?kiosk=1) resets after each answer and after a minute without a touch.
embed_domainsstring[]requiredSites that may embed it (an iframe); empty: embedding is off.
answeredintegerrequiredAnswers through the public link.
switched_off_by_bizisyobject | nullrequiredBizisy switched the link off (after reports): HR can't switch it on.
2 fields
atstringrequiredreasonstringrequired
reportsintegerrequiredproblemsobject[]requiredWhy it can't be public yet (empty: it can).
2 fields
atstringrequiredmessagestringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/surveys/public.set \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"survey_id": "s1",
"respondent": "named",
"max_answers": 500,
"embed_domains": [
"www.acme.example"
]
}'const res = await fetch('https://api.bizisy.com/v1/surveys/public.set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"survey_id": "s1",
"respondent": "named",
"max_answers": 500,
"embed_domains": [
"www.acme.example"
]
}),
});
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/surveys/public.set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"survey_id": "s1",
"respondent": "named",
"max_answers": 500,
"embed_domains": [
"www.acme.example",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"on": true,
"id": "Pk3mZ9xQ2rT7vW1yB4nD6f",
"url": "https://acme.bizisy.com/f/Pk3mZ9xQ2rT7vW1yB4nD6f",
"respondent": "named",
"max_answers": 500,
"one_per_browser": true,
"kiosk": false,
"embed_domains": [],
"answered": 0,
"switched_off_by_bizisy": null,
"reports": 0,
"problems": []
}
}Something missing or wrong on this page? Write to hello@bizisy.com.