Data Map - Listen Labs

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/studies to find the study’s id and linkId
GET /api/public/v1/studies/{studyId}/questions to get all questions (using the id)
GET /api/public/v1/responses/{linkId} to get all responses
Join each answersArray[] item to its question using discussionGuideQuestionId = Question.id

Match transcript audio/video to specific questions

GET /api/public/v1/responses/{linkId}/{responseId} to get the full transcript
GET /api/public/v1/studies/{studyId}/questions to get question definitions
Each transcript row’s discussionGuideQuestionId tells you which question it belongs to
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)

GET /api/public/v1/responses/{linkId}/{responseId} to get the full transcript
Group transcript rows by answerId. Rows sharing the same answerId belong to the same answer. Follow-ups are marked by isFollowUp: true.
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

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