Skip to content

Tool reference

Tools appear in the order the server lists them. The heading is the name your assistant calls, and the bold name under it is the label your client shows you. One tagged Read-only only reads your data; one tagged Writes creates, updates or deletes it. Under Parameters, a field is optional unless marked required; under Response, a field is always returned unless marked optional. Soft delete holds a position: a deleted questionnaire element keeps a position of its own and a deleted answer holds a slot in the order, so both still come back in the order they sit in.

Get connected account Read-only

Return the Potloc account this connection is authenticated as.

Parameters

None.

Response

  • id (integer): Your user ID, the same id created_by.id carries elsewhere
  • name (string or null): First and last name joined; null when you have neither
  • email (string): Email address the account signs in with

List surveys Read-only

List the surveys you have access to, most recently created first, with a link to each one on Potloc.

Parameters

  • page (integer): Page number (1-indexed). Defaults to 1.
  • per_page (integer): Results per page (default 25, max 100).

Response

  • surveys (array of object): Surveys for the current page, most recently created first
    • id (integer): Survey ID
    • name (string or null): Survey name
    • created_at (string): Creation timestamp (ISO 8601)
    • url (string): Potloc URL for the survey
  • page (integer): Current page number (1-indexed).
  • total_pages (integer): Total number of pages available.
  • total_count (integer): Total number of surveys you have access to across all pages.

Get survey Read-only

Fetch a survey’s details and the questionnaires you can read on it.

Parameters

  • survey_id (integer, required): The survey ID (numeric)

Response

  • id (integer): Survey ID
  • name (string or null): Survey name
  • created_at (string): Creation timestamp (ISO 8601)
  • updated_at (string): Last update timestamp (ISO 8601)
  • url (string): Potloc URL for the survey
  • questionnaires (array of object): Questionnaires you can read on this survey
    • id (integer): Questionnaire ID
    • title (string): Questionnaire title
    • status (string or null): Questionnaire lifecycle status
      • Values: draft, optimizing, review, completed
    • potloc_crafted (boolean): True when Potloc’s research team crafts this questionnaire for you as part of your engagement, which keeps it read-only here so the methodology stays intact. False when you built it yourself, which makes it yours to edit until it reaches review.
    • language_code (string): Source language of the questionnaire (IETF tag, e.g. “en”).

Get questionnaire Read-only

Fetch a questionnaire with all its respondent-facing elements and answers, the deleted ones included. Returns the full questionnaire structure for review. Element and answer ids are stable: they survive publishing and stay the same across versions.

Parameters

  • questionnaire_id (integer, required): The questionnaire ID (numeric)

Response

  • id (integer): Questionnaire ID
  • title (string): Questionnaire title
  • survey_id (integer): Parent survey ID
  • status (string or null): Questionnaire lifecycle status
    • Values: draft, optimizing, review, completed
  • potloc_crafted (boolean): True when Potloc’s research team crafts this questionnaire for you as part of your engagement, which keeps it read-only here so the methodology stays intact. False when you built it yourself, which makes it yours to edit until it reaches review.
  • updated_at (string): Last update timestamp (ISO 8601)
  • url (string): Potloc URL for the questionnaire
  • elements (array of object): Elements in the current version, ordered by position
    • id (integer): Stable element id: the same across questionnaire versions and publishes. Pass it to the element tools.
    • type (string): Element type
      • Values: BlockElement, InstructionElement, LoopElement, MessageElement, QuestionElement, TerminationElement
    • position (integer): 0-based position
    • deleted_at (string, optional): When this element was deleted (ISO 8601). It is not part of the questionnaire a respondent answers. Omitted while the element is live.
    • value (string, optional): Element text content: a question or message title as HTML, with each inserted earlier answer and each condition in braces ({S5}, {IF S5.1} … {ELSE} … {END}). Plain text on every other element type. Omitted when unset.
    • label (string, optional): Element label. Omitted when unset.
    • status (string, optional): Review status. Omitted when unset.
    • display_logic (string, optional): The display logic that decides whether respondents see the element, as an expression (e.g. QAGE > 18 AND S5.1). Omitted when there is none, in which case display_logic_for_scripting may still carry written display logic. On a TerminationElement this is its screen-out rule. Can only be edited on Potloc. Syntax: https://docs.potloc.com/mcp/expression-syntax/
    • display_logic_for_scripting (string, optional): Written display logic, a note for the team scripting this questionnaire. It does not by itself change which respondents see the element: when display_logic is present, display_logic decides. A TerminationElement never has it: its written rule is in value and its screen-out rule in display_logic. Omitted when unset.
    • instructions_for_respondent (string, optional): Instructions shown to respondents as HTML, with each inserted earlier answer and each condition in braces ({S5}, {IF S5.1} … {ELSE} … {END}). Omitted when unset.
    • instructions_for_scripting (string, optional): Instructions for the team scripting this questionnaire. Omitted when unset.
    • min_loi (number, optional): Minimum length of interview in points. Omitted when unset.
    • max_loi (number, optional): Maximum length of interview in points. Omitted when unset.
    • question_type (string, optional): Question type key (QuestionElement only). Omitted when unset.
    • row_order (string, optional): Row answer order (QuestionElement only). Omitted when unset.
    • column_order (string, optional): Column answer order (QuestionElement only). Omitted when unset.
    • row_order_source_question_id (integer, optional): Stable id of the question whose per-respondent row order the rows follow, matched by answer label (QuestionElement with row_order source only). Omitted otherwise.
    • column_order_source_question_id (integer, optional): Stable id of the question whose per-respondent column order the columns follow, matched by answer label (QuestionElement with column_order source only). Omitted otherwise.
    • answer_groups (array of object, optional): Group headers of the row answers (single_select, multiple_select and conjoint QuestionElements). On a conjoint, each group is an attribute and its rows are that attribute’s levels. Omitted when the question has none.
      • id (integer): Stable group id: the same across questionnaire versions and publishes. Send it back to keep the group when editing the answer groups.
      • title (string, optional): Group header as HTML. Omitted when unset.
      • condition (string, optional): Show/hide condition for the whole group and its rows, as text. Only present on Potloc runtime questionnaires; omitted when the group has none.
      • position (integer): Order of the group among the question’s groups, from 0
      • answer_order (string): How the rows inside the group are ordered for respondents
      • fixed (boolean, optional): true when the group keeps its slot while the question shuffles its groups. Omitted otherwise.
    • answers (array of object, optional): Answers (QuestionElement only)
      • id (integer): Stable answer id: the same across questionnaire versions and publishes.
      • label (string, optional): Answer label. Omitted when unset.
      • title (string, optional): Answer display text as HTML, with each inserted earlier answer and each condition in braces ({S5}, {IF S5.1} … {ELSE} … {END}). Omitted when unset.
      • position (integer): Answer position
      • answer_group_id (integer, optional): Stable id of the group this row belongs to. Omitted on an ungrouped answer.
      • deleted_at (string, optional): When this answer was deleted (ISO 8601). It is not offered to respondents. Omitted while the answer is live.
      • direction (string): row or column (grid questions), or footer for an opt-out under the whole question
      • opt_out (boolean, optional): true on an opt-out: a checkbox letting the respondent skip the question rather than answer it. Omitted otherwise.
      • condition (string, optional): The condition deciding whether respondents see this answer, as an expression (e.g. QAGE > 18). Omitted when there is none, in which case condition_for_scripting may still carry written text. Can only be edited on Potloc. Syntax: https://docs.potloc.com/mcp/expression-syntax/
      • condition_for_scripting (string, optional): Written condition, a note for the team scripting this questionnaire. It does not by itself change whether respondents see the answer: when condition is present, condition decides. Omitted when unset.
      • attributes (array of string, optional): Answer attributes: NE=non-eligible, E=exclusive, F=fixed, OE=open-end. Omitted when the answer has none (i.e. eligible, non-exclusive, unfixed, closed).
        • Values: NE, E, F, OE
    • termination_reason (string or null, optional): Termination reason (TerminationElement only)
    • parent_element_id (integer, optional): Stable id of the parent element (section, loop, or block) when nested inside one
    • source_question_id (integer, optional): Stable id of the source question (LoopElement only)
    • randomize_children (boolean, optional): Whether the block shows its direct children in a random order per respondent (BlockElement only)

