NAV Navbar
Logo
curl PHP Node.js

Supplier API

Innovate Supplier APIs provide a simple and quick way to pull down survey inventory available to supplier and match with user’s profile. With this, supplier will be able to get updated list of survey inventory, real time statistics for each survey and targeting questions to match with user’s profile.

Running in Postman

Postman Image

The entire Innovate API collection can be easily imported into Postman, by clicking the button below:

Run in Postman

Postman is a free application that allows you to execute test calls in an intuitive interface. When making test calls, you should use the development environment.

Environments

Sandbox Endpoint

http://innovate-stage-209385288.us-east-1.elb.amazonaws.com/api/v1

Production Endpoint

https://supplier.innovatemr.net/api/v1/

Innovate has two environments—production and sandbox. The sandbox environment is used during development and for testing. There are no live respondents in this environment (although you may enter as a respondent). It is important to note that lookup libraries in the sandbox are different from those in production. Production should only be used once an application has been thoroughly tested in sandbox.

Lookup Question Library

Definition

GET http://<serverName>/api/v1/supply/getQuestionsByCategory/<CountryKey>/<language>

Example Request

curl -X GET -H "Content-Type: application/json" 
"x-access-token: YOUR_X-ACCESS-TOKEN_HERE"
"https://supplier.innovatemr.net/api/v1/supply/getQuestionsByCategory/US/ARABIC"
<?php
  $URL = "supplier.innovatemr.net/api/v1/supply/";

  $aHTTP['http']['method']  = 'GET';

  $aHTTP['http']['header']  = "x-access-token: YOUR_X-ACCESS-TOKEN_HERE";

  $context = stream_context_create($aHTTP);

  $response = file_get_contents($URL, false, $context);
