...
GET /Surveys/:Survey_id
...
/
...
PSIDEligible?PSID=%PSID%&rd_device_id=[%%research_defender_respondent_ud%%]&ip_address=[%%ipv4_address%%]
The primary use of this API End Point is to check the PSID exclusion. The supplier can check whether a given PSID is eligible for Exclusion.
| Warning |
|---|
Not yet available on Staging or Production |
Implementation
Every survey on PureSpectrum will have a "PSIDRef" List. Whether this list is used for Include or Exclude is determined by the response parameter "Incl_excl" present in the GET /Surveys
or GET /Surveys/:Survey_id call. The value of Include Exclude will not change for a survey which goes live.
| Info |
|---|
"incl_excl":0 indicates PSIDRef is an exclude list "incl_excl":1 indicates PSIDRef is an include list |
API Response for GET /surveys/:survey_id/PSIDref
| Code Block |
|---|
{
"PSIDRef":[
"75xxee23-370b-a8ye-e601-e1fzz59284c8"
"94xx7b3b-4608-01y4-b908-8aezzab971e1"
"24xx7db6-8507-47y9-9c67-0c6zz6244d98"
]
} |
Include
Include Survey's are sometimes referred to as recontact surveys. Effectively a buyer will define the list of respondents which they are attempting to reach. When a respondent that is on this list completes the survey, their id will automatically be removed from the PSIDRef list. As long as the PSID is present on the Ref list, the respondent may take the survey. PSID's are consistent across suppliers, so it is possible that the respondent may take a survey from one supplier, and be recontacted via a different supplier.
As a supplier, you should be storing the PSID of each respondent you send into PureSpectrum. We always append the PSID of the respondent on redirect back to you.
| Warning |
|---|
PSID is loosely based on device id. While unlikely, it is possible that the PSID of a respondent may change. You should always overwrite the PSID of your respondents in case the PSID changes. |
| Info |
|---|
If you see that a survey has "incl_excl":1, your system should call the api endpoint GET /surveys/:survey_id/PSIDRef. If any of the PSID's match within your system, you may then target these respondents for this survey. |
Exclude
If a survey is not defined as an include survey, the PSIDref list will always contain the EXCLUDE list. This is the default for surveys created on PureSpectrum. Leveraging the exclude list will allow you the ability to avoid termination due to deduplication. You may either call the survey's PSIDRef list, and store it, or you may use the optional query string parameter /PSIDref?PSID=%respondent'sPSID%, which will return back a response of
API Response for is present in the exclusion list or not.Implementation
PSIDEligible returns a response in form of either a 0 or 1.
Suppose that a PSID is present in the exclusion list, then the API response will be 0 which means that the PSID is not eligible for taking the survey, where as 1 means that it is eligible.
On the other hand lets suppose that a PSID is present in the inclusion list, then the API response will be 1 which means that the PSID is eligible for taking the survey, where as 0 means that it is not eligible.
API Response for "GET /surveys/:survey_id/PSIDEligible?PSID=75xxee23-370b-a8ye-e601-e1fzz59284c8"
| Code Block |
|---|
Example 1 :- When the PSID is present in the include List { "eligible": 1 // 1 is eligible, 0 is ineligible } } Example 2 :- When the PSID is *NOT* present in the include List { "eligible": 0 } Example 3 :- When the PSID is present in the Exclude List { "eligible": 0 } Example 4 :- When the PSID is *NOT* present in the Exclude List { "eligible": 1 } |
Research Defender /Predupe
By passing in a respondent's respondent_ud value, we are able to prevent duplicated clicks as determined by device id, which is a different dedupe mechanism than PSID.
Utilizing this feature will reduce the status "ps_df_dupe" - code 70
Respondent IP Addrress
By passing in a respondent's ip_address value, we are able to prequalify eligibility with some external partners.
Utilizing this feature will reduce the status "buyer_eligibility_precheck" - code 74
HEADER Parameters
Parameter | Type | Required | Description |
|---|---|---|---|
access-token | string | Yes | Token used to identify the authenticity of the user. |
Query String Parameters
Parameter | Type | Required | Description |
|---|---|---|---|
PSID | string | Yes | The respondent's persistent PSID |
| rd_device_id | string | No | Will check a respondent using Research Defender's /predupe api. Use this to reduce ps_df_dupe statuses |
| ip_address | string | No | Will check a respondent's eligibility with some buyers. IP Address should be in the format 0.0.0.0 |
Response Parameters
Parameter | Type | Description | Nullable | text|||||
|---|---|---|---|---|---|---|---|---|
| eligible | string | The text of the question asked to the respondent | PSIDRef | array | Contains a list of "PSIDRef" numbers which fall either under include or exclude category. | number | Shows whether a PSID is eligible for inclusion / exclusion. Either a 0 or 1. | no |
HTTP Response Codes
Response | Status | Description |
|---|---|---|
200 | OK | |
| 400 | Bad Request | See Error Messages |
| 404 | Not Found | Qualification code doesn't exist in database |
5xx | Internal Server Error | Please Report to support@purespectrum.com |
Error Messages
Response | Description |
|---|---|
1001 | Invalid Survey ID |
| 1002 | Invalid PSID Format |
9999 | Unknown Error - Please Report to support@purespectrum.com |
...