Skip to content

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

Input

  • archivedboolean

    true: only archived surveys.

  • status"draft" | "scheduled" | "open" | "closed"

Returns

  • itemsobject[]required
    21 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).

  • totalintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

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

Input

  • survey_idstringrequired

    1–64 characters.

Returns

38 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).

  • definitionobjectrequired

    The 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
    • languagestringrequired

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

    • languagesstring[]required

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

    • translationsobjectrequired
    • coverobjectrequired
      3 fields
      • showbooleanrequired
      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

    • thanksobjectrequired
      5 fields
      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

      • link_urlstring | null

        Up to 500 characters. Pattern ^https:\/\/[^\s]+$.

      • link_labelstring | null

        Up to 80 characters.

      • redirect_urlstring | null

        Up to 500 characters. Pattern ^https:\/\/[^\s]+$.

    • layout"one" | "page"required
    • progressbooleanrequired
    • logobooleanrequired
    • themeobject

      How 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 | null

        A background image id from surveys_design_image_upload.

        Pattern ^[0-9a-z]{26}$.

      • image_diminteger

        How 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[]required

      1–50 items.

      6 fields
      • idstringrequired

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

      • titlestring | null

        Up to 300 characters.

      • descriptionstring | null

        Up to 2000 characters.

      • questionsobject[]required

        Up to 200 items.

        22 fields
        • idstringrequired

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

        • typestring (enum)required

          One of: single, multi, dropdown, nps, likert, star, emoji, slider, ranking, matrix, short_text, long_text, number, date, yes_no, people, location, statement, consent.

        • titlestringrequired

          Up to 1000 characters.

        • descriptionstring | null

          Up to 2000 characters.

        • requiredboolean
        • required_messagestring | null

          Up to 200 characters.

        • choicesobject[]

          Up to 100 items.

          4 fields
          • idstringrequired

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

          • labelstringrequired

            Up to 500 characters.

          • scorenumber | null
          • quotainteger | null

            From 1 to 100000.

        • otherboolean
        • randomizeboolean
        • max_picksinteger | null

          From 1 to 100.

        • points5 | 7
        • minnumber | null
        • maxnumber | null
        • stepnumber | null

          At least 0.

        • low_labelstring | null

          Up to 80 characters.

        • high_labelstring | null

          Up to 80 characters.

        • rowsobject[]

          Up to 100 items.

          4 fields
          • idstringrequired

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

          • labelstringrequired

            Up to 500 characters.

          • scorenumber | null
          • quotainteger | null

            From 1 to 100000.

        • max_lengthinteger | null

          From 1 to 5000.

        • show_ifobject | null
          2 fields
          • match"all" | "any"required
          • rulesobject[]required

            Up to 20 items.

        • score_intoobject | null
          2 fields
          • variablestringrequired

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

          • weightnumber
        • library_idstring | null

          The library item it was copied from (surveys_library_list): rounds and trends compare by it.

          Pattern ^lib\.[a-z]+\.[a-z]+$.

        • driverstring | null

          The engagement driver it measures (engagement, recognition, growth, manager, workload, autonomy, belonging, purpose, communication, wellbeing, fairness).

          Pattern ^[a-z_]{2,30}$.

      • randomize_questionsboolean
      • jumpsobject[]

        Up to 20 items.

        2 fields
        • whenobjectrequired
          2 fields
          • match"all" | "any"required
          • rulesobject[]required

            Up to 20 items.

        • tostring | "end"required
    • variablesobject[]required

      Up to 20 items.

      3 fields
      • idstringrequired

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

      • namestringrequired

        Up to 80 characters.

      • initialnumber
    • outcomesobject[]required

      Up to 20 items.

      4 fields
      • idstringrequired

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

      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

      • whenobjectrequired
        2 fields
        • match"all" | "any"required
        • rulesobject[]required

          Up to 20 items.

          5 fields
          • qstring

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

          • vstring

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

          • f"team" | "location" | "entity" | "language"
          • opstring (enum)required

            One of: eq, neq, gt, gte, lt, lte, includes, excludes, answered, not_answered.

          • valuestring | number | boolean | "null"
  • thresholdintegerrequired
  • comment_thresholdintegerrequired
  • audienceobjectrequired
    5 fields
    • everyoneboolean

      Default 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[]required
  • problemsobject[]required

    What stops it from opening (empty: ready).

    2 fields
    • atstringrequired
    • messagestringrequired
  • lockedbooleanrequired

    Opened once: the mode and questions are fixed; translations, reminders and the close date can still change.

  • manager_viewbooleanrequired

    Managers see their own line's results in My workspace (above the threshold, never a sub-line that could be worked out).

  • recurrenceobject | nullrequired

    The series' schedule (on its first round).

    2 fields
    • every"week" | "two_weeks" | "month" | "quarter" | "half_year" | "year"required
    • open_daysinteger

      From 1 to 60. Default 7.

  • anonymous_bands"team" | "location" | "tenure"[]required

    Anonymous surveys: the coarse bands kept with each answer.

  • fatigue_skippedintegerrequired

    People left out at sending: they already had their surveys this month.

  • triggerobject | nullrequired

    Lifecycle: 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"required

      start: 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.

    • daysintegerrequired

      From 0 to 365.

  • slackbooleanrequired

    Invitations and reminders also go as Slack direct messages where the company connected Slack.

  • retention_monthsintegerrequired

    Answers are deleted this many months after it closes; the group results are kept.

  • purged_atstring | nullrequired

    When its answers were deleted (retention); results then come from the kept group results.

  • publicobject | nullrequired

    Its public link (surveys_public_set); null: never set.

    10 fields
    • onbooleanrequired
    • idstringrequired
    • respondent"anonymous" | "named"required
    • max_answersintegerrequired
    • one_per_browserbooleanrequired
    • kioskbooleanrequired
    • embed_domainsstring[]required
    • answeredintegerrequired
    • switched_off_by_bizisybooleanrequired
    • reportsintegerrequired
  • councilobjectrequired

    The works council's approval (when the company asks for it, surveys_settings_get council_approval).

    3 fields
    • status"not_asked" | "waiting" | "approved" | "returned"required
    • approved_for_this_versionbooleanrequired
    • 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/surveys.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"survey_id":"s1"}'
