Listen LabsDocs

    Getting Started

    Data Map

    How the public API entities relate to each other and which fields to use as join keys.

    Join Keys

    FromToJoin fieldNotes
    StudyResponselinkIdPath param in GET /api/public/v1/responses/{linkId}. Accepts the study's linkId or its UUID id. Single response returns linkId.
    StudyQuestionidPath param in GET /api/public/v1/studies/{studyId}/questions. Accepts the study's UUID id or its linkId.
    QuestionAnswerdiscussionGuideQuestionIdQuestion.id = Answer.discussionGuideQuestionId
    QuestionTranscriptRowdiscussionGuideQuestionIdQuestion.id = TranscriptRow.discussionGuideQuestionId
    AnswerTranscriptRowanswerIdOne answer can have multiple transcript rows (follow-ups where isFollowUp: true).
    QuestionConceptconceptsArray on the Question object. conceptId on Answer/TranscriptRow links to Concept.id. Empty when the question has no concepts.
    QuestionOptionchoices[].idAnswer.optionIds holds the id of each selected option.
    Question (matrix)Matrix cellrowChoices[].id, columnChoices[].idAnswer.matrixSelections holds one rowId and columnId pair per selected cell.

    Entity Fields

    Study

    Returned by List Studies.

    FieldTypeDescription
    iduuidPermanent study identifier. The path param for launch, and also accepted for questions and responses.
    linkIdstringEditable URL slug. Accepted by the questions and response endpoints.
    titlestringStudy title
    responseCountnumberCompleted response count
    createdAtstringUTC timestamp
    creatorobject | nullStudy creator. Contains name and email, each of which may be null.
    folderPathstring[] | nullStudy folder path as an array of strings.

    Response

    Returned by Get Responses. Each response belongs to a study via linkId.

    FieldTypeDescription
    iduuidResponse identifier
    readableIdnumberOrder within the study
    progressstring"complete", "screened_out", or "in_progress"
    responseDurationSecondsnumberTotal duration
    qualityScorenumber | stringQuality rating (optional)
    answersobjectKeyed by question title, with no question-number prefix (e.g. "What is your age?"). Use answersArray to join answers to questions. Summaries are in tagline and bulletSummary.
    answersArrayAnswer[]Structured answers, joinable to questions and transcript
    urlParamsobjectURL params passed into the study
    tagsstring[]Keywords (optional)
    taglinestring | nullOne-line synthesis
    bulletSummarystring[]Bullet-point summary
    shortTranscriptstring | nullWhole conversation with assistant messages shortened to a few words
    shortAssistantMessagesstring[]Condensed assistant turns (optional)
    otherRemarksstringAdditional remarks (optional)
    personasstringPersona classification (optional)
    createdAtstringUTC timestamp
    updatedAtstringUTC timestamp

    Answer

    Nested inside Response.answersArray.

    FieldTypeDescription
    answerIduuidJoin key. Matches TranscriptRow.answerId.
    discussionGuideQuestionIdstring | nullJoin key. Matches Question.id. Null when the answer isn't tied to a guide question.
    conceptIdstring | nullLinks to Concept.id when the question involves concept testing
    questionstringQuestion text. Prefixed with its number when one is available (e.g. "Q1: What is your age?").
    answerstringAnswer text
    optionIdsstring[]Join key to Question.choices[].id. The option ids the participant selected, in the order given. For ranking questions, the order is the rank order. Empty for open-ended answers, for a typed "other" answer, and for matrix questions. Also empty when the stored answer has no option selections.
    matrixSelectionsobject[]Matrix answers only. One entry per selected row and column pair, with rowId and columnId. Join rowId to Question.rowChoices[].id and columnId to Question.columnChoices[].id. Multi-select matrix rows can have several entries. Empty for every other question type.

    TranscriptRow

    Returned by Get Single Response inside the transcript array.

    FieldTypeDescription
    moderatorstringAssistant/moderator text
    userstringParticipant text
    discussionGuideQuestionIdstring | nullJoin key. Matches Question.id. Null for non-question rows (e.g. intro).
    answerIdstring | nullJoin key. Matches Answer.answerId. Null for non-question rows (e.g. intro).
    conceptIdstring | nullLinks to Concept.id
    responseIndexnumberZero-based row index
    isFollowUpbooleantrue when this row is a follow-up to the same question as the previous row
    audiostring | nullSigned URL (~1 hour validity)
    videoobject | nullCamera recording. Contains streamUrl (HLS) and mp4Url.
    screenVideoobject | nullScreen recording (when the study captured the participant's screen). Contains streamUrl (HLS) and mp4Url.

    Question

    Returned by Get Study Questions.

    FieldTypeDescription
    idstringJoin key. Referenced as discussionGuideQuestionId on answers and transcript rows.
    textstringQuestion text shown to participants
    typestringopen_ended, file_upload, multiple_choice, ranking, statement, matrix, max_diff, or gabor_granger. New types may be added.
    questionNumbernumberDisplay order
    isScreenerbooleanWhether this is a screener question
    choicesobject[]Options with a stable id and text. Used by multiple_choice, ranking, and max_diff.
    optionsstring[]Deprecated. Option texts in the same order as choices. Use choices.
    isMultiSelectbooleanWhether multiple selections are allowed (multiple_choice and matrix only)
    rowChoices, columnChoicesobject[]Matrix rows and columns, each with id and text (matrix only). Use the id values to read matrixSelections.
    rows, columnsstring[]Deprecated. Matrix row and column texts. Use rowChoices and columnChoices.
    displaystringMatrix only. grid or card_sort.
    metric, itemsPerScreenstring, numberMaxDiff metric and items shown per screen (max_diff only)
    taskobjectOpen-ended task settings. Present only for task questions.
    pricePoints, currencyCode, acceptIntentThreshold, startPriceRangenumber[], string, number, stringPrice ladder and settings (gabor_granger only)
    conceptsConcept[]Concept definitions attached to this question

    Concept

    Nested inside Question.concepts.

    FieldTypeDescription
    idstringReferenced by conceptId on Answer and TranscriptRow
    titlestringConcept title
    descriptionstringConcept description
    mediaMedia[]Attached images/videos (type, name, url, and error when the file can't be loaded)
    embedUrlstring | nullExternal embed (e.g. Figma link)
    embedErrorstringPresent only when the embed can't be loaded. The value is media_unavailable.

    Traversal Examples

    Get all answers for a study, grouped by question

    1. GET /api/public/v1/studies to find the study's id and linkId
    2. GET /api/public/v1/studies/{studyId}/questions to get all questions (using the id)
    3. GET /api/public/v1/responses/{linkId} to get all responses
    4. Join each answersArray[] item to its question using discussionGuideQuestionId = Question.id

    Match transcript audio/video to specific questions

    1. GET /api/public/v1/responses/{linkId}/{responseId} to get the full transcript
    2. GET /api/public/v1/studies/{studyId}/questions to get question definitions
    3. Each transcript row's discussionGuideQuestionId tells you which question it belongs to
    4. Use audio, video, and screenVideo fields on the transcript row to access the media for that exchange

    Group transcript rows by answer (including follow-ups)

    1. GET /api/public/v1/responses/{linkId}/{responseId} to get the full transcript
    2. Group transcript rows by answerId. Rows sharing the same answerId belong to the same answer. Follow-ups are marked by isFollowUp: true.
    3. Cross-reference with answersArray from the list endpoint using the same answerId to get the extracted answer text

    Read the selected options for a multiple choice question

    1. GET /api/public/v1/studies/{studyId}/questions to get choices for the question
    2. GET /api/public/v1/responses/{linkId} to get the response's answersArray
    3. Find the answer whose discussionGuideQuestionId matches Question.id
    4. Map each value in optionIds to the text of the choices entry with the same id