<aside> 📢

IMPORTANT: From 1 December 2025, you will no longer be able to create new studies or launch previously drafted studies using the old version of custom screening.

We will also deprecate the following API endpoints:

• bulk screen-out endpoint
• screen-out reward calculator endpoint

</aside>

Custom Screening Upgrade: Slot Management

In the old version, custom screening studies are created (via the api/v1/studies endpoint) by adding a completion path with a SCREENED_OUT code type and a manual review action. Submissions are marked as screened-out by sending a POST request to the api/v1/studies/{id}/screen-out-submissions endpoint, including the reward that should be sent to the participants, based on the time it took them to answer the pre-screening questions.

In the new version, the main required changes are to the POST request to the studies endpoint. See below:

1. The completion path for custom screening studies requires two additional fields:

   • fixed_screen_out_reward which determines the reward that all screened-out participant should received (regardless of their completion time).
   • slots which sets a limit around the number of participants you are willing to screen out (once this threshold has been reached, the study will be paused, with the option to increase it if needed).

2. The completion path’s action is now FIXED_SCREEN_OUT_PAYMENT .

   // POST /api/v1/studies/ (partial request)
   {
     "name": "name of the study",
   	"completion_codes": [
       {
         "code": "completion code",
         "code_type": "code label",
         "actions": [
           {
             "action": "FIXED_SCREEN_OUT_PAYMENT", // <------ required
             "fixed_screen_out_reward": 50, // <------ new key (number of pence/cents)
             "slots": 5, // <------ new key (number of slots)
           }
         ],
         "actor": "participant"
       },
       {
         "code": "a different completion code",
         "code_type": "code label",
         "actions": [
           {
             "action": "code action"
           }
         ]
       }
     ],
     "total_available_places": 10,
     "reward": 100,
     ...
   }
   

Other changes to note:

1. Screened out participants will automatically be paid. Given this, you no longer need to make requests to the bulk screen-out endpoint or screen-out reward calculator endpoint.

2. Study totals now include the estimated total cost of screened out participants. Once the study is complete, any unused slots will automatically be reimbursed.

3. If all screen-out slots have been used up but you still need more participants, the study will be paused. At this point, you may choose to add more slots by sending a PATCH request to the studies endpoint with the new total number of slots:

   // PATCH /api/v1/studies/:study_id/
   {
   	"completion_codes": [
       {
         "code": "completion code",
         "actions": [
           {
             "action": "FIXED_SCREEN_OUT_PAYMENT",
             "slots": 14 // <------- new key
           }
         ]
       }
     ]
   }
   

   After increasing slots you’ll then need to resume the study:

   // POST /api/v1/studies/:study_id/transition/
   {
   	"action": "START"
   }
   

Read our API docs to get started

To get started with using new custom screening via the API, head to “Studies” > “Create a draft study” > expand “completion_codes” > expand “actions” > select “FixedScreenOut”.

If you need to increase to increase screen-out slots, go to “Studies” > “Update study” > select “update_slots” in the example dropdown.

Example

I want to run a short survey on people who own a specific dog breed. I can filter to dog owners but I need to run a custom screening question to find out which breed they own.

I am willing to pay £0.10 to any participant who answers my screening question but is screened out because they don’t own the breed I need. I set my fixed_screen_out_reward as £0.10.

I have a budget of £20 to pay for custom screening, so I can afford to screen out 200 participants at 10p per screen-out. I will allocate 200 slots.

Now you have much more reliable way to calculate costs and stay within budget.

See exactly how much custom screening will cost