Response
{
  "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_create on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • titlestringrequired

    1–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".

  • languagestring

    The 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".

  • definitionobject

    The 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
    • languagestringrequired

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

    • languagesstring[]required

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

    • translationsobjectrequired
    • coverobjectrequired
      3 fields
      • showbooleanrequired
      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

    • thanksobjectrequired
      5 fields
      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

      • link_urlstring | null

        Up to 500 characters. Pattern ^https:\/\/[^\s]+$.

      • link_labelstring | null

        Up to 80 characters.

      • redirect_urlstring | null

        Up to 500 characters. Pattern ^https:\/\/[^\s]+$.

    • layout"one" | "page"required
    • progressbooleanrequired
    • logobooleanrequired
    • themeobject

      How 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 | null

        A background image id from surveys_design_image_upload.

        Pattern ^[0-9a-z]{26}$.

      • image_diminteger

        How 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[]required

      1–50 items.

      6 fields
      • idstringrequired

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

      • titlestring | null

        Up to 300 characters.

      • descriptionstring | null

        Up to 2000 characters.

      • questionsobject[]required

        Up to 200 items.

        22 fields
        • idstringrequired

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

        • typestring (enum)required

          One of: single, multi, dropdown, nps, likert, star, emoji, slider, ranking, matrix, short_text, long_text, number, date, yes_no, people, location, statement, consent.

        • titlestringrequired

          Up to 1000 characters.

        • descriptionstring | null

          Up to 2000 characters.

        • requiredboolean
        • required_messagestring | null

          Up to 200 characters.

        • choicesobject[]

          Up to 100 items.

          4 fields
          • idstringrequired

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

          • labelstringrequired

            Up to 500 characters.

          • scorenumber | null
          • quotainteger | null

            From 1 to 100000.

        • otherboolean
        • randomizeboolean
        • max_picksinteger | null

          From 1 to 100.

        • points5 | 7
        • minnumber | null
        • maxnumber | null
        • stepnumber | null

          At least 0.

        • low_labelstring | null

          Up to 80 characters.

        • high_labelstring | null

          Up to 80 characters.

        • rowsobject[]

          Up to 100 items.

          4 fields
          • idstringrequired

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

          • labelstringrequired

            Up to 500 characters.

          • scorenumber | null
          • quotainteger | null

            From 1 to 100000.

        • max_lengthinteger | null

          From 1 to 5000.

        • show_ifobject | null
          2 fields
          • match"all" | "any"required
          • rulesobject[]required

            Up to 20 items.

        • score_intoobject | null
          2 fields
          • variablestringrequired

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

          • weightnumber
        • library_idstring | null

          The library item it was copied from (surveys_library_list): rounds and trends compare by it.

          Pattern ^lib\.[a-z]+\.[a-z]+$.

        • driverstring | null

          The engagement driver it measures (engagement, recognition, growth, manager, workload, autonomy, belonging, purpose, communication, wellbeing, fairness).

          Pattern ^[a-z_]{2,30}$.

      • randomize_questionsboolean
      • jumpsobject[]

        Up to 20 items.

        2 fields
        • whenobjectrequired
          2 fields
          • match"all" | "any"required
          • rulesobject[]required

            Up to 20 items.

        • tostring | "end"required
    • variablesobject[]required

      Up to 20 items.

      3 fields
      • idstringrequired

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

      • namestringrequired

        Up to 80 characters.

      • initialnumber
    • outcomesobject[]required

      Up to 20 items.

      4 fields
      • idstringrequired

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

      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

      • whenobjectrequired
        2 fields
        • match"all" | "any"required
        • rulesobject[]required

          Up to 20 items.

          5 fields
          • qstring

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

          • vstring

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

          • f"team" | "location" | "entity" | "language"
          • opstring (enum)required

            One 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.

  • audienceobject
    5 fields
    • everyoneboolean

      Default 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
  • 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).

  • definitionobjectrequired

    The 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
    • languagestringrequired

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

    • languagesstring[]required

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

    • translationsobjectrequired
    • coverobjectrequired
      3 fields
      • showbooleanrequired
      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

    • thanksobjectrequired
      5 fields
      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

      • link_urlstring | null

        Up to 500 characters. Pattern ^https:\/\/[^\s]+$.

      • link_labelstring | null

        Up to 80 characters.

      • redirect_urlstring | null

        Up to 500 characters. Pattern ^https:\/\/[^\s]+$.

    • layout"one" | "page"required
    • progressbooleanrequired
    • logobooleanrequired
    • themeobject

      How 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 | null

        A background image id from surveys_design_image_upload.

        Pattern ^[0-9a-z]{26}$.

      • image_diminteger

        How 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[]required

      1–50 items.

      6 fields
      • idstringrequired

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

      • titlestring | null

        Up to 300 characters.

      • descriptionstring | null

        Up to 2000 characters.

      • questionsobject[]required

        Up to 200 items.

        22 fields
        • idstringrequired

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

        • typestring (enum)required

          One of: single, multi, dropdown, nps, likert, star, emoji, slider, ranking, matrix, short_text, long_text, number, date, yes_no, people, location, statement, consent.

        • titlestringrequired

          Up to 1000 characters.

        • descriptionstring | null

          Up to 2000 characters.

        • requiredboolean
        • required_messagestring | null

          Up to 200 characters.

        • choicesobject[]

          Up to 100 items.

          4 fields
          • idstringrequired

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

          • labelstringrequired

            Up to 500 characters.

          • scorenumber | null
          • quotainteger | null

            From 1 to 100000.

        • otherboolean
        • randomizeboolean
        • max_picksinteger | null

          From 1 to 100.

        • points5 | 7
        • minnumber | null
        • maxnumber | null
        • stepnumber | null

          At least 0.

        • low_labelstring | null

          Up to 80 characters.

        • high_labelstring | null

          Up to 80 characters.

        • rowsobject[]

          Up to 100 items.

          4 fields
          • idstringrequired

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

          • labelstringrequired

            Up to 500 characters.

          • scorenumber | null
          • quotainteger | null

            From 1 to 100000.

        • max_lengthinteger | null

          From 1 to 5000.

        • show_ifobject | null
          2 fields
          • match"all" | "any"required
          • rulesobject[]required

            Up to 20 items.

        • score_intoobject | null
          2 fields
          • variablestringrequired

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

          • weightnumber
        • library_idstring | null

          The library item it was copied from (surveys_library_list): rounds and trends compare by it.

          Pattern ^lib\.[a-z]+\.[a-z]+$.

        • driverstring | null

          The engagement driver it measures (engagement, recognition, growth, manager, workload, autonomy, belonging, purpose, communication, wellbeing, fairness).

          Pattern ^[a-z_]{2,30}$.

      • randomize_questionsboolean
      • jumpsobject[]

        Up to 20 items.

        2 fields
        • whenobjectrequired
          2 fields
          • match"all" | "any"required
          • rulesobject[]required

            Up to 20 items.

        • tostring | "end"required
    • variablesobject[]required

      Up to 20 items.

      3 fields
      • idstringrequired

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

      • namestringrequired

        Up to 80 characters.

      • initialnumber
    • outcomesobject[]required

      Up to 20 items.

      4 fields
      • idstringrequired

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

      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

      • whenobjectrequired
        2 fields
        • match"all" | "any"required
        • rulesobject[]required

          Up to 20 items.

          5 fields
          • qstring

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

          • vstring

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

          • f"team" | "location" | "entity" | "language"
          • opstring (enum)required

            One of: eq, neq, gt, gte, lt, lte, includes, excludes, answered, not_answered.

          • valuestring | number | boolean | "null"
  • thresholdintegerrequired
  • comment_thresholdintegerrequired
  • audienceobjectrequired
    5 fields
    • everyoneboolean

      Default 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[]required
  • problemsobject[]required

    What stops it from opening (empty: ready).

    2 fields
    • atstringrequired
    • messagestringrequired
  • lockedbooleanrequired

    Opened once: the mode and questions are fixed; translations, reminders and the close date can still change.

  • manager_viewbooleanrequired

    Managers see their own line's results in My workspace (above the threshold, never a sub-line that could be worked out).

  • recurrenceobject | nullrequired

    The series' schedule (on its first round).

    2 fields
    • every"week" | "two_weeks" | "month" | "quarter" | "half_year" | "year"required
    • open_daysinteger

      From 1 to 60. Default 7.

  • anonymous_bands"team" | "location" | "tenure"[]required

    Anonymous surveys: the coarse bands kept with each answer.

  • fatigue_skippedintegerrequired

    People left out at sending: they already had their surveys this month.

  • triggerobject | nullrequired

    Lifecycle: 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"required

      start: 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.

    • daysintegerrequired

      From 0 to 365.

  • slackbooleanrequired

    Invitations and reminders also go as Slack direct messages where the company connected Slack.

  • retention_monthsintegerrequired

    Answers are deleted this many months after it closes; the group results are kept.

  • purged_atstring | nullrequired

    When its answers were deleted (retention); results then come from the kept group results.

  • publicobject | nullrequired

    Its public link (surveys_public_set); null: never set.

    10 fields
    • onbooleanrequired
    • idstringrequired
    • respondent"anonymous" | "named"required
    • max_answersintegerrequired
    • one_per_browserbooleanrequired
    • kioskbooleanrequired
    • embed_domainsstring[]required
    • answeredintegerrequired
    • switched_off_by_bizisybooleanrequired
    • reportsintegerrequired
  • councilobjectrequired

    The works council's approval (when the company asks for it, surveys_settings_get council_approval).

    3 fields
    • status"not_asked" | "waiting" | "approved" | "returned"required
    • approved_for_this_versionbooleanrequired
    • 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/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": []
  }
}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • survey_idstringrequired

    1–64 characters.

  • titlestring

    1–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.

  • definitionobject

    The 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
    • languagestringrequired

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

    • languagesstring[]required

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

    • translationsobjectrequired
    • coverobjectrequired
      3 fields
      • showbooleanrequired
      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

    • thanksobjectrequired
      5 fields
      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

      • link_urlstring | null

        Up to 500 characters. Pattern ^https:\/\/[^\s]+$.

      • link_labelstring | null

        Up to 80 characters.

      • redirect_urlstring | null

        Up to 500 characters. Pattern ^https:\/\/[^\s]+$.

    • layout"one" | "page"required
    • progressbooleanrequired
    • logobooleanrequired
    • themeobject

      How 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 | null

        A background image id from surveys_design_image_upload.

        Pattern ^[0-9a-z]{26}$.

      • image_diminteger

        How 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[]required

      1–50 items.

      6 fields
      • idstringrequired

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

      • titlestring | null

        Up to 300 characters.

      • descriptionstring | null

        Up to 2000 characters.

      • questionsobject[]required

        Up to 200 items.

        22 fields
        • idstringrequired

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

        • typestring (enum)required

          One of: single, multi, dropdown, nps, likert, star, emoji, slider, ranking, matrix, short_text, long_text, number, date, yes_no, people, location, statement, consent.

        • titlestringrequired

          Up to 1000 characters.

        • descriptionstring | null

          Up to 2000 characters.

        • requiredboolean
        • required_messagestring | null

          Up to 200 characters.

        • choicesobject[]

          Up to 100 items.

          4 fields
          • idstringrequired

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

          • labelstringrequired

            Up to 500 characters.

          • scorenumber | null
          • quotainteger | null

            From 1 to 100000.

        • otherboolean
        • randomizeboolean
        • max_picksinteger | null

          From 1 to 100.

        • points5 | 7
        • minnumber | null
        • maxnumber | null
        • stepnumber | null

          At least 0.

        • low_labelstring | null

          Up to 80 characters.

        • high_labelstring | null

          Up to 80 characters.

        • rowsobject[]

          Up to 100 items.

          4 fields
          • idstringrequired

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

          • labelstringrequired

            Up to 500 characters.

          • scorenumber | null
          • quotainteger | null

            From 1 to 100000.

        • max_lengthinteger | null

          From 1 to 5000.

        • show_ifobject | null
          2 fields
          • match"all" | "any"required
          • rulesobject[]required

            Up to 20 items.

        • score_intoobject | null
          2 fields
          • variablestringrequired

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

          • weightnumber
        • library_idstring | null

          The library item it was copied from (surveys_library_list): rounds and trends compare by it.

          Pattern ^lib\.[a-z]+\.[a-z]+$.

        • driverstring | null

          The engagement driver it measures (engagement, recognition, growth, manager, workload, autonomy, belonging, purpose, communication, wellbeing, fairness).

          Pattern ^[a-z_]{2,30}$.

      • randomize_questionsboolean
      • jumpsobject[]

        Up to 20 items.

        2 fields
        • whenobjectrequired
          2 fields
          • match"all" | "any"required
          • rulesobject[]required

            Up to 20 items.

        • tostring | "end"required
    • variablesobject[]required

      Up to 20 items.

      3 fields
      • idstringrequired

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

      • namestringrequired

        Up to 80 characters.

      • initialnumber
    • outcomesobject[]required

      Up to 20 items.

      4 fields
      • idstringrequired

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

      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

      • whenobjectrequired
        2 fields
        • match"all" | "any"required
        • rulesobject[]required

          Up to 20 items.

          5 fields
          • qstring

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

          • vstring

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

          • f"team" | "location" | "entity" | "language"
          • opstring (enum)required

            One of: eq, neq, gt, gte, lt, lte, includes, excludes, answered, not_answered.

          • valuestring | number | boolean | "null"
  • thresholdinteger

    From 3 to 50.

  • comment_thresholdinteger

    From 3 to 100.

  • audienceobject
    5 fields
    • everyoneboolean

      Default 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 | null

    When it closes by itself (null: when you close it).

    ISO 8601 date and time (UTC).

  • manager_viewboolean

    Managers 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 | null

    Lifecycle: 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"required

      start: 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.

    • daysintegerrequired

      From 0 to 365.

  • slackboolean

    Also send invitations and reminders as Slack direct messages where the company connected Slack (held outside working time like emails).

  • retention_monthsinteger

    Delete 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
  • 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).

  • definitionobjectrequired

    The 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
    • languagestringrequired

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

    • languagesstring[]required

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

    • translationsobjectrequired
    • coverobjectrequired
      3 fields
      • showbooleanrequired
      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

    • thanksobjectrequired
      5 fields
      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

      • link_urlstring | null

        Up to 500 characters. Pattern ^https:\/\/[^\s]+$.

      • link_labelstring | null

        Up to 80 characters.

      • redirect_urlstring | null

        Up to 500 characters. Pattern ^https:\/\/[^\s]+$.

    • layout"one" | "page"required
    • progressbooleanrequired
    • logobooleanrequired
    • themeobject

      How 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 | null

        A background image id from surveys_design_image_upload.

        Pattern ^[0-9a-z]{26}$.

      • image_diminteger

        How 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[]required

      1–50 items.

      6 fields
      • idstringrequired

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

      • titlestring | null

        Up to 300 characters.

      • descriptionstring | null

        Up to 2000 characters.

      • questionsobject[]required

        Up to 200 items.

        22 fields
        • idstringrequired

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

        • typestring (enum)required

          One of: single, multi, dropdown, nps, likert, star, emoji, slider, ranking, matrix, short_text, long_text, number, date, yes_no, people, location, statement, consent.

        • titlestringrequired

          Up to 1000 characters.

        • descriptionstring | null

          Up to 2000 characters.

        • requiredboolean
        • required_messagestring | null

          Up to 200 characters.

        • choicesobject[]

          Up to 100 items.

          4 fields
          • idstringrequired

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

          • labelstringrequired

            Up to 500 characters.

          • scorenumber | null
          • quotainteger | null

            From 1 to 100000.

        • otherboolean
        • randomizeboolean
        • max_picksinteger | null

          From 1 to 100.

        • points5 | 7
        • minnumber | null
        • maxnumber | null
        • stepnumber | null

          At least 0.

        • low_labelstring | null

          Up to 80 characters.

        • high_labelstring | null

          Up to 80 characters.

        • rowsobject[]

          Up to 100 items.

          4 fields
          • idstringrequired

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

          • labelstringrequired

            Up to 500 characters.

          • scorenumber | null
          • quotainteger | null

            From 1 to 100000.

        • max_lengthinteger | null

          From 1 to 5000.

        • show_ifobject | null
          2 fields
          • match"all" | "any"required
          • rulesobject[]required

            Up to 20 items.

        • score_intoobject | null
          2 fields
          • variablestringrequired

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

          • weightnumber
        • library_idstring | null

          The library item it was copied from (surveys_library_list): rounds and trends compare by it.

          Pattern ^lib\.[a-z]+\.[a-z]+$.

        • driverstring | null

          The engagement driver it measures (engagement, recognition, growth, manager, workload, autonomy, belonging, purpose, communication, wellbeing, fairness).

          Pattern ^[a-z_]{2,30}$.

      • randomize_questionsboolean
      • jumpsobject[]

        Up to 20 items.

        2 fields
        • whenobjectrequired
          2 fields
          • match"all" | "any"required
          • rulesobject[]required

            Up to 20 items.

        • tostring | "end"required
    • variablesobject[]required

      Up to 20 items.

      3 fields
      • idstringrequired

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

      • namestringrequired

        Up to 80 characters.

      • initialnumber
    • outcomesobject[]required

      Up to 20 items.

      4 fields
      • idstringrequired

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

      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

      • whenobjectrequired
        2 fields
        • match"all" | "any"required
        • rulesobject[]required

          Up to 20 items.

          5 fields
          • qstring

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

          • vstring

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

          • f"team" | "location" | "entity" | "language"
          • opstring (enum)required

            One of: eq, neq, gt, gte, lt, lte, includes, excludes, answered, not_answered.

          • valuestring | number | boolean | "null"
  • thresholdintegerrequired
  • comment_thresholdintegerrequired
  • audienceobjectrequired
    5 fields
    • everyoneboolean

      Default 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[]required
  • problemsobject[]required

    What stops it from opening (empty: ready).

    2 fields
    • atstringrequired
    • messagestringrequired
  • lockedbooleanrequired

    Opened once: the mode and questions are fixed; translations, reminders and the close date can still change.

  • manager_viewbooleanrequired

    Managers see their own line's results in My workspace (above the threshold, never a sub-line that could be worked out).

  • recurrenceobject | nullrequired

    The series' schedule (on its first round).

    2 fields
    • every"week" | "two_weeks" | "month" | "quarter" | "half_year" | "year"required
    • open_daysinteger

      From 1 to 60. Default 7.

  • anonymous_bands"team" | "location" | "tenure"[]required

    Anonymous surveys: the coarse bands kept with each answer.

  • fatigue_skippedintegerrequired

    People left out at sending: they already had their surveys this month.

  • triggerobject | nullrequired

    Lifecycle: 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"required

      start: 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.

    • daysintegerrequired

      From 0 to 365.

  • slackbooleanrequired

    Invitations and reminders also go as Slack direct messages where the company connected Slack.

  • retention_monthsintegerrequired

    Answers are deleted this many months after it closes; the group results are kept.

  • purged_atstring | nullrequired

    When its answers were deleted (retention); results then come from the kept group results.

  • publicobject | nullrequired

    Its public link (surveys_public_set); null: never set.

    10 fields
    • onbooleanrequired
    • idstringrequired
    • respondent"anonymous" | "named"required
    • max_answersintegerrequired
    • one_per_browserbooleanrequired
    • kioskbooleanrequired
    • embed_domainsstring[]required
    • answeredintegerrequired
    • switched_off_by_bizisybooleanrequired
    • reportsintegerrequired
  • councilobjectrequired

    The works council's approval (when the company asks for it, surveys_settings_get council_approval).

    3 fields
    • status"not_asked" | "waiting" | "approved" | "returned"required
    • approved_for_this_versionbooleanrequired
    • 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/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
}'
Response
{
  "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_duplicate on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • survey_idstringrequired

    1–64 characters.

  • titlestring

    1–160 characters.

Returns

38 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).

  • definitionobjectrequired

    The 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
    • languagestringrequired

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

    • languagesstring[]required

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

    • translationsobjectrequired
    • coverobjectrequired
      3 fields
      • showbooleanrequired
      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

    • thanksobjectrequired
      5 fields
      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

      • link_urlstring | null

        Up to 500 characters. Pattern ^https:\/\/[^\s]+$.

      • link_labelstring | null

        Up to 80 characters.

      • redirect_urlstring | null

        Up to 500 characters. Pattern ^https:\/\/[^\s]+$.

    • layout"one" | "page"required
    • progressbooleanrequired
    • logobooleanrequired
    • themeobject

      How 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 | null

        A background image id from surveys_design_image_upload.

        Pattern ^[0-9a-z]{26}$.

      • image_diminteger

        How 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[]required

      1–50 items.

      6 fields
      • idstringrequired

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

      • titlestring | null

        Up to 300 characters.

      • descriptionstring | null

        Up to 2000 characters.

      • questionsobject[]required

        Up to 200 items.

        22 fields
        • idstringrequired

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

        • typestring (enum)required

          One of: single, multi, dropdown, nps, likert, star, emoji, slider, ranking, matrix, short_text, long_text, number, date, yes_no, people, location, statement, consent.

        • titlestringrequired

          Up to 1000 characters.

        • descriptionstring | null

          Up to 2000 characters.

        • requiredboolean
        • required_messagestring | null

          Up to 200 characters.

        • choicesobject[]

          Up to 100 items.

          4 fields
          • idstringrequired

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

          • labelstringrequired

            Up to 500 characters.

          • scorenumber | null
          • quotainteger | null

            From 1 to 100000.

        • otherboolean
        • randomizeboolean
        • max_picksinteger | null

          From 1 to 100.

        • points5 | 7
        • minnumber | null
        • maxnumber | null
        • stepnumber | null

          At least 0.

        • low_labelstring | null

          Up to 80 characters.

        • high_labelstring | null

          Up to 80 characters.

        • rowsobject[]

          Up to 100 items.

          4 fields
          • idstringrequired

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

          • labelstringrequired

            Up to 500 characters.

          • scorenumber | null
          • quotainteger | null

            From 1 to 100000.

        • max_lengthinteger | null

          From 1 to 5000.

        • show_ifobject | null
          2 fields
          • match"all" | "any"required
          • rulesobject[]required

            Up to 20 items.

        • score_intoobject | null
          2 fields
          • variablestringrequired

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

          • weightnumber
        • library_idstring | null

          The library item it was copied from (surveys_library_list): rounds and trends compare by it.

          Pattern ^lib\.[a-z]+\.[a-z]+$.

        • driverstring | null

          The engagement driver it measures (engagement, recognition, growth, manager, workload, autonomy, belonging, purpose, communication, wellbeing, fairness).

          Pattern ^[a-z_]{2,30}$.

      • randomize_questionsboolean
      • jumpsobject[]

        Up to 20 items.

        2 fields
        • whenobjectrequired
          2 fields
          • match"all" | "any"required
          • rulesobject[]required

            Up to 20 items.

        • tostring | "end"required
    • variablesobject[]required

      Up to 20 items.

      3 fields
      • idstringrequired

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

      • namestringrequired

        Up to 80 characters.

      • initialnumber
    • outcomesobject[]required

      Up to 20 items.

      4 fields
      • idstringrequired

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

      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

      • whenobjectrequired
        2 fields
        • match"all" | "any"required
        • rulesobject[]required

          Up to 20 items.

          5 fields
          • qstring

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

          • vstring

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

          • f"team" | "location" | "entity" | "language"
          • opstring (enum)required

            One of: eq, neq, gt, gte, lt, lte, includes, excludes, answered, not_answered.

          • valuestring | number | boolean | "null"
  • thresholdintegerrequired
  • comment_thresholdintegerrequired
  • audienceobjectrequired
    5 fields
    • everyoneboolean

      Default 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[]required
  • problemsobject[]required

    What stops it from opening (empty: ready).

    2 fields
    • atstringrequired
    • messagestringrequired
  • lockedbooleanrequired

    Opened once: the mode and questions are fixed; translations, reminders and the close date can still change.

  • manager_viewbooleanrequired

    Managers see their own line's results in My workspace (above the threshold, never a sub-line that could be worked out).

  • recurrenceobject | nullrequired

    The series' schedule (on its first round).

    2 fields
    • every"week" | "two_weeks" | "month" | "quarter" | "half_year" | "year"required
    • open_daysinteger

      From 1 to 60. Default 7.

  • anonymous_bands"team" | "location" | "tenure"[]required

    Anonymous surveys: the coarse bands kept with each answer.

  • fatigue_skippedintegerrequired

    People left out at sending: they already had their surveys this month.

  • triggerobject | nullrequired

    Lifecycle: 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"required

      start: 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.

    • daysintegerrequired

      From 0 to 365.

  • slackbooleanrequired

    Invitations and reminders also go as Slack direct messages where the company connected Slack.

  • retention_monthsintegerrequired

    Answers are deleted this many months after it closes; the group results are kept.

  • purged_atstring | nullrequired

    When its answers were deleted (retention); results then come from the kept group results.

  • publicobject | nullrequired

    Its public link (surveys_public_set); null: never set.

    10 fields
    • onbooleanrequired
    • idstringrequired
    • respondent"anonymous" | "named"required
    • max_answersintegerrequired
    • one_per_browserbooleanrequired
    • kioskbooleanrequired
    • embed_domainsstring[]required
    • answeredintegerrequired
    • switched_off_by_bizisybooleanrequired
    • reportsintegerrequired
  • councilobjectrequired

    The works council's approval (when the company asks for it, surveys_settings_get council_approval).

    3 fields
    • status"not_asked" | "waiting" | "approved" | "returned"required
    • approved_for_this_versionbooleanrequired
    • 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/surveys.duplicate \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"survey_id":"s1"}'