Create questionnaire Writes

Create a new questionnaire on one of your surveys, in draft, ready for you to add elements to.

Parameters

  • survey_id (integer, required): The survey the questionnaire belongs to
  • title (string, required): Questionnaire title. Must be unique within the survey.
  • language_code (string, required): IETF language tag the questionnaire is written in. Supported values: ‘en’ (English), ‘fr’ (French).
    • Values: en, fr

Response

  • id (integer): The created questionnaire ID
  • created_at (string): Creation timestamp (ISO 8601)

Update questionnaire Writes

Rename a questionnaire.

Parameters

  • questionnaire_id (integer, required): The questionnaire ID
  • title (string, required): New title. Must be unique within the survey.

Response

  • id (integer): The questionnaire ID
  • updated_at (string): Last update timestamp (ISO 8601)

Add questionnaire element Writes

Add a question, message, instruction, termination, block or loop to a questionnaire. Every element and answer id, in the arguments and in the response, is stable across versions and publishes.

Parameters

  • questionnaire_id (integer, required): The questionnaire to add the element to
  • type (string, required): Element type. QuestionElement asks something, MessageElement shows text to the respondent, InstructionElement documents intent without being shown, TerminationElement ends the interview, BlockElement and LoopElement contain other elements.
    • Values: BlockElement, InstructionElement, LoopElement, MessageElement, QuestionElement, TerminationElement
  • value (string): Element text content — the question title on a QuestionElement, the copy on a MessageElement
  • label (string): Element label identifier (e.g. Q1, S1). Must be unique within the questionnaire.
  • position (integer): Position in the element list (0-based). Defaults to the end.
  • question_type (string): How the question is asked and answered (required for QuestionElement)
    • Values: accordion, autosuggest, autosum, conjoint, date_picker, dropdown_menu, essay, max_diff, multiple_select, multiple_select_card_sort, multiple_select_grid, net_promoter_score, number, rank_sort, sequential_text, single_select, single_select_card_sort, single_select_grid, slider, star_rating, text
  • termination_reason (string): Why the interview ends (required for TerminationElement). eligibility=screened out, attention=failed attention check, coherence=failed coherence check, over_quota=a quota the rule reads is full
    • Values: eligibility, attention, coherence, over_quota
  • source_question_id (integer): Stable id of the question whose answers drive the loop iteration (required for LoopElement). Must be an element of the same questionnaire.
  • child_element_ids (array of integer): Stable element ids to nest under this element, replacing its current children. Only applies to LoopElement and BlockElement.
  • parent_element_id (integer): Stable id of the BlockElement or LoopElement this element is nested under. Must be an element of the same questionnaire.
  • display_logic_for_scripting (string): Written display logic, a note for the team scripting the questionnaire. It does not by itself change who sees the element: when get_questionnaire returns display_logic, that expression decides, and it can only be edited on Potloc. Applies to QuestionElement, MessageElement and BlockElement. A TerminationElement takes no display_logic_for_scripting: its written rule is value and its screen-out rule reads in display_logic. display_logic is read-only and not accepted here.
  • instructions_for_respondent (string): Instructions shown to respondents. Only applies to QuestionElement. Plain text, no HTML.
  • items_per_screen (integer): Number of rows each screen of a max_diff question shows, 3 or more and no more than its rows. It cannot change once a version is published. Required on a max_diff QuestionElement and dropped on every other question type
  • screen_count (integer): Number of screens a max_diff or conjoint question shows, 1 or more. Required on a max_diff or conjoint QuestionElement and dropped on every other question type
  • randomize_children (boolean): Whether the block shows its direct children in a random order per respondent, each child moving with everything nested in it. An element can’t reference one in another child of the block (display logic, piping, a screener’s termination, a loop’s source). Only applies to BlockElement
  • row_order (string): Order the row answers are presented in. Only applies to QuestionElement.
    • Values: alphabetical, ordered, randomized, source
  • column_order (string): Order the column answers are presented in. Only applies to QuestionElement.
    • Values: alphabetical, ordered, randomized, source
  • row_order_source_question_id (integer): Stable id of the question whose per-respondent row order the rows follow, matched by answer label. Required when row_order is source and dropped otherwise. Only applies to QuestionElement
  • column_order_source_question_id (integer): Stable id of the question whose per-respondent column order the columns follow, matched by answer label. Required when column_order is source and dropped otherwise. Only applies to QuestionElement
  • answer_groups (array of object): Group headers of the row answers, on a single_select, multiple_select, single_select_grid, multiple_select_grid or conjoint QuestionElement only. On a conjoint, each group is an attribute and its rows are that attribute’s levels. Rows join a group with answer_group_id.
    • id (string, required): Any string naming the group; the answers of the group point at it with answer_group_id
    • position (integer, required): Order of the group among the question’s groups, from 0. The rows of each group follow each other in the order of the groups, and a row in no group may sit above, between or below the groups
    • answer_order (string, required): How the rows inside the group are ordered for respondents
      • Values: alphabetical, ordered, randomized
    • title (string, required): Group header shown above its rows. Plain text, no HTML.
    • fixed (boolean): true keeps the group in its slot when the question shuffles its groups. Not allowed on a conjoint attribute
  • answers (array of object): Answer choices (QuestionElement only)
    • label (string, required): Answer label (e.g. A1). Must be unique among the answers sharing this direction.
    • title (string, required): Answer text shown to the respondent
    • position (integer): Answer position (0-based)
    • answer_group_id (string): The id of the group this row belongs to, as sent in answer_groups. A row sent without one belongs to no group and keeps its position, above, between or below the groups; while answer_groups is omitted, an existing row keeps its group.
    • direction (string, required): row for a plain answer or a grid row, column for a grid column, footer for an opt-out under the whole question, sent with opt_out: true
      • Values: row, column, footer
    • opt_out (boolean): true on an opt-out: a checkbox letting the respondent skip the question rather than answer it. Only with direction footer, which requires it; only on autosum/essay/number/rank_sort/sequential_text/slider/text questions; no row may share its label. On a conjoint question, true on at most one column instead, which becomes the None option
    • condition_for_scripting (string): Written condition for this answer, a note for the team scripting the questionnaire. It does not by itself change whether the answer is shown: when get_questionnaire returns condition, that expression decides, and it can only be edited on Potloc. condition is read-only and not accepted here.
    • attributes (array of string): Answer attributes: NE=non-eligible (screens the respondent out), E=exclusive (clears the other selections, so not on single_select/autosuggest/single_select_grid/dropdown_menu/accordion/single_select_card_sort/star_rating/net_promoter_score/single_select_recode/rank_sort/coherence_check/coherence_check_minor/max_diff/conjoint questions), F=fixed (stays put when the answers are randomized), OE=open-end (adds a free-text box; rows only, on single_select/autosuggest/multiple_select/single_select_grid/multiple_select_grid/dropdown_menu/net_promoter_score/rank_sort/number/autosum/text/essay/slider/star_rating/single_select_card_sort/multiple_select_card_sort/accordion questions)
      • Values: NE, E, F, OE

