VOvoicepanel
Stimuli

Claim a stimulus

Claim one stimulus for one response. The first call for a response and a stimulus answers allowed: true and records the claim. Every later call for the same pair answers allowed: false with the reason already_claimed. This makes a prototype link single-use: a participant cannot reopen it, and a shared link admits nobody else. Use it on the server that hosts a prototype, and call it once, when the participant arrives. A page reload after the claim is refused, so keep the participant on the page, or use GET /api/v1/stimuli/{stimulus_id}/access for a multi-use link. A claim applies the rule of the access check first: the study plan must reference the stimulus and the response must be active. A refused claim records nothing. A preview response is always allowed and is never claimed, because the researcher replays it. 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. A token with only the stimuli:claim scope can call this endpoint.

post/api/v1/stimuli/{stimulus_id}/claim

Request

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

Path parameters

stimulus_idstring required
Example:stim_3nK8xQw2PzLr7Y

The stimulus ID

Request body

response_idstring required

The ID of the response that asks to see the stimulus

Example request

{
  "response_id": "3f9c2b7e-5d41-4a8e-9b0c-7e2f1a6d4c58"
}

Response

Successful response

allowedboolean required

True if this call claimed the stimulus for the response. 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. The first call that passes this rule records the claim. Every later call for the same response and stimulus is refused. A preview response is always allowed and is never claimed.

reason'response_inactive' | 'stimulus_not_in_study' | 'already_claimed' nullable required

Why the claim 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. already_claimed: an earlier call claimed the stimulus for this response. Null when allowed is true.

Example response

{
  "allowed": true
}

Changes

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