?>
var options = {
  "method": "GET",
  "hostname": "supplier.innovatemr.net",
  "path": "/api/v1/supply/getQuestionsByCategory/US",
  "headers": {
    "content-type": "application/json",
    "x-access-token": "YOUR_X-ACCESS-TOKEN_HERE",
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Example Response

{  
   "apiStatus":"success",
   "msg":"questions are successfully searched",
   "result":[  
      {
        "QuestionId": 801,
        "QuestionText": "ma hi easimat alhind?",
        "QuestionKey": "TESTING_A_8012",
        "QuestionType": "Single Punch",
        "language": "ARABIC",
        "Category": [
          "Testing_A"
        ]
      },
      {
        "QuestionId": 804,
        "QuestionText": "'ayn taeish?",
        "QuestionKey": "TESTING_AB_804",
        "QuestionType": "Single Punch",
        "language": "ARABIC",
        "Category": [
          "Testing_A",
          "TESTING_KASH"
        ]
      }
   ]
}

This API will allow supplier to pull down list of all questions associated with the specified country and language( i.e. country and language passed in request). These questions are used as survey criteria and will be helpful to match user’s profile with survey criteria.

Query Parameters

Property Type Required Description
Country Key String Yes Country Key (like US)
Language String No (Default will be ENGLISH) Language (like ENGLISH)

Answer Lookup

Definition

GET http://<serverName>/api/v1/supply/getAnswersByQuesKey/<QuestionKey>?country=<country name>&language=<language name>

Example Request

curl -X GET -H "Content-Type: application/json" 
"x-access-token: YOUR_X-ACCESS-TOKEN_HERE"
"https://supplier.innovatemr.net/api/v1/supply/getAnswersByQuesKey/GENDER"
<?php
  $URL = "https://supplier.innovatemr.net/api/v1/supply/getAnswersByQuesKey/GENDER";

  $aHTTP['http']['method']  = 'GET';

  $aHTTP['http']['header']  = "x-access-token: YOUR_X-ACCESS-TOKEN_HERE";

  $context = stream_context_create($aHTTP);

  $response = file_get_contents($URL, false, $context);
?>
var options = {
  "method": "GET",
  "hostname": "supplier.innovatemr.net",
  "path": "/api/v1/supply/getAnswersByQuesKey/GENDER",
  "headers": {
    "content-type": "application/json",
    "x-access-token": "YOUR_X-ACCESS-TOKEN_HERE",
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Example Response

{
  "apiStatus": "success",
  "msg": "Answers are successfully searched",
  "result": {
    "QuestionId": 2,
    "QuestionText": "What is your gender?",
    "QuestionType": "Single Punch",
    "QuestionOptions": [
      {
        "OptionText": "Male",
        "id": 1
      },
      {
        "OptionText": "Female",
        "id": 2
      }
    ]
  }
}


API returns a list of all Answer options for the Question associated with the specified QuestionKey,country and language.

Query Parameters

Property Type Required Description
Question Key String Yes QuestionKey of the question (Example : GENDER)
Country String No (Default will be US) Country Key (like US)
Language String No (Default will be ENGLISH) Language (like ENGLISH)

Get Allocated Surveys (all live surveys)

Definition

GET http://<serverName>/api/v1/supply/getAllocatedSurveys

Example Request

curl -X GET -H "Content-Type: application/json" 
"x-access-token: YOUR_X-ACCESS-TOKEN_HERE"
"https://supplier.innovatemr.net/api/v1/supply/getAllocatedSurveys"
<?php
  $URL = "https://supplier.innovatemr.net/api/v1/supply/getAllocatedSurveys";

  $aHTTP['http']['method']  = 'GET';

  $aHTTP['http']['header']  = "x-access-token: YOUR_X-ACCESS-TOKEN_HERE";

  $context = stream_context_create($aHTTP);

  $response = file_get_contents($URL, false, $context);
?>
var options = {
  "method": "GET",
  "hostname": "supplier.innovatemr.net",
  "path": "/api/v1/supply/getAllocatedSurveys",
  "headers": {
    "content-type": "application/json",
    "x-access-token": "YOUR_X-ACCESS-TOKEN_HERE",
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Example Response

{
  "apiStatus": "success",
  "msg": " All live groups are successfully searched",
  "result": [
    {
      "surveyId": 12632,
      "surveyName": "Basic Demo With Beverage survey",
      "N": 100,
      "isRevShr": true,
      "supCmps": 3,
      "remainingN": 97,
      "LOI": 15,
      "IR": 10,
      "Country": "United States",
      "Language": "ENGLISH",
      "groupType": "Consumer",
      "deviceType": "All",
      "createdDate": "09/11/2017, 11:03:50 pm PST",
      "modifiedDate": "09/11/2017, 11:50:27 pm PST",
      "reContact": false,
      "entryLink": "http://innovate-stage-209385288.us-east-1.elb.amazonaws.com/startSurvey?survNum=86NMz1YX&supCode=225&PID=[%%pid%%]",
      "testEntryLink": "",
      "targeting": [
        {
          "QuestionId": 11,
          "QuestionKey": "ZIPCODES",
          "QuestionText": "What is your zipcode?",
          "QuestionType": "Numeric Open Ended",
          "QuestionCategory":"Demographic",
          "Options": [
            {
              "OptionId": 1,
              "OptionText": "800235"
            }
          ]
        },
       {
          "QuestionId": 1,
          "QuestionKey":"AGE",
          "QuestionText":"What is your age?",
          "QuestionType":"Numeric Open Ended",
          "QuestionCategory":"Demographic",
           "Options":[
              {
                 "OptionId":1,
                 "ageStart":15,
                 "ageEnd":30
              }
           ]
         },
          {
             "QuestionId": 2,
             "QuestionKey":"GENDER",
             "QuestionText":"What is your gender?",
             "QuestionType":"Single Punch",
             "QuestionCategory":"Demographic",
             "Options":[
                {
                   "OptionId":1,
                   "OptionText":"Male"
                },
                {
                   "OptionId":2,
                   "OptionText":"Female"
                }
             ]
          }
      ],
      "CPI": "4.50",
      "isQuota": true,
      "jobCategory": "Beauty/Cosmetics",
      "isPIIRequired": false,
      "JobId": 9175,
      "expected_end_date": "09/21/2018"

    },
    {
      "surveyId": 12631,
      "surveyName": "Basic Demo With Miscellaneous",
      "N": 100,
      "isRevShr": true,
      "supCmps": 0,
      "remainingN": 100,
      "LOI": 15,
      "IR": 10,
      "Country": "United States",
      "Language": "ENGLISH",
      "groupType": "Consumer",
      "deviceType": "All",
      "createdDate": "09/11/2017, 11:03:50 pm PST",
      "modifiedDate": "10/09/2017, 9:26:27 am PST",
      "reContact": false,
      "entryLink": "http://innovate-stage-209385288.us-east-1.elb.amazonaws.com/startSurvey?survNum=M6wXK8P8&supCode=225&PID=[%%pid%%]",
      "testEntryLink": "",
      "targeting": [],
      "CPI": "0.30",
      "isQuota": false,
      "jobCategory": "Beauty/Cosmetics"
    }
  ]
}

This API will allow supplier to pull down survey inventory associated with supplier’s account at Innovate. Survey list will be of only LIVE surveys.

Get Allocated Surveys By Date (live surveys only)

Definition

GET http://<serverName>/api/v1/supply/getAllocatedSurveysByDate/<Datetime>

Example Request

curl -X GET -H "Content-Type: application/json" 
"x-access-token: YOUR_X-ACCESS-TOKEN_HERE"
"https://supplier.innovatemr.net/api/v1/supply/getAllocatedSurveysByDate/2017-10-01T13:35:11.364Z"
<?php
  $URL = "https://supplier.innovatemr.net/api/v1/supply/getAllocatedSurveysByDate/2017-10-01T13:35:11.364Z";

  $aHTTP['http']['method']  = 'GET';

  $aHTTP['http']['header']  = "x-access-token: YOUR_X-ACCESS-TOKEN_HERE";

  $context = stream_context_create($aHTTP);

  $response = file_get_contents($URL, false, $context);
?>
var options = {
  "method": "GET",
  "hostname": "supplier.innovatemr.net",
  "path": "/api/v1/supply/getAllocatedSurveysByDate/2017-10-01T13:35:11.364Z",
  "headers": {
    "content-type": "application/json",
    "x-access-token": "YOUR_X-ACCESS-TOKEN_HERE",
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Example Response

{
  "apiStatus": "success",
  "msg": " All live groups are successfully searched",
  "result": [
    {
      "surveyId": 14345,
      "surveyName": "Basic Demo With Beverage survey",
      "N": 10,
      "isRevShr": true,
      "supCmps": 0,
      "remainingN": 10,
      "LOI": 3,
      "IR": 100,
      "Country": "United States",
      "Language": "ENGLISH",
      "groupType": "B2B",
      "deviceType": "All",
      "createdDate": "11/07/2017, 12:46:10 am PST",
      "modifiedDate": "11/07/2017, 12:58:06 am PST",
      "reContact": false,
      "entryLink": "http://innovate-stage-209385288.us-east-1.elb.amazonaws.com/startSurvey?survNum=36mnkXPb&supCode=225&PID=[%%pid%%]",
      "testEntryLink": "",
      "CPI": "1.13",
      "jobCategory": "Education",
      "targeting": [
        {
          "QuestionId": 11,
          "QuestionKey": "ZIPCODES",
          "QuestionText": "What is your zipcode?",
          "QuestionType": "Numeric Open Ended",
          "QuestionCategory": "Geographic",
          "Options": [
            {
              "OptionId": 1,
              "OptionText": "800235"
            }
          ]
        }
      ],
      "isQuota": false,
      "isPIIRequired": false,
      "JobId": 9175,
      "expected_end_date": "09/21/2018"
    },
    {
      "surveyId": 14343,
      "surveyName": "Basic Demo With Miscellaneous",
      "N": 10,
      "isRevShr": true,
      "supCmps": 0,
      "remainingN": 10,
      "LOI": 3,
      "IR": 100,
      "Country": "United States",
      "Language": "ENGLISH",
      "groupType": "B2B",
      "deviceType": "All",
      "createdDate": "11/07/2017, 12:40:34 am PST",
      "modifiedDate": "11/07/2017, 12:45:30 am PST",
      "reContact": false,
      "entryLink": "http://innovate-stage-209385288.us-east-1.elb.amazonaws.com/startSurvey?survNum=1YjMLWvq&supCode=225&PID=[%%pid%%]",
      "testEntryLink": "",
      "CPI": "0.60",
      "jobCategory": "Education",
      "targeting": [],
      "isQuota": false
    }
  ]
}

API returns a list of all LIVE surveys allocated to supplier’s account updated or created after certain datetime.

Query Parameters

Property Type Required Description
Date Time String Yes Date and time of the live surveys (Example : 2017-10-01T13:35:11.364Z)

Get Quota for Survey

Definition

GET http://<serverName>/api/v1/supply/getQuotaForSurvey/<surveyId>

Example Request

curl -X GET -H "Content-Type: application/json" 
"x-access-token: YOUR_X-ACCESS-TOKEN_HERE"
"https://supplier.innovatemr.net/api/v1/supply/getQuotaForSurvey/12634"
<?php
  $URL = "https://supplier.innovatemr.net/api/v1/supply/getQuotaForSurvey/12634";

  $aHTTP['http']['method']  = 'GET';

  $aHTTP['http']['header']  = "x-access-token: YOUR_X-ACCESS-TOKEN_HERE";

  $context = stream_context_create($aHTTP);

  $response = file_get_contents($URL, false, $context);
?>
var options = {
  "method": "GET",
  "hostname": "supplier.innovatemr.net",
  "path": "/api/v1/supply/getQuotaForSurvey/12634",
  "headers": {
    "content-type": "application/json",
    "x-access-token": "YOUR_X-ACCESS-TOKEN_HERE",
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Example Response

{
  "apiStatus": "success",
  "msg": "Quotas are successfully searched",
  "result": [
    {
      "_id": "59b778c66e4c0b1c8288f6ad",
      "quotaN": 10,
      "title": " 13 - 99 Yes, for business Yes, for personal Yes, for both",
      "quotaName": "",
      "hardStopType": 0,
      "cmp": 1,
      "clk": 1,
      "hardStop": 1,
      "quotaStatus": "Open",
      "RemainingN": 9,
      "targeting": {
        "AGE": [
            {
                "ageEnd": 99,
                "ageStart": 13,
                "OptionId": 1
            }
        ],
        "TECHNOLOGY_87": [
            {
                "OptionText": "Yes, for business",
                "OptionId": 1
            },
            {
                "OptionText": "Yes, for personal",
                "OptionId": 2
            },
            {
                "OptionText": "Yes, for both",
                "OptionId": 3
            }
        ]
      }
    },
    {
      "_id": "59b778c66e4c0b1c8288f6af",
      "quotaN": 10,
      "title": " 3rd Grade or less Middle School - Grades 4 - 8 Completed some high school High school graduate Completed some college, but no degree",
      "quotaName": "",
      "hardStopType": 0,
      "cmp": 0,
      "clk": 0,
      "hardStop": 1,
      "quotaStatus": "Open",
      "RemainingN": 10,
      "targeting": {
        "EDUCATION": [
            {
                "OptionId": 1,
                "OptionText": "3rd Grade or less"
            },
            {
                "OptionId": 2,
                "OptionText": "Middle School - Grades 4 - 8"
            },
            {
                "OptionId": 3,
                "OptionText": "Completed some high school"
            },
            {
                "OptionId": 4,
                "OptionText": "High school graduate"
            },
            {
                "OptionId": 6,
                "OptionText": "Completed some college, but no degree"
            }
        ]
      }
    }
  ]
}

This API will allow supplier to get quotas associated with each survey. Each quota will be returned with sample size and targeting criteria.

Query Parameters

Property Type Required Description
Survey ID Integer Yes Survey Id of particular survey (like : 12634)

Set Redirect Method for Survey

Definition

PUT http://<serverName>/api/v1/supply/setRedirectionForSurvey/<surveyId>

Example Request

curl -X PUT -H "Content-Type: application/json" 
"x-access-token: YOUR_X-ACCESS-TOKEN_HERE"
"https://supplier.innovatemr.net/api/v1/supply/setRedirectionForSurvey/6544"
<?php
  $URL = "https://supplier.innovatemr.net/api/v1/supply/setRedirectionForSurvey/6544";

  $aHTTP['http']['method']  = 'PUT';

  $aHTTP['http']['header']  = "x-access-token: YOUR_X-ACCESS-TOKEN_HERE";

  $context = stream_context_create($aHTTP);

  $response = file_get_contents($URL, false, $context);
?>
var options = {
  "method": "PUT",
  "hostname": "supplier.innovatemr.net",
  "path": "/api/v1/supply/setRedirectionForSurvey/6544",
  "headers": {
    "content-type": "application/json",
    "x-access-token": "YOUR_X-ACCESS-TOKEN_HERE",
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Example Response

{
  "apiStatus": "success",
  "msg": "Redirection Methods updated successfully"
}

With this API, supplier should be able to update redirect URLs or Pixels for each survey. By default, supplier’s global redirect and URLs will be used for each survey associated with supplier’s account. This API allows supplier to update the same at survey level. Global redirect URLs and Pixels for supplier’s account will remain as it is.

Query Parameters

Property Type Required Description
sUrl String NO Survey Success Url
fUrl String NO Fail Survey Url
oUrl String NO Overquota Survey Url
qTUrl String NO Quality Termination Survey Url
tUrl String NO Termination Survey Url
pstbck String NO Success Postback
pstbck_fail String NO Postback Fail

Get PIDs for re-contact surveys (studies)

Definition

GET http://<serverName>/api/v1/supply/getPidsForRecontactSurvey/<surveyId>

Example Request

curl -X GET -H "Content-Type: application/json" 
"x-access-token: YOUR_X-ACCESS-TOKEN_HERE"
"https://supplier.innovatemr.net/api/v1/supply/getPidsForRecontactSurvey/6299"
<?php
  $URL = "https://supplier.innovatemr.net/api/v1/supply/getPidsForRecontactSurvey/6299";

  $aHTTP['http']['method']  = 'GET';

  $aHTTP['http']['header']  = "x-access-token: YOUR_X-ACCESS-TOKEN_HERE";

  $context = stream_context_create($aHTTP);

  $response = file_get_contents($URL, false, $context);
?>
var options = {
  "method": "GET",
  "hostname": "supplier.innovatemr.net",
  "path": "/api/v1/supply/getPidsForRecontactSurvey/6299",
  "headers": {
    "content-type": "application/json",
    "x-access-token": "YOUR_X-ACCESS-TOKEN_HERE",
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Example Response

{
  "apiStatus": "success",
  "msg": "PIDs are successfully searched",
  "result": {
    "exclude": [
      "57974767f92c2ed94208a507",
      "57d7c450707c3d6220489230",
      "57ac5ae0707c3d095f4886eb"
    ],
    "include": [
      "57f255a5707c3d3a76410182",
      "572adfc1f92c2e971efb7678"
    ]
  }
}

This API allows suppliers to pull down list of PIDs (user Ids) for re-contact studies. When re-contact flag is True in Survey details, this API should be used to pull down user Ids associated with Supplier’s traffic.

Query Parameters

Property Type Required Description
Survey ID Integer Yes Survey Id of particular survey (like : 6299)

Get Closed Survey List (allocated to supplier only)

Definition

GET http://<surveyName>/api/v1/supply/getClosedSurveyListByDate/<Datetime>

Example Request

curl -X GET -H "Content-Type: application/json" 
"x-access-token: YOUR_X-ACCESS-TOKEN_HERE"
"https://supplier.innovatemr.net/api/v1/supply/getClosedSurveyListByDate/2017-11-01T13:35:11.364Z"
<?php
  $URL = "https://supplier.innovatemr.net/api/v1/supply/getClosedSurveyListByDate/2017-11-01T13:35:11.364Z";

  $aHTTP['http']['method']  = 'GET';

  $aHTTP['http']['header']  = "x-access-token: YOUR_X-ACCESS-TOKEN_HERE";

  $context = stream_context_create($aHTTP);

  $response = file_get_contents($URL, false, $context);
?>
var options = {
  "method": "GET",
  "hostname": "supplier.innovatemr.net",
  "path": "/api/v1/supply/getClosedSurveyListByDate/2017-11-01T13:35:11.364Z",
  "headers": {
    "content-type": "application/json",
    "x-access-token": "YOUR_X-ACCESS-TOKEN_HERE",
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Example Response

{
  "apiStatus": "success",
  "msg": "closed Survey IDs are successfully searched",
  "result": [
      12331,
      12656,
      14055,
      12163,
      12849,
      12423,
      12458
  ]
}

This API returns list of all Closed survey Ids which were allocated to Supplier’s account. Closed surveys after certain date time will be returned in this list. Using this list, Supplier should be able to archive such closed surveys from list.

Query Parameters

Property Type Required Description
Date Time String Yes Date and time of the closed survey (Example : 2017-11-01T13:35:11.364Z)

Get survey stats

Definition

GET http://<severName>/api/v1/supply/getSurveyStats/<surveyKey>

Example Request

curl -X GET -H "Content-Type: application/json" 
"x-access-token: YOUR_X-ACCESS-TOKEN_HERE"
"https://supplier.innovatemr.net/api/v1/supply/getSurveyStats/6614"
<?php
  $URL = "https://supplier.innovatemr.net/api/v1/supply/getSurveyStats/6614";

  $aHTTP['http']['method']  = 'GET';

  $aHTTP['http']['header']  = "x-access-token: YOUR_X-ACCESS-TOKEN_HERE";

  $context = stream_context_create($aHTTP);

  $response = file_get_contents($URL, false, $context);
?>
var options = {
  "method": "GET",
  "hostname": "supplier.innovatemr.net",
  "path": "/api/v1/supply/getSurveyStats/6614",
  "headers": {
    "content-type": "application/json",
    "x-access-token": "YOUR_X-ACCESS-TOKEN_HERE",
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Example Response

{
  "apiStatus": "success",
  "msg": "Survey Stats are successfully searched",
  "result": {
    "isVerified": false,
    "clicks": 52,
    "surveyStarts": 19,
    "completes": 13,
    "fails": 0,
    "overQuota": 0,
    "qualityTerms": 0,
    "preSurveyTerminates": 21,
    "preSurveyOverQuota": 1,
    "preSurveyQualityTermination": 0,
    "averageLOI": "0.23",
    "revenue": 3.379999999999999,
    "Conversion": "68.42"
  }
}

This API allows suppliers to get real time statistics for allocated survey. This will return data like number of clicks, completes, fails, over quota, revenue etc. for supplier’s traffic.

Query Parameters

Property Type Required Description
Survey ID Integer Yes Survey Id of particular survey (like : 6614)

Get Survey Transactions data

Definition

GET http://<serverName>/api/v1/supply/getSurveyTransactions/<surveyId>?startDate=yyyy-mm-dd&endDate=yyyy-mm-dd&status=Completed

Example Request

curl -X GET -H "Content-Type: application/json" 
"x-access-token: YOUR_X-ACCESS-TOKEN_HERE"
"https://supplier.innovatemr.net/api/v1/supply/getSurveyTransactions/6299?startDate=2017-01-02&endDate=2017-02-10&status=Completed"
<?php
  $URL = "https://supplier.innovatemr.net/api/v1/supply/getSurveyTransactions/6299?startDate=2017-01-02&endDate=2017-02-10&status=Completed";

  $aHTTP['http']['method']  = 'GET';

  $aHTTP['http']['header']  = "x-access-token: YOUR_X-ACCESS-TOKEN_HERE";

  $context = stream_context_create($aHTTP);

  $response = file_get_contents($URL, false, $context);
?>
var options = {
  "method": "GET",
  "hostname": "supplier.innovatemr.net",
  "path": "/api/v1/supply/getSurveyTransactions/6299?startDate=2017-01-02&endDate=2017-02-10&status=Completed",
  "headers": {
    "content-type": "application/json",
    "x-access-token": "YOUR_X-ACCESS-TOKEN_HERE",
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Example Response

{
  "apiStatus": "success",
  "msg": "Survey Transactions are successfully searched",
  "result": [
    {
      "ip": "104.189.11.109",
      "verifyToken": "Pending",
      "termReason": "",
      "CPI": "0.26",
      "PID": "9834540538942",
      "token": "TrJHBnKhpW",
      "st_date_time": "10/24/2017, 2:12:24 am PST",
      "clkDateTime": "10/24/2017, 2:12:03 am PST",
      "completeDateTime": "10/24/2017, 2:12:33 am PST",
      "status": "Completed"
    }
  ]
}

This API allows supplier to download transactional data for each survey with fields like PID (supplier user Id), survey transaction status, IP Address, survey start time, survey end time etc.

Query Parameters

Property Type Required Description
Survey ID Integer Yes Survey Id of particular survey (like : 6299)
Start Date String Yes - if End Date is present Start Date is beginning date (like : 2017-01-02)
End Date String Yes - if Start Date is present End Date is ending date (like :2017-02-10)
Status String No If we passed status along with Start Date and End Date then transaction status/ statuses (Pre Survey DNC/Completed/Failed/ Over Quota, Quality Termination/Pre Survey Termination/Start Survey DNC/Pre Survey Over Quota/Pre Survey Quality Termination) should be passed.

Get Survey Transactions data By PID and survey number

Definition

GET http://<serverName>/api/v1/supply/getSurveyTransactionsByCond/<surveyId>/<PID>

Example Request

curl -X GET -H "Content-Type: application/json" 
"x-access-token: YOUR_X-ACCESS-TOKEN_HERE"
"https://supplier.innovatemr.net/api/v1/supply/getSurveyTransactionsByCond/6555/9834540538942"
<?php
  $URL = "https://supplier.innovatemr.net/api/v1/supply/getSurveyTransactionsByCond/6555/9834540538942";

  $aHTTP['http']['method']  = 'GET';

  $aHTTP['http']['header']  = "x-access-token: YOUR_X-ACCESS-TOKEN_HERE";

  $context = stream_context_create($aHTTP);

  $response = file_get_contents($URL, false, $context);
?>
var options = {
  "method": "GET",
  "hostname": "supplier.innovatemr.net",
  "path": "/api/v1/supply/getSurveyTransactionsByCond/6555/9834540538942",
  "headers": {
    "content-type": "application/json",
    "x-access-token": "YOUR_X-ACCESS-TOKEN_HERE",
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Example Response

{  
   "apiStatus":"success",
   "msg":"Survey Transactions are successfully searched",
   "result":[  
      {  
        "id": "TrJHBnKhpW",
        "ip": "104.189.11.109",
        "verifyToken": "Pending",
        "termReason": "",
        "CPI": "0.26",
        "st_date_time": "10/24/2017, 2:12:24 am PST",
        "clkDateTime": "10/24/2017, 2:12:03 am PST",
        "completeDateTime": "10/24/2017, 2:12:33 am PST",
        "status": "Completed"
      }
   ]
}

This API allows suppliers to get specific survey transaction record associated with PID (supplier user Id) and survey Id.

Query Parameters

Property Type Required Description
Survey ID Integer Yes Survey Id of particular survey (like : 6555)
PID String Yes Panelist Id (like : 9834540538942)

Get Survey Transactions data By Date Range

Definition

GET http://<serverName>/api/v1/supply/getSurveyTransactionsByDateRange?startDate=yyyy-mm-dd&endDate=yyyy-mm-dd&status=Completed
                            OR
GET http://<serverName>/api/v1/supply/getSurveyTransactionsByDateRange?verifiedStartDate=yyyy-mm-dd&verifiedEndDate=yyyy-mm-dd&status=Valid

Example Request

curl -X GET -H "Content-Type: application/json" 
"x-access-token: YOUR_X-ACCESS-TOKEN_HERE"
"https://supplier.innovatemr.net/api/v1/supply/getSurveyTransactionsByDateRange?startDate=2017-01-02&endDate=2017-02-10&status=Completed"
<?php
  $URL = "https://supplier.innovatemr.net/api/v1/supply/getSurveyTransactionsByDateRange?startDate=2017-01-02&endDate=2017-02-10&status=Completed";

  $aHTTP['http']['method']  = 'GET';

  $aHTTP['http']['header']  = "x-access-token: YOUR_X-ACCESS-TOKEN_HERE";

  $context = stream_context_create($aHTTP);

  $response = file_get_contents($URL, false, $context);
?>
var options = {
  "method": "GET",
  "hostname": "supplier.innovatemr.net",
  "path": "/api/v1/supply/getSurveyTransactionsByDateRange?startDate=2017-01-02&endDate=2017-02-10&status=Completed",
  "headers": {
    "content-type": "application/json",
    "x-access-token": "YOUR_X-ACCESS-TOKEN_HERE",
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Example Response

{  
   "apiStatus":"success",
   "msg":"Survey Transactions are successfully searched",
   "result":[  
    {
      "id": "THyBTPgJkf",
      "ip": "122.160.153.166",
      "verifyToken": "Pending",
      "termReason": "",
      "grp": {},
      "CPI": "1.57",
      "PID": "J1",
      "st_date_time": "11/07/2017, 1:08:15 am PST",
      "clkDateTime": "11/07/2017, 1:06:53 am PST",
      "completeDateTime": "11/07/2017, 1:09:33 am PST",
      "surveyId": 14344,
      "status": "Completed"
    },
    {
      "id": "THy8jOzDCW",
      "ip": "122.160.153.166",
      "verifyToken": "Valid",
      "termReason": "",
      "grp": {},
      "verifiedTknDt": "11/01/2017, 5:00:20 am PST",
      "CPI": "0.26",
      "PID": "test52",
      "st_date_time": "11/01/2017, 2:11:53 am PST",
      "clkDateTime": "11/01/2017, 2:11:35 am PST",
      "completeDateTime": "11/01/2017, 2:12:01 am PST",
      "surveyId": 14016,
      "status": "Completed"
    },
  ] 
}

This API allows suppliers to get survey transaction records associated within the specified Date Range whether startDate and endDate/ verifiedStartDate and verifiedEndDate (in case of valid and invalid token).

Query Parameters

Property Type Required Description
Start Date String Yes Start Date is beginning date (like : 2017-01-02)
End Date String Yes End Date is ending date (like :2017-02-10)
Verified Start Date String Yes Verified Start Date is beginning date to get token which are verified(like : 2017-01-02)
Verified End Date String Yes Verified End Date is ending date to get token which are verified upto that date (like : 2017-02-10)
Status String No 1. If we passed status along with Start Date and End Date then transaction status/ statuses (Pre Survey DNC/Completed/Failed/ Over Quota,Quality Termination/Pre Survey Termination/Start Survey DNC/Pre Survey Over Quota/Pre Survey Quality Termination) should be passed.
2. If we passed status along with Verified Start Date and Verified End Date then verified token status/statues (Valid/Invalid) should be passed.

Get Survey Stats data By Date Range

Definition

GET http://<serverName>/api/v1/supply/getSurveyStatsByDateRange?startDate=yyyy-mm-dd&endDate=yyyy-mm-dd
                            OR
GET http://<serverName>/api/v1/supply/getSurveyStatsByDateRange?verifiedStartDate=yyyy-mm-dd&verifiedEndDate=yyyy-mm-dd

Example Request

curl -X GET -H "Content-Type: application/json" 
"x-access-token: YOUR_X-ACCESS-TOKEN_HERE"
"https://supplier.innovatemr.net/api/v1/supply/getSurveyStatsByDateRange?startDate=2017-01-02&endDate=2017-02-10"
<?php
  $URL = "https://supplier.innovatemr.net/api/v1/supply/getSurveyStatsByDateRange?startDate=2017-01-02&endDate=2017-02-10";

  $aHTTP['http']['method']  = 'GET';

  $aHTTP['http']['header']  = "x-access-token: YOUR_X-ACCESS-TOKEN_HERE";

  $context = stream_context_create($aHTTP);

  $response = file_get_contents($URL, false, $context);
?>
var options = {
  "method": "GET",
  "hostname": "supplier.innovatemr.net",
  "path": "/api/v1/supply/getSurveyStatsByDateRange?startDate=2017-01-02&endDate=2017-02-10",
  "headers": {
    "content-type": "application/json",
    "x-access-token": "YOUR_X-ACCESS-TOKEN_HERE",
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

Example Response

{  
  "apiStatus": "success",
  "msg": "Survey Stats are successfully searched",
  "result": 
  {
    "clicks": 418,
    "surveyStarts": 172,
    "completes": 94,
    "fails": 10,
    "overQuota": 7,
    "qualityTerms": 7,
    "preSurveyTerminates": 164,
    "preSurveyOverQuota": 4,
    "preSurveyQualityTermination": 15,
    "averageLOI": "0.48",
    "revenue": "46.79",
    "Conversion": "54.65",
    "validCompletes": 16,
    "invalidCompletes": 6,
    "pendingCompletes": 72
  }
}

This API allows suppliers to get survey statistics records associated within the specified Date Range whether startDate and endDate/verifiedStartDate and verifiedEndDate.

Query Parameters

Property Type Required Description
Start Date String Yes Start Date is beginning date (like : 2017-01-02)
End Date String Yes End Date is ending date (like :2017-02-10)
Verified Start Date String Yes Verified Start Date is beginning date to get token which are verified(like : 2017-01-02)
Verified End Date String Yes Verified End Date is ending date to get token which are verified upto that date (like : 2017-02-10)

Postbacks/Redirects

Redirect URL

Survey success URL

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

Fail survey URL

This redirect URL will be used when user will be terminated on client side for the survey.

Over quota survey URL

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

Quality terminate survey URL

This redirect URL will be used when user will be marked as Quality terminate by client OR by Innovate 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 Innovate system for the survey.

Following fields support in redirect URL :-

Field Merge Field Defintion
token %%token%% Unique survey transaction ID.
pid %%pid%% Supplier unique user Id sent to Innovate in survey entry link as part of PID variable. Innovate will send it back to supplier in the redirects or postback.
status %%status%% Status of survey(success(1), termination(2), over quota(3) and quality termination(4))
revenue %%revenue%% Supplier final calculated CPI for survey complete.
surveyId %%surveyId%% Survey Id for which supplier have sent traffic.
trackId %%trackId%% Supplier unique transaction Id sent to Innovate in survey entry link as part of trackId variable. Innovate will send it back to supplier in the redirects or postback.
hashdata %%hashdata%% Innovate support 2 algorithms to hash the entire string of redirect/postback URL. SHA1 and MD5. Supplier can choose any method from this and InnovateMR will share secret key for supplier account. Supplier can use that key to decrypt the value and match the exact string.
termReason %%termReason%% Reason of survey termination.

PostBack URL

Success postback

This URL is fired as server to server postback pixel in case of successful complete. Both redirect and postback URLs can be used. First, Innovate system will fire postback pixel and then redirect user to the success redirect URL. Postback can be used for more secure logic with whitelisting server IPs.

Postback fail

This URL is fired as server to server postback pixel in case of all status except complete.

Following fields support in postback URL :-

Field Merge Field Definition
token %%token%% Unique survey transaction ID.
pid %%pid%% Unique user Id sent to Innovate in survey entry link as part of PID variable. Innovate will send it back to supplier in the redirects or postback.
status %%status%% Status of survey(success(1), termination(2), over quota(3) and quality termination(4))
revenue %%revenue%% Supplier final calculated CPI for survey complete.
trackId %%trackId%% Supplier unique transaction Id sent to Innovate in survey entry link as part of trackId variable. Innovate will send it back to supplier in the redirects or postback.
hashdata %%hashdata%% Innovate support 2 algorithms to hash the entire string of redirect/postback URL. SHA1 and MD5. Supplier can choose any method from this and InnovateMR will share secret key for supplier account. Supplier can use that key to decrypt the value and match the exact string.
termReason %%termReason%% Reason of survey termination.
surveyId %%surveyId%% Survey Id for which supplier have sent traffic.

Hashing Mechanism

Innovate uses Hashing Mechanism for the encryption using following methods :-

SHA1

MD5

Steps to generate hash-

Secret key is required to generate hash. Secret key will be provided by InnovateMR account manager.

Innovate will use complete URL without hash value in it. Example Hashed URL = https://www.xyz.com/web-service/innovate?pubid=ct4JGltDsCS&tran_id=28969 &offer_id=3&cpi=1.8&hash=

Code which will be used to generate hash :

A. SHA1 encryption method : var hashVal = crypto.createHmac(‘sha1’, secret_key).update(restUrl).digest(“hex”); where restUrl = Hashed URL

B. MD5 encryption method : var hashVal = crypto.createHmac(‘MD5’, secret_key).update(restUrl).digest(“hex”); where restUrl = Hashed URL

Generated Hash = “8c593bbbfa0beae8604e4d88805c60dc59e24db1”. Add this hash value in the URL mentioned in step 2.

Final URL which will be redirected to client side = https://www.xyz.com/web-service/innovate?pubid=ct4JGltDsCS&tran_id=28969&offer_id=3&cpi=1.8 &hash=8c593bbbfa0beae8604e4d88805c60dc59e24db1

HTTP Status Codes

Innovate uses 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 Fulcrum’s servers (these are rare).

Status Code Meaning
200 OK – The request has succeeded . Request include GET and POST
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.
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 Allowed – 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)
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The kitten requested has been removed from our servers
418 I’m a teapot
429 Too Many Requests – You’re requesting too many kittens! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.
504 Gateway Timeout – This error response is given when the server is acting as a gateway and cannot get a response in time.

SUPPLY API – FAQ

A supplier API that provides a simple and quick way to pull down survey inventory available to suppliers and match it with the user’s profile.

We connect our systems together and allocate a portion of our inventory to your company based on various attributes, including delivery speed, targeting capabilities, geographical reach and price. This way you as a supplier will be able to get updated lists of survey inventory, real time statistics for each survey and targeting questions to match with the user’s profile.

Your system will be able to analyze the projects fit for your target groups and then you will send your traffic to our projects.

You will be sending the invites. We are working on a feature to send the invites ourselves, but this is currently in the development phase.

It gives you the opportunity to be selective and pick only projects that are fit for your audience, thus monetizing traffic in an effective and efficient manner.

You are the one who decides the incentives for your panelists.

The general volume opportunity of our API surveys has exceeded 350k survey completions monthly and is continuously growing as we’re expanding our reach in new markets across the globe.

There are three pricing methods we can accommodate: flat rate, grid and revenue share. We’re open to discuss each and every option.

This depends on your capacity, targeting capabilities and geographical reach and engagement. As general information, Innovate MR spends considerable amounts on sample each month and this figure is constantly increasing.

We are quickly growing our global client base and adding new surveys daily, so all markets can and will be considered for integration. Our goal is to expand our inventory globally to as many markets as possible.

Beside the great revenue opportunity and the chance to exceed your ROI goals, this is a great way to increase user engagement and keep your users on their platform longer. Also save valuable time, as it eliminates the back and forth from ad-hoc bidding because everything is automated.

All the technical information regarding the integration can be found in our developer portal (http://developer.innovatemr.com/). Our tech team will also be available to assist during the integration process from start to finish.