Response
{
  "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_count on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • audienceobjectrequired
    5 fields
    • everyoneboolean

      Default 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

  • peopleintegerrequired
  • at_capintegerrequired

    Of 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
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": []
  }
}'
Response
{
  "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_open on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • survey_idstringrequired

    1–64 characters.

  • open_atdate-time

    An ISO date and time, e.g. 2026-12-01T09:00:00Z.

    ISO 8601 date and time (UTC).

  • close_atdate-time | null

    An ISO date and time, e.g. 2026-12-01T09:00:00Z.

    ISO 8601 date and time (UTC).

  • recurrenceobject | null
    2 fields
    • every"week" | "two_weeks" | "month" | "quarter" | "half_year" | "year"required
    • open_daysinteger

      From 1 to 60. Default 7.

  • ignore_fatigueboolean

Returns

38 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).

  • definitionobjectrequired

    The 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
    • languagestringrequired

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

    • languagesstring[]required

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

    • translationsobjectrequired
    • coverobjectrequired
      3 fields
      • showbooleanrequired
      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

    • thanksobjectrequired
      5 fields
      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

      • link_urlstring | null

        Up to 500 characters. Pattern ^https:\/\/[^\s]+$.

      • link_labelstring | null

        Up to 80 characters.

      • redirect_urlstring | null

        Up to 500 characters. Pattern ^https:\/\/[^\s]+$.

    • layout"one" | "page"required
    • progressbooleanrequired
    • logobooleanrequired
    • themeobject

      How 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 | null

        A background image id from surveys_design_image_upload.

        Pattern ^[0-9a-z]{26}$.

      • image_diminteger

        How 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[]required

      1–50 items.

      6 fields
      • idstringrequired

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

      • titlestring | null

        Up to 300 characters.

      • descriptionstring | null

        Up to 2000 characters.

      • questionsobject[]required

        Up to 200 items.

        22 fields
        • idstringrequired

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

        • typestring (enum)required

          One of: single, multi, dropdown, nps, likert, star, emoji, slider, ranking, matrix, short_text, long_text, number, date, yes_no, people, location, statement, consent.

        • titlestringrequired

          Up to 1000 characters.

        • descriptionstring | null

          Up to 2000 characters.

        • requiredboolean
        • required_messagestring | null

          Up to 200 characters.

        • choicesobject[]

          Up to 100 items.

          4 fields
          • idstringrequired

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

          • labelstringrequired

            Up to 500 characters.

          • scorenumber | null
          • quotainteger | null

            From 1 to 100000.

        • otherboolean
        • randomizeboolean
        • max_picksinteger | null

          From 1 to 100.

        • points5 | 7
        • minnumber | null
        • maxnumber | null
        • stepnumber | null

          At least 0.

        • low_labelstring | null

          Up to 80 characters.

        • high_labelstring | null

          Up to 80 characters.

        • rowsobject[]

          Up to 100 items.

          4 fields
          • idstringrequired

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

          • labelstringrequired

            Up to 500 characters.

          • scorenumber | null
          • quotainteger | null

            From 1 to 100000.

        • max_lengthinteger | null

          From 1 to 5000.

        • show_ifobject | null
          2 fields
          • match"all" | "any"required
          • rulesobject[]required

            Up to 20 items.

        • score_intoobject | null
          2 fields
          • variablestringrequired

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

          • weightnumber
        • library_idstring | null

          The library item it was copied from (surveys_library_list): rounds and trends compare by it.

          Pattern ^lib\.[a-z]+\.[a-z]+$.

        • driverstring | null

          The engagement driver it measures (engagement, recognition, growth, manager, workload, autonomy, belonging, purpose, communication, wellbeing, fairness).

          Pattern ^[a-z_]{2,30}$.

      • randomize_questionsboolean
      • jumpsobject[]

        Up to 20 items.

        2 fields
        • whenobjectrequired
          2 fields
          • match"all" | "any"required
          • rulesobject[]required

            Up to 20 items.

        • tostring | "end"required
    • variablesobject[]required

      Up to 20 items.

      3 fields
      • idstringrequired

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

      • namestringrequired

        Up to 80 characters.

      • initialnumber
    • outcomesobject[]required

      Up to 20 items.

      4 fields
      • idstringrequired

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

      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

      • whenobjectrequired
        2 fields
        • match"all" | "any"required
        • rulesobject[]required

          Up to 20 items.

          5 fields
          • qstring

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

          • vstring

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

          • f"team" | "location" | "entity" | "language"
          • opstring (enum)required

            One of: eq, neq, gt, gte, lt, lte, includes, excludes, answered, not_answered.

          • valuestring | number | boolean | "null"
  • thresholdintegerrequired
  • comment_thresholdintegerrequired
  • audienceobjectrequired
    5 fields
    • everyoneboolean

      Default 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[]required
  • problemsobject[]required

    What stops it from opening (empty: ready).

    2 fields
    • atstringrequired
    • messagestringrequired
  • lockedbooleanrequired

    Opened once: the mode and questions are fixed; translations, reminders and the close date can still change.

  • manager_viewbooleanrequired

    Managers see their own line's results in My workspace (above the threshold, never a sub-line that could be worked out).

  • recurrenceobject | nullrequired

    The series' schedule (on its first round).

    2 fields
    • every"week" | "two_weeks" | "month" | "quarter" | "half_year" | "year"required
    • open_daysinteger

      From 1 to 60. Default 7.

  • anonymous_bands"team" | "location" | "tenure"[]required

    Anonymous surveys: the coarse bands kept with each answer.

  • fatigue_skippedintegerrequired

    People left out at sending: they already had their surveys this month.

  • triggerobject | nullrequired

    Lifecycle: 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"required

      start: 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.

    • daysintegerrequired

      From 0 to 365.

  • slackbooleanrequired

    Invitations and reminders also go as Slack direct messages where the company connected Slack.

  • retention_monthsintegerrequired

    Answers are deleted this many months after it closes; the group results are kept.

  • purged_atstring | nullrequired

    When its answers were deleted (retention); results then come from the kept group results.

  • publicobject | nullrequired

    Its public link (surveys_public_set); null: never set.

    10 fields
    • onbooleanrequired
    • idstringrequired
    • respondent"anonymous" | "named"required
    • max_answersintegerrequired
    • one_per_browserbooleanrequired
    • kioskbooleanrequired
    • embed_domainsstring[]required
    • answeredintegerrequired
    • switched_off_by_bizisybooleanrequired
    • reportsintegerrequired
  • councilobjectrequired

    The works council's approval (when the company asks for it, surveys_settings_get council_approval).

    3 fields
    • status"not_asked" | "waiting" | "approved" | "returned"required
    • approved_for_this_versionbooleanrequired
    • 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/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"
}'
Response
{
  "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_close on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • survey_idstringrequired

    1–64 characters.

Returns

38 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).

  • definitionobjectrequired

    The 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
    • languagestringrequired

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

    • languagesstring[]required

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

    • translationsobjectrequired
    • coverobjectrequired
      3 fields
      • showbooleanrequired
      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

    • thanksobjectrequired
      5 fields
      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

      • link_urlstring | null

        Up to 500 characters. Pattern ^https:\/\/[^\s]+$.

      • link_labelstring | null

        Up to 80 characters.

      • redirect_urlstring | null

        Up to 500 characters. Pattern ^https:\/\/[^\s]+$.

    • layout"one" | "page"required
    • progressbooleanrequired
    • logobooleanrequired
    • themeobject

      How 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 | null

        A background image id from surveys_design_image_upload.

        Pattern ^[0-9a-z]{26}$.

      • image_diminteger

        How 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[]required

      1–50 items.

      6 fields
      • idstringrequired

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

      • titlestring | null

        Up to 300 characters.

      • descriptionstring | null

        Up to 2000 characters.

      • questionsobject[]required

        Up to 200 items.

        22 fields
        • idstringrequired

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

        • typestring (enum)required

          One of: single, multi, dropdown, nps, likert, star, emoji, slider, ranking, matrix, short_text, long_text, number, date, yes_no, people, location, statement, consent.

        • titlestringrequired

          Up to 1000 characters.

        • descriptionstring | null

          Up to 2000 characters.

        • requiredboolean
        • required_messagestring | null

          Up to 200 characters.

        • choicesobject[]

          Up to 100 items.

          4 fields
          • idstringrequired

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

          • labelstringrequired

            Up to 500 characters.

          • scorenumber | null
          • quotainteger | null

            From 1 to 100000.

        • otherboolean
        • randomizeboolean
        • max_picksinteger | null

          From 1 to 100.

        • points5 | 7
        • minnumber | null
        • maxnumber | null
        • stepnumber | null

          At least 0.

        • low_labelstring | null

          Up to 80 characters.

        • high_labelstring | null

          Up to 80 characters.

        • rowsobject[]

          Up to 100 items.

          4 fields
          • idstringrequired

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

          • labelstringrequired

            Up to 500 characters.

          • scorenumber | null
          • quotainteger | null

            From 1 to 100000.

        • max_lengthinteger | null

          From 1 to 5000.

        • show_ifobject | null
          2 fields
          • match"all" | "any"required
          • rulesobject[]required

            Up to 20 items.

        • score_intoobject | null
          2 fields
          • variablestringrequired

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

          • weightnumber
        • library_idstring | null

          The library item it was copied from (surveys_library_list): rounds and trends compare by it.

          Pattern ^lib\.[a-z]+\.[a-z]+$.

        • driverstring | null

          The engagement driver it measures (engagement, recognition, growth, manager, workload, autonomy, belonging, purpose, communication, wellbeing, fairness).

          Pattern ^[a-z_]{2,30}$.

      • randomize_questionsboolean
      • jumpsobject[]

        Up to 20 items.

        2 fields
        • whenobjectrequired
          2 fields
          • match"all" | "any"required
          • rulesobject[]required

            Up to 20 items.

        • tostring | "end"required
    • variablesobject[]required

      Up to 20 items.

      3 fields
      • idstringrequired

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

      • namestringrequired

        Up to 80 characters.

      • initialnumber
    • outcomesobject[]required

      Up to 20 items.

      4 fields
      • idstringrequired

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

      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

      • whenobjectrequired
        2 fields
        • match"all" | "any"required
        • rulesobject[]required

          Up to 20 items.

          5 fields
          • qstring

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

          • vstring

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

          • f"team" | "location" | "entity" | "language"
          • opstring (enum)required

            One of: eq, neq, gt, gte, lt, lte, includes, excludes, answered, not_answered.

          • valuestring | number | boolean | "null"
  • thresholdintegerrequired
  • comment_thresholdintegerrequired
  • audienceobjectrequired
    5 fields
    • everyoneboolean

      Default 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[]required
  • problemsobject[]required

    What stops it from opening (empty: ready).

    2 fields
    • atstringrequired
    • messagestringrequired
  • lockedbooleanrequired

    Opened once: the mode and questions are fixed; translations, reminders and the close date can still change.

  • manager_viewbooleanrequired

    Managers see their own line's results in My workspace (above the threshold, never a sub-line that could be worked out).

  • recurrenceobject | nullrequired

    The series' schedule (on its first round).

    2 fields
    • every"week" | "two_weeks" | "month" | "quarter" | "half_year" | "year"required
    • open_daysinteger

      From 1 to 60. Default 7.

  • anonymous_bands"team" | "location" | "tenure"[]required

    Anonymous surveys: the coarse bands kept with each answer.

  • fatigue_skippedintegerrequired

    People left out at sending: they already had their surveys this month.

  • triggerobject | nullrequired

    Lifecycle: 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"required

      start: 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.

    • daysintegerrequired

      From 0 to 365.

  • slackbooleanrequired

    Invitations and reminders also go as Slack direct messages where the company connected Slack.

  • retention_monthsintegerrequired

    Answers are deleted this many months after it closes; the group results are kept.

  • purged_atstring | nullrequired

    When its answers were deleted (retention); results then come from the kept group results.

  • publicobject | nullrequired

    Its public link (surveys_public_set); null: never set.

    10 fields
    • onbooleanrequired
    • idstringrequired
    • respondent"anonymous" | "named"required
    • max_answersintegerrequired
    • one_per_browserbooleanrequired
    • kioskbooleanrequired
    • embed_domainsstring[]required
    • answeredintegerrequired
    • switched_off_by_bizisybooleanrequired
    • reportsintegerrequired
  • councilobjectrequired

    The works council's approval (when the company asks for it, surveys_settings_get council_approval).

    3 fields
    • status"not_asked" | "waiting" | "approved" | "returned"required
    • approved_for_this_versionbooleanrequired
    • 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/surveys.close \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"survey_id":"s1"}'
