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

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.

Demand Integration FAQs

Supply Integration FAQs

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

Feed - 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 Feed (formerly known as 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 Feed 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/

Feed - Opportunities

Feed (formerly On-time Supply) Opportunities allows you to subscribe to receive data on Cint survey opportunities that match your subscription criteria. You will receive messages about new survey opportunities, along with updates to existing surveys in your feed, to your specified callback.

In addition to upgraded workflows, you will see Cint’s modern paths and parameters styling. Feed Opportunities 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.

Important Information

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. Please refer to the Recontact section in Getting Survey Data for more detailed guidance on how to target and manage 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.
Survey Group management through Opportunities: Survey group deduplication can be managed using the survey_group_ids property in the Opportunities Model. Refer to the Survey Group section in Getting Survey Data to understand the importance of survey group deduplication and how to implement it.

The Feed Opportunities collection can be easily imported into Postman by clicking the button below:

Access our Feed Opportunities and Respondent Outcomes FAQ article to find answers related to these products.

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.
buyer_id	int	The Unique ID of the buyer.
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 Cint Exchange (formerly 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.
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.
revenue_per_interview	Monetary Amount	Payout per complete.
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 Cint Exchange (formerly 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.
revenue_per_click	float	The Revenue Per Click value of the survey. RPC = (RPI * 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 Opportunities subscription. See Support Article for additional information.
px_buyer_message	array of strings	An array of tags from the buyer to the supplier.

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.
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"},
    "revenue_per_interview": {"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"},
    revenue_per_interview: {"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"},
  "revenue_per_interview": {"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'},
  'revenue_per_interview': {'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""},
    ""revenue_per_interview"": {""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" },
          revenue_per_interview: { 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",
      "buyer_id": 12345,
      "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,
      "revenue_per_interview": {
        "value": 1.35,
        "currency_code": "USD"
      },
      "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",
      "px_buyer_message": [
        "some-example-text",
        "another-tag"
      ],
      "survey_quotas": [
        {
          "survey_quota_id": 80544313,
          "survey_quota_type": "Total",
          "conversion": 0.39166668,
          "number_of_respondents": 46,
          "questions": null
        },
        {
          "survey_quota_id": 80544314,
          "survey_quota_type": "Client",
          "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",
          "conversion": 0.39166668,
          "number_of_respondents": 2,
          "questions": [
            {
              "precodes": [
                "2"
              ],
              "logical_operator": "OR",
              "question_id": 43
            }
          ]
          },
        {
          "survey_quota_id": 80544316,
          "survey_quota_type": "Client",
          "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 Opportunities 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 Cint Exchange (formerly 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.	-
revenue_per_interview	#CompareFloat	false	Revenue 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
revenue_per_click	#CompareFloat	false	The Revenue Per Click value of the survey. RPC = (RPI * completes) / system entrants	0.0<=
length_of_interview	#CompareInt	false	Median time for a respondent to complete the survey, excluding the Cint Exchange (formerly Marketplace) prescreener, in minutes.	0<=
termination_length_of_interview	#CompareInt	false	Median time for a respondent to be termed, in minutes.	0<=
buyer_id	#CompareInt	false	The Unique ID of the buyer
px_buyer_message	#CompareStrArray	false	(Coming soon!) An array of tags from the buyer to the supplier. Any tags need to match.

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]

CompareStrArray

Object	Description
in	[“string”, “string”]
nin	[“string”, “string”]

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": [
          {
              "revenue_per_interview": {
                  "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 Opportunities 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.	-

Feed - Respondent Outcomes

The Outcomes resource contains information about a respondent’s session as they move through the Cint Exchange (formerly known as 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 Cint Exchange (Marketplace) and Client response statuses can be found on the Cint Support Site: Cint Exchange (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. This value will be blank if a respondent terminates on a marketplace_status of 236 or 237.
session_id	string	Secondary panelist ID. Also known as MID. This value will be blank if a respondent terminates on a marketplace_status of 236 or 237.
marketplace_status	int	Response code associated with the respondent’s Cint Exchange (Marketplace) session.
client_status	int	Response code associated with the respondent’s client survey attempt.
entry_date	datetime	Date and time the respondent entered the Cint Exchange.
last_date	datetime	Date and time the respondent last interacted with the session.
survey_id	int	Unique number associated with the survey.
rpi	Monetary Amount	Revenue 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,
        "rpi": {
          "value": 1.25
          "currency_code": "USD"
        },
        "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 Cint Exchange (Marketplace) session.	Cint Exchange (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}"
  }

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.

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 Exchange (formerly Marketplace).
TrackingTypeCode	string	Defines how Cint 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.
TestLink	string	Test supplier-specific respondent entry link generated by Cint.
RPI Monetary Amount	Payout per complete.

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=cint&fs=1&uid=[%MID%]",
    "SuccessLink": "https:\/\/www.anon.com\/surveys?v=cint&fs=2&uid=[%MID%]&COST=[%COST%]",
    "FailureLink": "https:\/\/www.anon.com\/surveys?v=cint&fs=1&uid=[%MID%]",
    "OverQuotaLink": "https:\/\/www.anon.com\/surveys?v=cint&fs=1&uid=[%MID%]",
    "QualityTerminationLink": "https:\/\/www.anon.com\/surveys?v=cint&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",
    "RPI": {
        "Value": 1.35,
        "CurrencyCode": "USD"
    }
  }
}

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 Exchange (formerly Marketplace).
TrackingTypeCode	string	true	Defines how Cint 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",
    "RPI": {
        "Value": 1.35,
        "CurrencyCode": "USD"
    }
  }
}

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 Exchange (formerly Marketplace).
TrackingTypeCode	string	true	Defines how Cint 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",
    "RPI": {
        "Value": 1.35,
        "CurrencyCode": "USD"
    }
  }
}

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.

RPI

To help Suppliers better understand their expected payouts and allow for future support of additional currencies, RPI is conceptually replacing CPI as the canonical financial payout value for Supplier integrations. RPI as a value already takes into account your fees and commissions as well as how Suppliers are allocated into the Survey to provide more accurate financial data up front. This feature is currently in beta.

Monetary Amount Format

RPI uses a new format for currency that includes the currency code and allows for greater precision (up to 9 places). This allows for future expansion to support other currency models with much finer precision than was provided by CPI.

Property	Type	Description
value	float	The net payment for a complete
currency_code	string	The currency type that is being payed out by this survey in ISO 4217 format. Currently always `USD`.

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 - 100000)	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-100000)	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, or array[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, or auto (which indicates the property was auto-generated). Any property that is null by default can be created as null, set as null, or returned as null.
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_type is one of bool, int, float, string, object, or array[data_type].
description is an explanation of the property.
limits define the range of acceptable values for this property.
default is the default value of the property. Default options could be an account-level setting, our standard defaults, or auto (which indicates the property was auto-generated). Any property that is null by default can be created as null, set as null, or returned as null.
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.

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.
RPI	Monetary Amount	Revenue 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&RPIGTE=2&RPILTE=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&RPIGTE=2&RPILTE=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&RPIGTE=2&RPILTE=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&RPIGTE=2&RPILTE=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&RPIGTE=2&RPILTE=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&RPIGTE=2&RPILTE=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,
      "RPI": {
        "Value": 1.35,
        "CurrencyCode": "USD"
      },
      "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
RPIGTE	float	false	Minimum gross payout per complete.	0<=
RPILTE	float	false	Maximum gross payout per complete.	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,
      "RPI": {
        "Value": 1.35,
        "CurrencyCode": "USD"
      },
      "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,
      "RPI": {
        "Value": 1.35,
        "CurrencyCode": "USD"
      },
      "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.
RPI Monetary Amount	Payout per targeted complete.

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",
          "RPI": {
            "value": 1.35,
            "currency_code": "USD"
          }
        }
      }
    ],
    "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.
RPI	Monetary Amount	Payout per complete.
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",
      "RPI": {
        "Value": 1.35,
        "CurrencyCode": "USD"
      },
      "Conversion": 0,
      "NumberOfRespondents": 20,
      "Questions": []
    },
    {
      "SurveyQuotaID": 1781601,
      "SurveyQuotaType": "Client",
      "RPI": {
        "Value": 1.35,
        "CurrencyCode": "USD"
      },
      "Conversion": 0,
      "NumberOfRespondents": 10,
      "Questions": [
        {
          "QuestionID": 43,
          "LogicalOperator": "OR",
          "PreCodes": [
            "1"
          ]
        }
      ]
    },
    {
      "SurveyQuotaID": 1781602,
      "SurveyQuotaType": "Client",
      "RPI": {
        "Value": 1.35,
        "CurrencyCode": "USD"
      },
      "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 revenue studies receive the most traffic and low revenue studies are removed from sample send.

Global Trailing Model

Property	Type	Description
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
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": {
    "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.

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:

Complete
Terminate
Quality Terminate
Overquota

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 as PO-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 either prescreens or completes
quantity_calc_type - Used to set survey quantity denomination as either prescreens or completes.
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 the live_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 to false unless 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_profile
fraud_profile_threshold
relevant_id
unique_ip
unique_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 FieldTarget fields represent completes and Fielding Assistant manages the actual quota in prescreens to reach the target set in the FieldTarget.
Even Pacing - Paces completes over a fielding period using FieldTarget as completes.
Balanced CPI Model - Does not control completes. This goal optimizes CPI within your budget to deliver all requested completes by the completion_timestamp deadline. Calculate the total_budget field 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 FieldTarget parameter if using Fielding Assistant or the Quota parameter 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 id field 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 complete status. If it is not, update the status to complete.
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 the total_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.

Timeline

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:

AGE
GENDER
ZIP
HISPANIC
ETHNICITY
STANDARD_HHI
STANDARD_EDUCATION_V2
STANDARD_EMPLOYMENT
STANDARD_INDUSTRY_PERSONAL
STANDARD_JOB_TITLE
Parental_Status_Standard
Age_and_Gender_of_Child
STANDARD_NO_OF_EMPLOYEES
STANDARD_INDUSTRY
STANDARD_WEBCAM
STANDARD_COMPANY_REVENUE
STANDARD_B2B_DECISION_MAKER
STANDARD_COMPANY_DEPARTMENT
STANDARD_HISPANIC_ACCULTURATION
STANDARD_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 QuotaCPI represents the amount to be paid per complete. The QuotaCPI should not include Marketplace commissions and fees, and/or your desired margins.
IsActive: This parameter controls the availability of the Marketplace Survey within our database. This should be hardcoded to true and should not be changed at any time. If you need to “delete” a Survey use the SurveyStatusCodes.
Survey Level Security: We recommend hardcoding the following Survey Level Securities. Definitions for each parameter can be found here.
- verify_callback: false
- unique_pid: true
- unique_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 ClientSurveyLiveURL or v2-beta parameter live_url, URLs for Surveys must conform to the pattern https://mysurveydomain.com/valid_path?valid_query_string=true where 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
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: 01 which 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 using SurveyStatusCode: 03 The 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: 0
- FulcrumExchangeHedgeAccess: 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 integration gives you and your respondents instant access to thousands of Cint Marketplace opportunities globally. Our suite of Supply APIs gives you the ability to receive 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 Exchange (formerly 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 Exchange. In this step, we recommend mapping to country ID, country languages, industries, sample types, and study type data.

2. Store 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

To launch your integration with Cint, you must ensure that your respondents are profiled on all Critical Qualifications for each market you have users in. To maximize survey opportunities, we strongly recommend incorporating Primary Qualifications during the initial development phases.

You can download the Supplier Qualification Tier file here. For more information on Standard Qualifications, profiling best practices, and other resources, please refer to our profiling guide.

3. Understanding Survey Qualifications

Example 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 Redirect 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%]

Survey qualifications are used to define who the buyers wants to get responses from in their survey. These qualifications are presented to respondents in the prescreener before they leave the Cint Exchange and enter the client survey.

Important Details:

There are two types of survey qualifications: standard and custom. Standard qualifications consist of a predefined list of industry-standard questions. Custom qualifications are typically created by the buyer when their specific question needs are not met by the standard qualification library.
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.
Survey qualification data is returned in the survey_qualifications model of Feed Opportunities. To receive this information, ensure the argument “include_quota” is set to “true” in the body of the Opportunities POST request.
You should pass respondent demographics on the entry link allowing the respondent to bypass pre screener questions.
Respondents will also bypass questions they have already answered in the Cint Exchange. You can capture this data by including demographic variables in your supplier redirects.
- Cint 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 Survey Quotas

Quotas determine how many completes of each type of respondent are allowed into the survey. Quotas are always created off survey qualifications.

Survey 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 Feed Opportunities set filter "include_quota":true in the body of the POST request
Quotas are distinguished by survey_quota_id property.
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. When you opt in to receive qualification data through your Feed Opportunities subscription, you’ll receive a list of all question IDs for a given study—both standard and custom (if exposed).

The List Standard Questions call only returns standard qualification data. Therefore, if a question ID returned via the Feed 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)
Opportunities Subscription	Pushed to your callback every 15 seconds*
Create a Link	Once
Show a Link	Optional
Update a Link	Never, unless updating your redirect links
Respondent Outcomes Subscription	Pushed to your callback with each respondent session update

*You can adjust the frequency of survey data delivery, along with the number of surveys per message, and the message size. Please refer to the argument section of Feed Opportunities on how to apply these filters.

2. Opportunities Subscription

Opportunities subscribes you to receive messages containing live studies currently available to you on the Cint Exchange. 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).

