Listen Labs

App · 10 actions

Create research studies and retrieve interviews, transcripts, and summaries.

Actions

ActionWhat it does
Create a draft studyCreate a draft study.
Get an interview responseGet an interview response.
Get response deletion statusGet response deletion status.
Get study questionsGet study questions.
Launch a studyLaunch a study.
List studiesList studies.
List study responsesList study responses.
List walletsList wallets.
Request response deletionRequest response deletion.
Search responses by URL parameterSearch responses by URL parameter.

Create a draft study

Create a draft study.

Inputs

TitletitletextRequired
Title.
External titleexternal_titletext
External title.
Backgroundbackgroundtext
Background.
Study goalstudy_goaltext
Study goal.
Configconfigobject
Config.
Welcome messagewelcome_messageobject
Welcome message.
Closing messageclosing_messagetext
Closing message.
Study guidestudy_guidelistRequired
Study guide.

Outputs

dataobject
The response from Listen Labs.
Example output
{
  "data": {
    "id": "example",
    "linkId": "example",
    "status": "draft"
  }
}

Get an interview response

Get an interview response.

Inputs

Linklink_idtextRequired
The study's editable link ID (as used in the response URL) or the study UUID.
Response IDresponse_idtextRequired
Response UUID or positive readable numeric ID.

Outputs

dataobject
The response from Listen Labs.
Example output
{
  "data": {
    "bulletSummary": [
      "example"
    ],
    "id": "example",
    "linkId": "example",
    "readableId": 1,
    "tagline": "example",
    "transcript": [
      {
        "answerId": "example",
        "audio": "example",
        "conceptId": "example",
        "discussionGuideQuestionId": "example",
        "isFollowUp": true,
        "moderator": "example",
        "responseIndex": 1,
        "screenVideo": {
          "mp4Url": "example",
          "streamUrl": "example"
        },
        "user": "example",
        "video": {
          "mp4Url": "example",
          "streamUrl": "example"
        }
      }
    ],
    "urlParams": {}
  }
}

Get response deletion status

Get response deletion status.

Inputs

Deletion IDdeletion_idtextRequired
Deletion id.

Outputs

dataobject
The response from Listen Labs.
Example output
{
  "data": {
    "completedAt": "example",
    "deletionId": "example",
    "requestedAt": "example",
    "responseId": "example",
    "status": "queued"
  }
}

Get study questions

Get study questions.

Inputs

Studystudy_idtextRequired
Study UUID or the study's link ID.

Outputs

dataobject
The response from Listen Labs.
Example output
{
  "data": {
    "questions": [
      {
        "columns": [
          "example"
        ],
        "concepts": [
          {}
        ],
        "id": "example",
        "isMultiSelect": true,
        "isScreener": true,
        "itemsPerScreen": 1,
        "metric": "example",
        "options": [
          "example"
        ],
        "questionNumber": 1,
        "rows": [
          "example"
        ],
        "text": "example",
        "type": "max_diff"
      }
    ]
  }
}

Launch a study

Launch a study.

Inputs

Studystudy_idtextRequired
Study id.
Walletwallet_idtext
Wallet to bill this study from; must be granted to the API key's workspace (see GET /api/public/v1/wallets). Omit to auto-select the workspace's wallet when it has exactly one.

Outputs

dataobject
The response from Listen Labs.
Example output
{
  "data": {
    "id": "example",
    "linkId": "example",
    "selfRecruitLink": "example",
    "status": "live",
    "wallet": {
      "name": "example",
      "projectCreditBalance": {
        "balance": 1,
        "usage": 1
      },
      "recruitmentCreditBalance": {
        "balance": 1,
        "usage": 1
      },
      "walletId": "example"
    }
  }
}

List studies

List studies.

Inputs

None.

Outputs

datalist
The response from Listen Labs.
Example output
{
  "data": [
    {
      "createdAt": "example",
      "creator": {
        "email": "example",
        "name": "example"
      },
      "folderPath": [
        "example"
      ],
      "id": "example",
      "linkId": "example",
      "responseCount": 1,
      "title": "example"
    }
  ]
}

List study responses

List study responses.

Inputs

Linklink_idtextRequired
The study's editable link ID (as used in the response URL) or the study UUID.
Pagepagenumber
Page.At least 0.
Per pageper_pagenumber
Per page.At least 1.
Updated sinceupdated_sincedate and time
Only responses updated at or after this timestamp.
Include in progressinclude_in_progresstrue/false
Include in progress.

Outputs

datalist
The response from Listen Labs.
Example output
{
  "data": [
    {
      "answers": {},
      "answersArray": [
        {
          "answer": "example",
          "answerId": "example",
          "conceptId": "example",
          "discussionGuideQuestionId": "example",
          "question": "example"
        }
      ],
      "bulletSummary": [
        "example"
      ],
      "createdAt": "example",
      "id": "example",
      "otherRemarks": "example",
      "personas": "example",
      "progress": "complete",
      "qualityScore": "example",
      "readableId": 1,
      "responseDurationSeconds": 1,
      "shortAssistantMessages": [
        "example"
      ],
      "shortTranscript": "example",
      "tagline": "example",
      "tags": [
        "example"
      ],
      "updatedAt": "example",
      "urlParams": {}
    }
  ]
}

List wallets

List wallets.

Inputs

None.

Outputs

dataobject
The response from Listen Labs.
Example output
{
  "data": {
    "wallets": [
      {
        "name": "example",
        "projectCreditBalance": {
          "balance": 1,
          "usage": 1
        },
        "recruitmentCreditBalance": {
          "balance": 1,
          "usage": 1
        },
        "walletId": "example"
      }
    ]
  }
}

Request response deletion

Request response deletion.

Inputs

Studystudy_idtextRequired
Study id.
Response IDresponse_idtextRequired
Response id.

Outputs

dataobject
The response from Listen Labs.
Example output
{
  "data": {
    "deletionId": "example",
    "responseId": "example",
    "status": "queued"
  }
}

Search responses by URL parameter

Search responses by URL parameter.

Inputs

ParameterparametertextRequired
Parameter.
ValuevaluetextRequired
Value.
Cursorcursortext
Use nextCursor from the previous page to continue. Keep the other search parameters unchanged. Invalid cursors return 400.
Limitlimitnumber
Limit.From 1 to 1000.
Include hiddeninclude_hiddentrue/false
Include hidden.

Outputs

dataobject
The response from Listen Labs.
Example output
{
  "data": {
    "nextCursor": "example",
    "results": [
      {
        "linkId": "example",
        "readableResponseId": 1,
        "responseId": "example",
        "responseUrl": "example",
        "studyId": "example",
        "studyUrl": "example"
      }
    ]
  }
}

On this page