Response

  • id (integer): The created element ID
  • created_at (string): Creation timestamp (ISO 8601)

Update questionnaire element Writes

Edit a questionnaire element: its text, answers, display logic for scripting, instructions and nesting. Each attribute you send replaces its current value, and a replaced value can’t be recovered through this server. Omitted attributes are left alone, and omitting answers leaves the answer list untouched, except that switching question_type to star_rating or net_promoter_score replaces the columns with that type’s scale and removes any opt-out, and switching it to max_diff replaces the columns with Most, Not picked and Least. A deleted element is read-only: naming the id of one get_questionnaire returned with a deleted_at is refused until it is restored. Element and answer ids are stable across versions and publishes, so ids from an earlier read stay valid.

Parameters

  • element_id (integer, required): The stable element id, as returned by get_questionnaire
  • attributes (object, required): The attributes to change. Send only what you want changed.
    • value (string): Element text content — the question title on a QuestionElement, the copy on a MessageElement
    • label (string): Element label identifier (e.g. Q1, S1). Must be unique within the questionnaire, and cannot be cleared once set.
    • position (integer): Position in the element list (0-based)
    • question_type (string): How the question is asked and answered (QuestionElement only)
      • Values: accordion, autosuggest, autosum, conjoint, date_picker, dropdown_menu, essay, max_diff, multiple_select, multiple_select_card_sort, multiple_select_grid, net_promoter_score, number, rank_sort, sequential_text, single_select, single_select_card_sort, single_select_grid, slider, star_rating, text
    • termination_reason (string): Why the interview ends (TerminationElement only). eligibility=screened out, attention=failed attention check, coherence=failed coherence check, over_quota=a quota the rule reads is full
      • Values: eligibility, attention, coherence, over_quota
    • source_question_id (integer): Question whose answers drive the loop iteration (LoopElement only). Must be an element of the same questionnaire.
    • child_element_ids (array of integer): Stable element ids to nest under this element, replacing its current children (send an empty array to clear them). Only applies to LoopElement and BlockElement.
    • parent_element_id (integer): Stable id of the BlockElement or LoopElement this element is nested under. Must be an element of the same questionnaire.
    • display_logic_for_scripting (string): Written display logic, a note for the team scripting the questionnaire. It does not by itself change who sees the element: when get_questionnaire returns display_logic, that expression decides, and it can only be edited on Potloc. Applies to QuestionElement, MessageElement and BlockElement. A TerminationElement takes no display_logic_for_scripting: its written rule is value and its screen-out rule reads in display_logic. display_logic is read-only and not accepted here.
    • instructions_for_respondent (string): Instructions shown to respondents. Only applies to QuestionElement. Plain text, no HTML. Instructions that insert an earlier answer or have conditions only accept back, unchanged, the instructions_for_respondent get_questionnaire returns; any other text is refused.
    • items_per_screen (integer): Number of rows each screen of a max_diff question shows, 3 or more and no more than its rows. It cannot change once a version is published. Required on a max_diff QuestionElement and dropped on every other question type
    • screen_count (integer): Number of screens a max_diff or conjoint question shows, 1 or more. Required on a max_diff or conjoint QuestionElement and dropped on every other question type
    • randomize_children (boolean): Whether the block shows its direct children in a random order per respondent, each child moving with everything nested in it. An element can’t reference one in another child of the block (display logic, piping, a screener’s termination, a loop’s source). Only applies to BlockElement
    • row_order (string): Order the row answers are presented in. Only applies to QuestionElement.
      • Values: alphabetical, ordered, randomized, source
    • column_order (string): Order the column answers are presented in. Only applies to QuestionElement.
      • Values: alphabetical, ordered, randomized, source
    • row_order_source_question_id (integer): Stable id of the question whose per-respondent row order the rows follow, matched by answer label. Required when row_order is source and dropped otherwise. Only applies to QuestionElement
    • column_order_source_question_id (integer): Stable id of the question whose per-respondent column order the columns follow, matched by answer label. Required when column_order is source and dropped otherwise. Only applies to QuestionElement
    • answer_groups (array of object): Group headers of the row answers, on a single_select, multiple_select, single_select_grid, multiple_select_grid or conjoint QuestionElement only. On a conjoint, each group is an attribute and its rows are that attribute’s levels. Rows join a group with answer_group_id.
      • id (string, required): Stable id of an existing group, as get_questionnaire returns it, or any other string to create one. Leaving an existing group out of the list deletes it, and its rows stay where they are, in no group. Omit answer_groups to keep the groups as they are. Removing the last row of a group is refused until answer_groups is sent without that group
      • position (integer, required): Order of the group among the question’s groups, from 0. The rows of each group follow each other in the order of the groups, and a row in no group may sit above, between or below the groups
      • answer_order (string, required): How the rows inside the group are ordered for respondents
        • Values: alphabetical, ordered, randomized
      • title (string, required): Group header shown above its rows. Plain text, no HTML.
      • fixed (boolean): true keeps the group in its slot when the question shuffles its groups. Not allowed on a conjoint attribute
    • answers (array of object): Full replacement of the answer choices (QuestionElement only). Every answer you want to keep must be listed, with its id for existing ones; answers left out are deleted, permanently unless a published version shows them or another element still refers to them. Pass [] to delete them all, or omit the field entirely to leave the answers unchanged. Send the deleted answers get_questionnaire returned back too, each carrying deleted: true, so they keep their slot in the order.
      • id (integer): Stable id of the answer to update. Omit to add a new answer. Naming a deleted answer’s id brings it back unless the row also carries deleted: true.
      • deleted (boolean): Send true on an existing answer’s id to place it in the order while keeping it out of the questionnaire — deleting it if it is still live. Omit it otherwise.
      • label (string, required): Answer label (e.g. A1). Must be unique among the answers sharing this direction.
      • title (string, required): Answer text shown to the respondent
      • position (integer): Answer position (0-based)
      • answer_group_id (string): The id of the group this row belongs to, as sent in answer_groups. A row sent without one belongs to no group and keeps its position, above, between or below the groups; while answer_groups is omitted, an existing row keeps its group.
      • direction (string, required): row for a plain answer or a grid row, column for a grid column, footer for an opt-out under the whole question, sent with opt_out: true
        • Values: row, column, footer
      • opt_out (boolean): true on an opt-out: a checkbox letting the respondent skip the question rather than answer it. Only with direction footer, which requires it; only on autosum/essay/number/rank_sort/sequential_text/slider/text questions; no row may share its label. On a conjoint question, true on at most one column instead, which becomes the None option
      • condition_for_scripting (string): Written condition for this answer, a note for the team scripting the questionnaire. It does not by itself change whether the answer is shown: when get_questionnaire returns condition, that expression decides, and it can only be edited on Potloc. condition is read-only and not accepted here.
      • attributes (array of string): Answer attributes: NE=non-eligible (screens the respondent out), E=exclusive (clears the other selections, so not on single_select/autosuggest/single_select_grid/dropdown_menu/accordion/single_select_card_sort/star_rating/net_promoter_score/single_select_recode/rank_sort/coherence_check/coherence_check_minor/max_diff/conjoint questions), F=fixed (stays put when the answers are randomized), OE=open-end (adds a free-text box; rows only, on single_select/autosuggest/multiple_select/single_select_grid/multiple_select_grid/dropdown_menu/net_promoter_score/rank_sort/number/autosum/text/essay/slider/star_rating/single_select_card_sort/multiple_select_card_sort/accordion questions). A question that still holds an attribute its type rejects (OE on a row of another type, E on a single choice question) fails every save, even one that omits answers, until it is removed. Send the full answers list again and give each answer the error names its attributes without it.
        • Values: NE, E, F, OE

