eligibility-rules

increase conversion

📘

GET /supplier/v1/subsamples/{subsampleId}/eligibility-rules

Returns all eligibility criteria applied to a given subsample. Each rule is described as a series of return codes that will be eliminated and the time span for which the rule is enforced for each respondent.

To make sure that unique respondents are sent within the same event (a project with multiple subsamples with valid allocations), you must group subsamples by event id (property available for each subsample listed in POST /supplier/v1/event/all or POST /supplier/v1/event/live-details).

Caching: 15 minutes

field name	description
surveys	Eliminate respondents from other surveys/ rule used to eliminate certain surveys. (This will be used mostly on trackers to exclude past waves)
Id	The "id" under surveys represents the subsampleid to be excluded - unique value for each survey.
researchTypes	Eliminate respondents from surveys in the same research-type pool. This refers to very specific projects, like Next Connect, In-home user tests, even some diaries. A respondent who is participating in some capacity in this more involved kind of research will not be invited to multiple surveys, to avoid fatiguing the respondent or diluting the quality of an in-home test.
Id	The "id" under researchTypes represents the research type id to be excluded - for projects that were run in the past with this research-type value.
categories	This is the standard survey topic/category elimination rule, all 3 type of category should be checked and apply the exclusion for the return codes within this rule. Usually the exclusion should apply to specific category, if it's null, check generic category, if this is null check Main. The category classification is: specific category is included in generic category which is part of the main category.
mainCategoryId	The main category value to be excluded - for projects that were run in the past with this main category value.
genericCategoryId	The generic category value to be excluded - for projects that were run in the past with this generic category value.
specificCategoryId	The specific category value to be excluded - for projects that were run in the past with this specific category value.
events	Elimination on the same event a multi-target survey on a single country will require that completes are unique across the entire survey, not just within each target group (subsampleid). For the current event id most of the respondents that register a final status will be blocked for entering again in any subsample ids within this event.
Id	The "id" under events represents the event Id value to be excluded - for projects that are currently/were run in the past with this event value.
NumDays	The period of elimination – the number of days to apply the exclusion (0 means forever)
Implementation	Check if field:  "subsamples" has a value for "Id" different from "0" or "null" and apply the period of elimination and the return codes selected to be eliminated only for this subsampleId. Check if there are more than 1 subsampleIds and apply the exclusion selected within the second subsample.  "researchTypes" has a value for " Id " different from "0" or "null" and apply the period of elimination and the return codes selected to be eliminated only for studies with the same research-type-id. Check if there are more than 1 research-types ids and apply the exclusion selected within the second research type id.  "categories" has a value for any of the "mainCategoryId”, “genericCategoryId”, “specificCategoryId” different from "0" or "null" and apply the period of elimination and the return codes selected to be eliminated only for studies with the same "mainCategoryId”/ “genericCategoryId”/“specificCategoryId”. Check if there are more than 1 "mainCategoryId”/ “genericCategoryId”/“specificCategoryId” and apply the exclusion for those as well.  " events" has a value for "Id" different from "0" or "null" and apply the period of elimination and the return codes selected to be eliminated only for studies with the same eventid. Check if there are more than 1 eventids and apply the exclusion selected within the second eventid.

🚧

Respondent's History

To be able to track everything (category, research type, survey id, event id) you will need to create on your end, a history for each respondent that register a final status on one of our surveys. That history should contain: unique identifier of your respondent (the id/panelistid), survey id (subsample id) where the status was registered, the status id of that respondent on that survey, the date the status was registered, the event id of that survey, the category id of that survey (you can include only the specific category id) and the research type id of that survey.
Doing this, your system will know from the beginning which respondents will be/be not eligible to access the survey, from an exclusion point of view.

return codes legend

Status Id	Status name
2	In survey
3	Complete
82	Screen out
83	Quota full
92	Abandon
98	Erroneous complete
99	Potentially unengaged

eligibility-criteria return example:

JSON

{
  "surveys": [ 
    {
      "Id": 244678, 
      "numDays": 56,
      "returnCodes": [
        3,
        98
      ]
    },
   {
      "Id": 255959, 
      "numDays": 77,
      "returnCodes": [
        3,
        98
      ]
    }
  ],
  
  "researchTypes": [ 
    {
      "id": 0, 
      "numDays": 0,
      "returnCodes": [
        0
      ]
    }
  ],
  
  "categories": [
    {
        "mainCategoryId": 1, 
         "genericCategoryId": 431, 
    	  "specificCategoryId": 516, 
      "numDays": 0,
      "returnCodes": [
        0
      ],
      
    }
    {
        "mainCategoryId": 1, 
        "genericCategoryId": 504,
       "specificCategoryId": 573, 
     "numDays": 5
     "returnCodes": [
        3,
       82,
      ],
    }
  ],
  
  "events": [
    {
      "Id": 104775, 
      "name": "string",
      ""numDays": 999,
      "returnCodes": [
        2,
        3,
        98,
        82,
        83,
        99        
      ]
    }
  ],