Surveys
GET: https://www.your-surveys.com/suppliers_api/surveys
The Survey endpoint will return a list of studies. Each study will have quotas, demographics, and other data elements associated. The list will either be Performance or Basic.
Performance API calls
If respondent data is included in the call, The Supply Api powered by Yield Management System will return a filtered, de-duplicated, and prioritized list of surveys for that respondent.
Basic API calls
If respondent data is not included in the call, you can pull the full inventory for specific countries.
Both calls will return the same data objects.
Note!
The Performance API call is the only API call that will return user-specific surveys like market effectiveness & recontact studies.
It is highly recommended that the supplier passes a value for ssi for both types of integration. Read more on this under Best Practices
Parameters
Performance API calls
Here are the different parameters that pertain to Performance API calls only:
Parameter | Description |
---|---|
unique_user_id
❗ | A unique user ID assigned to the user by the supplier. It should be unique for each user. The unique_user_id may contain alphanumeric characters only, no special characters except underscore(), dash (-), and at sign (@). There is a 128 character limit. |
user_id | User ID assigned to the user by the supplier. It should be unique for each user.
|
date_of_birth | Date of birth of the user in YYYY-MM-DD format. For a filtered view, one of the parameters - Example: If a user has a static value for
|
age | Age of the user
Since age is calculated from date_of_birth, it is not available on the API response, however, it could be passed through URL |
email ❗ | Email address of the user
|
hashed_e |
|
gender | User's gender. Possible values in lower case - |
ip_address | The IP address of the user (IPv4 or IPv6) |
platform_type | You can also filter the items by sending the parameter platform_type. This parameter can have one value out of -
|
browser_family | This parameter filters the items by allowed browsers. It can have one value out of - |
zip_code | We highly recommend to also add zip_code as it allows our system to filter the studies based on it accurately.
When zip_code is passed, other region info like region1, region2, will be auto-calculated and region1, region2 is not required to be passed |
Basic API calls
Here are the parameters that pertain to Basic API calls only:
Parameter | Description |
---|---|
country
❗ | The country you want to pull studies from |
Common
Here are the parameters that can be used on both a Performance and Basic API call:
Parameter | Description |
---|---|
basic | You can choose to retrieve only the basic information about the surveys. This will reduce the response time as less data will have to be returned. If you want to specify basic, just add the GET parameter |
limit | When specified, the response will contain the given number of items. |
project_id | Comma separated value. The response will contain only specified items. Example: |
profilers_extra | If present and set to 1, in addition to qualifications and conditions, the response will also have conditions_extra and qualifications_extra keys in the study objects. Each item in these extra objects have profiler_name, answers and sorting keys. You can use the value of sorting to order the profiler objects in your system. |
exchange_type | This allows suppliers to pull inventory for a specific exchange. Specifying 'OX' will return all available inventory from the Open Exchange. If not used, by default it will return both type of inventory. |
More is BetterWhen making an API call, we strongly recommend providing as many demographic profilers as possible, in addition to the required profilers.
For profiler questions with type Multiple Choice, the answers must be comma-separated value. Example:
http://www.your-surveys.com/?gender=m&diagnosed_ailments=5665,5674,5687&electronics=6182,6193&hmac=1c6469cffa996fc14a2dc187b665a806&si=3&ssi=test
Examples
Performance API call
<?php
$secret = 'secret';
# Required parameters
$params = array(
'user_id'=> 12,
'date_of_birth'=> '1990-01-01',
'email'=> '[email protected]',
'gender'=> 'f',
'zip_code'=> '99501',
'ip_address'=> '100.200.240.240',
'limit'=> 3,
'basic'=> 1,
);
$params = http_build_query($params);
$opts = array(
'http'=> array(
'method'=> "GET",
'header'=> "X-YourSurveys-Api-Key: $secret",
'ignore_errors' => true,
)
);
$url = 'https://www.your-surveys.com/suppliers_api/surveys/user';
$url = $url . '?' . $params;
$context = stream_context_create($opts);
/* Sends an http request to www.your-surveys.com/supppliers/surveys with additional headers shown above */
$fp = fopen($url, 'r', false, $context);
# Output all data from the response
fpassthru($fp);
fclose($fp);
import requests
import json
import pprint
# Pass our secret in the HTTP request header
headers = {"X-YourSurveys-Api-Key": "secret"}
# Surveys User URL
url = "https://www.your-surveys.com/suppliers_api/surveys/user"
# Required and optional parameters
params = {
"user_id": 1,
"date_of_birth": "1990-01-01",
"email": "[email protected]",
"gender": "f",
"zip_code": "99501",
"ip_address": "100.200.200.200",
}
response = requests.get(url, headers=headers, params=params)
# We have the response, pretty print using the pprint module
pp = pprint.PrettyPrinter(indent=4)
pprint.pprint(response.json())
# If you don't want to use pprint, you could just print using
# print response.json()
Basic API call
<?php
$secret = 'secret';
# Required parameters
$params = array(
'limit'=> 3,
'basic'=> 1,
'country'=>'US',
);
$params = http_build_query($params);
$opts = array(
'http'=> array(
'method'=> "GET",
'header'=> "X-YourSurveys-Api-Key: $secret",
'ignore_errors' => true,
)
);
$url = 'https://www.your-surveys.com/suppliers_api/surveys/user';
$url = $url . '?' . $params;
$context = stream_context_create($opts);
/* Sends an http request to www.your-surveys.com/supppliers/surveys with additional headers shown above */
$fp = fopen($url, 'r', false, $context);
# Output all data from the response
fpassthru($fp);
fclose($fp);
import requests
import json
import pprint
# Pass our secret in the HTTP request header
headers = {"X-YourSurveys-Api-Key": "secret"}
# Surveys User URL
url = "https://www.your-surveys.com/suppliers_api/surveys/user"
# Required and optional parameters
params = {
"country": "US",
"limit": 3,
}
response = requests.get(url, headers=headers, params=params)
# We have the response, pretty print using the pprint module
pp = pprint.PrettyPrinter(indent=4)
pprint.pprint(response.json())
# If you don't want to use pprint, you could just print using
# print response.json()
Description of Response body
The HTTP response body is in JSON format. The top level keys in the object are:
status
- possible values aresuccess
andfailure
surveys
- list of survey objects
Description of survey object
Field | Description |
---|---|
platform_types | Allowed platform type |
survey_groups_ids | Survey Group IDs. list of groups that a survey can be a member of. Surveys that are member of the same group need to be deduped against each other. |
qualifications | Dictionary with profiler names as keys and profiler answers are values |
conversion_rate | In field - The ratio of clicks to completes |
mobile_conversion_rate | In field - The ratio of clicks to completes for mobile devices |
desktop_conversion_rate | In field - The ratio of clicks to completes for desktop devices |
country | Country in which survey is offered |
cpi | CPI |
entry_link | The entry link for the panelist |
loi | In field - length of the interview |
project_id | Project ID |
qualifications_extra | list of objects. Each object contains the keys answers , profiler_name and sorting |
quotas | List of objects. Each object in the list contains the key conditions and conditions_extra . conditions is a dictionary with profiler name as key and profiler answers list as value. conditions_extra contains three fields: answers , profiler_name and sorting |
remaining_completes | Remaining completes for the survey |
match_to_qualify | If true , the panelist has to match one of the quotas to be able to get into the study. If the panelist does not match any of the quotas, they cannot do the study. If false , then the panelist can go into the study when the basic qualifications of the study are met. Quota in this case will block panelists if there is no allocation left. |
delay_crediting | Boolean field. Whether or not there is delay in crediting. |
tentitive_payout | Defines whether a project will result in completes or tentative completes. For more detailed information see below. |
order | Object which contains order details such as ir and loi fields (estimated IR and LOI) |
is_pmp | Defines whether project is PMP or not. Possible values: true or false |
buyer | Object which contains buyer details such as id and name fields. Returned only when is_pmp is true ! |
c_project_id | Exposing C Project Id, an internal field used by Cint and PMP suppliers. Most suppliers won't need this. This is primarily used for debugging purposes. |
c_target_group_id | Exposing C Target Group Id, an internal field used by Cint and PMP suppliers. Most suppliers won't need this. This is primarily used for debugging purposes. |
Example Survey object
{
"project_id": 28306514,
"name": "Give us your opinion",
"study_type": 1,
"cpi": "1.00",
"remaining_completes": 199,
"conversion_rate": "0.08", "_comment": "in field conversion rate",
"loi": 14, "_comment": "in field LOI",
"country": "US",
"survey_groups_ids": [
2995568
],
"platform_types": [
"desktop",
"ios_tablet",
"android_kindle",
"android_tablet"
],
"match_to_qualify": true,
"delay_crediting": false,
"tentative_payout": false,
"order": { "_comment": "estimated LOI and IR",
"loi": 18,
"ir": 60
},
"is_pmp": false,
"mobile_conversion_rate": "0.62", "_comment": "in field conversion rate for mobile devices",
"desktop_conversion_rate": "0.00", "_comment": "in field conversion rate for desktop devices",
"entry_link": "https://www.your-surveys.com?si=472&offer_id=28306514&ssi=SUBID",
"c_project_id": 1730169,
"c_target_group_id": 3471033,
"_comment": "blocks of quotas and qualification is visible only with paramter basic=0",
"quotas": [
{
"id": 389177770,
"remaining_completes": 199,
"conditions": {
"age": [
25,
26
],
"region2": [
366147
]
}
}
],
"qualifications": {
"age": [
25,
26
],
"region2": [
366147
],
"gender": [
10682,
10683
]
},
"score": null
},
Project-Specific Performance Calls
If a project ID is appended to the Performance API call (one project at a time) suppliers utilizing project-specific performance API calls will gain further term insight.
The API response will return %status% or %cobra_status% terms under “messages.”
Example of the call:
GET: https://www.your-surveys.com/suppliers_api/surveys?unique_user_id=test123&date_of_birth=2000-08-16&gender=m&ip_address=82.15.233.24&[email protected]&project_id=28502082

Completes vs Tentative Completes
Tentative completes are completes that are not final yet. They include completes that are more likely to be reconciled but also completes where the CPI and payout might still change.
Suppliers with Private Market Place (PMP) deals will see their Private Market Place completes as tentative until the project is closed and the CPI and payout are updated and verified.
The API will communicate 'tentative payout' in the API upon pulling the survey data. Private Market Place projects can be identified by looking at the 'buyer name' communicated in the API. Only Private Market Place projects will have the buyer name included.
It is up to each supplier to decide whether to delay payment to respondents, lower their payout to be covered for risk or pay out like they typically do.
For this, there are two callbacks/redirects that can be set in the Supply Portal, one for completes and one for tentative completes.
Updated 2 months ago