Response

  • id (integer): The stable element id
  • updated_at (string): Last update timestamp (ISO 8601)

Delete questionnaire element Writes

Delete an element from a questionnaire. Deleting a loop or block also deletes every element inside it, unless keep_descendants is true, which spares them and moves them up one level, into the element that held it. Positions of the remaining elements are adjusted for you. The element keeps a slot of its own and get_questionnaire keeps returning it with a deleted_at, so restore_questionnaire_element can bring it back; naming one already deleted reports it as already deleted.

Parameters

  • element_id (integer, required): The stable element id to delete, as returned by get_questionnaire
  • keep_descendants (boolean): Whether the elements inside a loop or block survive its deletion. Defaults to false; pass true to spare them and move them up one level, into the element that held it.

Response

  • id (integer): The deleted element’s stable id
  • deleted_at (string): Deletion timestamp (ISO 8601)

Restore questionnaire element Writes

Bring a deleted element back into a questionnaire, in the slot it held while deleted. Everything deleted together with it comes back too (deleted within a minute of it, before or after): a loop’s or block’s contents, a question’s answers. Anything deleted separately stays deleted, so re-read the element after a restore. An element whose parent block or loop is still deleted comes back at the top level.

Parameters

  • element_id (integer, required): The stable element id to restore, as returned by get_questionnaire carrying a deleted_at

Response

  • id (integer): The restored element’s stable id
  • updated_at (string): Last update timestamp (ISO 8601)

List questionnaire translations Read-only

List a questionnaire’s translations into one language, with the source text and the current translation side by side for each element and answer, and whether each is outdated (missing, or drifted from the source). Scope with element_ids to read only some elements. Paginated (page / per_page): on a long questionnaire, read a page, save corrections with update_questionnaire_translations, then fetch the next.

