Distributions

Create a distribution

Create a new distribution for a study. A distribution defines how participants access the study — via a shareable link, a panel provider, embedded widget, or other method.

post/api/v1/distributions

Request

Base URL
https://app.voicepanel.com
URL
https://app.voicepanel.com/api/v1/distributions
Auth
HTTP bearer

Request body

study_idstring required

ID of the study this distribution belongs to

namestring nullable

Name of the distribution

How the study is distributed to participants

distribution_provider'respondent' | 'user_interviews' | 'prolific' | 'terac' nullable

Third-party panel provider

configobject

Provider-specific configuration

incentiveobject nullable

Incentive configuration for link distributions

quota_limitnumber nullable

Maximum number of responses

quota_frequency'lifetime' | 'monthly' | 'weekly' | 'daily'

How often the quota resets

default_response_languagestring nullable

Default language for responses

collect_emailboolean

Whether to collect participant email

screen_emailboolean

Whether to screen participants against an email list

email_list_idstring nullable

Email list used to screen or invite participants

automatic_invitesboolean

Whether participants are invited automatically

keystring nullable

Snippet key used to trigger an intercept distribution

traffic_thresholdnumber nullable

Share of eligible traffic shown the study, out of 1,000,000

complete_redirect_urlstring nullable

URL to redirect to after completion

screen_out_redirect_urlstring nullable

URL to redirect screened-out participants

quota_full_redirect_urlstring nullable

URL to redirect when quota is full

quality_terminate_redirect_urlstring nullable

URL to redirect participants terminated for quality

descriptionstring nullable

Description of the distribution

is_archivedboolean

Whether the distribution is archived. Archiving hides it in the dashboard and does not change its status.

Example request

{
  "study_id": "stdy_Qm3vR8tLp2XnWz",
  "name": "March newsletter link",
  "type": "link",
  "config": {},
  "incentive": {
    "type": "gift_card",
    "amount": 10,
    "title": "$10 gift card",
    "description": "Sent by email after you complete the interview."
  },
  "quota_limit": 100,
  "quota_frequency": "lifetime",
  "screener_questions": [
    {
      "text": "Have you ordered grocery delivery in the last 3 months?",
      "type": "radio",
      "isRequired": true,
      "options": [
        {
          "text": "Yes",
          "qualification": "qualify"
        },
        {
          "text": "No",
          "qualification": "disqualify"
        }
      ]
    }
  ],
  "default_response_language": "en",
  "automatic_invites": true,
  "complete_redirect_url": "https://example.com/thanks?rid={{response_id}}",
  "description": "Shared with newsletter subscribers in March."
}

Response

Created

idstring required

Distribution ID

urlstring nullable required

Public link participants open to take the study. Set for link distributions only; null for every other type.

study_idstring required

ID of the study this distribution belongs to

namestring nullable required

Name of the distribution

descriptionstring nullable required

Description of the distribution

How the study is distributed to participants

status'draft' | 'published' | 'paused' | 'completed' | 'in_review' required

Current status of the distribution

distribution_provider'respondent' | 'user_interviews' | 'prolific' | 'terac' nullable required

Third-party panel provider

distribution_provider_idstring nullable required

External provider project ID

configobject required

Provider-specific configuration

incentiveobject nullable required

Incentive configuration for link distributions

quota_limitnumber nullable required

Maximum number of responses

quota_frequency'lifetime' | 'monthly' | 'weekly' | 'daily' required

How often the quota resets

quota_usageinteger required

Responses counted against the current quota

default_response_languagestring nullable required

Default language for responses

collect_emailboolean required

Whether to collect participant email

screen_emailboolean required

Whether to screen participants against an email list

email_list_idstring nullable required

Email list used to screen or invite participants

automatic_invitesboolean required

Whether participants are invited automatically

keystring nullable required

Snippet key used to trigger an intercept distribution

traffic_thresholdnumber nullable required

Share of eligible traffic shown the study, out of 1,000,000

complete_redirect_urlstring nullable required

URL to redirect to after completion

screen_out_redirect_urlstring nullable required

URL to redirect screened-out participants

quota_full_redirect_urlstring nullable required

URL to redirect when quota is full

quality_terminate_redirect_urlstring nullable required

URL to redirect participants terminated for quality

is_archivedboolean required

Whether the distribution is archived

seq_numinteger nullable required

Sequence number within the study

published_atstring date-time nullable required

When the distribution was published

last_completed_atstring date-time nullable required

When the latest response completed

created_bystring nullable required

ID of the user who created the distribution

created_atstring date-time nullable required

updated_atstring date-time nullable required

Example response

{
  "id": "dst_7C1hPliVteu3n4",
  "url": "https://app.voicepanel.co/d/7C1hPliVteu3n4",
  "study_id": "stdy_Qm3vR8tLp2XnWz",
  "name": "March newsletter link",
  "description": "Shared with newsletter subscribers in March.",
  "type": "link",
  "status": "published",
  "config": {},
  "incentive": {
    "type": "gift_card",
    "amount": 10,
    "title": "$10 gift card",
    "description": "Sent by email after you complete the interview."
  },
  "quota_limit": 100,
  "quota_frequency": "lifetime",
  "quota_usage": 42,
  "screener_questions": [
    {
      "text": "Have you ordered grocery delivery in the last 3 months?",
      "type": "radio",
      "isRequired": true,
      "options": [
        {
          "text": "Yes",
          "qualification": "qualify"
        },
        {
          "text": "No",
          "qualification": "disqualify"
        }
      ]
    }
  ],
  "default_response_language": "en",
  "automatic_invites": true,
  "complete_redirect_url": "https://example.com/thanks?rid={{response_id}}",
  "seq_num": 1,
  "published_at": "2026-03-02T15:12:00.000Z",
  "last_completed_at": "2026-03-09T18:45:00.000Z",
  "created_by": "0f1b3c6e-9d2a-4b7c-8e5f-2a1d4c6b8e90",
  "created_at": "2026-03-02T15:00:00.000Z",
  "updated_at": "2026-03-09T18:45:00.000Z",
  "pretranslations": [
    {
      "locale": "es"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.