Response
{
  "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_archive on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • survey_idstringrequired

    1–64 characters.

  • archivedboolean

    Default true.

Returns

38 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).

  • definitionobjectrequired

    The 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
    • languagestringrequired

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

    • languagesstring[]required

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

    • translationsobjectrequired
    • coverobjectrequired
      3 fields
      • showbooleanrequired
      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

    • thanksobjectrequired
      5 fields
      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

      • link_urlstring | null

        Up to 500 characters. Pattern ^https:\/\/[^\s]+$.

      • link_labelstring | null

        Up to 80 characters.

      • redirect_urlstring | null

        Up to 500 characters. Pattern ^https:\/\/[^\s]+$.

    • layout"one" | "page"required
    • progressbooleanrequired
    • logobooleanrequired
    • themeobject

      How 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 | null

        A background image id from surveys_design_image_upload.

        Pattern ^[0-9a-z]{26}$.

      • image_diminteger

        How 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[]required

      1–50 items.

      6 fields
      • idstringrequired

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

      • titlestring | null

        Up to 300 characters.

      • descriptionstring | null

        Up to 2000 characters.

      • questionsobject[]required

        Up to 200 items.

        22 fields
        • idstringrequired

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

        • typestring (enum)required

          One of: single, multi, dropdown, nps, likert, star, emoji, slider, ranking, matrix, short_text, long_text, number, date, yes_no, people, location, statement, consent.

        • titlestringrequired

          Up to 1000 characters.

        • descriptionstring | null

          Up to 2000 characters.

        • requiredboolean
        • required_messagestring | null

          Up to 200 characters.

        • choicesobject[]

          Up to 100 items.

          4 fields
          • idstringrequired

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

          • labelstringrequired

            Up to 500 characters.

          • scorenumber | null
          • quotainteger | null

            From 1 to 100000.

        • otherboolean
        • randomizeboolean
        • max_picksinteger | null

          From 1 to 100.

        • points5 | 7
        • minnumber | null
        • maxnumber | null
        • stepnumber | null

          At least 0.

        • low_labelstring | null

          Up to 80 characters.

        • high_labelstring | null

          Up to 80 characters.

        • rowsobject[]

          Up to 100 items.

          4 fields
          • idstringrequired

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

          • labelstringrequired

            Up to 500 characters.

          • scorenumber | null
          • quotainteger | null

            From 1 to 100000.

        • max_lengthinteger | null

          From 1 to 5000.

        • show_ifobject | null
          2 fields
          • match"all" | "any"required
          • rulesobject[]required

            Up to 20 items.

        • score_intoobject | null
          2 fields
          • variablestringrequired

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

          • weightnumber
        • library_idstring | null

          The library item it was copied from (surveys_library_list): rounds and trends compare by it.

          Pattern ^lib\.[a-z]+\.[a-z]+$.

        • driverstring | null

          The engagement driver it measures (engagement, recognition, growth, manager, workload, autonomy, belonging, purpose, communication, wellbeing, fairness).

          Pattern ^[a-z_]{2,30}$.

      • randomize_questionsboolean
      • jumpsobject[]

        Up to 20 items.

        2 fields
        • whenobjectrequired
          2 fields
          • match"all" | "any"required
          • rulesobject[]required

            Up to 20 items.

        • tostring | "end"required
    • variablesobject[]required

      Up to 20 items.

      3 fields
      • idstringrequired

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

      • namestringrequired

        Up to 80 characters.

      • initialnumber
    • outcomesobject[]required

      Up to 20 items.

      4 fields
      • idstringrequired

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

      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

      • whenobjectrequired
        2 fields
        • match"all" | "any"required
        • rulesobject[]required

          Up to 20 items.

          5 fields
          • qstring

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

          • vstring

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

          • f"team" | "location" | "entity" | "language"
          • opstring (enum)required

            One of: eq, neq, gt, gte, lt, lte, includes, excludes, answered, not_answered.

          • valuestring | number | boolean | "null"
  • thresholdintegerrequired
  • comment_thresholdintegerrequired
  • audienceobjectrequired
    5 fields
    • everyoneboolean

      Default 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[]required
  • problemsobject[]required

    What stops it from opening (empty: ready).

    2 fields
    • atstringrequired
    • messagestringrequired
  • lockedbooleanrequired

    Opened once: the mode and questions are fixed; translations, reminders and the close date can still change.

  • manager_viewbooleanrequired

    Managers see their own line's results in My workspace (above the threshold, never a sub-line that could be worked out).

  • recurrenceobject | nullrequired

    The series' schedule (on its first round).

    2 fields
    • every"week" | "two_weeks" | "month" | "quarter" | "half_year" | "year"required
    • open_daysinteger

      From 1 to 60. Default 7.

  • anonymous_bands"team" | "location" | "tenure"[]required

    Anonymous surveys: the coarse bands kept with each answer.

  • fatigue_skippedintegerrequired

    People left out at sending: they already had their surveys this month.

  • triggerobject | nullrequired

    Lifecycle: 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"required

      start: 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.

    • daysintegerrequired

      From 0 to 365.

  • slackbooleanrequired

    Invitations and reminders also go as Slack direct messages where the company connected Slack.

  • retention_monthsintegerrequired

    Answers are deleted this many months after it closes; the group results are kept.

  • purged_atstring | nullrequired

    When its answers were deleted (retention); results then come from the kept group results.

  • publicobject | nullrequired

    Its public link (surveys_public_set); null: never set.

    10 fields
    • onbooleanrequired
    • idstringrequired
    • respondent"anonymous" | "named"required
    • max_answersintegerrequired
    • one_per_browserbooleanrequired
    • kioskbooleanrequired
    • embed_domainsstring[]required
    • answeredintegerrequired
    • switched_off_by_bizisybooleanrequired
    • reportsintegerrequired
  • councilobjectrequired

    The works council's approval (when the company asks for it, surveys_settings_get council_approval).

    3 fields
    • status"not_asked" | "waiting" | "approved" | "returned"required
    • approved_for_this_versionbooleanrequired
    • 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/surveys.archive \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"survey_id":"s1","archived":false}'
