Getting Started
Data Map
How the public API entities relate to each other and which fields to use as join keys.
Join Keys
| From | To | Join field | Notes |
|---|---|---|---|
| Study | Response | linkId | Path param in GET /api/public/v1/responses/{linkId}. Accepts the study's linkId or its UUID id. Single response returns linkId. |
| Study | Question | id | Path param in GET /api/public/v1/studies/{studyId}/questions. Accepts the study's UUID id or its linkId. |
| Question | Answer | discussionGuideQuestionId | Question.id = Answer.discussionGuideQuestionId |
| Question | TranscriptRow | discussionGuideQuestionId | Question.id = TranscriptRow.discussionGuideQuestionId |
| Answer | TranscriptRow | answerId | One answer can have multiple transcript rows (follow-ups where isFollowUp: true). |
| Question | Concept | concepts | Array on the Question object. conceptId on Answer/TranscriptRow links to Concept.id. Empty when the question has no concepts. |
| Question | Option | choices[].id | Answer.optionIds holds the id of each selected option. |
| Question (matrix) | Matrix cell | rowChoices[].id, columnChoices[].id | Answer.matrixSelections holds one rowId and columnId pair per selected cell. |
Entity Fields
Study
Returned by List Studies.
| Field | Type | Description |
|---|---|---|
id | uuid | Permanent study identifier. The path param for launch, and also accepted for questions and responses. |
linkId | string | Editable URL slug. Accepted by the questions and response endpoints. |
title | string | Study title |
responseCount | number | Completed response count |
createdAt | string | UTC timestamp |
creator | object | null | Study creator. Contains name and email, each of which may be null. |
folderPath | string[] | null | Study folder path as an array of strings. |
Response
Returned by Get Responses. Each response belongs to a study via linkId.
| Field | Type | Description |
|---|---|---|
id | uuid | Response identifier |
readableId | number | Order within the study |
progress | string | "complete", "screened_out", or "in_progress" |
responseDurationSeconds | number | Total duration |
qualityScore | number | string | Quality rating (optional) |
answers | object | Keyed 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. |
answersArray | Answer[] | Structured answers, joinable to questions and transcript |
urlParams | object | URL params passed into the study |
tags | string[] | Keywords (optional) |
tagline | string | null | One-line synthesis |
bulletSummary | string[] | Bullet-point summary |
shortTranscript | string | null | Whole conversation with assistant messages shortened to a few words |
shortAssistantMessages | string[] | Condensed assistant turns (optional) |
otherRemarks | string | Additional remarks (optional) |
personas | string | Persona classification (optional) |
createdAt | string | UTC timestamp |
updatedAt | string | UTC timestamp |
Answer
Nested inside Response.answersArray.
| Field | Type | Description |
|---|---|---|
answerId | uuid | Join key. Matches TranscriptRow.answerId. |
discussionGuideQuestionId | string | null | Join key. Matches Question.id. Null when the answer isn't tied to a guide question. |
conceptId | string | null | Links to Concept.id when the question involves concept testing |
question | string | Question text. Prefixed with its number when one is available (e.g. "Q1: What is your age?"). |
answer | string | Answer text |
optionIds | string[] | 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. |
matrixSelections | object[] | 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.
| Field | Type | Description |
|---|---|---|
moderator | string | Assistant/moderator text |
user | string | Participant text |
discussionGuideQuestionId | string | null | Join key. Matches Question.id. Null for non-question rows (e.g. intro). |
answerId | string | null | Join key. Matches Answer.answerId. Null for non-question rows (e.g. intro). |
conceptId | string | null | Links to Concept.id |
responseIndex | number | Zero-based row index |
isFollowUp | boolean | true when this row is a follow-up to the same question as the previous row |
audio | string | null | Signed URL (~1 hour validity) |
video | object | null | Camera recording. Contains streamUrl (HLS) and mp4Url. |
screenVideo | object | null | Screen recording (when the study captured the participant's screen). Contains streamUrl (HLS) and mp4Url. |
Question
Returned by Get Study Questions.
| Field | Type | Description |
|---|---|---|
id | string | Join key. Referenced as discussionGuideQuestionId on answers and transcript rows. |
text | string | Question text shown to participants |
type | string | open_ended, file_upload, multiple_choice, ranking, statement, matrix, max_diff, or gabor_granger. New types may be added. |
questionNumber | number | Display order |
isScreener | boolean | Whether this is a screener question |
choices | object[] | Options with a stable id and text. Used by multiple_choice, ranking, and max_diff. |
options | string[] | Deprecated. Option texts in the same order as choices. Use choices. |
isMultiSelect | boolean | Whether multiple selections are allowed (multiple_choice and matrix only) |
rowChoices, columnChoices | object[] | Matrix rows and columns, each with id and text (matrix only). Use the id values to read matrixSelections. |
rows, columns | string[] | Deprecated. Matrix row and column texts. Use rowChoices and columnChoices. |
display | string | Matrix only. grid or card_sort. |
metric, itemsPerScreen | string, number | MaxDiff metric and items shown per screen (max_diff only) |
task | object | Open-ended task settings. Present only for task questions. |
pricePoints, currencyCode, acceptIntentThreshold, startPriceRange | number[], string, number, string | Price ladder and settings (gabor_granger only) |
concepts | Concept[] | Concept definitions attached to this question |
Concept
Nested inside Question.concepts.
| Field | Type | Description |
|---|---|---|
id | string | Referenced by conceptId on Answer and TranscriptRow |
title | string | Concept title |
description | string | Concept description |
media | Media[] | Attached images/videos (type, name, url, and error when the file can't be loaded) |
embedUrl | string | null | External embed (e.g. Figma link) |
embedError | string | Present only when the embed can't be loaded. The value is media_unavailable. |
Traversal Examples
Get all answers for a study, grouped by question
GET /api/public/v1/studiesto find the study'sidandlinkIdGET /api/public/v1/studies/{studyId}/questionsto get all questions (using theid)GET /api/public/v1/responses/{linkId}to get all responses- Join each
answersArray[]item to its question usingdiscussionGuideQuestionId=Question.id
Match transcript audio/video to specific questions
GET /api/public/v1/responses/{linkId}/{responseId}to get the full transcriptGET /api/public/v1/studies/{studyId}/questionsto get question definitions- Each transcript row's
discussionGuideQuestionIdtells you which question it belongs to - Use
audio,video, andscreenVideofields on the transcript row to access the media for that exchange
Group transcript rows by answer (including follow-ups)
GET /api/public/v1/responses/{linkId}/{responseId}to get the full transcript- Group transcript rows by
answerId. Rows sharing the sameanswerIdbelong to the same answer. Follow-ups are marked byisFollowUp: true. - Cross-reference with
answersArrayfrom the list endpoint using the sameanswerIdto get the extracted answer text
Read the selected options for a multiple choice question
GET /api/public/v1/studies/{studyId}/questionsto getchoicesfor the questionGET /api/public/v1/responses/{linkId}to get the response'sanswersArray- Find the answer whose
discussionGuideQuestionIdmatchesQuestion.id - Map each value in
optionIdsto thetextof thechoicesentry with the sameid