API reference
Surveys and works councils
Each survey's works-council pack (what it asks, who sees what, thresholds, retention, where the data goes, country notes with sources), the council's approval before sending (asked by HR, decided by a login with Surveys at Approve, in the app only) and the council's results by group, never one person's answers.
5 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
A survey's works-council pack#
POST/v1/surveys/council.packRead
The facts a works council needs about one survey: what it asks (questions and types, which are shown only on conditions), the mode and what each role sees, the thresholds (smallest group, smallest group for comments, results in steps, combined filters doubled, the subtraction rule), retention (answers deleted N months after it closes, group results kept), where the data goes (Bizisy in the EU; the AI provider, Slack and a Google Sheets link when used) and the country notes for the company's legal entities, with sources. Owners, admins, HR and a works council login.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_council_packon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
survey_idstringrequired1–64 characters.
langstringPattern
^[a-z]{2}(-[A-Z]{2})?$.
Returns
8 fields
surveyobjectrequired6 fields
idstringrequiredtitlestringrequiredmode"named" | "confidential" | "anonymous"requiredstatusstringrequiredlanguagestringrequiredlanguagesstring[]required
questionsobject[]required5 fields
idstringrequiredtypestringrequiredtitlestringrequiredrequiredbooleanrequiredconditionalbooleanrequired
audienceobjectrequired6 fields
everyonebooleanrequiredteamsintegerrequiredlocationsintegerrequiredentitiesintegerrequiredgroupsintegerrequiredlifecycleobject | nullrequired2 fields
kindstringrequireddaysintegerrequired
privacyobjectrequired6 fields
thresholdintegerrequiredcomment_thresholdintegerrequiredstepsbooleanrequiredmanager_viewbooleanrequiredbandsstring[]requiredcombined_floorintegerrequired
retentionobjectrequired2 fields
monthsintegerrequiredpurged_atstring | nullrequired
data_flowobjectrequired4 fields
aibooleanrequiredslackbooleanrequiredsheets_linkbooleanrequiredremindersintegerrequired
countriesobject[]requiredCountry notes (general information, not legal advice): verified false marks a source known from a secondary source, to check.
8 fields
countrystringrequiredbodystringrequiredsummarystringrequiredemployer_stepsstring[]requiredsourcesobject[]required3 fields
titlestringrequiredurlstringrequiredverifiedbooleanrequired
uncertainstring | nullrequiredchecked_onstringrequiredeu_defaultbooleanrequired
councilobjectrequired3 fields
requiredbooleanrequiredstatus"not_asked" | "waiting" | "approved" | "returned" | "outdated"requiredoutdated: approved, then the survey changed.
entriesobject[]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/council.pack \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"survey_id":"s1","lang":"pt-PT"}'const res = await fetch('https://api.bizisy.com/v1/surveys/council.pack', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"survey_id": "s1",
"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/council.pack",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"survey_id": "s1",
"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": "draft",
"language": "en",
"languages": [
"pt-PT"
]
},
"questions": [
{
"id": "enps",
"type": "nps",
"title": "How likely are you to recommend working here?",
"required": true,
"conditional": false
}
],
"audience": {
"everyone": true,
"teams": 0,
"locations": 0,
"entities": 0,
"groups": 0,
"lifecycle": null
},
"privacy": {
"threshold": 5,
"comment_threshold": 10,
"steps": true,
"manager_view": true,
"bands": [],
"combined_floor": 10
},
"retention": {
"months": 24,
"purged_at": null
},
"data_flow": {
"ai": false,
"slack": false,
"sheets_link": false,
"reminders": 2
},
"countries": [
{
"country": "DE",
"body": "Betriebsrat",
"summary": "Co-determination applies.",
"employer_steps": [
"Agree it with the works council first."
],
"sources": [
{
"title": "§94 BetrVG",
"url": "https://www.gesetze-im-internet.de/betrvg/__94.html",
"verified": true
}
],
"uncertain": null,
"checked_on": "2026-11-16",
"eu_default": false
}
],
"council": {
"required": true,
"status": "waiting",
"entries": [
{
"kind": "asked",
"by": "Ana Costa",
"text": null,
"at": "2026-11-12T10:00:00.000Z"
}
]
}
}
}Surveys for the works council#
POST/v1/surveys/council.listRead
For a works council: the company's surveys (not archived), waiting for the council first, then the others, with their council status. Owners, admins, HR and a works council login.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_council_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
requiredbooleanrequireditemsobject[]required22 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).
councilobjectrequired3 fields
requiredbooleanrequiredstatus"not_asked" | "waiting" | "approved" | "returned" | "outdated"requiredoutdated: approved, then the survey changed.
entriesobject[]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/council.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/surveys/council.list', {
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/council.list",
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": {
"required": true,
"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,
"council": {
"required": true,
"status": "waiting",
"entries": []
}
}
]
}
}A survey's results for the works council#
POST/v1/surveys/council.resultsRead
A survey's results by group for a works council login: exactly what surveys_results_get shows HR (the same thresholds, steps and hidden groups), never one person's answers, not even in a named survey (option counts and averages only; no comments of a named survey). Owners, admins, HR and a works council login.
- Who can call it
- Manage key owner admin hr
- MCP tool
surveys_council_resultson 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
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/council.results \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"survey_id":"s1","segment":{"kind":"location","id":"l1"}}'const res = await fetch('https://api.bizisy.com/v1/surveys/council.results', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"survey_id": "s1",
"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/council.results",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"survey_id": "s1",
"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": {
"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
}
]
}
}Ask the works council to approve a survey#
POST/v1/surveys/council.requestWrite
Asks the works council to approve a draft survey (when the company asks for its approval: surveys_settings_update council_approval). Council members (a custom role with Surveys at Approve) get an email with a link to its pack. While it waits, it can't be sent; an approval covers the questions, mode, thresholds and audience as they are now. In the app only (API keys and AI assistants are refused). Supports dry_run. Owners, admins and HR.
- Web app only
- Refused for API keys and connected apps. HR asks the works council in the app.
- MCP tool
surveys_council_requeston 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.
notestringUp to 2000 characters.
Returns
requiredbooleanrequiredstatus"not_asked" | "waiting" | "approved" | "returned" | "outdated"requiredoutdated: approved, then the survey changed.
entriesobject[]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/council.request \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"survey_id": "s1",
"note": "Our yearly pulse: same questions as last year."
}'const res = await fetch('https://api.bizisy.com/v1/surveys/council.request', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"survey_id": "s1",
"note": "Our yearly pulse: same questions as last year."
}),
});
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/council.request",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"survey_id": "s1",
"note": "Our yearly pulse: same questions as last year.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"required": true,
"status": "waiting",
"entries": [
{
"kind": "asked",
"by": "Ana Costa",
"text": null,
"at": "2026-11-12T10:00:00.000Z"
}
]
}
}Approve a survey for the works council, or send it back#
POST/v1/surveys/council.decideWrite
For a works council member (a custom role with Surveys at Approve): approve a survey waiting for the council, send it back with a comment (comment required), or add a comment. Who and when is kept with the survey; HR who asked gets an email. In the app only (API keys and AI assistants are refused).
- Web app only
- Refused for API keys and connected apps. The works council decides in the app.
- MCP tool
surveys_council_decideon 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.
decision"approve" | "return" | "comment"requiredcommentstringUp to 2000 characters.
Returns
requiredbooleanrequiredstatus"not_asked" | "waiting" | "approved" | "returned" | "outdated"requiredoutdated: approved, then the survey changed.
entriesobject[]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/council.decide \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"survey_id":"s1","decision":"return","comment":"Leave out question 4."}'const res = await fetch('https://api.bizisy.com/v1/surveys/council.decide', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"survey_id": "s1",
"decision": "return",
"comment": "Leave out question 4."
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/surveys/council.decide",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"survey_id": "s1",
"decision": "return",
"comment": "Leave out question 4.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"required": true,
"status": "approved",
"entries": [
{
"kind": "approved",
"by": "Rita Conselho",
"text": null,
"at": "2026-11-12T15:00:00.000Z"
}
]
}
}Something missing or wrong on this page? Write to hello@bizisy.com.