Response
{
  "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_get 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

    Language 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_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/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"}'
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
      }
    ]
  }
}

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

Input

  • survey_idstringrequired

    1–64 characters.

  • langstring

    Language 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[]required
    2 fields
    • idstringrequired
    • titlestringrequired
  • rowsobject[]required
    5 fields
    • person_idstringrequired
    • namestringrequired
    • submitted_atstringrequired
    • languagestringrequired
    • answersstring[]required

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

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

Input

  • survey_idstringrequired

    1–64 characters.

  • format"csv" | "xlsx" | "sav" | "json"

    Default "xlsx".

  • segmentobject
    2 fields
    • kindstring (enum)required

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

    • idstringrequired

      1–160 characters.

  • langstring

    Language 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

  • fileobjectrequired
    6 fields
    • namestringrequired
    • content_typestringrequired
    • encoding"utf8" | "base64"required
    • contentstringrequired
    • bytesintegerrequired
    • sha256stringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

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

Input

  • survey_idstringrequired

    1–64 characters.

  • bystring (enum)

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

  • field_keystring

    Up to 60 characters.

  • filterobject
    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

9 fields
  • survey_idstringrequired
  • bystring (enum)required

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

  • field_keystring | nullrequired
  • filterobject | nullrequired
    3 fields
    • kindstring (enum)required

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

    • idstringrequired

      1–160 characters.

    • namestringrequired
  • filter_hiddenbooleanrequired

    The filter group itself is under the threshold: nothing shows.

  • floorintegerrequired

    The smallest group a cell shows (doubled with a filter).

  • previousobject | nullrequired

    The round changes compare with.

    2 fields
    • survey_idstringrequired
    • round_nointegerrequired
  • columnsobject[]required
    5 fields
    • idstringrequired
    • namestringrequired
    • ninteger | nullrequired
    • hiddenbooleanrequired
    • underinteger | nullrequired
  • rowsobject[]required
    6 fields
    • keystringrequired

      driver:<name>, a library id, or q:<question id>.

    • kind"driver" | "enps" | "question"required
    • titlestringrequired
    • driverstring | nullrequired
    • overallnumber | nullrequired
    • cellsobject[]required
      6 fields
      • column_idstringrequired
      • valuenumber | nullrequired
      • previousnumber | nullrequired
      • changenumber | nullrequired
      • hiddenbooleanrequired
      • underinteger | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

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

  • series_idstring | nullrequired
  • roundsobject[]required
    7 fields
    • survey_idstringrequired
    • round_nointegerrequired
    • opened_atstring | nullrequired
    • statusstringrequired
    • respondentsinteger | nullrequired
    • hiddenbooleanrequired
    • valuesobjectrequired

      Row key → value in that round (null: hidden or not asked).

  • rowsobject[]required
    3 fields
    • keystringrequired
    • kind"driver" | "enps" | "question"required
    • titlestringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

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