For answers to common questions about Opportunities, please refer to our Cint Exchange Feed Opportunities and Respondent Outcomes FAQs.

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 Groups

Cint Exchange buyers organize surveys into survey groups to prevent duplication across multiple surveys. Buyers can add or remove surveys from these groups as their deduplication needs evolve. If a respondent has already attempted one survey in a group, avoid sending them to other surveys within that same group. The Opportunities model message includes the property survey_group_ids, which can be used to identify if a survey belongs to a survey group.

How to handle survey group data:

Observe the Opportunities model message.
Check the survey_group_ids property:
- If the array is empty, the survey is not part of a survey group, and no further action is needed.
- If a value is present, it indicates the survey belongs to a survey group.
Store the survey_group_ids:
- The value(s) in the survey_group_ids array represent the parent survey group ID.
- Store this ID and associate it with the relevant surveys.
- As you receive future survey updates, remove or deactivate surveys no longer linked to that survey group ID.
Avoid duplicate survey participation:
- Do not send a respondent to more than one survey within the same survey group.
- If a survey is removed from the group, you may start sending respondents who previously completed that survey to other surveys still in the group.

5. Recontacts

Buyers often want to recontact respondents that have completed their surveys in order to ask follow-up questions. What makes these studies unique is that buyers upload a list of PIDs (Participant IDs) to a survey to communicate to Suppliers which respondents qualify for the opportunity. Any respondents sent in by a Supplier which are not on the defined PID list, will be immediately terminated.

