Introduction

Our suppliers can have an easy access to all our survey inventory through this API. They can expect latest list of surveys available to use with real time statistics for each survey.

Suppliers can set up qualification questions and quotas as required, to reach any specific target or population.

This is a simplified and protected system to provide ease of access and security to our partners.

Environments

For high accessibility Torfac API allows the users to integrate in different environments.

Sandbox Environment: Enables easy walkthrough of the system. Remain active while the development is being carried out. It is a testing environment with no live respondents, though test respondents can be allowed when required.

Production Environment: Go live here. We recommend thorough testing in sandbox before hitting production.

Sandbox Endpoint:

https://stagingapi.torfac.com

Production Endpoint:

https://api.torfac.com

Authentication

To connect through the API, you need a unique API key.

This API key is to be included in every call to the server in a header like below:

Authorization: sYYqoIUQJ2

P.S xxxxxxxxxxxxxxxxx will be replaced by the key you have been provided.

Lookup

GET List Country

<?php
    $curl = curl_init();

    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://<serverName>/lookup/api/countries",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_MAXREDIRS => 10,
      CURLOPT_CUSTOMREQUEST => "GET",
      CURLOPT_HTTPHEADER => array(
        "Authorization: sYYqoIUQJ2"
      ),
    ));

    $response = curl_exec($curl);
    $err = curl_error($curl);

    curl_close($curl);

    if ($err) {
      echo "cURL Error #:" . $err;
    } else {
      echo $response;
    }
 ?>

import requests
url = 'https://<serverName>/lookup/api/countries'
payload = {}
headers = {
  'Authorization': 'sYYqoIUQJ2'
}
response = requests.request('GET', url, headers = headers, data = payload)
print(response.text)

require "uri"
require "net/https"

url = URI("https://<serverName>/lookup/api/countries")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = "sYYqoIUQJ2"

response = http.request(request)
puts response.read_body

curl "https://<serverName>/lookup/api/countries"
  -H "Authorization: sYYqoIUQJ2"

The above command returns JSON structured like this:

{
    "auth": true,
    "success": true,
    "message": "Country List!",
    "data": [
        {
            "countryID": 232,
            "countryName": "United States",
            "countryCode": "US"
        }
    ]
}

This returns the list of countries for which we launch surveys.

HTTP Request

GET https://<serverName>/lookup/api/countries

GET List Standard Questions

This returns the list of all the profiling question.

<?php
    $curl = curl_init();

    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://<serverName>/lookup/api/questions/232",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_MAXREDIRS => 10,
      CURLOPT_CUSTOMREQUEST => "GET",
      CURLOPT_HTTPHEADER => array(
        "Authorization: sYYqoIUQJ2"
      ),
    ));

    $response = curl_exec($curl);
    $err = curl_error($curl);

    curl_close($curl);

    if ($err) {
      echo "cURL Error #:" . $err;
    } else {
      echo $response;
    }
 ?>

import requests
url = 'https://<serverName>/lookup/api/questions/232'
payload = {}
headers = {
  'Authorization': 'sYYqoIUQJ2'
}
response = requests.request('GET', url, headers = headers, data = payload)
print(response.text)

require "uri"
require "net/https"

url = URI("https://<serverName>/lookup/api/questions/232")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = "sYYqoIUQJ2"

response = http.request(request)
puts response.read_body

curl "https://<serverName>/lookup/api/questions/232"
  -H "Authorization: sYYqoIUQJ2"

The above command returns JSON structured like this:

{
    "auth": true,
    "success": true,
    "message": "Question List!",
    "data": [
        {
            "questionId": 1,
            "questionKey": "AGE",
            "questionText": "Please enter your date of birth.",
            "questionType": "Open End"
        },
        {
            "questionId": 2,
            "questionKey": "GENDER",
            "questionText": "What is your gender ?",
            "questionType": "Single Select"
        }
    ]
}

HTTP Request

GET https://<serverName>/lookup/api/questions/<countryid>

Query Parameters

Parameter	Required	Description
countryid	yes	Country Id (like US).

GET Question Options

This returns the list of answer options for the given question

<?php
    $curl = curl_init();

    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://<serverName>/lookup/api/answers/232/2",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_MAXREDIRS => 10,
      CURLOPT_CUSTOMREQUEST => "GET",
      CURLOPT_HTTPHEADER => array(
        "Authorization: sYYqoIUQJ2"
      ),
    ));

    $response = curl_exec($curl);
    $err = curl_error($curl);

    curl_close($curl);

    if ($err) {
      echo "cURL Error #:" . $err;
    } else {
      echo $response;
    }
 ?>

import requests
url = 'https://<serverName>/lookup/api/answers/232/2'
payload = {}
headers = {
  'Authorization': 'sYYqoIUQJ2'
}
response = requests.request('GET', url, headers = headers, data = payload)
print(response.text)