Parameters

  • questionnaire_id (integer, required): The questionnaire ID
  • language_code (string, required): Target language code (IETF tag, e.g. “es”)
  • element_ids (array of integer): Only return the elements with these stable ids. Omit for the whole questionnaire.
  • page (integer): Page number (1-indexed). Defaults to 1.
  • per_page (integer): Elements per page (default 25, max 50)

Response

  • questionnaire_id (integer): The questionnaire ID
  • language_code (string): Target language code
  • source_language_code (string): Language of the source_* fields (the questionnaire’s own language)
  • elements (array of object): Elements to translate, in position order. A recode’s own title is never shown, so translate only its answers
    • id (integer): The stable element id
    • label (string or null): Element label (e.g. Q1)
    • source_value (string or null): Source-language element title as HTML, with each inserted earlier answer and each condition in braces ({S5}, {IF S5.1} … {ELSE} … {END})
    • translated_value (string or null): Current translation of the element title, read the same way as source_value
    • source_instructions (string or null): Source-language respondent instructions as HTML, with each inserted earlier answer and each condition in braces ({S5}, {IF S5.1} … {ELSE} … {END})
    • translated_instructions (string or null): Current translation of the respondent instructions, read the same way as source_instructions
    • outdated (boolean): True if the element translation is missing or has drifted from the source
    • answers (array of object): Answers under this element (empty for message elements)
      • id (integer): The stable answer id
      • label (string or null): Answer label
      • source_title (string or null): Source-language answer text as HTML, with each inserted earlier answer and each condition in braces ({S5}, {IF S5.1} … {ELSE} … {END})
      • translated_title (string or null): Current translation of the answer text, read the same way as source_title
      • outdated (boolean): True if the answer translation is missing or has drifted from the source
  • page (integer): Current page number (1-indexed)
  • total_pages (integer): Total number of pages
  • total_count (integer): Total number of elements to translate across all pages

Update questionnaire translations Writes

Save translations of a questionnaire into one of its languages: element text, respondent instructions and answer titles. Each record you touch is marked as reviewed, which clears its outdated flag. One language per call. Omit a field to leave it unchanged; send “” to clear it. Element and answer ids are the ones list_questionnaire_translations returns.

Parameters

  • questionnaire_id (integer, required): The questionnaire ID
  • language_code (string, required): Target language code (IETF tag, e.g. “es”)
  • elements (array of object, required): Elements to update in this language
    • id (integer, required): The stable element id
    • value (string): Translated element title. Omit to leave unchanged; “” clears it. A translation that inserts an earlier answer or has conditions only accepts back its translated_value unchanged.
    • instructions_for_respondent (string): Translated respondent instructions. Plain text, no HTML. Omit to leave unchanged; “” clears it. A translation that inserts an earlier answer or has conditions only accepts back its translated_instructions unchanged.
    • answers (array of object): Answers under this element to update
      • id (integer, required): The stable answer id
      • title (string): Translated answer text. Omit to leave unchanged; “” clears it. A translation that inserts an earlier answer or has conditions only accepts back its translated_title unchanged.

Response

  • id (integer): The questionnaire ID
  • updated_at (string): Last update timestamp (ISO 8601)

List questionnaire comments Read-only

List the comments on a questionnaire, oldest first: the ones you left and the answers from Potloc’s research team. Reaches across the whole of the questionnaire’s current version so you can sweep it for outstanding feedback in one call; pass element_id to narrow to a single element. Each comment carries the element it belongs to. A questionnaire you hold no role on comes back as an empty page.

Parameters

  • questionnaire_id (integer, required): The questionnaire ID (numeric)
  • element_id (integer): Optional. Narrow results to comments on a single element of the questionnaire, by its stable id. Omit to list comments across the whole questionnaire.
  • page (integer): Page number (1-indexed). Defaults to 1.
  • per_page (integer): Results per page (default 25, max 100).

Response

  • comments (array of object): Comments on the questionnaire’s current-version elements, oldest first
    • id (integer): Comment ID
    • element_id (integer): Stable id of the questionnaire element the comment is attached to
    • element_label (string or null): Label of the element (e.g. “Q20”), null when it has none
    • body (string or null): Comment text, as HTML
    • created_by (object or null): The user who wrote the comment. Null on comments that predate authorship tracking.
      • id (integer): User ID
      • name (string or null): First and last name joined; null when the user has neither
    • created_at (string): Creation timestamp (ISO 8601)
    • updated_at (string): Last update timestamp (ISO 8601)
  • page (integer): Current page number (1-indexed).
  • total_pages (integer): Total number of pages available.
  • total_count (integer): Total number of comments you can read on the questionnaire across all pages.

Add questionnaire comment Writes

Leave a comment on a questionnaire element, to ask Potloc’s research team for a review or to answer what they wrote back. Every comment you leave is visible to them, and to everyone else who can open the survey. Leaving one also notifies the people subscribed to the questionnaire’s comment notifications, and your first comment on a questionnaire subscribes you to them. It stands once left: to change it, leave another or edit it on the platform.

Parameters

  • element_id (integer, required): The stable id of the questionnaire element to comment on, as returned by get_questionnaire
  • body (string, required): Comment text. Formatting may use these HTML tags: p, br, strong, b, em, i, u, span, div, blockquote, ul, ol, li, h1, h2, h3, h4, h5, h6, a, mark, sup, sub, s, del, code, pre, hr. Anything else is stripped.

Response

  • id (integer): The created comment ID
  • created_at (string): Creation timestamp (ISO 8601)

List questions Read-only

List the questions on a survey that results are reported on, in the order they appear. These are the final, recoded questions ready to chart, not the raw imported fields. Each carries the display types and value formats a chart on it supports. Four identifiers come back per question: id is the stable one, the same value get_chart_data and get_report carry for the question a chart is built on; question_number is the reference a stakeholder cites (Q14, REVENUE); title is the question as a respondent reads it; and label is a short name shown in place of the title when the survey sets one.

Parameters

  • survey_id (integer, required): The survey ID (numeric)
  • page (integer): Page number (1-indexed). Defaults to 1.
  • per_page (integer): Results per page (default 25, max 100).

