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

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

Surveys

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

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

Questionnaires

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 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. Omitted when unset.
  • label (string, optional): Element label. Omitted when unset.
  • status (string, optional): Review status. Omitted when unset.
  • display_logic (string, optional): Display logic condition. Omitted when unset.
  • display_logic_expression (string, optional): Plain-language reading of the structured display-logic condition (e.g. “QAGE > 18”). Only present when the native-expression feature is enabled for this survey; omitted when the element has none.
  • instructions_for_respondent (string, optional): Instructions shown to respondents. 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.
  • 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. Omitted when unset.
    • position (integer): Answer position
    • 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): Display logic condition for this answer. Omitted when unset.
    • condition_expression (string, optional): Plain-language reading of the structured show/hide condition for this answer (e.g. “QAGE > 18”). Only present when the native-expression feature is enabled for this survey; omitted when the answer has none.
    • 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)

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

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)

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 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, autosum, date_picker, dropdown_menu, essay, 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
  • Values: eligibility, attention, coherence
• 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 (string): Plain-language condition deciding whether the element is shown. Only applies to QuestionElement, MessageElement, TerminationElement and BlockElement.
• instructions_for_respondent (string): Instructions shown to respondents. Only applies to QuestionElement.
• row_order (string): Order the row answers are presented in. Only applies to QuestionElement.
  • Values: alphabetical, ordered, randomized
• column_order (string): Order the column answers are presented in. Only applies to QuestionElement.
  • Values: alphabetical, ordered, randomized
• 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)
  • 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
  • condition (string): Plain-language condition deciding whether this answer is shown
  • attributes (array of string): Answer attributes: NE=non-eligible (screens the respondent out), E=exclusive (clears the other selections), F=fixed (stays put when the answers are randomized), OE=open-end (adds a free-text box)
    • Values: NE, E, F, OE

Response

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

update_questionnaire_element

Update questionnaire element Writes

Edit a questionnaire element: its text, answers, display logic, instructions and nesting. Only the attributes you send change; omitted ones are left alone, and omitting answers leaves the answer list untouched. 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, autosum, date_picker, dropdown_menu, essay, 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
    • Values: eligibility, attention, coherence
  • 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 (string): Plain-language condition deciding whether the element is shown. Only applies to QuestionElement, MessageElement, TerminationElement and BlockElement.
  • instructions_for_respondent (string): Instructions shown to respondents. Only applies to QuestionElement.
  • row_order (string): Order the row answers are presented in. Only applies to QuestionElement.
    • Values: alphabetical, ordered, randomized
  • column_order (string): Order the column answers are presented in. Only applies to QuestionElement.
    • Values: alphabetical, ordered, randomized
  • 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. 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)
    • 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
    • condition (string): Plain-language condition deciding whether this answer is shown
    • attributes (array of string): Answer attributes: NE=non-eligible (screens the respondent out), E=exclusive (clears the other selections), F=fixed (stays put when the answers are randomized), OE=open-end (adds a free-text box)
      • Values: NE, E, F, OE

Response

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

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 to the top level. 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 to the top level.

Response

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

restore_questionnaire_element

Restore questionnaire element Writes

Bring a deleted element back into a questionnaire, in the slot it held while deleted. A loop or block also brings back the elements deleted with it, and a question its answers, leaving behind anything deleted separately beforehand.

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)

Questionnaire comments

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

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

Questions

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 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, count_percentage, rating
• 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.

Reports

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

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.

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

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

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

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 creates a public link anyone can open without signing in. Moving a report in or out of private needs its author; creating or disabling the public link 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 disable the public link if there is one.
  • 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)

sort_report_blocks

Reorder report blocks Writes

Reorder a report’s blocks. 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

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

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_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)

create_report_block

Add report block Writes

Create one block on a report: a chart of a survey question, a section heading that groups the blocks below it, or a paragraph of written commentary. kind picks which, and decides what else is required: question_id for a chart, title for a section, body for text. 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 is a heading, text is written commentary.
  • Values: chart, section, text
• question_id (integer): The survey question to plot (required when kind is chart). Must belong to the report’s survey. Get it from list_questions.
• title (string): The heading (required when kind is section). 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.
• position (integer): 1-based position on the report. Defaults to the end.

Response

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

Responses

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

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.