---
title: "Claim a stimulus"
method: POST
path: "/api/v1/stimuli/{stimulus_id}/claim"
tags: ["Stimuli"]
---

# Claim a stimulus

`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

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](#tag/stimuli/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.

## Path parameters

- `stimulus_id` string, required

## Request body

- StimulusClaimBody: Claim a stimulus for a response
  - `response_id` string, required: The ID of the response that asks to see the stimulus

## Response `200`

Successful response

- StimulusClaim: Whether one response claimed one stimulus
  - `allowed` boolean, 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.

## Other responses

- `400`: Bad request. `code` is `validation_error` when a field is invalid or a query parameter is unknown, with the field paths in `details`, or `bad_request` otherwise.
- `401`: Unauthorized. The token is missing, invalid, or has no user.
- `403`: Forbidden. The token has no access to this resource.
- `404`: Not found. The resource does not exist or belongs to another account.
- `409`: Conflict. The write disagrees with the current state of the resource.
- `429`: Too many requests. The account used its API rate limit. `code` is `too_many_requests`. Wait for the number of seconds in `Retry-After`, then retry.
- `500`: Internal error. Quote `request_id` when you contact support.
- `503`: Service unavailable. A dependency did not answer and nothing was saved. Retry later.

---

[API](https://skmtc.dev/voicepanel/apis/voicepanel-api.md) - [All operations](https://skmtc.dev/voicepanel/apis/voicepanel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/voicepanel/apis/voicepanel-api/revisions/ee41535c5694?raw)