Response

  • questions (array of object): Questions on the survey for the current page, in the order they appear
    • id (integer): Question ID
    • label (string or null): Short name set on the question in place of its title. Null when it has none.
    • title (string): Question title
    • question_type (string): Question type key, in the analysis vocabulary rather than the questionnaire’s: netPromoterScore arrives here as nps, autosum as continuous_sum, rankSort as ranking, and the select types as choices
      • Values: text, choices, email, number, postal_code, nps, rating, matrix, ranking, continuous_sum
    • question_number (string or null): The question’s identifier (e.g. Q14, REVENUE, QINDUSTRY), built from the element’s label in the questionnaire
    • position (integer): 0-based position
    • valid_display_types (array of string): Display types a chart on this question supports.
      • Values: table, bar_graph, column_graph, donut_graph, stacked_bar_graph, stacked_column_graph, line_graph, histogram_graph, nps_stacked_column_graph, nps_graph
    • valid_formats (array of string): Value formats a chart on this question supports.
      • Values: count, percentage, rating
    • conjoint_utilities (boolean): Whether the question holds a conjoint’s utilities. Its id is the one get_conjoint_design, get_conjoint_simulation and a conjoint_simulator block take.
  • page (integer): Current page number (1-indexed).
  • total_pages (integer): Total number of pages available.
  • total_count (integer): Total number of questions you can read on the survey across all pages.

Get conjoint design Read-only

Read the attributes and levels of a conjoint, with the level ids that get_conjoint_simulation takes in its plans.

Parameters

  • question_id (integer, required): ID of the conjoint’s utilities question, from list_questions, where its conjoint_utilities is true

Response

  • question_id (integer): The conjoint utilities question ID
  • question_number (string or null): Question number of the utilities question
  • attributes (array of object): Attributes of the conjoint, in the questionnaire’s order
    • name (string): Attribute name
    • levels (array of object): The attribute’s levels, in the questionnaire’s order
      • id (integer): Level id to put in a get_conjoint_simulation plan. It is the row answer’s id in get_questionnaire.
      • title (string): Level title
  • has_none_option (boolean): Whether the conjoint has a None option, which get_conjoint_simulation’s include_none needs

Get conjoint simulation Read-only

Run a market simulation on a conjoint: each plan’s share of the respondents. Read the level ids to put in the plans with get_conjoint_design. A plan leaves a respondent’s choice set when they never saw one of its levels. Shares are weighted when the survey is. Nothing is saved.

Parameters

  • question_id (integer, required): ID of the conjoint’s utilities question, from list_questions, where its conjoint_utilities is true
  • plans (array of array, required): Plans to simulate. Each plan is an array of level ids from get_conjoint_design, one level of every attribute, in any order. For example [[101, 205], [102, 206]] simulates two plans on a conjoint with two attributes.
  • rule (string): share_of_preference (default) splits each respondent between the plans by the logit of their utilities. first_choice gives each respondent to the plan with their highest utility.
    • Values: share_of_preference, first_choice
  • include_none (boolean): Whether respondents can pick None instead of a plan. Defaults to false. Needs has_none_option in get_conjoint_design.
  • filter_answer_ids (array of integer): Answer ids on questions of this survey to keep only the respondents who picked them, as the filters on a chart do

Response

  • rule (string): Rule the shares come from
    • Values: share_of_preference, first_choice
  • include_none (boolean): Whether None was in every choice set
  • plans (array of object): One entry per plan, in the order given
    • levels (array of object): The plan’s levels, in attribute order
      • id (integer): Level id
      • attribute (string): Attribute name
      • title (string): Level title
    • share (number or null): Share of the respondents, from 0 to 1. Null when respondent_count is 0.
  • none_share (number or null): Share of the respondents who pick None, from 0 to 1. Null when None is left out or respondent_count is 0.
  • respondent_count (integer): Number of respondents the shares cover: those who match the filters and saw every level of at least one plan
  • weighted_respondent_count (number): Sum of their weights. Equals respondent_count on a survey without weighting.

List reports Read-only

List the reports on a survey, most recently created first: every report shared with the survey, plus any private one you created yourself. visibility says who can view each one. Read one’s contents with get_report.

Parameters

  • survey_id (integer, required): The survey ID (numeric)
  • page (integer): Page number (1-indexed). Defaults to 1.
  • per_page (integer): Results per page (default 25, max 100).

Response

  • reports (array of object): Reports on the survey for the current page, most recently created first
    • id (integer): Report ID
    • title (string): Report title
    • description (string or null): What the report covers and who it is for; null when none was written
    • visibility (object): Who can view the report
      • level (string): private is a draft only you can see, project is everyone holding a permission on the survey, public adds anyone holding its public link
        • Values: private, project, public
      • public_url (string, optional): The link that opens the report without signing in (only present when level is public)
      • password_protected (boolean, optional): Whether the link asks for a password before opening the report (only present when level is public)
    • created_by (object or null): The user who created the report. Null on reports that predate authorship tracking.
      • id (integer): User ID
      • name (string or null): First and last name joined; null when the user has neither
    • blocks_count (integer): Number of blocks (charts, text, images, sections) on the report
    • url (string): Potloc URL for the report
    • created_at (string): Creation timestamp (ISO 8601)
  • page (integer): Current page number (1-indexed).
  • total_pages (integer): Total number of pages available.
  • total_count (integer): Total number of reports you can read on the survey across all pages.

Get report Read-only

Read a report with all its blocks, charts, and structure. Reports shared with the survey and your own private ones are readable; visibility says who can view it. Blocks are listed flat, ordered by position; a block nested in a section carries that section’s id. Chart blocks carry a chart with the id to pass to get_chart_data for the underlying numbers. Conjoint simulator blocks carry the simulation they save in conjoint_simulator.

Parameters

  • report_id (integer, required): The report ID (numeric), from list_reports

