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",
      "trackId": "6d30aa69-2693-4bce-91ab-1a85b69a72d5"
    }
  ]
}

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",
        "trackId": "6d30aa69-2693-4bce-91ab-1a85b69a72d5"
      }
   ]
}

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",
      "trackId": "6d30aa69-2693-4bce-91ab-1a85b69a72d5"
    },
    {
      "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",
      "trackId": ""
    },
  ] 
}

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.

Supplier 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.

Buyer API

Environments

Sandbox Endpoint

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

Production Endpoint

 https://api.pegasusmr.com

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.

Create Job

Definition

POST http://<serverName>/api/v2/pega/job

Example Request

curl --request POST 
  --url 'https://api.pegasusmr.com/api/v2/pega/job' 
  --header 'Content-Type: application/json' 
  --header 'x-access-token: {token}' 
  --data '{"Name": "job_name",
    "Category": 42,
    "CustomerContact": [
        {
            "CustomerContactName": "customer_name",
            "CustomerContactId": 150,
            "Primary": 0
        }
    ],
    "SalesRepresentative" : 67,
    "ProjectManager": 123,
    "ProjectManagerAlt": 133,
    "ReferenceNumber": "15",
    "Status": 2,
    "Description": "",
    "Category": 3,
    "FingerPrintingLevel": 3,
    "AllowDuplicateStatus": [1,3],
    "StartDate": "12/11/2019",
    "EndDate": "12/11/2019"

}'

Example Response

{
    "apiStatus": "success",
    "msg": "Job is successfully added",
    "job": {
        "Customer": {
            "CustomerName": "cust_name",
            "CustomerId": 394
        },
        "ProjectManager": {
            "ProjectManagerName": "pm1",
            "ProjectManagerId": 123
        },
        "ProjectManagerAlt": {
            "ProjectManagerName": "pm2",
            "ProjectManagerId": 133
        },
        "SalesRepresentative": {
            "SalesRepresentativeName": "salesRep1",
            "SalesRepresentativeId": 67
        },
        "Status": 2,
        "FingerPrintingLevel": 3,
        "AllowDuplicateStatus": [
            1,
            3
        ],
        "Name": "job_name",
        "Category": 3,
        "CustomerContact": [
            {
                "Primary": 0,
                "CustomerContactName": "customer_cont_name",
                "CustomerContactId": 150
            }
        ],
        "ReferenceNumber": "15",
        "Description": "",
        "StartDate": "2019-12-10T18:30:00.000Z",
        "EndDate": "2019-12-10T18:30:00.000Z",
        "DigitalFingerprintType": 1,
        "Id": 8576
    }
}

This api will allow you to create job

Here are properties to send for Job Model:

Property Type Required Remarks
Name String true
CustomerContact Array of JSONObject
CustomerContactName String false
CustomerContactId Number false
Primary Number false Used as boolean 0 for false and 1 for true
SalesRepresentative Number false
ProjectManager Number false
ProjectManagerAlt Number false
ReferenceNumber String false Maximum Length can be 100 chars
Status Number true
Description String false
Category Number true It can be a Number from 1 to 43
FingerPrintingLevel Number false Values can be 1, 2, 3 or 4
AllowDuplicateStatus Array false Array of Numbers like [1, 2, 3, 4]
StartDate Date false ISO String format
EndDate Date false ISO String format
ProjectedCloseDate JSONObject
Year Number false YYYY format
Month Number false MM format
DigitalFingerprintType Number false Values can be 1, 2 or 3"
UniqueIPCheck Number false Used as boolean 0 for false and 1 for true
UniquePIDCheck Number false Used as boolean 0 for false and 1 for true

Update Job

Definition

PUT http://<serverName>/api/v2/pega/job/{jobId}

Example Request

curl --request PUT 
  --url 'https://api.pegasusmr.com/api/v2/pega/job/8575'
  --header 'Content-Type: application/json'
  --header 'x-access-token: {token}'
  --data '{
    "Name": "Job_name",
    "Category": 41,
    "status" : 1
}'

Example Response