require "uri"
require "net/https"

url = URI("https://<serverName>/lookup/api/answers/232/2")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = "sYYqoIUQJ2"

response = http.request(request)
puts response.read_body

curl "https://<serverName>/lookup/api/answers/232/2"
  -H "Authorization: sYYqoIUQJ2"

The above command returns JSON structured like this:

{
    "auth": true,
    "success": true,
    "message": "Answer List!",
    "data": [
        {
            "answerId": 1,
            "answerTitle": "Male",
            "answerEngTitle": "Male"
        },
        {
            "answerId": 2,
            "answerTitle": "Female",
            "answerEngTitle": "Female"
        }
    ]
}

GET https://<serverName>/lookup/api/answers/<countryid>/<questionid>

Query Parameters

Parameter	Required	Description
countryid	true	Country Id (like US)
questionid	true	questionId of the question (Example : GENDER).

Survey

Get Allocated Surveys (all live surveys)

<?php
    $curl = curl_init();

    $url = "https://<serverName>/supply/v1/surveys/getallocatedsurveys";

    curl_setopt_array($curl, array(
      CURLOPT_URL => $url,
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_MAXREDIRS => 10,
      CURLOPT_CUSTOMREQUEST => "GET",
      CURLOPT_HTTPHEADER => array(
        "Authorization: sYYqoIUQJ2"
      ),
    ));

    $response = curl_exec($curl);
    $err = curl_error($curl);

    curl_close($curl);

    if ($err) {
      echo "cURL Error #:" . $err;
    } else {
      echo $response;
    }
 ?>

import requests
url = 'https://<serverName>/supply/v1/surveys/getallocatedsurveys'
payload = {}
headers = {
  'Authorization': 'sYYqoIUQJ2'
}
response = requests.request('GET', url, headers = headers, data = payload)
print(response.text)

require "uri"
require "net/https"

url = URI("https://<serverName>/supply/v1/surveys/getallocatedsurveys")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = "sYYqoIUQJ2"

response = http.request(request)
puts response.read_body

curl "https://<serverName>/supply/v1/surveys/getallocatedsurveys"
  -H "Authorization: sYYqoIUQJ2"

The above command returns JSON structured like this:

{
    "auth": true,
    "success": true,
    "message": "Survey List!",
    "data": {
        "0": {
            "surveyId": 9,
            "surveyName": "abc",
            "overallCompletes": 0,
            "totalRemaining": 999,
            "LOI": 10,
            "IR": 25,
            "CPI": 2,
            "countryId": 232,
            "countryName": "United States",
            "countryCode": "US",
            "deviceType": {
                "0": "desktop",
                "1": "tablet",
                "2": "mobile"
            },
            "reContact": "false",
            "entryLink": "https://<serverName>/startsurvey?survnum=
MTcwMzA1NDI=&supcode=2&pid=[%%pid%%]&token=[%%md5%%]",
            "createdDate": "2019-02-07T19:27:51Z",
            "modifiedDate": "2019-02-07T19:27:51Z"
        }
    }
}

GET https://<serverName>/supply/v1/surveys/getallocatedsurveys

Verify your request.

We verify your request by using the token variable

How to encrypt this token variable

In entry link you get
https://<serverName>/startsurvey?survnum=MTcwMzA1NDI=&supcode=2&pid=[%%pid%%]&token=[%%md5%%]

token=md5(base64decode(survnum)+supcode+pid+secretkey)

Example

survnum=base64decode(MTcwMzA1NDI=)
survnum=17030542
supcode=2
pid=12345 (We assume the panelist id is this)
secretkey=sYYqoIUQJ2

Generated token is:6a626e88f79c17becd6fa45423670dc8

Query Parameters

Parameter	Required	Description
survnum	true	Decode this into base64(eg: MTcwMzA1NDI = 17030542)
supcode	true	Supplier code shared during entry link
pid	true	Panelist Id
secret key	true	The secret key we share with you.

Get Allocated Surveys By Id

<?php
    $curl = curl_init();

    $url = "https://<serverName>/supply/v1/surveys/getallocatedsurvey/9";

    curl_setopt_array($curl, array(
      CURLOPT_URL => $url,
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_MAXREDIRS => 10,
      CURLOPT_CUSTOMREQUEST => "GET",
      CURLOPT_HTTPHEADER => array(
        "Authorization: sYYqoIUQJ2"
      ),
    ));

    $response = curl_exec($curl);
    $err = curl_error($curl);

    curl_close($curl);

    if ($err) {
      echo "cURL Error #:" . $err;
    } else {
      echo $response;
    }
 ?>

import requests
url = 'https://<serverName>/supply/v1/surveys/getallocatedsurvey/9'
payload = {}
headers = {
  'Authorization': 'sYYqoIUQJ2'
}
response = requests.request('GET', url, headers = headers, data = payload)
print(response.text)