Response

  • id (integer): Report ID
  • survey_id (integer): Parent survey ID
  • title (string): Report title
  • description (string or null): What the report covers and who it is for; null when none was written
  • visibility (object): Who can view the report
    • level (string): private is a draft only you can see, project is everyone holding a permission on the survey, public adds anyone holding its public link
      • Values: private, project, public
    • public_url (string, optional): The link that opens the report without signing in (only present when level is public)
    • password_protected (boolean, optional): Whether the link asks for a password before opening the report (only present when level is public)
  • created_by (object or null): The user who created the report. Null on reports that predate authorship tracking.
    • id (integer): User ID
    • name (string or null): First and last name joined; null when the user has neither
  • url (string): Potloc URL for the report
  • filter_answer_ids (array of integer): Answer ids the report filters its respondents by, on questions list_questions returns. A conjoint simulator block’s shares follow every filter of the report, so a rerun with these differs when the report also filters on a question list_questions leaves out.
  • blocks (array of object): Blocks on the report, ordered by position
    • id (integer): Block ID
    • type (string or null): Block class name (e.g. ChartBlock, TextBlock, ImageBlock, SectionBlock, ConjointSimulatorBlock)
    • position (integer or null): 1-based position on the report
    • display_width (string or null): Block display width
      • Values: full, half
    • title (string or null, optional): Block title
    • section_block_id (integer, optional): Parent section block ID (only present when nested in a section)
    • body (string or null, optional): Annotation commentary as HTML: written on the block itself for text and image blocks, on the chart for chart blocks
    • chart (object, optional): The chart the block renders (only for chart blocks)
      • id (integer): Chart ID to pass to get_chart_data
      • title (string or null, optional): Chart title. The block’s own title is usually blank on a chart block, so this is the name the report shows.
      • question (object): The survey question the chart is built from
        • id (integer): Survey question ID
        • number (string or null): Question number (e.g. Q14, REVENUE, QINDUSTRY)
        • label (string or null): Question label
        • title (string): Question title
        • type (string or null): Question type key
    • conjoint_simulator (object, optional): The simulation the block saves (only for conjoint simulator blocks). Rerun it with get_conjoint_simulation, passing each plan’s level_ids, the rule, include_none and the report’s filter_answer_ids.
      • question_id (integer or null): The conjoint’s utilities question ID. Null once it is deleted.
      • question_number (string or null): Question number of the utilities question
      • plans (array of object): Saved plans, in order.
        • name (string or null): The plan’s name. Null when it has none and shows as Plan N from its position.
        • level_ids (array of integer): Level ids of the plan, one per attribute
      • rule (string): Rule the shares come from
        • Values: share_of_preference, first_choice
      • include_none (boolean): Whether respondents can pick None instead of a plan

Get chart data Read-only

Read the numbers behind a chart on one of your reports. Returns the chart’s table representation with columns, rows, and cell values (counts/percentages), plus the question it charts, its display type, and the number of respondents it covers.

Parameters

  • chart_id (integer, required): The chart ID (numeric), from a chart block in get_report or from create_report_block

Response

  • id (integer): Chart ID
  • title (string or null, optional): Chart title
  • question (object): The survey question the chart is built from
    • id (integer): Survey question ID
    • number (string or null): Question number (e.g. Q14, REVENUE, QINDUSTRY)
    • label (string or null): Question label
    • title (string): Question title
    • type (string or null): Question type key
  • display_type (string or null, optional): Chart visualization type
  • format (string or null, optional): Value format the chart renders
  • total_respondents (integer or null, optional): Number of respondents the chart covers, shown as n= on the chart
  • table (object or null, optional): Chart table (null when there is no tabular representation)
    • columns (array of object, optional)
      • id (string, optional): Column ID (table-presenter string key)
      • title (string or null, optional): Column title
    • rows (array of object, optional)
      • id (string or integer, optional): Row ID — string key for most presenters, integer index for number-question tables
      • position (integer, optional): 0-based row position
      • fixed (boolean, optional): Whether the row is fixed in position
      • cells (array of object, optional)
        • column_id (string, optional): Column ID the cell belongs to
        • value (any, optional): Cell value — integer (counts), float rounded to 2 decimals (percentages, means, ratings), or string.

Update report Writes

Rename or describe a report, or change who can view it. visibility private is a draft only its author can see, project hands it to everyone holding a permission on the survey, and public also turns on a public link anyone can open without signing in. Leaving public suspends that link, and going back to public restores the same URL and password. Moving a report in or out of private needs its author; turning the public link on or off needs a role that can share, Contributor or above. Renaming needs Creator. Omitted fields are left as they are.

Parameters

  • report_id (integer, required): The report ID (numeric), from list_reports
  • title (string): New report title
  • description (string): What the report covers and who it is for, 450 characters at most. An empty string clears it.
  • visibility (string): Who can view the report. project and private suspend the public link if there is one, and public brings it back with the same URL and password.
    • Values: private, project, public

Response

  • id (integer): Report ID
  • updated_at (string): Last update timestamp (ISO 8601)
  • visibility (object): Who can view the report
    • level (string): private is a draft only you can see, project is everyone holding a permission on the survey, public adds anyone holding its public link
      • Values: private, project, public
    • public_url (string, optional): The link that opens the report without signing in (only present when level is public)
    • password_protected (boolean, optional): Whether the link asks for a password before opening the report (only present when level is public)

Reorder report blocks Writes

Reorder a report’s blocks, and move them in or out of a section: a section groups the blocks placed in it with section_block_id. Pass every block you are moving with the 1-based position it should end up at, reading the ids off get_report. A block you leave out keeps the position it has, so send the report’s whole order rather than the one block you moved, or two blocks end up sharing a position.

Parameters

  • report_id (integer, required): The report ID (numeric), from list_reports
  • blocks (array of object, required): The blocks to move, each with the position it should end up at
    • id (integer, required): Block ID, from get_report
    • position (integer, required): New 1-based position on the report
    • section_block_id (integer or null): Section block ID to move the block into, from get_report (null to take it out of its section). Omit to leave the block’s section as it is. A section cannot be moved into another section.

Response

  • blocks (array of object): The moved blocks, ordered by their new position
    • id (integer): Block ID
    • type (string or null): Block class name (e.g. ChartBlock, TextBlock, ImageBlock, SectionBlock)
    • title (string or null): Block title
    • position (integer or null): 1-based position on the report
    • section_block_id (integer or null): Section block ID the block sits in, or null when it sits in none

Create report Writes

Start a new report on a survey. It is created empty and private, so only you can see it until update_report changes its visibility. Fill it in with create_report_block.