Input

  • survey_idstringrequired

    1–64 characters.

Returns

  • outcome"enps" | "engagement"required

    What the drivers are compared with: the 0–10 question, else the engagement driver.

  • ninteger | nullrequired
  • enoughbooleanrequired

    At least 10 answers and the threshold: below that no correlation is shown.

  • driversobject[]required
    3 fields
    • driverstringrequired
    • rnumber | nullrequired

      Correlation with the outcome (−1 to 1).

    • scorenumber | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

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

Input

  • language"en" | "pt-PT" | "es-ES" | "de-DE" | "fr-FR" | "it-IT"

    Default "en".

Returns

  • itemsobject[]required
    6 fields
    • idstringrequired
    • driverstring | nullrequired
    • typestringrequired
    • titlestringrequired
    • sourceobjectrequired
      2 fields
      • citestringrequired
      • urlstringrequired
    • questionobjectrequired

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

Input

No input: send {}.

Returns

  • max_per_monthintegerrequired

    Surveys a person gets at most per calendar month (fatigue guard; 0: no limit).

  • aibooleanrequired

    Surveys' 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_connectedbooleanrequired

    Slack is connected (Integrations): surveys can also go as Slack direct messages (surveys_surveys_update slack).

  • council_approvalbooleanrequired

    Surveys wait for the works council's approval before they are sent (a login with Surveys at Approve decides).

  • privacy_urlstring | nullrequired

    The 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
curl https://api.bizisy.com/v1/surveys/settings.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • max_per_monthinteger

    From 0 to 12.

  • aiboolean
  • council_approvalboolean

    Surveys wait for the works council's approval before they are sent.

  • privacy_urlURL | null

    The company's privacy notice (https://), linked on every public survey.

    Up to 500 characters.