{
    "apiStatus": "success",
    "msg": "Job is successfully updated",
    "job": {
        "Customer": {
            "CustomerName": "cust_name",
            "CustomerId": 394
        },
        "ProjectManager": {
            "ProjectManagerName": "pm1",
            "ProjectManagerId": 67
        },
        "ProjectManagerAlt": {
            "ProjectManagerName": "pm2",
            "ProjectManagerId": 243
        },
        "SalesRepresentative": {
            "SalesRepresentativeName": "salesRep1",
            "SalesRepresentativeId": 45
        },
        "Status": 1,
        "FingerPrintingLevel": 3,
        "AllowDuplicateStatus": [
            1,
            3
        ],
        "Name": "Job_name",
        "Category": 41,
        "CustomerContact": [
            {
                "Primary": 0,
                "CustomerContactName": "customer_cont_name",
                "CustomerContactId": 150
            }
        ],
        "ReferenceNumber": "",
        "Description": "",
        "StartDate": "2019-12-10T18:30:00.000Z",
        "EndDate": "2019-12-10T18:30:00.000Z",
        "DigitalFingerprintType": 1,
        "Id": 8575
    }
}

This api will allow you to modify job

Here are properties to send for Job Model:

Property Type Required Remarks
Name String true
CustomerContact Array of JSONObject
CustomerContactName String false
CustomerContactId Number false
Primary Number false Used as boolean 0 for false and 1 for true
SalesRepresentative Number false
ProjectManager Number false
ProjectManagerAlt Number false
ReferenceNumber String false Maximum Length can be 100 chars
Status Number true
Description String false
Category Number true It can be a Number from 1 to 43
FingerPrintingLevel Number false Values can be 1, 2, 3 or 4
AllowDuplicateStatus Array false Array of Numbers like [1, 2, 3, 4]
StartDate Date false ISO String format
EndDate Date false ISO String format
ProjectedCloseDate JSONObject
Year Number false YYYY format
Month Number false MM format
DigitalFingerprintType Number false Values can be 1, 2 or 3
UniqueIPCheck Number false Used as boolean 0 for false and 1 for true
UniquePIDCheck Number false Used as boolean 0 for false and 1 for true

Get Job Details

Definition

GET http://<serverName>/api/v2/pega/job/{jobId}

Example Request

curl --request GET 
  --url 'https://api.pegasusmr.com/api/v2/pega/job/8575'
  --header 'Content-Type: application/json'
  --header 'x-access-token: {token}'

This api will allow you to get job

Query Parameters

Property Type Required Remarks
JobId Number true Job Number

Example Response

{
    "apiStatus": "success",
    "job": {
        "Customer": {
            "CustomerName": "cust_name",
            "CustomerId": 394
        },
        "ProjectManager": {
            "ProjectManagerName": "pm1",
            "ProjectManagerId": 67
        },
        "ProjectManagerAlt": {
            "ProjectManagerName": "pm2",
            "ProjectManagerId": 243
        },
        "SalesRepresentative": {
            "SalesRepresentativeName": "salesRep1",
            "SalesRepresentativeId": 45
        },
        "Status": 1,
        "FingerPrintingLevel": 3,
        "AllowDuplicateStatus": [
            1,
            3
        ],
        "Name": "Job_name",
        "Category": 41,
        "CustomerContact": [
            {
                "Primary": 0,
                "CustomerContactName": "customer_cont_name",
                "CustomerContactId": 150
            }
        ],
        "ReferenceNumber": "",
        "Description": "",
        "StartDate": "2019-12-10T18:30:00.000Z",
        "EndDate": "2019-12-10T18:30:00.000Z",
        "DigitalFingerprintType": 1,
        "Id": 8575,
        "CreatedDate": "2018-12-05T12:18:25.508Z",
        "LiveDate": "2018-12-05T12:59:41.932Z"
    }
}

Update Job Status

Definition

PUT http://<serverName>/api/v2/pega/job/{JobId}/status

Example Request

curl --request PUT
  --url 'https://api.pegasusmr.com/api/v2/pega/job/8575/status'
  --header 'Content-Type: application/json'
  --header 'x-access-token: {token}'
  --data '{
    "Status": 1
}'

Example Response

{
    "apiStatus": "success",
    "msg": "Job status is set as Live"
}

This api will allow you to update job status

Query Parameters

Property Type Required Remarks
status Number true Example 0/1/2
JobId Number true Job Number

Find Jobs

Definition

POSThttp://<serverName>/api/v2/pega/jobs

Example Request

