Studies

A study defines the scope, tasks, targeting criteria, and compensation for a round of user testing. Once created, testers are matched and assigned. Studies map to internal jobs in the API path.

Endpoints

POST /api/jobs JWT

Create a new study

Request body

{
  "title": "Checkout Redesign - Usability Test",
  "description": "Evaluate the redesigned checkout flow for clarity and completion rate.",
  "prototypeUrl": "https://www.figma.com/proto/abc123/checkout-v2",
  "prototypeType": "figma",
  "tasks": [
    {
      "title": "Add a product to your cart",
      "description": "Start from the homepage and add any item to your cart.",
      "successCriteria": "Cart count increments to 1.",
      "order": 1
    },
    {
      "title": "Complete the checkout",
      "description": "Proceed through checkout and reach the order confirmation screen.",
      "successCriteria": "Order confirmation page is displayed.",
      "order": 2
    }
  ],
  "targeting": {
    "countries": ["US", "GB", "CA"],
    "ageRange": { "min": 18, "max": 55 },
    "devices": ["desktop", "mobile"],
    "languages": ["en"],
    "testerCount": 10
  },
  "abTest": {
    "enabled": true,
    "variants": [
      { "label": "A", "description": "Current checkout flow" },
      { "label": "B", "description": "Redesigned checkout flow" }
    ],
    "splitRatio": { "A": 0.5, "B": 0.5 }
  },
  "compensation": {
    "currency": "USD",
    "amount": 15.00,
    "type": "flat"
  },
  "settings": {
    "requireThinkAloud": true,
    "recordScreen": true,
    "recordFacial": true,
    "recordVoice": true,
    "maxDurationMinutes": 45,
    "reminderAfterHours": 24
  }
}

Field reference

Field	Type	Required	Description
title	string	Yes	Study title shown to testers
description	string	Yes	Internal description of the study objectives
prototypeUrl	string	Yes	URL to the prototype or live product
prototypeType	string	Yes	One of: figma, invision, marvel, url
tasks	array	Yes	Ordered list of tasks the tester must complete
targeting	object	Yes	Tester matching criteria
targeting.countries	array of strings	Yes	ISO 3166-1 alpha-2 country codes
targeting.ageRange	object	No	{ min, max } age range
targeting.devices	array of strings	Yes	One or more of: desktop, mobile, tablet
targeting.languages	array of strings	No	BCP 47 language codes. Defaults to ["en"].
targeting.testerCount	integer	Yes	Number of testers to recruit
abTest	object	No	A/B test configuration. Omit for single-variant studies.
abTest.enabled	boolean	Yes	Whether A/B testing is active
abTest.variants	array	Yes	Variant definitions with label and description
abTest.splitRatio	object	No	Proportion of testers per variant. Must sum to 1.0. Defaults to equal split.
compensation.currency	string	Yes	ISO 4217 currency code
compensation.amount	number	Yes	Payment per completed session
compensation.type	string	Yes	flat (only supported type currently)
settings.requireThinkAloud	boolean	No	Whether testers must narrate while testing
settings.recordScreen	boolean	No	Enable screen recording
settings.recordFacial	boolean	No	Enable facial analysis
settings.recordVoice	boolean	No	Enable voice transcription and analysis
settings.maxDurationMinutes	integer	No	Session time limit. Defaults to 60.
settings.reminderAfterHours	integer	No	Hours before sending an inactivity reminder

Task schema

Field	Type	Required	Description
title	string	Yes	Short task title shown to the tester
description	string	Yes	Full task instructions
successCriteria	string	No	Observable condition for task completion
order	integer	Yes	Presentation order (1-indexed)

Response

{
  "success": true,
  "data": {
    "jobId": "job_abc123",
    "title": "Checkout Redesign - Usability Test",
    "status": "draft",
    "testerCount": 10,
    "abTestEnabled": true,
    "variants": ["A", "B"],
    "estimatedLaunchDate": "2026-03-17T00:00:00Z",
    "createdAt": "2026-03-16T10:00:00Z"
  },
  "error": null,
  "metadata": null
}

Study status lifecycle

Status	Description
draft	Created but not yet active. Testers cannot be assigned.
active	Open for tester assignment and sessions.
paused	Temporarily closed. Existing sessions continue.
completed	All target sessions collected.
archived	Closed and removed from active dashboards.

After creation, a study is in draft status. Activate it via the dashboard or the study management API.