Returns

  • max_per_monthintegerrequired

    Surveys a person gets at most per calendar month (fatigue guard; 0: no limit).

  • aibooleanrequired

    Surveys' 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_connectedbooleanrequired

    Slack is connected (Integrations): surveys can also go as Slack direct messages (surveys_surveys_update slack).

  • council_approvalbooleanrequired

    Surveys wait for the works council's approval before they are sent (a login with Surveys at Approve decides).

  • privacy_urlstring | nullrequired

    The 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
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"}'
Response
{
  "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_stop on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • survey_idstringrequired

    Any round of the series.

    1–64 characters.

Returns

38 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).

  • definitionobjectrequired

    The 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
    • languagestringrequired

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

    • languagesstring[]required

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

    • translationsobjectrequired
    • coverobjectrequired
      3 fields
      • showbooleanrequired
      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

    • thanksobjectrequired
      5 fields
      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

      • link_urlstring | null

        Up to 500 characters. Pattern ^https:\/\/[^\s]+$.

      • link_labelstring | null

        Up to 80 characters.

      • redirect_urlstring | null

        Up to 500 characters. Pattern ^https:\/\/[^\s]+$.

    • layout"one" | "page"required
    • progressbooleanrequired
    • logobooleanrequired
    • themeobject

      How 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 | null

        A background image id from surveys_design_image_upload.

        Pattern ^[0-9a-z]{26}$.

      • image_diminteger

        How 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[]required

      1–50 items.

      6 fields
      • idstringrequired

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

      • titlestring | null

        Up to 300 characters.

      • descriptionstring | null

        Up to 2000 characters.

      • questionsobject[]required

        Up to 200 items.

        22 fields
        • idstringrequired

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

        • typestring (enum)required

          One of: single, multi, dropdown, nps, likert, star, emoji, slider, ranking, matrix, short_text, long_text, number, date, yes_no, people, location, statement, consent.

        • titlestringrequired

          Up to 1000 characters.

        • descriptionstring | null

          Up to 2000 characters.

        • requiredboolean
        • required_messagestring | null

          Up to 200 characters.

        • choicesobject[]

          Up to 100 items.

          4 fields
          • idstringrequired

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

          • labelstringrequired

            Up to 500 characters.

          • scorenumber | null
          • quotainteger | null

            From 1 to 100000.

        • otherboolean
        • randomizeboolean
        • max_picksinteger | null

          From 1 to 100.

        • points5 | 7
        • minnumber | null
        • maxnumber | null
        • stepnumber | null

          At least 0.

        • low_labelstring | null

          Up to 80 characters.

        • high_labelstring | null

          Up to 80 characters.

        • rowsobject[]

          Up to 100 items.

          4 fields
          • idstringrequired

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

          • labelstringrequired

            Up to 500 characters.

          • scorenumber | null
          • quotainteger | null

            From 1 to 100000.

        • max_lengthinteger | null

          From 1 to 5000.

        • show_ifobject | null
          2 fields
          • match"all" | "any"required
          • rulesobject[]required

            Up to 20 items.

        • score_intoobject | null
          2 fields
          • variablestringrequired

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

          • weightnumber
        • library_idstring | null

          The library item it was copied from (surveys_library_list): rounds and trends compare by it.

          Pattern ^lib\.[a-z]+\.[a-z]+$.

        • driverstring | null

          The engagement driver it measures (engagement, recognition, growth, manager, workload, autonomy, belonging, purpose, communication, wellbeing, fairness).

          Pattern ^[a-z_]{2,30}$.

      • randomize_questionsboolean
      • jumpsobject[]

        Up to 20 items.

        2 fields
        • whenobjectrequired
          2 fields
          • match"all" | "any"required
          • rulesobject[]required

            Up to 20 items.

        • tostring | "end"required
    • variablesobject[]required

      Up to 20 items.

      3 fields
      • idstringrequired

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

      • namestringrequired

        Up to 80 characters.

      • initialnumber
    • outcomesobject[]required

      Up to 20 items.

      4 fields
      • idstringrequired

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

      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

      • whenobjectrequired
        2 fields
        • match"all" | "any"required
        • rulesobject[]required

          Up to 20 items.

          5 fields
          • qstring

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

          • vstring

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

          • f"team" | "location" | "entity" | "language"
          • opstring (enum)required

            One of: eq, neq, gt, gte, lt, lte, includes, excludes, answered, not_answered.

          • valuestring | number | boolean | "null"
  • thresholdintegerrequired
  • comment_thresholdintegerrequired
  • audienceobjectrequired
    5 fields
    • everyoneboolean

      Default 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[]required
  • problemsobject[]required

    What stops it from opening (empty: ready).

    2 fields
    • atstringrequired
    • messagestringrequired
  • lockedbooleanrequired

    Opened once: the mode and questions are fixed; translations, reminders and the close date can still change.

  • manager_viewbooleanrequired

    Managers see their own line's results in My workspace (above the threshold, never a sub-line that could be worked out).

  • recurrenceobject | nullrequired

    The series' schedule (on its first round).

    2 fields
    • every"week" | "two_weeks" | "month" | "quarter" | "half_year" | "year"required
    • open_daysinteger

      From 1 to 60. Default 7.

  • anonymous_bands"team" | "location" | "tenure"[]required

    Anonymous surveys: the coarse bands kept with each answer.

  • fatigue_skippedintegerrequired

    People left out at sending: they already had their surveys this month.

  • triggerobject | nullrequired

    Lifecycle: 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"required

      start: 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.

    • daysintegerrequired

      From 0 to 365.

  • slackbooleanrequired

    Invitations and reminders also go as Slack direct messages where the company connected Slack.

  • retention_monthsintegerrequired

    Answers are deleted this many months after it closes; the group results are kept.

  • purged_atstring | nullrequired

    When its answers were deleted (retention); results then come from the kept group results.

  • publicobject | nullrequired

    Its public link (surveys_public_set); null: never set.

    10 fields
    • onbooleanrequired
    • idstringrequired
    • respondent"anonymous" | "named"required
    • max_answersintegerrequired
    • one_per_browserbooleanrequired
    • kioskbooleanrequired
    • embed_domainsstring[]required
    • answeredintegerrequired
    • switched_off_by_bizisybooleanrequired
    • reportsintegerrequired
  • councilobjectrequired

    The works council's approval (when the company asks for it, surveys_settings_get council_approval).

    3 fields
    • status"not_asked" | "waiting" | "approved" | "returned"required
    • approved_for_this_versionbooleanrequired
    • 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/series.stop \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"survey_id":"s1"}'
Response
{
  "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_status on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

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

    About how many AI credits a typical request uses.

  • left_todayintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/surveys/ai.status \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_draft 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

  • sentencestringrequired

    10–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

  • titlestringrequired
  • definitionobjectrequired

    The 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
    • languagestringrequired

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

    • languagesstring[]required

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

    • translationsobjectrequired
    • coverobjectrequired
      3 fields
      • showbooleanrequired
      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

    • thanksobjectrequired
      5 fields
      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

      • link_urlstring | null

        Up to 500 characters. Pattern ^https:\/\/[^\s]+$.

      • link_labelstring | null

        Up to 80 characters.

      • redirect_urlstring | null

        Up to 500 characters. Pattern ^https:\/\/[^\s]+$.

    • layout"one" | "page"required
    • progressbooleanrequired
    • logobooleanrequired
    • themeobject

      How 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 | null

        A background image id from surveys_design_image_upload.

        Pattern ^[0-9a-z]{26}$.

      • image_diminteger

        How 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[]required

      1–50 items.

      6 fields
      • idstringrequired

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

      • titlestring | null

        Up to 300 characters.

      • descriptionstring | null

        Up to 2000 characters.

      • questionsobject[]required

        Up to 200 items.

        22 fields
        • idstringrequired

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

        • typestring (enum)required

          One of: single, multi, dropdown, nps, likert, star, emoji, slider, ranking, matrix, short_text, long_text, number, date, yes_no, people, location, statement, consent.

        • titlestringrequired

          Up to 1000 characters.

        • descriptionstring | null

          Up to 2000 characters.

        • requiredboolean
        • required_messagestring | null

          Up to 200 characters.

        • choicesobject[]

          Up to 100 items.

          4 fields
          • idstringrequired

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

          • labelstringrequired

            Up to 500 characters.

          • scorenumber | null
          • quotainteger | null

            From 1 to 100000.

        • otherboolean
        • randomizeboolean
        • max_picksinteger | null

          From 1 to 100.

        • points5 | 7
        • minnumber | null
        • maxnumber | null
        • stepnumber | null

          At least 0.

        • low_labelstring | null

          Up to 80 characters.

        • high_labelstring | null

          Up to 80 characters.

        • rowsobject[]

          Up to 100 items.

          4 fields
          • idstringrequired

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

          • labelstringrequired

            Up to 500 characters.

          • scorenumber | null
          • quotainteger | null

            From 1 to 100000.

        • max_lengthinteger | null

          From 1 to 5000.

        • show_ifobject | null
          2 fields
          • match"all" | "any"required
          • rulesobject[]required

            Up to 20 items.

        • score_intoobject | null
          2 fields
          • variablestringrequired

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

          • weightnumber
        • library_idstring | null

          The library item it was copied from (surveys_library_list): rounds and trends compare by it.

          Pattern ^lib\.[a-z]+\.[a-z]+$.

        • driverstring | null

          The engagement driver it measures (engagement, recognition, growth, manager, workload, autonomy, belonging, purpose, communication, wellbeing, fairness).

          Pattern ^[a-z_]{2,30}$.

      • randomize_questionsboolean
      • jumpsobject[]

        Up to 20 items.

        2 fields
        • whenobjectrequired
          2 fields
          • match"all" | "any"required
          • rulesobject[]required

            Up to 20 items.

        • tostring | "end"required
    • variablesobject[]required

      Up to 20 items.

      3 fields
      • idstringrequired

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

      • namestringrequired

        Up to 80 characters.

      • initialnumber
    • outcomesobject[]required

      Up to 20 items.

      4 fields
      • idstringrequired

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

      • titlestringrequired

        Up to 300 characters.

      • bodystring | null

        Up to 5000 characters.

      • whenobjectrequired
        2 fields
        • match"all" | "any"required
        • rulesobject[]required

          Up to 20 items.

          5 fields
          • qstring

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

          • vstring

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

          • f"team" | "location" | "entity" | "language"
          • opstring (enum)required

            One of: eq, neq, gt, gte, lt, lte, includes, excludes, answered, not_answered.

          • valuestring | number | boolean | "null"
  • warningsobject[]required
    3 fields
    • question_idstringrequired
    • kindstringrequired
    • notestringrequired
  • ai_generatedtruerequired
  • ai_creditsobjectrequired
    2 fields
    • costintegerrequired

      AI credits this used.

    • leftinteger | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

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

  • descriptionstringrequired

    4–1000 characters.

  • language"en" | "pt-PT" | "es-ES" | "de-DE" | "fr-FR" | "it-IT"

    Default "en".

  • mode"named" | "confidential" | "anonymous"

    Default "confidential".

Returns

  • questionany

    A question of the survey definition (type, title, choices…), with a fresh id.

  • warningsobject[]required
    2 fields
    • kindstringrequired
    • notestringrequired
  • ai_generatedtruerequired
  • ai_creditsobjectrequired
    2 fields
    • costintegerrequired

      AI credits this used.

    • leftinteger | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

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

  • language"en" | "pt-PT" | "es-ES" | "de-DE" | "fr-FR" | "it-IT"required

Returns

  • languagestringrequired
  • translationsobjectrequired
  • ai_generatedtruerequired
  • ai_creditsobjectrequired
    2 fields
    • costintegerrequired

      AI credits this used.

    • leftinteger | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_check on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • survey_idstringrequired

    1–64 characters.

  • aiboolean

    Default false.

Returns

  • warningsobject[]required
    5 fields
    • question_idstringrequired
    • kind"identifying" | "leading" | "double_barrelled" | "loaded"required
    • notestringrequired
    • suggestionstring | nullrequired
    • by"rule" | "ai"required
  • ai_usedbooleanrequired
  • ai_creditsobjectrequired
    2 fields
    • costintegerrequired

      AI credits this used.

    • leftinteger | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

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

Input

  • survey_idstringrequired

    1–64 characters.

Returns

9 fields
  • survey_idstringrequired
  • enoughbooleanrequired

    Enough published comments to find themes (the comment threshold).

  • stalebooleanrequired

    The published answers grew since the themes were made: refresh with surveys_ai_themes_refresh.

  • comments_ninteger | nullrequired
  • themesobject[]required
    6 fields
    • labelstringrequired
    • sentiment"positive" | "mixed" | "negative"required
    • countintegerrequired
    • sharenumberrequired
    • quotesstring[]required
    • previous_sharenumber | nullrequired
  • summarystring | nullrequired
  • previous_roundinteger | nullrequired
  • created_atstring | nullrequired
  • ai_generatedtruerequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/surveys/results.themes \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"survey_id":"s1"}'
