Ask

Ask Digital Twins up to 15 questions in one call. For concepts and tips, see Asking questions.

Ask questions

POST/v1/ask

Ask a described audience, a saved audience or a study's participants. Each participant's Twin answers every question in order, in one conversation, so a later question can follow up on an earlier pick.

Calls take tens of seconds, so use a timeout of a few minutes. You pay per answer: participants × questions.

Body

targetobjectrequired

Who answers. Set exactly one of audience, audienceId or studyId.

audiencestring

An audience in your own words, e.g. "UK, 18-30, fitness enthusiasts". Up to 2,048 characters.

audienceIdstring

A saved audience id from List audiences.

studyIduuid

A study id from List studies. Its participants answer, with their whole study conversation in context.

questionsarrayrequired

1–15 questions, asked in order. Open and choice questions can be mixed.

type'open' | 'choice'required

open for a free-text answer, choice to pick from options.

questionstringrequired

The question, up to 2,048 characters. Paste any copy or concept you're testing right into it.

choicesstring[]

Choice only, and required for it: 2–20 distinct options, each up to 255 characters.

isMultipleChoiceboolean

Choice only. Lets participants pick several options. Defaults to false.

idstring

Your key for this question in the answers. Letters, numbers, _ and -. Defaults to q1, q2, …

sampleSizeinteger

How many participants answer: 1–200, and at most 100 for audiences. Defaults: 25 for a described audience, everyone (up to 100) for a saved audience, everyone for an interview study and 25 for a twin-survey study.

filterstring

Study targets only. Free text matched against each participant's profile and what they said in the study, e.g. "said price was the main barrier".

twinIdsstring[]

Study targets only. Ask specific participants, by twinId from List participants. Combines with filter.

Returns

participantsarray

One entry per Twin, with twinId, demographics and answers keyed by question id. demographics has age, gender and country, and can be null; age can also be null. A missing answer key means that participant didn't answer.

answerstring

Open questions: the answer in the Twin's own words.

selectionsstring[]

Choice questions: the options picked, with a reason.

confidence'low' | 'medium' | 'high'

How much the answer rests on the Twin's own data about the topic, rather than demographics alone.

questionsarray

Your questions with answered counts. Choice questions also carry results: each option's count and percentage (its average probability across participants, 0–100).

askedinteger

How many participants answered. total is the number of participants in the study or audience, and matched is how many matched your filter and twinIds.

curl

curl https://api.originalvoices.ai/v1/ask \
  -H "Authorization: Bearer $ORIGINALVOICES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": { "audience": "UK, 18-30, fitness enthusiasts" },
    "questions": [
      {
        "id": "pick",
        "type": "choice",
        "question": "Which matters most when buying running shoes?",
        "choices": ["Price", "Comfort", "Style", "Durability"]
      },
      { "id": "why", "type": "open", "question": "Why did you pick that?" }
    ]
  }'

TypeScript

const res = await fetch("https://api.originalvoices.ai/v1/ask", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ORIGINALVOICES_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    target: { audience: "UK, 18-30, fitness enthusiasts" },
    questions: [
      {
        id: "pick",
        type: "choice",
        question: "Which matters most when buying running shoes?",
        choices: ["Price", "Comfort", "Style", "Durability"],
      },
      { id: "why", type: "open", question: "Why did you pick that?" },
    ],
  }),
});
const { data } = await res.json();

Python

import os, requests

res = requests.post(
    "https://api.originalvoices.ai/v1/ask",
    headers={"Authorization": f"Bearer {os.environ['ORIGINALVOICES_API_KEY']}"},
    json={
        "target": {"audience": "UK, 18-30, fitness enthusiasts"},
        "questions": [
            {
                "id": "pick",
                "type": "choice",
                "question": "Which matters most when buying running shoes?",
                "choices": ["Price", "Comfort", "Style", "Durability"],
            },
            {"id": "why", "type": "open", "question": "Why did you pick that?"},
        ],
    },
    timeout=300,
)
data = res.json()["data"]

Response

{
  "requestId": "4f1c…",
  "data": {
    "source": { "type": "audience", "id": null, "description": "UK, 18-30, fitness enthusiasts" },
    "total": 30,
    "matched": 30,
    "asked": 25,
    "questions": [
      {
        "id": "pick",
        "type": "choice",
        "question": "Which matters most when buying running shoes?",
        "choices": ["Price", "Comfort", "Style", "Durability"],
        "isMultipleChoice": false,
        "answered": 25,
        "results": [
          { "choice": "Price", "count": 7, "percentage": 27 },
          { "choice": "Comfort", "count": 12, "percentage": 41 },
          { "choice": "Style", "count": 2, "percentage": 12 },
          { "choice": "Durability", "count": 4, "percentage": 20 }
        ]
      },
      { "id": "why", "type": "open", "question": "Why did you pick that?", "answered": 25 }
    ],
    "participants": [
      {
        "twinId": "b7e2…",
        "demographics": { "age": 27, "gender": "Female", "country": "GB" },
        "answers": {
          "pick": {
            "selections": ["Comfort"],
            "confidence": "high",
            "reason": "Runs most mornings and has had shin pain from cheap pairs."
          },
          "why": {
            "answer": "I run most mornings, so a bad pair hurts fast.",
            "confidence": "high"
          }
        }
      }
    ]
  },
  "error": null
}