curl --request POST
  --url 'https://api.pegasusmr.com/api/v2/pega/jobs'
  --header 'Content-Type: application/json'
  --header 'x-access-token: {token}'
  --data '{"CloseDate":{},"GroupStatus":[0],"StaffMember":[],"Customer":[394],"Color":[1],"Keywords":[],"Status":[1], "Limit":5}'

Example Response

{
    "apiStatus": "success",
    "totalCount": 1,
    "job": [
        {
            "Id": 7032,
            "Name": "job_name",
            "DigitalFingerprintType": 2,
            "CreatedBy": {
                "FirstName": "createdby_first_name",
                "LastName": "createdby_last_name",
                "Id": 84
            },
            "ProjectedCloseDate": {
                "Year": 2017,
                "Month": 12
            },
            "CreatedDate": "2017-11-07T22:40:10.753Z",
            "Groups": [
                {
                    "CreatedDate": "2017-11-07T22:40:10.829Z",
                    "CreatedBy": {
                        "Id": 84,
                        "LastName": "createdby_last_name",
                        "FirstName": "createdby_first_name"
                    },
                    "Status": 0,
                    "Id": 14377,
                    "Name": "Group_name"
                }
            ],
            "FingerPrintingLevel": 3,
            "EndDate": "2017-12-01T00:00:00.000Z",
            "StartDate": "2017-11-01T00:00:00.000Z",
            "Status": 2,
            "SalesRepresentative": {
                "SalesRepresentativeId": 68,
                "SalesRepresentativeName": "salesRep1"
            },
            "ProjectManagerAlt": {
                "ProjectManagerId": 67,
                "ProjectManagerName": "pm2"
            },
            "ProjectManager": {
                "ProjectManagerId": 84,
                "ProjectManagerName": "pm1"
            },
            "Customer": {
                "CustomerId": 144,
                "CustomerName": ""
            },
            "CustomerContact": [
                {
                    "CustomerContactName": "customer_name",
                    "CustomerContactId": 182,
                    "Primary": 1
                }
            ]
        }
    ]
}

This api will allow you to get all jobs

Here are properties to send for Job Model:

Property Type Required Remarks
GroupStatus Array false Like [1, 2, 0, 11]
StaffMember Array false Array of Ids for SalesRepresentative, ProjectManager etc.
Customer Array false Array of CustomerIds
Color Array false Colors Numbers like 1, 2 and 3
Keywords Array false Keywords used in job names etc
Status Array false Array of job’s Status that you need. Like [0, 1, 2]
For Pagination
Limit Number false Default 15
Page Number false Default 1

Create Group

Definition

POST http://<serverName>/api/v2/pega/jobs/{JobId}/group

Example Request

curl --request POST
  --url 'https://api.pegasusmr.com/api/v2/pega/jobs/8575/group'
  --header 'Content-Type: application/json'
  --header 'x-access-token: {token}'
  --data '{
    "Name": "Group A Test",
    "N": 20,
    "IncidenceRate": 50,
    "CostPerInterview": 3,
    "LengthOfInterview": 5,
    "LiveSurveyUrl": "http://www.survey.com?tk=[%%token%%]&pid=[%%pid%%]",
    "Target":{
        "Country": "United States",
        "Languages": [1]
    }
}'

Example Response

{
    "apiStatus": "success",
    "msg": "Group is successfully accepted",
    "group": {
        "Target": {
            "GeoIPCheck": 1,
            "Languages": [
                1
            ],
            "Country": "United States"
        },
        "Status": 1,
        "Name": "Group A Test",
        "N": 20,
        "IncidenceRate": 50,
        "CostPerInterview": 2,
        "LengthOfInterview": 5,
        "LiveSurveyUrl": "http://www.survey.com?tk=[%%token%%]&pid=[%%pid%%]",
        "JobId": 8575,
        "CompanyId": 44,
        "DeviceType": 6,
        "CountryCode": "US",
        "Language": "ENGLISH",
        "Id": 19427,
        "CreatedDate": "2018-12-05T13:15:54.745Z",
        "SID": "ev9wL269"
    }
}

This api will allow you to create group for a job.

Here are properties to send for Job Model:

Property Type Required Remarks
JobId Number false JobId to create group under that job
Name String true Group Name
N Number true
Status Number false Default 0, 0 = Pause and 1 = Live
IncidenceRate Number true 1 to 100
CostPerInterview Number true Cost in USD
LengthOfInterview Number true 1 to 45 minutes
LiveSurveyUrl String true Url Length can be maximum 1000 chars. Example: http://www.survey.com?tk=[%%token%%]&pid=[%%pid%%]
TestSurveyUrl String false Same as Live Url
Color Number false Default 0, 0 = White/None, 1 = Yellow and 2 = Red
Priority Number false Default 0, 0 = Normal, 1 = High and 2 = Critical
DeviceType Number false Default 6(All)
Target JSONObject
GeoIPCheck Number false Default 1, 0 = false and 1 = true
Country String true Country Name. Example:“United States” Please check Country list for other country names
Languages Array true Array of Language code. Example: For English - [1]
Note String false Note to add any specific information
MaximumCostPerInterview Number false MaximumCostPerInterview is to limit CostPerInterview.

Update Group

Definition

PUT http://<serverName>/api/v2/pega/group/{GroupId}

Example Request

curl --request PUT 
  --url 'https://api.pegasusmr.com/api/v2/pega/group/19427'
  --header 'Content-Type: application/json'
  --header 'x-access-token: {token}'
  --data '{
    "IncidenceRate": 30,
    "CostPerInterview": 2,
    "LengthOfInterview": 3
}'

Example Response

{
    "apiStatus": "success",
    "msg": "Group is successfully accepted",
    "group": {
        "Target": {
            "GeoIPCheck": 1,
            "Languages": [
                1
            ],
            "Country": "United States"
        },
        "Status": 1,
        "Name": "Group A Test",
        "N": 20,
        "IncidenceRate": 30,
        "CostPerInterview": 3.75,
        "LengthOfInterview": 3,
        "LiveSurveyUrl": "http://www.survey.com?tk=[%%token%%]&pid=[%%pid%%]",
        "JobId": 8575,
        "CompanyId": 44,
        "DeviceType": 6,
        "CountryCode": "US",
        "Language": "ENGLISH",
        "Id": 19427,
        "CreatedDate": "2018-12-05T13:15:54.745Z",
        "SID": "ev9wL269",
        "TestSurveyUrl": ""
}

This api will allow you to update group for a job.

Here are properties to send for Job Model:

Property Type Required Description
JobId Number false JobId to create group under that job
Name String false Group Name
N Number false
Status Number false Default 0, 0 = Pause and 1 = Live
IncidenceRate Number false 1 to 100
CostPerInterview Number false Cost in USD
LengthOfInterview Number false 1 to 45 minutes
LiveSurveyUrl String false Url Length can be maximum 1000 chars. Example: http://www.survey.com?tk=[%%token%%]&pid=[%%pid%%]
TestSurveyUrl String false Same as Live Url
Color Number false Default 0, 0 = White/None, 1 = Yellow and 2 = Red
Priority Number false Default 0, 0 = Normal, 1 = High and 2 = Critical
DeviceType Number false Default 6(All)
Target JSONObject
GeoIPCheck Number false Default 1, 0 = false and 1 = true
Country String false Country Name. Example:“United States” Please check Country list for other country names
Languages Array false Array of Language code. Example: For English - [1]
Note String false Note to add any specific information
MaximumCostPerInterview Number false MaximumCostPerInterview is to limit CostPerInterview.

Get Group Details

Definition

GET http://<serverName>/api/v2/pega/groups/{GroupId}

Example Request

curl --request GET 
  --url 'https://api.pegasusmr.com/api/v2/pega/groups/19427' 
  --header 'Content-Type: application/json' 
  --header 'x-access-token: {token}'

Example Response

{
    "apiStatus": "success",
    "group": {
        "Target": {
            "GeoIPCheck": 1,
            "Languages": [
                1
            ],
            "Country": "United States",
            "Questions": []
        },
        "Status": 1,
        "Name": "Group A Test",
        "N": 20,
        "IncidenceRate": 30,
        "CostPerInterview": 3.75,
        "LengthOfInterview": 3,
        "LiveSurveyUrl": "http://www.survey.com?tk=[%%token%%]&pid=[%%pid%%]",
        "JobId": 8575,
        "CompanyId": 44,
        "DeviceType": 6,
        "CountryCode": "US",
        "Language": "ENGLISH",
        "Id": 19427,
        "CreatedDate": "2018-12-05T13:15:54.745Z",
        "SID": "ev9wL269",
        "TestSurveyUrl": ""
    }
}

This api will allow you to get group for a job.

Query Parameters

Property Type Required Remarks
GroupId Number true Group Number

Update Group Status

Definition

PUT http://<serverName>/api/v2/pega/group/{GroupId}/status

Example Request

curl --request PUT 
  --url 'https://api.pegasusmr.com/api/v2/pega/group/19427/status' 
  --header 'Content-Type: application/json'
  --header 'x-access-token: {token}' 
  --data '{
    "Status": 2
}'

