![Lucid fulcrum type [color]](images/lucid-fulcrum-type-[color].png)
Introduction
Cint brings efficiency and automation to online sampling with Cint Marketplace, the world’s most powerful, open, and customizable online sampling platform.
The Demand and Supply APIs provide a simple way to connect to millions of people and get answers in real time. By specifying a set of demographic qualifications and quotas, buyers can target a wide or very specific population on a topic of your choosing. As a supplier, you get fine grain control over your survey matching and business relationships on the platform.
We want to encourage innovation with minimal limits. We ask that you please be practical and considerate when determining call frequencies. We rate limit when needed to protect the system and ensure the highest level of service to all of our clients.
We also have a status page that displays real-time system performance. Any and all system downtime will be posted here.
New to Market Research & Surveys? Check out our glossary for definitions of common terms you will see in our documentation.
Environments
Sandbox Endpoint
https://sandbox.techops.engineering/
Production Endpoint
https://api.samplicio.us/
To make Cint’s APIs as explorable as possible, we have environments specific to your development needs. For access to these environments contact your Integration Consultant at integrations@cint.com. Please navigate to the Supply Integration Guide or the Demand Integration Guide to see how to get started.
Please note: Sandbox keys are only available for the Demand API, and not for the Supply API.
Users are financially responsible for all transactions made on the system regardless of whether it was the result of a bug in your integration.
Authentication
The Cint APIs use a HTTP Authorization header for authentication. Every call should have a header Authorization: {{APIkey}}. Ensure that the key you are passing is the correct key for the environment. If you don’t already have a Cint account, get started by signing up for a demo!
Request Format
Built on RESTful principles, the API uses HTTP methods and verbs. Requests should be made using JSON, and JSON is returned by all responses.
Running in Postman
The entire Cint Marketplace API collection can be easily imported into Postman, by clicking the button below:
Postman is a free application that allows you to execute test calls in an intuitive interface.
HTTP Status Codes
Cint Marketplace APIs use conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error caused by the information provided (i.e., a required parameter was omitted, a method was not found, etc.), and codes in the 5xx range indicate an error with Cint’s servers (these are rare).
| Status Code | Status Text | Description |
|---|---|---|
| 200 | OK | The request has succeeded. The meaning of a success varies depending on the HTTP method: |
| GET: The resource has been fetched and is transmitted in the message body. | ||
| POST: The resource describing the result of the action is transmitted in the message body | ||
| 201 | Created | The request has succeeded and a new resource has been created as a result of it. This is typically the response sent after a PUT request. |
| 202 | Accepted | The request has succeeded and has been added to the queue, but the resource has not yet been created. This is typically the response sent after PUT and POST requests. |
| 204 | No Content | There is no content to send for this request. This is common for DELETE requests. |
| 307 | Temporary Redirect | The target resource resides temporarily under a different URI and the user agent MUST NOT change the request method if it performs an automatic redirection to that URI. |
| 400 | Bad Request | This response means that server could not understand the request due to invalid syntax. |
| 401 | Unauthorized | Authentication is needed to get requested response. This is similar to 403, but in this case, authentication is possible. |
| 403 | Forbidden | Client does not have access rights to the content so server is refusing to give proper response. |
| 404 | Not Found | Server cannot find the requested resource. |
| 405 | Method Not Found | The request method is known by the server but has been disabled and cannot be used. Double check your method type (i.e. GET, POST, PUT, DELETE) |
| 409 | Conflict | This response would be sent when a request conflicts with the current state of the server. |
| 429 | Too Many Requests | The user has sent too many requests in a given amount of time (“rate limiting”). |
| 499 | Internal Server Error | The server has encountered an internal error. |
| 500 | Internal Server Error | The server has encountered a situation it doesn’t know how to handle. |
| 502 | Bad Gateway | The server, while acting as a gateway or proxy, received an invalid response from an inbound server it accessed while attempting to fulfill the request. |
| 503 | Service Unavailable | The server is not ready to handle the request. Common causes are a server that is down for maintenance or that is overloaded. |
| 504 | Gateway Timeout | This error response is given when the server is acting as a gateway and cannot get a response in time. |
FAQs
Do you have a question regarding your Cint integration? Click on the appropriate FAQ article to find the answer. If you still can’t find the answer to your question, get in touch with your account team.
Lookup
Definitions
GET List Global Definitions
Definition
GET https://api.samplicio.us/Lookup/v1/BasicLookups/BundledLookups/{Bundle}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Lookup/v1/BasicLookups/BundledLookups/CountryLanguages,Industries,SampleTypes,StudyTypes,SupplierLinkTypes,SurveyStatuses
require 'net/http'
uri = URI('https://api.samplicio.us/Lookup/v1/BasicLookups/BundledLookups/CountryLanguages,Industries,SampleTypes,StudyTypes,SupplierLinkTypes,SurveyStatuses')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Lookup/v1/BasicLookups/BundledLookups/CountryLanguages,Industries,SampleTypes,StudyTypes,SupplierLinkTypes,SurveyStatuses";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Lookup/v1/BasicLookups/BundledLookups/CountryLanguages,Industries,SampleTypes,StudyTypes,SupplierLinkTypes,SurveyStatuses'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Lookup/v1/BasicLookups/BundledLookups/CountryLanguages,Industries,SampleTypes,StudyTypes,SupplierLinkTypes,SurveyStatuses");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Lookup/v1/BasicLookups/BundledLookups/CountryLanguages,Industries,SampleTypes,StudyTypes,SupplierLinkTypes,SurveyStatuses",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetBundledLookups successful."
],
"ResultCount": 6,
"AllBidProbabilities": [],
"AllBidStatuses": [],
"AllCategoryLockOutDurations": [],
"AllCountries": [],
"AllCountryLanguages": [
{
"Code": "CHI-CN",
"Id": "1",
"IsActive": true,
"Name": "Chinese Simplified - China",
"SortOrder": 1
}
],
"AllIndustries": [
{
"Code": "AUTO",
"Id": "1",
"IsActive": true,
"Name": "Automotive",
"SortOrder": 1
}
],
"AllProposalTypes": [],
"AllQuestionClassifications": [],
"AllSampleTypes": [
{
"Code": "Consumer",
"Id": "100",
"IsActive": true,
"Name": "Consumer",
"SortOrder": 1
}
],
"AllStudyTypes": [
{
"Code": "ADH",
"Id": "1",
"IsActive": true,
"Name": "Adhoc",
"SortOrder": 1
}
],
"AllSupplierLinkTypes": [
{
"Code": "TS",
"Id": "1",
"IsActive": true,
"Name": "Targeted / Standalone",
"SortOrder": 1
}
],
"AllSupplierPreferenceTypes": [],
"AllSupplierRequestStatuses": [],
"AllSupplierTrackingUrlTypes": [],
"AllSurveyPlatforms": [],
"AllSurveyStatuses": [
{
"Code": "02",
"Id": "1",
"IsActive": true,
"Name": "Pending",
"SortOrder": 1
}
],
"AllThirdPartyServices": []
}
Returns a list of global system definitions. Arguments can be passed individually or in aggregate, with arguments separated by a comma. One argument must be provided at minimum.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| Bundle | string | true | A string of lookup options delimited by a comma. |
Options
| Option | Description |
|---|---|
| Countries | Array of all countries. |
| CountryLanguages | Array of all Country-Language pairs by ID. |
| Industries | Array of all options for industry type. |
| SampleTypes | Array of all types of sample that buyers can field on the platform. |
| StudyTypes | Array of all types of studies buyers can field on the platform. |
| SupplierLinkTypes | Array of all link types suppliers can use to send sample. |
| SurveyStatuses | Array of all possible survey statuses on the platform. |
| BidProbabilities | Array of all probabilities of a bid being awarded (Low, Med, High). |
| BidStatuses | Array of all possible statuses for a bid. |
| ProposalTypes | Array of all possible proposal types. |
| CategoryLockOutDurations | Array of all possible lockout times. |
| QuestionClassifications | Array of all question categories on the platform. |
| SupplierPreferenceTypes | Array of all possible preferences a supplier can communicate. |
| SupplierRequestStatuses | Array of all tracking methods a supplier can use to track a respondent’s status. |
| ThirdPartyServices | Array of all Third Party Services on the platform. |
GET List Suppliers
Definition
GET https://api.samplicio.us/Core/v1/Suppliers/AllWithAccount
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Core/v1/Suppliers/AllWithAccount
require 'net/http'
uri = URI('https://api.samplicio.us/Core/v1/Suppliers/AllWithAccount')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Core/v1/Suppliers/AllWithAccount",
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Core/v1/Suppliers/AllWithAccount'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Core/v1/Suppliers/AllWithAccount");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "https://api.samplicio.us/Core/v1/Suppliers/AllWithAccount",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetAllSuppliersGroupedByAccount successful."
],
"ResultCount": 4,
"AccountsWithSuppliers": [
{
"AccountName": "Sample Company",
"Suppliers": [
{
"Name": "Supplier 1",
"Code": "1010"
},
{
"Name": "Supplier 2",
"Code": "1010"
},
{
"Name": "Supplier 3",
"Code": "1010"
},
{
"Name": "Supplier 4",
"Code": "1010"
},
]
}
]
}
Returns a list of all suppliers.
GET List Business Units
Definition
GET https://api.samplicio.us/Core/v1/BusinessUnits/All
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Core/v1/BusinessUnits/All
require 'net/http'
uri = URI('https://api.samplicio.us/Core/v1/BusinessUnits/All')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Core/v1/BusinessUnits/All";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Core/v1/BusinessUnits/All'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Core/v1/BusinessUnits/All");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Core/v1/BusinessUnits/All",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetAllBusinessUnits successful."
],
"ResultCount": 1,
"BusinessUnits": [
{
"AccountID": 001,
"Id": "001",
"Name": "Fulcrum"
},
]
}
Returns a list of all Business Units.
Question Library
The questions in this library can be used to build qualifications for surveys created in the Cint Marketplace. Each question represents a respondent profile datapoint.
GET List Standard Questions
Definition
GET https://api.samplicio.us/Lookup/v1/QuestionLibrary/AllQuestions/{CountryLanguageID}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Lookup/v1/QuestionLibrary/AllQuestions/{CountryLanguageID}
require 'net/http'
uri = URI('https://api.samplicio.us/Lookup/v1/QuestionLibrary/AllQuestions/{CountryLanguageID}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Lookup/v1/QuestionLibrary/AllQuestions/{CountryLanguageID}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Lookup/v1/QuestionLibrary/AllQuestions/{CountryLanguageID}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Lookup/v1/QuestionLibrary/AllQuestions/{CountryLanguageID}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Lookup/v1/QuestionLibrary/AllQuestions/{CountryLanguageID}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetAllQuestions successful."
],
"ResultCount": 1,
"Questions": [
{
"IsCoreDemographic": true,
"IsFeasibilityFactor": true,
"LK_QuestionClassificationID": 8,
"Name": "AGE",
"QuestionID": 42,
"QuestionText": "What is your age?",
"QuestionType": "Numeric - Open-end",
"SurveyUse": 8162
}
]
}
Returns a list of all standard questions and question texts for the specified Country-Language pair.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| CountryLanguageID | int | true | Unique id associated with the Country-Language pair the question text applies to. |
GET List Custom Questions
Definition
GET https://api.samplicio.us/Lookup/v1/QuestionLibrary/AllCustomQuestionsByAccount/{CountryLanguageID}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Lookup/v1/QuestionLibrary/AllCustomQuestionsByAccount/{CountryLanguageID}
require 'net/http'
uri = URI('https://api.samplicio.us/Lookup/v1/QuestionLibrary/AllCustomQuestionsByAccount/{CountryLanguageID}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Lookup/v1/QuestionLibrary/AllCustomQuestionsByAccount/{CountryLanguageID}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Lookup/v1/QuestionLibrary/AllCustomQuestionsByAccount/{CountryLanguageID}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Lookup/v1/QuestionLibrary/AllCustomQuestionsByAccount/{CountryLanguageID}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Lookup/v1/QuestionLibrary/AllCustomQuestionsByAccount/{CountryLanguageID}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetAllQuestions successful."
],
"ResultCount": 1,
"Questions": [
{
"__type": "PublicQuestionModel",
"IsCoreDemographic": false,
"IsFeasibilityFactor": false,
"LK_QuestionClassificationID": null,
"Name": "HHI",
"QuestionID": 51,
"QuestionText": "What is your annual household income before taxes?",
"QuestionType": "Single Punch",
"SurveyUse": 2,
"AccountID": 1
}
]
}
Returns a list of custom questions associated with and created by your account for the specified Country-Language pair.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| CountryLanguageID | int | true | Unique id associated with the Country-Language pair the question text applies to. |
GET Show Question Text
Definition
GET https://api.samplicio.us/Lookup/v1/QuestionLibrary/QuestionById/{CountryLanguageID}/{QuestionID}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Lookup/v1/QuestionLibrary/QuestionById/{CountryLanguageID}/{QuestionID}
require 'net/http'
uri = URI('https://api.samplicio.us/Lookup/v1/QuestionLibrary/QuestionById/{CountryLanguageID}/{QuestionID}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Lookup/v1/QuestionLibrary/QuestionById/{CountryLanguageID}/{QuestionID}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Lookup/v1/QuestionLibrary/QuestionById/{CountryLanguageID}/{QuestionID}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Lookup/v1/QuestionLibrary/QuestionById/{CountryLanguageID}/{QuestionID}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Lookup/v1/QuestionLibrary/QuestionById/{CountryLanguageID}/{QuestionID}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetQuestionById successful."
],
"ResultCount": 1,
"Question": {
"IsCoreDemographic": true,
"IsFeasibilityFactor": true,
"LK_QuestionClassificationID": 8,
"Name": "AGE",
"QuestionID": 42,
"QuestionText": "What is your age?",
"QuestionType": "Numeric - Open-end",
"SurveyUse": 8420
}
}
Returns the details of a specific standard or custom qualification.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| CountryLanguageID | int | true | Unique id associated with the Country-Language pair the question text applies to. |
| QuestionID | int | true | Unique id associated with the question the question text applies to. |
GET Show Question Options
Definition
GET https://api.samplicio.us/Lookup/v1/QuestionLibrary/AllQuestionOptions/{CountryLanguageID}/{QuestionID}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Lookup/v1/QuestionLibrary/AllQuestionOptions/{CountryLanguageID}/{QuestionID}
require 'net/http'
uri = URI('https://api.samplicio.us/Lookup/v1/QuestionLibrary/AllQuestionOptions/{CountryLanguageID}/{QuestionID}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response= http.request(request)
<?php
$URL = "https://api.samplicio.us/Lookup/v1/QuestionLibrary/AllQuestionOptions/{CountryLanguageID}/{QuestionID}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Lookup/v1/QuestionLibrary/AllQuestionOptions/{CountryLanguageID}/{QuestionID}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Lookup/v1/QuestionLibrary/AllQuestionOptions/{CountryLanguageID}/{QuestionID}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Lookup/v1/QuestionLibrary/AllQuestionOptions/{CountryLanguageID}/{QuestionID}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetAllQuestionOptions successful."
],
"ResultCount": 1,
"QuestionOptions": [
{
"OptionText": "Male",
"ParentItemText": null,
"Precode": "1",
"QuestionID": 43
},
{
"OptionText": "Female",
"ParentItemText": null,
"Precode": "2",
"QuestionID": 43
}
]
}
Returns the answer options and associated precodes for a specific QuestionID and Country-Language pair.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| CountryLanguageID | int | true | Unique id associated with the Country-Language pair the question text applies to. |
| QuestionId | int | true | Unique id associated with the question the question text applies to. |
Beta - Lookup
Dictionary (beta)
These resources support our beta endpoints, including Beta - Demand Integration and Beta - On Time Supply sections. They provide data about the values you can use in the fields of models used in beta endpoints.
We recommend caching the endpoints below as they will rarely change.
Definition
GET https://api.samplicio.us/demand/v2-beta/{property}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" "https://api.samplicio.us/demand/v2-beta/locales?page_size=3&page_number=23"
require 'net/http'
uri = URI("https://api.samplicio.us/demand/v2-beta/locales?page_size=3&page_number=23")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/demand/v2-beta/locales?page_size=3&page_number=23";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = "https://api.samplicio.us/demand/v2-beta/locales?page_size=3&page_number=23"
headers = {'Authorization' : 'YOUR_API_KEY_HERE'}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/locales?page_size=3&page_number=23");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/demand/v2-beta/locales?page_size=3&page_number=23",
"headers": {'Authorization': 'YOUR_API_KEY_HERE'}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"result": [
{
"code": "fre_ma",
"name": "French - Morocco"
},
{
"code": "eng_lu",
"name": "English - Luxembourg"
},
{
"code": "ger_lu",
"name": "German - Luxembourg"
}
],
"total": 263
}
Dictionaries model
| Property | Description | Query Args |
|---|---|---|
| business-units | Which business unit of an account a survey belongs to, determines currency used by the survey. | page_size, page_number |
| clients | The clients that have been created on your account. | page_size, page_number |
| industries | The industries that a survey can be associated with. | page_size, page_number |
| locales | A Country-Language pair. | page_size, page_number |
| lockouts | Blocks respondents during a certain timeframe based on whether they’ve taken a separate survey in the same industry. | page_size, page_number |
| study-types | Indicates the survey’s limits and purpose. | page_size, page_number |
| survey-groups | A security grouping to control respondents. | page_size, page_number |
| suppliers | A list of suppliers with their ids and codes. | page_size, page_number |
| users | All of the users on the account. Use the user’s returned id when using this property. If you are updating your users list often, caching this lookup might not be effective. | page_size, page_number, query |
Errors (beta)
The error messages for the v2-beta endpoints are designed to be both human and machine-readable. An example of an error reponse is listed below.
{
"errors": [{
"code": "v07",
"detail": {
"field": "expected_incidence_rate",
"max": 1,
"min": 0
},
"docs_url": "https://developer.lucidhq.com/#v07",
"message": "This field isn't within the correct range."
}]
}
Errors model
| Property | Data Type | Description |
|---|---|---|
| code | string | The associated error code. |
| detail | dict | Additional info for understanding the error, such as validation information. |
| docs_url | string | The URL in the documentation which describes the given error |
| message | string | The message associated with the error. |
GET List of Possible Errors (beta)
This endpoint returns the list of all possible errors, including a list of what additional properties will be returned in each error’s detail section.
Definition
GET https://api.samplicio.us/demand/v2-beta/errors
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" "https://api.samplicio.us/demand/v2-beta/errors"
require 'net/http'
uri = URI("https://api.samplicio.us/demand/v2-beta/errors")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/demand/v2-beta/errors";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = "https://api.samplicio.us/demand/v2-beta/errors"
headers = {'Authorization' : 'YOUR_API_KEY_HERE'}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/errors");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/demand/v2-beta/errors",
"headers": {'Authorization': 'YOUR_API_KEY_HERE'}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"result": [
{
"detail": ["field"],
"error_code": "v01",
"http_status": 400,
"message": "This field didn't pass validation."
}
]
}
Possible Errors Model
| Property | Data Type | Description |
|---|---|---|
| detail | string[] | The additional information that will be included in the error’s detail object |
| error_code | string | The error’s unique identifier |
| http_status | number | The HTTP Status code that this error is attached to |
| message | string | The human-readable message that is displayed with the error |
Possible Errors
a01
HTTP Status: 500
Message: An undefined error occurred.
This error is a catch-all for any errors that do not belong into any of the below categories (yet). We log these errors and will resolve the issue soon.
Server Errors
These errors generally follow the pattern of 500-level HTTP Errors. We log all server errors. If you run into one of these, we will be investigating them to find the problem. If you continually run into an issue, shoot us an email at integrations@cint.com and we will get you more information.
s01
HTTP Status: 500
Message: An unspecified server error occurred.
This occurs when the API runs into an error we did not expect and was unable to handle it properly.
s02
HTTP Status: 500
Message: A server error occurred.
This occurs when the API runs into an error we expected to never happen.
s03, s04, s05, s07
HTTP Status: 500
Message: An upstream server error occurred.
This occurs when one of our internal services was unable to fulfill the request properly.
s06
HTTP Status: 504
Message: An upstream server timed out.
This occurs when one of our internal services takes too long to respond to a request. If this happens, retry the request a few times after backing off for a few seconds before giving up. Many times, these are simply caused by a hiccup in our system that will resolve itself.
Validation Errors
These errors usually occur when one of your inputs is not valid and follow the pattern of 400-level HTTP errors. Thus, with most of these errors, we will return the problematic field in the error body.
v01
HTTP Status: 400
Message: This field didn't pass validation.
Additional Data: field
This is a generic catch-all for validation errors that do not fall into one of the below error types.
v02
HTTP Status: 400
Message: This field must be a multiple of the denominator.
Additional Data: field, denominator
This occurs when a value passed into a numeric field is not a multiple of the returned denominator. For example, a value (numerator) of 0.875 would not be valid if the denominator is 0.1.
v03
HTTP Status: 404
Message: This endpoint doesn't exist.
This occurs when you made a request to a URL that does not exist. Confirm that you do not have any unwanted trailing slashes and that you are passing in numbers to a URL path fragment that expects it (for example: a survey_id should be a number).
v04
HTTP Status: 404
Message: This object doesn't exist.
Additional Data: type, id
This occurs when you try to request an object that does not exist or you reference an object in the body of a request that does not exist.
v05
HTTP Status: 405
Message: This method isn't allowed on this endpoint.
This error occurs when the endpoint you are hitting exists, but the HTTP method (GET/PATCH/DELETE/etc) you used in the request is not accepted on the endpoint. Check that you are using GET to fetch data, PATCH to update objects, or DELETE to remove objects. See individual endpoint documentation for more details.
v06
HTTP Status: 400
Message: This field isn't the correct type.
Additional Data: field, type
This error occurs when you try to pass in an incorrect JSON type (number/string/boolean/array/etc) for a field. The error’s type property will tell you what type the value needs to be.
v07
HTTP Status: 400
Message: This field isn't within the correct range.
Additional Data: field, min, max
For certain numeric fields, there is a restricted acceptable range for values. This error occurs when you input a value that doesn’t fall into that range. Some fields may not have a min or a max - in this case, those properties in the error will be null.
v08
HTTP Status: 400
Message: This field isn't in the correct format.
Additional Data: field, pattern
This error occurs when an input value does not match against a field’s regular expression. For example, the locale field must follow the format xxx_xx, or language code, underscore, and country code. This also occurs when a date is not a valid RFC3339 datetime.
v09
HTTP Status: 400
Message: Must provide this field in this request.
Additional Data: field
This error occurs when you do not pass in a field that is required on a request.
v10
HTTP Status: 400
Message: This field isn't accepted on this request.
Additional Data: field
This error occurs when you pass in a field that is not accepted on this request.
v11
HTTP Status: 400
Message: This field must be one of these options.
Additional Data: field, options
This error occurs when a field’s value must come from a list of specific values. The valid options will be returned in the error’s options property.
v12
HTTP Status: 400
Message: This field cannot be modified after the survey is launched.
Additional Data: field
Certain fields are locked and not modifiable after the survey launches for the first time. This error occurs when you try to modify one of those fields after the survey goes live. If you need to modify one of these values, please create a new survey and try again.
v13
HTTP Status: 400
Message: This field must be set before the survey goes live.
Additional Data: field
Certain fields must be set before setting a survey live via the status or begin_date parameters. This error occurs when one of those fields is still set to null and you try to set the survey live.
v14
HTTP Status: 400
Message: This string has an invalid length.
Additional Data: field, min_length, max_length
This error occurs when a field’s string value is not an acceptable length. This error’s min_length and/or max_length can be null, meaning there is no minimum length or maximum length, respectively.
v15
HTTP Status: 400
Message: The start_date must fall before the end_date.
This error occurs when you pass in a correctly-formatted start_date and/or end_date, but the start_date doesn’t fall before the end_date.
v16
HTTP Status: 400
Message: Content-Type header must be "application/json" and request body must be valid JSON.
This error occurs when your Content-Type HTTP header does not have the value "application/json" or your request is not valid JSON. Note that we only accept JSON bodies on requests that accept a body.
v19
HTTP Status: 400
Message: These fields cannot be modified while Fielding Assistant is enabled.
Additional Data: fields, survey_id
This error occurs when Fielding Assistant is enabled on the survey and a change is requested for a field that Fielding Assistant is automating. Apart from the above message, a list of all fields that cannot be modified will be returned in the response.
For example, if Fielding Assistant is automating the CPI of the survey and the API receives a request to change the CPI of the survey, this error will be returned. This error will never be returned if Fielding Assistant is not enabled on the survey.
Supply Integration
On-time Supply - Webhook Security
Supply Services at Cint employ a number of security measures to protect both ourselves and users. While most of this happens behind the scenes, taking full advantage of these security features require those using On Time Supply features to verify message integrity by verifying the signature included in the header of each outbound request. All callback requests are signed with a Cint generated key that is unique to the supplier. The receiving supplier verifies the signature using a public key that is shared to the supplier via the secured GET request to the OTS resource they are securing. This provides security against the manipulation of the data payload. Additionally, a timestamp will be included, which affords additional security against replay attacks.
Request Signatures
To begin the request signing process, one must make an initial ‘subscribe’ request. In turn, they will receive a response body, which contains an encoded public key and key identifier.
From that point onward, messages from Supply Services will undergo KMS signing procedures and will contain the following X-Lucid-Signature header
| Header Name | Format |
|---|---|
| X-Lucid-Signature | t:<timestamp>,<schema version>:<signing key identifier>:<signature> |
| Property | Description |
|---|---|
| timestamp | The unix timestamp (UTC) for when the signature was generated. This is used to provide protection against replay exploits |
| schema version | The version of the schema used to build the text segment that gets signed using ECDSA_SHA_256 |
| signing key identifier | An identifier for the key that was used to generate the signature. This value should match the first 8 characters of the ID returned on subscription creation. |
| signature | The result of the signing operation encoded using SHA256. |
The following example demonstrates what a signature header may look like during a key rotation/deprecation event. We see two message signatures both tagged with schema version v1. The first signature, in this case, is for the deprecated key e21612e, and the second signature is signed with the current key 6ffbb59.
X-Lucid-Signature: t:1492774577,v1:e21612e:MEYCIQDXHipmLwxYl18Kkc8WRy6abCr1NJH4wlh1kcCJQ6LT7gIhALXJxiXqRgZVqXIQPMKsSZLWv7B-YpJjzxxj6qLwVvCm,v1:6ffbb59:MEYCIQCavPcHvdbRKNrUcB8CupWEx0s2QufT8nnYj-CbR0avcgIhANWnKbidVe7f2-5Q-8Ukyz3c1cZ0Y8RiRWIXYrOWl-4k
Signature Verification
Step 1: Extract the timestamp and signatures from the header
Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the : character as the separator, to get a prefix, the secret identifier, and signature elements.
Step 2: Construct the Message Digest for the request
The signature string is created by concatenating the following values together before SHA256 summing the result into the Message Digest.
- timestamp (as a Unix Timestamp in UTC)
- character
. - actual JSON payload of the request body
Step 3: Verify the included signature
You can use your chosen programming language’s ECDSA library to verify that your message_digest matches the signature included when verified with your public key.
Examples of this process will be provided. See: https://aws.amazon.com/blogs/security/how-to-verify-aws-kms-asymmetric-key-signatures-locally-with-openssl/
Further Reading
This design was inspired by Stripe’s Webhook signing strategy. You can read more about it at the following locations:
- https://stripe.com/docs/webhooks/signatures
- https://docs.aws.amazon.com/kms/latest/APIReference/API_Sign.html
- https://aws.amazon.com/blogs/security/how-to-verify-aws-kms-asymmetric-key-signatures-locally-with-openssl/
- https://aws.amazon.com/blogs/security/how-to-verify-aws-kms-signatures-in-decoupled-architectures-at-scale/
On-time Supply - Opportunities
On-time Supply allows you to subscribe to Cint survey opportunities. New opportunities that meet your subscription criteria will be sent to the callback specified in your subscription, along with changes as opportunities you are subscribed to are updated.
In addition to upgraded workflows, you will see Cint’s modern paths and parameters styling. On-time Supply uses snake_case rather than CamelCase you see in existing Supply API endpoints. You can see a translation of the old styling to the new in our FAQ article.
Recontacts in Opportunities
To receive recontact survey opportunities, configured your subscription criteria to include the recontact study_type either by not filtering by study_type or specifically filtering to include recontact study_type. Where buyers want to recontact your respondents, you will begin to see the recontact_pids field populated with your respondents PIDs information for those recontact surveys.
Qualification and Quotas in Opportunities
To receive qualification and quota data include "include_quotas": true in the body of the POST Create Opportunities request.
The On-time Supply collection can be easily imported into Postman by clicking the button below:
Access our On-Time Supply FAQ article to find answers relating to common On-Time Supply questions.
Opportunities Model
| Property | Type | Description |
|---|---|---|
| survey_id | int | Unique number associated with the survey. |
| survey_name | string | External name of the survey. This name may be exposed to respondents. This value is not unique across surveys. Maximum length of 128. |
| account_name | string | Name of the buyer running the survey. |
| country_language | string | The Country-Language pair the survey is open to. |
| industry | string | Industry associated with the survey’s topic. |
| study_type | string | Indicates the survey’s format and purpose (i.e. adhoc, recruit, etc). |
| bid_length_of_interview | float | Estimated time for a respondent to complete the survey excluding the Marketplace prescreener in minutes as provided by the buyer. |
| bid_incidence | float | Estimated incidence rate of the survey as provided by the buyer. |
| collects_pii | boolean | true indicates that the survey will collect PII. |
| survey_group_ids | array | Unique ID associated with a survey group, if applicable. |
| is_live | boolean | true indicates that the survey is live on the Marketplace. |
| survey_quota_calc_type | string | Indicates whether quotas are calculated based on completes or prescreens. |
| is_only_supplier_in_group | boolean | true indicates that an allocation is reserved for a single supplier. |
| cpi | float | Gross payout per complete. This value is in US dollars and is before any applicable commissions or fees. |
| total_client_entrants | int | Number of total client survey entrants across all suppliers. |
| total_remaining | int | Number of completes still available to the supplier. |
| completion_percentage | float | Percentage of total, needed completes that have been achieved on the survey. |
| conversion | float | Percentage of respondents who complete the survey after qualifying. |
| length_of_interview | int | Median time for a respondent to complete the survey, excluding the Marketplace prescreener, in minutes. This value will be zero until a complete is achieved. |
| overall_completes | int | Number of completes already achieved across all suppliers on the survey. |
| mobile_conversion | float | Percentage of respondents on a mobile device who complete the survey after qualifying. |
| earnings_per_click | float | The Earning Per Click value of the survey. EPC = (CPI * completes) / system entrants |
| termination_length_of_interview | int | Median time for a respondent to be termed, in minutes. This value is calculated after six survey entrants and rounded to the nearest whole number. Until six survey entrants are achieved the value will be zero. |
| respondent_pids | array of strings | List of calling suppliers PIDs that are valid for the survey if it is configured as a recontact survey. Field intentionally left blank on non-recontact studies or on recontact studies that the supply has no matching PIDs for. |
| message_reason | string | Describes the status of the survey in the supplier’s OTS subscription. See Support Article for additional information. |
survey_quotas model
| Property | Type | Description |
|---|---|---|
| survey_quota_id | int | Unique number associated with the quota. |
| survey_quota_type | string | Represents the function of the quota. The Total quota represents the maximum number of completes available on the survey and will always be present. Client quotas are any subquotas on the survey. They are independent of the total quota and may be overlapping with one another. |
| quota_cpi | float | CPI gross payout set for that quota complete. This value is in US dollars and is before any applicable commissions or fees. |
| conversion | float | Percentage of respondents who complete the survey after qualifying for that quota. This value is calculated after one complete and rounded to the nearest whole number. |
| number_of_respondents | int | Number of completes available in that quota group. |
| questions | array | Contains an array of Question models. |
survey_qualifications model
| Property | Type | Description |
|---|---|---|
| questions | array | Contains an array of Questions models. |
questions model
| Property | Type | Description |
|---|---|---|
| question_id | int | Unique number associated with the question. |
| logical_operator | string | Defines the logical operation applied to the conditions. |
| precodes | array | Qualification answer option identifier. |
POST Create Opportunities Subscription
Definition
POST https://api.samplicio.us/supply/opportunities/v1/subscriptions/{supplier_code}
Example Request
curl -H "Content-Type: application/json" \
-H 'Authorization: YOUR_API_KEY_HERE' \
-X POST --data '{
"callback": "https://wwww.callback.com/url",
"include_quotas": true,
"payload_max_size_mb":9,
"payload_max_survey_count":1000,
"send_interval_seconds":10,
"opportunities": [{
"country_language": {"in": ["eng_us", "eng_gb"]},
"study_type": {"eq": "adhoc"},
"cpi": {"gte": 1}
}]
}' \
https://api.samplicio.us/supply/opportunities/v1/subscriptions/{supplier_code}
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/supply/opportunities/v1/subscriptions/{supplier_code}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri, initheader = {'Content-Type' =>'application/json'})
request.body = {
callback: "https://wwww.callback.com/url",
include_quotas: true,
opportunities: [{
country_language: {"in": ["eng_us", "eng_gb"]}},
study_type: {"eq": "adhoc"},
cpi: {"gte": 1}
]}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
puts response.body
<?php
$curl = curl_init();
$params = '{"callback": "https://wwww.callback.com/url",
"include_quotas": true,
"opportunities": [{
"country_language": {"in": ["eng_us", "eng_gb"]},
"study_type": {"eq": "adhoc"},
"cpi": {"gte": 1}
}]}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/supply/opportunities/v1/subscriptions/{supplier_code}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
echo $response;
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/supply/opportunities/v1/subscriptions/{supplier_code}'
params = {'callback': 'https://wwww.callback.com/url',
'include_quotas': true,
'opportunities': [{
'country_language': {'in': ['eng_us', 'eng_gb']},
'study_type': {'eq': 'adhoc'},
'cpi': {'gte': 1},}]}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.post(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/supply/opportunities/v1/subscriptions/{supplier_code}");
string args = @"{
""callback"": ""https://wwww.callback.com/url"",
""include_quotas"": true,
""opportunities"": [{
""country_language"": {""in"": [""eng_us"", ""eng_gb""]},
""study_type"": {""eq"": ""adhoc""},
""cpi"": {""gte"": 1}
}]
}";
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "POST",
"hostname": "api.samplicio.us",
"path": "/supply/opportunities/v1/subscriptions/{supplier_code}",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'}
};
var json = { callback: 'https://wwww.callback.com/url',
include_quotas: true,
opportunities:
[ { country_language: { in: [ "eng_us", "eng_gb", "fre_fr" ] },
study_type: { "eq": "adhoc" },
cpi: { gte: 1 }, } ] };
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
"OK"
{
"survey_id": 12345678,
"survey_name": "My Great Survey",
"account_name": "Sample_Account",
"country_language": "eng_us",
"industry": "other",
"study_type": "adhoc",
"bid_length_of_interview": 5,
"bid_incidence": 50,
"collects_pii": false,
"survey_group_ids": [1258951],
"is_live": true,
"survey_quota_calc_type": "completes",
"is_only_supplier_in_group": true,
"cpi": 1.35,
"total_client_entrants": 480,
"total_remaining": 46,
"completion_percentage": 0.15824915,
"conversion": 0.39166668,
"overall_completes": 188,
"mobile_conversion": 0.28,
"earnings_per_click": 0.35,
"length_of_interview": 3,
"termination_length_of_interview": 2,
"respondent_pids": [],
"message_reason": "new",
"survey_quotas": [
{
"survey_quota_id": 80544313,
"survey_quota_type": "Total",
"quota_cpi": 1.5,
"conversion": 0.39166668,
"number_of_respondents": 46,
"questions": null
},
{
"survey_quota_id": 80544314,
"survey_quota_type": "Client",
"quota_cpi": 1.5,
"conversion": 0.4329897,
"number_of_respondents": 30,
"questions": [
{
"precodes": [
"25",
"26",
"27",
"28",
"29"
],
"logical_operator": "OR",
"question_id": 42
}
]
},
{
"survey_quota_id": 80544315,
"survey_quota_type": "Client",
"quota_cpi": 1.5,
"conversion": 0.39166668,
"number_of_respondents": 2,
"questions": [
{
"precodes": [
"2"
],
"logical_operator": "OR",
"question_id": 43
}
]
},
{
"survey_quota_id": 80544316,
"survey_quota_type": "Client",
"quota_cpi": 1.5,
"conversion": 0.3909091,
"number_of_respondents": 44,
"questions": [
{
"precodes": [
"8",
"9"
],
"logical_operator": "OR",
"question_id": 61076
}
]
}
],
"survey_qualifications": [
{
"logical_operator": "OR",
"precodes": [
"25",
"26",
"27",
"28",
"29"
],
"question_id": 42
},
{
"logical_operator": "OR",
"precodes": [
"2"
],
"question_id": 43
},
{
"logical_operator": "OR",
"precodes": [
"8",
"9"
],
"question_id": 61076
}
]
}
Post a new subscription or replace an existing subscription. This endpoint returns 200 on success. The Opportunities model will be returned to your callback url every 15 seconds* for any new or updated survey opportunity that matches the criteria specified in your subscription. You will receive messages about any surveys that are set live or changed after your subscription has been created. You may have one subscription per Supplier Code. This endpoint will return Webhook Security fields to use to validate OTS callbacks.
*You can adjust how frequently you receive survey data, the size of the payload and the number of surveys in the callback message. Please refer to the Arguments section on how to create these filters.
Arguments
| Property | Data Type | Required | Description | Limits |
|---|---|---|---|---|
| callback | string | true | The callback url that survey opportunities, both new and updates, will be sent to. | - |
| include_quotas | boolean | false | true opts you in to receive qualification and quota data. | |
| payload_max_size_mb | int | false | The maximum amount of data sent via callback per call. Measured in MB. If not included, this defaults to 8. | 4<x<32 |
| payload_max_survey_count | int | false | The maximum number of surveys sent via callback per call. If not included, this defaults to 1000. | 1000<x<10000 |
| send_interval_seconds | int | false | The minimum batch time for survey changes to gather before being sent in a callback. This is in seconds. If not included, this defaults to 15. | 5 < x < 30 |
| opportunities | array | true | Array of arguments, specified to filter opportunities delivered to callback. | - |
| country_language | #CompareStr | true | The Country-Language pair the survey is open to. | #locales |
| industry | #CompareStr | false | Industry associated with the survey’s topic. | #industries |
| study_type | #CompareStr | false | Indicates the survey’s format and purpose (i.e. adhoc, recruit, etc). | #study-types |
| bid_length_of_interview | #CompareFloat | false | Estimated time for a respondent to complete the survey excluding the Marketplace prescreener in minutes as provided by the buyer. | 0<= |
| bid_incidence | #CompareFloat | false | Estimated incidence rate of the survey as provided by the buyer. | 0-100 |
| collects_pii | #CompareBool | false | true indicates that the survey will collect PII. |
- |
| cpi | #CompareFloat | false | Gross payout per complete. This value is before any applicable commissions or fees. | 0.0<= |
| conversion | #CompareFloat | false | Percentage of respondents who complete the survey after qualifying. | 0.0-1.0 |
| mobile_conversion | #CompareFloat | false | Percentage of respondents on a mobile device who complete the survey after qualifying. | 0.0-1.0 |
| earnings_per_click | #CompareFloat | false | The Earning Per Click value of the survey. EPC = (CPI * completes) / system entrants | 0.0<= |
| length_of_interview | #CompareInt | false | Median time for a respondent to complete the survey, excluding the Marketplace prescreener, in minutes. | 0<= |
| termination_length_of_interview | #CompareInt | false | Median time for a respondent to be termed, in minutes. | 0<= |
Compare Objects
CompareStr
| Object | Description |
|---|---|
| eq | “string” |
| ne | “string” |
| in | [“string”, “string”] |
| nin | [“string”, “string”] |
CompareInt, CompareFloat
| Object | Description |
|---|---|
| eq | num |
| ne | num |
| in | [num, num] |
| nin | [num, num] |
| gte | num |
| lte | num |
CompareBool
| Object | Description |
|---|---|
| eq | bool |
CompareIntArray
| Object | Description |
|---|---|
| in | [num, num] |
| nin | [num, num] |
DELETE Remove an Opportunity Subscription
Definition
DELETE https://api.samplicio.us/supply/opportunities/v1/subscriptions/{supplier_code}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" -X DELETE https://api.samplicio.us/supply/opportunities/v1/subscriptions/{supplier_code}
require 'net/http'
uri = URI('https://api.samplicio.us/supply/opportunities/v1/subscriptions/{supplier_code}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/supply/opportunities/v1/subscriptions/{supplier_code}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_POSTFIELDS => "",
));
curl_exec($curl);
curl_close($curl);
?>
import requests
url = 'https://api.samplicio.us/supply/opportunities/v1/subscriptions/{supplier_code}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.delete(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/supply/opportunities/v1/subscriptions/{supplier_code}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
request.Method = "DELETE";
request.GetResponse();
const https = require('https');
var options = {
"method": "DELETE",
"hostname": "api.samplicio.us",
"port": 443,
"path": "/supply/opportunities/v1/subscriptions/{supplier_code}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options);
request.end();
Example Response
"OK"
Remove an existing subscription. This endpoint returns 200 on success. This call will stop all opportunities from being sent to the callback url in your subscription.
GET Show an Opportunity Subscription
Definition
GET https://api.samplicio.us/supply/opportunities/v1/subscriptions/{supplier_code}?surveys=true
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" -X GET https://api.samplicio.us/supply/opportunities/v1/subscriptions/{supplier_code}?surveys=true
require 'net/http'
uri = URI('https://api.samplicio.us/supply/opportunities/v1/subscriptions/{supplier_code}?surveys=true')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/supply/opportunities/v1/subscriptions/{supplier_code}?surveys=true",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_POSTFIELDS => "",
));
curl_exec($curl);
curl_close($curl);
?>
import requests
url = 'https://api.samplicio.us/supply/opportunities/v1/subscriptions/{supplier_code}?surveys=true'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/supply/opportunities/v1/subscriptions/{supplier_code}?surveys=true");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
request.Method = "GET";
request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"port": 443,
"path": "/supply/opportunities/v1/subscriptions/{supplier_code}?surveys=true",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options);
request.end();
Example Response
"OK"
{
"callback": "https://wwww.callback.com/url",
"include_quotas": true,
"opportunities": [
{
"cpi": {
"gte": 1
},
"country_language": {
"in": [
"eng_us",
"eng_gb"
]
},
"study_type": {
"eq": "adhoc"
},
}
],
"name": "{supplier_code}",
"surveys": [
{
"survey_id": 123456,
"survey_name": "Example Survey",
"survey_lastSend": "2019-08-26T08:56:53.578330598Z"
},
{
"survey_id": 234567,
"survey_name": "Another Example Survey",
"survey_lastSend": "2019-08-27T19:14:12.578167806Z"
}
]
}
Show an existing subscription. This endpoint returns 200 on success. This call will return the current subscription, if one exists for the supplier. This endpoint will return Webhook Security fields to use to validate OTS callbacks.
Arguments
| Property | Data Type | Required | Description | Limits |
|---|---|---|---|---|
| surveys | boolean | false | When true, a list of surveys currently active on the existing subscription will be returned in the response body. |
- |
On-time Supply - Respondent Outcomes
The Outcomes resource contains information about a respondent’s session as they move through the Marketplace. You may have one subscription per Supplier Code. Through optional filtering of your subscription, you can limit messages to specified response codes. Detailed information about Marketplace and Client response statuses can be found on the Cint Support Site: Marketplace Response Codes and Client Response Codes. See our FAQ article for additional example subscriptions.
Respondent Model
| Property | Type | Description |
|---|---|---|
| respondent_id | string | Unique session ID per study per respondent. |
| parent_session_id | string | Parent session ID. |
| panelist_id | string | A supplier’s unique respondent identifier. |
| session_id | string | Secondary panelist ID. Also known as MID. |
| marketplace_status | int | Response code associated with the respondent’s Marketplace session. |
| client_status | int | Response code associated with the respondent’s client survey attempt. |
| entry_date | datetime | Date and time the respondent entered Marketplace. |
| last_date | datetime | Date and time the respondent last interacted with the session. |
| survey_id | int | Unique number associated with the survey. |
| cpi | float | Gross payout per complete. This value is before any applicable commissions or fees. |
| study_type | string | The type of study associated with the respondent’s session. |
POST Create Outcomes Subscription
Definition
POST https://api.samplicio.us/supply/respondent-outcomes/v1/subscriptions/{supplier-code}
Example Request
curl -H "Content-Type: application/json" \
-H 'Authorization: YOUR_API_KEY_HERE' \
-X POST --data '{
"callback": "https://wwww.callback.com/url",
"outcomes": [{
"marketplace_status": {"eq": 3},
"client_status": {"in": [11, 26, 28]}
}]
}' \
https://api.samplicio.us/supply/respondent-outcomes/v1/subscriptions/{supplier-code}
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/supply/respondent-outcomes/v1/subscriptions/{supplier-code}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri, initheader = {'Content-Type' =>'application/json'})
request.body = {
callback: "https://wwww.callback.com/url",
outcomes: [{
marketplace_status: {"eq": 3},
client_status: {"in": [11, 26, 28]}
]}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
puts response.body
<?php
$curl = curl_init();
$params = '{"callback": "https://wwww.callback.com/url",
"outcomes": [{
"marketplace_status": {"eq": 3},
"client_status": {"in": [11, 26, 28]}
}]}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/supply/respondent-outcomes/v1/subscriptions/{supplier-code}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
echo $response;
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/supply/respondent-outcomes/v1/subscriptions/{supplier-code}'
params = {'callback': 'https://wwww.callback.com/url',
'outcomes': [{
'marketplace_status': {'eq': 3},
'client_status': {'in': [11, 26, 28]},}]}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.post(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/supply/respondent-outcomes/v1/subscriptions/{supplier-code}");
string args = @"{
""callback"": ""https://wwww.callback.com/url"",
""outcomes"": [{
""marketplace_status"": {""eq"": 3},
""client_status"": {""in"": [11, 26, 28]}
}]
}";
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "POST",
"hostname": "api.samplicio.us",
"path": "/supply/respondent-outcomes/v1/subscriptions/{supplier-code}",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'}
};
var json = { callback: 'https://wwww.callback.com/url',
outcomes:
[ { marketplace_status: { "eq": 3 ] },
client_status: { "in": [ 11, 26, 28 ] }, } ] };
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
"OK"
{
"respondent_id": "XXXXX-XXXX",
"parent_session_id": "XXXXX-XXXX",
"panelist_id": "XXXXX-XXXX",
"session_id": "XXXXX-XXXX",
"marketplace_status": 3,
"client_status": 11,
"entry_date": "2019-09-18T19:29:18.119Z",
"last_date": "2019-09-18T19:29:18.119Z",
"survey_id": 100001,
"cpi": 1.25,
"study_type": "adhoc"
}
Post a new subscription or replace an existing subscription. This endpoint returns 200 on success. The Respondent model will be returned to your callback url every 15 seconds for any status that matches the criteria specified in your subscription. You will receive messages about any new sessions or updates after your subscription has been created. You may have one subscription per Supplier Code. This endpoint will return Webhook Security fields to use to validate OTS callbacks.
Callback & supplier_code are required parameters for this call. There must be at least one argument in the array of outcomes.
Arguments
| Property | Data Type | Required | Description | Limits |
|---|---|---|---|---|
| callback | string | true | The callback url that respondent outcomes will be sent to. | - |
| outcomes | array | true | Array of arguments, specified to filter respondent outcomes delivered to callback. | - |
| marketplace_status | #CompareInt | false | Response code associated with the respondent’s Marketplace session. | Marketplace Response Codes |
| client_status | #CompareInt | false | Response code associated with the respondent’s client survey attempt. | Client Response Codes |
CompareInt, CompareFloat
| Object | Description |
|---|---|
| eq | num |
| ne | num |
| in | [num, num] |
| nin | [num, num] |
| gte | num |
| lte | num |
DELETE Remove an Outcome Subscription
Definition
DELETE https://api.samplicio.us/supply/respondent-outcomes/v1/subscriptions/{supplier-code}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" -X DELETE https://api.samplicio.us/supply/respondent-outcomes/v1/subscriptions/{supplier-code}
require 'net/http'
uri = URI('https://api.samplicio.us/supply/respondent-outcomes/v1/subscriptions/{supplier-code}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/supply/respondent-outcomes/v1/subscriptions/{supplier-code}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_POSTFIELDS => "",
));
curl_exec($curl);
curl_close($curl);
?>
import requests
url = 'https://api.samplicio.us/supply/respondent-outcomes/v1/subscriptions/{supplier-code}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.delete(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/supply/respondent-outcomes/v1/subscriptions/{supplier-code}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
request.Method = "DELETE";
request.GetResponse();
const https = require('https');
var options = {
"method": "DELETE",
"hostname": "api.samplicio.us",
"port": 443,
"path": "/supply/respondent-outcomes/v1/subscriptions/{supplier-code}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options);
request.end();
Example Response
"OK"
Remove an existing subscription. This endpoint returns 200 on success. This call will stop all respondent outcomes from being sent to the callback url in your subscription.
GET Show an Outcomes Subscription
Definition
GET https://api.samplicio.us/supply/respondent-outcomes/v1/subscriptions/{supplier-code}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" -X GET https://api.samplicio.us/supply/respondent-outcomes/v1/subscriptions/{supplier-code}
require 'net/http'
uri = URI('https://api.samplicio.us/supply/respondent-outcomes/v1/subscriptions/{supplier-code}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/supply/respondent-outcomes/v1/subscriptions/{supplier-code}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_POSTFIELDS => "",
));
curl_exec($curl);
curl_close($curl);
?>
import requests
url = 'https://api.samplicio.us/supply/respondent-outcomes/v1/subscriptions/{supplier-code}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/supply/respondent-outcomes/v1/subscriptions/{supplier-code}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
request.Method = "GET";
request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"port": 443,
"path": "/supply/respondent-outcomes/v1/subscriptions/{supplier-code}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options);
request.end();
Example Response
"OK"
{
"callback": "https://wwww.callback.com/url",
"outcomes": [
{
"marketplace_status": {
"eq": 3
},
"client_status": {
"in": [
11,
26,
28
]
}
}
],
"name": "{supplier-code}"
}
Show an existing subscription. This endpoint returns 200 on success. This call will return the current subscription, if one exists for the supplier. This endpoint will return Webhook Security fields to use to validate OTS callbacks.
Survey Groups
The Survey Groups resource will return survey group details for a particular survey number. This information can be used to track survey groups to avoid sending a respondent to a survey which is in a survey group with a survey they have already been sent to.
The Surveys/AllOfferwall and SupplierAllocations/BySurveyNumber calls return a SurveyGroupExists property which will indicate if the survey is in a survey group. The Surveys/SurveyGroups call can then be made to identify and track survey group details. You will need to continue to check the survey number and do not send the same respondent to any survey in that survey group as long as you are sending respondents to the survey and the survey continues to show "SurveyGroupExists": 0.
Survey Groups Model
| Property | Type | Description |
|---|---|---|
| SurveyGroup | string | Name associated with the survey group. Maximum length of 200. |
| SurveyGroupID | int | Unique ID associated with a survey group |
| SurveyGroupSurveys | array | List of all survey numbers in the survey group |
GET List a Survey’s Groups
Definition
GET https://api.samplicio.us/Supply/v1/Surveys/SurveyGroups/BySurveyNumber/{SurveyNumber}/{SupplierCode}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Supply/v1/Surveys/SurveyGroups/BySurveyNumber/{SurveyNumber}/{SupplierCode}
require 'net/http'
uri = URI('https://api.samplicio.us/Supply/v1/Surveys/SurveyGroups/BySurveyNumber/{SurveyNumber}/{SupplierCode}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Supply/v1/Surveys/SurveyGroups/BySurveyNumber/{SurveyNumber}/{SupplierCode}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Supply/v1/Surveys/SurveyGroups/BySurveyNumber/{SurveyNumber}/{SupplierCode}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Supply/v1/Surveys/SurveyGroups/BySurveyNumber/{SurveyNumber}/{SupplierCode}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Supply/v1/Surveys/SurveyGroups/BySurveyNumber/{SurveyNumber}/{SupplierCode}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetSurveyGroups successful."
],
"ResultCount": 2,
"SurveyGroups": [
{
"SurveyGroup": "",
"SurveyGroupID": 12259,
"SurveyGroupSurveys": [
590043,
600432,
583920,
601834,
598282
]
},
{
"SurveyGroup": "",
"SurveyGroupID": 12274,
"SurveyGroupSurveys": [
600432,
601834,
601943
]
}
]
}
Returns information on the survey group used by the specified survey.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
| SupplierCode | string | true | Unique code associated with a supplier account. |
Entry Links
The Entry Links resource enables you to create, update, and retrieve survey entry links, specify supplier link and tracking types as well as create custom survey redirects. The entry links can then be used to send a respondent to a particular survey, and attaching important information in a query string, such as the unique panelist ID (PID), unique session ID (MID) or respondent’s profile data. Our generating API entry links article has more detailed information on how to format your entry links.
Supplier Link Model
| Property | Type | Description |
|---|---|---|
| SupplierLinkTypeCode | string | Defines the type of buyer-supplier engagement and the respondent’s path in Cint Marketplace. |
| TrackingTypeCode | string | Defines how the Marketplace should communicate back to the supplier’s system at the end of a session. The options are: |
| NONE (Default and recommended, physically redirects the respondent back to the supplier system) | ||
| PIXEL (pixel tracking) | ||
| S2S (server to server postback) | ||
| DefaultLink | string | Tracking code or link used if none of the below apply. (Limit 2999 characters) |
| SuccessLink | string | Tracking code or link used after a completion. (Limit 2999 characters) |
| FailureLink | string | Tracking code or link used after a termination. (Limit 2999 characters) |
| OverQuotaLink | string | Tracking code or link used after an overquota. (Limit 2999 characters) |
| QualityTerminationLink | string | Tracking code or link used after a quality (security) termination. (Limit 2999 characters) |
| LiveLink | string | Live supplier-specific respondent entry link generated by Cint Marketplace. |
| TestLink | string | Test supplier-specific respondent entry link generated by Cint Marketplace. |
| CPI | double | Gross payout per complete. This value is in US dollars and is before any applicable commissions or fees. |
POST Create a Link
Definition
POST https://api.samplicio.us/Supply/v1/SupplierLinks/Create/{SurveyNumber}/{SupplierCode}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X POST --data '{"SupplierLinkTypeCode": "OWS", "TrackingTypeCode": "NONE"}' https://api.samplicio.us/Supply/v1/SupplierLinks/Create/{SurveyNumber}/{SupplierCode}
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Supply/v1/SupplierLinks/Create/{SurveyNumber}/{SupplierCode}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.path, initheader = {'Content-Type' =>'application/json'})
request.body = {SupplierLinkTypeCode:"OWS",TrackingTypeCode:"NONE"}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
supplierLink = http.request(request)
<?php
$curl = curl_init();
$params = '{"SupplierLinkTypeCode": "OWS","TrackingTypeCode": "NONE"}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Supply/v1/SupplierLinks/Create/{SurveyNumber}/{SupplierCode}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/Supply/v1/SupplierLinks/Create/{SurveyNumber}/{SupplierCode}'
params = {'SupplierLinkTypeCode':'OWS','TrackingTypeCode':'NONE'}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.post(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Supply/v1/SupplierLinks/Create/{SurveyNumber}/{SupplierCode}");
string args = @"{
""SupplierLinkTypeCode"":""OWS"",
""TrackingTypeCode"":""NONE""
}";
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "POST",
"hostname": "api.samplicio.us",
"port": 443,
"path": "/Supply/v1/SupplierLinks/Create/{SurveyNumber}/{SupplierCode}",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {
"SupplierLinkTypeCode":"OWS",
"TrackingTypeCode":"NONE"
};
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: CreateSupplierLinkFromModel successful."
],
"ResultCount": 1,
"SupplierLink": {
"SupplierLinkTypeCode": "OWS",
"TrackingTypeCode": "NONE",
"DefaultLink": "https:\/\/www.anon.com\/surveys?v=lucid&fs=1&uid=[%MID%]",
"SuccessLink": "https:\/\/www.anon.com\/surveys?v=lucid&fs=2&uid=[%MID%]&COST=[%COST%]",
"FailureLink": "https:\/\/www.anon.com\/surveys?v=lucid&fs=1&uid=[%MID%]",
"OverQuotaLink": "https:\/\/www.anon.com\/surveys?v=lucid&fs=1&uid=[%MID%]",
"QualityTerminationLink": "https:\/\/www.anon.com\/surveys?v=lucid&fs=1&uid=[%MID%]",
"LiveLink": "https:\/\/samplicio.us\/s\/default.aspx?SID=52c975a7-15fb-804d-9bf2-3d5d553aa7af&PID=",
"TestLink": "https:\/ \/samplicio.us\/s\/default.aspx?SID=a948gef7-3591-42c0-ce51-0e4jdf25582f&FIRID=MSDHONI7&SUMSTAT=1&PID=test",
"CPI": 100
}
}
Creates your supplier-specific respondent entry link for a survey. If custom redirects are not included in this payload, your default supplier redirects will be used.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SupplierLinkTypeCode | string | true | Defines the type of buyer-supplier engagement and the respondent’s path in Cint Marketplace. |
| TrackingTypeCode | string | true | Defines how the Marketplace should communicate back to the supplier’s system at the end of a session. The options are: |
| NONE (Default and recommended, physically redirects the respondent back to the supplier system) | |||
| PIXEL (pixel tracking) | |||
| S2S (server to server postback) | |||
| DefaultLink | string | false | Tracking code or link used if none of the below apply. (Limit 2999 characters) |
| SuccessLink | string | false | Tracking code or link used after a completion. (Limit 2999 characters) |
| FailureLink | string | false | Tracking code or link used after a termination. (Limit 2999 characters) |
| OverQuotaLink | string | false | Tracking code or link used after an overquota. (Limit 2999 characters) |
| QualityTerminationLink | string | false | Tracking code or link used after a quality (security) termination. (Limit 2999 characters) |
PUT Update a Link
Definition
PUT https://api.samplicio.us/Supply/v1/SupplierLinks/Update/{SurveyNumber}/{SupplierCode}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X PUT --data '{"SupplierLinkTypeCode": "OWS", "TrackingTypeCode": "NONE", "DefaultLink":"","SuccessLink":"","FailureLink":"","OverQuotaLink":"","QualityTerminationLink":""}' https://api.samplicio.us/Supply/v1/SupplierLinks/Update/{SurveyNumber}/{SupplierCode}
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Supply/v1/SupplierLinks/Update/{SurveyNumber}/{SupplierCode}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Put.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request['Authorization'] = YOUR_API_KEY_HERE
request.body = {SupplierLinkTypeCode:"OWS",TrackingTypeCode:"NONE",DefaultLink:"",SuccessLink:"",FailureLink:"",OverQuotaLink:"",QualityTerminationLink:""}.to_json
response = http.request(request)
<?php
$curl = curl_init();
$params = '{"SupplierLinkTypeCode": "OWS","TrackingTypeCode": "NONE","DefaultLink": "","SuccessLink": "","FailureLink": "","OverQuotaLink": "","QualityTerminationLink": ""}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Supply/v1/SupplierLinks/Update/{SurveyNumber}/{SupplierCode}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/Supply/v1/SupplierLinks/Update/{SurveyNumber}/{SupplierCode}'
params = {'SupplierLinkTypeCode':'OWS','TrackingTypeCode':'NONE','DefaultLink':'','SuccessLink':'','FailureLink':'','OverQuotaLink':'','QualityTerminationLink':''}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.put(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Supply/v1/SupplierLinks/Update/{SurveyNumber}/{SupplierCode}");
string args = @"{
""SupplierLinkTypeCode"":""OWS"",
""TrackingTypeCode"":""NONE"",
""DefaultLink"":"""",
""SuccessLink"":"""",
""FailureLink"":"""",
""OverQuotaLink"":"""",
""QualityTerminationLink"":""""
}";
request.Method = "PUT";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "PUT",
"hostname": "api.samplicio.us",
"port": 443,
"path": "/Supply/v1/SupplierLinks/Update/{SurveyNumber}/{SupplierCode}",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {
"SupplierLinkTypeCode":"OWS",
"TrackingTypeCode":"NONE",
"DefaultLink":"",
"SuccessLink":"",
"FailureLink":"",
"OverQuotaLink": "",
"QualityTerminationLink":""
};
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: UpdateSupplierLinkFromModel successful."
],
"ResultCount": 1,
"SupplierLink": {
"SupplierLinkTypeCode": "OWS",
"TrackingTypeCode": "NONE",
"DefaultLink": "",
"SuccessLink": "",
"FailureLink": "",
"OverQuotaLink": "",
"QualityTerminationLink": "",
"LiveLink": "https:\/\/samplicio.us\/s\/default.aspx?SID=52c795a7-15fh-454d-9ap2-3d5d803aa7af&PID=",
"TestLink": "https:\/\/samplicio.us\/s\/default.aspx?SID=a348dif7- 3491-42v0-be51-0e4fdf25582f&FIRID=MSDHQNI7&SUMSTAT=8&PID=test",
"CPI": 100
}
}
Update an existing entry link for a study.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SupplierLinkTypeCode | string | true | Defines the type of buyer-supplier engagement and the respondent’s path in Cint Marketplace. |
| TrackingTypeCode | string | true | Defines how Marketplace should communicate back to the supplier’s system at the end of a session. The options are: |
| NONE (Default and recommended, physically redirects the respondent back to the supplier system) | |||
| PIXEL (pixel tracking) | |||
| S2S (server to server postback) | |||
| DefaultLink | string | true | Tracking code or link used if none of the below apply. (Limit 2999 characters) |
| SuccessLink | string | true | Tracking code or link used after a completion. (Limit 2999 characters) |
| FailureLink | string | true | Tracking code or link used after a termination. (Limit 2999 characters) |
| OverQuotaLink | string | true | Tracking code or link used after an overquota. (Limit 2999 characters) |
| QualityTerminationLink | string | true | Tracking code or link used after a quality (security) termination. (Limit 2999 characters) |
GET Show a Link
Definition
GET https://api.samplicio.us/Supply/v1/SupplierLinks/BySurveyNumber/{SurveyNumber}/{SupplierCode}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Supply/v1/SupplierLinks/BySurveyNumber/{SurveyNumber}/{SupplierCode}
require 'net/http'
uri = URI('https://api.samplicio.us/Supply/v1/SupplierLinks/BySurveyNumber/{SurveyNumber}/{SupplierCode}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Supply/v1/SupplierLinks/BySurveyNumber/{SurveyNumber}/{SupplierCode}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Supply/v1/SupplierLinks/BySurveyNumber/{SurveyNumber}/{SupplierCode}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Supply/v1/SupplierLinks/BySurveyNumber/{SurveyNumber}/{SupplierCode}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Supply/v1/SupplierLinks/BySurveyNumber/{SurveyNumber}/{SupplierCode}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetSupplierLinkBySurveyNumberAndSupplierCode successful."
],
"ResultCount": 1,
"SupplierLink": {
"SupplierLinkTypeCode": "OWS",
"TrackingTypeCode": "NONE",
"DefaultLink": "https:\/\/www.anon.com\/surveys?v=1&fs=1&uid=[%MID%]",
"SuccessLink": "https:\/\/www.anon.com\/surveys?v=1&fs=2&uid=[%MID%]&COST=[%COST%]",
"FailureLink": "https:\/\/www.anon.com\/surveys?v=1&fs=1&uid=[%MID%]",
"OverQuotaLink": "https:\/\/www.anon.com\/surveys?v=1&fs=1&uid=[%MID%]",
"QualityTerminationLink": "https:\/\/www.anon.com\/surveys?v=1&fs=1&uid=[%MID%]",
"LiveLink": "https:\/\/samplicio.us\/s\/default.aspx?SID=52c975a7-15fb-804d-9bd2-3d5d553aa7af&PID=",
"TestLink": "https:\/ \/samplicio.us\/s\/default.aspx?SID=a948gef7-3591-42c0-ce51-0e4xdf25582f&FIRID=MSDHONI7&SUMSTAT=1&PID=test",
"CPI": 100
}
}
Returns link details for a survey.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
| SupplierCode | string | true | Unique code associated with supplier account. |
Inventory
The inventory allows Suppliers to see a list of Surveys that they have been allocated to or created an entry link. This endpoint is sparser in content than the Allocations and Offerwall endpoints but because of their reduced payload size per Survey, they have no limits on the number of Surveys that can be contained. This endpoint can be used in place of Allocations/All to return full Survey inventories without capacity limits.
SurveyInventory Model
| Property | Type | Description |
|---|---|---|
| SupplyAllocationSurveyIDs | List of Ints | List of Survey IDs for which the Supplier has allocation. |
GET List Allocated Surveys
Definition
GET https://api.samplicio.us/Supply/v1/Surveys/Inventory/{SupplierCode}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Supply/v1/Surveys/Inventory/{SupplierCode}
require 'net/http'
uri = URI('https://api.samplicio.us/Supply/v1/Surveys/Inventory/{SupplierCode}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
allocations = http.request(request)
<?php
$URL = "https://api.samplicio.us/Supply/v1/Surveys/Inventory/{SupplierCode}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Supply/v1/Surveys/Inventory/{SupplierCode}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Supply/v1/Surveys/Inventory/{SupplierCode}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Supply/v1/Surveys/Inventory/{SupplierCode}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"SupplyAllocationSurveyIDs": [
1, 2, 5, 7, 2323, 543
]
}
Returns a list of all live survey opportunities for which you have an allocation or entry link.
Demand Integration
Surveys
The Surveys resource allows the buyer to create new surveys, update existing surveys, and retrieve survey details in Marketplace.
Survey Model
| Property | Type | Description |
|---|---|---|
| AccountID | int | Unique account identifier. |
| SurveyStatusCode | string | Code associated with the current status of the survey. See List Global Definitions for a map of survey status codes. |
| SurveyPriority | int | An Audience-only variable to track the survey’s priority. |
| SurveyNumber | int | Unique number associated with the survey. |
| SurveyName | string | External name of the survey. This name may be exposed to respondents. This value is not unique across surveys. Maximum length of 128. |
| CountryLanguageID | int | Unique id associated with a Country-Language pair. |
| IndustryID | int | Industry associated with the survey’s topic. |
| StudyTypeID | int | Indicates the survey’s format and purpose (i.e. adhoc, recruit, etc). |
| ClientCPI | double | Revenue per complete used to calculate internal margin or savings. |
| QuotaCPI | double | Gross payout per complete. This value is before any applicable commissions or fees. Minimum value is 0.01 for live surveys. |
| ClientSurveyLiveURL | string | Link to client survey. Limit of URL length is 3000 characters. Must conform to RFC3987. See Guide for more detail. |
| TestRedirectURL | string | Link to client survey for testing purposes. All studies should include a working test link. Limit of URL length is 3000 characters. |
| IsActive | boolean | Indicates if a survey is active or inactive in Cint Marketplace database. We recommend keeping all surveys in an active status. |
| Quota | int | Total number of completes needed. |
| FulcrumExchangeAllocation | double | Percentage of total completes allocated only to Cint Marketplace. Must be between 0 and 100%. |
| FulcrumExchangeHedgeAccess | boolean | true gives the Marketplace access to any unallocated completes. |
| IsVerifyCallBack | boolean | true enables Verify CallBack security which requires the correct [%RSFN%] variable to be included on the “complete” client callback for verification. |
| UniquePID | boolean | true enables PID deduplication on a survey preventing a respondent with the same PID from entering more than once. Recommended on all surveys. |
| UniqueIPAddress | boolean | true enables IP deduplication on a survey preventing a respondent with the same IP address from entering more than once. Recommended on all surveys. |
| IsRelevantID | boolean | Non-Functional: Cint automatically protects against invalid respondent traffic. |
| IsDedupe | boolean | Non-Functional: Cint automatically protects against invalid respondent traffic. |
| IsGeoIP | boolean | Non-Functional: Cint automatically protects against invalid respondent traffic. |
| IsFraudProfile | boolean | Non-Functional: Cint automatically protects against invalid respondent traffic. |
| FraudProfileThreshold | int | Non-Functional: Cint automatically protects against invalid respondent traffic. |
| IsTrueSample | boolean | Non-Functional: Cint automatically protects against invalid respondent traffic. |
| QuotaCalculationTypeID | int | Sets the quota calculation method. Either 1 for ”Completes” (quotas determined by completes) or 2=”Prescreens” (quotas determined when leaving Cint Marketplace). |
| SurveyPlatformID | int | Sets the external platform ID. This should be hardcoded to 1 which represents “none”. |
| BidLengthOfInterview | int | Estimated time for a respondent to complete the survey excluding the Marketplace prescreener in minutes as provided by the buyer. |
| BusinessUnitID | int | Sets the account business unit. |
| SampleTypeID | int | Sets the type of sample the survey is open to (i.e. consumer, business-to-business, etc). See Sample Types |
| SurveySID | string | Unique hash value (GUID) associated with the survey. |
| BidIncidence | int | Estimated incidence rate for the survey. |
| CollectsPII | boolean | true indicates that the survey will collect PII. |
POST Create a Survey
Definition
POST https://api.samplicio.us/Demand/v1/Surveys/Create
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X POST --data '{"SurveyStatusCode": "01","SurveyPriority": 11,"SurveyName": "Example API Survey","CountryLanguageID": 9,"IndustryID": 30,"StudyTypeID": 1,"ClientCPI": 1,"QuotaCPI": 2,"ClientSurveyLiveURL": "https://www.surveyURL.com?rid=[%RID%]","TestRedirectURL": "https://www.surveyURL.com?rid=[%RID%]","IsActive": true,"Quota": 1000,"FulcrumExchangeAllocation": 0,"FulcrumExchangeHedgeAccess": true,"IsVerifyCallBack": true,"UniquePID": true,"UniqueIPAddress": true,"IsRelevantID": false,"IsDedupe": false,"IsGeoIP": false,"IsFraudProfile": false,"FraudProfileThreshold": 0,"IsTrueSample": false,"QuotaCalculationTypeID": 1,"SurveyPlatformID": 1,"BidLengthOfInterview": 10,"BusinessUnitID": 9,"SampleTypeID": 100,"BidIncidence": 20,"CollectsPII": null}' https://api.samplicio.us/Demand/v1/Surveys/Create
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Demand/v1/Surveys/Create')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Post.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {
"SurveyStatusCode"=> "01",
"SurveyPriority"=> 11,
"SurveyName"=> "Example API Survey",
"CountryLanguageID": 9,
"IndustryID"=> 30,
"StudyTypeID"=> 1,
"ClientCPI"=> 1,
"QuotaCPI"=> 2,
"ClientSurveyLiveURL"=> "https://www.surveyURL.com?rid=[%RID%]",
"TestRedirectURL"=> "https://www.surveyURL.com?rid=[%RID%]",
"IsActive"=> true,
"Quota"=> 1000,
"FulcrumExchangeAllocation"=> 0,
"FulcrumExchangeHedgeAccess"=> true,
"IsVerifyCallBack"=> true,
"UniquePID"=> true,
"UniqueIPAddress"=> true,
"IsRelevantID"=> false,
"IsDedupe"=> false,
"IsGeoIP"=> false,
"IsFraudProfile"=> false,
"FraudProfileThreshold"=> 0,
"IsTrueSample"=> false,
"QuotaCalculationTypeID"=> 1,
"SurveyPlatformID"=> 1,
"BidLengthOfInterview"=> 10,
"BusinessUnitID"=> 9,
"SampleTypeID"=> 100,
"BidIncidence"=> 20,
"CollectsPII"=> nil
}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{
"SurveyStatusCode": "01",
"SurveyPriority": 11,
"SurveyName": "Example API Survey",
"CountryLanguageID": 9,
"IndustryID": 30,
"StudyTypeID": 1,
"ClientCPI": 1,
"QuotaCPI": 2,
"ClientSurveyLiveURL": "https://www.surveyURL.com?rid=[%RID%]",
"TestRedirectURL": "https://www.surveyURL.com?rid=[%RID%]",
"IsActive": true,
"Quota": 1000,
"FulcrumExchangeAllocation": 0,
"FulcrumExchangeHedgeAccess": true,
"IsVerifyCallBack": true,
"UniquePID": true,
"UniqueIPAddress": true,
"IsRelevantID": false,
"IsDedupe": false,
"IsGeoIP": false,
"IsFraudProfile": false,
"FraudProfileThreshold": 0,
"IsTrueSample": false,
"QuotaCalculationTypeID": 1,
"SurveyPlatformID": 1,
"BidLengthOfInterview": 10,
"BusinessUnitID": 9,
"SampleTypeID": 100,
"BidIncidence": 20,
"CollectsPII": null
}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/Surveys/Create",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/Demand/v1/Surveys/Create'
params = {
"SurveyStatusCode": "01",
"SurveyPriority": 11,
"SurveyName": "Example API Survey",
"CountryLanguageID": 9,
"IndustryID": 30,
"StudyTypeID": 1,
"ClientCPI": 1,
"QuotaCPI": 2,
"ClientSurveyLiveURL": "https://www.surveyURL.com?rid=[%RID%]",
"TestRedirectURL": "https://www.surveyURL.com?rid=[%RID%]",
"IsActive": True,
"Quota": 1000,
"FulcrumExchangeAllocation": 0,
"FulcrumExchangeHedgeAccess": True,
"IsVerifyCallBack": True,
"UniquePID": True,
"UniqueIPAddress": True,
"IsRelevantID": False,
"IsDedupe": False,
"IsGeoIP": False,
"IsFraudProfile": False,
"FraudProfileThreshold": 0,
"IsTrueSample": False,
"QuotaCalculationTypeID": 1,
"SurveyPlatformID": 1,
"BidLengthOfInterview": 10,
"BusinessUnitID": 9,
"SampleTypeID": 100,
"BidIncidence": 20,
"CollectsPII": None
}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.post(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/Surveys/Create");
string args = @"{
""SurveyStatusCode"": ""01"",
""SurveyPriority"": 11,
""SurveyName"": ""Example API Survey"",
""CountryLanguageID"": 9,
""IndustryID"": 30,
""StudyTypeID"": 1,
""ClientCPI"": 1,
""QuotaCPI"": 2,
""ClientSurveyLiveURL"": ""https://www.surveyURL.com?rid=[%RID%]"",
""TestRedirectURL"": ""https://www.surveyURL.com?rid=[%RID%]"",
""IsActive"": true,
""Quota"": 1000,
""FulcrumExchangeAllocation"": 0,
""FulcrumExchangeHedgeAccess"": true,
""IsVerifyCallBack"": true,
""UniquePID"": true,
""UniqueIPAddress"": true,
""IsRelevantID"": false,
""IsDedupe"": false,
""IsGeoIP"": false,
""IsFraudProfile"": false,
""FraudProfileThreshold"": 0,
""IsTrueSample"": false,
""QuotaCalculationTypeID"": 1,
""SurveyPlatformID"": 1,
""BidLengthOfInterview"": 10,
""BusinessUnitID"": 9,
""SampleTypeID"": 100,
""BidIncidence"": 20,
""CollectsPII"": null
}";
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "POST",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/Surveys/Create",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {
"SurveyStatusCode": "01",
"SurveyPriority": 11,
"SurveyName": "Example API Survey",
"CountryLanguageID": 9,
"IndustryID": 30,
"StudyTypeID": 1,
"ClientCPI": 1,
"QuotaCPI": 2,
"ClientSurveyLiveURL": "https://www.surveyURL.com?rid=[%RID%]",
"TestRedirectURL": "https://www.surveyURL.com?rid=[%RID%]",
"IsActive": true,
"Quota": 1000,
"FulcrumExchangeAllocation": 0,
"FulcrumExchangeHedgeAccess": true,
"IsVerifyCallBack": true,
"UniquePID": true,
"UniqueIPAddress": true,
"IsRelevantID": false,
"IsDedupe": false,
"IsGeoIP": false,
"IsFraudProfile": false,
"FraudProfileThreshold": 0,
"IsTrueSample": false,
"QuotaCalculationTypeID": 1,
"SurveyPlatformID": 1,
"BidLengthOfInterview": 10,
"BusinessUnitID": 9,
"SampleTypeID": 100,
"BidIncidence": 20,
"CollectsPII": null
};
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: CreateSurveyFromModel successful."
],
"ResultCount": 1,
"Survey": {
"AccountID": 1,
"SurveyStatusCode": "01",
"SurveyPriority": 11,
"SurveyNumber": 12345,
"SurveyName": "Example API Survey",
"CountryLanguageID": 9,
"IndustryID": 30,
"StudyTypeID": 1,
"ClientCPI": 1,
"QuotaCPI": 2,
"ClientSurveyLiveURL": "https://www.surveyURL.com?rid=[%RID%]",
"TestRedirectURL": "https://www.surveyURL.com?rid=[%RID%]",
"IsActive": true,
"Quota": 1000,
"FulcrumExchangeAllocation": 0,
"FulcrumExchangeHedgeAccess": true,
"IsVerifyCallBack": true,
"UniquePID": true,
"UniqueIPAddress": true,
"IsRelevantID": false,
"IsDedupe": false,
"IsGeoIP": false,
"IsFraudProfile": false,
"FraudProfileThreshold": 0,
"IsTrueSample": false,
"QuotaCalculationTypeID": 1,
"SurveyPlatformID": 1,
"BidLengthOfInterview": 10,
"BusinessUnitID": 9,
"SampleTypeID": 100,
"SurveySID": "E75CDFE2-7221-4FAC-8561-78EE1B1D6ECF",
"BidIncidence": 20,
"CollectsPII": null
}
}
Creates a Marketplace survey.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| AccountID | int | false | Unique account identifier. |
| SurveyStatusCode | string | true | Code associated with the current status of the survey. See List Global Definitions for a map of survey status codes. |
| SurveyPriority | int | false | Survey priority from 1-11 (1 being the highest). Priority only applies to routed sample. |
| SurveyName | string | true | External name of the survey. This name may be exposed to respondents. This value is not unique across surveys. Maximum 128 characters. |
| CountryLanguageID | int | true | Unique id associated with a Country-Language pair. |
| IndustryID | int | false | Industry associated with the survey’s topic. |
| StudyTypeID | int | false | Indicates the survey’s format and purpose (i.e. adhoc, recruit, etc). |
| ClientCPI | double | false | Revenue per complete used to calculate internal margin or savings. |
| QuotaCPI | double | false | Gross payout per complete. This value is before any applicable commissions or fees. Minimum value is 0.01 for live surveys. |
| ClientSurveyLiveURL | string | true | Link to client survey. Limit of URL length is 3000 characters. Must conform to RFC3987. See Guide for more detail. |
| TestRedirectURL | string | false | Link to client survey for testing purposes. All studies should include a working test link. Limit of URL length is 3000 characters. |
| IsActive | boolean | false | Indicates if a survey is active or inactive in Cint Marketplace. We recommend keeping any surveys that have prescreens or completes in active status. |
| Quota | int | false | Total number of completes needed. |
| FulcrumExchangeAllocation | double | false | Percentage of total completes allocated only to Cint Marketplace. Must be between 0 and 100%. |
| FulcrumExchangeHedgeAccess | boolean | false | true gives the Marketplace access to any unallocated completes. |
| IsVerifyCallBack | boolean | false | true enables Verify CallBack security which requires the correct [%RSFN%] variable to be included on the “complete” client callback for verification. |
| UniquePID | boolean | false | true enables PID deduplication on a survey preventing a respondent with the same PID from entering more than once. Recommended on all surveys. |
| UniqueIPAddress | boolean | false | true enables IP deduplication on a survey preventing a respondent with the same IP address from entering more than once. Recommended on all surveys. |
| IsRelevantID | boolean | false | Non-Functional: Cint automatically protects against invalid respondent traffic. |
| IsDedupe | boolean | false | Non-Functional: Cint automatically protects against invalid respondent traffic. |
| IsGeoIP | boolean | false | Non-Functional: Cint automatically protects against invalid respondent traffic. |
| IsFraudProfile | boolean | false | Non-Functional: Cint automatically protects against invalid respondent traffic. |
| FraudProfileThreshold | int | false | Non-Functional: Cint automatically protects against invalid respondent traffic. |
| IsTrueSample | boolean | false | Non-Functional: Cint automatically protects against invalid respondent traffic. |
| QuotaCalculationTypeID | int | false | Sets the quota calculation method. Either 1 for ”Completes” (quotas determined by completes) or 2=”Prescreens” (quotas determined when leaving Cint Marketplace). |
| SurveyPlatformID | int | false | Sets the external platform ID. This should be hardcoded to 1 which represents “none”. |
| BidLengthOfInterview | int | false | Estimated time for a respondent to complete the survey excluding the Marketplace prescreener in minutes as provided by the buyer. |
| BusinessUnitID | int | false | Sets the account business unit. |
| SampleTypeID | int | false | Sets the type of sample the survey is open to (i.e. consumer, business-to-business, etc). See Sample Types. |
| BidIncidence | int | false | Estimated incidence rate for the survey. |
| CollectsPII | boolean | false | true indicates that the survey will collect PII. |
PUT Update a Survey
Definition
PUT https://api.samplicio.us/Demand/v1/Surveys/Update/{SurveyNumber}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X PUT --data '{"AccountID": 1,"SurveyStatusCode": "01","SurveyPriority": 11,"SurveyNumber": 12345,"SurveyName": "Example API Survey","CountryLanguageID": 9,"IndustryID": 30,"StudyTypeID": 1,"ClientCPI": 1,"QuotaCPI": 2,"ClientSurveyLiveURL": "https://www.surveyURL.com?rid=[%RID%]","TestRedirectURL": "https://www.surveyURL.com?rid=[%RID%]","IsActive": true,"Quota": 100,"FulcrumExchangeAllocation": 0,"FulcrumExchangeHedgeAccess": true,"IsVerifyCallBack": true,"UniquePID": true,"UniqueIPAddress": true,"IsRelevantID": false,"IsDedupe": false,"IsGeoIP": false,"IsFraudProfile": false,"FraudProfileThreshold": 0,"IsTrueSample": false,"QuotaCalculationTypeID": 1,"SurveyPlatformID": 1,"BidLengthOfInterview": 10,"BusinessUnitID": 9,"SampleTypeID": 100,"CollectsPII": null}' https://api.samplicio.us/Demand/v1/Surveys/Update/{SurveyNumber}
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Demand/v1/Surveys/Update/{SurveyNumber}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Put.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {
AccountID: 1,
SurveyStatusCode: "01",
SurveyPriority: 11,
SurveyNumber: 12345,
SurveyName: "Example API Survey",
CountryLanguageID: 9,
IndustryID: 30,
StudyTypeID: 1,
ClientCPI: 1,
QuotaCPI: 2,
ClientSurveyLiveURL: "https://www.surveyURL.com?rid=[%RID%]",
TestRedirectURL: "https://www.surveyURL.com?rid=[%RID%]",
IsActive: true,
Quota: 100,
FulcrumExchangeAllocation: 0,
FulcrumExchangeHedgeAccess: true,
IsVerifyCallBack: true,
UniquePID: true,
UniqueIPAddress: true,
IsRelevantID: false,
IsDedupe: false,
IsGeoIP: false,
IsFraudProfile: false,
FraudProfileThreshold: 0,
IsTrueSample: false,
QuotaCalculationTypeID: 1,
SurveyPlatformID: 1,
BidLengthOfInterview: 10,
BusinessUnitID: 9,
SampleTypeID: 100,
BidIncidence: 20,
CollectsPII: nil
}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{
"AccountID": 1,
"SurveyStatusCode": "01",
"SurveyPriority": 11,
"SurveyNumber": 12345,
"SurveyName": "Example API Survey",
"CountryLanguageID": 9,
"IndustryID": 30,
"StudyTypeID": 1,
"ClientCPI": 1,
"QuotaCPI": 2,
"ClientSurveyLiveURL": "https://www.surveyURL.com?rid=[%RID%]",
"TestRedirectURL": "https://www.surveyURL.com?rid=[%RID%]",
"IsActive": true,
"Quota": 100,
"FulcrumExchangeAllocation": 0,
"FulcrumExchangeHedgeAccess": true,
"IsVerifyCallBack": true,
"UniquePID": true,
"UniqueIPAddress": true,
"IsRelevantID": false,
"IsDedupe": false,
"IsGeoIP": false,
"IsFraudProfile": false,
"FraudProfileThreshold": 0,
"IsTrueSample": false,
"QuotaCalculationTypeID": 1,
"SurveyPlatformID": 1,
"BidLengthOfInterview": 10,
"BusinessUnitID": 9,
"SampleTypeID": 100,
"BidIncidence": 20,
"CollectsPII": null
}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/Surveys/Update/{SurveyNumber}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/Demand/v1/Surveys/Update/{SurveyNumber}'
params = {
"AccountID": 1,
"SurveyStatusCode": "01",
"SurveyPriority": 11,
"SurveyNumber": 12345,
"SurveyName": "Example API Survey",
"CountryLanguageID": 9,
"IndustryID": 30,
"StudyTypeID": 1,
"ClientCPI": 1,
"QuotaCPI": 2,
"ClientSurveyLiveURL": "https://www.surveyURL.com?rid=[%RID%]",
"TestRedirectURL": "https://www.surveyURL.com?rid=[%RID%]",
"IsActive": True,
"Quota": 100,
"FulcrumExchangeAllocation": 0,
"FulcrumExchangeHedgeAccess": True,
"IsVerifyCallBack": True,
"UniquePID": True,
"UniqueIPAddress": True,
"IsRelevantID": False,
"IsDedupe": False,
"IsGeoIP": False,
"IsFraudProfile": False,
"FraudProfileThreshold": 0,
"IsTrueSample": False,
"QuotaCalculationTypeID": 1,
"SurveyPlatformID": 1,
"BidLengthOfInterview": 10,
"BusinessUnitID": 9,
"SampleTypeID": 100,
"BidIncidence": 20,
"CollectsPII": None
}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.put(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/Surveys/Update/{SurveyNumber}");
string args = @"{
""AccountID"": 1,
""SurveyStatusCode"": ""01"",
""SurveyPriority"": 11,
""SurveyNumber"": 12345,
""SurveyName"": ""Example API Survey"",
""CountryLanguageID"": 9,
""IndustryID"": 30,
""StudyTypeID"": 1,
""ClientCPI"": 1,
""QuotaCPI"": 2,
""ClientSurveyLiveURL"": ""https://www.surveyURL.com?rid=[%RID%]"",
""TestRedirectURL"": ""https://www.surveyURL.com?rid=[%RID%]"",
""IsActive"": true,
""Quota"": 100,
""FulcrumExchangeAllocation"": 0,
""FulcrumExchangeHedgeAccess"": true,
""IsVerifyCallBack"": true,
""UniquePID"": true,
""UniqueIPAddress"": true,
""IsRelevantID"": false,
""IsDedupe"": false,
""IsGeoIP"": false,
""IsFraudProfile"": false,
""FraudProfileThreshold"": 0,
""IsTrueSample"": false,
""QuotaCalculationTypeID"": 1,
""SurveyPlatformID"": 1,
""BidLengthOfInterview"": 10,
""BusinessUnitID"": 9,
""SampleTypeID"": 100,
""BidIncidence"": 20,
""CollectsPII"": null
}";
request.Method = "PUT";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "PUT",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/Surveys/Update",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {
"AccountID": 1,
"SurveyStatusCode": "01",
"SurveyPriority": 11,
"SurveyNumber": 12345,
"SurveyName": "Example API Survey",
"CountryLanguageID": 9,
"IndustryID": 30,
"StudyTypeID": 1,
"ClientCPI": 1,
"QuotaCPI": 2,
"ClientSurveyLiveURL": "https://www.surveyURL.com?rid=[%RID%]",
"TestRedirectURL": "https://www.surveyURL.com?rid=[%RID%]",
"IsActive": true,
"Quota": 100,
"FulcrumExchangeAllocation": 0,
"FulcrumExchangeHedgeAccess": true,
"IsVerifyCallBack": true,
"UniquePID": true,
"UniqueIPAddress": true,
"IsRelevantID": false,
"IsDedupe": false,
"IsGeoIP": false,
"IsFraudProfile": false,
"FraudProfileThreshold": 0,
"IsTrueSample": false,
"QuotaCalculationTypeID": 1,
"SurveyPlatformID": 1,
"BidLengthOfInterview": 10,
"BusinessUnitID": 9,
"SampleTypeID": 100,
"BidIncidence": 20,
"CollectsPII": null
};
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: UpdateSurveyFromModel successful."
],
"ResultCount": 1,
"Survey": {
"AccountID": 1,
"SurveyStatusCode": "01",
"SurveyPriority": 11,
"SurveyNumber": 12345,
"SurveyName": "Example API Survey",
"CountryLanguageID": 9,
"IndustryID": 30,
"StudyTypeID": 1,
"ClientCPI": 1,
"QuotaCPI": 2,
"ClientSurveyLiveURL": "https://www.surveyURL.com?rid=[%RID%]",
"TestRedirectURL": "https://www.surveyURL.com?rid=[%RID%]",
"IsActive": true,
"Quota": 100,
"FulcrumExchangeAllocation": 0,
"FulcrumExchangeHedgeAccess": true,
"IsVerifyCallBack": true,
"UniquePID": true,
"UniqueIPAddress": true,
"IsRelevantID": false,
"IsDedupe": false,
"IsGeoIP": false,
"IsFraudProfile": false,
"FraudProfileThreshold": 0,
"IsTrueSample": false,
"QuotaCalculationTypeID": 1,
"SurveyPlatformID": 1,
"BidLengthOfInterview": 10,
"BusinessUnitID": 9,
"SampleTypeID": 100,
"SurveySID": "E75CDFE2-7221-4FAC-8561-78EE1B1D6ECF",
"BidIncidence": 20,
"CollectsPII": null
}
}
Update an existing Marketplace survey.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| AccountID | int | true | Unique account identifier. |
| SurveyStatusCode | string | true | Code associated with the current status of the survey. See List Global Definitions for a map of survey status codes. |
| SurveyPriority | int | true | Survey priority from 1-11 (1 being the highest). Priority only applies to routed sample. |
| SurveyName | string | true | External name of the survey. This name may be exposed to respondents. This value is not unique across surveys. |
| SurveyNumber | int | true | Unique number associated with the survey. |
| CountryLanguageID | int | true | Unique id associated with a Country-Language pair. |
| IndustryID | int | true | Industry associated with the survey’s topic. |
| StudyTypeID | int | true | Indicates the survey’s format and purpose (i.e. adhoc, recruit, etc). |
| ClientCPI | double | true | Revenue per complete used to calculate internal margin or savings. |
| QuotaCPI | double | true | Gross payout per complete. This value is before any applicable commissions or fees. |
| ClientSurveyLiveURL | string | true | Link to client survey. Limit of URL length is 3000 characters. Must conform to RFC3987. See Guide for more detail. |
| TestRedirectURL | string | true | Link to client survey for testing purposes. All studies should include a working test link. Limit of URL length is 3000 characters. |
| IsActive | boolean | true | Indicates if a survey is active or inactive in Marketplace database. |
| Quota | int | true | Total number of completes needed. |
| FulcrumExchangeAllocation | double | true | Percentage of total completes allocated only to Cint Marketplace. Must be between 0 and 100%. |
| FulcrumExchangeHedgeAccess | boolean | true | true gives the Marketplace access to any unallocated completes. |
| IsVerifyCallBack | boolean | true | true enables Verify CallBack security which requires the correct [%RSFN%] variable to be included on the “complete” client callback for verification. |
| UniquePID | boolean | true | true enables PID deduplication on a survey preventing a respondent with the same PID from entering more than once. Recommended on all surveys. |
| UniqueIPAddress | boolean | true | true enables IP deduplication on a survey preventing a respondent with the same IP address from entering more than once. Recommended on all surveys. |
| IsRelevantID | boolean | true | Non-Functional: Cint automatically protects against invalid respondent traffic. |
| IsDedupe | boolean | true | Non-Functional: Cint automatically protects against invalid respondent traffic. |
| IsGeoIP | boolean | true | Non-Functional: Cint automatically protects against invalid respondent traffic. |
| IsFraudProfile | boolean | true | Non-Functional: Cint automatically protects against invalid respondent traffic. |
| FraudProfileThreshold | int | true | Non-Functional: Cint automatically protects against invalid respondent traffic. |
| IsTrueSample | boolean | false | Non-Functional: Cint automatically protects against invalid respondent traffic. |
| QuotaCalculationTypeID | int | true | Sets the quota calculation method. Either 1 for ”Completes” (quotas counted using completes) or 2=”Prescreens” (quotas counted when leaving Marketplace for the survey). |
| SurveyPlatformID | int | true | Sets the external platform ID. This should be hardcoded to 1 which represents “none”. |
| BidLengthOfInterview | int | true | Estimated time for a respondent to complete the survey excluding the Marketplace prescreener in minutes as provided by the buyer. |
| BusinessUnitID | int | true | Sets the account business unit. |
| SampleTypeID | int | false | Sets the type of sample the survey is open to (i.e. consumer, business-to-business, etc). See Sample Types. |
| BidIncidence | int | false | Estimated incidence rate for the survey. |
| CollectsPII | boolean | false | true indicates that the survey will collect PII. |
GET Show a Survey
Definition
GET https://api.samplicio.us/Demand/v1/Surveys/BySurveyNumber/{SurveyNumber}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Demand/v1/Surveys/BySurveyNumber/{SurveyNumber}
require 'net/http'
uri = URI('https://api.samplicio.us/Demand/v1/Surveys/BySurveyNumber/{SurveyNumber}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Demand/v1/Surveys/BySurveyNumber/{SurveyNumber}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Demand/v1/Surveys/BySurveyNumber/{SurveyNumber}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/Surveys/BySurveyNumber/{SurveyNumber}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/Surveys/BySurveyNumber/{SurveyNumber}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetSurveyBySurveyNumber successful."
],
"ResultCount": 1,
"Survey": {
"AccountID": 1,
"SurveyStatusCode": "01",
"SurveyPriority": 11,
"SurveyNumber": 12345,
"SurveyName": "Example API Survey",
"CountryLanguageID": 9,
"IndustryID": 30,
"StudyTypeID": 1,
"ClientCPI": 1,
"QuotaCPI": 2,
"ClientSurveyLiveURL": "https://www.surveyURL.com?rid=[%RID%]",
"TestRedirectURL": "https://www.surveyURL.com?rid=[%RID%]",
"IsActive": true,
"Quota": 100,
"FulcrumExchangeAllocation": 0,
"FulcrumExchangeHedgeAccess": true,
"IsVerifyCallBack": true,
"UniquePID": true,
"UniqueIPAddress": true,
"IsRelevantID": true,
"IsDedupe": true,
"IsGeoIP": true,
"IsFraudProfile": true,
"FraudProfileThreshold": 11,
"IsTrueSample": false,
"QuotaCalculationTypeID": 1,
"SurveyPlatformID": 1,
"BidLengthOfInterview": 10,
"BusinessUnitID": 9,
"SampleTypeID": 100,
"SurveySID": "E75CDFE2-7221-4FAC-8561-78EE1B1D6ECF",
"BidIncidence": 20,
"CollectsPII": null
}
}
Returns the details of a specific Marketplace survey.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
GET List Surveys By Status
Definition
GET https://api.samplicio.us/Demand/v1/Surveys/BySurveyStatus/{SurveyStatus}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Demand/v1/Surveys/BySurveyStatus/{SurveyStatus}
require 'net/http'
uri = URI('https://api.samplicio.us/Demand/v1/Surveys/BySurveyStatus/{SurveyStatus}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Demand/v1/Surveys/BySurveyStatus/{SurveyStatus}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Demand/v1/Surveys/BySurveyStatus/{SurveyStatus}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/Surveys/BySurveyStatus/{SurveyStatus}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "https://api.samplicio.us/Demand/v1/Surveys/BySurveyStatus/{SurveyStatus}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetSurveysBySurveyStatus successful."
],
"ResultCount": 1,
"Surveys": [
{
"AccountID": 1,
"SurveyStatusCode": "01",
"SurveyPriority": 11,
"SurveyNumber": 12345,
"SurveyName": "Example API Survey",
"CountryLanguageID": 9,
"IndustryID": 30,
"StudyTypeID": 1,
"ClientCPI": 1,
"QuotaCPI": 2,
"ClientSurveyLiveURL": "https://www.surveyURL.com?rid=[%RID%]",
"TestRedirectURL": "https://www.surveyURL.com?rid=[%RID%]",
"IsActive": true,
"Quota": 100,
"FulcrumExchangeAllocation": 0,
"FulcrumExchangeHedgeAccess": true,
"IsVerifyCallBack": true,
"UniquePID": true,
"UniqueIPAddress": true,
"IsRelevantID": true,
"IsDedupe": true,
"IsGeoIP": false,
"IsFraudProfile": false,
"FraudProfileThreshold": 0,
"IsTrueSample": false,
"QuotaCalculationTypeID": 1,
"SurveyPlatformID": 1,
"BidLengthOfInterview": 10,
"BusinessUnitID": 9,
"SampleTypeID": 100,
"SurveySID": "E75CDFE2-7221-4FAC-8561-78EE1B1D6ECF",
"BidIncidence": 20,
"CollectsPII": null
}
]
}
Returns an index of all surveys by status such as Pending, Live, and Completed. This supports up to 100,000 items. In order to access more, please use our newest offering of v2-beta.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyStatus | int | true | Code associated with the current status of the survey. See List Global Definitions for a map, of survey status codes. |
POST Reconcile a Survey
Definition
POST https://api.samplicio.us/Demand/v1/Surveys/Reconcile/{SurveyNumber}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X POST --data '{"ResponseIDs" : ["9AF8B134-9E9F-E611-813Z-121EAE80731D", "1ADX57D4-9A9F-E711-813E-121DAC84731P"]}' https://api.samplicio.us/Demand/v1/Surveys/Reconcile/123456
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Demand/v1/Surveys/Reconcile/123456')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Post.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {ResponseIDs: [
"9AF8B134-9E9F-E611-813Z-121EAE80731D",
"1ADX57D4-9A9F-E711-813E-121DAC84731P"
]
}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{"ResponseIDs": [
"9AF8B134-9E9F-E611-813Z-121EAE80731D",
"1ADX57D4-9A9F-E711-813E-121DAC84731P"
]
}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/Surveys/Reconcile/123456",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/Demand/v1/Surveys/Reconcile/123456'
params = {"ResponseIDs": [
"9AF8B134-9E9F-E611-813Z-121EAE80731D",
"1ADX57D4-9A9F-E711-813E-121DAC84731P"
]
}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.post(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/Surveys/Reconcile/123456");
string args = @"{
""ResponseIDs"" : [
9AF8B134-9E9F-E611-813Z-121EAE80731D,
1ADX57D4-9A9F-E711-813E-121DAC84731P
]
}";
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "POST",
"hostname": "api.samplicio.us",
"port": 443,
"path": "/Demand/v1/Surveys/Reconcile/123456",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {"ResponseIDs": [
"9AF8B134-9E9F-E611-813Z-121EAE80731D",
"1ADX57D4-9A9F-E711-813E-121DAC84731P"
]
};
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"AccountCode": "AA",
"AccountType": 2,
"ApiAccount": "Anon",
"ApiAccountStatus": 1,
"ApiMessages": [
"API Message: Response initialized.",
"API Message: Reconciliation in-progress"
],
"ApiResult": 0,
"ApiResultCode": 0,
"ResultCount": 0,
"reconciliation": {
"ResponseIDs": [
"9AF8B134-9E9F-E611-813Z-121EAE80731D",
"1ADX57D4-9A9F-E711-813E-121DAC84731P"
]
}
}
Reconciles the list of respondents in this call with the list of completes in Marketplace. Any RID not included will be removed from Marketplace completes, and any valid RID included but not already registered as a complete on Marketplace will be changed to a complete. Reconciliation will not take place immediately, and can take some time to take effect. This call can be done multiple times, with the latest call overriding the previous reconciliations.
Please note that a survey must be in Complete Status in order to Reconcile. (SurveyStatusCode: 04)
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| ResponseIDs | array | true | A list of up to 14,000 RIDs that should be completes. Any RIDs omitted from this list will be changed to a terminate. |
Qualifications
The Qualifications resource allows the buyer to create new qualifications on an existing survey, update existing qualifications, and retrieve survey qualifications. These qualifications make up the Marketplace Prescreener and define the overall survey targeting criteria for suppliers.
Qualifications Model
| Property | Type | Description |
|---|---|---|
| Qualifications | array | Contains an array of elements described below. |
| Name | string | Name of the qualification. Maximum length of 3000. Visible as the “Description” field in the UI. |
| QuestionID | int | Unique number associated with the question. |
| LogicalOperator | string | Defines the logical operation applied to the conditions (OR, AND, or NOT). |
| NumberOfRequiredConditions | int | Indicates the number of conditions that must be selected by the respondent to proceed. |
| IsActive | boolean | false if the qualification has effectively been deleted. |
| PreCodes | array of strings | Qualification answer option identifiers. |
| MaxPunch | int | Defines the maximum number of options that can be selected by user. Should be set as n+1 for n is number of allowed responses. |
POST Create a Qualification
Definition
POST https://api.samplicio.us/Demand/v1/SurveyQualifications/Create/{SurveyNumber}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X POST --data '{"Name": "STANDARD_RELATIONSHIP","QuestionID": 632,"LogicalOperator": "OR","NumberOfRequiredConditions": 1,"IsActive": true,"PreCodes": ["1"], "Order": 7,"MaxPunch": 2}' https://api.samplicio.us/Demand/v1/SurveyQualifications/Create/{SurveyNumber}
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Demand/v1/SurveyQualifications/Create/{SurveyNumber}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Post.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {
Name: "STANDARD_RELATIONSHIP",
QuestionID: 632,
LogicalOperator: "OR",
NumberOfRequiredConditions: 1,
IsActive: true,
PreCodes: [
"1"
],
Order: 7,
MaxPunch: 2
}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{
"Name": "STANDARD_RELATIONSHIP",
"QuestionID": 632,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 1,
"IsActive": true,
"PreCodes": [
"1"
],
"Order": 7,
"MaxPunch": 2
}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/SurveyQualifications/Create/{SurveyNumber}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/Demand/v1/SurveyQualifications/Create/{SurveyNumber}'
params = {
"Name": "STANDARD_RELATIONSHIP",
"QuestionID": 632,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 1,
"IsActive": True,
"PreCodes": [
"1"
],
"Order": 7,
"MaxPunch": 2
}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.post(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SurveyQualifications/Create/{SurveyNumber}");
string args = @"{
""Name"": ""STANDARD_RELATIONSHIP"",
""QuestionID"": 632,
""LogicalOperator"": ""OR"",
""NumberOfRequiredConditions"": 1,
""IsActive"": true,
""PreCodes"": [""1""],
""Order"": 7,
""MaxPunch"": 2
}";
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "POST",
"hostname": "api.samplicio.us",
"port": 443,
"path": "/Demand/v1/SurveyQualifications/Create/{SurveyNumber}",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {
"Name": "STANDARD_RELATIONSHIP",
"QuestionID": 632,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 1,
"IsActive": true,
"PreCodes": [
"1"
],
"Order": 7,
"MaxPunch": 2
};
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: CreateSurveyQualificationFromModel successful."
],
"ResultCount": 7,
"Qualifications": [
{
"Name": "AGE",
"QuestionID": 42,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 1,
"IsActive": true,
"Order": 1,
"PreCodes": [
"18",
"19",
"20",
"21",
"22",
"23",
"24",
"25"
],
"MaxPunch": 2
},
{
"Name": "GENDER",
"QuestionID": 43,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 0,
"IsActive": true,
"Order": 3,
"PreCodes": [
"1",
"2"
],
"MaxPunch": 2
},
{
"Name": "ZIP",
"QuestionID": 45,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 0,
"IsActive": true,
"Order": 2,
"PreCodes": [],
"MaxPunch": 2
},
{
"Name": "HISPANIC",
"QuestionID": 47,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 1,
"IsActive": true,
"Order": 4,
"PreCodes": [
"1",
"10",
"11",
"12",
"13",
"14",
"2",
"3",
"4",
"5",
"6",
"7",
"8",
"9"
],
"MaxPunch": 2
},
{
"Name": "ETHNICITY",
"QuestionID": 113,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 1,
"IsActive": true,
"Order": 5,
"PreCodes": [
"1",
"2",
"3"
],
"MaxPunch": 2
},
{
"Name": "STANDARD_RELATIONSHIP",
"QuestionID": 632,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 1,
"IsActive": true,
"Order": 7,
"PreCodes": [
"1"
],
"MaxPunch": 2,
},
{
"Name": "STANDARD_HHI",
"QuestionID": 61076,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 0,
"IsActive": true,
"Order": 6,
"PreCodes": [
"1",
"10",
"11",
"12",
"13",
"14",
"15",
"16",
"17",
"18",
"19",
"2",
"20",
"21",
"22",
"23",
"24",
"25",
"26",
"27",
"3",
"4",
"5",
"6",
"7",
"8",
"9"
],
"MaxPunch": 2
}
]
}
Creates qualification and conditions for an existing Marketplace survey.
Arguments
| Property | Type | Description |
|---|---|---|
| SurveyNumber | int | Unique number associated with the survey. |
| Name | string | Name of the qualification. Maximum 32 characters. |
| QuestionID | int | Unique number associated with the question. |
| LogicalOperator | string | Defines the logical operation applied to the conditions. |
| NumberOfRequiredConditions | int | Indicates the number of conditions that must be selected by the respondent to proceed. |
| IsActive | boolean | Indicates if the qualification is active or inactive. Inactive effectively is the same as deleted. |
| PreCodes | array of strings | Qualification answer option identifiers. |
| Order | int | Determines qualification order in the prescreener. |
| MaxPunch | int | Defines the maximum number of options that can be selected by user. Should be set as n+1 for n is number of allowed responses. |
PUT Update a Qualification
Definition
PUT https://api.samplicio.us/Demand/v1/SurveyQualifications/Update/{SurveyNumber}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X PUT --data '{"Name": "STANDARD_RELATIONSHIP","QuestionID": 632,"LogicalOperator": "OR",NumberOfRequiredConditions": 1,"IsActive": true,"PreCodes": ["2"],"Order": 7,"MaxPunch": 2}' https://api.samplicio.us/Demand/v1/SurveyQualifications/Update/{SurveyNumber}
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Demand/v1/SurveyQualifications/Update/{SurveyNumber}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Put.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {
Name: "STANDARD_RELATIONSHIP",
QuestionID: 632,
LogicalOperator: "OR",
NumberOfRequiredConditions: 1,
IsActive: true,
PreCodes: [
"2"
],
Order: 7,
MaxPunch: 2
}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{
"Name": "STANDARD_RELATIONSHIP",
"QuestionID": 632,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 1,
"IsActive": true,
"PreCodes": [
"2"
],
"Order": 7,
"MaxPunch": 2
}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/SurveyQualifications/Update/{SurveyNumber}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/Demand/v1/SurveyQualifications/Update/{SurveyNumber}'
params = {
"Name": "STANDARD_RELATIONSHIP",
"QuestionID": 632,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 1,
"IsActive": True,
"PreCodes": [
"2"
],
"Order": 7,
"MaxPunch": 2
}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.put(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SurveyQualifications/Update/{SurveyNumber}");
string args = @"{
""Name"": ""STANDARD_RELATIONSHIP"",
""QuestionID"": 632,
""LogicalOperator"": ""OR"",
""NumberOfRequiredConditions"": 1,
""IsActive"": ~~true~~,
""PreCodes"": [""2""],
""Order"": 7,
""MaxPunch"": 2
}";
request.Method = "PUT";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "PUT",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SurveyQualifications/Update/{SurveyNumber}",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {
"Name": "STANDARD_RELATIONSHIP",
"QuestionID": 632,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 1,
"IsActive": true,
"PreCodes": [
"2"
],
"Order": 7,
"MaxPunch": 2
};
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: UpdateSurveyQualificationFromModel successful."
],
"ResultCount": 7,
"Qualifications": [
{
"Name": "AGE",
"QuestionID": 42,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 1,
"IsActive": true,
"Order": 1,
"PreCodes": [
"18",
"19",
"20",
"21",
"22",
"23",
"24",
"25"
],
"MaxPunch": 2
},
{
"Name": "GENDER",
"QuestionID": 43,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 0,
"IsActive": true,
"Order": 3,
"PreCodes": [
"1",
"2"
],
"MaxPunch": 2
},
{
"Name": "ZIP",
"QuestionID": 45,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 0,
"IsActive": true,
"Order": 2,
"PreCodes": [],
"MaxPunch": 2
},
{
"Name": "HISPANIC",
"QuestionID": 47,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 1,
"IsActive": true,
"Order": 4,
"PreCodes": [
"1",
"10",
"11",
"12",
"13",
"14",
"2",
"3",
"4",
"5",
"6",
"7",
"8",
"9"
],
"MaxPunch": 2
},
{
"Name": "ETHNICITY",
"QuestionID": 113,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 1,
"IsActive": true,
"Order": 5,
"PreCodes": [
"1",
"2",
"3"
],
"MaxPunch": 2
},
{
"Name": "STANDARD_RELATIONSHIP",
"QuestionID": 632,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 1,
"IsActive": true,
"Order": 7,
"PreCodes": [
"2"
],
"MaxPunch": 2
},
{
"Name": "STANDARD_HHI",
"QuestionID": 61076,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 0,
"IsActive": true,
"Order": 6,
"PreCodes": [
"1",
"10",
"11",
"12",
"13",
"14",
"15",
"16",
"17",
"18",
"19",
"2",
"20",
"21",
"22",
"23",
"24",
"25",
"26",
"27",
"3",
"4",
"5",
"6",
"7",
"8",
"9"
],
"MaxPunch": 2
}
]
}
Updates existing qualifications for a Marketplace survey.
Arguments
| Property | Type | Description |
|---|---|---|
| SurveyNumber | int | Unique number associated with the survey. |
| Name | string | Name of the qualification. Maximum 32 characters. |
| QuestionID | int | Unique number associated with the question. |
| LogicalOperator | string | Defines the logical operation applied to the conditions. |
| NumberOfRequiredConditions | int | Indicates the number of conditions that must be selected by the respondent to proceed. |
| IsActive | boolean | Indicates if the qualification is active or inactive. Inactive effectively is the same as deleted. |
| PreCodes | array of strings | Qualification answer option identifiers. |
| Order | int | Determines qualification order in the prescreener |
| MaxPunch | int | Defines the maximum number of options that can be selected by user. Should be set as n+1 for n is number of allowed responses. |
GET List Qualifications
Definition
GET https://api.samplicio.us/Demand/v1/SurveyQualifications/BySurveyNumber/{SurveyNumber}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Demand/v1/SurveyQualifications/BySurveyNumber/{SurveyNumber}
require 'net/http'
uri = URI('https://api.samplicio.us/Demand/v1/SurveyQualifications/BySurveyNumber/{SurveyNumber}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Demand/v1/SurveyQualifications/BySurveyNumber/{SurveyNumber}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Demand/v1/SurveyQualifications/BySurveyNumber/{SurveyNumber}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SurveyQualifications/BySurveyNumber/{SurveyNumber}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SurveyQualifications/BySurveyNumber/{SurveyNumber}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetSurveyQualificationsBySurveyNumber successful."
],
"ResultCount": 6,
"Qualifications": [
{
"Name": "AGE",
"QuestionID": 42,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 1,
"IsActive": true,
"Order": 1,
"PreCodes": [
"18",
"19",
"20",
"21",
"22",
"23",
"24",
"25"
],
"MaxPunch": 2
},
{
"Name": "GENDER",
"QuestionID": 43,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 0,
"IsActive": true,
"Order": 3,
"PreCodes": [
"1",
"2"
],
"MaxPunch": 2
},
{
"Name": "ZIP",
"QuestionID": 45,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 0,
"IsActive": true,
"Order": 2,
"PreCodes": [],
"MaxPunch": 2
},
{
"Name": "HISPANIC",
"QuestionID": 47,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 1,
"IsActive": true,
"Order": 4,
"PreCodes": [
"1",
"10",
"11",
"12",
"13",
"14",
"2",
"3",
"4",
"5",
"6",
"7",
"8",
"9"
],
"MaxPunch": 2
},
{
"Name": "ETHNICITY",
"QuestionID": 113,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 1,
"IsActive": true,
"Order": 5,
"PreCodes": [
"1",
"2",
"3"
],
"MaxPunch": 2
},
{
"Name": "STANDARD_HHI",
"QuestionID": 61076,
"LogicalOperator": "OR",
"NumberOfRequiredConditions": 0,
"IsActive": true,
"Order": 6,
"PreCodes": [
"1",
"10",
"11",
"12",
"13",
"14",
"15",
"16",
"17",
"18",
"19",
"2",
"20",
"21",
"22",
"23",
"24",
"25",
"26",
"27",
"3",
"4",
"5",
"6",
"7",
"8",
"9"
],
"MaxPunch": 2
}
]
}
Returns a list of all qualifications associated with a survey.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
Quotas
Quotas are used to specify how many respondents of a desired demographic type are allowed to either complete or enter the survey (depending if the survey is set to run on prescreens or run on completes). Quotas must be built from an existing qualification, so the question ID and all associated conditons must already be present as a qualification.
There is a limit of 1,000 Quotas per survey, which can be checked by using the “ResultCount” parameter on the List Quotas call. This is a combination of one Total Quota and up to 999 subquotas. The Total Quota is set using the “Quota” parameter in the Surveys model.
Quotas Model
| Property | Type | Description |
|---|---|---|
| SurveyQuotaID | int | Unique ID associated with the quota. |
| Name | string | Name associated with the quota. Maximum length of 64. |
| FieldTarget | int | Completes Goal (formerly called Field Target in the UI) associated with the quota. Only visible to the buyer. |
| Quota | int | Quota number for the specified quota. |
| Prescreens | int | Number of prescreens achieved. A prescreen is a respondent who enters the client survey. |
| Completes | int | Number of completes achieved. |
| IsActive | boolean | Indicates if the quotas is active or inactive. Should the quota be enforced on this project? |
| Conditions | array | Contains an array of Conditions models described below |
Conditions Model
Note that each quota may only contain up to 100,000 precodes spread across all its conditions.
| Property | Type | Description |
|---|---|---|
| QuestionID | int | QuestionID(s) that the quota is based upon |
| PreCodes | array of strings | Qualification answer option precodes defined by the API Standard |
POST Create a Quota
Definition
POST https://api.samplicio.us/Demand/v1/SurveyQuotas/Create/{SurveyNumber}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X POST --data '{"Name": "Quota Name", "Quota": 50, "IsActive":true, "Conditions":[{"QuestionID":42, "PreCodes": ["18","19","20","21","22"] }]}' https://api.samplicio.us/Demand/v1/SurveyQuotas/Create/{SurveyNumber}
require 'net/http'
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Demand/v1/SurveyQuotas/Create/{SurveyNumber}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Post.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {Name: "Quota Name", Quota: 50, IsActive:true, Conditions:[{QuestionID:42, PreCodes: ["18","19","20","21","22"] }]}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{"Name": "Quota Name", "Quota": 50, "IsActive":true, "Conditions":[{"QuestionID":42, "PreCodes": ["18","19","20","21","22"] }]}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/SurveyQuotas/Create/{SurveyNumber}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/Demand/v1/SurveyQuotas/Create/{SurveyNumber}'
params = {'Name': 'Quota Name', 'Quota': 50, 'IsActive': True, 'Conditions':[{'QuestionID':42, 'PreCodes': ['18','19','20','21','22'] }]}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.post(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SurveyQuotas/Create/{SurveyNumber}");
string args = @"{
""Name"": ""Quota Name"",
""Quota"": 50,
""IsActive"": true,
""Conditions"":[{
""QuestionID"":42,
""PreCodes"": [""18"",""19"",""20"",""21"",""22""]
}]
}";
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "POST",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SurveyQuotas/Create/{SurveyNumber}",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'}
};
var json = {
"Name": "Quota Name",
"Quota": 50,
"IsActive": true,
"Conditions":
[
{
"QuestionID": 42,
"PreCodes": [
"18",
"19",
"20",
"21",
"22",
]
}
]
};
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: CreateSurveyQuotaFromModel successful."
],
"ResultCount": 2,
"Quotas": [
{
"SurveyQuotaID": 0001100,
"Name": "Total",
"SurveyQuotaType": "Total",
"FieldTarget": 100,
"Quota": 100,
"Prescreens": 0,
"Completes": 0,
"IsActive": true,
"Conditions": null
},
{
"SurveyQuotaID": 1000110,
"Name": "Quota Name",
"SurveyQuotaType": "Client",
"FieldTarget": 50,
"Quota": 50,
"Prescreens": 0,
"Completes": 0,
"IsActive": true,
"Conditions": [
{
"QuestionID": 42,
"PreCodes": [
"18",
"19",
"20",
"21",
"22",
]
},
]
}
]
}
Creates Quota based on specified questionIDs.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
| Name | string | true | Name associated with the quota. Maximum 64 characters. |
| FieldTarget | int | true | Completes Goal (formerly called Field Target in the UI) associated with the quota. Only visible to the buyer. |
| Quota | int | true | Quota number for the specified quota. |
| IsActive | boolean | true | Should the quota be enforced on this project? |
| SurveyQuotaType | string | false | Indicates quota type (Client or Total). |
| Conditions | array | true | Indicates conditions associated with quota (by questionID and precodes). |
PUT Update a Quota
Definition
PUT https://api.samplicio.us/Demand/v1/SurveyQuotas/Update/{SurveyNumber}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X PUT --data '{"SurveyQuotaID": 1000110,"Name": "Quota Name", "FieldTarget":1000, "Quota": 50, "IsActive":true, "Conditions":[{"QuestionID":42, "PreCodes": ["18","19","20","21","22"] }]}' https://api.samplicio.us/Demand/v1/SurveyQuotas/Update/{SurveyNumber}
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Demand/v1/SurveyQuotas/Update/{SurveyNumber}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Put.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {SurveyQuotaID: 1000110, Name: "Quota Name", FieldTarget:1000, Quota: 50, IsActive:true, Conditions:[{QuestionID:42, PreCodes: [18, 19, 20, 21, 22] }]}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{"SurveyQuotaID": 1000110, "Name": "Quota Name", "FieldTarget":1000, "Quota": 50, "IsActive":true, "Conditions":[{"QuestionID":42, "PreCodes": ["18","19","20","21","22"] }]}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/SurveyQuotas/Update/{SurveyNumber}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/Demand/v1/SurveyQuotas/Update/{SurveyNumber}'
params = {'SurveyQuotaID': 1000110, 'Name': "Quota Name", 'FieldTarget':1000, 'Quota': 50, 'IsActive': True, 'Conditions':[{'QuestionID':42, 'PreCodes': ['18','19','20','21','22'] }]}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
updateQuotas = requests.put(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SurveyQuotas/Update/{SurveyNumber}");
string args = @"{
""SurveyQuotaID"": 1000110,
""Name"": ""Quota Name"",
""FieldTarget"":1000,
""Quota"": 50,
""IsActive"": true,
""Conditions"":[{
""QuestionID"":42,
""PreCodes"": [""18"",""19"",""20"",""21"",""22""]
}]
}";
request.Method = "PUT";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "PUT",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SurveyQuotas/Update/{SurveyNumber}",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {
"SurveyQuotaID": 0001100,
"Name": "Quota Name",
"FieldTarget": 50,
"Quota": 50,
"IsActive": true,
"Conditions": [
{
"QuestionID": 42,
"PreCodes": [
"18",
"19"
]
},
]
};
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: CreateSurveyQuotaFromModel successful."
],
"ResultCount": 2,
"Quotas": [
{
"SurveyQuotaID": 0001100,
"Name": "Total",
"SurveyQuotaType": "Total",
"FieldTarget": 100,
"Quota": 100,
"Prescreens": 0,
"Completes": 0,
"IsActive": true,
"Conditions": null
},
{
"SurveyQuotaID": 1000110,
"Name": "Quota Name",
"SurveyQuotaType": "Client",
"FieldTarget": 50,
"Quota": 50,
"Prescreens": 0,
"Completes": 0,
"IsActive": true,
"Conditions": [
{
"QuestionID": 42,
"PreCodes": [
"18",
"19",
"20",
"21",
"22",
]
},
]
}
]
}
Updates a quota’s size, conditions, and other parameters.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
| Name | string | true | Name associated with the quota. Maximum length of 64. |
| SurveyQuotaID | int | true | Unique ID associated with the quota. |
| FieldTarget | int | true | Completes Goal (formerly called Field Target in the UI) associated with the quota. Only visible to the buyer. |
| Quota | int | true | Quota number for the specified quota. |
| IsActive | boolean | true | Should the quota be enforced on this project? |
| SurveyQuotaType | string | false | Indicates quota type (Client or Total). |
| Conditions | array | true | Indicates conditions associated with quota (by questionID and precodes). |
GET List Quotas
Definition
GET https://api.samplicio.us/Demand/v1/SurveyQuotas/BySurveyNumber/{SurveyNumber}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Demand/v1/SurveyQuotas/BySurveyNumber/{SurveyNumber}
require 'net/http'
uri = URI('https://api.samplicio.us/Demand/v1/SurveyQuotas/BySurveyNumber/{SurveyNumber}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Demand/v1/SurveyQuotas/BySurveyNumber/{SurveyNumber}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Demand/v1/SurveyQuotas/BySurveyNumber/{SurveyNumber}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SurveyQuotas/BySurveyNumber/{SurveyNumber}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SurveyQuotas/BySurveyNumber/{SurveyNumber}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetSurveyQuotasBySurveyNumber successful."
],
"ResultCount": 2,
"Quotas": [
{
"SurveyQuotaID": 0001000,
"Name": "Total",
"SurveyQuotaType": "Total",
"FieldTarget": 100,
"Quota": 100,
"Prescreens": 0,
"Completes": 0,
"IsActive": true,
"Conditions": null
},
{
"SurveyQuotaID": 0101010,
"Name": "Age Quota",
"SurveyQuotaType": "Client",
"FieldTarget": 40,
"Quota": 40,
"Prescreens": 0,
"Completes": 0,
"IsActive": true,
"Conditions": [
{
"QuestionID": 42,
"PreCodes": [
"18",
"19",
"20",
"24",
"25"
]
}
]
}
Returns the list of quotas associated with the specified survey.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
Marketplace Allocation Templates
A Marketplace Allocation Template allows a buyer to quickly add a commonly used supply blend. The Marketplace Allocation Templates resource returns all Marketplace Allocation Templates associated with an existing account as well as apply an existing Marketplace Allocation Template to a survey. An Marketplace Allocation Template must first be created in the Marketplace UI.
Marketplace Allocation Templates Model
| Property | Type | Description |
|---|---|---|
| ID | int | ID associated with the Marketplace Allocation Template. |
| AccountID | int | Unique account identifier. |
| Name | string | Marketplace Allocation Template Name. Maximum length of 255. |
| ExchangeAllocationPercentage | double | Percentage of total completes allocated to the Cint Marketplace, expressed as a decimal from 0 to 1. |
| ExchangeIsHedgeAccess | boolean | true gives the Cint Marketplace access to any unallocated completes. true is recommended when using Cint Marketplace. |
| IsGlobalTemplate | boolean | Should always return false indicating the template is only available to the buyers account. |
Supplier Groups Model
| Property | Type | Description |
|---|---|---|
| ID | int | ID associated with the Marketplace Allocation Template. |
| Name | string | Marketplace Allocation Template Name. Maximum length of 255. |
| SupplierGroupDisplayTypeID | int | Indicates if the group is the “blocked” group or not. 1 = unblocked. 2 = blocked. |
| Completes | int | Number of completes gained by the group. |
| Screens | int | Number of prescreens gained by the group. |
| AllocationPercentage | double | Percentage of total completes allocated only to the Marketplace group, expressed as a decimal from 0 to 1. |
| IsHedgeAccess | boolean | true gives the Marketplace group access to any unallocated completes. |
| CPI | int | Will return null as CPI can’t be set via an Marketplace Allocation Template. |
| Suppliers | array | Contains array of elements described below. |
Suppliers Model
| Property | Type | Description |
|---|---|---|
| SupplierID | int | ID associated with the supplier account. |
| Completes | int | Number of completes gained by the supplier. |
| Screens | string | Number of prescreens gained by the supplier. |
GET List Marketplace Allocation Templates
Definition
GET https://api.samplicio.us/Demand/v1/ExchangeTemplates/GetAll
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Demand/v1/ExchangeTemplates/GetAll
require 'net/http'
uri = URI('https://api.samplicio.us/Demand/v1/ExchangeTemplates/GetAll')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Demand/v1/ExchangeTemplates/GetAll";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Demand/v1/ExchangeTemplates/GetAll'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/ExchangeTemplates/GetAll");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/ExchangeTemplates/GetAll",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetAllExchangeTemplates successful."
],
"ResultCount": 2,
"ExchangeTemplates": [
{
"ID": 1,
"AccountID": 1,
"Name": "ExchangeTemplate1",
"ExchangeAllocationPercentage": 0,
"ExchangeIsHedgeAccess": true,
"IsGlobalTemplate": true
},
{
"ID": 2,
"AccountID": 1,
"Name": "ExchangeTemplate2",
"ExchangeAllocationPercentage": 0.4,
"ExchangeIsHedgeAccess": true,
"IsGlobalTemplate": false
}
]
}
Returns all Marketplace Templates associated with an existing account.
POST Apply a Marketplace Template
Definition
POST https://api.samplicio.us/Demand/v1/ExchangeTemplates/ApplyToSurvey/{SurveyNumber}/{ExchangeTemplateID}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X POST https://api.samplicio.us/Demand/v1/ExchangeTemplates/ApplyToSurvey/{SurveyNumber}/{ExchangeTemplateID}
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Demand/v1/ExchangeTemplates/ApplyToSurvey/{SurveyNumber}/{ExchangeTemplateID}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Post.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/ExchangeTemplates/ApplyToSurvey/{SurveyNumber}/{ExchangeTemplateID}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/Demand/v1/ExchangeTemplates/ApplyToSurvey/{SurveyNumber}/{ExchangeTemplateID}'
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.post(url, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/ExchangeTemplates/ApplyToSurvey/{SurveyNumber}/{ExchangeTemplateID}");
request.Method = "POST";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "POST",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/ExchangeTemplates/ApplyToSurvey/{SurveyNumber}/{ExchangeTemplateID}",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: ApplyExchangeTemplateToSurvey successful."
],
"ResultCount": 1,
"SupplierGroups": [
{
"ID": 1234,
"Name": "Group 1",
"SupplierGroupDisplayTypeID": 1,
"Completes": 0,
"Screens": 0,
"AllocationPercentage": 0,
"IsHedgeAccess": false,
"CPI": null,
"Suppliers": [
{
"SupplierID": 1,
"Completes": 0,
"Screens": 0
},
{
"SupplierID": 2,
"Completes": 0,
"Screens": 0
},
{
"SupplierID": 3,
"Completes": 0,
"Screens": 0
},
{
"SupplierID": 4,
"Completes": 0,
"Screens": 0
}
]
}
]
}
Applies the specified Marketplace Allocation Template to an existing survey.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
| ID | int | true | ID associated with the Marketplace Allocation Template. |
Supplier Groups
Supplier Groups allow buyers to allocate completes to a specific group of suppliers. Supplier Groups contain a hedge property, which allows suppliers from Supplier Groups to also have access to unallocated completes.
POST Create a Group
Definition
POST https://api.samplicio.us/Demand/v1/SupplierGroups/CreateWithSuppliers/{SurveyNumber}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X POST --data '{"SurveyNumber": 101100,"Name":"Top Supplier Group", "AllocationPercentage": 0.10,"IsHedgeAccess": true, "Suppliers": [{"SupplierCode":"0001"}]}' https://api.samplicio.us/Demand/v1/SupplierGroups/CreateWithSuppliers/{SurveyNumber}
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Demand/v1/SupplierGroups/CreateWithSuppliers/{SurveyNumber}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(FullUriPath, initheader = {'Content-Type' => 'application/json'})
request.body = {SurveyNumber: 101100, Name:"Top Supplier Group", AllocationPercentage: 0.10, IsHedgeAccess: true, "Suppliers": [{"SupplierCode":"0001"}]}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{"SurveyNumber": 101100, "Name":"Top Supplier Group", "AllocationPercentage": 0.10, "IsHedgeAccess": true, "Suppliers": [{"SupplierCode":"0001"}]}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/SupplierGroups/CreateWithSuppliers/{SurveyNumber}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests
url = 'https://api.samplicio.us/Demand/v1/SupplierGroups/CreateWithSuppliers/{SurveyNumber}'
params = {'SurveyNumber': 101100, 'Name':'Top Supplier Group', 'AllocationPercentage': 0.10, 'IsHedgeAccess': True, 'Suppliers': [{'SupplierCode':'1010'}]}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.post(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SupplierGroups/CreateWithSuppliers/{SurveyNumber}");
string args = @"{
""SurveyNumber"": 101100,
""Name"":""Top Supplier Group"",
""AllocationPercentage"": 0.10,
""IsHedgeAccess"": true,
""Suppliers"": [{
""SupplierCode"":""1010""
}]
}";
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "POST",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SupplierGroups/CreateWithSuppliers/{SurveyNumber}",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {"SurveyNumber": 101100,
"Name":"Top Supplier Group",
"AllocationPercentage": 0.10,
"IsHedgeAccess": true,
"Suppliers": [
{
"SupplierCode":"1010"
}
]
}
var params = JSON.stringify(json);
var request = https.request(options, function (createGroup) {
var chunks = [];
createGroup.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: CreateSupplierGroupFromModel successful."
],
"ResultCount": 1,
"SupplierGroup": {
"ID": 201967,
"Name": "Top Supplier Group",
"Completes": 0,
"Screens": 0,
"AllocationPercentage": 0.1,
"CPI": null,
"IsHedgeAccess": true,
"Suppliers": [
{
"SupplierCode": "1010",
"Completes": 0,
"Screens": 0
}
]
}
}
Creates a group with specific suppliers and allocation for that group.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
| Name | string | true | Supplier Group name. Maximum 64 characters. |
| AllocationPercentage | double | true | Group reserved allocation, expressed as a decimal percentage from 0 to 1. |
| IsHedgeAccess | boolean | true | Access to unallocated completes on Cint Marketplace. |
| Suppliers | array | true | An array of all supplier codes (strings). |
| CPI | double | false | The payout per complete for the group (defaults to survey QCPI). |
POST Create an Empty Group
Definition
POST https://api.samplicio.us/Demand/v1/SupplierGroups/Create/{SurveyNumber}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X POST --data '{"SurveyNumber": 101100,"Name":"Top Supplier Group", "AllocationPercentage": 0.10,"IsHedgeAccess": true}' https://api.samplicio.us/Demand/v1/SupplierGroups/Create/{SurveyNumber}
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Demand/v1/SupplierGroups/Create/{SurveyNumber}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Post.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {SurveyNumber: 101100, Name:"Top Supplier Group", AllocationPercentage: 0.10, IsHedgeAccess: true}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{"SurveyNumber": 101100,"Name":"Top Supplier Group", "AllocationPercentage": 0.10,"IsHedgeAccess": true}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/SupplierGroups/Create/{SurveyNumber}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/Demand/v1/SupplierGroups/Create/{SurveyNumber}'
params = {'SurveyNumber': 101100,'Name':'Top Supplier Group', 'AllocationPercentage': 0.10,'IsHedgeAccess': True}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.post(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SupplierGroups/Create/{SurveyNumber}");
string args = @"{
""SurveyNumber"": 101100,
""Name"":""Top Supplier Group"",
""AllocationPercentage"": 0.10,
""IsHedgeAccess"": true
}";
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "POST",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SupplierGroups/Create/{SurveyNumber}",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {"SurveyNumber": 101100,
"Name":"Top Supplier Group",
"AllocationPercentage": 0.10,
"IsHedgeAccess": true,
}
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: CreateSupplierGroupFromModel successful."
],
"ResultCount": 1,
"SupplierGroup": {
"ID": 000110,
"Name": "Top Supplier Group",
"Completes": 0,
"Screens": 0,
"AllocationPercentage": 0,
"CPI": null,
"IsHedgeAccess": true,
"Suppliers": []
}
}
Creates an empty supplier group with a specific allocation and name.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
| Name | string | true | Supplier Group name. Maximum 64 characters. |
| AllocationPercentage | double | true | Group reserved allocation, expressed as a decimal percentage from 0 to 1. |
| IsHedgeAccess | boolean | false | Access to unallocated completes on Cint Marketplace. |
| CPI | double | false | The payout per complete for the group (defaults to survey QCPI). |
PUT Update a Group
Definition
PUT https://api.samplicio.us/Demand/v1/SupplierGroups/Update/{SurveyNumber}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X PUT --data '{"ID": 1234, "SurveyNumber": 001100,"Name":"Top Supplier Group", "AllocationPercentage": 0.10,"IsHedgeAccess": true}' https://api.samplicio.us/Demand/v1/SupplierGroups/Update/{SurveyNumber}
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Demand/v1/SupplierGroups/Update/{SurveyNumber}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Put.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {ID: 1234, SurveyNumber: 101100, Name:"Top Supplier Group",AllocationPercentage: 0.10, IsHedgeAccess: true}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{"ID": 1234,"SurveyNumber": 101100,"Name":"Top Supplier Group", "AllocationPercentage": 0.10,"IsHedgeAccess": true}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/SupplierGroups/Update/{SurveyNumber}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/Demand/v1/SupplierGroups/Update/{SurveyNumber}'
params = {'ID': 1234,'SurveyNumber': 101100,'Name':'Top Supplier Group', 'AllocationPercentage': 0.10,'IsHedgeAccess': True}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.put(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SupplierGroups/Update/{SurveyNumber}");
string args = @"{
""ID"": 1234,
""SurveyNumber"": 101100,
""Name"":""Top Supplier Group"",
""AllocationPercentage"": 0.10,
""IsHedgeAccess"": true
}";
request.Method = "PUT";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "PUT",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SupplierGroups/Create/{SurveyNumber}",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {"ID": 1234,
"SurveyNumber": 101100,
"Name":"Top Supplier Group",
"AllocationPercentage": 0.10,
"IsHedgeAccess": true,
}
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: UpdateSupplierGroupFromModel successful."
],
"ResultCount": 1,
"SupplierGroup": {
"ID": 000001,
"Name": "Top Supplier Group",
"Completes": 0,
"Screens": 0,
"AllocationPercentage": 0.15,
"CPI": null,
"IsHedgeAccess": true,
"Suppliers": []
}
}
Updates a supplier group with the specified values.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| ID | int | true | Unique ID associated with the group. |
| SurveyNumber | int | true | Unique number associated with the survey. |
| Name | string | true | Supplier Group name. Maximum 64 characters. |
| AllocationPercentage | double | true | Group reserved allocation, expressed as a decimal percentage from 0 to 1. |
| IsHedgeAccess | boolean | true | Access to unallocated completes on Cint Marketplace. |
| CPI | double | false | The payout per complete for the group (defaults to survey QCPI). |
DELETE Delete a Group
Definition
DELETE https://api.samplicio.us/Demand/v1/SupplierGroups/Delete/{SurveyNumber}/{SupplierGroupID}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" -X DELETE https://api.samplicio.us/Demand/v1/SupplierGroups/Delete/{SurveyNumber}/{SupplierGroupID}
require 'net/http'
uri = URI('https://api.samplicio.us/Demand/v1/SupplierGroups/Delete/{SurveyNumber}/{SupplierGroupID}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/SupplierGroups/Delete/{SurveyNumber}/{SupplierGroupID}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_POSTFIELDS => "",
));
curl_exec($curl);
curl_close($curl);
?>
import requests
url = 'https://api.samplicio.us/Demand/v1/SupplierGroups/Delete/{SurveyNumber}/{SupplierGroupID}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.delete(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SupplierGroups/Delete/{SurveyNumber}/{SupplierGroupID}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
request.Method = "DELETE";
request.GetResponse();
const https = require('https');
var options = {
"method": "DELETE",
"hostname": "api.samplicio.us",
"port": 443,
"path": "/Demand/v1/SupplierGroups/Delete/{SurveyNumber}/{SupplierGroupID}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options);
request.end();
Deletes the specified supplier group.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
| SupplierGroupID | int | true | Unique ID for Supplier Group. |
POST Add to a Group
Definition
POST https://api.samplicio.us/Demand/v1/SupplierGroups/AddSuppliersToGroup/{SurveyNumber}/{SupplierGroupID}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X POST --data '{"SupplierCode":"0010"}' https://api.samplicio.us/Demand/v1/SupplierGroups/AddSuppliersToGroup/{SurveyNumber}/{SupplierGroupID}
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Demand/v1/SupplierGroups/AddSuppliersToGroup/{SurveyNumber}/{SupplierGroupID}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Post.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {SupplierCode: 1010}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{"SupplierCode": 1010}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/SupplierGroups/AddSuppliersToGroup/{SurveyNumber}/{SupplierGroupID}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/Demand/v1/SupplierGroups/AddSuppliersToGroup/{SurveyNumber}/{SupplierGroupID}'
params = {'SupplierCode': 1010}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.post(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SupplierGroups/AddSuppliersToGroup/{SurveyNumber}/{SupplierGroupID}");
string args = @"{""SupplierCode"": 1010}";
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "POST",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SupplierGroups/AddSuppliersToGroup/{SurveyNumber}/{SupplierGroupID}",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {"SupplierCode": 1010}
var params = JSON.stringify(json);
var request = https.request(options, function (createGroupEmpty) {
var chunks = [];
createGroupEmpty.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: AddSupplierGroupSuppliersToSupplierGroup successful."
],
"ResultCount": 1,
"SupplierGroup": {
"ID": 201967,
"Name": "Top Supplier Group",
"Completes": 0,
"Screens": 0,
"AllocationPercentage": 0.1,
"CPI": null,
"IsHedgeAccess": true,
"Suppliers": [
{
"SupplierCode": "1010",
"Completes": 0,
"Screens": 0
},
]
}
}
Adds suppliers to the specified supplier group.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
| SupplierGroupID | int | true | Unique ID for Supplier Group. |
GET Show a Group
Definition
GET https://api.samplicio.us/Demand/v1/SupplierGroups/BySurveyNumber/{SurveyNumber}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Demand/v1/SupplierGroups/BySurveyNumber/{SurveyNumber}
require 'net/http'
uri = URI('https://api.samplicio.us/Demand/v1/SupplierGroups/BySurveyNumber/{SurveyNumber}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Demand/v1/SupplierGroups/BySurveyNumber/{SurveyNumber}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Demand/v1/SupplierGroups/BySurveyNumber/{SurveyNumber}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SupplierGroups/BySurveyNumber/{SurveyNumber}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SupplierGroups/BySurveyNumber/{SurveyNumber}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetAllWithSuppliersBySurveyNumber successful."
],
"ResultCount": 2,
"SupplierGroups": [
{
"ID": 001100,
"Name": "Top Supplier Group",
"Completes": 0,
"Screens": 0,
"AllocationPercentage": 0.1,
"CPI": null,
"IsHedgeAccess": true,
"Suppliers": [
{
"SupplierCode": "1010",
"Completes": 0,
"Screens": 0
}
]
},
{
"ID": 001001,
"Name": "The Gremlins",
"Completes": 0,
"Screens": 0,
"AllocationPercentage": 0.15,
"CPI": null,
"IsHedgeAccess": true,
"Suppliers": [
{
"SupplierCode": "1010",
"Completes": 0,
"Screens": 0
}
]
}
]
}
Returns the supplier groups for the survey specified.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
PUT Remove from a Group
Definition
PUT https://api.samplicio.us/Demand/v1/SupplierGroups/RemoveSuppliersFromGroup/{SurveyNumber}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X PUT --data '{"SupplierCode": "1010"}' https://api.samplicio.us/Demand/v1/SupplierGroups/RemoveSuppliersFromGroup/{SurveyNumber}
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Demand/v1/SupplierGroups/RemoveSuppliersFromGroup/{SurveyNumber}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Put.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {SupplierCode: '1010'}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{"SupplierLinkTypeCode": "OWS","TrackingTypeCode": "NONE","DefaultLink": "","SuccessLink": "","FailureLink": "","OverQuotaLink": "","QualityTerminationLink": ""}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/SupplierGroups/RemoveSuppliersFromGroup/{SurveyNumber}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/Demand/v1/SupplierGroups/RemoveSuppliersFromGroup/{SurveyNumber}'
params = {'SupplierCode': '1010'}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.put(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SupplierGroups/RemoveSuppliersFromGroup/{SurveyNumber}");
string args = @"{""SupplierCode"": 1010}";
request.Method = "PUT";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "PUT",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SupplierGroups/RemoveSuppliersFromGroup/{SurveyNumber}",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {
"SupplierCode": "1010",
};
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: RemoveSupplierGroupSuppliersFromSupplierGroups successful."
],
"ResultCount": 0,
"SupplierGroup": {
"ID": null,
"Name": null,
"Completes": null,
"Screens": null,
"AllocationPercentage": null,
"CPI": null,
"IsHedgeAccess": null,
"Suppliers": null
}
}
Removes specified suppliers from their supplier group.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
| SupplierGroupID | int | true | Unique ID for Supplier Group. |
Non-Marketplace Allocations
Non-Marketplace Allocations allow you to add a specific supplier to your survey. These allocations are separate from the Cint Marketplace and are sometimes referred to as Services. This resource allows you to create, update, delete, and retrieve a supplier allocation. You can also specify a TCPI (targeted CPI) and allocate a desired number of completes to each supplier.
Supplier Allocations Model
| Property | Type | Description |
|---|---|---|
| SupplierCode | int | Unique code associated with a supplier account. |
| AllocationPercentage | double | Percentage of total completes allocated to supplier, expressed as a decimal from 0 to 1. |
| TCPI | double | Gross payout per targeted complete. |
| HedgeAccess | boolean | Enables or disables hedge access for the supplier. |
| BlockRouterTraffic | boolean | Enables or disables router traffic for the supplier. |
| SupplierSurveyID | string | Survey supplier ID (SSID). |
| Prescreens | int | Number of prescreens achieved by the supplier. A prescreen is a respondent who enters the client survey. |
| Completes | int | Number of completes achieved by the supplier. |
| AllocationRemaining | int | Number of completes allocated only to the supplier. |
| HedgeRemaining | int | Number of unallocated completes available to any suppliers with access to hedge. |
| TotalRemaining | int | Total number of completes available to the supplier (aggregate of allocation and hedge remaining |
| Target | array | Contains an array of elements described below |
Target Model
| Property | Type | Description |
|---|---|---|
| SupplierLinkTypeCode | string | Defines the type of buyer-supplier engagement and the respondent’s path in Cint Marketplace. See List Global Definitions for a map of supplier link types. |
| TrackingTypeCode | string | Defines how Marketplace should communicate back to the supplier’s system at the end of a session. The options are: |
| NONE (Default and recommended, physically redirects the respondent back to the supplier system) | ||
| PIXEL (pixel tracking) | ||
| S2S (server to server postback) | ||
| DefaultLink | string | Tracking code or link used if none of the below apply. This will typically be the same as the FailureLink |
| SuccessLink | string | Tracking code or link used after a completion. |
| FailureLink | string | Tracking code or link used after a termination. |
| OverQuotaLink | string | Tracking code or link used after an overquota. |
| QualityTerminationLink | string | Tracking code or link used after a quality (security) termination. |
| LiveLink | string | Live supplier-specific respondent entry link generated by Cint Marketplace. |
| TestLink | string | Test supplier-specific respondent entry link generated by Cint Marketplace. |
GET Show Allocations
Definition
GET https://api.samplicio.us/Demand/v1/SupplierAllocations/BySurveyNumber/{SurveyNumber}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Demand/v1/SupplierAllocations/BySurveyNumber/{SurveyNumber}
require 'net/http'
uri = URI('https://api.samplicio.us/Demand/v1/SupplierAllocations/BySurveyNumber/{SurveyNumber}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Demand/v1/SupplierAllocations/BySurveyNumber/{SurveyNumber}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Demand/v1/SupplierAllocations/BySurveyNumber/{SurveyNumber}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SupplierAllocations/BySurveyNumber/{SurveyNumber}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SupplierAllocations/BySurveyNumber/{SurveyNumber}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 1,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetAllSupplierAllocationsBySurveyNumber successful."
],
"ResultCount": 1,
"SupplierAllocations": [
{
"SupplierCode": "1010",
"AllocationPercentage": 0,
"TCPI": 11,
"HedgeAccess": true,
"BlockRouterTraffic": false,
"SupplierSurveyID": null,
"Prescreens": 183,
"Completes": 4,
"AllocationRemaining": 0,
"HedgeRemaining": 695,
"TotalRemaining": 695,
"Target": null
}
]
}
Returns the supplier allocations for the survey specified.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
POST Create an Allocation
Definition
POST https://api.samplicio.us/Demand/v1/SupplierAllocations/Create/{SurveyNumber}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X POST --data '{"SupplierCode": "1010", "AllocationPercentage": 0.1, "TCPI": 2, "HedgeAccess": true, "BlockRouterTraffic": false,}' https://api.samplicio.us/Demand/v1/SupplierAllocations/Create/{SurveyNumber}
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Demand/v1/SupplierAllocations/Create/{SurveyNumber}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Post.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {SupplierCode: "1010", AllocationPercentage: 0.1, TCPI: 2, HedgeAccess: true, BlockRouterTraffic: false}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{"SupplierCode": "1010", "AllocationPercentage": 0.1, "TCPI": 2, "HedgeAccess": true, "BlockRouterTraffic": false}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/SupplierAllocations/Create/{SurveyNumber}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/Demand/v1/SupplierAllocations/Create/{SurveyNumber}'
params = {'SupplierCode': '1010', 'AllocationPercentage': 0.1, 'TCPI': 2, 'HedgeAccess': True, 'BlockRouterTraffic': False}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.post(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SupplierAllocations/Create/{SurveyNumber}");
string args = @"{
""SupplierCode"": ""1010"",
""AllocationPercentage"": 0.1,
""TCPI"": 2,
""HedgeAccess"": true,
""BlockRouterTraffic"": false
}";
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "POST",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SupplierAllocations/Create/{SurveyNumber}/{SupplierCode}",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {
"SupplierCode": "1010",
"AllocationPercentage": 0.1,
"TCPI": 2,
"HedgeAccess": true,
"BlockRouterTraffic": false
};
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 1,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: CreateSupplierAllocationFromModel successful."
],
"ResultCount": 1,
"SupplierAllocation": {
"SupplierCode": "1010",
"AllocationPercentage": 0.1,
"TCPI": 2,
"HedgeAccess": true,
"BlockRouterTraffic": false,
"SupplierSurveyID": null,
"Prescreens": null,
"Completes": null,
"AllocationRemaining": null,
"HedgeRemaining": null,
"TotalRemaining": null,
"Target": null
}
}
Creates supplier allocations for an existing Marketplace survey.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
| SupplierCode | string | true | Unique code associated with a supplier account. |
| AllocationPercentage | double | false | Percentage of total completes allocated to supplier, expressed as a decimal from 0 to 1. |
| TCPI | double | true | Over-the-counter cost per supplier complete. |
| HedgeAccess | boolean | false | Indicates if hedge access is enabled for the supplier. |
| BlockRouterTraffic | string | false | Indicates if router traffic is enabled for the supplier. |
PUT Update an Allocation
Definition
PUT https://api.samplicio.us/Demand/v1/SupplierAllocations/Update/{SurveyNumber}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X PUT --data '{"SupplierCode": "1010", "AllocationPercentage": 0.1, "TCPI": 2, "HedgeAccess": true, "BlockRouterTraffic": false,}' https://api.samplicio.us/Demand/v1/SupplierAllocations/Update/{SurveyNumber}
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Demand/v1/SupplierAllocations/Update/{SurveyNumber}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Put.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {SupplierCode: "1010", AllocationPercentage: 0.1, TCPI: 2, HedgeAccess: true, BlockRouterTraffic: false}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{"SupplierCode": "1010", "AllocationPercentage": 0.1, "TCPI": 2, "HedgeAccess": true, "BlockRouterTraffic": false}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/SupplierAllocations/Update/{SurveyNumber}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/Demand/v1/SupplierAllocations/Update/{SurveyNumber}'
params = {'SupplierCode': '1010', 'AllocationPercentage': 0.1, 'TCPI': 2, 'HedgeAccess': True, 'BlockRouterTraffic': False}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
supplierLink = requests.put(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SupplierAllocations/Update/{SurveyNumber}");
string args = @"{
""SupplierCode"": ""1010"",
""AllocationPercentage"": 0.1,
""TCPI"": 2,
""HedgeAccess"": true,
""BlockRouterTraffic"": false
}";
request.Method = "PUT";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "PUT",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SupplierAllocations/Update/{SurveyNumber}/{SupplierCode}",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {
"SupplierCode": "1010",
"AllocationPercentage": 0.1,
"TCPI": 2,
"HedgeAccess": true,
"BlockRouterTraffic": false
};
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 1,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: UpdateSupplierAllocationFromModel successful."
],
"ResultCount": 1,
"SupplierAllocation": {
"SupplierCode": "1010",
"AllocationPercentage": 0.1,
"TCPI": 2,
"HedgeAccess": true,
"BlockRouterTraffic": false,
"SupplierSurveyID": null,
"Prescreens": 0,
"Completes": 0,
"AllocationRemaining": 1,
"HedgeRemaining": 2,
"TotalRemaining": 3,
"Target": null
}
}
Creates supplier allocations for an existing Marketplace survey.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
| SupplierCode | string | true | Unique code associated with a supplier account. |
| AllocationPercentage | double | false | Percentage of total completes allocated to supplier, expressed as a decimal from 0 to 1. |
| TCPI | double | true | Over-the-counter cost per supplier complete. |
| HedgeAccess | boolean | false | Indicates if hedge access is enabled for the supplier. |
| BlockRouterTraffic | string | false | Indicates if router traffic is enabled for the supplier. |
DELETE Delete an Allocation
Definition
DELETE https://api.samplicio.us/Demand/v1/SupplierAllocations/Delete/{SurveyNumber}/{SupplierCode}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" -X DELETE https://api.samplicio.us/Demand/v1/SupplierAllocations/Delete/{SurveyNumber}/{SupplierCode}
require 'net/http'
uri = URI('https://api.samplicio.us/Demand/v1/SupplierAllocations/Delete/{SurveyNumber}/{SupplierCode}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
http.request(request)
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/SupplierAllocations/Delete/{SurveyNumber}/{SupplierCode}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_POSTFIELDS => "",
));
curl_exec($curl);
curl_close($curl);
?>
import requests
url = 'https://api.samplicio.us/Demand/v1/SupplierAllocations/Delete/{SurveyNumber}/{SupplierCode}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.delete(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SupplierAllocations/Delete/{SurveyNumber}/{SupplierCode}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
request.Method = "DELETE";
request.GetResponse();
const https = require('https');
var options = {
"method": "DELETE",
"hostname": "stg-api.samplicio.us",
"path": "/Demand/v1/SupplierAllocations/Delete/{SurveyNumber}/{SupplierCode}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options);
request.end();
Deletes a supplier allocation for an existing Marketplace survey.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
| SupplierCode | string | true | Unique code associated with a supplier account. |
Non-Marketplace Entry Links
The Non-Marketplace Entry Link resource allows the buyer to create, update, and delete supplier links (targets) on non-marketplace allocations.
Supplier Allocation Model
| Property | Type | Description |
|---|---|---|
| SupplierCode | string | Unique code associated with a supplier account. |
| AllocationPercentage | double | Percentage of total completes allocated to supplier, expressed as a decimal from 0 to 1. |
| TCPI | double | Over-the-counter cost per supplier complete. |
| HedgeAccess | string | Indicates if hedge access is enabled for the supplier (true, false). |
| BlockRouterTraffic | string | Indicates if router traffic is enabled for the supplier (true, false). |
| SupplierSurveyID | int | 36 digit hex GUID that identifies a supplier. |
| Prescreens | int | Number of prescreens achieved by the supplier. A prescreen is a respondent who enters the client survey. |
| Completes | int | Number of completes achieved by the supplier. |
| AllocationRemaining | int | Number of completes allocated only to the supplier. |
| HedgeRemaining | int | Number of unallocated completes available to any suppliers with access to hedge. |
| TotalRemaining | int | Total number of completes available to the supplier (aggregate of allocation and hedge remaining properties). |
| Target | array | Contains array of elements described below. |
Target Model
| Property | Type | Description |
|---|---|---|
| SupplierLinkTypeCode | string | Defines the type of buyer-supplier engagement and the respondent’s path in Cint Marketplace. |
| TrackingTypeCode | string | Defines how Cint Marketplace should communicate back to the supplier’s system at the end of a session. |
| NONE (Default and recommended, physically redirects the respondent back to the supplier system) | ||
| PIXEL (pixel tracking) | ||
| S2S (server to server postback) | ||
| DefaultLink | string | Tracking code or link used if none of the below apply. |
| SuccessLink | string | Tracking code or link used after a completion. |
| FailureLink | string | Tracking code or link used after a termination. |
| OverQuotaLink | string | Tracking code or link used after an overquota. |
| QualityTerminationLink | string | Tracking code or link used after a quality (security) termination. |
| LiveLink | string | Live supplier-specific respondent entry link generated by Cint Marketplace. |
| TestLink | string | Test supplier-specific respondent entry link generated by Cint Marketplace. |
POST Create a Link
Definition
POST https://api.samplicio.us/Demand/v1/SupplierAllocations/Targets/Create/{SurveyNumber}/{SupplierCode}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X POST --data '{"SupplierLinkTypeCode": "TS", "TrackingTypeCode": "NONE"}' https://api.samplicio.us/Demand/v1/SupplierAllocations/Targets/Create/{SurveyNumber}/{SupplierCode}
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Demand/v1/SupplierAllocations/Targets/Create/{SurveyNumber}/{SupplierCode}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Post.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {SupplierLinkTypeCode:"TS",TrackingTypeCode:"NONE"}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{"SupplierLinkTypeCode": "TS","TrackingTypeCode": "NONE"}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/SupplierAllocations/Targets/Create/{SurveyNumber}/{SupplierCode}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/Demand/v1/SupplierAllocations/Targets/Create/{SurveyNumber}/{SupplierCode}'
params = {'SupplierLinkTypeCode':'TS','TrackingTypeCode':'NONE'}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.post(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SupplierAllocations/Targets/Create/{SurveyNumber}/{SupplierCode}");
string args = @"{
""SupplierLinkTypeCode"":""TS"",
""TrackingTypeCode"":""NONE""
}";
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "POST",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SupplierAllocations/Targets/Create/{SurveyNumber}/{SupplierCode}",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {
"SupplierLinkTypeCode":"TS",
"TrackingTypeCode":"NONE"
};
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: CreateSupplierAllocationTargetFromModel successful."
],
"ResultCount": 1,
"SupplierAllocation": {
"SupplierCode": "1010",
"AllocationPercentage": 0,
"TCPI": 5,
"HedgeAccess": true,
"BlockRouterTraffic": false,
"SupplierSurveyID": "",
"Prescreens": 0,
"Completes": 0,
"AllocationRemaining": 0,
"HedgeRemaining": 15,
"TotalRemaining": 15,
"Target": {
"SupplierLinkTypeCode": "TS",
"TrackingTypeCode": "NONE",
"DefaultLink": "https:\/\/www.anon.com\/surveys?v=1&fs=1&uid=[%MID%]",
"SuccessLink": "https:\/\/www.anon.com\/surveys?v=1&fs=2&uid=[%MID%]&COST=[%COST%]",
"FailureLink": "https:\/\/www.anon.com\/surveys?v=1&fs=1&uid=[%MID%]",
"OverQuotaLink": "https:\/\/www.anon.com\/surveys?v=1&fs=1&uid=[%MID%]",
"QualityTerminationLink": "https:\/\/www.anon.com\/surveys?v=1&fs=1&uid=[%MID%]",
"LiveLink": "https:\/\/samplicio.us\/s\/default.aspx?SID=52c975a7-15fb-804d-9bd2-3d5d553aa7af&PID=",
"TestLink": "https:\/ \/samplicio.us\/s\/default.aspx?SID=a948gef7-3591-42c0-ce51-0e4xdf25582f&FIRID=MSDHONI7&SUMSTAT=1&PID=test"
}
}
}
Creates target links for suppliers with an allocation for a Marketplace survey.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
| SupplierCode | string | true | Unique code associated with a supplier account. |
| SupplierLinkTypeCode | int | true | Defines the type of buyer-supplier engagement and the respondent’s path in Cint Marketplace. |
| TrackingTypeCode | int | true | Defines how Marketplace should communicate back to the supplier’s system at the end of a session. The options are: |
| NONE (Default and recommended, physically redirects the respondent back to the supplier system) | |||
| PIXEL (pixel tracking) | |||
| S2S (server to server postback) |
PUT Update a Link
Definition
PUT https://api.samplicio.us/Demand/v1/SupplierAllocations/Targets/Update/{SurveyNumber}/{SupplierCode}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X PUT --data '{"SupplierLinkTypeCode": "TS", "TrackingTypeCode": "NONE", "DefaultLink":"","SuccessLink":"","FailureLink":"","OverQuotaLink":"","QualityTerminationLink":""}' https://api.samplicio.us/Demand/v1/SupplierAllocations/Targets/Update/{SurveyNumber}/{SupplierCode}
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Demand/v1/SupplierAllocations/Targets/Update/{SurveyNumber}/{SupplierCode}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Put.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {SupplierLinkTypeCode:"TS",TrackingTypeCode:"NONE",DefaultLink:"",SuccessLink:"",FailureLink:"",OverQuotaLink:"",QualityTerminationLink:""}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{"SupplierLinkTypeCode": "TS","TrackingTypeCode": "NONE","DefaultLink": "","SuccessLink": "","FailureLink": "","OverQuotaLink": "","QualityTerminationLink": ""}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/SupplierAllocations/Targets/Update/{SurveyNumber}/{SupplierCode}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/Demand/v1/SupplierAllocations/Targets/Update/{SurveyNumber}/{SupplierCode}'
params = {'SupplierLinkTypeCode':'TS','TrackingTypeCode':'NONE','DefaultLink':'','SuccessLink':'','FailureLink':'','OverQuotaLink':'','QualityTerminationLink':''}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.put(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SupplierAllocations/Targets/Update/{SurveyNumber}/{SupplierCode}");
string args = @"{
""SupplierLinkTypeCode"":""TS"",
""TrackingTypeCode"":""NONE"",
""DefaultLink"":"""",
""SuccessLink"":"""",
""FailureLink"":"""",
""OverQuotaLink"":"""",
""QualityTerminationLink"":""""
}";
request.Method = "PUT";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "PUT",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SupplierAllocations/Targets/Update/{SurveyNumber}/{SupplierCode}",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {
"SupplierLinkTypeCode":"TS",
"TrackingTypeCode":"NONE",
"DefaultLink":"",
"SuccessLink":"",
"FailureLink":"",
"OverQuotaLink": "",
"QualityTerminationLink":""
};
var params = JSON.stringify(json);
var request = https.request(options, function (updatedSupplierLink) {
var chunks = [];
updatedSupplierLink.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Updates existing supplier target links.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
| SupplierCode | string | true | Unique code associated with a supplier account. |
| SupplierLinkTypeCode | string | true | Defines the type of buyer-supplier engagement and the respondent’s path in Cint Marketplace. |
| TrackingTypeCode | int | true | Defines how Marketplace should communicate back to the supplier’s system at the end of a session. The options are: |
| NONE (Default and recommended, physically redirects the respondent back to the supplier system) | |||
| PIXEL (pixel tracking) | |||
| S2S (server to server postback) | |||
| DefaultLink | string | true | Tracking code or link used if none of the below apply. |
| SuccessLink | string | true | Tracking code or link used after a completion. |
| FailureLink | string | true | Tracking code or link used after a termination. |
| OverQuotaLink | string | true | Tracking code or link used after an overquota. |
| QualityTerminationLink | string | true | Tracking code or link used after a quality (security) termination. |
DELETE Delete a Link
Definition
DELETE https://api.samplicio.us/Demand/v1/SupplierAllocations/Targets/Delete/{SurveyNumber}/{SupplierCode}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" -X DELETE https://api.samplicio.us/Demand/v1/SupplierAllocations/Targets/Delete/{SurveyNumber}/{SupplierCode}
require 'net/http'
uri = URI('https://api.samplicio.us/Demand/v1/SupplierAllocations/Targets/Delete/{SurveyNumber}/{SupplierCode}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
http.request(request)
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/SupplierAllocations/Targets/Delete/{SurveyNumber}/{SupplierCode}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_POSTFIELDS => "",
));
curl_exec($curl);
curl_close($curl);
?>
import requests
url = 'https://api.samplicio.us/Demand/v1/SupplierAllocations/Targets/Delete/{SurveyNumber}/{SupplierCode}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.delete(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SupplierAllocations/Targets/Delete/{SurveyNumber}/{SupplierCode}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
request.Method = "DELETE";
request.GetResponse();
const https = require('https');
var options = {
"method": "DELETE",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SupplierAllocations/Targets/Delete/{SurveyNumber}/{SupplierCode}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options);
request.end();
Deletes target links for a supplier allocated to a Marketplace survey.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
| SupplierCode | string | true | Unique code associated with a supplier account. |
Recontact
Recontacts allow buyers to collect a follow-up impression on a respondent they have already interacted with or already have knowledge of.
SurveyQualifiedRespondents Model
| Property | Type | Description |
|---|---|---|
| IsActive | boolean | Indicates whether a respondent qualifies for the recontact. |
| PID | string | A supplier’s unique respondent identifier. |
GET List Qualified Respondents
Definition
GET https://api.samplicio.us/Demand/v1/SurveyQualifiedRespondents/BySurveyNumberSupplierCode/{SurveyNumber}/{SupplierCode}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Demand/v1/SurveyQualifiedRespondents/BySurveyNumberSupplierCode/{SurveyNumber}/{SupplierCode}
require 'net/http'
uri = URI('https://api.samplicio.us/Demand/v1/SurveyQualifiedRespondents/BySurveyNumberSupplierCode/{SurveyNumber}/{SupplierCode}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Demand/v1/SurveyQualifiedRespondents/BySurveyNumberSupplierCode/{SurveyNumber}/{SupplierCode}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Demand/v1/SurveyQualifiedRespondents/BySurveyNumberSupplierCode/{SurveyNumber}/{SupplierCode}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SurveyQualifiedRespondents/BySurveyNumberSupplierCode/{SurveyNumber}/{SupplierCode}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SurveyQualifiedRespondents/BySurveyNumberSupplierCode/{SurveyNumber}/{SupplierCode}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 1,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: SurveyQualifiedRespondentsBySurveyNumberSupplierCode successful."
],
"ResultCount": 2,
"SurveyQualifiedRespondents": [
{
"PID": "1110111",
"IsActive": true
},
{
"PID": "1110110",
"IsActive": true
},
]
}
Returns a list of qualified respondents for a specified recontact study and supplier by PID.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
| SupplierCode | string | true | Unique code associated with a supplier account. |
PUT Update Qualified Respondents
Definition
PUT https://api.samplicio.us/Demand/v1/SurveyQualifiedRespondents/Update/{SurveyNumber}/{SupplierCode}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X PUT --data '{"SurveyQualifiedRespondents":[{"IsActive": true,"PID": "0001110"},]}' https://api.samplicio.us/Demand/v1/SurveyQualifiedRespondents/Update/{SurveyNumber}/{SupplierCode}
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Demand/v1/SurveyQualifiedRespondents/Update/{SurveyNumber}/{SupplierCode}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Put.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {
SurveyQualifiedRespondents:
[
{
IsActive: true,
PID: '0001110'
},
]
}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{
"SurveyQualifiedRespondents":
[
{
"IsActive": true,
"PID": "0001110"
},
]
}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/SurveyQualifiedRespondents/Update/{SurveyNumber}/{SupplierCode}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/Demand/v1/SurveyQualifiedRespondents/Update/{SurveyNumber}/{SupplierCode}'
params = {
'SurveyQualifiedRespondents':
[
{
'IsActive': True,
'PID': '0001110'
},
]
}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.put(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SurveyQualifiedRespondents/Update/{SurveyNumber}/{SupplierCode}");
string args = @"{
""SurveyQualifiedRespondents"":
[
{
""IsActive"": true,
""PID"": ""0001110""
},
]
}";
request.Method = "PUT";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "PUT",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SurveyQualifiedRespondents/Update/{SurveyNumber}/{SupplierCode}",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {
"SurveyQualifiedRespondents":
[
{
"IsActive": true,
"PID": "0001110"
},
]
};
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: UpdateSurveyQualifiedRespondentsBySurveyNumberSupplierCode successful."
],
"ResultCount": 1,
"SurveyQualifiedRespondents": [
{
"PID": "1234",
"IsActive": true
},
]
}
Updates the list of PIDs that qualify for a recontact survey.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
| SupplierCode | string | true | Unique code associated with a supplier account. |
| IsActive | boolean | true | Should the respondent still qualify? |
| PID | string | true | Persistent panelist identifier used by the supplier. |
Reports
Reports allows the buyer to generate a cost summary report for a set of their surveys. For more information, please visit our Support Site.
Response Model
| Property | Data Type | Description |
|---|---|---|
| end_date | datetime | Latest date of data included. (RFC-3339 Format) |
| generated_on | datetime | Date the summary was generated on. (RFC-3339 Format) |
| po_number | string | Purchaser order number. |
| start_date | datetime | Earliest date of data included. (RFC-3339 Format) |
| summary | object | Summary model JSON object that includes totals for all survey IDs specified in request. |
| surveys | array | Array of Surveys model JSON objects for each survey specified in the request |
Summary Model
| Property | Data Type | Description |
|---|---|---|
| buyer_commissions | float | Total commissions amount from the Surveys |
| buyer_fees | float | Total fees amount from the Surveys |
| buyside_commission_adjustments | float | Total commissions adjusted from the Surveys |
| buyside_fee_adjustments | float | Total fees adjusted from the Surveys |
| completes | int | Total complete counts from the Surveys |
| currency | string | Currency the report is being calculated in |
| other_costs | float | Total other costs from the Surveys |
| sample_cost | float | Total sample CPI costs from the Surveys |
| sample_cost_adjustments | float | Total sample CPI costs adjusted from the Surveys |
| total_cost | float | Total cost of all sample, fees, commissions, others and any adjustments for all surveys. |
Surveys Model
| Property | Data Type | Description |
|---|---|---|
| buyer_commissions | float | Commission amount from the survey |
| buyer_fees | float | Fee amount from the survey |
| buyside_commission_adjustments | float | Commission adjusted from the survey |
| buyside_fee_adjustments | float | Fee adjusted from the survey |
| completes | int | Complete count from the survey |
| currency | string | Currency the survey is being calculated in |
| other_costs | float | Other costs from the survey |
| sample_cost | float | Sample CPI costs from the survey |
| sample_cost_adjustments | float | Sample CPI costs adjusted from the survey |
| survey_id | int | Survey id |
| total_cost | float | Cost of all sample, fees, commissions, others and any adjustments for the survey. |
POST Create a financial cost summary report JSON object
Definition
POST https://api.samplicio.us/v1/reports/surveys/financesummary.json
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X POST --data '{"survey_ids": ["1","2","3"],"po_number": "ABCD1234","start_date": "2020-09-01","end_date": "2020-10-01"}' https://api.samplicio.us/v1/reports/surveys/financesummary.json
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/v1/reports/surveys/financesummary.json')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {
"survey_ids"=> ["1","2","3"],
"po_number"=> "ABCD1234",
"start_date"=> "2020-09-01",
"end_date"=> "2020-10-01"
}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{
"survey_ids": ["1","2","3"],
"po_number": "ABCD1234",
"start_date": "2020-09-01",
"end_date": "2020-10-01"
}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/v1/reports/surveys/financesummary.json",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/v1/reports/surveys/financesummary.json'
params = {
"survey_ids": ["1","2","3"],
"po_number": 11,
"start_date": "2020-09-01",
"end_date": "2020-10-01"
}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.post(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/v1/reports/surveys/financesummary.json");
string args = @"{
""survey_ids"": [""1"",""2"",""3""],
""po_number"": ABCD1234,
""start_Date"": ""2020-09-01"",
""end_date"": ""2020-10-01""
}";
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "POST",
"hostname": "api.samplicio.us",
"path": "/v1/reports/surveys/financesummary.json",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {
"survey_ids": "01",
"po_number": "ABCD1234,
"start_date": "2020-09-01",
"end_date": "2020-10-01"
};
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"end_date": "2020-10-01T23:59:59-06:00",
"generated_on": "2020-10-22T10:03:00-06:00",
"po_number": "ABCD1234",
"start_date": "2020-09-01T00:00:00-06:00",
"summary": {
"buyer_commissions": "0.00",
"buyer_fees": "0.00",
"buyside_commission_adjustments": "0.00",
"buyside_fee_adjustments": "0.00",
"completes": 0,
"currency": "USD",
"other_costs": "0.00",
"sample_cost": "0.00",
"sample_cost_adjustments": "0.00",
"total_cost": "0.00"
},
"surveys": [
{
"buyer_commissions": "0.00",
"buyer_fees": "0.00",
"buyside_commission_adjustments": "0.00",
"buyside_fee_adjustments": "0.00",
"completes": 0,
"currency": "USD",
"other_costs": "0.00",
"sample_cost": "0.00",
"sample_cost_adjustments": "0.00",
"survey_id": 7673902,
"total_cost": "0.00"
}
]
}
Generates a cost summary report in JSON format.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| survey_ids | array | true | A comma-separated list of survey IDs to include in the cost summary report. Maximum 200 IDs. |
| po_number | string | false | Purchaser order number. A label or name to attach to the generated report limited to 64 characters. |
| start_date | string | false | Earliest date to generate summary for. (RFC-3339 Format, Limited to the YYYY-MM-DD) |
| end_date | string | false | Latest date to generate summary for. (RFC-3339 Format, Limited to the YYYY-MM-DD) |
POST Create a financial cost summary report PDF
Definition
POST https://api.samplicio.us/v1/reports/surveys/financesummary.pdf
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X POST --data '{"survey_ids": ["1","2","3"],"po_number": "ABCD1234","start_date": "2020-09-01","end_date": "2020-10-01"}' https://api.samplicio.us/v1/reports/surveys/financesummary.pdf
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/v1/reports/surveys/financesummary.pdf')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {
"survey_ids"=> ["1","2","3"],
"po_number"=> "ABCD1234",
"start_date"=> "2020-09-01",
"end_date"=> "2020-10-01"
}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{
"survey_ids": ["1","2","3"],
"po_number": "ABCD1234",
"start_date": "2020-09-01",
"end_date": "2020-10-01"
}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/v1/reports/surveys/financesummary.pdf",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/v1/reports/surveys/financesummary.pdf'
params = {
"survey_ids": ["1","2","3"],
"po_number": 11,
"start_date": "2020-09-01",
"end_date": "2020-10-01"
}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.post(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/v1/reports/surveys/financesummary.pdf");
string args = @"{
""survey_ids"": [""1"",""2"",""3""],
""po_number"": ABCD1234,
""start_Date"": ""2020-09-01"",
""end_date"": ""2020-10-01""
}";
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "POST",
"hostname": "api.samplicio.us",
"path": "/v1/reports/surveys/financesummary.pdf",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {
"survey_ids": "01",
"po_number": "ABCD1234,
"start_date": "2020-09-01",
"end_date": "2020-10-01"
};
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
"application/pdf"
Generates a cost summary report in PDF format.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| survey_ids | array | true | A comma-separated list of survey IDs to include in the cost summary report. Maximum 200 IDs. |
| po_number | string | false | Purchaser order number. A label or name to attach to the generated report limited to 64 characters. |
| start_date | string | false | Earliest date to generate summary for. (RFC-3339 Format, Limited to the YYYY-MM-DD) |
| end_date | string | false | Latest date to generate summary for. (RFC-3339 Format, Limited to the YYYY-MM-DD) |
Survey Groups
Survey Groups Model
The Surveys Groups resource allows the buyer to list existing survey groups, see details of a survey group, create survey groups, add and remove surveys from a survey group.
| Property | Type | Description |
|---|---|---|
| ID | int | Unique survey group identifier. |
| Name | string | Name of the survey group. This value is not unique across surveys. Maximum length of 200. |
| SurveyCount | int | Number of surveys in the survey group. |
Survey Group Model
The Survey Group allows the buyer to view surveys in a survey group.
| Property | Type | Description |
|---|---|---|
| SurveyIds | array | Unique IDs associated with the survey. |
GET List Survey Groups
Definition
GET https://api.samplicio.us/Demand/v1/SurveyGroups/
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Demand/v1/SurveyGroups/
require 'net/http'
uri = URI('https://api.samplicio.us/Demand/v1/SurveyGroups/')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Demand/v1/SurveyGroups/";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Demand/v1/SurveyGroups/'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SurveyGroups/");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SurveyGroups",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetSurveyGroups successful."
],
"ResultCount": 2,
"SurveyGroups": [
{
"ID": 10001,
"Name": "Local Group",
"SurveyCount": 38
},
{
"ID": 10101,
"Name": "Neighbor Group",
"SurveyCount": 12
}
]
}
Returns the survey groups, their IDs, and number of surveys within each. This endpoint must end in a trailing slash or it will redirect you to http due to a bug in an underlying framework.
GET Show a Survey Group
Definition
GET https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}
require 'net/http'
uri = URI('https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SurveyGroups/{SurveyGroupID}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetSurveyGroupBySurveyGroupID successful."
],
"ResultCount": 2,
"SurveyIDs": [
123456,
654321
]
}
Returns the survey IDs for the survey group specified.
POST Create a Survey Group
Definition
POST https://api.samplicio.us/Demand/v1/SurveyGroups/
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X POST --data '{"Name": "Group 1"}' https://api.samplicio.us/Demand/v1/SurveyGroups/
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Demand/v1/SurveyGroups/')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(FullUriPath, initheader = {'Content-Type' => 'application/json'})
request.body = {Name:"Group 1"}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
<?php
$curl = curl_init();
$params = '{"Name":"Group 1"}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/SurveyGroups/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests
url = 'https://api.samplicio.us/Demand/v1/SurveyGroups/'
params = {'Name':'Group 1'}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.post(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SurveyGroups/");
string args = @"{""Name"":""Group 1""}";
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.
RequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "POST",
"hostname": "api.samplicio.us",
"path": "Demand/v1/SurveyGroups/",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {
"Name":"Group 1"
}
var params = JSON.stringify(json);
var request = https.request(options, function (createGroup) {
var chunks = [];
createGroup.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: InsertSurveyGroup successful."
],
"ResultCount": 0,
"SurveyGroup": {
"ID": 18096,
"SID": "AA11AA22-A111-CCDD-5F66-123456D11",
"Name": "Group 1",
"Description": "",
"LK_RecordStatusID": true,
"LK_SurveyGroupTypeID": 1
}
}
Creates an empty survey group.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| Name | string | true | Survey Group name. Maximum 200 characters. |
POST Add to Survey Group
Definition
POST https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X POST --data '{"SurveyIDs": ["101101"]}' https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Post.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {SurveyIDs: ["101101"]}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{"SurveyIDs": ["101101"]}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}'
params = {'SurveyIDs': 101101}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.post(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}");
string args = @"{""SurveyIDs"": ["101101"]}";
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "POST",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SurveyGroups/{SurveyGroupID}",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {"SurveyIDs": ["101101"]
}
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: InsertSurveyGroupSurveys successful."
],
"ResultCount": 1,
"SurveyIDs": [
101101
]
}
Adds a survey to the specified survey group.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyIDs | array | true | Unique ID associated with the survey. |
PUT Update a Group
Definition
PUT https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X PUT --data '{"SurveyIDs":["001100"]}' https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Put.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {"SurveyIDs":["001100"]}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{"SurveyIDs":["001100"]}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}'
params = {'SurveyIDs':['001100']}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.put(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}");
string args = @"{"SurveyIDs":["001100"]}";
request.Method = "PUT";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "PUT",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SurveyGroups/{SurveyGroupID}",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {"SurveyIDs":["001100"]}
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetSurveyGroupBySurveyGroupID successful."
],
"ResultCount": 1,
"SurveyIDs": [
001100
]
}
Updates a survey group with the specified surveys.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyIDs | array | true | Unique ID associated with the survey. |
DELETE Remove from a Survey Group
Definition
DELETE https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" -X DELETE --data '{"SurveyIDs": ["101101"]}' https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(uri.request_uri)
request.body = {SurveyIDs: 101101}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{"SurveyIDs": ["101101"]}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_POSTFIELDS => "",
));
curl_exec($curl);
curl_close($curl);
?>
import requests
url = 'https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}'
params = {'SurveyIDs': 101101}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.delete(url, data=data, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Demand/v1/SurveyGroups/{SurveyGroupID}");
string args = @"{""SurveyIDs"": [101101]}";
request.Method = "DELETE";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
request.GetResponse();
const https = require('https');
var options = {
"method": "DELETE",
"hostname": "api.samplicio.us",
"path": "/Demand/v1/SurveyGroups/{SurveyGroupID}",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {"SurveyIDs": ["101101"]
}
var params = JSON.stringify(json);
var request = https.request(options);
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: DeleteSurveyGroupSurveys successful."
],
"ResultCount": 0,
"SurveyIDs": []
}
Deletes the surveyID from the specified survey group.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyIDs | array | true | Unique ID associated with the survey. |
Beta - Demand Integration
Reach v1
The Reach estimator tool allows you to specify a target and returns the expected number of completes for that target. There are two supported versions of the API. Whilst they provide very similar results the changes made in v2 were designed to allow greater accuracy in predictions and its usage is recommended.
POST Target Estimate (v1)
Definition
POST https://api.samplicio.us/demand/v2-beta/reach/audience-estimate
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X POST --data '{"qualifications": [{"question_id": 42, "condition": "18" },{"question_id": 42, "condition": "19" },{"question_id": 42, "condition": "20" },{"question_id": 42, "condition": "21" },{"question_id": 42, "condition": "22" },{"question_id": 42, "condition": "23" },{"question_id": 42, "condition": "24" },{"question_id": 42, "condition": "25" },{"question_id": 43, "condition": "2" }],"completes": 500,"days": 7,"length_of_interview": 10,"incidence_rate": 0.5,"price_ceiling": 1.5, "locale": "eng_us"}' https://api.samplicio.us/demand/v2-beta/reach/audience-estimate
require 'net/http'
require 'json'
uri = URI('https://api.samplicio.us/demand/v2-beta/reach/audience-estimate')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Post.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {
"qualifications"=> [
{
"question_id"=> 42,
"condition"=> "18"
},
{
"question_id"=> 42,
"condition"=> "19"
},
{
"question_id"=> 42,
"condition"=> "20"
},
{
"question_id"=> 42,
"condition"=> "21"
},
{
"question_id"=> 42,
"condition"=> "22"
},
{
"question_id"=> 42,
"condition"=> "23"
},
{
"question_id"=> 42,
"condition"=> "24"
},
{
"question_id"=> 42,
"condition"=> "25"
},
{
"question_id"=> 43,
"condition"=> "2"
}
],
"completes"=> 500,
"days"=> 7,
"length_of_interview"=> 10,
"incidence_rate"=> 0.5,
"price_ceiling"=> 1.5,
"locale"=> "eng_us"
}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{
"qualifications": [
{
"question_id": 42,
"condition": "18"
},
{
"question_id": 42,
"condition": "19"
},
{
"question_id": 42,
"condition": "20"
},
{
"question_id": 42,
"condition": "21"
},
{
"question_id": 42,
"condition": "22"
},
{
"question_id": 42,
"condition": "23"
},
{
"question_id": 42,
"condition": "24"
},
{
"question_id": 42,
"condition": "25"
},
{
"question_id": 43,
"condition": "2"
}
],
"completes": 500,
"days": 7,
"length_of_interview": 10,
"incidence_rate": 0.5,
"price_ceiling": 1.5,
"locale": "eng_us"
}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/demand/v2-beta/reach/audience-estimate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/demand/v2-beta/reach/audience-estimate'
params = {
"qualifications": [
{
"question_id": 42,
"condition": "18"
},
{
"question_id": 42,
"condition": "19"
},
{
"question_id": 42,
"condition": "20"
},
{
"question_id": 42,
"condition": "21"
},
{
"question_id": 42,
"condition": "22"
},
{
"question_id": 42,
"condition": "23"
},
{
"question_id": 42,
"condition": "24"
},
{
"question_id": 42,
"condition": "25"
},
{
"question_id": 43,
"condition": "2"
}
],
"completes": 500,
"days": 7,
"length_of_interview": 10,
"incidence_rate": 0.5,
"price_ceiling": 1.5,
"locale": "eng_us"
}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.post(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/reach/audience-estimate");
string args = @"{
""qualifications"": [
{
""question_id"": 42,
""condition"": ""18""
},
{
""question_id"": 42,
""condition"": ""19""
},
{
""question_id"": 42,
""condition"": ""20""
},
{
""question_id"": 42,
""condition"": ""21""
},
{
""question_id"": 42,
""condition"": ""22""
},
{
""question_id"": 42,
""condition"": ""23""
},
{
""question_id"": 42,
""condition"": ""24""
},
{
""question_id"": 42,
""condition"": ""25""
},
{
""question_id"": 43,
""condition"": ""2""
}
],
""completes"": 500,
""days"": 7,
""length_of_interview"": 10,
""incidence_rate"": 0.5,
""price_ceiling"": 1.5,
""locale"": ""eng_us""
}";
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "POST",
"hostname": "api.samplicio.us",
"path": "/demand/v2-beta/reach/audience-estimate",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {
"qualifications": [
{
"question_id": 42,
"condition": "18"
},
{
"question_id": 42,
"condition": "19"
},
{
"question_id": 42,
"condition": "20"
},
{
"question_id": 42,
"condition": "21"
},
{
"question_id": 42,
"condition": "22"
},
{
"question_id": 42,
"condition": "23"
},
{
"question_id": 42,
"condition": "24"
},
{
"question_id": 42,
"condition": "25"
},
{
"question_id": 43,
"condition": "2"
}
],
"completes": 500,
"days": 7,
"length_of_interview": 10,
"incidence_rate": 0.5,
"price_ceiling": 1.5,
"locale": "eng_us"
};
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"result": {
"feasibility": 257,
"price": 1.5,
"sample_probability": 1
}
}
Allows you to estimate the price and feasibility for a survey, using basic details about the survey and an target. The Reach endpoints return an Estimate Model representing the estimated number of completes and cost. If you are outside any possible feasibility, you will receive a feasibility of 0. This does not mean that the target is impossible, only that it cannot be estimated.
Target Model
| Property | Type | Description |
|---|---|---|
| completes | int (1 - 10000) | Number of survey completes desired. |
| days | int (1 - 14) | Number of days in the field. |
| incidence_rate | float (0 - 1) | Percentage of respondents that will qualify for the study after targeting using standard qualifications. |
| locale | string | Locale code with language and country, e.g. “eng_us”. |
| length_of_interview | int (1 - 45) | Expected time to finish the survey in minutes. |
| price_ceiling | float (0.25-100) | Max price you’d be willing to pay for each complete. |
| qualifications | array[Qualification] | Set of qualifications to define the target. |
Qualification Model
| Property | Type | Description |
|---|---|---|
| condition | string | Precode for the qualification condition. |
| question_id | int | ID of the question. |
Estimate Model
| Property | Type | Description |
|---|---|---|
| feasibility | float | The estimated number of survey completes for this target at the requested price_ceiling. |
| limited_data | array of strings (optional) | Question and condition pairs that reach didn’t have enough data on to make an accurate estimate. In the form “question_condition”. |
| price | float | Estimated price for a survey complete in USD. In some locales this may be different from the price_ceiling in the target. It then represents the estimated price to get all the completes requested in the target. |
| sample_probability | float | Unused and fixed as 1 for all requests. |
GET Locales (v1)
Get a list of locales supported in Reach.
Definition
GET https://api.samplicio.us/demand/v2-beta/reach/locales
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" "https://api.samplicio.us/demand/v2-beta/reach/locales"
require 'net/http'
uri = URI("https://api.samplicio.us/demand/v2-beta/reach/locales")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/demand/v2-beta/reach/locales";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = "https://api.samplicio.us/demand/v2-beta/reach/locales"
headers = {'Authorization' : 'YOUR_API_KEY_HERE'}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/reach/locales");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/demand/v2-beta/reach/locales",
"headers": {'Authorization': 'YOUR_API_KEY_HERE'}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"result": [
{
"code": "eng_th",
"name": "English - Thailand"
},
{
"code": "eng_pl",
"name": "English - Poland"
}
]
}
Locale Model
| Property | Type | Description |
|---|---|---|
| code | string | Locale code with language and country, e.g. “eng_us” |
| name | string | Locale name in English. |
GET Questions (v1)
Get a list of available questions and their question options for a given locale. This may not be all the Standard Qualifications in a locale.
Definition
GET https://api.samplicio.us/demand/v2-beta/reach/questions?locale={locale}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" "https://api.samplicio.us/demand/v2-beta/reach/questions?locale=fre_ca&id=638,640&translation_language=eng&limit=5"
require 'net/http'
uri = URI("https://api.samplicio.us/demand/v2-beta/reach/questions?locale=fre_ca&id=638,640&translation_language=eng&limit=5")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/demand/v2-beta/reach/questions?locale=fre_ca&id=638,640&translation_language=eng&limit=5";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = "https://api.samplicio.us/demand/v2-beta/reach/questions?locale=fre_ca&id=638,640&translation_language=eng&limit=5"
headers = {'Authorization' : 'YOUR_API_KEY_HERE'}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/reach/questions?locale=fre_ca&id=638,640&translation_language=eng&limit=5");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/demand/v2-beta/reach/questions?locale=fre_ca&id=638,640&translation_language=eng&limit=5",
"headers": {'Authorization': 'YOUR_API_KEY_HERE'}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"result": [
{
"id": 638,
"name": "STANDARD_PRIMARY_DECISION_MAKER",
"question_options": [
{
"precode": "1",
"text": "Oui",
"text_translated": "Yes"
},
{
"precode": "2",
"text": "Non",
"text_translated": "No"
},
{
"precode": "3",
"text": "Nous partageons les décisions équitablement",
"text_translated": "Share decisions equally"
}
],
"question_text": "Dans votre foyer, êtes-vous la personne qui prend le plus souvent les décisions d'achats au quotidien ?",
"question_type": "Single Punch",
"question_text_translated": "In your household, are you the person who makes most of the daily purchasing decisions?"
},
{
"id": 640,
"name": "STANDARD_SEXUAL_ORIENTATION",
"question_options": [
{
"precode": "1",
"text": "Hétérosexuel",
"text_translated": "Heterosexual"
},
{
"precode": "2",
"text": "Homosexuel",
"text_translated": "Homosexual"
},
{
"precode": "3",
"text": "Bisexuel",
"text_translated": "Bisexual"
},
{
"precode": "5",
"text": "Je ne souhaite pas répondre",
"text_translated": "Prefer not to answer"
}
],
"question_text": "Quelle-est votre orientation sexuelle ?",
"question_type": "Single Punch",
"question_text_translated": "What is your sexual orientation?"
}
],
"total": 2
}
Query Parameters
| Property | Type | Description |
|---|---|---|
| locale | string | Locale code with language and country, e.g. “eng_us” |
| id | csv[int] | An optional list of specified question IDs to retrieve |
| translation_language | string | Locale code with language for questions and question options translation, e.g., “eng”. |
| limit | int | Limit for the number of questions in the response. |
Question Model
| Property | Type | Description |
|---|---|---|
| id | int | ID of the question, used to identify a question when defining estimation qualifications. |
| name | string | Human readable name for the question translated to the requested locale. |
| question_options | array[Question Options] | Set of valid options for the question (if not open ended) |
| question_text | string | The question text as it appears to respondents for the requested locale. |
| question_type | string | The type of question, valid options include Single Punch, Multi Punch, Dummy, and a variety of Open Ended types. |
| question_text_translated | string (optional) | The translated text for the question. May not appear if it is not present for a question. Further there may be some survey responses where some questions are translated and some are not. |
| option_mask | string (optional) | Option template for open ended questions. Letter “X” represents a digit, letter “A” represents any alphanumeric character. |
Question Options Model
| Property | Type | Description |
|---|---|---|
| precode | string | Value used to identify a Question Option for a given Question. |
| text | string | Question Option text as it appears to respondents for the requested locale. |
| text_translated | string (optional) | The translated text for the question option. May not appear if it is not present for the option. |
Reach v2
The Reach estimator tool allows you to specify a survey description and returns the expected number of completes for the survey and the targets that comprise it and a suggested price to get the completes that you request. Reach provides predictions for ad hoc survey types with no restrictive allocations or survey groups and no usage of OTC supply. The prediction models are trained on past activity on the Cint Marketplace and are not a guarantee of delivery.
Reach API v2 provides range results rather than point estimates as these gave false precision to the predictions. It also requires developers to send specific start and end times for their surveys, rather than a generic days in field. This allows Cint to provide more accurate results for all types of surveys that take into account the normal ebbs and flows of a marketplace.
The estimates endpoints provide two predictions: a completes prediction which holds all the other variables static and returns an estimate of the number of completes available for that specification; and a price prediction which does the same thing, only varying the survey CPI field. As such, if you ask for more completes than you really need the price prediction will be aiming to provide a market clearing price to fill that survey. There could be unexpected results if you apply that estimate to a survey with a different specification.
Reach In Field
Reach can also provide estimates for survey specifications that are already live in the Marketplace. This allows you to continue to monitor feasibility for your survey throughout its lifecycle, explore difference scenarios and adjust your quotas and pricing to ensure better delivery. To enable this you can optionally provide extra information as to how many completes have already been collected in your targets and the current time you wish to get a prediction for. Then Reach can take into account how far through its run the survey is and adjust the results based on historical patterns for similar surveys. The results format is the same as a normal prediction.
POST Target Estimate v2
Definition
POST https://api.samplicio.us/demand/v2-beta/reach/v2/audience-estimate
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X POST --data '{"completes": 1000, "end_date": "2020-01-20T14:05:05+02:00", "incidence_rate": 0.5, "length_of_interview": 20, "locale": "eng_us", "price": 0.8, "start_date": "2020-01-01T14:05:05+02:00", "targets": [{"qualifications": [{"condition": "18", "question_id": 42}, {"condition": "19", "question_id": 42}, {"condition": "20", "question_id": 42}, {"condition": "21", "question_id": 42}], "quota": 500}, {"qualifications": [{"condition": "22", "question_id": 42}, {"condition": "23", "question_id": 42}, {"condition": "24", "question_id": 42}, {"condition": "25", "question_id": 42}], "quota": 500}]}' "https://api.samplicio.us/demand/v2-beta/reach/v2/audience-estimate"
require 'net/http'
require 'json'
uri = URI("https://api.samplicio.us/demand/v2-beta/reach/v2/audience-estimate")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path
request = Net::HTTP::Post.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {
"collects_pii"=> false,
"completes"=> 1000,
"completes_collected"=> 220,
"current_date"=> "2020-01-02T12:07:05+02:00",
"end_date"=> "2020-01-20T14:05:05+02:00",
"incidence_rate"=> 0.5,
"length_of_interview"=> 20,
"locale"=> "eng_us",
"price"=> 0.8,
"start_date"=> "2020-01-01T14:05:05+02:00",
"targets"=> [
{
"completes_collected"=> 120,
"qualifications"=> [
{
"condition"=> "18",
"question_id"=> 42
},
{
"condition"=> "19",
"question_id"=> 42
},
{
"condition"=> "20",
"question_id"=> 42
},
{
"condition"=> "21",
"question_id"=> 42
}
],
"quota"=> 500
},
{
"completes_collected"=> 100,
"qualifications"=> [
{
"condition"=> "22",
"question_id"=> 42
},
{
"condition"=> "23",
"question_id"=> 42
},
{
"condition"=> "24",
"question_id"=> 42
},
{
"condition"=> "25",
"question_id"=> 42
}
],
"quota"=> 500
}
]
}.to_json
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$curl = curl_init();
$params = '{
"collects_pii": false,
"completes": 1000,
"completes_collected": 220,
"current_date": "2020-01-02T12:07:05+02:00",
"end_date": "2020-01-20T14:05:05+02:00",
"incidence_rate": 0.5,
"length_of_interview": 20,
"locale": "eng_us",
"price": 0.8,
"start_date": "2020-01-01T14:05:05+02:00",
"targets": [
{
"completes_collected": 120,
"qualifications": [
{
"condition": "18",
"question_id": 42
},
{
"condition": "19",
"question_id": 42
},
{
"condition": "20",
"question_id": 42
},
{
"condition": "21",
"question_id": 42
}
],
"quota": 500
},
{
"completes_collected": 100,
"qualifications": [
{
"condition": "22",
"question_id": 42
},
{
"condition": "23",
"question_id": 42
},
{
"condition": "24",
"question_id": 42
},
{
"condition": "25",
"question_id": 42
}
],
"quota": 500
}
]
}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/demand/v2-beta/reach/v2/audience-estimate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = 'https://api.samplicio.us/demand/v2-beta/reach/v2/audience-estimate'
params = {
"collects_pii": False,
"completes": 1000,
"completes_collected": 220,
"current_date": "2020-01-02T12:07:05+02:00",
"end_date": "2020-01-20T14:05:05+02:00",
"incidence_rate": 0.5,
"length_of_interview": 20,
"locale": "eng_us",
"price": 0.8,
"start_date": "2020-01-01T14:05:05+02:00",
"targets": [
{
"completes_collected": 120,
"qualifications": [
{
"condition": "18",
"question_id": 42
},
{
"condition": "19",
"question_id": 42
},
{
"condition": "20",
"question_id": 42
},
{
"condition": "21",
"question_id": 42
}
],
"quota": 500
},
{
"completes_collected": 100,
"qualifications": [
{
"condition": "22",
"question_id": 42
},
{
"condition": "23",
"question_id": 42
},
{
"condition": "24",
"question_id": 42
},
{
"condition": "25",
"question_id": 42
}
],
"quota": 500
}
]
}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.post(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/reach/v2/audience-estimate");
string args = @"{
""collects_pii"": false,
""completes"": 1000,
""completes_collected"": 220,
""current_date"": ""2020-01-02T12:07:05+02:00"",
""end_date"": ""2020-01-20T14:05:05+02:00"",
""incidence_rate"": 0.5,
""length_of_interview"": 20,
""locale"": ""eng_us"",
""price"": 0.8,
""start_date"": ""2020-01-01T14:05:05+02:00"",
""targets"": [
{
""completes_collected"": 120,
""qualifications"": [
{
""condition"": ""18"",
""question_id"": 42
},
{
""condition"": ""19"",
""question_id"": 42
},
{
""condition"": ""20"",
""question_id"": 42
},
{
""condition"": ""21"",
""question_id"": 42
}
],
""quota"": 500
},
{
""completes_collected"": 100,
""qualifications"": [
{
""condition"": ""22"",
""question_id"": 42
},
{
""condition"": ""23"",
""question_id"": 42
},
{
""condition"": ""24"",
""question_id"": 42
},
{
""condition"": ""25"",
""question_id"": 42
}
],
""quota"": 500
}
]
}";
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "POST",
"hostname": "api.samplicio.us",
"path": "/demand/v2-beta/reach/v2/audience-estimate",
"headers": {'Content-Type': 'application/json',
'Authorization': 'YOUR_API_KEY_HERE'
}
};
var json = {
"collects_pii": false,
"completes": 1000,
"completes_collected": 220,
"current_date": "2020-01-02T12:07:05+02:00",
"end_date": "2020-01-20T14:05:05+02:00",
"incidence_rate": 0.5,
"length_of_interview": 20,
"locale": "eng_us",
"price": 0.8,
"start_date": "2020-01-01T14:05:05+02:00",
"targets": [
{
"completes_collected": 120,
"qualifications": [
{
"condition": "18",
"question_id": 42
},
{
"condition": "19",
"question_id": 42
},
{
"condition": "20",
"question_id": 42
},
{
"condition": "21",
"question_id": 42
}
],
"quota": 500
},
{
"completes_collected": 100,
"qualifications": [
{
"condition": "22",
"question_id": 42
},
{
"condition": "23",
"question_id": 42
},
{
"condition": "24",
"question_id": 42
},
{
"condition": "25",
"question_id": 42
}
],
"quota": 500
}
]
};
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"result": {
"completes_prediction": {
"max": 1200,
"min": 800
},
"price_prediction": {
"max": 1.1,
"min": 0.5
},
"targets": [
{
"completes_prediction": {
"max": 400,
"min": 300
},
"price_prediction": {
"max": 1.1,
"min": 0.5
}
},
{
"completes_prediction": {
"max": 800,
"min": 500
},
"price_prediction": {
"max": 0.5,
"min": 0.3
}
}
]
}
}
Predict number of completes based on survey criteria and audience.
ForecastRequest Model
| Property | Type | Description |
|---|---|---|
| collects_pii | bool (optional) | Indicates whether or not the client survey collects personally identifiable information (PII). If missing, it is assumed that the survey does not collect PII. |
| completes | int ( >= 1) | Number of survey completes desired. |
| completes_collected | int ( >= 0, optional) | When the survey is already running, you can specify how many completes were already collected using this field, at the date-time specified at current_date. |
| current_date | string (optional) | When the survey is already running, this field in ISO 8601 format specifies the date-time at which the survey has collected the number of completes from completes_collected. |
| end_date | string | The end date and time of the survey in ISO 8601 format. |
| incidence_rate | float (0 - 1) | Percentage of respondents that will qualify for the study after targeting using standard qualifications. |
| length_of_interview | int (1 - 45) | Expected time to finish the survey in minutes. |
| locale | string | Locale code with language and country, e.g. “eng_us”. |
| price | float ( >= 0.25) | Maximum price you’d be willing to pay for each complete in USD. |
| start_date | string | The start date and time of the survey in ISO 8601 format. |
| targets | array[Target] | Audience defined by qualifications. |
Target Model
| Property | Type | Description |
|---|---|---|
| completes_collected | int ( >= 0, optional) | When the survey is already running, you can specify how many completes were already collected for this target using this field, at the date-time specified at current_date. |
| qualifications | array[Qualification] | Target qualifications. |
| quota | int (1-10000) | The requested number of respondents for this target. |
Forecast Model
| Property | Type | Description |
|---|---|---|
| completes_prediction | Range | The estimated number of survey completes for this target at the requested price_ceiling. |
| price_prediction | Range | Predicted necessary CPI for the survey to collect all requested completes. If collecting all requested completes seems infeasible, min and max contain nulls |
| targets | array[TargetForecast] | List of per target price and completes predictions. |
Range Model
| Property | Type | Description |
|---|---|---|
| max | float | Predicted upper bound. It can be null in case of price for infeasible input. |
| min | float | Predicted lower bound. It can be null in case of price for infeasible input. |
TargetForecast Model
| Property | Type | Description |
|---|---|---|
| completes_prediction | Range | Predicted number of completes for the given target with requested CPI. |
| price_prediction | Range | Predicted necessary CPI for the given target to collect all requested completes. If collecting all requested completes seems infeasible, min and max contain nulls. |
GET Locales v2
Get a list of locales supported in Reach v2. You can compare this with the platform supported locales to see any differences.
Definition
GET https://api.samplicio.us/demand/v2-beta/reach/v2/locales
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" "https://api.samplicio.us/demand/v2-beta/reach/v2/locales"
require 'net/http'
uri = URI("https://api.samplicio.us/demand/v2-beta/reach/v2/locales")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/demand/v2-beta/reach/v2/locales";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = "https://api.samplicio.us/demand/v2-beta/reach/v2/locales"
headers = {'Authorization' : 'YOUR_API_KEY_HERE'}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/reach/v2/locales");
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/demand/v2-beta/reach/v2/locales",
"headers": {'Authorization': 'YOUR_API_KEY_HERE'}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"result": [
{
"code": "eng_th",
"name": "English - Thailand"
},
{
"code": "eng_pl",
"name": "English - Poland"
}
]
}
GET Questions v2
Get a list of available questions and their question options for a given locale. This may not be all the Standard Qualifications in a locale, however, if the qualification is supported then all valid inputs will be supported for that question.
When used with the query argument, the Questions endpoint can be used for search of available questions and answers, with results that can then be used with Reach or for other Qualifications endpoints.
Definition
GET https://api.samplicio.us/demand/v2-beta/reach/v2/questions?locale={locale}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" "https://api.samplicio.us/demand/v2-beta/reach/v2/questions?locale=eng_gb&id=42,43&translation_language=eng&limit=5"
require 'net/http'
uri = URI("https://api.samplicio.us/demand/v2-beta/reach/v2/questions?locale=eng_gb&id=42,43&translation_language=eng&limit=5")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/demand/v2-beta/reach/v2/questions?locale=eng_gb&id=42,43&translation_language=eng&limit=5";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = "https://api.samplicio.us/demand/v2-beta/reach/v2/questions?locale=eng_gb&id=42,43&translation_language=eng&limit=5"
headers = {'Authorization' : 'YOUR_API_KEY_HERE'}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/reach/v2/questions?locale=eng_gb&id=42,43&translation_language=eng&limit=5");
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/demand/v2-beta/reach/v2/questions?locale=eng_gb&id=42,43&translation_language=eng&limit=5",
"headers": {'Authorization': 'YOUR_API_KEY_HERE'}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"result": [
{
"id": 42,
"name": "AGE",
"question_options": [],
"question_text": "What is your age?",
"question_type": "Numeric - Open-end"
},
{
"id": 43,
"name": "GENDER",
"question_options": [
{
"precode": "1",
"text": "Male"
},
{
"precode": "2",
"text": "Female"
}
],
"question_text": "What is your gender?",
"question_type": "Single Punch"
}
],
"total": 2
}
Query Parameters
| Property | Type | Description |
|---|---|---|
| locale | string | Locale code with language and country, e.g., “eng_us”. |
| query | string | A free form query. |
| id | csv[int] | An optional list of specified question IDs to retrieve. |
| translation_language | string | Locale code with language for questions and question options translation, e.g., “eng”. |
| limit | int | Limit for the number of questions in the response. |
Question Model
| Property | Type | Description |
|---|---|---|
| id | int | ID of the question, used to identify a question when defining estimation qualifications. |
| name | string | Human readable name of the question in the given locale. |
| question_options | array[Question Options] | Set of valid options for the question (if not open ended) |
| question_text | string | The question text as it appears to respondents for the requested locale. |
| question_type | string | The type of question, valid options include Single Punch, Multi Punch, Dummy, and a variety of Open Ended types. |
| question_text_translated | string (optional) | The translated text for the question. May not appear if it is not present for a question. |
| option_mask | string (optional) | Option template for validating open ended questions. Letter “X” represents a digit, letter “A” represents any alphanumeric character. |
Projects (beta)
Projects allow surveys to be put into groupings. There is a 1:many relationship between project:survey(s). A project_id is a required property for the POST Create a Survey call.
Column Descriptions
data_type— the type of data displayed:bool,int,float,string,object, orarray[data_type].description— an explanation of the field.limits— defines the range of acceptable values for this property.default— the default value of the property. Default options could be an account-level setting, our standard defaults, orauto(which indicates the property was auto-generated). Any property that isnullby default can be created asnull, set asnull, or returned asnull.required_on_create— indicates whether the property is required on the POST call.required_on_live— indicates whether the property is required in order for the survey to be set live.locked_on_live— indicates whether the property can be changed after a survey has gone live.
Projects Model
| Property | Data Type | Description | Limits |
|---|---|---|---|
| client_id | int | ID associated with Marketplace user’s end-client | #clients |
| description | string | Details about the project. | Less than or equal to 64 characters. |
| id | int | A unique identifier generated for the project. | - |
| name | string | The name of the project. | Less than or equal to 64 characters. |
| project_owner_id | int | ID of the owner of the entire project. | #users |
| sid | string | An alternative unique identifier. | UUID4 |
POST Create a Project (beta)
Create a project. POST will return all Model parameters to show all current parameters values at the time of the API call.
Definition
POST https://api.samplicio.us/demand/v2-beta/projects
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X POST --data {
"description": "Sodas and Water",
"name": "First Project",
"project_owner_id": 4
} https://api.samplicio.us/demand/v2-beta/projects
require 'net/http'
require 'json'
uri = URI(https://api.samplicio.us/demand/v2-beta/projects)
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Post.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {
"description" => "Sodas and Water",
"name" => "First Project",
"project_owner_id" => 4
}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{
"description": "Sodas and Water",
"name": "First Project",
"project_owner_id": 4
}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/demand/v2-beta/projects",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = https://api.samplicio.us/demand/v2-beta/projects
params = {
"description": "Sodas and Water",
"name": "First Project",
"project_owner_id": 4
}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.post(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/projects");
string args = @"{
""description"": ""Sodas and Water"",
""name"": ""First Project"",
""project_owner_id"": 4
}";
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "POST",
"hostname": "api.samplicio.us",
"path": "/demand/v2-beta/projects",
"headers": {'Authorization': 'YOUR_API_KEY_HERE', 'Content-Type': 'application/json'}
};
var json = {
"description": "Sodas and Water",
"name": "First Project",
"project_owner_id": 4
};
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"client_id": 123,
"description": "Sodas and Cars",
"id": 12345,
"name": "First Project",
"project_owner_id": 4
}
| Property | Default | Required On Create | Required On Live | Locked On Live |
|---|---|---|---|---|
| client_id | API_Client | - | yes | - |
| description | null | - | - | - |
| name | - | yes | yes | - |
| project_owner_id | null | - | - | - |
PATCH Update a Project (beta)
Update a project by passing in the id to be updated.
Definition
PATCH https://api.samplicio.us/demand/v2-beta/projects/{id}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X PATCH --data {
"client_id": 4567
} https://api.samplicio.us/demand/v2-beta/projects/12345
require 'net/http'
require 'json'
uri = URI(https://api.samplicio.us/demand/v2-beta/projects/12345
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Patch.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {
"client_id" => 4567
}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{
"client_id": 4567
}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/demand/v2-beta/projects/12345",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_PATCHFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = https://api.samplicio.us/demand/v2-beta/projects/12345
params = {
"client_id": 4567
}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.patch(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/projects/12345");
string args = @"{
""client_id"": 4567
}";
request.Method = "PATCH";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "PATCH",
"hostname": "api.samplicio.us",
"path": "/demand/v2-beta/projects/12345",
"headers": {'Authorization': 'YOUR_API_KEY_HERE', 'Content-Type': 'application/json'}
};
var json = {
"client_id": 4567
};
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"client_id": 4567,
"description": "Sodas and Water",
"id": 12345,
"name": "First Project",
"project_owner_id": 4
}
| Property | Required On Live | Locked On Live |
|---|---|---|
| client_id | yes | - |
| description | - | - |
| name | yes | - |
| project_owner_id | - | - |
GET Project (beta)
Returns a single project by passing in the id in the path.
Definition
GET https://api.samplicio.us/demand/v2-beta/projects/{id}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" "https://api.samplicio.us/demand/v2-beta/projects/{id}"
require 'net/http'
uri = URI("https://api.samplicio.us/demand/v2-beta/projects/{id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/demand/v2-beta/projects/{id}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = "https://api.samplicio.us/demand/v2-beta/projects/{id}"
headers = {'Authorization' : 'YOUR_API_KEY_HERE'}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/projects/{id}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/demand/v2-beta/projects/{id}",
"headers": {'Authorization': 'YOUR_API_KEY_HERE'}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"client_id": 123,
"description": "Sodas and Water",
"id": 12345,
"name": "First Project",
"project_owner_id": 4
}
| Property | Description |
|---|---|
| client_id | The client associated with this project. |
| description | Details about the project. |
| id | A unique identifier generated for the project. |
| name | The name of the project. |
| project_owner_id | The owner of the entire project. |
| sid | An alternative unique identifier. |
GET List of Projects (beta)
Get a list of project names and ids using query arguments.
Definition
GET https://api.samplicio.us/demand/v2-beta/projects
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" "https://api.samplicio.us/demand/v2-beta/projects?page_size=3&client_id=4567&order=asc"
require 'net/http'
uri = URI("https://api.samplicio.us/demand/v2-beta/projects?page_size=3&client_id=4567&order=asc")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/demand/v2-beta/projects?page_size=3&client_id=4567&order=asc";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = "https://api.samplicio.us/demand/v2-beta/projects?page_size=3&client_id=4567&order=asc"
headers = {'Authorization' : 'YOUR_API_KEY_HERE'}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/projects?page_size=3&client_id=4567&order=asc");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/demand/v2-beta/projects/{id}",
"headers": {'Authorization': 'YOUR_API_KEY_HERE'}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"result": [
{
"id": 13951,
"name": "Cars and Trucks"
},
{
"id": 13977,
"name": "Monthly Tracker - Books"
},
{
"id": 13980,
"name": "Universities"
}
],
"total": 11582
}
Query Arguments
| Property | Data Type | Description |
|---|---|---|
| client_id | int | The ID associated with Marketplace user’s end-client. |
| fields | csv[string] | The model fields to retrieve for these projects. |
| id | int | The unique identifier associated with this project. |
| name | string | A human-readable name for this project. |
| order | string | Sort data by [asc]ending or [desc]ending order. |
| order_by | csv[string] | Order the results by a particular column. |
| page_number | int | The specific page of results to retrieve. |
| page_size | int | How many results to retrieve per page (1-200). |
| project_owner_id | int | The project owner’s identification number. |
Questions (beta)
The Questions resource allows you to access details for questions and their related answers to help construct accurate and valid qualifications and quotas for your survey.
Question Model
| Property | Type | Description |
|---|---|---|
| id | int | A unique identifier generated for the question. |
| name | string | Human readable name of the question. |
| question_type | string | The type of question; valid options include Single Punch, Multi Punch, Dummy, and a variety of Open Ended types. |
| question_type_name | string | The Name of the question type. |
| standard | Boolean | Denotes whether the question is standard or custom. |
Question Options Model
| Property | Type | Description |
|---|---|---|
| id | int | A unique identifier generated for the question option. |
| precode | int | A unique identifier associated with the answer text. |
| order | int | A number specifying where in the order of answers this question option is located. |
| text | string | Human readable question option text that is translated to the requested locale. |
GET Questions (beta)
Returns questions and their details based on query parameters supplied. Properties that are included by default are in the example response to the right. Properties that are not included by default can be explicitly requested by using the fields query parameter. When including the fields query parameter, only the comma separated values requested will be in the response.
For example,/v2-beta/questions?fields=name,question_options,question_text,question_type&id=42,43 will return only the name, question_options, question_text, and question_type fields for the questions matching the question ID 42 and 43.
Definition
GET https://api.samplicio.us/demand/v2-beta/questions?id=42,43
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" "https://api.samplicio.us/demand/v2-beta/questions?id=42,43"
require 'net/http'
uri = URI("https://api.samplicio.us/demand/v2-beta/questions?id=42,43")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/demand/v2-beta/questions?id=42,43";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = "https://api.samplicio.us/demand/v2-beta/questions?id=42,43"
headers = {'Authorization' : 'YOUR_API_KEY_HERE'}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/questions?id=42,43");
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/demand/v2-beta/questions?id=42,43",
"headers": {'Authorization': 'YOUR_API_KEY_HERE'}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"result": [
{
"id": 42,
"name": "AGE",
"question_type": "Numeric - Open-end",
"question_type_name": "Numeric - Open-end",
"standard": true
},
{
"id": 43,
"name": "GENDER",
"question_type": "Single Punch",
"question_type_name": "Single Punch",
"standard": true
}
],
"total": 2
}
Query Arguments
| Property | Type | Description |
|---|---|---|
| fields | csv[string] | An optional list of specific fields to be returned for each question |
| locale | string | Locale code with language and country, e.g., “eng_us” for “English - United States”, “tam_in” for “Tamil - India” |
| id | csv[int] | an optional list of question ids |
| class | string | Denotes either standard or custom questions |
| page_number | int | The specific page of results to retrieve |
| page_size | int | How many results to retrieve per page (1-200) |
fields values
The following values can be passed to the fields query parameter as comma separated values. These fields will be included for each question returned.
| Property | Description |
|---|---|
| classification_code | The code representing the classification of the question (e.g. AUT = Automotive, BAN = Banking/Finance, AIR = Airlines/Travel). |
| classification_id | ID associated with the question classification. |
| create_date | The date the question was created. |
| locale | Locale code with language and country, e.g., “eng_us”. |
| name | Human readable name for the question. |
| option_mask | Question answer template for open ended and multi punch questions used in respondent redirects, sent from and to suppliers. For open ended questions option_mask defines the type and length of the input using “X” for digits, “A” for capital letters, and “a” for lowercase letters. The value for open ended questions may also include whitespace (“XX XX”) or hyphen (“XX-XX”) characters. Open ended question answers will be formatted based on the option_mask (e.g. “abc” will be formatted as “ABC” with the option_mask value “AAA”). For multi punch questions, the option_mask value is a sequence of zeros, where each zero represents a question option ("0000” would be the value for a multi punch question with four options). These values are used as a bit mask to communicate answers chosen via the URL. |
| question_options | Set of valid options for the question (if not open ended). |
| question_text | The question text as it appears to respondents for the requested locale. |
| question_type | The type of question, valid options include Single Punch, Multi Punch, Dummy, and a variety of Open Ended types. |
| question_type_name | name of question type. |
Surveys (beta)
The Surveys resource allows you to create new surveys, edit existing surveys, or access details for surveys within your Account.
Column Descriptions
data_typeis one ofbool,int,float,string,object, orarray[data_type].descriptionis an explanation of the property.limitsdefine the range of acceptable values for this property.defaultis the default value of the property. Default options could be an account-level setting, our standard defaults, orauto(which indicates the property was auto-generated). Any property that isnullby default can be created asnull, set asnull, or returned asnull.required_on_createindicates whether the property is required on the POST call.required_on_liveindicates whether the property is required in order for the survey to be set live.locked_on_liveindicates whether the property can be changed after a survey has gone live.
Surveys Model
| Property | Data Type | Description | Limits |
|---|---|---|---|
| account_executive_id | int | ID of the user that is assigned to be the executive on this survey. | #users |
| alternate_project_manager_id | int | ID of the alternate project manager user for the survey. | #users |
| begin_date | string | The time at which a survey will begin. A non-null value means the survey status will automatically be changed to live at the specified time. |
RFC3339 datetime. Must not be a value in the past. |
| business_unit_id | int | ID of the business unit of an account this survey belongs to. The business unit determines currency used for this survey. | #business-units |
| client_cpi_usd | float | Information property used to track internal margin in USD. | 0.0<= |
| client_id | int | ID associated with Marketplace user’s end-client information. | #clients |
| client_user_id | int | ID of the client’s chosen project manager user. | #users |
| collects_pii | bool | Indicates whether or not the client survey collects personally identifiable information. | - |
| country_id | int | Filters based on surveys which are running/have run in a specific country (See the Lookups section to find a list of available countries). | #Countries |
| create_date | string | The time at which a survey was created. | RFC3339 datetime |
| currency | object | Currency and exchange rate of the Survey as defined by the Business Unit. | - |
| end_date | string | The time at which a survey will end. A non-null value means the survey status will automatically be changed to complete at the specified time. |
RFC3339 datetime |
| expected_completes | int | The expected number of completes at the end of this survey’s life. | 0<= |
| expected_completion_loi | int | The expected length of time (in minutes) that respondents will need to take the survey. | 0<= |
| expected_incidence_rate | float | Percent of respondents that are expected to qualify for the survey. | 0-1 |
| external_name | string | A human-readable name for the survey displayed to suppliers. Default is the survey’s industry selection concatenated with “Survey”. Default can be overwritten by using this field. | Less than or equal to 128 characters. |
| fields | csv[string] | Which model fields to retrieve for these surveys. | - |
| first_complete_date | string | The time at which the first complete occurred. | RFC3339 datetime |
| fraud_profile | bool | Non-Functional: Cint automatically protects against invalid respondent traffic. | - |
| fraud_profile_threshold | int | Non-Functional: Cint automatically protects against invalid respondent traffic. | - |
| id | int | The unique identifier associated with this survey. | 0<= |
| industry | string | The industry this survey’s topic is associated with. Will be used as the default for the external_name unless the external_name field is explicitly specified. |
#industries |
| industry_lockout | string | Blocks respondents during a certain timeframe based on whether they’ve taken a separate survey in the same industry. | #industry_lockout |
| last_complete_date | string | The time at which the latest complete occurred. | RFC3339 datetime |
| live_url | string | The link into the study that the respondent gets redirected to upon qualification. | RFC3987. See Guide for more detail. |
| locale | string | The Country-Language pair that this survey is designed for. | #locale, xxx_yy using ISO 639-2B and ISO 3166-1 alpha-2. Example: eng_us for English United States. |
| name | string | A human-readable name for this survey. | Less than or equal to 128 characters. |
| order | string | Sort data by [asc]ending or [desc]ending order. | asc or desc |
| page_number | int | Which page of results to retrieve. | 0<= |
| page_size | int | How many results to retrieve per page (1-200). | 1-200 |
| priority | int | An Audience-only variable to track the survey’s priority. | 0-100 |
| project_id | int | ID of the project that this survey is associated with. | #id |
| project_manager_id | string | ID of the primary project manager user for the survey. | #users |
| quantity | int | Total number of respondents needed for this survey. | - |
| quantity_calc_type | string | Sets the survey’s calculation method to use completes or prescreens. | ‘completes’, ‘prescreens’ |
| relevant_id | bool | Non-Functional: Cint automatically protects against invalid respondent traffic. | - |
| sid | string | An alternative unique identifier. | UUID4 |
| status | string | Tracks the state of the survey, ‘live’ is the only time completes will be allowed. | status list |
| study_type | string | Indicates the survey’s limits and purpose. | #study_type |
| survey_cpi_usd | float | The price paid to suppliers in USD based on when a respondent completes the survey. This value is before any applicable commissions or fees. | 0.01<= on Live. |
| test_url | string | The test link into the study that the respondent gets redirected to upon qualification. | - |
| total_completes | int | Number of respondents that have completed the survey. | 0<= |
| total_screens | int | Number of respondents that have completed the Marketplace prescreener. | 0<= |
| unique_ip | bool | Security feature that prevents respondents from reentering this study (or any other one in its survey groups) if their IP has already done so. | - |
| unique_pid | bool | Security feature that prevents respondents from reentering this study (or any other one in its survey groups) if their Panelist ID has already done so. | - |
| verify_callback | bool | Security feature that encrypts the study’s link with a variable intended to prevent link manipulation. | - |
Currency Model
| Property | Data Type | Description |
|---|---|---|
| currency_code | string | ex: USD, determined by the survey’s chosen business unit. |
| exchange_rate | float | Exchange rate from USD to survey currency. This will be null until the survey goes live at which point the rate gets locked in. |
Status list
Surveys can be in one of the following statuses:
archived
awarded
bid
canceled_with_charge
canceled_non_charged
complete
complete_non_charged
completes_approved
invoiced
live
paid
pending
ready_to_invoice
POST Create a Survey (beta)
Create a survey. POST will return all Model parameters to show all current parameters values at the time of the API call.
Definition
POST https://api.samplicio.us/demand/v2-beta/surveys
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X POST --data {
"business_unit_id": 140,
"client_cpi_usd": 5,
"collects_pii": true,
"expected_completes": 10,
"expected_completion_loi": 10,
"expected_incidence_rate": 0.1,
"fraud_profile": true,
"fraud_profile_threshold": 13,
"industry": "education",
"live_url": "https://www.samplesurvey.com/",
"locale": "eng_us",
"name": "Test Survey",
"priority": 13,
"project_id": 54321,
"project_manager_id": 6238,
"quantity_calc_type": "prescreens",
"relevant_id": true,
"status": "pending",
"study_type": "adhoc",
"survey_cpi_usd": 5,
"test_url": "https://www.samplesurvey.com/test",
"unique_ip": true,
"unique_pid": true,
"verify_callback": true
} https://api.samplicio.us/demand/v2-beta/surveys
require 'net/http'
require 'json'
uri = URI(https://api.samplicio.us/demand/v2-beta/surveys)
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Post.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {
"business_unit_id" => 140,
"client_cpi_usd" => 5,
"collects_pii" => true,
"expected_completes" => 10,
"expected_completion_loi" => 10,
"expected_incidence_rate" => 0.1,
"fraud_profile" => true,
"fraud_profile_threshold" => 13,
"industry" => "education",
"live_url" => "https://www.samplesurvey.com/",
"locale" => "eng_us",
"name" => "Test Survey",
"priority" => 13,
"project_id" => 12345,
"project_manager_id" => 6238,
"quantity_calc_type" => "prescreens",
"relevant_id" => true,
"status" => "pending",
"study_type" => "adhoc",
"survey_cpi_usd" => 5,
"test_url" => "https://www.samplesurvey.com/test",
"unique_ip" => true,
"unique_pid" => true,
"verify_callback" => true
}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{
"business_unit_id": 140,
"client_cpi_usd": 5,
"collects_pii": true,
"expected_completes": 10,
"expected_completion_loi": 10,
"expected_incidence_rate": 0.1,
"fraud_profile": true,
"fraud_profile_threshold": 13,
"industry": "education",
"live_url": "https://www.samplesurvey.com/",
"locale": "eng_us",
"name": "Test Survey",
"priority": 13,
"project_id": 54321,
"project_manager_id": 6238,
"quantity_calc_type": "prescreens",
"relevant_id": true,
"status": "pending",
"study_type": "adhoc",
"survey_cpi_usd": 5,
"test_url": "https://www.samplesurvey.com/test",
"unique_ip": true,
"unique_pid": true,
"verify_callback": true
}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/demand/v2-beta/surveys",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = https://api.samplicio.us/demand/v2-beta/surveys
params = {
"business_unit_id": 140,
"client_cpi_usd": 5,
"collects_pii": true,
"expected_completes": 10,
"expected_completion_loi": 10,
"expected_incidence_rate": 0.1,
"fraud_profile": true,
"fraud_profile_threshold": 13,
"industry": "education",
"live_url": "https://www.samplesurvey.com/",
"locale": "eng_us",
"name": "Test Survey",
"priority": 13,
"project_id": 54321,
"project_manager_id": 6238,
"quantity_calc_type": "prescreens",
"relevant_id": true,
"status": "pending",
"study_type": "adhoc",
"survey_cpi_usd": 5,
"test_url": "https://www.samplesurvey.com/test",
"unique_ip": true,
"unique_pid": true,
"verify_callback": true
}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.post(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/surveys");
string args = @"{
""business_unit_id"": 140,
""client_cpi_usd"": 5,
""collects_pii"": true,
""expected_completes"": 10,
""expected_completion_loi"": 10,
""expected_incidence_rate"": 0.1,
""fraud_profile"": true,
""fraud_profile_threshold"": 13,
""industry"": ""education"",
""live_url"": ""https://www.samplesurvey.com/"",
""locale"": ""eng_us"",
""name"": ""Test Survey"",
""priority"": 13,
""project_id"": 12345,
""project_manager_id"": 6238,
""quantity_calc_type"": ""prescreens"",
""relevant_id"": true,
""status"": ""pending"",
""study_type"": ""adhoc"",
""survey_cpi_usd"": 5,
""test_url"": ""https://www.samplesurvey.com/test"",
""unique_ip"": true,
""unique_pid"": true,
""verify_callback"": true
}";
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "POST",
"hostname": "api.samplicio.us",
"path": "/v2-beta/surveys",
"headers": {'Authorization': 'YOUR_API_KEY_HERE', 'Content-Type': 'application/json'}
};
var json = {
"business_unit_id": 140,
"client_cpi_usd": 5,
"collects_pii": true,
"expected_completes": 10,
"expected_completion_loi": 10,
"expected_incidence_rate": 0.1,
"fraud_profile": true,
"fraud_profile_threshold": 13,
"industry": "education",
"live_url": "https://www.samplesurvey.com/",
"locale": "eng_us",
"name": "Test Survey",
"priority": 13,
"project_id": 54321,
"project_manager_id": 6238,
"quantity_calc_type": "prescreens",
"relevant_id": true,
"status": "pending",
"study_type": "adhoc",
"survey_cpi_usd": 5,
"test_url": "https://www.samplesurvey.com/test",
"unique_ip": true,
"unique_pid": true,
"verify_callback": true
};
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"account_executive_id": null,
"alternate_project_manager_id": null,
"begin_date": null,
"business_unit_id": 140,
"client_cpi_usd": 5,
"client_id": 3456,
"collects_pii": true,
"create_date": "2018-02-28T21:18:07-06:00",
"currency": {
"code": "USD",
"exchange_rate": 1
},
"end_date": "null",
"expected_completes": 10,
"expected_completion_loi": 10,
"expected_incidence_rate": 0.1,
"external_name": "Education Survey",
"fraud_profile": true,
"fraud_profile_threshold": 13,
"id": 12345678,
"industry": "education",
"industry_lockout": "no_lock_out",
"live_url": "https://www.samplesurvey.com/",
"locale": "eng_us",
"name": "Test Survey",
"priority": 13,
"project_id": 54321,
"project_manager_id": 6238,
"quantity": 0,
"quantity_calc_type": "prescreens",
"relevant_id": true,
"sid": "7de083fd-d586-457a-9b96-3cad23129fd2",
"status": "pending",
"study_type": "adhoc",
"survey_cpi_usd": 5,
"test_url": "https://www.samplesurvey.com/test",
"total_completes": 0,
"total_screens": 0,
"unique_ip": true,
"unique_pid": true,
"verify_callback": true
}
| Property | Default | Required On Create | Required On Live | Locked On Live |
|---|---|---|---|---|
| account_executive_id | null | - | - | - |
| alternate_project_manager_id | null | - | - | - |
| begin_date | null | - | - | - |
| business_unit_id | - | yes | yes | yes |
| client_cpi_usd | 0 | - | - | - |
| client_user_id | null | - | - | - |
| collects_pii | required | - | yes | yes |
| end_date | null | - | - | - |
| expected_completes | null | - | - | - |
| expected_completion_loi | null | - | - | - |
| expected_incidence_rate | null | - | - | - |
| external_name | industry + Survey |
- | yes | - |
| fraud_profile | Account default | - | - | - |
| fraud_profile_threshold | 11 | - | - | - |
| industry | null | - | yes | yes |
| industry_lockout | no_lock_out | - | - | - |
| live_url | null | - | yes | - |
| locale | - | yes | yes | yes |
| name | - | yes | yes | - |
| priority | 11 | - | - | - |
| project_id | - | yes | yes | yes |
| project_manager_id | null | - | - | - |
| quantity | 0 | - | yes | - |
| quantity_calc_type | completes | - | - | - |
| relevant_id | Account default | - | - | - |
| status | pending | - | yes | - |
| study_type | null | - | yes | yes |
| survey_cpi_usd | 0 | - | yes | - |
| test_url | null | - | - | - |
| unique_ip | Account default | - | - | - |
| unique_pid | Account default | - | - | - |
| verify_callback | Account default | - | - | - |
PATCH Update a Survey (beta)
Update one or many properties of a single survey by passing in the id to be updated. Will only return the properties you pass in.
Definition
PATCH https://api.samplicio.us/demand/v2-beta/surveys/{id}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X PATCH --data {
"name": "New survey name",
"begin_date": "2018-03-07T00:00:00.00Z",
"end_date": "2018-03-15T00:00:00.00Z"
} https://api.samplicio.us/demand/v2-beta/surveys/12345678
require 'net/http'
require 'json'
uri = URI(https://api.samplicio.us/demand/v2-beta/surveys/12345678)
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
fullUriPath = uri.path + '?' + uri.query
request = Net::HTTP::Patch.new(fullUriPath, initheader = {'Content-Type' =>'application/json'})
request.body = {
"name" => "New survey name",
"begin_date" => "2018-03-07T00 =>00 =>00.00Z",
"end_date" => "2018-03-15T00 =>00 =>00.00Z"
}.to_json
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$curl = curl_init();
$params = '{
"name": "New survey name",
"begin_date": "2018-03-07T00:00:00.00Z",
"end_date": "2018-03-15T00:00:00.00Z"
}';
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.samplicio.us/demand/v2-beta/surveys/12345678",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_HTTPHEADER => array('Content-Type: application/json', 'Authorization: YOUR_API_KEY_HERE'),
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_PATCHFIELDS => $params,
));
$response = curl_exec($curl);
curl_close($curl);
?>
import requests, json
url = https://api.samplicio.us/demand/v2-beta/surveys/12345678
params = {
"name": "New survey name",
"begin_date": "2018-03-07T00:00:00.00Z",
"end_date": "2018-03-15T00:00:00.00Z"
}
data = json.dumps(params)
headers = {'Content-type': 'application/json', 'Authorization' : 'YOUR_API_KEY_HERE', 'Accept': 'text/plain'}
response = requests.patch(url, data=data, headers=headers)
using System.IO;
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/surveys/12345678");
string args = @"{
""name"": ""New survey name"",
""begin_date"": ""2018-03-07T00:00:00.00Z"",
""end_date"": ""2018-03-15T00:00:00.00Z""
}";
request.Method = "PATCH";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "YOUR_API_KEY_HERE");
using(StreamWriter streamWriter = new StreamWriter(request.GetRequestStream()))
{
streamWriter.Write(args);
streamWriter.Flush();
streamWriter.Close();
}
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "PATCH",
"hostname": "api.samplicio.us",
"path": "/v2-beta/surveys/12345678",
"headers": {'Authorization': 'YOUR_API_KEY_HERE', 'Content-Type': 'application/json'}
};
var json = {
"name": "New survey name",
"begin_date": "2018-03-07T00:00:00.00Z",
"end_date": "2018-03-15T00:00:00.00Z"
};
var params = JSON.stringify(json);
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.write(params);
request.end();
Example Response
{
"id": 12345678,
"name": "New survey name",
"begin_date": "2018-03-07T00:00:00.00Z",
"end_date": "2018-03-15T00:00:00.00Z"
}
| Property | Required On Live | Locked On Live |
|---|---|---|
| account_executive_id | - | - |
| alternate_project_manager_id | - | - |
| begin_date | - | - |
| business_unit_id | yes | yes |
| client_cpi_usd | - | - |
| client_user_id | - | - |
| collects_pii | yes | yes |
| end_date | - | - |
| expected_completes | - | - |
| expected_completion_loi | - | - |
| expected_incidence_rate | - | - |
| external_name | yes | - |
| fraud_profile | - | - |
| fraud_profile_threshold | - | - |
| industry | yes | yes |
| industry_lockout | - | - |
| live_url | yes | - |
| locale | yes | yes |
| name | yes | - |
| priority | - | - |
| project_id | yes | yes |
| project_manager_id | - | - |
| quantity | yes | - |
| quantity_calc_type | - | - |
| relevant_id | - | - |
| status | yes | - |
| study_type | yes | yes |
| survey_cpi_usd | yes | - |
| test_url | - | - |
| unique_ip | - | - |
| unique_pid | - | - |
| verify_callback | - | - |
GET Survey (beta)
Returns a single survey by passing in the id. Properties that are included by default are in the example response to the right. Properties that are not included can be explicitly requested by using fields parameter. When using the fields query parameter, only those requested will be returned. For example: /v2-beta/surveys/{id}?fields=expected_completes,expected_incidence_rate,expected_completion_loi
will only return the expected_completes, expected_incidence_rate, and expected_completion_loi
Definition
GET https://api.samplicio.us/demand/v2-beta/surveys/{id}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" "https://api.samplicio.us/demand/v2-beta/surveys/123456"
require 'net/http'
uri = URI("https://api.samplicio.us/demand/v2-beta/surveys/123456")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/demand/v2-beta/surveys/123456";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = "https://api.samplicio.us/demand/v2-beta/surveys/123456"
headers = {'Authorization' : 'YOUR_API_KEY_HERE'}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/surveys/123456");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/demand/v2-beta/surveys/123456",
"headers": {'Authorization': 'YOUR_API_KEY_HERE'}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"business_unit_id": 140,
"collects_pii": true,
"currency": {
"code": "USD",
"exchange_rate": 1
},
"id": 12345678,
"industry": "education",
"live_url": "https://www.samplesurvey.com/",
"locale": "eng_us",
"name": "New survey name",
"project_id": 54321,
"quantity": 1000,
"survey_cpi_usd": 5,
"status": "live",
"study_type": "adhoc",
"test_url": "https://www.samplesurvey.com/test",
"total_completes": 34,
"total_screens": 128
}
| Property | Description |
|---|---|
| account_executive_id | ID of the user that is assigned to be the executive on this survey. |
| alternate_project_manager_id | ID of the alternate project manager user for the survey. |
| begin_date | The time at which a survey will begin. A non-null value means the survey status will automatically be changed to live at the specified time. |
| business_unit_id | ID of the business unit of an account this survey belongs to. The business unit determines currency used for this survey. |
| client_cpi_usd | Information property used to track internal margin in USD. |
| client_id | ID associated with Marketplace user’s end-client information. |
| client_user_id | ID of the client’s chosen project manager user. |
| collects_pii | Indicates whether or not the client survey collects personally identifiable information. |
| currency | Currency and exchange rate of the Survey as defined by the Business Unit. |
| create_date | The time at which a survey was created. |
| end_date | The time at which a survey will end. A non-null value means the survey status will automatically be changed to complete at the specified time. |
| expected_completes | The expected number of completes at the end of this survey’s life. |
| expected_completion_loi | The expected length of time (in minutes) that respondents will need to take the survey. |
| expected_incidence_rate | Percent of respondents that are expected to qualify for the survey. |
| external_name | A human-readable name for the survey displayed to suppliers. Default is the survey’s industry selection concatenated with “Survey”. Default can be overwritten by using this field. |
| first_complete_date | The time at which the first complete occurred. |
| fraud_profile | Non-Functional: Cint automatically protects against invalid respondent traffic. |
| fraud_profile_threshold | Non-Functional: Cint automatically protects against invalid respondent traffic. |
| id | The unique identifier associated with this survey. |
| industry | The industry this survey’s topic is associated with. Will be used as the default for the external_name unless the external_name field is explicitly specified. |
| industry_lockout | Blocks respondents during a certain timeframe based on whether they’ve taken a separate survey in the same industry. |
| last_complete_date | The time at which the latest complete occurred. |
| live_url | The link into the study that the respondent gets redirected to upon qualification. |
| locale | The Country-Language pair that this survey is designed for. |
| name | A human-readable name for this survey. |
| priority | An Audience-only variable to track the survey’s priority. |
| project_id | ID of the project that this survey is associated with. |
| project_manager_id | ID of the primary project manager user for the survey. |
| quantity | Total number of respondents needed for this survey. |
| quantity_calc_type | Sets the survey’s calculation method to use completes or prescreens. |
| relevant_id | Deprecated: Relevant ID will be discontinued in October 2020 |
| sid | An alternative unique identifier. |
| status | Tracks the state of the survey, ‘live’ is the only time completes will be allowed. |
| study_type | Indicates the survey’s limits and purpose. |
| survey_cpi_usd | The price paid to suppliers in USD based on when a respondent completes the survey. This value is before any applicable commissions or fees. |
| test_url | The test link into the study that the respondent gets redirected to upon qualification. |
| total_completes | Number of respondents that have completed the survey. |
| total_screens | Number of respondents that have completed the Marketplace prescreener. |
| unique_ip | Security feature that prevents respondents from reentering this study (or any other one in its survey groups) if their IP has already done so. |
| unique_pid | Security feature that prevents respondents from reentering this study (or any other one in its survey groups) if their Panelist ID has already done so. |
| verify_callback | Security feature that encrypts the study’s link with a variable intended to prevent link manipulation. |
Query Arguments
| Property | Data Type | Description |
|---|---|---|
| fields | csv[string] | Which model fields to retrieve for these surveys. |
| id | int | The unique identifier associated with this survey. |
GET List of Surveys (beta)
Get a list of surveys using query arguments. Define the fields you want in your response and the criteria you want returned surveys to match.
Definition
GET https://api.samplicio.us/demand/v2-beta/surveys
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" "https://api.samplicio.us/demand/v2-beta/surveys?name=test&fields=id,name&page_size=2"
require 'net/http'
uri = URI("https://api.samplicio.us/demand/v2-beta/surveys?name=test&fields=id,name&page_size=2")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/demand/v2-beta/surveys?name=test&fields=id,name&page_size=2";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = "https://api.samplicio.us/demand/v2-beta/surveys?name=test&fields=id,name&page_size=2"
headers = {'Authorization' : 'YOUR_API_KEY_HERE'}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/surveys?name=test&fields=id,name&page_size=2");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/demand/v2-beta/surveys?name=test&fields=id,name",
"headers": {'Authorization': 'YOUR_API_KEY_HERE'}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"result": [
{
"id": 123456,
"name": "test survey"
},
{
"id": 123457,
"name": "mytestsurvey123"
}
],
"total": 167
}
Query Arguments
| Property | Data Type | Description |
|---|---|---|
| business_unit_id | int | ID of the business unit of an account this survey belongs to. |
| client_id | int | ID associated with Marketplace user’s end-client information. |
| country_id | int | Filters based on surveys which are running/have run in a specific country (See the Lookups section to find a list of available countries). |
| fields | csv[string] | Which model fields to retrieve for these surveys. |
| id | int | The unique identifier associated with this survey. |
| locale | string | The Country-Language pair that this survey is designed for. |
| name | string | A human-readable name for this survey. |
| order | string | Sort data by [asc]ending or [desc]ending order. |
| page_number | int | Which page of results to retrieve. |
| page_size | int | How many results to retrieve per page (1-200). |
| project_id | int | ID of the project that this survey is associated with. |
| quantity_calc_type | string | Sets the survey’s calculation method to use completes or prescreens. |
| sid | string | An alternative unique identifier. |
| status | string | Tracks the state of the survey, ‘Live’ is the only time completes will be allowed. |
Sessions & Statistics (beta)
The Sessions & Statistics resource allows buyers to monitor survey and session performance in real time. Buyers will have access to the number of entrants, breakdown of Marketplace and Client statuses, cost of completes, supplier EPC, system conversion, and median LOI. Additionally, you will be able to bucket these data points by supplier and/or by date.
Sessions Model
| Property | Type | Description |
|---|---|---|
| fulcrum_status | int | Response code associated with the respondent’s Marketplace session. |
| client_status | int | Response code associated with the respondent’s client survey attempt. |
| entry_date | datetime | Date and time the respondent entered Marketplace. |
| last_date | datetime | Date and time the respondent last interacted with the session. |
| supplier_id | int | The Supplier ID associated with the supplier where the respondent was sourced. |
| panelist_id | string | A supplier’s unique respondent identifier. |
| respondent_id | string | Unique session ID per study per respondent. |
Statistics Model
| Property | Type | Description |
|---|---|---|
| earnings_per_click | float | The earnings a supplier can expect per entrant on average. |
| total_entrants | int | Total number of survey entrants to Marketplace. |
| median_length_of_interview | int | Median time for a respondent to complete the survey excluding the Marketplace prescreener in minutes. |
| median_length_of_term | int | Median time for a respondent to term from a survey excluding the Marketplace prescreener in minutes. |
| cost | json | Total cost of the survey described by the Cost Model below. |
| system_conversion | float | Total number of completes divided by total number of entrants. |
| fulcrum_status | json | Total count of each Marketplace Response Code. |
| client_status | json | Total count of each Client Response Code. |
Cost Model
| Property | Type | Description |
|---|---|---|
| amount | float | Total cost in USD of all sessions within this grouping. |
| currency_code | string | Currency code for the related Survey. |
| exchange_rate | float | Conversion rate from USD to given currency. |
GET Sessions (beta)
Returns a list of all sessions associated with a given survey for a buyer to analyze respondent-level data.
Definition
GET https://api.samplicio.us/demand/v2-beta/sessions
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" "https://api.samplicio.us/demand/v2-beta/sessions?survey_id=100001&entry_date_after=2019-01-31T00:00:00Z&entry_date_before=2019-01-31T23:59:59Z"
require 'net/http'
uri = URI("https://api.samplicio.us/demand/v2-beta/sessions?survey_id=100001&entry_date_after=2019-01-31T00:00:00Z&entry_date_before=2019-01-31T23:59:59Z")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/demand/v2-beta/sessions?survey_id=100001&entry_date_after=2019-01-31T00:00:00Z&entry_date_before=2019-01-31T23:59:59Z";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = "https://api.samplicio.us/demand/v2-beta/sessions?survey_id=100001&entry_date_after=2019-01-31T00:00:00Z&entry_date_before=2019-01-31T23:59:59Z"
headers = {'Authorization' : 'YOUR_API_KEY_HERE'}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/sessions?survey_id=100001&entry_date_after=2019-01-31T00:00:00Z&entry_date_before=2019-01-31T23:59:59Z");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/demand/v2-beta/sessions?survey_id=100001&entry_date_after=2019-01-31T00:00:00Z&entry_date_before=2019-01-31T23:59:59Z",
"headers": {'Authorization': 'YOUR_API_KEY_HERE'}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"sessions": [
{
"client_status": 1,
"entry_date": "2019-01-31T05:30:07.299000-06:00",
"fulcrum_status": 3,
"last_date": "2019-01-31T05:30:33.075000-06:00",
"panelist_id": "12345678",
"respondent_id": "5x5xxx3x-6xxx-4496-x2x9-1xx82xx1x434",
"supplier_id": 1
},
{
"client_status": 10,
"entry_date": "2019-01-31T05:30:29.439000-06:00",
"fulcrum_status": 3,
"last_date": "2019-01-31T05:46:9.027000-06:00",
"panelist_id": "12345678",
"respondent_id": "5xx2xx55-x045-4xd2-8x0x-xxx401xx9638",
"supplier_id": 1
},
{
"client_status": 20,
"entry_date": "2019-01-31T05:31:53.412000-06:00",
"fulcrum_status": 3,
"last_date": "2019-01-31T05:33:31.837000-06:00",
"panelist_id": "12345678",
"respondent_id": "xx5xxxx9-6xx3-445x-xx7x-946x4xx77147",
"supplier_id": 1
}
]
}
Query Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
| survey_id | int | true | The ID associated with the Survey. |
| entry_date_after | datetime | true | Lower bound on session entryDate. Lookback is limited to 90 days ago. (RFC-3339 Format) |
| entry_date_before | datetime | false | Upper bound entryDate. (RFC-3339 Format) |
| supplier_ids | int(s) | false | A comma-separated list of IDs associated with the supplier account. |
GET Statistics (beta)
Definition
Returns statistics to analyze survey-level data. Data can be segmented by supplier.
GET https://api.samplicio.us/demand/v2-beta/sessions/statistics
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" "https://api.samplicio.us/demand/v2-beta/sessions/statistics?survey_id=100001&entry_date_after=2017-06-01T00:00:00Z&entry_date_before=2017-05-30T23:59:59Z"
require 'net/http'
uri = URI("https://api.samplicio.us/demand/v2-beta/sessions/statistics?survey_id=100001&entry_date_after=2017-06-01T00:00:00Z&entry_date_before=2017-08-30T23:59:59Z")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/demand/v2-beta/sessions/statistics?survey_id=100001&entry_date_after=2017-06-01T00:00:00Z&entry_date_before=2017-09-30T23:59:59Z";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = "https://api.samplicio.us/demand/v2-beta/sessions/statistics?survey_id=100001&entry_date_after=2017-06-01T00:00:00Z&entry_date_before=2017-09-30T23:59:59Z"
headers = {'Authorization' : 'YOUR_API_KEY_HERE'}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/sessions/statistics?survey_id=100001&entry_date_after=2017-06-01T00:00:00Z&entry_date_before=2017-05-30T23:59:59Z");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/demand/v2-beta/sessions/statistics?survey_id=100001&entry_date_after=2017-06-01T00:00:00Z&entry_date_before=2017-09-30T23:59:59Z&",
"headers": {'Authorization': 'YOUR_API_KEY_HERE'}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"statistics": {
"client_status": {
"1": 77,
"10": 117,
"20": 577,
"-1": 222
},
"cost": {
"amount": 93.6,
"currency_code": "USD",
"exchange_rate": 1
},
"earnings_per_click": 0.09,
"fulcrum_status": {
"1": 7,
"3": 771,
"30": 12,
"31": 3,
"36": 121,
"38": 17,
"131": 3,
"138": 17,
"230": 5,
"-1": 37
},
"median_length_of_interview": 10,
"median_length_of_term": 1,
"system_conversion": 11,
"total_entrants": 993
}
}
Query Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
| survey_id | int | true | Unique number associated with the survey. |
| entry_date_after | datetime | true | Lower bound on session entryDate. Lookback is limited to 90 days ago. (RFC-3339 Format) |
| entry_date_before | datetime | false | Upper bound on session entryDate. (RFC-3339 Format) |
| supplier_ids | int(s) | false | A comma-separated list of IDs associated with the supplier account. |
| group_by | string | false | Desired grouping of statistics. Options include supplier_id, day, or hour. The group_by variable can include any of these options individually, or you can pair one datetime filter with supplied_id. For example, group_by=day, group_by=supplier_id,day OR group_by=supplier_id,hour. |
Fielding Assistant
The Fielding Assistant is an optional service that you can assign to a survey at any point in its lifecycle. The Assistant monitors the state of your survey and modifies parameters on it for you to assist in meeting your goals as a buyer. For instance, the Balanced goal will try and ensure that your survey reaches the number of completes that you specify in your total quota within the time and budget that you pass to the goal.
The assistant will only begin trying to meet your goals once you set your survey live on the Marketplace so it is safe to enable during your survey setup process. Once the assistant is enabled on a survey you should not modify the fields it is updating however you may modify the configuration or unmanaged fields at any time to change the way the assistant will try to meet your goals. You may remove the assistant from a survey at any point in its lifecycle; all survey settings will be left at their last values.
The project manager configured on the survey may recieve notifications from the Fielding Assistant about the progress of their survey or if their configuration is not possible to deliver in the Cint Marketplace within their selected cutoff time.
GET List Goals
Get a list of all available assistant goals which can be used to assist surveys. This may vary per account.
Definition
GET https://api.samplicio.us/demand/v2/fielding-assistant/goals
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" "https://api.samplicio.us/demand/v2/fielding-assistant/goals"
require 'net/http'
uri = URI("https://api.samplicio.us/demand/v2/fielding-assistant/goals")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/demand/v2/fielding-assistant/goals";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = "https://api.samplicio.us/demand/v2/fielding-assistant/goals"
headers = {'Authorization' : 'YOUR_API_KEY_HERE'}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2/fielding-assistant/goals");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/demand/v2/fielding-assistant/goals",
"headers": {'Authorization': 'YOUR_API_KEY_HERE'}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"goals": [
{
"id": "balanced_cpi",
"name": "Balanced CPI",
"description": "Adjust CPI when no completes received based on provided completes threshold.",
"fields": [
{
"id": "completion_timestamp",
"name": "Completion Timestamp"
},
{
"id": "total_budget",
"name": "Total Budget"
}
]
}
]
}
Goals Model
| Property | Type | Description |
|---|---|---|
| goals | array[Goal] | An object which contains a list of goals to assist survey. |
Goal Model
| Property | Type | Description |
|---|---|---|
| id | string | Unique identifier for the Fielding Assistant goal. |
| name | string | Human readable goal name. |
| description | string | Description of the goal. |
| fields | array[StrategyField] | A list of goal specific configuration fields. |
StrategyField Model
| Property | Type | Description |
|---|---|---|
| id | string | Unique identifier of the goal field. |
| name | string | Human readable field name. |
PUT Survey Configuration
Used to create a new Fielding Assistant survey configuration. If the configuration already exists for the provided marketplace survey ID, the existing configuration will be updated with the provided configuration fields.
Definition
PUT https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations/<int:survey_id>
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X PUT --data '{"goal": "balanced_cpi", "config": {"total_budget": 25.5, "completion_timestamp": "2020-09-01T13:37:00Z"}}' https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations/{survey_id}
require 'net/http'
require 'json'
def create_configuration
survey_id = SURVEY_ID_HERE
api_key = YOUR_API_KEY_HERE
request_body = {
"goal" => "balanced_cpi",
"config" => {
"total_budget" => 25.5,
"completion_timestamp" => "2020-09-01T13:37:00Z"
}
}
uri = URI("https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations/#{survey_id}")
request = Net::HTTP::Put.new(uri)
request.add_field "Content-Type", "application/json"
request.add_field "Authorization", api_key
request.body = JSON.dump(request_body)
response = Net::HTTP.new(uri.host, uri.port).request(request)
puts "response status code: #{response.code}"
puts "response body: #{response.body}"
rescue StandardError => e
puts "request failed (#{e.message})"
end
# Execute the create survey automation configuration API request.
create_configuration
<?php
$survey_id = SURVEY_ID_HERE;
$api_key = YOUR_API_KEY_HERE;
$request_body = json_encode([
'goal' => 'balanced_cpi',
'config' => [
'total_budget' => 25.5,
'completion_timestamp' => '2020-09-01T13:37:00Z'
]
]);
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations/' . $survey_id,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'Authorization: ' . $api_key,
),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $request_body,
));
$response = curl_exec($curl);
if (!$response) {
die('request failed: "' . curl_error($curl) . '", code: ' . curl_errno($curl));
}
echo 'response status code: ' . curl_getinfo($curl, CURLINFO_HTTP_CODE) . PHP_EOL;
echo 'response body: ' . $response . PHP_EOL;
curl_close($curl);
import requests
import json
def create_configuration():
survey_id = SURVEY_ID_HERE
api_key = YOUR_API_KEY_HERE
request_body = {
"goal": "balanced_cpi",
"config": {
"total_budget": 25.5,
"completion_timestamp": "2020-09-01T13:37:00Z"
}
}
try:
response = requests.put(
url=f"https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations/{survey_id}",
headers={
"Content-Type": "application/json",
"Authorization": api_key,
},
data=json.dumps(request_body)
)
print('response status code: {status_code}'.format(
status_code=response.status_code))
print('response body: {content}'.format(
content=response.content))
except requests.exceptions.RequestException:
print('request failed')
# Execute the create survey Fielding Assistant Configuration API request.
create_configuration()
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func createConfiguration() {
surveyID := "SURVEY_ID_HERE"
apiKey := "YOUR_API_KEY_HERE"
url := fmt.Sprintf("https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations/%s", surveyID)
requestBody := map[string]interface{}{
"goal": "balanced_cpi",
"config": map[string]interface{}{
"total_budget": 25.5,
"completion_timestamp": "2020-09-01T13:37:00Z",
},
}
jsonBody, err := json.Marshal(requestBody)
if err != nil {
fmt.Println("error marshalling JSON:", err)
return
}
req, err := http.NewRequest("PUT", url, bytes.NewBuffer(jsonBody))
if err != nil {
fmt.Println("error creating request:", err)
return
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", apiKey)
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Println("request failed:", err)
return
}
defer resp.Body.Close()
fmt.Println("response status code:", resp.Status)
// Read and print response body
buf := new(bytes.Buffer)
buf.ReadFrom(resp.Body)
fmt.Println("response body:", buf.String())
}
func main() {
// Execute the create survey Fielding Assistant Configuration API request.
createConfiguration()
}
using System;
using System.Threading.Tasks;
using System.Net;
using System.IO;
using System.Text;
namespace Lucid {
public class AutomationFieldingAssistant {
private async Task<bool> CreateConfiguration () {
int surveyID = SURVEY_ID_HERE;
string apiKey = YOUR_API_KEY_HERE;
string requestBody = @"{
""goal"": ""balanced_cpi"",
""config"": {
""total_budget"": 25.5,
""completion_timestamp"": ""2020-09-01T13:37:00Z""
}
}";
HttpWebRequest request = (HttpWebRequest)WebRequest.Create (new Uri("https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations/" + surveyID.ToString()));
request.Method = "PUT";
request.ContentType = "application/json";
request.Headers.Add("Authorization", apiKey);
ASCIIEncoding encoding = new ASCIIEncoding ();
byte[] byte1 = encoding.GetBytes (requestBody);
request.ContentLength = byte1.Length;
Stream newStream = request.GetRequestStream ();
newStream.Write (byte1, 0, byte1.Length);
newStream.Close ();
using (WebResponse response = await request.GetResponseAsync ()) {
using (Stream stream = response.GetResponseStream ()) {
// Process the API response.
return true;
}
}
}
}
}
(function (callback) {
'use strict';
let surveyID = 203748
let apiKey = "YOUR_API_KEY_HERE"
let requestBody = JSON.stringify({
"goal": "balanced_cpi",
"config": {
"total_budget": 25.5,
"completion_timestamp": "2020-09-01T13:37:00Z"
}
});
const httpTransport = require('http');
const responseEncoding = 'utf8';
const httpOptions = {
hostname: 'api.samplicio.us',
port: '80',
path: '/demand/v2/fielding-assistant/goals/configurations/' + surveyID,
method: 'PUT',
headers: {"Content-Type": "application/json", "Authorization": apiKey}
};
httpOptions.headers['User-Agent'] = 'node ' + process.version;
const request = httpTransport.request(httpOptions, (res) => {
let responseBuffer = [];
let responseBody = '';
res.on('data', (chunk) => {
if (Buffer.isBuffer(chunk)) {
responseBuffer.push(chunk);
} else {
responseBody = responseBody + chunk;
}
}).on('end', () => {
responseBody = responseBuffer.length > 0 ?
Buffer.concat(responseBuffer).toString(responseEncoding) : responseBody;
callback(null, res.statusCode, responseBody);
})
}).setTimeout(0)
.on('error', (error) => {
callback(error);
});
request.write(requestBody)
request.end();
})((error, statusCode, body) => {
error ? console.log('request failed:', error) : console.log('request successful');
console.log('response status code:', statusCode);
console.log('response body:', body);
});
Example Response
{
"status": "OK"
}
Allows you to select and configure the goal used by the Fielding Assistant to manage your survey in field. Different goals represent different postures that you may have as a buyer towards the way you fill your survey. If in doubt the balanced goal is a good all rounder and is suitable for most ad hoc surveys.
Configuration Model
| Property | Type | Description |
|---|---|---|
| goal | string | Goal identifier. Call goals to obtain a list of available goals. |
| config | GoalConfig | Goal configuration for the selected goal. |
Goal configuration fields depend on which goal is selected. Details of GoalConfig fields can be found by calling goals. In the model below, the balanced_cpi configuration is described.
If a goal does not appear in your List Goals call, its availability or support cannot be guaranteed, even if it is documented here.
The start date behavior remains consistent across all goals: it triggers a “Live” status once the designated start timestamp is reached, remains it is not already live.
To transition from one goal to another, make a PUT request to the endpoint, and FA will incorporate the changes.
Balanced CPI Model
Manages the CPI of the survey to fill total quota by the specified completion deadline.
Once the goal is established, the survey_cpi_usd value cannot be modified.
| Property | Type | Description |
|---|---|---|
| total_budget | float | Total survey budget available to achieve quota fill, in the survey’s currency. |
| completion_timestamp | string | RFC3339 timestamp by which the survey should be completed. |
| start_timestamp | string (optional) | RFC3339 timestamp by which the survey should be started. |
Timeline Model
Manages status of the survey to set it live when the start timestamp occurs, and set it to a “pending” state (if it’s live) when the completion timestamp occurs.
| Property | Type | Description |
|---|---|---|
| completion_timestamp | string | RFC3339 timestamp by which the survey should be completed. |
| start_timestamp | string (optional) | RFC3339 timestamp by which the survey should be started. |
Even Pacing
Manages total and sub-quotas of the survey using Completes Goal specified in the survey. Even pacing tries to spread the completes across the duration of the fielding.
Once the goal is established, the quantity, quantity_calc_type values cannot be modified.
| Property | Type | Description |
|---|---|---|
| interval | string | Increment interval, must be divisible by 5 minutes. Pattern: ‘(^\d+)([mdh])$’. |
| completion_timestamp | string | RFC3339 timestamp by which the survey should be completed. |
| start_timestamp | string (optional) | RFC3339 timestamp by which the survey should be started. |
Dynamic Pacing
Manages total and sub-quotas of the survey using Completes Goal specified in the survey. Dynamic pacing tries to prevent the overfills. If a completion_timestamp is not supplied, it will automatically be set to 60 days after the current date.
Once the goal is established, the quantity, quantity_calc_type values cannot be modified.
| Property | Type | Description |
|---|---|---|
| completion_timestamp | string (optional) | RFC3339 timestamp by which the survey should be completed. |
| start_timestamp | string (optional) | RFC3339 timestamp by which the survey should be started. |
Interlocked Quota
Manages total and sub-quotas of the survey using Completes Goal specified in the survey. Interlocked Quotas goal ensures, that sub-quotas with the same question are filled at a similar pace.
Once the goal is established, the quantity, quantity_calc_type values cannot be modified.
| Property | Type | Description |
|---|---|---|
| completion_timestamp | string | RFC3339 timestamp by which the survey should be completed. |
| start_timestamp | string (optional) | RFC3339 timestamp by which the survey should be started. |
GET Survey Configuration by Survey ID
Obtain the Fielding Assistant configuration for a given Survey ID. If Fielding Assistant is not enabled on this survey id, a 404 Not Found HTTP response will be returned.
Definition
GET https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations/<int:survey_id>
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" "https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations/{survey_id}"
require 'net/http'
uri = URI("https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations/{survey_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations/{survey_id}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = "https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations/{survey_id}"
headers = {'Authorization' : 'YOUR_API_KEY_HERE'}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations/{survey_id}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "demand/v2/fielding-assistant/goals/configurations/{survey_id}",
"headers": {'Authorization': 'YOUR_API_KEY_HERE'}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"goal": "balanced_cpi",
"config": {
"completion_timestamp": "2020-09-01T13:37:00Z",
"total_budget": 25.5
}
}
Configuration Model
| Property | Type | Description |
|---|---|---|
| goal | string | Goal identifier. Call goals to obtain a list of available goals. |
| config | GoalConfig | Goal configuration for the selected goal. |
GoalConfig Model
Goal configuration fields depend on which goal is selected. Details of GoalConfig fields can be found by calling goals. In the model below, the balanced_cpi configuration is described.
| Property | Type | Description |
|---|---|---|
| total_budget | float | Total survey budget available to achieve quota fill, in the survey’s currency. |
| completion_timestamp | string | RFC3339 timestamp by which the survey should be completed. |
DELETE Fielding Assistant Configuration
Used to delete an existing Fielding Assistant survey configuration by providing the marketplace survey ID. On deletion, Fielding Assistant will no longer manage the survey and all current values will remain in the current state unless adjusted manually, or Fielding Assistant is re-enabled for the survey.
Definition
DELETE https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations/<int:survey_id>
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" -X DELETE "https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations/<int:survey_id>"
require 'net/http'
uri = URI("https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations/<int:survey_id>")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(uri.request_uri)
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations/<int:survey_id>";
$aHTTP['http']['method'] = 'DELETE';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = "https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations/<int:survey_id>"
headers = {'Authorization' : 'YOUR_API_KEY_HERE'}
response = requests.delete(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations/<int:survey_id>");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
request.Method = "DELETE";
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "DELETE",
"hostname": "api.samplicio.us",
"path": "/demand/v2/fielding-assistant/goals/configurations/<int:survey_id>",
"headers": {'Authorization': 'YOUR_API_KEY_HERE'}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"status": "OK"
}
GET List Fielding Assistant Enabled Survey IDs
Get a list of Fielding Assistant enabled surveys within the authenticated account.
Definition
GET https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" "https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations"
require 'net/http'
uri = URI("https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = "https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations"
headers = {'Authorization' : 'YOUR_API_KEY_HERE'}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2/fielding-assistant/goals/configurations");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/demand/v2/fielding-assistant/goals/configurations",
"headers": {'Authorization': 'YOUR_API_KEY_HERE'}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"assistant_enabled": [
{
"survey_id": 1
},
{
"survey_id": 2
},
{
"survey_id": 3
}
]
}
Configuration Model
| Property | Type | Description |
|---|---|---|
| assistant_enabled | array[AssistantEnabled] | A list of survey IDs for which the survey Fielding Assistant is currently enabled. |
AssistantEnabled Model
| Property | Type | Description |
|---|---|---|
| survey_id | int | Marketplace survey ID for which the survey Fielding Assistant is enabled. |
GET Check Enabled
Developers may wish to check the Fielding Assistant status of a list of surveys, perhaps for building a survey dashboard. This endpoint returns the same number of valid items in its output that are passed in the input, even if some of the surveys do not have the Assistant enabled. If a developer sends a Survey ID that isn’t visible to their account that ID is removed from the output. Surveys are returned in Survey ID ascending order.
Definition
GET https://api.samplicio.us/demand/v2/fielding-assistant/goals/check-enabled
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" "https://api.samplicio.us/demand/v2/fielding-assistant/goals/check-enabled?survey_ids=104383,99877"
require 'net/http'
uri = URI("https://api.samplicio.us/demand/v2/fielding-assistant/goals/check-enabled?survey_ids=104383,99877")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/demand/v2/fielding-assistant/goals/check-enabled?survey_ids=104383,99877";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = "https://api.samplicio.us/demand/v2/fielding-assistant/goals/check-enabled?survey_ids=104383,99877"
headers = {'Authorization' : 'YOUR_API_KEY_HERE'}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2/fielding-assistant/goals/check-enabled?survey_ids=104383,99877");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/demand/v2/fielding-assistant/goals/check-enabled?survey_ids=104383,99877",
"headers": {'Authorization': 'YOUR_API_KEY_HERE'}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"surveys_enabled": [
{
"survey_id": 99877,
"enabled": true
},
{
"survey_id": 104383,
"enabled": true
}
]
}
Query Arguments
| Property | Data Type | Description |
|---|---|---|
| survey_ids | string | List of comma separated Survey IDs. Surveys must be visible to the account making the request. |
CheckEnabled Result Model
| Property | Type | Description |
|---|---|---|
| surveys_enabled | array[SurveysEnabled] | A list of Survey IDs and if a Fielding Assistant goal is enabled on the survey. |
SurveysEnabled Model
| Property | Type | Description |
|---|---|---|
| survey_id | int | Marketplace survey ID. |
| enabled | boolean | Fielding Assistant status. |
Audience Templates
Audience Templates allow you to reuse previously created set of qualifications and quotas. You can create, use and save your own templates based either on custom audiences you use a lot (e.g. Marketing Consultants, Cat Owners etc.) or for your own versions of a common audience (e.g. ‘My Special German Gen Pop’) that may have different qualifications or breaks.
This part of the API allows you to store, modify, retrieve and archive Audience Templates.
Global and Account templates
There are two types of templates: Global and Account.
Global templates are accessible to anyone. They are the same for everyone in each locale. You cannot delete or modify them. A good example of a global template would be the US census representation template.
Account templates are templates that belong to a specific account and are created by you, or other users inside the same account. You can rename, edit and archive a template as you see fit.
If you make changes to a template, the previous version will be stored if you ever want to restore it. The 10 latest versions of the templates are available to be restored.
Scopes
You can query for global or account templates using scopes in your requests.
When you are retrieving the templates, you can use the scopes parameter to
filter the templates according to their type. For example, using ?scopes=account:123,account:345
would return templates for accounts 123 and 345. If you do not have the right
permissions to access to the templates from these accounts, you will get an error.
If you don’t specify accounts in your scope, you’ll get all the templates for
all the accounts that you are associated with. For example, if you are part of
accounts 123 and 456, ?scopes=account would be equivalent to
?scopes=account:123,account:456.
It is also possible to combine global and account filters.
Pagination
Some of the endpoints allow to specify a page GET parameter, which is a
number specifying the page to retrieve.
Locales
You can query the templates via locales using the locales parameter in the
endpoints that support it. You can query against multiple locales by separating
them by commas. For example, using ?locales=eng_gb,eng_us would return all the
templates you have access to that are targeting “English - Great Britain” and “English - United States”.
Importing qualifications and quotas to create a template from a survey
You can create a template out of your surveys if you find the quotas and qualifications on the survey useful. This can save you time when you are launching a new survey that should have a similar target audience. You have the option to either import both the quotas and qualifications from a survey, or just the qualifications.
Template Model
| Property | Type | Description |
|---|---|---|
| uuid | UUID | UUID for this template. |
| description | String | Template description. |
| name | String | Template name. |
| label | String | Template label. |
| country_languages | array[String] | Template locales (normalized). |
| qualifications | array[Qualification] | List of template qualifications. |
| quotas | array [Quota] | List of template quotas. |
| created_at | String | Creation timestamp (RFC3339 format). |
| updated_at | String | Updated timestamp (RFC3339 format). |
| created_by | UUID | UUID of the user who created it. |
| updated_by | UUID | UUID of the user who last updated the template. |
Qualification Model
| Property | Type | Description |
|---|---|---|
| name | String | Qualification name. |
| description | String | Qualification description. |
| question_id | Integer | Qualification question ID. |
| precodes | Precodes | Precodes for this qualification. |
| order | Integer | Order in which this qualification is evaluated. |
| country_languages | array[String] | List of locales this qualification applies to. |
Quota Model
| Property | Type | Description |
|---|---|---|
| name | String | Name of the quota. |
| conditions | array[QuotaCondition] | Conditions for the quota. |
QuotaCondition Model
| Property | Type | Description |
|---|---|---|
| question_id | Integer | Question ID for the condition. |
| precodes | Precodes | Precodes for the condition. |
Precodes Model
| Property | Type | Description |
|---|---|---|
| type | String | Precode type. Valid values are range and selection. |
| values | array[String] | Precode values. |
Create template from survey Model
| Property | Type | Description |
|---|---|---|
| account_id | Integer | The ID of the account the newly created template will belong to. |
| survey_id | Integer | The ID of the survey whose data will be used for the new template. |
| name | String | The name for the new template. |
| label | String | Label for the new template. |
| description | String | Description for the new template. |
| mode | String | How to create the new template. Valid values are quotas_and_quals and quals_only. |
{
"template": {
"uuid": "639d12e7-ae66-4f16-a84e-000000000000",
"description": "Source: United States Census Bureau (2020)",
"name": "census-representation",
"label": "Census Representation",
"country_languages": [
"eng_us",
"spa_us"
],
"qualifications": [
{
"name": "age",
"description": "18 years old or older",
"question_id": 42,
"precodes": {
"type": "range",
"values": [
"18",
"99"
]
},
"order": 0
}
],
"quotas": [
{
"name": "18 to 24 years old",
"conditions": [
{
"question_id": 42,
"precodes": {
"type": "range",
"values": [
"18",
"24"
]
}
}
],
"percentage": 11.9
},
{
"name": "25 to 34 years old",
"conditions": [
{
"question_id": 42,
"precodes": {
"type": "range",
"values": [
"25",
"34"
]
}
}
],
"percentage": 17.85
}
],
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "2023-01-11T16:05:03.95573Z",
"created_by": "00000000-0000-0000-0000-000000000000",
"updated_by": "00000000-0000-0000-0000-000000000000"
}
}
Template Version Model
| Property | Type | Description |
|---|---|---|
| version_id | UUID | ID of this version. |
| outdated_at | String | Time at which this version was superseded (RFC3339 format). |
| template | Template | Template data before it was overwritten. |
GET List Templates
Return a paginated list of available templates in the form of a summary. Returns 100 summaries per page.
This endpoint accepts the scopes, locale and page GET parameters.
Definition
GET https://api.samplicio.us/demand/v2-beta/audience-templates
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" "https://api.samplicio.us/demand/v2-beta/audience-templates"
require 'net/http'
uri = URI("https://api.samplicio.us/demand/v2-beta/audience-templates")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/demand/v2-beta/audience-templates";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = "https://api.samplicio.us/demand/v2-beta/audience-templates"
headers = {'Authorization' : 'YOUR_API_KEY_HERE'}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/audience-templates");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "demand/v2-beta/audience-templates",
"headers": {'Authorization': 'YOUR_API_KEY_HERE'}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"number_of_items_total": 59,
"items": [
{
"uuid": "639d12e7-ae66-4f16-a84e-000000000000",
"label": "Census Representation",
"name": "census-representation",
"description": "Source: United States Census Bureau (2020)",
"scope": "global",
"locales": [
"eng_us",
"spa_us"
],
"account_ids": []
}
]
}
Template Summary Model
| Property | Type | Description |
|---|---|---|
| uuid | UUID | The unique identifier for this template. |
| label | String | The label for this template. |
| name | String | The name for this template. |
| description | String | The description for this template. |
| scope | String | The scope this template belongs to. |
| locales | array[String] | The locales this template belongs to. |
| account_ids | array[Integer] | The account IDs this template belongs to. If empty, the template is global. |
POST Create Template
Create a new template.
Definition
POST https://api.samplicio.us/demand/v2-beta/audience-templates
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X POST --data '{"description":"Source: United States Census Bureau (2020)","name":"census-representation","label":"Census Representation","country_languages":["eng_us","spa_us"],"qualifications":[{"name":"age","description":"18 years old or older","question_id":42,"precodes":{"type":"range","values":["18","99"]},"order":0}],"quotas":[{"name":"18 to 24 years old","conditions":[{"question_id":42,"precodes":{"type":"range","values":["18","24"]}}],"percentage":11.9}]}' https://api.samplicio.us/demand/v2-beta/audience-templates
require 'net/http'
require 'json'
def create_template
api_key = YOUR_API_KEY_HERE
request_body = {
"description" => "Source: United States Census Bureau (2020)",
"name" => "census-representation",
"label" => "Census Representation",
"country_languages" => [
"eng_us",
"spa_us"
],
"qualifications" => [{
"name" => "age",
"description" => "18 years old or older",
"question_id" => 42,
"precodes" => {
"type" => "range",
"values" => [
"18",
"99"
]
},
"order" => 0
}],
"quotas" => [{
"name" => "18 to 24 years old",
"conditions" => [{
"question_id" => 42,
"precodes" => {
"type" => "range",
"values" => [
"18",
"24"
]
}
}],
"percentage" => 11.9
}]
}
uri = URI("https://api.samplicio.us/demand/v2-beta/audience-templates")
request = Net::HTTP::Post.new(uri)
request.add_field "Content-Type", "application/json"
request.add_field "Authorization", api_key
request.body = JSON.dump(request_body)
response = Net::HTTP.new(uri.host, uri.port).request(request)
puts "response status code: #{response.code}"
puts "response body: #{response.body}"
rescue StandardError => e
puts "request failed (#{e.message})"
end
create_template
<?php
$api_key = YOUR_API_KEY_HERE;
$request_body = '{
"description":"Source: United States Census Bureau (2020)",
"name":"census-representation",
"label":"Census Representation",
"country_languages":[
"eng_us",
"spa_us"
],
"qualifications":[
{
"name":"age",
"description":"18 years old or older",
"question_id":42,
"precodes":{
"type":"range",
"values":[
"18",
"99"
]
},
"order":0
}
],
"quotas":[
{
"name":"18 to 24 years old",
"conditions":[
{
"question_id":42,
"precodes":{
"type":"range",
"values":[
"18",
"24"
]
}
}
],
"percentage":11.9
}
]
}';
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.samplicio.us/demand/v2-beta/audience-templates",
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Authorization: " . $api_key,
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $request_body,
]);
$response = curl_exec($curl);
if (!$response) {
die(
'request failed: "' .
curl_error($curl) .
'", code: ' .
curl_errno($curl)
);
}
echo "response status code: " .
curl_getinfo($curl, CURLINFO_HTTP_CODE) .
PHP_EOL;
echo "response body: " . $response . PHP_EOL;
curl_close($curl);
import requests
import json
def create_template():
api_key = YOUR_API_KEY_HERE
request_body = {'description': 'Source: United States Census Bureau (2020)', 'name': 'census-representation', 'label': 'Census Representation', 'country_languages': ['eng_us', 'spa_us'], 'qualifications': [{'name': 'age', 'description': '18 years old or older', 'question_id': 42, 'precodes': {'type': 'range', 'values': ['18', '99']}, 'order': 0}], 'quotas': [{'name': '18 to 24 years old', 'conditions': [{'question_id': 42, 'precodes': {'type': 'range', 'values': ['18', '24']}}], 'percentage': 11.9}]}
try:
response = requests.post(
url=f"https://api.samplicio.us/demand/v2-beta/audience-templates",
headers={
"Content-Type": "application/json",
"Authorization": api_key,
},
data=json.dumps(request_body)
)
print('response status code: {status_code}'.format(
status_code=response.status_code))
print('response body: {content}'.format(
content=response.content))
except requests.exceptions.RequestException:
print('request failed')
create_template()
using System;
using System.Threading.Tasks;
using System.Net;
using System.IO;
using System.Text;
namespace Lucid {
public class AudienceTemplates {
private async Task<bool> CreateAudienceTemplate () {
string apiKey = YOUR_API_KEY_HERE;
string requestBody = @"{
""description"": ""Source: United States Census Bureau (2020)"",
""name"": ""census-representation"",
""label"": ""Census Representation"",
""country_languages"": [
""eng_us"",
""spa_us""
],
""qualifications"": [
{
""name"": ""age"",
""description"": ""18 years old or older"",
""question_id"": 42,
""precodes"": {
""type"": ""range"",
""values"": [
""18"",
""99""
]
},
""order"": 0
}
],
""quotas"": [
{
""name"": ""18 to 24 years old"",
""conditions"": [
{
""question_id"": 42,
""precodes"": {
""type"": ""range"",
""values"": [
""18"",
""24""
]
}
}
],
""percentage"": 11.9
}
]
}";
HttpWebRequest request = (HttpWebRequest)WebRequest.Create (new Uri("https://api.samplicio.us/demand/v2-beta/audience-templates"));
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", apiKey);
ASCIIEncoding encoding = new ASCIIEncoding ();
byte[] byte1 = encoding.GetBytes (requestBody);
request.ContentLength = byte1.Length;
Stream newStream = request.GetRequestStream ();
newStream.Write (byte1, 0, byte1.Length);
newStream.Close ();
using (WebResponse response = await request.GetResponseAsync ()) {
using (Stream stream = response.GetResponseStream ()) {
// Process the API response.
return true;
}
}
}
}
}
(function (callback) {
'use strict';
let apiKey = "YOUR_API_KEY_HERE"
let requestBody = JSON.stringify({
"description": "Source: United States Census Bureau (2020)",
"name": "census-representation",
"label": "Census Representation",
"country_languages": [
"eng_us",
"spa_us"
],
"qualifications": [
{
"name": "age",
"description": "18 years old or older",
"question_id": 42,
"precodes": {
"type": "range",
"values": [
"18",
"99"
]
},
"order": 0
}
],
"quotas": [
{
"name": "18 to 24 years old",
"conditions": [
{
"question_id": 42,
"precodes": {
"type": "range",
"values": [
"18",
"24"
]
}
}
],
"percentage": 11.9
}
]
});
const https = require('https');
const responseEncoding = 'utf8';
const httpOptions = {
hostname: 'api.samplicio.us',
port: '443',
path: '/demand/v2-beta/audience-templates',
method: 'POST',
headers: {"Content-Type": "application/json", "Authorization": apiKey}
};
httpOptions.headers['User-Agent'] = 'node ' + process.version;
const request = https.request(httpOptions, (res) => {
let responseBuffer = [];
let responseBody = '';
res.on('data', (chunk) => {
if (Buffer.isBuffer(chunk)) {
responseBuffer.push(chunk);
} else {
responseBody = responseBody + chunk;
}
}).on('end', () => {
responseBody = responseBuffer.length > 0 ?
Buffer.concat(responseBuffer).toString(responseEncoding) : responseBody;
callback(null, res.statusCode, responseBody);
})
}).setTimeout(0)
.on('error', (error) => {
callback(error);
});
request.write(requestBody)
request.end();
})((error, statusCode, body) => {
error ? console.log('request failed:', error) : console.log('request successful');
console.log('response status code:', statusCode);
console.log('response body:', body);
});
Example Response
{
"template": {
"uuid": "639d12e7-ae66-4f16-a84e-000000000000",
"description": "Source: United States Census Bureau (2020)",
"name": "census-representation",
"label": "Census Representation",
"country_languages": [
"eng_us",
"spa_us"
],
"qualifications": [
{
"name": "age",
"description": "18 years old or older",
"question_id": 42,
"precodes": {
"type": "range",
"values": [
"18",
"99"
]
},
"order": 0
}
],
"quotas": [
{
"name": "18 to 24 years old",
"conditions": [
{
"question_id": 42,
"precodes": {
"type": "range",
"values": [
"18",
"24"
]
}
}
],
"percentage": 11.9
}
],
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "2023-01-11T16:05:03.95573Z",
"created_by": "00000000-0000-0000-0000-000000000000",
"updated_by": "00000000-0000-0000-0000-000000000000"
}
}
PUT Update a template
Make changes to a template. Note that this endpoint is PUT, meaning that the whole template needs to be sent. It won’t do partial updates to specific fields, only replace the whole resource.
Definition
PUT https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X PUT --data '{"description":"Source: United States Census Bureau (2020)","name":"census-representation","label":"Census Representation","country_languages":["eng_us","spa_us"],"qualifications":[{"name":"age","description":"18 years old or older","question_id":42,"precodes":{"type":"range","values":["18","99"]},"order":0}],"quotas":[{"name":"18 to 24 years old","conditions":[{"question_id":42,"precodes":{"type":"range","values":["18","24"]}}],"percentage":11.9}]}' https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}
require 'net/http'
require 'json'
def update_template(template_id)
api_key = YOUR_API_KEY_HERE
request_body = {
"description" => "Source: United States Census Bureau (2020)",
"name" => "census-representation",
"label" => "Census Representation",
"country_languages" => [
"eng_us",
"spa_us"
],
"qualifications" => [{
"name" => "age",
"description" => "18 years old or older",
"question_id" => 42,
"precodes" => {
"type" => "range",
"values" => [
"18",
"99"
]
},
"order" => 0
}],
"quotas" => [{
"name" => "18 to 24 years old",
"conditions" => [{
"question_id" => 42,
"precodes" => {
"type" => "range",
"values" => [
"18",
"24"
]
}
}],
"percentage" => 11.9
}]
}
uri = URI("https://api.samplicio.us/demand/v2-beta/audience-templates/#{template_id}")
request = Net::HTTP::Put.new(uri)
request.add_field "Content-Type", "application/json"
request.add_field "Authorization", api_key
request.body = JSON.dump(request_body)
response = Net::HTTP.new(uri.host, uri.port).request(request)
puts "response status code: #{response.code}"
puts "response body: #{response.body}"
rescue StandardError => e
puts "request failed (#{e.message})"
end
update_template({template_id})
<?php
$api_key = YOUR_API_KEY_HERE;
$request_body = '{
"description" => "Source: United States Census Bureau (2020)",
"name" => "census-representation",
"label" => "Census Representation",
"country_languages" => [
"eng_us",
"spa_us"
],
"qualifications" => [{
"name" => "age",
"description" => "18 years old or older",
"question_id" => 42,
"precodes" => {
"type" => "range",
"values" => [
"18",
"99"
]
},
"order" => 0
}],
"quotas" => [{
"name" => "18 to 24 years old",
"conditions" => [{
"question_id" => 42,
"precodes" => {
"type" => "range",
"values" => [
"18",
"24"
]
}
}],
"percentage" => 11.9
}]
}';
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}",
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Authorization: " . $api_key,
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_POSTFIELDS => $request_body,
]);
$response = curl_exec($curl);
if (!$response) {
die(
'request failed: "' .
curl_error($curl) .
'", code: ' .
curl_errno($curl)
);
}
echo "response status code: " .
curl_getinfo($curl, CURLINFO_HTTP_CODE) .
PHP_EOL;
echo "response body: " . $response . PHP_EOL;
curl_close($curl);
import requests
import json
def update_template():
api_key = 'YOUR_API_KEY_HERE'
template_id = '{template_id}'
request_body = {'description': 'Source: United States Census Bureau (2020)', 'name': 'census-representation', 'label': 'Census Representation', 'country_languages': ['eng_us', 'spa_us'], 'qualifications': [{'name': 'age', 'description': '18 years old or older', 'question_id': 42, 'precodes': {'type': 'range', 'values': ['18', '99']}, 'order': 0}], 'quotas': [{'name': '18 to 24 years old', 'conditions': [{'question_id': 42, 'precodes': {'type': 'range', 'values': ['18', '24']}}], 'percentage': 11.9}]}
try:
response = requests.put(
url=f"https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}",
headers={
"Content-Type": "application/json",
"Authorization": api_key,
},
data=json.dumps(request_body)
)
print('response status code: {status_code}'.format(
status_code=response.status_code))
print('response body: {content}'.format(
content=response.content))
except requests.exceptions.RequestException:
print('request failed')
update_template()
using System;
using System.Threading.Tasks;
using System.Net;
using System.IO;
using System.Text;
namespace Lucid {
public class AudienceTemplates {
private async Task<bool> UpdateAudienceTemplate () {
string apiKey = YOUR_API_KEY_HERE;
string requestBody = @"{
""description"": ""Source: United States Census Bureau (2020)"",
""name"": ""census-representation"",
""label"": ""Census Representation"",
""country_languages"": [
""eng_us"",
""spa_us""
],
""qualifications"": [
{
""name"": ""age"",
""description"": ""18 years old or older"",
""question_id"": 42,
""precodes"": {
""type"": ""range"",
""values"": [
""18"",
""99""
]
},
""order"": 0
}
],
""quotas"": [
{
""name"": ""18 to 24 years old"",
""conditions"": [
{
""question_id"": 42,
""precodes"": {
""type"": ""range"",
""values"": [
""18"",
""24""
]
}
}
],
""percentage"": 11.9
}
]
}";
HttpWebRequest request = (HttpWebRequest)WebRequest.Create (new Uri("https://api.samplicio.us/demand/v2-beta/audience-templates/{templateId}"));
request.Method = "PUT";
request.ContentType = "application/json";
request.Headers.Add("Authorization", apiKey);
ASCIIEncoding encoding = new ASCIIEncoding ();
byte[] byte1 = encoding.GetBytes (requestBody);
request.ContentLength = byte1.Length;
Stream newStream = request.GetRequestStream ();
newStream.Write (byte1, 0, byte1.Length);
newStream.Close ();
using (WebResponse response = await request.GetResponseAsync ()) {
using (Stream stream = response.GetResponseStream ()) {
// Process the API response.
return true;
}
}
}
}
}
(function (callback) {
'use strict';
let apiKey = "YOUR_API_KEY_HERE"
let templateId = "YOUR_TEMPLATE_ID_HERE"
let requestBody = JSON.stringify({
"description": "Source: United States Census Bureau (2020)",
"name": "census-representation",
"label": "Census Representation",
"country_languages": [
"eng_us",
"spa_us"
],
"qualifications": [
{
"name": "age",
"description": "18 years old or older",
"question_id": 42,
"precodes": {
"type": "range",
"values": [
"18",
"99"
]
},
"order": 0
}
],
"quotas": [
{
"name": "18 to 24 years old",
"conditions": [
{
"question_id": 42,
"precodes": {
"type": "range",
"values": [
"18",
"24"
]
}
}
],
"percentage": 11.9
}
]
});
const https = require('https');
const responseEncoding = 'utf8';
const httpOptions = {
hostname: 'api.samplicio.us',
port: '443',
path: `/demand/v2-beta/audience-templates/${templateId}`,
method: 'PUT',
headers: {"Content-Type": "application/json", "Authorization": apiKey}
};
httpOptions.headers['User-Agent'] = 'node ' + process.version;
const request = https.request(httpOptions, (res) => {
let responseBuffer = [];
let responseBody = '';
res.on('data', (chunk) => {
if (Buffer.isBuffer(chunk)) {
responseBuffer.push(chunk);
} else {
responseBody = responseBody + chunk;
}
}).on('end', () => {
responseBody = responseBuffer.length > 0 ?
Buffer.concat(responseBuffer).toString(responseEncoding) : responseBody;
callback(null, res.statusCode, responseBody);
})
}).setTimeout(0)
.on('error', (error) => {
callback(error);
});
request.write(requestBody)
request.end();
})((error, statusCode, body) => {
error ? console.log('request failed:', error) : console.log('request successful');
console.log('response status code:', statusCode);
console.log('response body:', body);
});
Example Response
{
"template": {
"uuid": "639d12e7-ae66-4f16-a84e-000000000000",
"description": "Source: United States Census Bureau (2020)",
"name": "census-representation",
"label": "Census Representation",
"country_languages": [
"eng_us",
"spa_us"
],
"qualifications": [
{
"name": "age",
"description": "18 years old or older",
"question_id": 42,
"precodes": {
"type": "range",
"values": [
"18",
"99"
]
},
"order": 0
}
],
"quotas": [
{
"name": "18 to 24 years old",
"conditions": [
{
"question_id": 42,
"precodes": {
"type": "range",
"values": [
"18",
"24"
]
}
}
],
"percentage": 11.9
}
],
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "2023-01-11T16:05:03.95573Z",
"created_by": "00000000-0000-0000-0000-000000000000",
"updated_by": "00000000-0000-0000-0000-000000000000"
}
}
DELETE Template
Delete a template. When a template is deleted the old versions are also deleted.
Definition
DELETE https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" -X DELETE "https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}"
require 'net/http'
uri = URI("https://api.samplicio.us/demand/v2-beta/audience-templates/#{template_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(uri.request_uri)
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}";
$aHTTP['http']['method'] = 'DELETE';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = "https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}"
headers = {'Authorization' : 'YOUR_API_KEY_HERE'}
response = requests.delete(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
request.Method = "DELETE";
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "DELETE",
"hostname": "api.samplicio.us",
"path": "/demand/v2-beta/audience-templates/{template_id}",
"headers": {'Authorization': 'YOUR_API_KEY_HERE'}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
204 No Content
GET List Template Versions
Get a list of template versions.
Definition
GET https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}/versions
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" "https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}/versions"
require 'net/http'
uri = URI("https://api.samplicio.us/demand/v2-beta/audience-templates/#{template_id}/versions")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}/versions";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = "https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}/versions"
headers = {'Authorization' : 'YOUR_API_KEY_HERE'}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}/versions");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/demand/v2-beta/audience-templates/{template_id}/versions",
"headers": {'Authorization': 'YOUR_API_KEY_HERE'}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"old_versions": [
{
"uuid": "98eec93f-b095-4cfb-ad0d-000000000000",
"template_id": "935babfc-60c1-44a6-a8e0-000000000000",
"outdated_at": "2023-03-15T14:23:04.822209Z",
"template": {
"uuid": "935babfc-60c1-44a6-a8e0-000000000000",
"description": "test",
"name": "test",
"label": "cat",
"account_ids": [
1015
],
"country_languages": [
"eng_us"
],
"qualifications": [
{
"name": "",
"description": "test",
"question_id": 42,
"precodes": {
"type": "range",
"values": [
"18",
"24"
]
},
"order": 0,
"country_languages": [
"eng_us"
]
}
],
"quotas": [
{
"name": "18 to 24 years old",
"conditions": [
{
"question_id": 42,
"precodes": {
"type": "range",
"values": [
"18",
"24"
]
}
}
],
"percentage": 11.9
}
],
"created_at": "2023-03-15T14:20:00.535363Z",
"updated_at": "2023-03-15T14:20:00.535363Z",
"created_by": "9c82efce-b27c-4a9d-b7ca-000000000000",
"updated_by": "9c82efce-b27c-4a9d-b7ca-000000000000"
}
}
]
}
GET Template Version
Get a template version.
Definition
GET https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}/versions/{version_id}"
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" "https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}/versions/{version_id}"
require 'net/http'
uri = URI("https://api.samplicio.us/demand/v2-beta/audience-templates/#{template_id}/versions/#{version_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}/versions/{version_id}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = "https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}/versions/{version_id}"
headers = {'Authorization' : 'YOUR_API_KEY_HERE'}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}/versions/{version_id}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/demand/v2-beta/audience-templates/{template_id}/versions/{version_id}",
"headers": {'Authorization': 'YOUR_API_KEY_HERE'}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"uuid": "98eec93f-b095-4cfb-ad0d-000000000000",
"template_id": "935babfc-60c1-44a6-a8e0-000000000000",
"outdated_at": "2023-03-15T14:23:04.822209Z",
"template": {
"uuid": "935babfc-60c1-44a6-a8e0-000000000000",
"description": "test",
"name": "test",
"label": "cat",
"account_ids": [
1015
],
"country_languages": [
"eng_us"
],
"qualifications": [
{
"name": "",
"description": "test",
"question_id": 42,
"precodes": {
"type": "range",
"values": [
"18",
"24"
]
},
"order": 0,
"country_languages": [
"eng_us"
]
}
],
"quotas": [
{
"name": "18 to 24 years old",
"conditions": [
{
"question_id": 42,
"precodes": {
"type": "range",
"values": [
"18",
"24"
]
}
}
],
"percentage": 11.9
}
],
"created_at": "2023-03-15T14:20:00.535363Z",
"updated_at": "2023-03-15T14:20:00.535363Z",
"created_by": "9c82efce-b27c-4a9d-b7ca-000000000000",
"updated_by": "9c82efce-b27c-4a9d-b7ca-000000000000"
}
}
POST Restore version
Makes the old version the current template, and pushes the current template to the old versions. The body of the request must be empty.
Definition
POST https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}/versions/{version_id}/restore
Example Request
curl -XPOST -H "Authorization: YOUR_API_KEY_HERE" "https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}/versions/{version_id}/restore"
require 'net/http'
uri = URI("https://api.samplicio.us/demand/v2-beta/audience-templates/#{template_id}/versions/#{version_id}/restore")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.request_uri)
request['Authorization'] = "YOUR_API_KEY_HERE"
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}/versions/{version_id}/restore";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = "https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}/versions/{version_id}/restore"
headers = {'Authorization' : 'YOUR_API_KEY_HERE'}
response = requests.post(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/demand/v2-beta/audience-templates/{template_id}/versions/{version_id}/restore");
request.Method = "POST";
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "POST",
"hostname": "api.samplicio.us",
"path": "/demand/v2-beta/audience-templates/{template_id}/versions/{version_id}/restore",
"headers": {'Authorization': 'YOUR_API_KEY_HERE'}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"uuid": "98eec93f-b095-4cfb-ad0d-000000000000",
"template_id": "935babfc-60c1-44a6-a8e0-000000000000",
"outdated_at": "2023-03-15T14:23:04.822209Z",
"template": {
"uuid": "935babfc-60c1-44a6-a8e0-000000000000",
"description": "test",
"name": "test",
"label": "cat",
"account_ids": [
1015
],
"country_languages": [
"eng_us"
],
"qualifications": [
{
"name": "",
"description": "test",
"question_id": 42,
"precodes": {
"type": "range",
"values": [
"18",
"24"
]
},
"order": 0,
"country_languages": [
"eng_us"
]
}
],
"quotas": [
{
"name": "18 to 24 years old",
"conditions": [
{
"question_id": 42,
"precodes": {
"type": "range",
"values": [
"18",
"24"
]
}
}
],
"percentage": 11.9
}
],
"created_at": "2023-03-15T14:20:00.535363Z",
"updated_at": "2023-03-15T14:20:00.535363Z",
"created_by": "9c82efce-b27c-4a9d-b7ca-000000000000",
"updated_by": "9c82efce-b27c-4a9d-b7ca-000000000000"
}
}
POST Create Template from Survey
Create a new template based on the setup of a survey.
Definition
POST https://api.samplicio.us/demand/v2-beta/audience-templates/from-survey
Example Request
curl -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY_HERE" -X POST --data '{"account_id":1,"survey_id":1234,"mode":"quotas_and_quals","description":"my template","name":"my-template","label":"my template"}' https://api.samplicio.us/demand/v2-beta/audience-templates/from-survey
require 'net/http'
require 'json'
def create_template_from_survey
api_key = "YOUR_API_KEY_HERE"
request_body = {
"account_id" => 1,
"survey_id" => 1234,
"mode" => "quotas_and_quals",
"description" => "my template",
"name" => "my-template",
"label" => "my template"
}
uri = URI("https://api.samplicio.us/demand/v2-beta/audience-templates/from-survey")
request = Net::HTTP::Post.new(uri)
request.add_field "Content-Type", "application/json"
request.add_field "Authorization", api_key
request.body = JSON.dump(request_body)
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts "response status code: #{response.code}"
puts "response body: #{response.body}"
rescue StandardError => e
puts "request failed (#{e.message})"
end
create_template_from_survey
<?php
$api_key = 'YOUR_API_KEY_HERE';
$request_body = '{
"account_id":1,
"survey_id":1234,
"mode":"quotas_and_quals",
"description":"my template",
"name":"my-template",
"label":"my template"
}';
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.samplicio.us/demand/v2-beta/audience-templates/from-survey",
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Authorization: " . $api_key,
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $request_body,
]);
$response = curl_exec($curl);
if (!$response) {
die(
'request failed: "' .
curl_error($curl) .
'", code: ' .
curl_errno($curl)
);
}
echo "response status code: " .
curl_getinfo($curl, CURLINFO_HTTP_CODE) .
PHP_EOL;
echo "response body: " . $response . PHP_EOL;
curl_close($curl);
import requests
import json
def create_from_survey():
api_key = "YOUR_API_KEY_HERE"
request_body = {
"account_id": 1,
"survey_id": 1234,
"mode": "quotas_and_quals",
"description": "my template",
"name": "my-template",
"label": "my template"
}
try:
response = requests.post(
url="https://api.samplicio.us/demand/v2-beta/audience-templates/from-survey",
headers={
"Content-Type": "application/json",
"Authorization": api_key,
},
data=json.dumps(request_body)
)
print('response status code: {status_code}'.format(
status_code=response.status_code))
print('response body: {content}'.format(
content=response.content))
except requests.exceptions.RequestException:
print('request failed')
create_from_survey()
using System;
using System.Net;
using System.IO;
using System.Text;
namespace YourNamespace
{
public class YourClassName
{
private async Task<bool> CreateAudienceTemplate()
{
string apiKey = "YOUR_API_KEY_HERE";
string requestBody = @"{
""account_id"":1,
""survey_id"":1234,
""mode"":""quotas_and_quals"",
""description"":""my template"",
""name"":""my-template"",
""label"":""my template""
}";
HttpWebRequest request = (HttpWebRequest)WebRequest.Create("https://api.samplicio.us/demand/v2-beta/audience-templates/from-survey");
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", apiKey);
ASCIIEncoding encoding = new ASCIIEncoding();
byte[] byte1 = encoding.GetBytes(requestBody);
request.ContentLength = byte1.Length;
Stream newStream = request.GetRequestStream();
newStream.Write(byte1, 0, byte1.Length);
newStream.Close();
using (WebResponse response = await request.GetResponseAsync())
{
using (Stream stream = response.GetResponseStream())
{
// Process the API response.
return true;
}
}
}
}
}
(function (callback) {
'use strict';
let apiKey = "YOUR_API_KEY_HERE"
let requestBody = JSON.stringify({
"account_id": 1,
"survey_id": 1234,
"mode": "quotas_and_quals",
"description": "my template",
"name": "my-template",
"label": "my template"
});
const https = require('https');
const responseEncoding = 'utf8';
const httpOptions = {
hostname: 'api.samplicio.us',
port: '443',
path: '/demand/v2-beta/audience-templates/from-survey',
method: 'POST',
headers: {"Content-Type": "application/json", "Authorization": apiKey}
};
httpOptions.headers['User-Agent'] = 'node ' + process.version;
const request = https.request(httpOptions, (res) => {
let responseBuffer = [];
let responseBody = '';
res.on('data', (chunk) => {
if (Buffer.isBuffer(chunk)) {
responseBuffer.push(chunk);
} else {
responseBody = responseBody + chunk;
}
}).on('end', () => {
responseBody = responseBuffer.length > 0 ?
Buffer.concat(responseBuffer).toString(responseEncoding) : responseBody;
callback(null, res.statusCode, responseBody);
})
}).setTimeout(0)
.on('error', (error) => {
callback(error);
});
request.write(requestBody)
request.end();
})((error, statusCode, body) => {
error ? console.log('request failed:', error) : console.log('request successful');
console.log('response status code:', statusCode);
console.log('response body:', body);
});
Example Response
{
"template": {
"uuid": "639d12e7-ae66-4f16-a84e-000000000000",
"description": "my template",
"name": "my-template",
"label": "my template",
"country_languages": [
"eng_us",
"spa_us"
],
"qualifications": [
{
"name": "age",
"description": "18 years old or older",
"question_id": 42,
"precodes": {
"type": "range",
"values": [
"18",
"99"
]
},
"order": 0
}
],
"quotas": [
{
"name": "18 to 24 years old",
"conditions": [
{
"question_id": 42,
"precodes": {
"type": "range",
"values": [
"18",
"24"
]
}
}
],
"percentage": 11.9
}
],
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "2023-01-11T16:05:03.95573Z",
"created_by": "00000000-0000-0000-0000-000000000000",
"updated_by": "00000000-0000-0000-0000-000000000000"
}
}
Supply Integration (Legacy)
Surveys
The Survey resource contains basic information about a survey opportunity posted by a sample buyer. More detailed information about who qualifies for the survey is contained in the Qualifications and Quotas resources. These properties may return Null: BidIncidence, BidLengthOfInterview, IndustryID, and StudyTypeID.
Surveys Model
| Property | Type | Description |
|---|---|---|
| SurveyName | string | External name of the survey. This name may be exposed to respondents. This value is not unique across surveys. Maximum length of 128. |
| SurveyNumber | int | Unique number associated with the survey. |
| SurveySID | string | Unique hash value (GUID) associated with the survey. |
| AccountName | string | Name of the buyer running the survey. Maximum length of 64. |
| CountryLanguageID | int | Unique id associated with the Country-Language pair the survey is open to. |
| LengthOfInterview | int | Median time for a respondent to complete the survey excluding the Marketplace prescreener in minutes. This value is calculated after six completes and rounded to the nearest whole number. Until six completes are achieved the value will be zero. |
| BidIncidence | double | Estimated incidence rate of the survey as provided by the buyer. |
| Conversion | int | Percentage of respondents who complete the survey after qualifying. This value is calculated after one complete and rounded to the nearest whole number. |
| CPI | double | Gross payout per complete. This value is in US dollars and is before any applicable commissions or fees. |
| FieldEndDate | datetime | Target date for survey closure. This property usually does not indicate a hard closure time, although buyers may opt to automatically close the study. “FieldEndDate”: “\/Date(1388293200000-0600)\/”. Where 1388293200000 is a unix timestamp (in milliseconds) denoting 12/29/2013 05:00:00, where -0600 is the time difference from UTC |
| IndustryID | int | Industry associated with the survey’s topic. |
| StudyTypeID | int | Indicates the survey’s format and purpose (i.e. adhoc, recruit, etc). |
| OverallCompletes | int | Number of completes already achieved. |
| TotalRemaining | int | Number of completes still available. |
| CompletionPercentage | int | Percentage of the survey that has filled in terms of completes. |
| SurveyGroup | string | Deprecated: Will return null. Instead use the SurveyGroupExists property. |
| SurveyGroupID | int | Deprecated: Will return null. If SurveyGroupExists is true, then list the survey’s groups. |
| SurveyGroupExists | int | Indicates whether there is a survey group(s) associated with the survey. (0=false, 1=true) |
| BidLengthOfInterview | int | Estimated time for a respondent to complete the survey excluding the Marketplace prescreener in minutes as provided by the buyer. |
| TerminationLengthOfInterview | int | Median time for a respondent to be termed in minutes. This value is calculated after six survey entrants and rounded to the nearest whole number. Until six survey entrants are achieved the value will be zero. |
| IsTrueSample | string | Non-Functional: Cint automatically protects against invalid respondent traffic. |
| SurveyMobileConversion | int | Percentage of mobile respondents who complete the survey after qualifying. This value is calculated after one mobile complete and rounded to the nearest whole number. |
| SurveyQuotaCalcTypeID | int | Indicates whether quotas are calculated based on completes or prescreens (1=Completes, 2=Prescreens). |
| SampleTypeID | int | The type of sample the survey is open to (i.e. consumer, business-to-business, etc). The value will be returned as null if not specified by the buyer. |
| CollectsPII | boolean | true indicates that the survey will collect PII. |
| IsOnlySupplierInGroup | boolean | true indicates that an allocation is reserved for a single supplier |
| RespondentPIDs | array of strings | Contains valid Respondent PIDs belonging to the Supplier for recontact surveys. Field is only present for valid Recontact studies |
GET List Filtered Marketplace Surveys
Definition
GET https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall?CountryLanguageID={CountryLanguageID}&SupplierCode={SupplierCode}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall?CountryLanguageID=11,74&SupplierCode=1234&CollectsPII=1&CPIGTE=2&CPILTE=15&IndustryID=20,25,30
require 'net/http'
uri = URI('https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall?CountryLanguageID=11,74&SupplierCode=1234&CollectsPII=1&CPIGTE=2&CPILTE=15&IndustryID=20,25,30')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall?CountryLanguageID=11,74&SupplierCode=1234&CollectsPII=1&CPIGTE=2&CPILTE=15&IndustryID=20,25,30";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall?CountryLanguageID=11,74&SupplierCode=1234&CollectsPII=1&CPIGTE=2&CPILTE=15&IndustryID=20,25,30'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall?CountryLanguageID=11,74&SupplierCode=1234&CollectsPII=1&CPIGTE=2&CPILTE=15&IndustryID=20,25,30");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Supply/v1/Surveys/AllOfferwall?CountryLanguageID=11,74&SupplierCode=1234&CollectsPII=1&CPIGTE=2&CPILTE=15&IndustryID=20,25,30",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetAllOfferwallSurveys successful."
],
"ResultCount": 1,
"Surveys": [
{
"SurveyName": "Asthma Sufferers",
"SurveyNumber": 457751,
"SurveySID": "26CB55E2-74CC-4E19-88E3-7F2F8D4DE74D",
"AccountName": "Sample Company",
"CountryLanguageID": 11,
"LengthOfInterview": 12,
"BidIncidence": 30,
"Conversion": 1,
"CPI": 5.5,
"FieldEndDate": "\/Date(1541000567000-0600)\/",
"IndustryID": 30,
"StudyTypeID": 1,
"OverallCompletes": 5,
"TotalRemaining": 995,
"CompletionPercentage": 0,
"SurveyGroup": null,
"SurveyGroupID": null,
"SurveyGroupExists": 1,
"BidLengthOfInterview": 10,
"TerminationLengthOfInterview": 6,
"SurveyQuotaCalcTypeID": 1,
"IsTrueSample": false,
"SurveyMobileConversion": 0,
"SampleTypeID": null,
"CollectsPII": true,
"IsOnlySupplierInGroup": false,
"RespondentPIDs": ["75530545", "30776758", "23180686"]
}
]
}
Returns a list, using query parameter filters, of all live survey opportunities available through the Marketplace for which you do not have an allocation or entry link. After creating an entry link you can list allocated surveys or show an allocated survey to access these opportunities. CountryLanguageID & SupplierCode are required parameters for this call.
Arguments
| Property | Type | Required | Description | Limits |
|---|---|---|---|---|
| CountryLanguageID | int | true | Unique id associated with the Country-Language pair the survey is open to. | csv |
| SupplierCode | string | true | Single Unique code associated with a supplier account. | - |
| BidIncidenceGTE | float | false | Minimum estimated incidence rate for the survey. | 0-100 |
| BidIncidenceLTE | float | false | Maximum estimated incidence rate for the survey. | 0-100 |
| BidLengthOfInterviewGTE | int | false | Minimum estimated time for a respondent to complete the survey excluding the Marketplace prescreener in minutes as provided by the buyer. | 0<= |
| BidLengthOfInterviewLTE | int | false | Maximum estimated time for a respondent to complete the survey excluding the Marketplace prescreener in minutes as provided by the buyer. | 0<= |
| CollectsPII | bool | false | 1 indicates that the survey will collect PII. |
- |
| ConversionGTE | int | false | Minimum percentage of respondents who complete the survey after qualifying. This value is calculated after one complete and rounded to the nearest whole number. | 0-100 |
| CPIGTE | float | false | Minimum gross payout per complete. This value is in US dollars and is before any applicable commissions or fees. | 0<= |
| CPILTE | float | false | Maximum gross payout per complete. This value is in US dollars and is before any applicable commissions or fees. | 0<= |
| IndustryID | int | false | Industry associated with the survey’s topic. | csv |
| IsOnlySupplierInGroup | bool | false | 1 indicates that an allocation is reserved for a single supplier |
- |
| LengthOfInterviewLTE | int | false | Maximum median time for a respondent to complete the survey excluding the Marketplace prescreener in minutes. This value is calculated after six completes and rounded to the nearest whole number. Until six completes are achieved the value will be zero. | 0<= |
| OverallCompletesGTE | int | false | Minimum number of completes already achieved. | 0<= |
| SampleTypeID | int | false | The type of sample the survey is open to (i.e. consumer, business-to-business, etc). The value will be returned as null if not specified by the buyer. |
csv |
| StudyTypeID | int | false | Indicates the survey’s format and purpose (i.e. adhoc, recruit, etc). | csv |
| SurveyGroupExists | bool | false | 1 indicates there is a survey group(s) associated with the survey |
- |
| SurveyMobileConversionGTE | int | false | Minimum percentage of mobile respondents who complete the survey after qualifying. This value is calculated after one mobile complete and rounded to the nearest whole number. | 0-100 |
| SurveyName | string | false | External name of the survey. This name may be exposed to respondents. This value is not unique across surveys | Less than or equal to 128 characters. |
| SurveyNumber | int | false | Unique number associated with the survey. | csv |
| SurveyQuotaCalcTypeID | int | false | Indicates whether quotas are calculated based on completes or prescreens. | 1=Completes, 2=Prescreens |
| SurveySID | string | false | Unique hash value (GUID) associated with the survey. | - |
| TerminationLengthOfInterviewLTE | int | false | Maximum median time for a respondent to be termed in minutes. This value is calculated after six survey entrants and rounded to the nearest whole number. Until six survey entrants are achieved the value will be zero. | 0<= |
GET List Marketplace Surveys
Definition
GET https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall/{SupplierCode}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall/{SupplierCode}
require 'net/http'
uri = URI('https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall/{SupplierCode}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall/{SupplierCode}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall/{SupplierCode}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall/{SupplierCode}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Supply/v1/Surveys/AllOfferwall/{SupplierCode}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetAllOfferwallSurveys successful."
],
"ResultCount": 1,
"Surveys": [
{
"SurveyName": "Asthma Sufferers",
"SurveyNumber": 457751,
"SurveySID": "26CB55E2-74CC-4E19-88E3-7F2F8D4DE74D",
"AccountName": "Sample Company",
"CountryLanguageID": 9,
"LengthOfInterview": 12,
"BidIncidence": 30,
"Conversion": 1,
"CPI": 1.5,
"FieldEndDate": "\/Date(1388293200000-0600)\/",
"IndustryID": 30,
"StudyTypeID": 1,
"OverallCompletes": 5,
"TotalRemaining": 995,
"CompletionPercentage": 0,
"SurveyGroup": null,
"SurveyGroupID": null,
"SurveyGroupExists": 1,
"BidLengthOfInterview": 10,
"TerminationLengthOfInterview": 6,
"SurveyQuotaCalcTypeID": 1,
"IsTrueSample": false,
"SurveyMobileConversion": 0,
"SampleTypeID": null,
"CollectsPII": null,
"IsOnlySupplierInGroup": false,
"RespondentPIDs": ["75530545", "30776758", "23180686"]
}
]
}
Returns a list of all live survey opportunities available through the Marketplace for which you do not have an allocation or entry link. After creating an entry link you can list allocated surveys or show an allocated survey to access these opportunities.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SupplierCode | string | true | Unique code associated with a supplier account. |
GET List Marketplace Surveys By Country Language
Definition
GET https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall/ByCountryLanguage/{CountryLanguageID}/{SupplierCode}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall/ByCountryLanguage/{CountryLanguageID}/{SupplierCode}
require 'net/http'
uri = URI('https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall/ByCountryLanguage/{CountryLanguageID}/{SupplierCode}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall/ByCountryLanguage/{CountryLanguageID}/{SupplierCode}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall/ByCountryLanguage/{CountryLanguageID}/{SupplierCode}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Supply/v1/Surveys/AllOfferwall/ByCountryLanguage/{CountryLanguageID}/{SupplierCode}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Supply/v1/Surveys/AllOfferwall/ByCountryLanguage/{CountryLanguageID}/{SupplierCode}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetAllOfferwallSurveysByCountryLanguage successful."
],
"ResultCount": 1,
"Surveys": [
{
"SurveyName": "Asthma Sufferers",
"SurveyNumber": 457751,
"SurveySID": "26CB55E2-74CC-4E19-88E3-7F2F8D4DE74D",
"AccountName": "Sample Company",
"CountryLanguageID": 9,
"LengthOfInterview": 12,
"BidIncidence": 30,
"Conversion": 1,
"CPI": 1.5,
"FieldEndDate": "\/Date(1388293200000-0600)\/",
"IndustryID": 30,
"StudyTypeID": 1,
"OverallCompletes": 5,
"TotalRemaining": 995,
"CompletionPercentage": 0,
"SurveyGroup": null,
"SurveyGroupID": null,
"SurveyGroupExists": 1,
"BidLengthOfInterview": 10,
"TerminationLengthOfInterview": 6,
"SurveyQuotaCalcTypeID": 1,
"IsTrueSample": false,
"SurveyMobileConversion": 0,
"SampleTypeID": null,
"CollectsPII": null,
"RespondentPIDs": ["75530545", "30776758", "23180686"]
}
]
}
Returns a list of all live survey opportunities available through the Marketplace for which you do not have an allocation or entry link, filtered by Country-Language. After creating an entry link you can list allocated surveys or show an allocated survey to access these opportunities.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| CountryLanguageID | int | true | Country-Language ID to filter with |
| SupplierCode | string | true | Unique code associated with a supplier account. |
Allocations
Allocations allow buyers to allocate portions of studies to specific suppliers. This resource returns the allocation you have been given for a study based on your supplier code. These properties may return Null: BidIncidence, BidLengthOfInterview, IndustryID, SampleTypeID and StudyTypeID.
SupplierAllocationSurveys Model
| Property | Type | Description |
|---|---|---|
| SurveyName | string | External name of the survey. This name may be exposed to respondents. This value is not unique across surveys. |
| SurveyNumber | int | Unique number associated with the survey. |
| SurveySID | string | Unique hash value (GUID) assoicated with the survey. |
| AccountName | string | Name of the buyer running the survey. |
| CountryLanguageID | int | Unique id associated with the Country-Language pair the survey is open to. |
| LengthOfInterview | int | Median time (in minutues) for a respondent to complete the survey, excluding the Marketplace prescreener. This value is calculated after six completes and rounded to the nearest whole number. Until six completes are achieved the value will be zero. |
| BidIncidence | double | Estimated incidence rate of the survey as provided by the buyer. |
| Conversion | int | Percentage of respondents who complete the survey after qualifying. This value is calculated after one complete and rounded to the nearest whole number. |
| FieldBeginDate | datetime | Target date for survey start. This property usually does not indicate a hard start time, although buyers may opt to automatically open the study. Ex: “FieldBeginDate”: “\/Date(1388293200000-0600)\/” where 1388293200000 is a unix timestamp (in milliseconds) denoting 12/29/2013 05:00:00, where -0600 is the time difference from UTC |
| FieldEndDate | datetime | Target date for survey closure. This property usually does not indicate a hard closure time, although buyers may opt to automatically close the study. Ex: “FieldEndDate”: “\/Date(1388293200000-0600)\/” where 1388293200000 is a unix timestamp (in milliseconds) denoting 12/29/2013 05:00:00, where -0600 is the time difference from UTC |
| IndustryID | int | Industry associated with the survey’s topic. |
| StudyTypeID | int | Indicates the survey’s format and purpose (i.e. adhoc, recruit, etc). |
| Priority | int | Survey priority (1 being the highest). Priority only applies to routed sample. |
| SurveyGroup | string | Deprecated: Will return null. Instead use the SurveyGroupExists property. |
| SurveyGroupExists | int | Indicates whether there is a survey group(s) associated with the survey. (0=false, 1=true) |
| BidLengthOfInterview | int | Estimated time (in minutes) for a respondent to complete the survey, as provided by the buyer, excluding the Marketplace prescreener. |
| TerminationLengthOfInterview | int | Median time (in minutes) for a respondent to be termed. This value is calculated after six survey entrants and rounded to the nearest whole number. Until six survey entrants are achieved the value will be zero. |
| IsTrueSample | string | Non-Functional: Cint automatically protects against invalid respondent traffic. |
| SurveyMobileConversion | int | Percentage of mobile respondents who complete the survey after qualifying. This value is calculated after one mobile complete and rounded to the nearest whole number. |
| SurveyQuotaCalcTypeID | int | Indicates whether quotas are calculated based on completes or prescreens (1=Completes, 2=Prescreens). |
| SampleTypeID | int | The type of sample the survey is open to (i.e. consumer, business-to-business, etc). The value will be returned as null if not specified by the buyer. |
| CollectsPII | boolean | true indicates that the survey will collect PII. |
SupplierAllocationSurvey Model
| Property | Type | Description |
|---|---|---|
| SurveyName | string | External name of the survey. This name may be exposed to respondents. This value is not unique across surveys. |
| SurveyNumber | int | Unique number associated with the survey. |
| SurveySID | string | Unique hash value (GUID) assoicated with the survey. |
| AccountName | string | Name of the buyer running the survey. |
| CountryLanguageID | int | Unique id associated with the Country-Language pair the survey is open to. |
| LengthOfInterview | int | Median time for a respondent to complete the survey excluding the Marketplace prescreener in minutes. This value is calculated after 6 completes and rounded to the nearest whole number. Until six completes are achieved the value will be zero. |
| BidIncidence | double | Estimated incidence rate of the survey as provided by the buyer. |
| Conversion | int | Percentage of respondents who complete the survey after qualifying. This value is calculated after one complete and rounded to the nearest whole number. |
| FieldBeginDate | datetime | Target date for survey start. This property usually does not indicate a hard start time, although buyers may opt to automatically open the study. Ex: “FieldBeginDate”: “\/Date(1388293200000-0600)\/” where 1388293200000 is a unix timestamp (in milliseconds) denoting 12/29/2013 05:00:00, where -0600 is the time difference from UTC |
| FieldEndDate | datetime | Target date for survey closure. This property usually does not indicate a hard closure time, although buyers may opt to automatically close the study. Ex: “FieldEndDate”: “\/Date(1388293200000-0600)\/” where 1388293200000 is a unix timestamp (in milliseconds) denoting 12/29/2013 05:00:00, where -0600 is the time difference from UTC |
| IndustryID | int | Industry associated with the survey’s topic. |
| StudyTypeID | int | Indicates the survey’s format and purpose (i.e. adhoc, recruit, etc). |
| Priority | int | Survey priority (1 being the highest). Priority only applies to routed sample. |
| SupplierAllocations | array | Contains an array of SupplierAllocations elements described below. |
| OfferwallTotalRemaining | int | Deprecated: Use the AllocationRemaining and HedgeRemaining properties return in each respective model. |
| OfferwallAllocations | array | Contains an array of OfferwallAllocations elements described below. |
| SurveyGroup | string | Deprecated: Will return null. Instead use the SurveyGroupExists property. |
| SurveyGroupID | int | Deprecated: Will return null. If SurveyGroupExists is true, then list the survey’s groups. |
| SurveyGroupExists | int | Indicates whether there is a survey group(s) associated with the survey. (0=false, 1=true) |
| BidLengthOfInterview | int | Estimated time (in minutes) for a respondent to complete the survey, as provided by the buyer, excluding the Marketplace prescreener. |
| TerminationLengthOfInterview | int | Median time (in minutes) for a respondent to be termed. This value is calculated after six survey entrants and rounded to the nearest whole number. Until six survey entrants are achieved the value will be zero. |
| IsTrueSample | string | Non-Functional: Cint automatically protects against invalid respondent traffic. |
| SurveyMobileConversion | int | Percentage of mobile respondents who complete the survey after qualifying. This value is calculated after one mobile complete and rounded to the nearest whole number. |
| SurveyQuotaCalcTypeID | int | Indicates whether quotas are calculated based on completes or prescreens (1=Completes, 2=Prescreens). |
| SampleTypeID | int | The type of sample the survey is open to (i.e. consumer, business-to-business, etc). The value will be returned as null if not specified by the buyer. |
| CollectsPII | boolean | true indicates that the survey will collect PII. |
| IsOnlySupplierInGroup | boolean | true indicates that an allocation is reserved for a single supplier |
SupplierAllocations Model
| Property | Type | Description |
|---|---|---|
| SupplierCode | int | Unique code associated with a supplier account. |
| SupplierName | string | Name of the supplier. |
| IsBlockRouted | boolean | Indicates if the survey accepts routed sample. |
| AchievedCompletes | int | Number of completes that have been already achieved by the supplier in this survey. |
| AllocationRemaining | int | Number of completes remaining as part of the allocation. |
| HedgeRemaining | int | Number of unallocated completes available to any suppliers with access to hedge. |
| TargetModel | object | Contains an object of the TargetModel elements described below. |
OfferwallAllocations Model
| Property | Type | Description |
|---|---|---|
| SupplierCode | int | Unique code associated with a supplier account. |
| SupplierName | string | Name of the supplier. |
| OfferwallCompletes | int | Number of completes that have been already achieved by the Suppliers included in the same Marketplace group as the allocation. |
| AllocationRemaining | int | Number of completes remaining as part of the allocation. |
| HedgeRemaining | int | Number of unallocated completes available to any suppliers with access to hedge. |
| TargetModel | object | Contains an object of the TargetModel elements described below. |
TargetModel Model
| Property | Type | Description |
|---|---|---|
| SupplierLinkType | int | Defines the type of buyer-supplier engagement and the respondent’s path in Cint Marketplace. See List Global Definitions for a map of supplier link types. |
| LiveSupplierLink | string | Live supplier-specific respondent entry link generated by Cint Marketplace. |
| SupplierLinkSID | string | Unique hash value (GUID) associated with a LiveSupplierLink. |
| TargetCCPI | double | Gross payout per targeted complete. The value is in US dollars. |
GET List Allocated Surveys
Definition
GET https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/All/{SupplierCode}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/All/{SupplierCode}
require 'net/http'
uri = URI('https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/All/{SupplierCode}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
allocations = http.request(request)
<?php
$URL = "https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/All/{SupplierCode}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/All/{SupplierCode}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/All/{SupplierCode}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Supply/v1/Surveys/SupplierAllocations/All/{SupplierCode}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetSupplierAllocationsAll successful."
],
"ResultCount": 1,
"SupplierAllocationSurveys": [
{
"SurveyName": "IT Developers Survey",
"SurveyNumber": 143479,
"SurveySID": "4C2B4533-0EA1-364A-212B-345B38C6AF57",
"AccountName": "Sample Company",
"CountryLanguageID": 9,
"LengthOfInterview": 2,
"BidIncidence": 8,
"Conversion": 1,
"FieldBeginDate": "/Date(1429160400000-0500)/",
"FieldEndDate": "/Date(1429848000000-0500)/",
"IndustryID": 3,
"StudyTypeID": 1,
"Priority": 2,
"SurveyGroup": null,
"SurveyGroupID": null,
"SurveyGroupExists": 0,
"BidLengthOfInterview": 15,
"TerminationLengthOfInterview": 5,
"SurveyQuotaCalcTypeID": 1,
"IsTrueSample": false,
"SurveyMobileConversion": 0,
"SampleTypeID": null,
"CollectsPII": null
}
]
}
Returns a list of all live survey opportunities for which you have an allocation or entry link.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SupplierCode | string | true | Unique code associated with a supplier account. |
GET Show an Allocated Survey
Definition
GET https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/BySurveyNumber/{SurveyNumber}/{SupplierCode}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/BySurveyNumber/{SurveyNumber}/{SupplierCode}
require 'net/http'
uri = URI('https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/BySurveyNumber/{SurveyNumber}/{SupplierCode}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/BySurveyNumber/{SurveyNumber}/{SupplierCode}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/BySurveyNumber/{SurveyNumber}/{SupplierCode}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/BySurveyNumber/{SurveyNumber}/{SupplierCode}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Supply/v1/Surveys/SupplierAllocations/BySurveyNumber/{SurveyNumber}/{SupplierCode}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetSupplierAllocationsBySurveyNumber successful."
],
"ResultCount": 1,
"SupplierAllocationSurvey": {
"SurveyName": "Pet Owner Survey",
"SurveyNumber": 17381,
"SurveySID": "03B4B292-0EA1-212B-02C1-345B38C6AF57",
"AccountName": "Sample Company",
"CountryLanguageID": 9,
"LengthOfInterview": 16,
"BidIncidence": 20,
"Conversion": 13,
"FieldBeginDate": "/Date(1400562000000-0500)/",
"FieldEndDate": "/Date(1401854400000-0500)/",
"IndustryID": 18,
"StudyTypeID": 1,
"Priority": 1,
"SupplierAllocations": [],
"OfferwallTotalRemaining": 47,
"OfferwallAllocations": [
{
"SupplierCode": "0050",
"SupplierName": "Supply Company",
"OfferwallCompletes": 403,
"AllocationRemaining": 47,
"HedgeRemaining": 0,
"TargetModel": {
"SupplierLinkType": 18,
"LiveSupplierLink": "https://samplicio.us/s/default.aspx?SID=da94c7f8-0dcf-4fcc-80d4-6e2beafc3ff4&PID=",
"SupplierLinkSID": "da94c7f8-0dcf-4fcc-80d4-6e2beafc3ff4",
"TargetCCPI": 3
}
}
],
"SurveyGroup": null,
"SurveyGroupID": null,
"SurveyGroupExists": 1,
"BidLengthOfInterview": 15,
"TerminationLengthOfInterview": 3,
"SurveyQuotaCalcTypeID": 1,
"IsTrueSample": false,
"SurveyMobileConversion": 0,
"SampleTypeID": null,
"CollectsPII": null,
"IsOnlySupplierInGroup": false
}
}
Returns any allocation(s) given to you for a particular survey.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SupplierCode | string | false | Unique code associated with a supplier account. |
| SurveyNumber | int | true | Unique number associated with the survey. |
GET List Allocated Surveys by Date
Definition
GET https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/ByDate/{Date}/{SupplierCode}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/ByDate/{Date}/{SupplierCode}
require 'net/http'
uri = URI('https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/ByDate/{Date}/{SupplierCode}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/ByDate/{Date}/{SupplierCode}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/ByDate/{Date}/{SupplierCode}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/ByDate/{Date}/{SupplierCode}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Supply/v1/Surveys/SupplierAllocations/ByDate/{Date}/{SupplierCode}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetSupplierAllocationsByDate successful."
],
"ResultCount": 1,
"SupplierAllocationSurveys": [
{
"SurveyName": "IT Developers Survey",
"SurveyNumber": 143479,
"SurveySID": "4C2B4533-0EA1-364A-212B-345B38C6AF57",
"AccountName": "Sample Company",
"CountryLanguageID": 9,
"LengthOfInterview": 2,
"BidIncidence": 8,
"Conversion": 1,
"FieldBeginDate": "/Date(1431666000000-0500)/",
"FieldEndDate": "/Date(1432353600000-0500)/",
"IndustryID": 30,
"StudyTypeID": 1,
"Priority": 2,
"SurveyGroup": null,
"SurveyGroupID": null,
"SurveyGroupExists": 0,
"BidLengthOfInterview": 15,
"TerminationLengthOfInterview": 5,
"SurveyQuotaCalcTypeID": 1,
"IsTrueSample": false,
"SurveyMobileConversion": 0,
"SampleTypeID": null,
"CollectsPII": null
}
]
}
Returns a list of all live survey opportunities for which you have an allocation or entry link and the TotalQuota has changed since a specified date.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| Date | string | true | Must follow the format YYYY-MM-DD |
| SupplierCode | string | true | Unique code associated with a supplier account. |
GET List Allocated Surveys By CountryLanguage
Definition
GET https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/ByCountryLanguage/{CountryLanguageID}/{SupplierCode}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/ByCountryLanguage/{CountryLanguageID}/{SupplierCode}
require 'net/http'
uri = URI('https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/ByCountryLanguage/{CountryLanguageID}/{SupplierCode}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/ByCountryLanguage/{CountryLanguageID}/{SupplierCode}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/ByCountryLanguage/{CountryLanguageID}/{SupplierCode}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/ByCountryLanguage/{CountryLanguageID}/{SupplierCode}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Supply/v1/Surveys/SupplierAllocations/ByCountryLanguage/{CountryLanguageID}/{SupplierCode}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetSupplierAllocationsByCountryLanguage successful."
],
"ResultCount": 1,
"SupplierAllocationSurveys": [
{
"SurveyName": "IT Developers Survey",
"SurveyNumber": 143479,
"SurveySID": "4C2B4533-0EA1-364A-212B-345B38C6AF57",
"AccountName": "Sample Company",
"CountryLanguageID": 9,
"LengthOfInterview": 2,
"BidIncidence": 8,
"Conversion": 1,
"FieldBeginDate": "/Date(1431666000000-0500)/",
"FieldEndDate": "/Date(1432353600000-0500)/",
"IndustryID": 30,
"StudyTypeID": 1,
"Priority": 2,
"SurveyGroup": null,
"SurveyGroupID": null,
"SurveyGroupExists": 0,
"BidLengthOfInterview": 15,
"TerminationLengthOfInterview": 5,
"SurveyQuotaCalcTypeID": 1,
"IsTrueSample": false,
"SurveyMobileConversion": 0,
"SampleTypeID": null,
"CollectsPII": null
}
]
}
Returns a list of all live survey opportunities for which you have an allocation or entry link in the selected Country-Language.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| CountryLanguageID | int | true | Country-Language ID to filter with |
| SupplierCode | string | true | Unique code associated with a supplier account. |
GET List Allocated Surveys By CountryLanguage and Date
Definition
GET https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/ByCountryLanguage/{CountryLanguageID}/ByDate/{Date}/{SupplierCode}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/ByCountryLanguage/{CountryLanguageID}/ByDate/{Date}/{SupplierCode}
require 'net/http'
uri = URI('https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/ByCountryLanguage/{CountryLanguageID}/ByDate/{Date}/{SupplierCode}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/ByCountryLanguage/{CountryLanguageID}/ByDate/{Date}/{SupplierCode}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/ByCountryLanguage/{CountryLanguageID}/ByDate/{Date}/{SupplierCode}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Supply/v1/Surveys/SupplierAllocations/ByCountryLanguage/{CountryLanguageID}/ByDate/{Date}/{SupplierCode}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Supply/v1/Surveys/SupplierAllocations/ByCountryLanguage/{CountryLanguageID}/ByDate/{Date}/{SupplierCode}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetSupplierAllocationsByCountryLanguageAndDate successful."
],
"ResultCount": 1,
"SupplierAllocationSurveys": [
{
"SurveyName": "IT Developers Survey",
"SurveyNumber": 143479,
"SurveySID": "4C2B4533-0EA1-364A-212B-345B38C6AF57",
"AccountName": "Sample Company",
"CountryLanguageID": 9,
"LengthOfInterview": 2,
"BidIncidence": 8,
"Conversion": 1,
"FieldBeginDate": "/Date(1431666000000-0500)/",
"FieldEndDate": "/Date(1432353600000-0500)/",
"IndustryID": 30,
"StudyTypeID": 1,
"Priority": 2,
"SurveyGroup": null,
"SurveyGroupID": null,
"SurveyGroupExists": 0,
"BidLengthOfInterview": 15,
"TerminationLengthOfInterview": 5,
"SurveyQuotaCalcTypeID": 1,
"IsTrueSample": false,
"SurveyMobileConversion": 0,
"SampleTypeID": null,
"CollectsPII": null
}
]
}
Returns a list of all live survey opportunities for which you have an allocation or entry link in the selected Country Language and the TotalQuota has changed since a specified date.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| CountryLanguageID | int | true | Country-Language ID to filter with |
| Date | string | true | Must follow the format YYYY-MM-DD |
| SupplierCode | string | true | Unique code associated with a supplier account. |
Qualifications
The Qualification resource contains the questions and corresponding conditions associated with a survey. These qualifications make up the Marketplace prescreener and define the overall survey targeting criteria for suppliers.
Survey Qualification Model
| Property | Type | Description |
|---|---|---|
| SurveyNumber | int | Unique number associated with the survey. |
| Questions | array | Contains an array of Question models. |
Questions Model
| Property | Type | Description |
|---|---|---|
| QuestionID | int | Unique number associated with the question. |
| LogicalOperator | string | Defines the logical operation applied to the conditions. |
| PreCodes | array | Qualification answer option identifier. |
GET Show Qualifications
Definition
GET https://api.samplicio.us/Supply/v1/SurveyQualifications/BySurveyNumberForOfferwall/{SurveyNumber}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Supply/v1/SurveyQualifications/BySurveyNumberForOfferwall/{SurveyNumber}
require 'net/http'
uri = URI('https://api.samplicio.us/Supply/v1/SurveyQualifications/BySurveyNumberForOfferwall/{SurveyNumber}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Supply/v1/SurveyQualifications/BySurveyNumberForOfferwall/{SurveyNumber}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Supply/v1/SurveyQualifications/BySurveyNumberForOfferwall/{SurveyNumber}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Supply/v1/SurveyQualifications/BySurveyNumberForOfferwall/{SurveyNumber}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Supply/v1/SurveyQualifications/BySurveyNumberForOfferwall/{SurveyNumber}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetOfferwallQualificationsBySurveyNumber successful."
],
"ResultCount": 10,
"SurveyQualification": {
"SurveyNumber": 254256,
"Questions": [
{
"QuestionID": 42,
"LogicalOperator": "Or",
"PreCodes": [
"18",
"19",
"20",
"21",
"22",
"23",
"24",
"25"
]
},
{
"QuestionID": 43,
"LogicalOperator": "Or",
"PreCodes": [
"1",
"2"
]
}
]
}
}
Returns a list of all standard and exposed custom qualifications associated with a survey.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
Quotas
The quotas resource returns the number of completes available to you for each demographic cell in a survey. Quotas can be built on any qualification(s).
Response Properties
| Property | Type | Description |
|---|---|---|
| SurveyNumber | int | Unique number associated with the survey. |
| SurveyQuotas | array | Contains an array of Survey Quotas models. |
| SurveyStatusCode | string | Code associated with the current status of the survey. See List Global Definitions for a map of survey status codes. |
| SurveyStillLive | boolean | A simple check to determine whether a survey is open to respondents. This can be used interchangeably with SurveyStatusCode. |
Survey Quotas Model
| Property | Type | Description |
|---|---|---|
| SurveyQuotaID | int | Unique number associated with the quota. |
| SurveyQuotaType | string | Represents the function of the quota. |
The Total quota represents the maximum number of completes available on the survey and will always be present. |
||
Client quotas are any subquotas on the survey. They are independent of the total quota and may be overlapping with one another. |
||
| QuotaCPI | double | We recommend using Show an Allocated Survey and TargetCCPI to retrieve survey CPI. Gross payout per complete. This value is in US dollars and is before any applicable commissions or fees. |
| Conversion | int | Percentage of respondents who complete the survey after qualifying for that quota. This value is calculated after one complete and rounded to the nearest whole number. |
| NumberOfRespondents | int | Number of completes available in that quota group. |
| Questions | array | Contains an array of Question models. |
Questions Model
| Property | Type | Description |
|---|---|---|
| QuestionID | int | Unique number associated with the question. |
| LogicalOperator | string | Defines the logical operation applied to the conditions. |
| PreCodes | array | Qualification answer option identifier. |
GET Show Quotas
Definition
GET https://api.samplicio.us/Supply/v1/SurveyQuotas/BySurveyNumber/{SurveyNumber}/{SupplierCode}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Supply/v1/SurveyQuotas/BySurveyNumber/{SurveyNumber}/{SupplierCode}
require 'net/http'
uri = URI('https://api.samplicio.us/Supply/v1/SurveyQuotas/BySurveyNumber/{SurveyNumber}/{SupplierCode}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Supply/v1/SurveyQuotas/BySurveyNumber/{SurveyNumber}/{SupplierCode}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Supply/v1/SurveyQuotas/BySurveyNumber/{SurveyNumber}/{SupplierCode}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Supply/v1/SurveyQuotas/BySurveyNumber/{SurveyNumber}/{SupplierCode}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Supply/v1/SurveyQuotas/BySurveyNumber/{SurveyNumber}/{SupplierCode}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetSurveyQuotasBySurveyNumberAndSupplierCode successful."
],
"ResultCount": 3,
"SurveyNumber": 254256,
"SurveyQuotas": [
{
"SurveyQuotaID": 1564722,
"SurveyQuotaType": "Total",
"QuotaCPI": 0,
"Conversion": 0,
"NumberOfRespondents": 20,
"Questions": []
},
{
"SurveyQuotaID": 1781601,
"SurveyQuotaType": "Client",
"QuotaCPI": 0,
"Conversion": 0,
"NumberOfRespondents": 10,
"Questions": [
{
"QuestionID": 43,
"LogicalOperator": "OR",
"PreCodes": [
"1"
]
}
]
},
{
"SurveyQuotaID": 1781602,
"SurveyQuotaType": "Client",
"QuotaCPI": 0,
"Conversion": 0,
"NumberOfRespondents": 10,
"Questions": [
{
"QuestionID": 43,
"LogicalOperator": "OR",
"PreCodes": [
"2"
]
}
]
}
],
"SurveyStatusCode": "02",
"SurveyStillLive": false
}
Returns the total quota and client quotas associated with a survey.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
| SupplierCode | string | true | Unique code associated with supplier account. |
Statistics
The Survey Statistics resource returns valuable survey performance statistics based on scope and timeframe. This resource is an important part of Yield Management which is the process of implementing business and API processes rank and order surveys to ensure high earnings-per-click (EPC) studies receive the most traffic and low EPC studies are removed from sample send.
Global Trailing Model
| Property | Type | Description |
|---|---|---|
| EffectiveEPC | float | Global Effective EPC given the trailing conversion rate and current CPI of survey (TrailingConversion*CPI) |
| LengthOfInterview | int | Global Trailing LOI. Median time for a respondent to complete the survey excluding the Marketplace prescreener in minutes. |
| SystemConversion | float | Global trailing conversion rate (# Completes / # System Entrants) |
Supplier Lifetime Model
| Property | Type | Description |
|---|---|---|
| EPC | float | Lifetime EPC |
| SystemConversion | float | Lifetime conversion rate |
Supplier Trailing Model
| Property | Type | Description |
|---|---|---|
| SystemConversion | float | Trailing conversion rate |
GET Show Statistics
Definition
GET https://api.samplicio.us/Supply/v1/SurveyStatistics/BySurveyNumber/{SurveyNumber}/{SupplierCode}/{Scope}/{Timespan}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Supply/v1/SurveyStatistics/BySurveyNumber/{SurveyNumber}/{SupplierCode}/{Scope}/{Timespan}
require 'net/http'
uri = URI('https://api.samplicio.us/Supply/v1/SurveyStatistics/BySurveyNumber/{SurveyNumber}/{SupplierCode}/{Scope}/{Timespan}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Supply/v1/SurveyStatistics/BySurveyNumber/{SurveyNumber}/{SupplierCode}/{Scope}/{Timespan}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Supply/v1/SurveyStatistics/BySurveyNumber/{SurveyNumber}/{SupplierCode}/{Scope}/{Timespan}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Supply/v1/SurveyStatistics/BySurveyNumber/{SurveyNumber}/{SupplierCode}/{Scope}/{Timespan}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Supply/v1/SurveyStatistics/BySurveyNumber/{SurveyNumber}/{SupplierCode}/{Scope}/{Timespan}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetGlobalTrailingStatisticsBySurveyNumber successful."
],
"ResultCount": 1,
"SurveyStatistics": {
"EffectiveEPC": 2.73,
"LengthOfInterview": 5,
"SystemConversion": 0.28
}
}
Returns Marketplace conversion information (as a percentage) for a live study based on the Scope and Timespan.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| Survey Number | int | true | Unique ID associated with the study. |
| SupplierCode | string | true | Your unique supplier code. |
| Scope | string | true | Either “Global” or “Supplier”. |
| Timespan | string | true | Either “Trailing” or “Lifetime”. Trailing returns data from the last 12 hours. |
GET List Statistics
Definition
GET https://api.samplicio.us/Supply/v1/SurveyStatistics/All/{SupplierCode}/{Scope}/{Timespan}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Supply/v1/SurveyStatistics/All/{SupplierCode}/{Scope}/{Timespan}
require 'net/http'
uri = URI('https://api.samplicio.us/Supply/v1/SurveyStatistics/All/{SupplierCode}/{Scope}/{Timespan}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Supply/v1/SurveyStatistics/All/{SupplierCode}/{Scope}/{Timespan}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Supply/v1/SurveyStatistics/All/{SupplierCode}/{Scope}/{Timespan}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Supply/v1/SurveyStatistics/All/{SupplierCode}/{Scope}/{Timespan}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Supply/v1/SurveyStatistics/All/{SupplierCode}/{Scope}/{Timespan}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: GetAllGlobalTrailingStatistics successful."
],
"ResultCount": 2,
"SurveyStatistics": [
{
"SurveyNumber": 999,
"SystemConversion": 0.42
},
{
"SurveyNumber": 999,
"SystemConversion": 0.07
},
]
}
Returns Marketplace conversion information (as a percentage) based on the Scope and Timespan, for all live surveys which have received an entrant in the last 12 hours.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| Scope | string | true | Either “Global” or “Supplier”. |
| Timespan | string | true | Either “Trailing” or “Lifetime”. Trailing returns the last 12 hours. |
| SupplierCode | string | true | Your unique supplier code. |
Recontact
Recontacts allow buyers to collect a follow-up impression on a respondent they have already interacted with or already have knowledge of.
SurveyQualifiedRespondents Model
| Property | Type | Description |
|---|---|---|
| IsActive | boolean | Indicates whether a respondent qualifies for the recontact. |
| PID | string | A supplier’s unique respondent identifier. |
GET List Qualified Respondents
Definition
GET https://api.samplicio.us/Supply/v1/SurveyQualifiedRespondents/BySurveyNumberSupplierCode/{SurveyNumber}/{SupplierCode}
Example Request
curl -H "Authorization: YOUR_API_KEY_HERE" https://api.samplicio.us/Supply/v1/SurveyQualifiedRespondents/BySurveyNumberSupplierCode/{SurveyNumber}/{SupplierCode}
require 'net/http'
uri = URI('https://api.samplicio.us/Supply/v1/SurveyQualifiedRespondents/BySurveyNumberSupplierCode/{SurveyNumber}/{SupplierCode}')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri.request_uri)
request['Authorization'] = YOUR_API_KEY_HERE
response = http.request(request)
<?php
$URL = "https://api.samplicio.us/Supply/v1/SurveyQualifiedRespondents/BySurveyNumberSupplierCode/{SurveyNumber}/{SupplierCode}";
$aHTTP['http']['method'] = 'GET';
$aHTTP['http']['header'] = "Authorization: YOUR_API_KEY_HERE";
$context = stream_context_create($aHTTP);
$response = file_get_contents($URL, false, $context);
?>
import requests
url = 'https://api.samplicio.us/Supply/v1/SurveyQualifiedRespondents/BySurveyNumberSupplierCode/{SurveyNumber}/{SupplierCode}'
headers = {'Authorization' : YOUR_API_KEY_HERE}
response = requests.get(url, headers=headers)
using System.Net;
WebRequest request = WebRequest.Create("https://api.samplicio.us/Supply/v1/SurveyQualifiedRespondents/BySurveyNumberSupplierCode/{SurveyNumber}/{SupplierCode}");
request.Headers.Add("Authorization", YOUR_API_KEY_HERE);
WebResponse response = request.GetResponse();
const https = require('https');
var options = {
"method": "GET",
"hostname": "api.samplicio.us",
"path": "/Supply/v1/SurveyQualifiedRespondents/BySurveyNumberSupplierCode/{SurveyNumber}/{SupplierCode}",
"headers": {'Authorization': YOUR_API_KEY_HERE}
};
var request = https.request(options, function (response) {
var chunks = [];
response.on("data", function (chunk) {
chunks.push(chunk);
});
});
request.end();
Example Response
{
"ApiResult": 0,
"ApiResultCode": 0,
"ApiAccount": "Anon",
"AccountType": 2,
"ApiAccountStatus": 1,
"AccountCode": "AA",
"ApiMessages": [
"API Message: Response initialized.",
"API Message: SurveyQualifiedRespondentsBySurveyNumberSupplierCode successful."
],
"ResultCount": 4,
"SurveyQualifiedRespondents": [
{
"PID": "1111110",
"IsActive": true
},
{
"PID": "1111101",
"IsActive": true
},
{
"PID": "1111001",
"IsActive": true
},
{
"PID": "1110001",
"IsActive": true
}
]
}
Returns the list of PIDs by supplier for a specific Marketplace survey when study type is Recontact.
Arguments
| Property | Type | Required | Description |
|---|---|---|---|
| SurveyNumber | int | true | Unique number associated with the survey. |
| SupplierCode | string | true | Unique code associated with the supplier performing the call. |
Guides
Demand Integration Best Practices 2024
The following provides recommendations on endpoint choices, design patterns, and integration architecture from the Demand Integrations Team. These recommendations reflect current patterns within the Marketplace User Interface (UI) and include the latest versions of endpoints and features.
These recommendations are in line with expectations around the forthcoming Cint Exchange APIs, which will be available in Q3 of 2024. Patterns and decisions here mirror those that will be present in the new APIs and will streamline migration efforts into the Cint Exchange.
General Notes
V2-Beta
Cint Marketplace, along with the Marketplace Demand APIs, has seen substantial updates and revisions over the past few years. As such, some features are only available via the V2-Beta APIs. While these still carry the designation of beta, they are considered stable and any breaking changes will be communicated with significant notice.
The V2-Beta APIs are in-line with the current Marketplace UI and include new features like Reach and Fielding Assistant. However, not all endpoints have received V2 updates, so an integration will need to use V1 and V2 endpoints to cover all needed features.
The V2 API is backwards-compatible with the V1 API. In most cases, surveys created with V1 endpoints can be updated with V2 endpoints, although care should be taken to ensure that certain validations on fields are in place.
Wherever possible, we recommend using the V2 endpoints for survey creation and updating. V1 endpoints are still needed for some features, including Qualifications, Quotas, and Survey Groups. These are discussed further in the following sections.
Respondent Flow
Redirection
The Marketplace relies on browser redirection to send respondents to and from surveys.
Each survey-taker, or respondent, is assigned a unique session identifier prior to redirection to your survey. This is referred to as an RID (response id), and it is appended as a query string variable on the survey entry URL using a standardized Marketplace placeholder. While any variable name can be used, we recommend using the following syntax: https://www.example.com/survey?rid=[%RID%]. Note the placeholder syntax of [%RID%].
On completion of the survey, redirect the respondent back to the Marketplace using a set of standard redirects. These cover four possible survey end conditions:
CompleteTerminateQuality TerminateOverquota
Your Integration Consultant or CSM will provide these redirects during the integration process.
Cint only invoices for respondents in Complete status. While other respondent statuses affect survey and account metrics, respondents in those statuses are not invoiced.
For more details on response codes and respondent statuses, refer to this Support Site document.
Link Security and SHA-1 HMAC
Since redirects are vulnerable to manipulation, Cint strongly recommends the implementation of a SHA-1 HMAC hashing approach for redirect URLs. For details on implementation, including code samples, please review https://hash.lucidhq.engineering/. Your CSM will assist with account setup and key generation, and your Integration Consultant will be available to answer any implementation questions.
The hashing option is also available for entry URLs as well and applies the same algorithm to the entry link provided for the survey.
Link-Passed Variables
To avoid screening a respondent multiple times, the Marketplace allows profiling data from the Marketplace prescreener to be appended to the entry link. This information is passed via placeholders similar to the RID placeholder above, but using the name of the relevant qualification. The placeholder will be replaced by the precode of the respondent’s answer, or with a binary string representing multi-select answers. Again, the query string variable name does not matter, though we recommend using the numeric Question ID for conciseness and clarity.
Example: https://www.example.com/survey?rid=[%RID%]&42=[%AGE%]&45=[%ZIP%]
For more information, please review the Marketplace Support Site article.
Lookups, Targeting, Sources of Truth
General Lookups and Account Parameters
Several important parameters for survey setup come from the Dictionary endpoint, called with various arguments.
The Dictionary endpoint’s results are formatted for V2 APIs, and several also provide V1-formatted data for backwards compatibility and mapping.
Parameters such as locales, industries, study-types, clients, and users can be found here, and are used in survey creation or other list/lookup calls.
Locales refer to pairings of country and language, such as eng_us or ger_de.
Qualifications/Profiling/Targeting
The Marketplace offers an extensive library of questions, also known as qualifications, for targeting respondents with specific characteristics. There are two V2 approaches to looking up available questions and answers, both with different applications.
For overall mapping of questions, we recommend the Questions endpoint. Iterating over this endpoint returns extensive details about available questions and answers within a locale. From this endpoint, the id parameter is used most throughout the other APIs, while the name field is used for link-passed variables as discussed above. The question_options field includes a list of available answers with a precode attribute. The precode is used to set specific answer choices for qualifications, quotas, and feasibility.
When working with feasibility tools, the Reach Questions endpoint shows similar data to the general Questions endpoint, but reflects questions for which enough profiling data exists to make accurate predictions. See the following section for more information on how to use Reach.
Feasibility/Reach
Reach is the primary feasibility tool for the Marketplace. It uses an extensive machine learning model based on real-time survey data to provide estimates on survey price (Cost per Interview) and available respondents.
While there are two versions available, we recommend the Reach V2 endpoints. The V2 endpoints mirror the Bid tab in the Marketplace UI and provide detailed options for survey setup and quota configuration. The Target Estimate V2 endpoint also offers tools for assessing survey performance in-field.
We recommend making a call to Reach V2 for each survey you intend to launch prior to survey creation. The result will help you determine whether your survey is feasible within your budget and what CPIs have historically worked for similar targeting and metrics.
The endpoint can also be used for in-field surveys, and we recommend making additional Reach V2 API calls throughout the fielding process as the metrics for your survey change.
Making a Reach API Call
When building a Reach API call, pay close attention to the inputs you choose. Your CSM will be able to assist in best practices for calculating key metrics, such as Incidence Rate (IR) and Length of Interview (LOI), which contribute heavily to overall feasibility.
Reach also differs from the Qualifications and Quotas approach to survey targeting; Reach quota cells can be nested or overlapping and can also be used to create filtering quotas that act like Marketplace qualifications in the UI and survey creation API flows.
In Reach, quotas, or targets, are expressed as a list of JSON objects. Each target specifies its quota, an integer count of desired respondents, as well as a list of qualifications, which are composed of individual question_id and condition pairs. The condition parameter is a precode as discussed above. Each target has an optional completes_collected field, which can be used to review in-field performance.
Setting Survey Metrics Prior to Launch
See this page at the Marketplace Support Site for information on how to calculate key metrics.
The price field in the request represents a maximum budget per complete, but does not necessarily represent what you will need to pay to achieve each complete. We recommend starting with a low number here, usually based on IR and LOI, then making successive Reach calls with incremented price until the number of desired completes becomes fully feasible.
Interpreting a Reach Response
Reach V2 returns a series of ranges for completes_prediction and price_prediction at the overall (survey) level and for each target specified. Each prediction has a max and min value, with the difference between max and min representing the model’s confidence about the estimate. When the difference between max and min is small, the model is more confident that the Marketplace will achieve the goal, assuming that all metrics remain in line.
Price estimate fields can return null, which indicates an infeasible input. It may be possible to increase the price field in the request to provide a feasible result, but you might need to remove targeting or improve qualifying characteristics to allow more respondents to qualify.
Project Organization and Survey Grouping
The Marketplace offers two tools for survey grouping. While they appear similar, they accomplish different goals, and a successful integration uses both.
Marketplace Projects
Projects serve to group surveys together and apply respondent security settings. Each Project has a Client attribute, which contains the appropriate settings for SHA-1 hashing. While Clients cannot be created programmatically, you can review the Clients available for your account via the Dictionary endpoint. Each Project has a single Client, but a Client can be used on many projects.
When starting a new logical grouping in your system, create a Project to hold the relevant surveys. This can be accomplished with the Create a Project endpoint, which returns an id parameter for use in your survey creation flow.
Projects can also be used to group surveys for review in the aggregation endpoints discussed below.
Marketplace Survey Groups and Deduplication Configuration
While Projects create logical groupings of surveys, Survey Groups are used to control exclusions between surveys.
Place the survey in a Survey Group to ensure that respondents do not participate in a survey, tracker, or project that spans multiple Marketplace surveys more than once.
For example, if you run a monthly tracker with a three-month exclusion, you would add each month’s survey to a common survey group, then remove the oldest survey from the group.
For a project running with different demographic targets, all feeding the same underlying survey URL in your system, you would also add all surveys to a Survey Group.
Prior to adding surveys, you need to create the Survey Group via the Create a Survey Group endpoint. The endpoint will return an ID parameter, which is needed to access and review the group later. We recommend storing the ID and the member surveys in your system, since there is not a way to determine survey group membership from a survey ID.
Re-entry configuration for a survey group is determined at the account level. Please reach out to your CSM with any questions or configuration requests.
The Marketplace Survey
Surveys are the core of the Marketplace. They hold pricing information, targeting configuration, and links to your survey platform. Suppliers read Surveys and make decisions about which respondents to send, and the Survey keeps track of respondents.
A survey object alone is a framework; it generally needs additional configuration to meet your fielding needs.
Steps to Create and Launch a Survey
- Create a Survey Object
- Add Targeting (Qualifications and Quotas)
- Configure Additional Settings
- Launch your Survey
Create a Survey Object
Use the Create a Survey (beta) to create surveys within your integration. The V2-Beta endpoint aligns with current UI options and exposes configurations and features that improve survey performance.
Surveys are created in awarded status by default. While this field can be overridden, we recommend that you configure your survey with targeting prior to moving the survey to live status.
In the Sandbox, the system modifies the survey status to ensure that a live status is never passed to the Production Marketplace. The Sandbox API returns the status you set, but the Marketplace UI and Production API will always show awarded.
Note: If you set the status of a Sandbox survey to live in the Marketplace UI, the survey will launch, potentially incurring costs.
Key Survey Fields
The Survey model has a number of fields, covering many different use cases. The endpoint only requires fields marked Required on Create here on the initial POST call, but any omitted fields marked Required on Live must be set prior to launch using the Update a Survey unless the field has a Default value.
The following fields are account and project-specific. While some do not change from survey to survey, others must be configured for each individual survey you create.
business_unit_id- The Business Unit in which the survey will be created.collects_pii- Whether or not the survey collects PII. For more information on what constitutes PII, see here.live_url- The URL for your live survey. This is a link to your survey platform, configured with appropriate RID and profiling placeholders.locale- The Country and Language Locale in which you intend to field your survey.name- Internal survey name. For programmatic tracking, we recommend adding an identifier somewhere in this field, such asPO-12345 My Project.project_id- Used to assign a survey to a previously-created Project.project_manager_id- The Project Manager for the survey. The designated Project Manager receives emails about survey status and reconciliations. For integrations with consistent Project Managers, we recommend aligning across systems. For integrations without varied Project Managers, your CSM can configure a designated Project Manager to assign.quantity- The overall filling target for your survey, denominated in eitherprescreensorcompletesquantity_calc_type- Used to set survey quantity denomination as eitherprescreensorcompletes.survey_cpi_usd- The price exposed to suppliers. Use Reach to determine this value as described above. This field does not include any Buyer Fee or Commission.test_url- An optional additional URL for testing. In many cases, this will be identical to thelive_url, but may include additional parameters to designate a test session.
The following fields are optional but should be set for optimal survey performance:
expected_completes- The total number of completes you intend to collect.expected_completion_loi- The expected Length Of Interview (LOI) for your survey.expected_incidence_rate- the expected Incidence Rate for your survey.verify_callback- Set tofalseunless you have been instructed otherwise by your Integration Consultant or CSM. This may align with your account defaults, allowing you to omit the field, but confirm prior to testing any surveys.
Leave the following fields at their account defaults and omitted from POST or PATCH requests:
fraud_profilefraud_profile_thresholdrelevant_idunique_ipunique_pid
Add Targeting (Qualifications and Quotas)
To configure which respondents can access your survey, add Qualifications and Quotas. Qualifications and quotas make up the Marketplace Prescreener, which filters respondents according to qualifications and quotas before they reach your survey platform.
Qualifications
The Qualifications API is part of the V1 API, but is fully compatible with surveys created using the V2 API. Each qualification you wish to add requires its own API call to the endpoint.
In the Qualifications model, the QuestionID aligns with the question_id used in Reach. Similarly, PreCodes are shared between the two.
A Qualification is a single question and its conditions are evaluated in an or condition for single-select questions, and optionally in and condition for multi-select questions.
If you want to allow all conditions, pass an empty list [] as the value for PreCodes. This is equivalent to adding every answer option available for the question. We recommend adding all answer options when creating complex quota logic or using Qualifications to collect demographic data.
Order matters for some Qualifications, especially for any dummy Qualification, which relies on a previous Qualification to set its value. When using region questions in the United States, you must add the ZIP Code Qualification before any region question. To avoid issues, set its order argument to 1 and all subsequent questions to a higher number.
Quotas
Quotas allow combinations of questions and answers, along with quantity limits. Quotas are similar to Qualifications, but may have more than one question in the Conditions field.
Before a question can be used in a Quota, you must add it as a Qualification.
Conditions within a quota have an and relation between questions, and an or relation for conditions within the same question.
The Quota model has a field for Quota, which is the respondent limit, calculated on either completes or prescreens depending on the quantity_calc_type attribute of the survey. The model also has a field for FieldTarget, renamed to Completes Goal in the UI, which is used by Fielding Assistant.
You can also use Quotas to express complex targeting, including not conditions. To restrict or block a joint condition, create a quota on the conditions you wish to block and set its Quota to 0.
Quotas do not have to cover the entire range allowed by Qualifications. When developing complex targeting, consult your CSM on best practices. They can also assist in setting up example surveys which your Integration Consultant can provide as JSON.
Configure Additional Settings
Once you set all of the parameters necessary for launch and configure all targeting, you can launch your survey. However, there are several additional options you can apply, including automated fielding modes or more detailed supplier allocations.
Applying Fielding Assistant
Fielding Assistant is a suite of machine-learning-powered automation tools for survey fielding. We recommend using Fielding Assistant to avoid complex polling and update routines while your survey is in field.
You can apply a Fielding Assistant goal to your survey at any time before or during fielding using the Survey Configuration endpoint. The most common goals for integrations are detailed below:
- Dynamic Pacing - Best for most integrations. This goal gives you the simplicity of targeting based on Completes without the risk of overfilling your survey. When Dynamic Pacing is enabled, quota
FieldTargetfields represent completes and Fielding Assistant manages the actual quota in prescreens to reach the target set in theFieldTarget. - Even Pacing - Paces completes over a fielding period using
FieldTargetas completes. - Balanced CPI Model - Does not control completes. This goal optimizes CPI within your budget to deliver all requested completes by the
completion_timestampdeadline. Calculate thetotal_budgetfield as(number of desired completes) * (expected CPI).
Other Settings
- Supplier Allocations - If you want to use a different supply blend than your account default, consult your CSM on how to set up a Marketplace Template of suppliers, then use the Apply a Marketplace Template endpoint to apply it to your survey.
- Recontacts - The Marketplace has several tools to recontact previously-surveyed respondents. You can upload a list of IDs using the Update Qualified Respondents endpoint. You must also configure specific survey parameters. Contact your Integration Consultant for more information.
Launch Your Survey
Once you complete all configuration, launch your survey by making a PATCH call to the Update a Survey (beta) endpoint to set the status parameter to live. At this time, your survey becomes visible to suppliers, who can then send respondents. If you enabled Fielding Assistant, it will begin to manage your survey on launch.
In-Field Management
After moving your survey to live, Marketplace suppliers will send respondents to the survey. As respondents move through the prescreener, your quotas update to track respondents who reach your survey platform. When a respondent returns to the Marketplace via a redirect, appropriate quotas and counts update.
We recommend that you consistently check on the status of your survey. Most integrations poll every five or ten minutes and retrieve data from live surveys.
Common Items to Retrieve
- Survey Overview - Call the Survey endpoint for an overall picture of your survey.
- Statistics - The Statistics (beta) endpoint shows an overview of respondent counts and computed metrics. Use this endpoint to retrieve current EPC (Earnings Per Click), Median Length of Interview, and Incidence Rate.
Incidence rate must be calculated from data in the client_status object, using the values at the following keys: "10" / ("10" + "20").
See this page for more information on how to calculate fielding metrics. * Quotas - Call the List Quotas endpoint to retrieve current complete and prescreen counts for all quotas. You can also use this response to format your quota updates, since the update is a PUT request and must contain all current information.
Updating Pricing
If your metrics for LOI and IR have drifted from your expected ranges, re-run your Reach request using the new metrics to determine whether to change your price. The Reach V2 endpoint has optional parameters for completes_collected and current_date, which you can use to indicate current progress.
To change your CPI, make a PATCH call to the Update a Survey (beta) endpoint to change the value for survey_cpi_usd.
Updating Qualifications and Quotas
While Qualifications can be updated in field, we recommend that you make most changes to Quotas. If you need to make significant changes to the Qualifications in your survey, we suggest closing the survey and creating a new survey with updated targeting.
To change Quotas, do the following:
- Call the List Quotas endpoint to retrieve current quota specifications.
- For each quota object you intend to update, change the
FieldTargetparameter if using Fielding Assistant or theQuotaparameter if not. - Send each new JSON Quota object to the Update a Quota endpoint, making a unique call for each quota.
Closing a Survey
When you have reached your overall fielding target, change the survey status to pending or complete. This prevents any further respondents from entering and marks any respondents in the survey as Client Status 136 (Quality Term - Survey Closed).
If you are using Fielding Assistant Dynamic or Even Pacing, your survey will move to pending automatically when your survey reaches quantity.
Reporting and Analytics
The Marketplace Demand API offers several endpoints to gather information about surveys. You can use the reporting endpoints for in-field tasks or after fielding to retrieve information about your surveys over time.
- Sessions - The Sessions endpoint lists all respondents for a survey over a specified period of time. You can review these records to confirm respondent statuses or identify dropouts.
- Statistics - See above.
- Reports - To create a summary of full pricing for a survey including Buyer Fees and Commissions, use the Reports endpoints. You can retrieve data as either a JSON object or PDF. The full pricing summary available from these endpoints reflects the full price that will be invoiced.
Note that the Reports endpoints are not available in the Sandbox.
Reconciliation
The Reconciliation process allows you to change the statuses of respondents after the conclusion of fielding. This change may be negative, to remove respondents for poor quality, or positive, to fix redirection or survey completion errors.
Respondent sessions can be reconciled in the month that the complete was achieved or in the month following.
For example, a complete registered on May 2nd could be reconciled up until 11:59PM CST on June 30th. A complete registered on May 31st could also be reconciled up until 11:59PM CST on June 30th.
You can reconcile a session multiple times within the reconciliation window described above.
Reconciliation Logic
The Reconciliation API works at the survey level. To reconcile respondents on a specific survey, provide a list of all RIDs you wish to retain for that survey. Any RIDs associated with that survey and not present in your reconciliation request are re-statused to Client Status "26" and excluded from invoicing. RIDs that move from a terminate status to complete are assigned Client Status "11".
If your reconciliation includes RIDs that are outside of the reconciliation window, the system ignores those RIDs. Likewise, if you include RIDs that are not associated with the survey you are reconciling, the system ignores those RIDs in the request.
Reconciliation Workflows
Surveys must be in complete status to reconcile. While you can close a survey to reconcile, then reopen, most integrations reconcile at the end of fielding or on a monthly basis.
- Ad Hoc/Per Survey - Reconcile surveys at the conclusion of fielding. For low-volume integrations, you can trigger this process when a project manager approves IDs.
- Bulk = Reconcile all surveys with additions or removals on a recurring cadence. Use this approach if your surveys regularly finish close together, or you have many project managers working on surveys.
The Reconciliation API has a rate limit of 10 calls per minute. To avoid rate limit errors, queue your requests regardless of which approach you take, waiting a few seconds between each request.
Reconciling a Survey
- Create a list of RIDs to keep. Usually, this comes from your survey platform.
- Check that all RIDs are within the reconciliation window. While you can submit a request containing non-reconcilable RIDs, you should exclude those RIDs prior to submission to ensure accurate counts of removed RIDs.
- If reconciling across surveys, match each RID to the appropriate Marketplace Survey ID. This is the
idfield on the survey object. - Compose a list of all RIDs to reconcile for a survey and upper-case all letters in the RIDs.
- Ensure that your survey is in
completestatus. If it is not, update the status tocomplete. - Make a POST call to the Reconcile a Survey endpoint.
- Wait for a few minutes while the request processes. Most reconciliations process within a few minutes, but during high-volume times such as the end of the month, processing can take several hours.
- Use the reporting endpoints to validate the reconciliation and ensure that complete counts match between your system and the Marketplace.
V1/V2 Compatibility Notes
As discussed above, the V1 and V2 endpoints are mostly backwards-compatible. The following are a few useful notes and best practices to follow while using both APIs.
- Do not mix V1 and V2 for survey creation and updating. If you use the V2 Surveys API to create your survey, continue to use V2 endpoints to update the survey object.
- On surveys created with V2, use the Update a Survey endpoint to change the
Quantity, rather than using the Quotas endpoint to adjust thetotal_quota.
Demand Integration
A Marketplace Demand API integration gives you instant access to millions of human sessions right inside your own application, effectively eliminating additional training requirements, duplication of effort, and overhead associated with scaling. The Demand API also offers in-depth Demand-Side Platform features, allowing you to manage hundreds of suppliers on the Marketplace while simultaneously controlling the exact targets and quotas you seek.
Before getting started, it’s important to note that all testing and development should be done in the sandbox environment. Information on environments and other foundational topics is available in the Introduction and should be reviewed before moving on to Phase 1.
Phase 1: Things to Know Before You Start
Mapping Qualifications
Targets are created through a combination of Qualifications and Quotas. Qualifications define the type of respondent you are looking for to complete the survey. Quotas allow you to control how many of each of those respondents you want.
Marketplace contains hundreds of Standard Qualifications, translated into many languages. These Standard Qualifications are viewed as industry standards for programmatic targeting. As such, your Surveys will be most successful when Standard Qualification targeting criteria is used. For more information regarding Qualification best practices on our platform click here
To use Marketplace Standard Qualifications, store the Qualification question texts and answer options for all Country-Languages you plan to run surveys in. You will use these Qualifications in Phase 3 of your integration.
For each Country-Language you plan to run surveys in, we recommend first mapping to the most-used Marketplace Qualifications. Below are the top 20 Marketplace Standard Qualifications for United States-English:
AGEGENDERZIPHISPANICETHNICITYSTANDARD_HHISTANDARD_EDUCATION_V2STANDARD_EMPLOYMENTSTANDARD_INDUSTRY_PERSONALSTANDARD_JOB_TITLEParental_Status_StandardAge_and_Gender_of_ChildSTANDARD_NO_OF_EMPLOYEESSTANDARD_INDUSTRYSTANDARD_WEBCAMSTANDARD_COMPANY_REVENUESTANDARD_B2B_DECISION_MAKERSTANDARD_COMPANY_DEPARTMENTSTANDARD_HISPANIC_ACCULTURATIONSTANDARD_HOMEOWNER
For a list of top Qualifications in other Country-Languages please reach out to your Integration Consultant at integrations@cint.com. For a full list of Qualifications in all available Country-Languages use the Question Library call.
Redirects
At the end of each Survey, a Redirect will send the respondent back to the Cint Marketplace. It is important that these Redirects are configured properly, as they indicate how the respondent should be compensated. For example, these redirects will indicate if the respondent is a Complete, Term, or Overquota.
When using our Secure Client Callback security solution, the Redirects are still necessary in order to return the respondent back to the Marketplace. For more information about how to configure your Redirects or the Secure Client Callback solution, please contact your Integration Consultant at integrations@cint.com.
Tracking Respondents
The Respondent ID (RID) is the primary respondent identifier. It is a unique session ID that is assigned each time a respondent enters Cint Marketplace. It is critical this value is appended to the end of your Client Survey URL. If it is left off, respondents cannot be tracked from Marketplace and the Suppliers will be unable to compensate them.
Details on how to construct your Client Survey URLs can be found here.
Phase 2: Security
We recommend reviewing the best security settings for your integration with your Integration Consultant and Client Success Manager before beginning development.
Deduplication
Marketplace offers deduplication on IP Address and Panelist ID (PID) within a single Survey as well as across a group of Surveys that are within a single Survey Group. A PID is a unique string assigned to the respondent by their Supplier. This ID is unique per respondent but persistent across Survey sessions.
These deduplication settings can be enabled at the Survey level and the Account level. For information regarding how to enable this on the Survey level see Phase 3: Survey Creation. To enable respondent deduplication settings on the Account level, contact your Integration Consultant at integrations@cint.com .
Secure Client Callback (SCCB)
This solution, while the best option for securing completes, is only available to develop against for clients that have ownership of their Survey Platform. You may still use other survey platforms that have developed this integration. For more information on a list of platforms supporting SCCB, please reach out to your Integration Consultant at integrations@cint.com . To indicate a respondent has completed the Survey a server to server call is made in conjunction with the respondent Redirect. For an added level of security, you will be provided with a separate API key to be used only for the SCCB. For access to this API Key and an Implementation Guide please contact your Integration Consultant at integrations@cint.com.
Phase 3: Survey Creation
Step 1: Feasibility and Pricing
Gauge the feasibility of an target and set a price per complete by using Reach.
If the tool you are building will display a price to your end users, remember to markup the output of our feasibility methods to add Marketplace commissions and fees, and your desired margins.
Step 2: Survey Workflow
While using the Survey Create Call the following details are important to be aware of:
If using Reach, input the determined Price as the
QuotaCPI.- NOTE:
The QuotaCPIrepresents the amount to be paid per complete. TheQuotaCPIshould not include Marketplace commissions and fees, and/or your desired margins.
- NOTE:
IsActive: This parameter controls the availability of the Marketplace Survey within our database. This should be hardcoded to
trueand should not be changed at any time. If you need to “delete” a Survey use theSurveyStatusCodes.Survey Level Security: We recommend hardcoding the following Survey Level Securities. Definitions for each parameter can be found here.
verify_callback: falseunique_pid: trueunique_ip: true
Survey Live URL: We recommend a URL length of 2,000 characters or fewer to ensure compatibility with the widest range of browsers. Whether using v1 parameter
ClientSurveyLiveURLor v2-beta parameterlive_url, URLs for Surveys must conform to the patternhttps://mysurveydomain.com/valid_path?valid_query_string=truewhere there are:- A valid protocol:
https:// - A valid domain:
mysurveydomain - A valid domain extension:
.com - A valid path if included:
/valid_path - A valid query string if included:
?valid_query_string=true - No spaces in the URL
- 3,000 characters or fewer
- A valid protocol:
Quota is the total number of respondents you are looking for. NOTE: This number can only be updated on the UpdateSurvey call. The UpdateQuota call is used to update sub-quotas only and does not allow updates to the total quota.
SurveyStatusCode Create a Survey with the
SurveyStatusCode: 01which is the “awarded” status. This means the Survey has been created in our system, but Suppliers cannot see it. When the Survey set up has been completed and your Survey is ready for respondents, use the UpdateSurvey call to change the Survey Status to live usingSurveyStatusCode: 03The most commonly used Survey Statuses are:- awarded (created and only available within your account to adjust)
- live (available for Suppliers to send respondents to)
- pending (pausing the Survey in order to fix or adjust the Survey or pause the influx of fielding)
- complete (the Survey is finished fielding)
- archived (Survey deleted)
Enable the Cint Marketplace: To ensure Suppliers have access to the Survey when it is set live, set the following parameters:
FulcrumExchangeAllocation: 0FulcrumExchangeHedgeAccess: true
Phase 4: Target Creation
Step 1: Qualifications Workflow
Before using Qualifications, it is necessary to map Marketplace Standard Qualifications to your system. Cint has hundreds of Standard Qualifications you can choose from. You can see the available Qualifications by Country-Language in our Global Definition Questions Library.
Please be sure you have mapped to our Qualifications as described in Phase 1 before continuing on.
When creating a Survey with the Country-Language US-English, the following Qualifications will be auto-added to the Survey:
1. AGE
2. GENDER
3. ZIP
4. STATE
5. ETHNICITY
6. HISPANIC
7. STANDARD_HHI_US
After the Survey is created, these qualifications can be modified or removed using the UpdateQualification call.
Keep in mind that there are restrictions on the age of respondents based on the location the Survey is being run in. For details of age requirements around the world contact your Integrations Consultant at integrations@cint.com
Step 2: Quotas Workflow
Quotas define how many of each type of respondent you need to complete your Survey. A qualification must be added to the Survey before a quota can be created for that qualification.
Quotas can be nested or unnested, overlapping, or contain only a subset of the qualified respondents. Here are a few examples of different quota structures:
- Study 1: only total quota
- Total = 1000
- Study 2: nested gender and age
- Total = 1000
- Male 18-35 = 250
- Male 36+ = 250
- Female 18-35 = 250
- Female 36+ = 250
- Study 3: separate gender and age
- Total = 1000
- Male = 500
- Female = 500
- 18-35 = 500
- 36+ = 500
- Study 4: separate gender and nested gender and age quotas
- Total = 1000
- Male = 500
- Female = 500
- Male 18-35 = 250
- Male 36+ = 250
- Female 18-35 = 250
- Female 36+ = 250
Phase 5: Control the Supply
Enable the Cint Marketplace To ensure your surveys are available on the Cint Marketplace, be sure to enable the Cint Marketplace.
Marketplace Templates Marketplace Templates allows Buyers to control which Suppliers have access to their Surveys. An Marketplace Template will spilt our Suppliers into buckets and you can control the percentage of completes available to each bucket. For more information regarding Templates and what will be best for your workflow please contact your Client Success Manager at success@cint.com.
Non-Marketplace Allocations Marketplace allows buyers to bring on Supply partners that might not be integrated with the Cint Marketplace. This workflow can be achieved by creating Non-Marketplace Allocations and then creating Non-Marketplace Links. If you are interested in bringing on a new partner, please reach out to your Client Success Manager at success@cint.com.
Phase 6: Fielding the Survey
Set the Survey Live
Setting a survey live makes the opportunity visible to our Suppliers. To do this, use the UpdateSurvey call and change the SurveyStatusCode to 03 which is “live”.
Tracking Survey’s Performance Use the Statistics method to check the health of your survey throughout fielding. We recommend calling this endpoint every 3-5 minutes. This document has human readable translations for the Marketplace Status IDs and the Client Status IDs returned on the Statistics call.
Update Quotas
To adjust the Total Quota to allow for more or fewer respondents to complete a survey, use the UpdateSurvey call to change the Quota parameter.
Note: The Total Quota needs to be greater than 0 to allow respondents to access your survey, regardless of the available sub-Quotas.
To update your sub-quotas use the UpdateQuota call to adjust each sub-quota.
Closing the Survey
When your survey has achieved the desired number of completes you need to remove the opportunity from the Marketplace. To do this, use the UpdateSurvey call to change the SurveyStatusCode to 04 which indicates “complete”.
Phase 7: Collecting Data
Buyers can collect respondents’ targeting information by appending Standard qualifications to the Client Survey URL. To achieve this, append &QualName=[%QUALNAME%] to the end of your Client Survey URLs. Keep in mind, the Client Survey URLs have a maximum length of 3000 characters. A list of available Standard Qualifications can be found on the ListStandardQuestion call.
Buyers can append a number of variables including Supplier information and additional IDs. To see a full list of available variables check out our Support Site Article
To collect data associated with each respondent that accesses your Survey, at the completion of fielding, use the Sessions call and store the response. Marketplace auto-archives all data after 90 days; we recommend storing this data on your side so it is accessible in your system at any time. After 90 days you will need to request that data from our Support Team by submitting a request to support@cint.com
Phase 8: Additional Features
Recontacts Recontact surveys allow you to re-invite respondents from a previous survey to a new survey, to ask follow-up questions to specific respondents and track new responses back to the respondent’s original survey session.
Please note not all of Marketplace Suppliers are able to recontact their respondents. Suppliers that can recontact respondents have recontact success rate ranging from 10-50%.
Recontact Set Up:
Step 1: Survey Create
Create a survey by following the steps outlined in Phase 2 with the additional step of setting the StudyTypeID to 22 to indicate that this is a “Recontact Study".
Step 2: Setting Recontact Marketplace Template
Apply the Marketplace Template ID 97 to reach Suppliers that support recontact studies.
Step 3: Adding the PID Check Qualification
Use the CreateQualification call to add the Standard Qualification “PIDCheck” with a condition of 1. This is the mechanism that will ensure the respondents that access your survey will match the respondent PIDs you are requesting.
Step 4: Adding List of Respondents
Use the UpdateQualifiedRespondents call to send a list of qualified Respondents. In addition to the PID, you will need the original Survey Number and the Supplier Code associated with the PID. To obtain the Supplier Code use the List Suppliers call.
Step 5: Field Survey
Use the UpdateSurvey call to set the survey status to “Live”. Once you have achieved the completes, use the Update Survey call again to set the survey status to “Complete”.
Reconciliations Cint’s Reconciliation Policy gives Buyers rights to reject completes they deem to be poor quality. For details regarding Cint’s Reconciliation time frame, acceptable and unacceptable reasons for Reconciliation, and required supporting data, please click here.
Phase 9: Testing and Launch
Contact your Integration Consultant to set up a time to run the following tests. This will ensure an Integration Consultant is available for monitoring, troubleshooting, and answering questions.
Testing Plan:
Survey 1: Create a survey in the Marketplace
Using your production credentials, it is meant for an Integration Consultant to confirm that it is set up in the Marketplace is as expected. This survey should not be set live
Survey 2: Create a survey with a small N size (50 completes or less)
This survey is meant to be set live to test redirects, respondent flow, and the overall respondent experience.
Survey 3: Create a survey that would reflect the price, N size, and target of a typical survey the integration is expected to run.
This survey is meant to ensure every aspect of the integration, and any fixes that were done as a result of Test Surveys 1 and 2, are working as expected.
Testing Success: During the fielding of Test Surveys 2 and 3, the Integration Consultant will monitor and analyze success based on the following metrics:
- Survey Performance
- Field time
- Feasibility & pricing accuracy
- Incidence rate variance
- Survey outcomes
- Review overall respondent flow
- Confirm Security Setting worked as expected
- Review final data
Once all three surveys are successfully created and fielded as expected the integration is ready to launch. After the integration has launched the Integration Consultant and Client Success Manager will monitor metrics and performance within Cint’s ecosystem. We expect our clients to continue to monitor their own applications for errors or issues. If you come across anything unexpected please reach out to your Integration Consultant as soon as possible.
Supply Integration
A Supply API integration gives you and your respondents instant access to thousands of Cint Marketplace opportunities globally. The Supply API gives you the ability to find and filter new survey opportunities, send targeted respondents using survey qualifications and quotas, and strategically rank survey opportunities in order to maximize revenue.
The following sections will guide you through the key stages of development.
Mapping
The Cint Marketplace contains numerous objects, structures, and options that should be mapped to your system.
1. Store our system definitions and map them to your system.
These definitions provide human-readable strings that correspond to various object/option IDs in the Cint Marketplace.
2. Store Marketplace Standard qualification question texts and answer options for countries you operate in.
Mapping your respondents to the Cint Standard Qualification library enables you to match your users to appropriate surveys. A lack of profiling can result in higher terminations and a poorer user experience.
To future proof your integration, we recommend that you map to all the standard qualifications for each country-language pairing you have respondents for. Once you are mapped to our question library you can begin the process of prioritizing which qualifications to profile your users on. To help you with this, we have segmented the Standard Qualification library into three tiers, ranked in importance:
- Critical Qualifications
- Primary Qualifications
- Secondary Qualifications
In order to launch your integration with Cint, you will be required to have profiled your respondents on all Critical Qualifications for each market you have users in. To enable you to match users to more survey opportunities, we strongly recommend you incorporate Primary Qualifications into your initial development phases. You can download the Supplier Qualification Tier file here.. To understand more about Standard Qualifications, best practices for profiling, and more, please visit our profiling guide.
3. Understanding Marketplace Qualifications
Example Marketplace Entry Link, with Respondent Data appended:
https://www.samplicio.us/s/default.aspx?SID=f6c83654-3d4f-4f7c-bef1-2f5097b6ae9c&PID=12345&MID=54321&43=35&43=2&45=70117
Example Marketplace Exit Link, with Respondent Data appended:
https://www.supplierURL.com?status=complete&PID=[%PID%]&MID=[%MID%]&42=[%AGE%]&43=[%GENDER%]&45=[%ZIP%]&47=[%HISPANIC%]&113=[%ETHNICITY%]
Marketplace Standard Qualifications are industry standards for programmatic survey targeting. A survey’s qualifications form the prescreener questions that are presented to each respondent before they leave the Marketplace and enter the client survey.
- Questions and their conditions make up qualifications—the respondent demographics needed to complete the survey.
- Conditions are created by questions to form a qualification, which specifies who is allowed into the survey. For example AGE and GENDER are questions. If the client is looking for AGE 18-24 and only Males, those would be conditions. The qualification would be Males, 18- 24 years old.
- A client may not necessarily build quotas off of all qualifications. It’s very important to use both qualifications and quotas when determining whether to send your respondent.
- You should pass respondent demographics on the Marketplace entry link allowing the respondent to bypass pre screener questions.
- Respondents will also bypass questions they have already answered in the Cint Marketplace. You can capture this data by including demographic variables in your supplier redirects.
- The Marketplace will pass back stored demographic data if the respondent has answered that question within the last 30 days. 30 days is the expiration period for all demographic data.
- If demographic data is returned on your supplier redirect which you do not have for your panelist, then update your panelist profile with this information to improve your targeting.
- If you already have that demographic information stored, then you should use your own as the source of truth.
- We recommend including the top 20 qualifications on your return redirects to capture valuable demographic data on your respondents. Please speak to your Account Team to get additional qualifications added to your default redirects.
4. Understanding Marketplace Quotas
Quotas determine how many completes of each type of respondent are allowed into the survey. Quotas are always created off Marketplace qualifications.
Marketplace quotas can be nested, overlapping, or contain only a subset of the qualified respondents. Here are a few examples:
- Study 1: only total quota (no subquotas)
- Total = 1000
- Study 2: nested gender and age
- Total = 1000
- Male 18-35 = 250
- Male 36+ = 250
- Female 18-35 = 250
- Female 36+ = 250
- Study 3: separate gender and age
- Total = 1000
- Male = 500
- Female = 500
- 18-35 = 500
- 36+ = 500
- Study 4: separate gender and nested gender and age quotas
- Total = 1000
- Male = 500
- Female = 500
- Male 18-35 = 250
- Male 36+ = 250
- Female 18-35 = 250
- Female 36+ = 250
Important Details:
- To receive quota data via OTS Opportunities set filter
"include_quota":truein the body of the POST request - Quotas are distinguished by
survey_quota_idproperty. - A respondent qualifies for a quota cell if they fit all of the conditions of the qualifications.
- The logical operator is “OR” within the same quota qualification (i.e. AGE 18 OR 19 OR 20), but AND between quota qualifications (AGE 18 OR 19 or 20 AND Male OR Female)
For details on how to match your respondents to Qualification and Quota data, see section matching respondents to survey data.
5. Identifying and handling Custom Qualifications
Buyers are able to choose to expose custom qualifications to suppliers at the survey level. Your OTS Opportunities subscription, when opted in to include qualification data, will return a list of all question IDs for a given study—standards and exposed customs. The List Standard Questions call only returns all standard qualifications. Therefore, if a question ID returned via the OTS Opportunities message is not in the Standard library, you can assume it is a custom. You can then look up the details on the fly for profiling respondents using the Show Question Text call and the Show Question Options call.
Getting Survey data
In this phase, we’ll explain the recommended process to find new survey opportunities, receive and store qualifications, quotas, survey groups and recontacts data in tables locally to be referenced later.
1. Recommended Supply API Call Interval
| API Call | Ideal Interval (in minutes) |
|---|---|
| Show Survey Statistics | 60 |
| Opportunities Subscription | Pushed to your callback every 15 seconds |
| List a Survey’s Groups | 10 (if in survey group) |
| Create a Link | Once |
| Show a Link | Optional |
| List Statistics | Optional |
| Update a Link | Never (unless project-specific) |
2. Opportunities Subscription
Opportunities subscribes you to receive messages containing live studies currently available to you on the Marketplace. The Opportunities model will be returned to your callback url every 15 seconds* for any new or updated survey opportunity that matches the criteria specified in your subscription. A survey will only return on this call if there are completes available to you.
Select and filter surveys based on desired criteria not already established in your subscription (e.g. country, study type, PII collection, acceptable LOI, and CPI)
*You can adjust how frequently you receive survey data, the size of the payload and the number of surveys in the callback message. Please refer to the argument section of OTS Opportunities on how to create these filters.
3. Qualifications and Quotas
Include "include_quotas": true in the body of the Create Opportunities subscription request to receive qualification and quota data. Get and store the survey qualification conditions and quota data in your tables
4. Survey’s Groups
Marketplace buyers place surveys in survey groups to avoid duplication across multiple surveys. Buyers may add or remove surveys from survey groups as their deduplication needs change. You should avoid sending the same respondent to all other surveys in a survey group if that respondent previously attempted one of that group’s surveys. The Opportunities model message returns the property survey_group_ids, which can be used to determine if the List a Survey’s Groups call should be made for that survey.
Below is the recommended process to check and update survey groups every 10 minutes:
- Observe the Opportunities model message.
- Check the
survey_group_idsproperty. An empty array indicates this survey is not part of a survey group. Any values within the array indicate the survey groups this survey belongs to - If
survey_group_idsis empty then no additional steps are needed. - If
survey_group_idsis not empty then the survey is in a survey group and you should make the List a Survey’s Groups call for that survey. - Store the
SurveyGroupIDand associated surveys from theSurveyGroupSurveysarray. On future polls remove or inactivate survey numbers not returned for thatSurveyGroupID. - Do not send a respondent to more than one survey in each survey group. If a survey is removed from a survey group, you may begin sending respondents you sent to that particular survey to other survey numbers remaining in that group.
5. Recontacts
Buyers often want to recontact respondents that have completed their surveys in order to ask follow-up questions. These surveys are known as recontact studies and have a study_type of 22 in Cint Marketplace. These studies are unique in that buyers will upload a list of PIDs that the supplier can then use to identify respondents that qualify for the opportunity. All recontact studies will have a unique Qualification, respondent_pids, that will terminate PID and supplier combinations that are not in the buyer’s PID list.
Below is the API process flow for recontact studies:
- To receive recontact surveys via your OTS Opportunities subscription either include a study_type filter containing
recontactor exclude the study_type filter altogether. - Observe the Opportunities model message and capture any PIDs returned in property
respondents_pids. - Only send those respondents to the study.
- If
respondents_pidsreturns an empty list, you do not have any qualifying respondents.
Creating an Entry Link and Setting Redirects
Once you have identified a survey opportunity, create the entry link. This call will return “live” and “test” links. The “live” link is where you should send your respondents. The test link can be used for running any User Acceptance Testing as outlined in the testing phase.
When creating a link you can specify custom redirects to be applied to that survey. If this information is not included in the payload your default supplier redirects will be used. Session and profiling data collected in the Marketplace can be passed back to you on the redirect links. Please reference our Collecting Data From Redirects article to understand what data can be returned.
If you receive a 404 error when creating a link, this can signal that you have been given a “targeted” or “OTC” allocation by a buyer. In these cases the buyer typically creates the entry link for you. Use the Show a Link call to retrieve your entry links.
When sending respondents into the Cint Marketplace we require you to append session, demographic and hash parameters to the entry link. Please review our generating API entry links article to understand what data you’ll need to pass in and how this should be formatted. Note: entry links have a character limit of 1999. If this is surpassed it will trigger an error and the respondent will be unable to enter the Cint Marketplace.
Matching respondents to survey data
This section provides guidance on how to match your respondents profiles to survey data to ensure users are paired to the right surveys. This is a fundamental step towards maintaining a healthy survey entry rate.
Qualifications
- Qualifications Check: The goal of this check is to determine if the respondent’s “Profile Data” would disqualify them based on the qualifications used on the survey. Apply the decision tree below to the EACH qualification question used on the survey. If ANY qualification question results in a “Fail”, do not send the respondent to this survey.
- Unmapped Qualifications: If there is a qualification that you are currently not mapped to but is a part of survey qualification, you should still send the respondent into the survey. If the respondent fails this qualification, the information would be passed back on the redirects, which can be collected and be used to enhance the respondent profile. However, if the qualification(s) not mapped is part of our Top Standard Qualifications, we strongly recommend profiling your respondents on these qualifications to avoid high Standard Qualification Terminations.
Quotas
Ensure the following logic in place to prevent respondents from attempting a survey if any of the following are true:
- Is the survey still live?
- Is OTS Opportunities is_live property false?
- Is the respondents redirect InitialStatus value 42?
- Is the number_of_respondents property greater than zero for the survey_quota_id with a survey_quota_type value of Total? (Essentially, if that total quota is closed any respondent will result in an overquota, regardless of what other quotas may still be open. )
- Is the number_of_respondents property greater than zero for all survey_quota_id that a respondent falls into? A respondent may fall into more than one quota. For example, there may be quotas for gender and quotas for age, in which case a respondent may fall into two quotas, both of which must be open, for the respondent to pass.
Survey re-entry rules
If a respondent with the same PID, cookie or IP address is sent to a survey they have already taken in the Cint Marketplace, they will be immediately terminated on a Marketplace duplication response code. To avoid these terminations you’ll need to implement logic in your system to stop:
- Sending a respondent(s) to the same survey. Apply rules to prevent the respondent from being able to access the same survey repeatedly. This also covers stopping multiple respondents who use the same IP address (eg within the same household) from entering the same survey ID.
- An individual from creating multiple accounts within your system and attempting the same survey on multiple occasions.
Keeping your Survey tables up to date
In this phase we’ll explain how to update your live survey tables. The main goals in this phase are to ensure you’re sending sample only to live surveys and respondents to surveys with relevant open quotas.
1. Opportunities Subscription
Opportunities returns new surveys and updates to all live surveys where the supplier has an allocation and meets the criteria specified in your subscription. Your survey update processes should be performed based on the results of this call.
- Update LOI of all surveys.
- Update the country (rarely changes).
- Pause surveys that are live in your system but return with the
is_liveproperty equal tofalse(the buyer has paused or closed the survey) or themessage_reasonproperty equals todeactivated(survey no longer meets your subscription criteria). - Set surveys live that are paused in your system but return
is_liveequaltrueormessage_reasonequalreactivatedon this call. - If this call returns a survey and you did not create the link via Create a Link then you have been given a “targeted” allocation or “OTC” allocation.
- In these cases the buyer typically creates the entry link for you.
- Use the Show a Link call to retrieve you entry links.
2. Qualifications and Quotas
Overwrite stored qualification and quota data for each survey.
3. List a Survey’s Groups
Capture any new survey numbers associated to the SurveyGroupID whilst removing or inactivating survey numbers not returned.
Yield Management
Yield Management is the process of selecting and ranking viable survey opportunities to ensure that the best performing studies receive the most amount of traffic, and surveys falling below any desired metric thresholds are deprioritised or not considered. Our recommendations on how to build out an effective yield management algorithm can be found in this article.
Security
It is important as a Cint Supply Partner that the traffic you send into the Marketplace is of good quality. If your reconciliation rates exceed the thresholds outlined in our Partner Improvement Program, you can be subject to traffic being paused in the affected countries. To understand what are the core security features required to mitigate against poor quality users and fraudulent activity, we provide multiple resources, all accessed in the Security Documentation section of our Cint Supplier Portal. Access to the Supplier Portal will be granted during onboarding.
Session and reconciliation data collection
This section explains what options are available to track session outcomes and the benefits of this. We’ll also provide resources to help you understand the Cint reconciliation process, what you’ll need to implement to track this data, and why it’s important to do so.
1. Tracking session outcomes
For each respondent that moves through our marketplace we will store a Marketplace and Client response code pertaining to the outcome of the session.
You can find detailed information about these response statuses on the Cint Support Site: Marketplace Response Code and Client Response Code. We recommend storing these response codes in your database to track respondent session outcome activity as it happens in the marketplace. This has a number of advantages, including;
- Providing granular information on how your integration is performing. It will shine a light on where optimisations are required, such as reducing Marketplace Termination
- Empowering Yield Management decisions. Adjust the flow of users to surveys based on in-field performance metrics
- Regulating respondent survey access based upon security failures, most notably;
Below are the available options to capture session outcome data.
2. Redirects
To collect the Marketplace and Client response codes for each respondent session ensure the below parameters are appended to all of your redirects. Our collecting data from redirects article provides more information on what parameters can be appended and the formatting options available.
MarketPlaceStatus=[%InitialStatus%]&ClientStatus=[%ClientStatus%]
3. On-time Supply Outcomes
Create an outcomes subscription to receive near real-time notifications on respondent sessions. You will receive messages on new sessions outcomes, or when a change occurs to a respondents response code. Our recommendation is to receive events for all available response codes, but if you want to limit to specific outcomes you can achieve this through the filtering options available. See our FAQ article for some example subscriptions.
4. Monitoring reconciliations
Cint’s policy allows respondents to be reconciled from a complete to a termination (negative reconciliations) and from a termination back to a complete (positive reconciliations). Monitoring this data closely is an integral measure to ensuring high quality traffic/respondents and maintaining a low reconciliation rate. If your reconciliation rate exceeds the threshold set-out in our Partner Improvement Program, you can be asked to pause traffic in the affected countries.
To ensure you are tracking reconciliation data, we recommend you create a subscription to On-time Supply outcomes to receive notifications when a respondent is positively or negatively reconciled within the marketplace. Getting this data in near real-time enables you to automatically regulate a respondent survey access and mitigate against fraudulent activity.
For more information on how to identify, minimise and handle reconciliation data please click on this link.
Testing and Launch
In this section we’ll explain the steps you should go through to test your integration and outline the core development required to execute a successful soft and full launch.
Testing
Once your integration is set-up it’s time to test! We have provided a few simple options to help you test your integration. This testing enables you to validate that your system is able to match respondent profiles accurately to surveys and you can receive and parse the parameters appended on the redirect links, including the hash signature.
1. Respondent matching validation
When creating a link for a survey, by default we will return a TestLink in the body of the response. This test URL can also be retrieved via the show a link call.
Example TestLink:
https://www.samplicio.us/s/default.aspx?SID=a948gef7-3591-42c0-ce51-0e4jdf25582f&FIRID=MSDHONI7&SUMSTAT=1&PID=test
This test URL allows you to participate in the survey prescreener similar to that of the live survey. It’s a great way to test the respondent’s experience and validate that you are able to match a user’s profile to the qualification and quota criteria. Once the prescreener phase is complete you will be presented with a useful session outcome report outlining if the user has matched the survey criteria, and if not, why.
Note: all standard security checks within the marketplace are deactivated for the TestLink.
2. Redirect testing
We have created test surveys to enable you to run end-to-end tests. Follow the steps below to test the redirect process.
Step1: Create a link for the test survey. If you are unable to create the link, please speak to a member of your Account Team. Append to the entry link the relevant session, profiling and hash parameters to test that you are passing these correctly into the Marketplace.
Test Survey per Country Language:
If you would like to test a different language that isn’t listed, please contact your Customer Success Manager for assistance.
Step2: Enter the test survey and complete the prescreener questions, any answer is permitted. For any qualifications that you are passing data in on the entry link, these will be skipped. This is a great way to check the qualification data you have appended is in the correct format.
Step3: Once the pre-screener stage is complete you’ll be presented with our test survey where you can select to simulate a Complete, Term, Quality or Overquota outcome. Based on the outcome chosen you will be returned on the corresponding redirect. We recommend testing all scenarios.
Soft-Launch
This is a guide to help plan, organize, and execute a successful soft launch of your Supply API Integration
Prior to Soft Launch
The following are steps to be taken to ensure that your integration is properly set up prior to a soft launch:
- Map and profile users on Cint Marketplace Standard Qualifications
- Receive, store, and process survey data from the Cint Marketplace
- Create links to favorable survey opportunities
- Pass in key parameters on the entry link
- Receive, store, and process qualifications and quotas data.
- Follow our guidelines to properly handle survey groups
- Follow our guidelines to target recontact surveys
- Develop an efficient matching algorithm
- Only invite respondents for which none of the respondent’s known profile data disqualifies them from the survey based on the quotas and qualifications of the survey.
- Design and implement a Yield Management system which includes:
- A proper survey ranking criteria to present the best surveys first
- Identifying poor performing surveys and stopping traffic to them
- Implement our Respondent Quality Standards requirements to deliver high-quality traffic and respondents to the Cint Marketplace
- Develop a rollback plan for any deployment of your integration
- It is important to be able to shut off the integration so that you can fix any major changes that need to be addressed without affecting your respondents’ experience.
- Test your integration
It is important to complete all the items listed above prior to a soft launch so you can prioritise optimising your processes over developing necessary functionality.
Soft Launch Requirements:
- Once development is complete and you are ready to Soft Launch, please fill out our soft launch checklist form. A member of your Account Team will validate your submission and confirm if any additional development is required before going live.
- Typically, for our large demand markets we recommend that you deploy to a segment of users that will result in 300 to 1000 survey attempts (“sessions”) per day. Work with your Integration Consultant to decide the appropriate segment size and sessions per day for the country-language pairings you will be providing sample for.
- Let the integration run for 12 hours. Confirm success/rollback with Cint team.
- In order to proceed from soft launch to full launch you will be required to achieve certain performance milestones across conversion, survey entry rate and reconciliations. During onboarding your account team will outline these thresholds, explaining how you can utilize the Supplier Portal reporting to track performance. If your integration is performing below the desired thresholds your Account Team will be on hand to provide optimisation solutions.
Full Launch
Once your integration is tracking above the required metrics you are ready to fully launch! Your Account Team will continue to work closely with you, providing tangible recommendations on how you can further optimise your Cint integration.
FAQs
Click here to access our FAQ page to find answers relating to common integration questions. If you still can’t find the answer to your question, get in touch with your account team.
Security
Our guide to setting up SHA-1 hashing is available in the Cint Supplier Portal. Supply partners can access this information in the Security Documentation section of the Cint Supplier Portal. If you do not have access to the Cint Supplier Portal please contact a member of your account team to have your login activated.
For Buy Side partners, please contact your integration consultant at integrations@cint.com for this information.
Changelog
Last 12 months of documentation updates.
09 September 2024
- Separated out legacy Supply endpoints from the suggested integration
28 August 2024
- Removed deprecated Supply Sessions and Recruit endpoints. Added Survey Inventory docs.
16 Aug 2024
On Time Supply
- Added send_interval_seconds, payload_max_size_mb, and payload_max_survey_count filter options to OTS Opportunities.
21 June 2024
Demand API Best Practices Guide
- Guide for 2024 Demand API Best Practices and workflows. Recommended for all new integrations.
19 October 2023
Fielding Assistant
- Expanded the list of supported goals and provided enhanced clarification on limitations.
26 June 2023
Audience Templates API
- Introducing Audience Templates API, including Global and Account templates. Previously, only the Global templates were available. Using Audience Templates, you can reuse your preferred set of qualifications and quotas in an easy and pragmatic way. The API allows you to import surveys as templates and save up to 10 versions of each template you own.
9 December 2022
Question Library
- The ShowUsage value in all Question endpoints will now always return 0. This does not mean that there are no surveys using the Question.
14 November 2022
Qualifications
- Users can now specify a MaxPunch option for a multi-punch question while creating or updating a SurveyQualification.
11 November 2022
Reach v2
- Optional parameter for specifying the survey collects PII.
28 September 2022
v2-Beta Questions
- Created documentation for v2-Beta Questions resource.
21 June 2022
Reach v2
- Optional parameters added to support Reach In Field.
12 May 2022
On Time Supply
- study_type property added to the Respondent model.
20 January 2022
On Time Supply
- Webhook security for On-Time Supply released to General Availability.
16 December 2021
Supply Integration Guide
- Added new sections “Matching respondents to survey data, security and testing and launch”.
15 October 2021
On Time Supply
- survey_quotas and survey_qualifications models for OTS Opportunites released to General Availability.
01 October 2021
Feasibility
- The legacy Feasibility API was removed. Users should migrate to the Reach family of APIs.
30 Sept 2021
Fielding Assistant
- Moved the Fielding Assistant API out of Beta.
23 Sept 2021
Dictionary-beta
- added an option to get all suppliers on the platform, including their id and code information in the response.
15 Sept 2021
On Time Supply
- survey_quotas and survey_qualifications models for OTS Opportunites released to “Open Beta” status.
09 Sept 2021
On Time Supply
- message_reason property added to the Opportunities model.
09 August 2021
On Time Supply
- earnings_per_click and mobile_conversion properties added to the Supply Opportunities Model.
21 July 2021
Reach
- Moved the Reach API v2 out of Beta.
1 July 2021
On Time Supply
- Recontact study type are now included in OTS responses.
Feasabilty
- FPI, previously marked for deprecation, now has an official deprecation and non-support date of October 1, 2021.