OriginalVoices

Appearance

Studies ​

Studies are research you've run on the platform: AI-moderated interviews with real people, or surveys answered by Twins. Ask a study's participants with target.studyId on Ask questions, and each participant's Twin answers with their whole study conversation in context.

List studies ​

GET/v1/studies

Lists your organisation's studies that have a finished run.

Returns ​

An array of studies.

iduuid

Pass it as target.studyId when you ask.

titlestring

The study's name.

kind'HUMAN_INTERVIEW' | 'TWIN_SURVEY'

HUMAN_INTERVIEW: real people interviewed one-to-one by an AI moderator. TWIN_SURVEY: a questionnaire answered by Digital Twins.

descriptionstring | null

The study's description, if it has one.

participantsinteger

How many people completed the latest run.

questionsarray

The study's questions, each with order, type and prompt.

bash
curl https://api.originalvoices.ai/v1/studies \
  -H "Authorization: Bearer $ORIGINALVOICES_API_KEY"
ts
const res = await fetch("https://api.originalvoices.ai/v1/studies", {
  headers: { Authorization: `Bearer ${process.env.ORIGINALVOICES_API_KEY}` },
});
const { data: studies } = await res.json();
python
res = requests.get(
    "https://api.originalvoices.ai/v1/studies",
    headers={"Authorization": f"Bearer {os.environ['ORIGINALVOICES_API_KEY']}"},
)
json
{
  "requestId": "51e8…",
  "data": [
    {
      "id": "d2b9c7f0-…",
      "title": "Coffee subscription interviews",
      "kind": "HUMAN_INTERVIEW",
      "description": "Why regulars would or wouldn't pay monthly",
      "participants": 42,
      "questions": [
        { "order": 1, "type": "open", "prompt": "How often do you buy coffee out?" }
      ]
    }
  ],
  "error": null
}

List participants ​

GET/v1/studies/{studyId}/participants

Lists the people who completed a study's latest run.

Use a participant's twinId to ask them specifically, with twinIds on Ask questions.

Returns ​

studystring

The study's id.

participantsarray

Each with a twinId and demographics (age, gender, country). demographics can be null.

bash
curl https://api.originalvoices.ai/v1/studies/d2b9c7f0-…/participants \
  -H "Authorization: Bearer $ORIGINALVOICES_API_KEY"
ts
const res = await fetch(
  `https://api.originalvoices.ai/v1/studies/${studyId}/participants`,
  { headers: { Authorization: `Bearer ${process.env.ORIGINALVOICES_API_KEY}` } },
);
const { data } = await res.json();
python
res = requests.get(
    f"https://api.originalvoices.ai/v1/studies/{study_id}/participants",
    headers={"Authorization": f"Bearer {os.environ['ORIGINALVOICES_API_KEY']}"},
)
json
{
  "requestId": "8c3f…",
  "data": {
    "study": "d2b9c7f0-…",
    "participants": [
      {
        "twinId": "a91e44d2-…",
        "demographics": { "age": 33, "gender": "Female", "country": "GB" }
      }
    ]
  },
  "error": null
}