Skip to content

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_pack on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • survey_idstringrequired

    1–64 characters.

  • langstring

    Pattern ^[a-z]{2}(-[A-Z]{2})?$.

Returns

8 fields
  • surveyobjectrequired
    6 fields
    • idstringrequired
    • titlestringrequired
    • mode"named" | "confidential" | "anonymous"required
    • statusstringrequired
    • languagestringrequired
    • languagesstring[]required
  • questionsobject[]required
    5 fields
    • idstringrequired
    • typestringrequired
    • titlestringrequired
    • requiredbooleanrequired
    • conditionalbooleanrequired
  • audienceobjectrequired
    6 fields
    • everyonebooleanrequired
    • teamsintegerrequired
    • locationsintegerrequired
    • entitiesintegerrequired
    • groupsintegerrequired
    • lifecycleobject | nullrequired
      2 fields
      • kindstringrequired
      • daysintegerrequired
  • privacyobjectrequired
    6 fields
    • thresholdintegerrequired
    • comment_thresholdintegerrequired
    • stepsbooleanrequired
    • manager_viewbooleanrequired
    • bandsstring[]required
    • combined_floorintegerrequired
  • retentionobjectrequired
    2 fields
    • monthsintegerrequired
    • purged_atstring | nullrequired
  • data_flowobjectrequired
    4 fields
    • aibooleanrequired
    • slackbooleanrequired
    • sheets_linkbooleanrequired
    • remindersintegerrequired
  • countriesobject[]required

    Country notes (general information, not legal advice): verified false marks a source known from a secondary source, to check.

    8 fields
    • countrystringrequired
    • bodystringrequired
    • summarystringrequired
    • employer_stepsstring[]required
    • sourcesobject[]required
      3 fields
      • titlestringrequired
      • urlstringrequired
      • verifiedbooleanrequired
    • uncertainstring | nullrequired
    • checked_onstringrequired
    • eu_defaultbooleanrequired
  • councilobjectrequired
    3 fields
    • requiredbooleanrequired
    • status"not_asked" | "waiting" | "approved" | "returned" | "outdated"required

      outdated: approved, then the survey changed.

    • entriesobject[]required
      4 fields
      • kind"asked" | "approved" | "returned" | "comment"required
      • bystringrequired
      • textstring | nullrequired
      • atstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • requiredbooleanrequired
  • itemsobject[]required
    22 fields
    • idstringrequired
    • titlestringrequired
    • mode"named" | "confidential" | "anonymous"required
    • status"draft" | "scheduled" | "open" | "closed"required
    • archivedbooleanrequired
    • questionsintegerrequired
    • languagestringrequired
    • languagesstring[]required
    • recipientsintegerrequired
    • answeredinteger | nullrequired

      null while fewer than the threshold answered a confidential survey (see answered_under).

    • answered_underinteger | nullrequired

      Confidential: "under N" when fewer than N answered.

    • open_atstring | nullrequired
    • opened_atstring | nullrequired
    • close_atstring | nullrequired
    • closed_atstring | nullrequired
    • created_atstringrequired
    • updated_atstringrequired
    • kind"custom" | "listening"required
    • series_idstring | nullrequired

      Recurring surveys: the series (its first round's id); null for a one-off.

    • round_nointegerrequired

      Which round of its series (1 for a one-off).

    • recurringbooleanrequired

      The series still sends new rounds (stop it with surveys_series_stop).

    • councilobjectrequired
      3 fields
      • requiredbooleanrequired
      • status"not_asked" | "waiting" | "approved" | "returned" | "outdated"required

        outdated: approved, then the survey changed.

      • entriesobject[]required
        4 fields
        • kind"asked" | "approved" | "returned" | "comment"required
        • bystringrequired
        • textstring | nullrequired
        • atstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/surveys/council.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_results on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • survey_idstringrequired

    1–64 characters.

  • segmentobject
    2 fields
    • kindstring (enum)required

      One of: team, manager, location, entity, tenure, field, source.

    • idstringrequired

      1–160 characters.

  • langstring

    Pattern ^[a-z]{2}(-[A-Z]{2})?$.

Returns

14 fields
  • survey_idstringrequired
  • titlestringrequired
  • mode"named" | "confidential" | "anonymous"required
  • statusstringrequired
  • thresholdintegerrequired
  • comment_thresholdintegerrequired
  • segmentobject | nullrequired
    3 fields
    • kindstring (enum)required

      One of: team, manager, location, entity, tenure, field, source.

    • idstringrequired

      1–160 characters.

    • namestringrequired
  • respondentsinteger | nullrequired

    Submitted answers in this view (null when hidden).

  • hiddenbooleanrequired

    true: the numbers are withheld (fewer people than the threshold, or the next-smallest rule).

  • underinteger | nullrequired

    Hidden because fewer than N answered: N. Hidden with under null: shown, it would let someone work out a smaller hidden group by subtraction.

  • includedinteger | nullrequired

    How many of those answers the results include. Confidential surveys publish in steps of the threshold (never moved by one answer); null when hidden.

  • rateobjectrequired
    6 fields
    • invitedintegerrequired
    • answeredinteger | nullrequired
    • ratenumber | nullrequired

      0–1; null when hidden or nobody invited.

    • hiddenbooleanrequired

      true: the numbers are withheld (fewer people than the threshold, or the next-smallest rule).

    • underinteger | nullrequired

      Hidden because fewer than N answered: N. Hidden with under null: shown, it would let someone work out a smaller hidden group by subtraction.

    • byobject[]required
      8 fields
      • invitedintegerrequired
      • answeredinteger | nullrequired
      • ratenumber | nullrequired

        0–1; null when hidden or nobody invited.

      • hiddenbooleanrequired

        true: the numbers are withheld (fewer people than the threshold, or the next-smallest rule).

      • underinteger | nullrequired

        Hidden 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)required

        One of: team, manager, location, entity, tenure, field, source.

      • idstringrequired
      • namestringrequired
  • questionsobject[]required
    18 fields
    • idstringrequired
    • typestringrequired
    • titlestringrequired
    • pageintegerrequired
    • ninteger | nullrequired

      How many answered it (null when hidden).

    • hiddenbooleanrequired

      true: the numbers are withheld (fewer people than the threshold, or the next-smallest rule).

    • underinteger | nullrequired

      Hidden because fewer than N answered: N. Hidden with under null: shown, it would let someone work out a smaller hidden group by subtraction.

    • optionsobject[] | nullrequired

      Choices, scale points, yes/no, locations: count and share.

      4 fields
      • idstringrequired
      • labelstringrequired
      • countintegerrequired
      • sharenumberrequired

        0–1 of those who answered the question.

    • rowsobject[] | nullrequired

      Matrix: per row.

      3 fields
      • idstringrequired
      • labelstringrequired
      • optionsobject[]required
        4 fields
        • idstringrequired
        • labelstringrequired
        • countintegerrequired
        • sharenumberrequired

          0–1 of those who answered the question.

    • rankingobject[] | nullrequired
      3 fields
      • idstringrequired
      • labelstringrequired
      • average_ranknumberrequired
    • meannumber | nullrequired
    • minnumber | nullrequired
    • maxnumber | nullrequired
    • enpsobject | nullrequired

      0–10 questions: eNPS = % promoters (9–10) − % detractors (0–6).

      5 fields
      • scoreintegerrequired
      • promotersintegerrequired
      • passivesintegerrequired
      • detractorsintegerrequired
      • nintegerrequired
    • commentsstring[] | nullrequired

      Free-text answers (confidential: masked, in alphabetical order, only from the comment threshold up; null when hidden).

    • comments_hiddenbooleanrequired
    • comments_underinteger | nullrequired
    • comment_idsstring | null[] | null

      Each comment's opaque id, in the same order (reply with surveys_comments_reply); null for comments sent before replies existed.

  • publicobject | null

    Its 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
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"}}'
Response
{
  "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_request on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • survey_idstringrequired

    1–64 characters.

  • notestring

    Up to 2000 characters.

Returns

  • requiredbooleanrequired
  • status"not_asked" | "waiting" | "approved" | "returned" | "outdated"required

    outdated: approved, then the survey changed.

  • entriesobject[]required
    4 fields
    • kind"asked" | "approved" | "returned" | "comment"required
    • bystringrequired
    • textstring | nullrequired
    • atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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."
}'
Response
{
  "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_decide on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • survey_idstringrequired

    1–64 characters.

  • decision"approve" | "return" | "comment"required
  • commentstring

    Up to 2000 characters.

Returns

  • requiredbooleanrequired
  • status"not_asked" | "waiting" | "approved" | "returned" | "outdated"required

    outdated: approved, then the survey changed.

  • entriesobject[]required
    4 fields
    • kind"asked" | "approved" | "returned" | "comment"required
    • bystringrequired
    • textstring | nullrequired
    • atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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."}'
Response
{
  "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.

Developer docs