Response
{
  "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_refresh 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.

Returns

9 fields
  • survey_idstringrequired
  • enoughbooleanrequired

    Enough published comments to find themes (the comment threshold).

  • stalebooleanrequired

    The published answers grew since the themes were made: refresh with surveys_ai_themes_refresh.

  • comments_ninteger | nullrequired
  • themesobject[]required
    6 fields
    • labelstringrequired
    • sentiment"positive" | "mixed" | "negative"required
    • countintegerrequired
    • sharenumberrequired
    • quotesstring[]required
    • previous_sharenumber | nullrequired
  • summarystring | nullrequired
  • previous_roundinteger | nullrequired
  • created_atstring | nullrequired
  • ai_generatedtruerequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

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

  • questionstringrequired

    3–500 characters.

  • lang"en" | "pt-PT" | "es-ES" | "de-DE" | "fr-FR" | "it-IT"

Returns

  • answerstringrequired
  • ai_generatedtruerequired
  • ai_creditsobjectrequired
    2 fields
    • costintegerrequired

      AI credits this used.

    • leftinteger | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

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

  • comment_idstringrequired

    8–40 characters.

  • textstringrequired

    1–2000 characters.

Returns

8 fields
  • idstringrequired
  • survey_idstringrequired
  • question_idstringrequired
  • comment_idstringrequired
  • quotestringrequired
  • messagesobject[]required
    3 fields
    • from"hr" | "manager" | "person"required
    • textstringrequired
    • atstringrequired
  • unreadbooleanrequired

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

Input

  • survey_idstringrequired

    1–64 characters.

Returns

  • itemsobject[]required
    8 fields
    • idstringrequired
    • survey_idstringrequired
    • question_idstringrequired
    • comment_idstringrequired
    • quotestringrequired
    • messagesobject[]required
      3 fields
      • from"hr" | "manager" | "person"required
      • textstringrequired
      • atstringrequired
    • unreadbooleanrequired

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

Input

No input: send {}.

Returns

  • availablebooleanrequired
  • maxintegerrequired
  • itemsobject[]required
    3 fields
    • idstringrequired
    • urlstringrequired
    • created_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/surveys/design.images \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_upload 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
Body limit
3 MiB (other actions: 2 MiB)

Input

  • image_base64stringrequired

    The image as base64: JPEG, PNG or WebP, at most 2 MB.

    1–2900000 characters.

Returns

  • idstringrequired
  • urlstringrequired
  • created_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled payload_too_large rate_limited internal

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

Input

  • survey_idstringrequired

    1–64 characters.

Returns

  • activebooleanrequired
  • created_atstring | nullrequired
  • last_used_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/surveys/feeds.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"survey_id":"s1"}'
Response
{
  "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_create 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.

Returns

  • activebooleanrequired
  • created_atstring | nullrequired
  • last_used_atstring | nullrequired
  • tokenstring | nullrequired

    Shown once (null on a dry run).

  • pathstring | nullrequired

    The 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
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"}'
Response
{
  "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_revoke on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • survey_idstringrequired

    1–64 characters.

Returns

  • activebooleanrequired
  • created_atstring | nullrequired
  • last_used_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

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

Input

  • survey_idstring

    1–64 characters.

Returns

  • itemsobject[]required
    14 fields
    • idstringrequired
    • survey_idstringrequired
    • survey_titlestringrequired
    • round_nointegerrequired
    • segmentobject | nullrequired
      3 fields
      • kindstringrequired
      • idstringrequired
      • namestringrequired
    • metricobjectrequired
      2 fields
      • keystringrequired
      • titlestringrequired
    • baselinenumber | nullrequired
    • titlestringrequired
    • ownerobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • duestring | nullrequired
    • status"open" | "done"required
    • checkobject | nullrequired

      The latest later round with results: the same number for the same group (null value: hidden there).

      3 fields
      • round_nointegerrequired
      • survey_idstringrequired
      • valuenumber | nullrequired
    • created_atstringrequired
    • done_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/surveys/actions.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"survey_id":"s1"}'
Response
{
  "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_create on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • survey_idstringrequired

    1–64 characters.

  • titlestringrequired

    3–200 characters.

  • owner_idstringrequired

    1–64 characters.

  • duestring | null

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

  • segmentobject | null
    2 fields
    • kindstring (enum)required

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

    • idstringrequired

      1–160 characters.

  • metricstringrequired

    enps, or q:<question id> (a scale question).

    Pattern ^(enps|q:[A-Za-z0-9_-]{1,40})$.

Returns

14 fields
  • idstringrequired
  • survey_idstringrequired
  • survey_titlestringrequired
  • round_nointegerrequired
  • segmentobject | nullrequired
    3 fields
    • kindstringrequired
    • idstringrequired
    • namestringrequired
  • metricobjectrequired
    2 fields
    • keystringrequired
    • titlestringrequired
  • baselinenumber | nullrequired
  • titlestringrequired
  • ownerobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • duestring | nullrequired
  • status"open" | "done"required
  • checkobject | nullrequired

    The latest later round with results: the same number for the same group (null value: hidden there).

    3 fields
    • round_nointegerrequired
    • survey_idstringrequired
    • valuenumber | nullrequired
  • created_atstringrequired
  • done_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
  }
}'
Response
{
  "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_update on HR Assistant, My Workplace
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • action_idstringrequired

    1–64 characters.

  • titlestring

    3–200 characters.

  • owner_idstring

    1–64 characters.

  • duestring | null

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

  • status"open" | "done"

Returns

14 fields
  • idstringrequired
  • survey_idstringrequired
  • survey_titlestringrequired
  • round_nointegerrequired
  • segmentobject | nullrequired
    3 fields
    • kindstringrequired
    • idstringrequired
    • namestringrequired
  • metricobjectrequired
    2 fields
    • keystringrequired
    • titlestringrequired
  • baselinenumber | nullrequired
  • titlestringrequired
  • ownerobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • duestring | nullrequired
  • status"open" | "done"required
  • checkobject | nullrequired

    The latest later round with results: the same number for the same group (null value: hidden there).

    3 fields
    • round_nointegerrequired
    • survey_idstringrequired
    • valuenumber | nullrequired
  • created_atstringrequired
  • done_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_delete on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • action_idstringrequired

    1–64 characters.

Returns

  • deletedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

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

  • onboolean
  • respondent"anonymous" | "named"
  • max_answersinteger

    From 1 to 50000.

  • one_per_browserboolean
  • kioskboolean
  • embed_domainsstring[]

    3–253 characters. Up to 10 items.

Returns

12 fields
  • onbooleanrequired
  • idstringrequired
  • urlstring | nullrequired

    The link (null until the server knows the company's address).

  • respondent"anonymous" | "named"required

    anonymous: nothing about who answers; named: they give their name (and an email if they like), not verified.

  • max_answersintegerrequired
  • one_per_browserbooleanrequired
  • kioskbooleanrequired

    Kiosk mode allowed: a shared screen (…/f/{id}?kiosk=1) resets after each answer and after a minute without a touch.

  • embed_domainsstring[]required

    Sites that may embed it (an iframe); empty: embedding is off.

  • answeredintegerrequired

    Answers through the public link.

  • switched_off_by_bizisyobject | nullrequired

    Bizisy switched the link off (after reports): HR can't switch it on.

    2 fields
    • atstringrequired
    • reasonstringrequired
  • reportsintegerrequired
  • problemsobject[]required

    Why it can't be public yet (empty: it can).

    2 fields
    • atstringrequired
    • messagestringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

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

Developer docs