Requirements object

AgeRangeEligibilityRequirement

• This filter allows you to apply a participant age range based on their date of birth. You can select the age range from 18 to 100 with the min_age and max_age configuration. Both min_age and max_age can be sent as two different objects in the attributes array. Please note, the age range is inclusive of max_age.

• All the necessary information for the payload, including the class name of the requirement (_cls), the attributes array, and the unique id of the question (query.id), can be sourced from the /api/v1/eligibility-requirements/ endpoint.

• The structure of each requirement object in the payload is as follows:

  • _cls: The class name of the requirement. It specifies the type of requirement (e.g. AgeRangeEligibilityRequirement).
  • attributes: An array of attribute objects. Each object in the array represents an option or answer. It has two properties:
    • name: The name of the attribute (min_age or max_age).
    • value: An integer that denotes the age limit.
  • query: An object that contains the id attribute. The query.id relates to the id of the question to which the object relates.

Here is an example of how to format your request:

1
...
2
  {
3
      "eligibility_requirements": [
4
          {
5
              "_cls": "web.eligibility.models.AgeRangeEligibilityRequirement",
6
              "attributes": [
7
                  {"name": "min_age", "value": 25},
8
                  {"name": "max_age", "value": 35},
9
              ],
10
              "query": {"id": "63567529751d8c97b6f7d16d"},
11
          }
12
      ]
13
  }

ApprovalNumbersEligibilityRequirement

• Recruit participants based on min and/or max number of approved submissions. You can send both minimum_approvals and maximum_approvals as two different objects in the attributes array.

  • To include participants that have 100 or more approved submissions, set minimum_approvals to value 100.
  • To include participants that have 200 or less approved submissions, set maximum_approvals to value 200.

ApprovalRateEligibilityRequirement

• Target participants based on minimum or maximum approval rate, the percentage of approved studies. We use the upper bound of the 95% confidence interval to calculate approval rate. You can send both minimum_approval_rate and maximum_approval_rate as two different objects in the attributes array.

  • To include participants that have 95% approval rate or higher, set minimum_approval_rate to value 95.
  • To include participants that have 95% approval rate or lower, set maximum_approval_rate to value 95.

JoinedBeforeEligibilityRequirement

• Only include participants who joined Prolific before a specified date (e.g. Participants who joined Prolific before 01/09/21).
• To include participants that have joined on the first of September 2021 or before, you can send an attribute with joined_before and value 2020-09-01. The format of the date is YYYY-MM-DD.

PreviousStudiesAllowlistEligibilityRequirement

• Include participants from selected completed studies. You can include participants from multiple studies by sending multiple attributes. Read about how to invite specific participants to your study.
• To include participants from a study, you can include the id and value attributes. Additionally, if you want to filter these participants to allow only those that have made a submission with a specific completion code, you can send the completion_codes attribute as an array of strings.

1
{
2
      ...
3
      "eligibility_requirements": [
4
          {
5
              "_cls": "web.eligibility.models.PreviousStudiesAllowlistEligibilityRequirement",
6
              "attributes": [
7
                  {
8
                      "id": "6356a58d1da9da204b53a076",
9
                      "value": true,
10
                      "completion_codes": [
11
                          "CODE"
12
                      ]
13
                  }
14
              ],
15
          }
16
      ]
17
  }

• To add previous participants whose response wasn’t approved, please instead use a custom allowlist.

PreviousStudiesEligibilityRequirement

• Exclude participants from the selected completed studies regardless of their submission status. You can exclude participants from multiple studies by sending multiple attributes. Read about how to prevent certain participants from accessing your study.
• To exclude participants from a study, you can include the id and value attributes. Additionally, if you want to filter these participants to block only those that have made a submission with a specific completion code, you can include the completion_codes attribute as an array of strings.

1
{
2
      ...
3
      "eligibility_requirements": [
4
          {
5
              "_cls": "web.eligibility.models.PreviousStudiesEligibilityRequirement",
6
              "attributes": [
7
                  {
8
                      "id": "6356a58d1da9da204b53a076",
9
                      "value": true,
10
                      "completion_codes": [
11
                          "CODE"
12
                      ]
13
                  }
14
              ],
15
    }
16
  ]
17
}

CustomWhitelistEligibilityRequirement

• A comma-separated list of participant and/or submission IDs for users you want to participate in the study.
• ONLY these participants will be eligible for this study (i.e. longitudinal design).
• To include participants by id, you can send an attribute with white_list and value an array of participant ids.
• You may also provide submission ids, which will be converted to their corresponding participant ids.

Custom Blacklist - CustomBlacklistEligibilityRequirement

• A comma-separated list of participant and/or submission IDs of the users you wish to make ineligible for the study.
• To exclude participants by id, you can send an attribute with black_list and value an array of participant ids.
• You may also provide submission ids, which will be converted to their corresponding participant ids.

Other Prescreen Requirements filters

Prescreening requirement filters enable participants to select one or multiple options/answers. The filters are of two types:

• Single Select - SelectAnswerEligibilityRequirement: Participants can select one option. Example: “In what country do you currently reside?”
• Multi Select - MultiSelectAnswerEligibilityRequirement: Participants can select multiple options. Example: “Which of the following languages are you fluent in?”

All the necessary information for the payload can be sourced from the /api/v1/eligibility-requirements/ endpoint. This endpoint provides the data structure for each requirement, including the class name (_cls), the attributes array, and the unique id of the question (query.id).

The structure of each requirement object in the payload is as follows:

• _cls: The class name of the requirement. It specifies the type of requirement (e.g. Single Select or Multi Select).
• attributes: An array of attribute objects. Each object in the array represents an option or answer. It has two properties:
  • value: A boolean that denotes if this option/answer is selected. Setting it to true includes the participants who have selected this option/answer. You only need to provide the attributes objects for those with value: True. The other options will default to false.
  • index: The position of this option/answer in the array. The indexing starts from 0.
• query: An object that contains the id attribute. The query.id relates to the id of the question to which the object relates.

Here is an example of how to format your request:

1
{
2
      ...
3
      "eligibility_requirements": [
4
          {
5
              "_cls": "web.eligibility.models.SelectAnswerEligibilityRequirement",
6
              "attributes": [
7
                  {"value": True, "index": 0},
8
              ],
9
              "query": {"id": "63567529751d8c97b6f7d16d"},
10
          }
11
      ]
12
  }

About unique Ids

If you are using React or other component framework to render these requirements, you might need a unique id for every requirement. At the moment there is not one, but you can use the question.id if present or the _cls if the question id was missing to build a unique id.