How to target recontact surveys:

Feed Opportunities subscription configuration:
- To receive recontact surveys include study_type: recontact in your filter, or omit the study_type filter entirely.
Capturing Qualified Respondents:
- Monitor the Opportunities model message, if for a given survey_id the respondents_pids property contains a value, call the List Qualified Respondents for that survey ID to collect the PID data from the SurveyQualifiedRespondents model.
- Note: although the respondents_pids property in the Opportunities model does return a list of PIDs, this has a limit for the number of IDs it can return. To ensure you capture all PIDs, please use the List Qualified Respondents endpoint as described above.
Survey Targeting:
- Only send respondent PIDs included in List Qualified Respondents model to the appropriate survey
- If the respondents_pids array in the Opportunities model is empty, no respondents qualify for that study.

Creating an Entry Link and Setting Redirects

Once you have identified a survey opportunity, create the entry link. This call will return both “live” and “test” links. The live link is where you should send your respondents and the test link can be used for internal User Acceptance Testing during the testing phase.

When creating a link you can specify custom redirects to be applied to that survey. If no custom redirects are included in the payload, your default supplier redirects will be applied. Session and profiling data collected in the Cint Exchange can be passed back to you via the redirect links. Refer to 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 Exchange we require you to append session, identity, demographic and hash parameters to the entry link. Please review our generating API entry links article to understand the necessary data and formatting. Note: entry links have a character limit of 1999. Exceeding this limit will trigger an error, preventing respondents from entering the Cint Exchange and stopping us from returning the user to your platform.

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.