require "uri"
require "net/https"

url = URI("https://<serverName>/supply/v1/surveys/getallocatedsurvey/9")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = "sYYqoIUQJ2"

response = http.request(request)
puts response.read_body

curl "https://<serverName>/supply/v1/surveys/getallocatedsurvey/9"
  -H "Authorization: sYYqoIUQJ2"

The above command returns JSON structured if survey is live:

{
    "auth": true,
    "success": true,
    "message": "Survey List!",
    "data": {
        "surveyId": 8,
        "surveyName": "abc",
        "OverallCompletes": 1,
        "TotalRemaining": 998,
        "LOI": 10,
        "IR": 25,
        "CPI": 3,
        "countryId": 232,
        "countryName": "United States",
        "countryCode": "US",
        "deviceType": {
                        "0": "desktop",
                        "1": "tablet"
                    },
        "reContact": "false",
        "entryLink": "https://127.0.0.1:8000/startsurvey?survnum=MTgwNTA5NTU=
&supcode=2&pid=[%%pid%%]&token=[%%md5%%]",
        "createdDate": "2019-02-05T11:16:09Z",
        "modifiedDate": "2019-06-20T17:39:34Z"

    }
}

The above command returns JSON structured if survey is paused/closed:


    {
        "auth": true,
        "success": true,
        "message": "Survey is Paused/Closed"
    }

GET https://<serverName>/supply/v1/surveys/getallocatedsurveys/<surveyId>

In this API, the supplier will get the survey status of the surveyId, if the survey is live then we will return the survey details or else will return the closed / paused message.

Quotas

GET Show Quotas

This will return the quota applied to the given survey.

<?php
    $curl = curl_init();

    $url = "https://<serverName>/supply/v1/surveys/getquotaforsurvey/9";

    curl_setopt_array($curl, array(
      CURLOPT_URL => $url,
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_MAXREDIRS => 10,
      CURLOPT_CUSTOMREQUEST => "GET",
      CURLOPT_HTTPHEADER => array(
        "Authorization: sYYqoIUQJ2"
      ),
    ));

    $response = curl_exec($curl);
    $err = curl_error($curl);

    curl_close($curl);

    if ($err) {
      echo "cURL Error #:" . $err;
    } else {
      echo $response;
    }
 ?>

import requests
url = 'https://<serverName>/supply/v1/surveys/getquotaforsurvey/9'
payload = {}
headers = {
  'Authorization': 'sYYqoIUQJ2'
}
response = requests.request('GET', url, headers = headers, data = payload)
print(response.text)

require "uri"
require "net/https"

url = URI("https://<serverName>/supply/v1/surveys/getquotaforsurvey/9")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = "sYYqoIUQJ2"

response = http.request(request)
puts response.read_body

curl "https://<serverName>/supply/v1/surveys/getquotaforsurvey/9"
  -H "Authorization: sYYqoIUQJ2"

The above command returns JSON structured like this:

{
    "auth": true,
    "success": true,
    "message": "Quota List!",
    "data": {
        "0": {
            "id": 11,
            "target": {
                "1": {
                    "0": {
                        "ageEnd": 35,
                        "ageStart": 15
                    },
                    "1": {
                        "ageEnd": 64,
                        "ageStart": 45
                    }
                },
                "2": {
                    "0": 1,
                    "1": 2
                },
                "17": {
                    "0": 8,
                    "1": 9999
                },
                "21": [
                    "12345",
                    "12349"
                ]
            }
        }
    }
}

GET https://<serverName>/supply/v1/surveys/getquotaforsurvey/<surveyId>

Query Parameters

Parameter	Required	Description
surveyId	true	Survey Id of particular survey (like US)

Redirects/Postbacks

Redirect URL

Survey success URL

This redirect URL will be used when user will complete a survey successfully.

Over quota survey URL

This redirect URL will be used when user will be marked as over quota by client OR by the system for the survey.

Terminate survey URL

This redirect URL will be used when user will be marked as terminate (for qualification mismatch OR survey closed reasons) by the system for the survey.

https://<redirecturl>?response=<responsecode>&pid=<panelistid>&token=<token>

Query Parameters

Parameter	Required	Description
redirecturl	true	supplier redirect url is required
responsecode	true	supplier response code is required ( response code for complete, terminate, over quota )
token	true	we send token so that supplier can validate this token

How Supplier Validate the token?

token_gen=responsecode+panelistid+secretkey

token=md5(responsecode+panelistid+secretkey)

Postbacks URL

This URL is fired as server to server.Both redirect and postback URLs can be used. First, Torfac system will fire postback and then redirect user to the success redirect URL.

We had 3 postback Url's

Success postback

Terminate postback

QuotaFull postback

HTTP Status Codes

The Supplier API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is not valid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The item requested is hidden for administrators only.
404	Not Found -- The specified item could not be found.