VOvoicepanel
Stimuli

Check stimulus access

Check whether one response can see one stimulus. Use it on the server that hosts a prototype: admit a participant only while allowed is true. The check records nothing, so a participant can open the link again, and every call gives the same answer while the response is active. This makes a prototype link multi-use. For a single-use link, use POST /api/v1/stimuli/{stimulus_id}/claim instead. When a participant opens a website, prototype, mobile app, or html stimulus, the URL carries both ids as query parameters: voicepanel_response_id and voicepanel_stimulus_id. Stimulus IDs also appear on each stimulus in a study's plan. A token with only the stimuli:check_access scope can call this endpoint.

get/api/v1/stimuli/{stimulus_id}/access

Request

  • Base URL
    https://app.voicepanel.com
  • URL
    https://app.voicepanel.com/api/v1/stimuli/{stimulus_id}/access
  • Auth
    HTTP bearer

Path parameters

stimulus_idstring required
Example:stim_3nK8xQw2PzLr7Y

The stimulus ID

Query parameters

response_idstring required
Example:3f9c2b7e-5d41-4a8e-9b0c-7e2f1a6d4c58

The ID of the response that asks to see the stimulus

Response

Successful response

allowedboolean required

True if the response can see the stimulus. The study plan must reference the stimulus and the response must be active. A response is active while its status is opened or in_progress and its distribution is published. A paused or completed distribution closes the study, so its responses are inactive. A preview response is always active, because it is the researcher's own test run. A participant who leaves stays active until the response times out, which can take up to about 15 minutes.

reason'response_inactive' | 'stimulus_not_in_study' nullable required

Why access is refused. stimulus_not_in_study: the plan of the response's study does not reference the stimulus. response_inactive: the response is completed, incomplete, or not yet opened, or its distribution is paused or completed. A preview response never gets this reason. Null when allowed is true.

Example response

{
  "allowed": true
}

Changes

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