Decision Chart

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 Feed Opportunities properties is_live value false or message_reason value deactivated?
- 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.

Decision Chart

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 Exchange, they will be immediately terminated on a 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 primary goals are to ensure that sample is sent only to live surveys and that respondents are directed to surveys with relevant open quotas.

1. Opportunities Subscription

Opportunities return new surveys and updates to all surveys where the supplier has an allocation and meets the criteria specified in your subscription. Your survey update processes should be based on the results of this call.

When the message_reason equals “updated”: Replace the existing survey data with the new data provided in the message.
Pause live surveys: If the is_live property is false (indicating the buyer has paused or closed the survey) or if the message_reason is deactivated (survey no longer meets your subscription criteria), pause any corresponding surveys in your system.
Set paused surveys live: If the message shows is_live is true or the message_reason is reactivated, resume any paused surveys in your system.

2. Qualifications and Quotas

Overwrite stored qualification and quota data for each survey.

3. Survey Groups

Capture any new survey numbers associated to the survey_group_ids 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

As a Cint Supply Partner, ensuring the quality of the traffic you send to Cint is essential. If your reconciliation rates exceed the thresholds outlined in our Partner Improvement Program, your traffic may be paused in affected countries. Before launching an integration, suppliers must implement all measures detailed in the Respondent Quality Standards article. This article, along with additional resources on Cint’s quality measures and strategies for mitigating poor-quality users and fraudulent activity, is available in the Security Documentation section of the Cint Supplier Portal. Access to the portal is granted during onboarding.

