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.
Identity
Section titled “Identity”get_current_user
Section titled “get_current_user”Get connected account Read-only
Return the Potloc account this connection is authenticated as.
Parameters
None.
Response
id(integer): Your user ID, the same idcreated_by.idcarries elsewherename(string or null): First and last name joined; null when you have neitheremail(string): Email address the account signs in with
Surveys
Section titled “Surveys”list_surveys
Section titled “list_surveys”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 firstid(integer): Survey IDname(string or null): Survey namecreated_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
Section titled “get_survey”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 IDname(string or null): Survey namecreated_at(string): Creation timestamp (ISO 8601)updated_at(string): Last update timestamp (ISO 8601)url(string): Potloc URL for the surveyquestionnaires(array of object): Questionnaires you can read on this surveyid(integer): Questionnaire IDtitle(string): Questionnaire titlestatus(string or null): Questionnaire lifecycle status- Values:
draft,optimizing,review,completed
- Values:
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”).
Questionnaires
Section titled “Questionnaires”get_questionnaire
Section titled “get_questionnaire”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 IDtitle(string): Questionnaire titlesurvey_id(integer): Parent survey IDstatus(string or null): Questionnaire lifecycle status- Values:
draft,optimizing,review,completed
- Values:
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 questionnaireelements(array of object): Elements in the current version, ordered by positionid(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
- Values:
position(integer): 0-based positiondeleted_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 0answer_order(string): How the rows inside the group are ordered for respondentsfixed(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 positionanswer_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 questionopt_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
- Values:
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 onesource_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
Section titled “create_questionnaire”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 totitle(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
- Values:
Response
id(integer): The created questionnaire IDcreated_at(string): Creation timestamp (ISO 8601)
update_questionnaire
Section titled “update_questionnaire”Update questionnaire Writes
Rename a questionnaire.
Parameters
questionnaire_id(integer, required): The questionnaire IDtitle(string, required): New title. Must be unique within the survey.
Response
id(integer): The questionnaire IDupdated_at(string): Last update timestamp (ISO 8601)
create_questionnaire_element
Section titled “create_questionnaire_element”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 totype(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
- Values:
value(string): Element text content — the question title on a QuestionElement, the copy on a MessageElementlabel(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
- Values:
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
- Values:
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 typescreen_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 typerandomize_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 BlockElementrow_order(string): Order the row answers are presented in. Only applies to QuestionElement.- Values:
alphabetical,ordered,randomized,source
- Values:
column_order(string): Order the column answers are presented in. Only applies to QuestionElement.- Values:
alphabetical,ordered,randomized,source
- Values:
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 QuestionElementcolumn_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 QuestionElementanswer_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_idposition(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 groupsanswer_order(string, required): How the rows inside the group are ordered for respondents- Values:
alphabetical,ordered,randomized
- Values:
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 respondentposition(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
- Values:
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 optioncondition_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
- Values:
Response
id(integer): The created element IDcreated_at(string): Creation timestamp (ISO 8601)
update_questionnaire_element
Section titled “update_questionnaire_element”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_questionnaireattributes(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 MessageElementlabel(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
- Values:
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
- Values:
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 typescreen_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 typerandomize_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 BlockElementrow_order(string): Order the row answers are presented in. Only applies to QuestionElement.- Values:
alphabetical,ordered,randomized,source
- Values:
column_order(string): Order the column answers are presented in. Only applies to QuestionElement.- Values:
alphabetical,ordered,randomized,source
- Values:
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 QuestionElementcolumn_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 QuestionElementanswer_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 groupposition(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 groupsanswer_order(string, required): How the rows inside the group are ordered for respondents- Values:
alphabetical,ordered,randomized
- Values:
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 carryingdeleted: 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 carriesdeleted: 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 respondentposition(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
- Values:
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 optioncondition_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
- Values:
Response
id(integer): The stable element idupdated_at(string): Last update timestamp (ISO 8601)
delete_questionnaire_element
Section titled “delete_questionnaire_element”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_questionnairekeep_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 iddeleted_at(string): Deletion timestamp (ISO 8601)
restore_questionnaire_element
Section titled “restore_questionnaire_element”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 idupdated_at(string): Last update timestamp (ISO 8601)
Questionnaire translations
Section titled “Questionnaire translations”list_questionnaire_translations
Section titled “list_questionnaire_translations”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 IDlanguage_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 IDlanguage_code(string): Target language codesource_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 answersid(integer): The stable element idlabel(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_valuesource_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_instructionsoutdated(boolean): True if the element translation is missing or has drifted from the sourceanswers(array of object): Answers under this element (empty for message elements)id(integer): The stable answer idlabel(string or null): Answer labelsource_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_titleoutdated(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 pagestotal_count(integer): Total number of elements to translate across all pages
update_questionnaire_translations
Section titled “update_questionnaire_translations”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 IDlanguage_code(string, required): Target language code (IETF tag, e.g. “es”)elements(array of object, required): Elements to update in this languageid(integer, required): The stable element idvalue(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 updateid(integer, required): The stable answer idtitle(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 IDupdated_at(string): Last update timestamp (ISO 8601)
Questionnaire comments
Section titled “Questionnaire comments”list_questionnaire_comments
Section titled “list_questionnaire_comments”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 firstid(integer): Comment IDelement_id(integer): Stable id of the questionnaire element the comment is attached toelement_label(string or null): Label of the element (e.g. “Q20”), null when it has nonebody(string or null): Comment text, as HTMLcreated_by(object or null): The user who wrote the comment. Null on comments that predate authorship tracking.id(integer): User IDname(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.
create_questionnaire_comment
Section titled “create_questionnaire_comment”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_questionnairebody(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 IDcreated_at(string): Creation timestamp (ISO 8601)
Questions
Section titled “Questions”list_questions
Section titled “list_questions”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 appearid(integer): Question IDlabel(string or null): Short name set on the question in place of its title. Null when it has none.title(string): Question titlequestion_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
- Values:
question_number(string or null): The question’s identifier (e.g. Q14, REVENUE, QINDUSTRY), built from the element’s label in the questionnaireposition(integer): 0-based positionvalid_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
- Values:
valid_formats(array of string): Value formats a chart on this question supports.- Values:
count,percentage,rating
- Values:
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
Section titled “get_conjoint_design”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 itsconjoint_utilitiesis true
Response
question_id(integer): The conjoint utilities question IDquestion_number(string or null): Question number of the utilities questionattributes(array of object): Attributes of the conjoint, in the questionnaire’s ordername(string): Attribute namelevels(array of object): The attribute’s levels, in the questionnaire’s orderid(integer): Level id to put in a get_conjoint_simulation plan. It is the row answer’sidin get_questionnaire.title(string): Level title
has_none_option(boolean): Whether the conjoint has a None option, which get_conjoint_simulation’sinclude_noneneeds
get_conjoint_simulation
Section titled “get_conjoint_simulation”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 itsconjoint_utilitiesis trueplans(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
- Values:
include_none(boolean): Whether respondents can pick None instead of a plan. Defaults to false. Needshas_none_optionin 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
- Values:
include_none(boolean): Whether None was in every choice setplans(array of object): One entry per plan, in the order givenlevels(array of object): The plan’s levels, in attribute orderid(integer): Level idattribute(string): Attribute nametitle(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 planweighted_respondent_count(number): Sum of their weights. Equals respondent_count on a survey without weighting.
Reports
Section titled “Reports”list_reports
Section titled “list_reports”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 firstid(integer): Report IDtitle(string): Report titledescription(string or null): What the report covers and who it is for; null when none was writtenvisibility(object): Who can view the reportlevel(string):privateis a draft only you can see,projectis everyone holding a permission on the survey,publicadds anyone holding its public link- Values:
private,project,public
- Values:
public_url(string, optional): The link that opens the report without signing in (only present whenlevelispublic)password_protected(boolean, optional): Whether the link asks for a password before opening the report (only present whenlevelispublic)
created_by(object or null): The user who created the report. Null on reports that predate authorship tracking.id(integer): User IDname(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 reporturl(string): Potloc URL for the reportcreated_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
Section titled “get_report”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 IDsurvey_id(integer): Parent survey IDtitle(string): Report titledescription(string or null): What the report covers and who it is for; null when none was writtenvisibility(object): Who can view the reportlevel(string):privateis a draft only you can see,projectis everyone holding a permission on the survey,publicadds anyone holding its public link- Values:
private,project,public
- Values:
public_url(string, optional): The link that opens the report without signing in (only present whenlevelispublic)password_protected(boolean, optional): Whether the link asks for a password before opening the report (only present whenlevelispublic)
created_by(object or null): The user who created the report. Null on reports that predate authorship tracking.id(integer): User IDname(string or null): First and last name joined; null when the user has neither
url(string): Potloc URL for the reportfilter_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 positionid(integer): Block IDtype(string or null): Block class name (e.g. ChartBlock, TextBlock, ImageBlock, SectionBlock, ConjointSimulatorBlock)position(integer or null): 1-based position on the reportdisplay_width(string or null): Block display width- Values:
full,half
- Values:
title(string or null, optional): Block titlesection_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 blockschart(object, optional): The chart the block renders (only for chart blocks)id(integer): Chart ID to pass to get_chart_datatitle(string or null, optional): Chart title. The block’s owntitleis usually blank on a chart block, so this is the name the report shows.question(object): The survey question the chart is built fromid(integer): Survey question IDnumber(string or null): Question number (e.g. Q14, REVENUE, QINDUSTRY)label(string or null): Question labeltitle(string): Question titletype(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 questionplans(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
- Values:
include_none(boolean): Whether respondents can pick None instead of a plan
get_chart_data
Section titled “get_chart_data”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 IDtitle(string or null, optional): Chart titlequestion(object): The survey question the chart is built fromid(integer): Survey question IDnumber(string or null): Question number (e.g. Q14, REVENUE, QINDUSTRY)label(string or null): Question labeltitle(string): Question titletype(string or null): Question type key
display_type(string or null, optional): Chart visualization typeformat(string or null, optional): Value format the chart renderstotal_respondents(integer or null, optional): Number of respondents the chart covers, shown as n= on the charttable(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 tablesposition(integer, optional): 0-based row positionfixed(boolean, optional): Whether the row is fixed in positioncells(array of object, optional)column_id(string, optional): Column ID the cell belongs tovalue(any, optional): Cell value — integer (counts), float rounded to 2 decimals (percentages, means, ratings), or string.
update_report
Section titled “update_report”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_reportstitle(string): New report titledescription(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.projectandprivatesuspend the public link if there is one, andpublicbrings it back with the same URL and password.- Values:
private,project,public
- Values:
Response
id(integer): Report IDupdated_at(string): Last update timestamp (ISO 8601)visibility(object): Who can view the reportlevel(string):privateis a draft only you can see,projectis everyone holding a permission on the survey,publicadds anyone holding its public link- Values:
private,project,public
- Values:
public_url(string, optional): The link that opens the report without signing in (only present whenlevelispublic)password_protected(boolean, optional): Whether the link asks for a password before opening the report (only present whenlevelispublic)
sort_report_blocks
Section titled “sort_report_blocks”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_reportsblocks(array of object, required): The blocks to move, each with the position it should end up atid(integer, required): Block ID, from get_reportposition(integer, required): New 1-based position on the reportsection_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 positionid(integer): Block IDtype(string or null): Block class name (e.g. ChartBlock, TextBlock, ImageBlock, SectionBlock)title(string or null): Block titleposition(integer or null): 1-based position on the reportsection_block_id(integer or null): Section block ID the block sits in, or null when it sits in none
create_report
Section titled “create_report”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_surveystitle(string, required): Report titledescription(string): What the report covers and who it is for, 450 characters at most.
Response
id(integer): The created report IDcreated_at(string): Creation timestamp (ISO 8601)
create_report_block
Section titled “create_report_block”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_reportskind(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 ofplanson a conjoint. A conjoint simulator’s shares follow the report’s filters.- Values:
chart,section,text,conjoint_simulator
- Values:
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 itsconjoint_utilitiesis 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’svalid_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
- Values:
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
- Values:
include_none(boolean): Only when kind is conjoint_simulator: whether respondents can pick None instead of a plan. Needshas_none_optionin 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 IDchart_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)
Responses
Section titled “Responses”list_data_layouts
Section titled “list_data_layouts”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_responses
Section titled “list_responses”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 matchingcolumns.
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.