side nav
Logo

Introduction

Catalyse Research brings efficiency and automation to online sampling with Catalyse Research Marketplace, the world’s most powerful, open, and customizable online sampling platform.

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.

Environments

To make Catalyse Research’s APIs as explorable as possible, we have environments specific to your development needs. For access to these environments contact your Integration Consultant at SupplyIntegrations@catalyseresearch.com.

Users are financially responsible for all transactions made on the system regardless of whether it was the result of a bug in your integration.

Sandbox Api URL:- https://qa.supplyapi.sampleeye.com

Sandbox Swagger URL:- https://qa.supplyapi.sampleeye.com/swagger/index.html

Production Api URL:- https://supplyapi.sampleeye.com

Production Swagger URL:- https://supplyapi.sampleeye.com/swagger/index.html

Authentication

The Catalyse Research Supply API use a HTTP Authorization header for authentication. Every call should have a header Authorization: Bearer {{APIkey}}. Ensure that the key you are passing is the correct key for the environment provided by account manager from Catalyse Research . If you do not have key then contact Integration Consultant at SupplyIntegrations@catalyseresearch.com

image

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.

Sample Types

Array of all types of sample that buyers can field on the platform

Id Name
1 B2B
2 Consumer
3 Patient/Healthcare
5 Information Technology Decision Maker
6 Medical Professionals
7 Panel Recruits

Qualification Library

GET Qualification and Answer List
({EnvironmentBaseApiURL}/api/QualificationMapping/{supplierCode}/{languageCode})

Return List Of All Qualificatins And Answers.

Request Header

Name Description
Authorization Please pass Api Key here provided by catalyse research. Ex: Bearer {{APIkey}}

Request Parameters

Name Description Data Type Required
supplierCode Please pass supplier code here shared by Catalyse Research. Int True
languageCode Please pass this paramter in languageCode-CountryCode Format.For example English(US) you need to pass EN-US. string True

image

Response Parameters

Name Description Data Type
qualificationId Id of Qualification Int
qualificationName Name of Qualification Int
questionText Translated Question Text. String
answerId Id of Answer. If not avalaible then 0. Int
answerText Translated Answer Text. String

image

Surveys

GET Get Live Surveys
({EnvironmentBaseApiURL}/api/Survey/{supplierCode})

Request Header

Name Description
Authorization Please pass Api Key here provided by catalyse research. Ex: Bearer {{APIkey}}

Request Parameters

Name Description Data Type Required
supplierCode Please pass supplier code here shared by Catalyse Research. Int True
languageCode Please pass this paramter in languageCode-CountryCode Format.For example English(US) you need to pass EN-US. It is not required if you will not pass this paramter then we will expose all surveys of all country. string False

image

Response Parameters

Name Description Data Type
surveyId Id of Survey int
name Name of Survey string
ir Estimated incidence rate of the survey decimal
loi Length of Interview int
isDesktopAllowed If survey allowed on desktop bool
isMobileAllowed If survey allowed on mobile bool
isTabletAllowed If survey allowed on tablet bool
quota Total number of completes needed int
cpi Gross payout per complete decimal
languageCode Unique Id associated with two letter language code-two letter country code string
quotaType Type of quota start/complete string
liveUrl Live Link to client survey string
testUrl Test Link to client survey for testing purposes string

Entry Link Variables

Name Description
$ST Unique Supplier Respondent Session
$SU Unique Panelist ID

image

Survey Groups

GET List a Survey’s Groups
({EnvironmentBaseApiURL}/api/SurveyGroup/{supplierCode}/{surveyId})

Returns information on the survey group used by the specified survey.

Request Header

Name Description
Authorization Please pass Api Key here provided by catalyse research. Ex: Bearer {{APIkey}}

Request Parameters

Name Description Data Type Required
supplierCode Please pass supplier code here shared by Catalyse Research. Int True
surveyId Id of the selected survey. Int True

image

Response Parameters

Name Description Data Type
groupId Id of Survey Group int
name Name of Survey Group string
surveyGroupSurveys An array of all the Survey Ids related to this group int[]

image

Survey Qualifications

GET Show Survey Qualifications
({EnvironmentBaseApiURL}/api/SurveyQualifications/{supplierCode}/{surveyId})

Returns a list of all standard and exposed custom qualifications associated with a survey.

Request Header

Name Description
Authorization Please pass Api Key here provided by catalyse research. Ex: Bearer {{APIkey}}

Request Parameters

Name Description Data Type Required
supplierCode Please pass supplier code here shared by Catalyse Research. Int True
surveyId Id of the selected survey. Int True

image

Response Parameters

Name Description Data Type
qualificationId Id of Qualification int
name Name of Qualification string
qualificationAnswers Qualification answer Ids. *Note: In case of age or zip, the values given in the array are the actual ages or the zip codes. string[]

image

Survey Quotas

GET Show Survey Quotas
({EnvironmentBaseApiURL}/api/SurveyQuota/{supplierCode}/{surveyId})

Returns client quotas associated with a survey.

Request Header

Name Description
Authorization Please pass Api Key here provided by catalyse research. Ex: Bearer {{APIkey}}

Request Parameters

Name Description Data Type Required
supplierCode Please pass supplier code here shared by Catalyse Research. Int True
surveyId Id of the selected survey. Int True

image

Response Parameters

Name Description Data Type
surveyQuotaId Id of Qualification int
name Name of Qualification string
quota Quota number for the specified quota int
qualifications An array of survey qualifications associated with this quota array

image

Sample Eye Hash

Calculate Hash

Note: Your URL should include the entire URL, excluding the trailing &

URL before hashing:
Encoded hash:
Final URL:

How does this work?


Python

import hmac
import hashlib
import base64

encoded_key = key.encode('utf-8')
encoded_URL = URL.encode('utf-8')
hashed = hmac.new(encoded_key, msg=encoded_URL, digestmod=hashlib.sha1)
digested_hash = hashed.digest()
base64_encoded_result = base64.b64encode(digested_hash)
final_result = base64_encoded_result.decode('utf-8').replace('+', '-').replace('/', '_').replace('=', '')


PHP

$encoded_key = utf8_encode($key);
$encoded_URL = utf8_encode($URL);
$hashed = hash_hmac('sha1', $encoded_URL, $encoded_key);
$digested_hash = pack('H*',$hashed);
$base64_encoded_result = base64_encode($digested_hash);
$final_result = str_replace(["+","/","="],["-","_",""],utf8_decode($base64_encoded_result))


Node.js

const Crypto = require('crypto');

const hash = Crypto.createHmac('sha1', key).update(url, 'utf-8').digest('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/\=/g, '');
const final_result = encodeURIComponent(hash);


Java

import java.io.UnsupportedEncodingException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

private static String hashMe(String url, String keyString) throws
    UnsupportedEncodingException, NoSuchAlgorithmException, InvalidKeyException {
    SecretKeySpec key = new SecretKeySpec((keyString).getBytes("UTF-8"), "HmacSHA1");
    Mac mac = Mac.getInstance("HmacSHA1");
    mac.init(key);
    byte[] bytes = mac.doFinal(url.getBytes("UTF-8"));
    byte[] encodedBytes = Base64.getEncoder().encode(bytes);
    String finalResult = new String(encodedBytes);
    return finalResult.replace("+", "-").replace("/", "_").replace("=", "");
}