Documentation

Surveys

Suggest Edits

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:

ParameterDescription
unique_user_id
❗required		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_idUser ID assigned to the user by the supplier. It should be unique for each user.

unique_user_id is preferred
date_of_birth
❗required		Date of birth of the user in YYYY-MM-DD format. For a filtered view, one of the parameters - date_of_birth or age is required

Example: If a user has a static value for age, the system does not have a start or end date for the user's age. If a panelist is 30 years-old today, they would receive surveys targeted for a user that is 30 years-old. If that user turns 31 tomorrow, they could be excluded from surveys that pertain to a 31 year-old.

date_of_birth is the preferred parameter.
ageAge of the user
Please note: that passing "age" info is less accurate and could impact performance.
If age is passed instead of date_of_birth, we will still ask date_of_birth and there could be terminates based on the user's input.

Since age is calculated from date_of_birth, it is not available on the API response, however, it could be passed through URL
email ❗requiredEmail address of the user

Suppliers must provide real email addresses.
If the supplier does not want to pass the real email - please see hashed_e.
hashed_esha1 hash of the email address of the user.
If the supplier does not want to pass email, they can alternatively pass hashed_e instead.
Note: It is NOT possible to decrypt the hashed emails
gender
❗required		User's gender. Possible values in lower case - m, f.
ip_address
❗required		The IP address of the user (IPv4 or IPv6)
IPv4 is the preferred parameter.
platform_typeYou can also filter the items by sending the parameter platform_type. This parameter can have one value out of - android_phone, android_tablet, android_kindle, ios_phone, ios_ipod, ios_tablet and desktop.
Please note: Although in API response the text is platform_types, while passing it as parameter it is passed as platform_type (without s)
browser_familyThis parameter filters the items by allowed browsers. It can have one value out of - safari, chrome, firefox, ie, opera.
zip_code We highly recommend to also add zip_code as it allows our system to filter the studies based on it accurately.
Our system accepts full zip codes without any spaces. For e.g. SE1 6TJ for London, to be passed as &zip_code=se16tj (upper or lower case, both are fine)

Please note: If zip_code is not passed then users will be asked about the same.
There are some smaller countries as listed here where zip code will not be asked to users even if zip_code is not passed in the URL.

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:

ParameterDescription
country
❗required		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:

ParameterDescription
basicYou 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 basic with value 1 (True). Default value of basic parameter is 1 (True). ie, if you do not specify basic=0, qualifications and quotas will not be returned in the response.
limitWhen specified, the response will contain the given number of items. limit is an integer value. This is another way to reduce the response time, as less data will have to be returned.
project_idComma separated value. The response will contain only specified items. Example: project_id=13,454,5654
profilers_extraIf 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_typeThis allows suppliers to pull inventory for a specific exchange. Specifying 'OX' will return all available inventory from the Open Exchange.
Specifying 'PMP' will return all available inventory from the Private Marketplace.

If not used, by default it will return both type of inventory.

🚧

More is Better

When 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 are success and failure
  • surveys - list of survey objects

Description of survey object

FieldDescription
platform_typesAllowed platform type
survey_groups_idsSurvey 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.
qualificationsDictionary with profiler names as keys and profiler answers are values
conversion_rateIn field - The ratio of clicks to completes
mobile_conversion_rateIn field - The ratio of clicks to completes for mobile devices
desktop_conversion_rateIn field - The ratio of clicks to completes for desktop devices
countryCountry in which survey is offered
cpiCPI
entry_linkThe entry link for the panelist
loiIn field - length of the interview
project_idProject ID
qualifications_extralist of objects. Each object contains the keys answers, profiler_name and sorting
quotasList 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_completesRemaining completes for the survey
match_to_qualifyIf 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_creditingBoolean field. Whether or not there is delay in crediting.
tentitive_payoutDefines whether a project will result in completes or tentative completes. For more detailed information see below.
orderObject which contains order details such as ir and loi fields (estimated IR and LOI)
is_pmpDefines whether project is PMP or not. Possible values: true or false
buyerObject which contains buyer details such as id and name fields. Returned only when is_pmp is true!
c_project_idExposing 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_idExposing 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 10 months ago

What’s Next