Example Response

{
    "apiStatus": "success",
    "msg": "Group status is set as Paused",
    "group": {
        "Target": {
            "GeoIPCheck": 1,
            "Languages": [
                1
            ],
            "Country": "United States"
        },
        "Status": 2,
        "Name": "Group A Test",
        "N": 20,
        "IncidenceRate": 30,
        "CostPerInterview": 3.75,
        "LengthOfInterview": 3,
        "LiveSurveyUrl": "http://www.survey.com?tk=[%%token%%]&pid=[%%pid%%]",
        "JobId": 8575,
        "CompanyId": 44,
        "DeviceType": 6,
        "CountryCode": "US",
        "Language": "ENGLISH",
        "Id": 19427,
        "CreatedDate": "2018-12-05T13:15:54.745Z",
        "SID": "ev9wL269",
        "TestSurveyUrl": ""
    }
}

This api is used to mark Group Live(Status 1), MaximumCostPerInterview.

Here are properties to send for Job Model:

Property Type Required Remarks
status Number false Default 0, 0 = Pause and 1 = Live
GroupId Number true Group Number

Add Target to group

Definition

POST http://<serverName>/api/v2/pega/group/{GroupId}/target

Example Request

curl --request POST
  --url 'https://api.pegasusmr.com/api/v2/pega/group/19427/target'
  --header 'Content-Type: application/json'
  --header 'x-access-token: {token}' 
  --data '{
    "Category":1,
    "QuestionText":"What is your gender?",
    "QuestionType":"Single Punch",
    "Options":[{
        "OptionText":"Male",
        "OptionId":1
    },
    {
        "OptionText":"Female",
        "OptionId":2
    }],
    "QuestionKey":"GENDER",
    "Type":"",
    "QuestionId":2
}'

Example Response

{
    "apiStatus": "success",
    "msg": "Target updated successfully",
    "Target": [
        {
            "Type": "",
            "Sequence": 0,
            "Category": 1,
            "QuestionText": "What is your gender?",
            "QuestionType": "Single Punch",
            "QuestionKey": "GENDER",
            "QuestionId": 2,
            "Options": [
                {
                    "OptionText": "Male",
                    "OptionId": 1
                },
                {
                    "OptionText": "Female",
                    "OptionId": 2
                }
            ]
        }
    ]
}

This api will allow you to add target to a group.

Here are properties to send for Job Model:

Property Type Required Remarks
QuestionId Number true Question Id as in Questions Library
QuestionType String false Question Type like “Single Punch” or “Numeric Open Ended” as in Questions Library
QuestionText String true Question Text as in Questions Library
QuestionKey String true Question Key Like “AGE”, “GENDER” etc. as in Questions Library
Category Number true Category Id for the Question as in Questions Library
Type String false Type is “Profile” for Profile Questions only else not required
Sequence Number false Determines qualification order in the prescreener
Options Array of JSONObjects
OptionId Number true Option Id for the chosen option from Questions Library, For Numeric Open Ended Questions this is just a sequence number
OptionText String false Option Text for the chosen option, It is required for all question options except AGE
AgeStart Number false For AGE Question only, Start age value
AgeEnd Number false For AGE Question only, End age value

Update Target to group

Definition

PUT http://<serverName>/api/v2/pega/group/{GroupId}/target

Example Request

curl --request PUT 
  --url 'https://api.pegasusmr.com/api/v2/pega/group/19427/target'
  --header 'Content-Type: application/json'
  --header 'x-access-token: {token}'
  --data '{
    "Category":1,
    "QuestionText":"What is your Age?",
    "QuestionType":"Numeric Open Ended",
    "Options":[{
        "AgeStart":24,
        "AgeEnd":40,
        "OptionId":1
    }],
    "QuestionKey":"AGE",
    "Type":"",
    "QuestionId":1
}'