Reconciliations

Cint’s policy permits respondents to be reconciled from a complete to a termination (negative reconciliation) and from a termination back to a complete (positive reconciliation). Closely monitoring this data is essential for ensuring high-quality traffic and maintaining a low reconciliation rate. To track reconciliation data effectively, we recommend subscribing to Feed Respondent Outcomes to receive notifications when a respondent is positively or negatively reconciled in the marketplace. Receiving this data in near real-time enables you to regulate respondent survey access automatically and mitigate fraudulent activity.

For detailed information on how to collect, minimizing, and manage reconciliation data, please view our Reconciliation Tracking article in the Supplier Portal.

Collecting Session Data

This section explains what options are available to track session outcomes and the benefits of this.

1. Tracking session outcomes

For each respondent moving through our platform, we store both a Cint Exchange (Marketplace) Response Code, identicating the outcome in the prescreener, and a Client Response Code, indicating the outcome within the client survey.

We recommend storing these response codes in your database to track respondent session activity in real-time. Doing so offers several advantages, including:

Providing detailed insights into integration performance, highlighting areas where optimizations are needed, such as reducing Cint Exchange Terminations.g Cint Exchange Terminations FAQs
Supporting Yield Management decisions by adjusting user flows to surveys based on in-field performance metrics.
Regulating respondent survey access based upon security failures, most notably;
- Link Manipulation Terminations
- Cint Survey Protection Services Terminations

Below are the available options to capture session outcome data.

a. Redirects

To collect Cint Exchange and Client response codes for each respondent session, ensure the following parameters are appended to all your redirects. For more details on parameters and formatting options, refer to our Collecting Data From Redirects article.

InitialStatus=[%InitialStatus%]&ClientStatus=[%ClientStatus%]