Parameters

  • survey_id (integer, required): The survey to build the report on, from list_surveys
  • title (string, required): Report title
  • description (string): What the report covers and who it is for, 450 characters at most.

Response

  • id (integer): The created report ID
  • created_at (string): Creation timestamp (ISO 8601)

Add report block Writes

Create one block on a report: a chart of a survey question, a section that groups the blocks placed in it with section_block_id, a paragraph of written commentary, or a conjoint simulator that saves a market simulation. kind picks which, and decides what else is required: question_id for a chart, title for a section, body for text, question_id and title for a conjoint simulator. Pass section_block_id to create a block other than a section inside a section. A chart inherits the crossing and breakdown the report’s existing charts already share, and only when they all agree on one; breakdown inheritance follows crossing inheritance, since a breakdown refines a crossing. Pass crossing_question_ids or breakdown_question_ids (an empty array included) to opt out of the matching half.

Parameters

  • report_id (integer, required): The report to add the block to, from list_reports
  • kind (string, required): What to add: chart plots one survey question, section groups other blocks under a heading, text is written commentary, conjoint_simulator saves the shares of plans on a conjoint. A conjoint simulator’s shares follow the report’s filters.
    • Values: chart, section, text, conjoint_simulator
  • question_id (integer): The survey question to plot (required when kind is chart), or the conjoint’s utilities question (required when kind is conjoint_simulator, where its conjoint_utilities is true). Must belong to the report’s survey. Get it from list_questions.
  • title (string): The heading (required when kind is section or conjoint_simulator). On a chart, overrides the title derived from the question.
  • body (string): Commentary as HTML (required when kind is text; only p, br, strong, b, em, i, u, span, div, blockquote, ul, ol, li, h1, h2, h3, h4, h5, h6, a, mark, sup, sub, s, del, code, pre, hr tags are kept). On a chart, it becomes the note shown with the chart.
  • display_type (string): How the chart renders. Must be one of the question’s valid_display_types, which list_questions returns; anything else is rejected. Omit to get the sensible default for the question’s type.
    • Values: table, bar_graph, column_graph, donut_graph, stacked_bar_graph, stacked_column_graph, line_graph, histogram_graph, nps_stacked_column_graph, nps_graph
  • crossing_question_ids (array of integer): Survey question IDs to cross the chart by. Each must belong to the report’s survey and be a choices question. An empty array creates the chart uncrossed instead of inheriting the report’s crossing.
  • breakdown_question_ids (array of integer): Survey question IDs to break the chart down by. Each must belong to the report’s survey and be a choices question. An empty array creates the chart with no breakdown instead of inheriting the report’s.
  • plans (array of object): Only when kind is conjoint_simulator: the plans to save. Each plan takes level ids from get_conjoint_design, one level of every attribute in any order, and an optional name. Omit to save 3 plans that take each attribute’s levels in turn.
    • name (string): The plan’s name. Omit it, or leave it blank, to show the plan as Plan N from its position.
    • level_ids (array of integer, required): Level ids of the plan, one per attribute
  • rule (string): Only when kind is conjoint_simulator. share_of_preference (default) splits each respondent between the plans by the logit of their utilities. first_choice gives each respondent to the plan with their highest utility.
    • Values: share_of_preference, first_choice
  • include_none (boolean): Only when kind is conjoint_simulator: whether respondents can pick None instead of a plan. Needs has_none_option in get_conjoint_design. Defaults to true when the conjoint has a None option.
  • section_block_id (integer): The section to create the block in, from get_report. Not accepted when kind is section, since a section cannot sit inside another. Omit to keep the block outside any section.
  • position (integer): 1-based position on the report. Defaults to the end.

Response

  • id (integer): The created block ID
  • chart_id (integer, optional): The created chart’s ID, to pass to get_chart_data (only when kind is chart)
  • created_at (string): Creation timestamp (ISO 8601)

List data layouts Read-only

List a survey’s data layouts, each one a shape its responses can be read in. Pass an id to list_responses to read through that layout. Requires full access on the survey.

Parameters

  • survey_id (integer, required): Survey to list data layouts for.
  • page (integer): Page number, defaults to 1.
  • per_page (integer): Layouts per page, defaults to 25.

Response

  • survey_id (integer): Survey the layouts belong to.
  • data_layouts (array of object): Data layouts, ordered by id.
    • id (integer): Pass this to list_responses as data_layout_id.
    • name (string): Layout name.
    • description (string or null): What Potloc says this layout is for.
    • columns_count (integer): Columns the layout exports, before multi-choice questions fan out.
  • page (integer): Page returned.
  • total_pages (integer): Pages at this page size.
  • total_count (integer): Data layouts on the survey.

List survey responses Read-only

Read a survey’s questionnaire responses, one row per respondent and one column per question, paginated. The shape comes from one of the survey’s data layouts, matching the spreadsheet that layout exports. Defaults to the survey’s default layout; pass data_layout_id for another, from list_data_layouts. Requires full access on the survey. Results are columnar, a flat column list plus a cell array per respondent, so payload size grows as page size x number of columns: a wide survey gets fewer rows per page than you asked for, and per_page in the response says how many.

Parameters

  • survey_id (integer, required): Survey to read responses from.
  • data_layout_id (integer): Data layout to read through. Defaults to the survey’s default layout.
  • page (integer): Page number, defaults to 1.
  • per_page (integer): Respondents per page, defaults to 25. Lowered on wide surveys to bound the payload.

Response

  • survey_id (integer): Survey the responses were read from.
  • data_layout_id (integer): Layout the columns and predicates came from.
  • data_layout_name (string): Name of that layout.
  • columns (array of object): The layout’s columns, in its order. Cell arrays follow this order.
    • header (string): Column header as the export writes it.
    • title (string or null): Question title behind the column.
    • type (string): Cell value type.
  • respondents (array of object): One entry per respondent on this page, holding only cells: no respondent identifier is exposed.
    • cells (array of string or null): Values positionally matching columns.
  • page (integer): Page returned.
  • per_page (integer): Respondents on this page, after the payload bound.
  • total_pages (integer): Pages at this page size.
  • total_count (integer): Respondents the data layout delivers.