Example Response

{
    "apiStatus": "success",
    "msg": "Target updated successfully",
    "Target": [
        {
            "Type": "",
            "Sequence": 0,
            "Category": 1,
            "QuestionText": "What is your gender?",
            "QuestionType": "Single Punch",
            "QuestionKey": "GENDER",
            "QuestionId": 2,
            "Options": [
                {
                    "OptionText": "Male",
                    "OptionId": 1
                },
                {
                    "OptionText": "Female",
                    "OptionId": 2
                }
            ]
        },
        {
            "Type": "",
            "Sequence": 0,
            "Category": 1,
            "QuestionText": "What is your Age?",
            "QuestionType": "Numeric Open Ended",
            "QuestionKey": "AGE",
            "QuestionId": 1,
            "Options": [
                {
                    "AgeStart": 24,
                    "AgeEnd": 40,
                    "OptionId": 1
                }
            ]
        }
    ]
}

This api will allow you to update target in a group.

Here are properties to send for Job Model:

Property Type Required Remarks
QuestionId Number true Question Id as in Questions Library
QuestionType String false Question Type like “Single Punch” or “Numeric Open Ended” as in Questions Library
QuestionText String true Question Text as in Questions Library
QuestionKey String true Question Key Like “AGE”, “GENDER” etc. as in Questions Library
Category Number true Category Id for the Question as in Questions Library
Type String false Type is “Profile” for Profile Questions only else not required
Sequence Number false Determines qualification order in the prescreener
Options Array of JSONObjects
OptionId Number true Option Id for the chosen option from Questions Library, For Numeric Open Ended Questions this is just a sequence number
OptionText String false Option Text for the chosen option, It is required for all question options except AGE
AgeStart Number false For AGE Question only, Start age value
AgeEnd Number false For AGE Question only, End age value

Remove Target Question

Definition

PUT http://<serverName>/api/v2/pega/group/{GroupId}/{QuestionKey}

Example Request

curl --request DELETE 
  --url 'https://api.pegasusmr.com/api/v2/pega/group/19427/GENDER' 
  --header 'Content-Type: application/json' 
  --header 'x-access-token: {token}'

Example Response

{
    "apiStatus": "success",
    "msg": "Target removed successfully",
    "Target": [
        {
            "Type": "",
            "Sequence": 0,
            "Category": 1,
            "QuestionText": "What is your Age?",
            "QuestionType": "Numeric Open Ended",
            "QuestionKey": "AGE",
            "QuestionId": 1,
            "Options": [
                {
                    "AgeStart": 24,
                    "AgeEnd": 40,
                    "OptionId": 1
                }
            ]
        }
    ]
}

This api will allow you to remove target from a group.

Query Parameters

Property Type Required Remarks
QuestionKey String true Question Key Like “AGE”, “GENDER” etc. as in Questions Library
GroupId Number true Group Number

Questions Library

Get All Questions

Definition

GET http://<serverName>/api/v2/pega/questions/<CountryKey>/<language>

Example Request

curl --request GET 
  --url 'https://api.pegasusmr.com/api/v2/pega/questions/US/ENGLISH' 
  --header 'Content-Type: application/json' 
  --header 'x-access-token: {token}'

Example Response

{
    "apiStatus": "success",
    "Questions": [
        {
            "StandardTarget": 0,
            "Category": [
                {
                    "Primary": true,
                    "Id": 202,
                    "Name": "Test Category"
                }
            ],
            "QuestionType": "Multipunch",
            "Id": 7123,
            "QuestionKey": "TEST_CATEGORY_7123",
            "Options": [
                {
                    "OptionText": "Palau",
                    "Id": 4
                },
                {
                    "OptionText": "Nauru",
                    "Id": 3
                },
                {
                    "OptionText": "Tuvalu",
                    "Id": 2
                },
                {
                    "OptionText": "Vatican City",
                    "Id": 1
                }
            ],
            "PremiumPrice": 3.23,
            "QuestionText": "Which country has the lowest population?"
        }
    ]
}

The questions in this library can be used to add qualifications for groups(surveys).

Query Parameters

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