b. Feed Respondent Outcomes

Create an outcomes subscription to receive near real-time notifications on respondent sessions. You will receive updates on new session outcomes or changes to a respondent’s response code. We recommend subscribing to all available response codes, but you can filter specific outcomes based on your preferences. For more examples and guidance, refer to our Feed Opportunities and Respondent Outcomes FAQs for some example subscriptions.

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 Cint Exchange 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, identity, profiling and hash parameters to test that you are passing these correctly into the Cint Exchange.

Test Survey per Country Language:

Test Surveys

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 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’s Standard Qualifications
- Critical qualifications.
Receive and store survey data from the Cint Exchange
- Create a subscription to Feed Opportunities, including qualification and quota data.
- Create links to favorable survey opportunities
Pass in key parameters on the entry link
- Append the “required” parameters outlined the Generating API Entry Links article.
Manage survey updates from your Feed Opportunities subscription
- Overide stored data with new information
- Close down inactive or deactivated surveys
Follow our guidelines to properly handle survey groups
- Survey Groups, section4
Follow our guidelines to target recontact surveys
- Recontact, section5
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
Capture session outcome data via redirects and/or Respondent Outcomes
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’re ready for the Soft Launch, please complete our soft launch checklist form in the Cint Supplier Portal. A member of your Account Team will review your submission and confirm if any additional development is needed before going live.
For large demand markets, we typically recommend deploying to a user segment that generates 300 to 1,000 survey attempts (sessions) per day. Work with your Integration Consultant to determine the appropriate segment size and session volume for each country-language pairing you’re providing samples for.
Let the integration run for 12 hours. Afterward, confirm success or initiate rollback with the Cint team.
To proceed from soft launch to full launch, you will need to meet specific performance milestones, including targets for conversion, survey entry rate, and reconciliations. Your Account Team will outline these thresholds during onboarding and explain how to use the Supplier Portal reporting to track performance. If your integration falls below the desired thresholds, your Account Team will provide optimization solutions.

Full Launch

Once your integration meets the required performance metrics, you are ready to fully launch your first market. If you have users in multiple countries, your Account Team will provide a suitable schedule for releasing each country. They will also continue to work closely with you, offering actionable recommendations on how to further optimize your Cint integration.

FAQs and additional resources

The following links provide additional resources and FAQs that you can use to enhance your Supply Integration.

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.

13 May 2025

Added buyer_id filter option to OTS Opportunities.

18 February 2025

Added buyer_id field to OTS Opportunities. This buyer_id is the same as the Demand side buyer ID.

18 December 2024

Added documentation for the RPI beta

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.

Introduction

Environments

Authentication

Request Format

Running in Postman

HTTP Status Codes

FAQs

Lookup

Definitions

GET List Global Definitions

Arguments

Options

GET List Suppliers

GET List Business Units

Question Library

GET List Standard Questions

Arguments

GET List Custom Questions

Arguments

GET Show Question Text

Arguments

GET Show Question Options

Arguments

Beta - Lookup

Dictionary (beta)

Dictionaries model

Errors (beta)

Errors model

GET List of Possible Errors (beta)

Possible Errors Model

Possible Errors

a01

Server Errors

s01

s02

s03, s04, s05, s07

s06

Validation Errors

v01

v02

v03

v04

v05

v06

v07

v08

v09

v10

v11

v12

v13

v14

v15

v16

v19

Supply Integration

Feed - Webhook Security

Request Signatures

Signature Verification

Step 1: Extract the timestamp and signatures from the header

Step 2: Construct the Message Digest for the request

Step 3: Verify the included signature

Further Reading

Feed - Opportunities

Important Information

Opportunities Model

survey_quotas model

survey_qualifications model

questions model

POST Create Opportunities Subscription

Arguments

Compare Objects

CompareStr

CompareInt, CompareFloat

CompareBool

CompareIntArray

CompareStrArray

DELETE Remove an Opportunity Subscription

GET Show an Opportunity Subscription

Arguments