Fetch top surveys for user

Definition

This API endpoint allows you to fetch the top inBrain surveys for a given user in real time.

Request

GET https://api.inbrain.ai/supplier-api/v1/surveys

Headers

Header	Description	Required
X-InBrain-Api-Key	Authentication API Key	true

Parameters

Endpoint accepts a range of parameters provided as query parameters on the request link.

Root parameters

Parameter	Description	Required
userId	Unique user identifier	true
ipAddress	IP address of the user	true
language	User language preference. See list of supported languages.	false
deviceTypes	User device type. One of DeviceType values.	false
placementId	Id of placement defined in Publisher dashboard	false

Profiler data parameters

Profiler data parameters represent user answers for given questions used as survey qualifications.
The table below lists the required profiler data parameters for first-time surveys being fetched.

Parameter	Description	Required
gender	User's gender. Possible values: 1 - Male 2 - Female	true
dateOfBirth	Date of birth of the user. Format: yyyy-MM-dd	true

info

Please see the full list of profiler data parameters to get all supported parameters and their value options per language. All not listed profiler data parameters are optional and can be omitted in the request.

Examples

cURL

curl \
--request GET 'https://api.inbrain.ai/supplier-api/v1/surveys?userId=someApiUserId&ipAddress=127.0.0.1&language=en-us&deviceTypes=mobile&placementId=0ddd2bb1-8f2e-4e95-a449-61deeaca37ed&gender=1&dateOfBirth=1980-01-01&zipCodeUs=12340&householdIncome=25' \
--header 'X-InBrain-Api-Key: YOUR_API_KEY_HERE'

C#

using System.Net.Http;
using System.Threading.Tasks;

var requestUrl = "https://api.inbrain.ai/supplier-api/v1/surveys?userId=someApiUserId&ipAddress=127.0.0.1&language=en-us&deviceTypes=mobile&placementId=0ddd2bb1-8f2e-4e95-a449-61deeaca37ed&gender=1&dateOfBirth=1980-01-01&zipCodeUs=12340&householdIncome=25";

using (var httpClient = new HttpClient())
{
    var requestMessage = new HttpRequestMessage(HttpMethod.Get, requestUrl);

    requestMessage.Headers.Add("X-InBrain-Api-Key", "YOUR_API_KEY_HERE");

    var response = await httpClient.SendAsync(requestMessage);

    // process the response
}

Node.js

const https = require("https");

const requestUrl =
  "https://api.inbrain.ai/supplier-api/v1/surveys?userId=someApiUserId&ipAddress=127.0.0.1&language=en-us&deviceTypes=mobile&placementId=0ddd2bb1-8f2e-4e95-a449-61deeaca37ed&gender=1&dateOfBirth=1980-01-01&zipCodeUs=12340&householdIncome=25";
const options = {
  headers: {
    "X-InBrain-Api-Key": "YOUR_API_KEY_HERE",
  },
};

https
  .get(requestUrl, options, (response) => {
    let body = "";
    response.on("data", (chunk) => {
      body += chunk;
    });

    response.on("end", () => {
      const surveysResponse = JSON.parse(body);

      // process the response
    });
  })
  .on("error", (error) => {
    console.error(error);
  });

Response

Response codes

Code	Description	Reason
200	Success
400	Bad Request	Some of the request parameters are missing or invalid
401	Unauthorized	Invaild API Key
403	Forbidden	User geo is unsupported/User reached surveys limit/User banned
429	Too Many Requests	Too many requests in a given amount of time
500	Internal Server Error	Server error occured while processing the request

Success model

Successful response is a JSON array of survey objects with the properties given below.

Property	Type	Description	Required
id	string	Id of the survey	true
link	string	Survey entry link for the user. See Survey entry link section for more details.	true
cpi	decimal	Reward in partner defined currency	true
revenueAmount	decimal	Partner Reward in USD	true
lengthOfInterview	decimal	Length of interview (minutes)	true
conversionRate	integer	Conversion rate (%)	true
conversionThreshold	integer	Survey conversion indicator. See possible values here.	true
rank	integer	inBrain survey rank	true
isProfilerSurvey	boolean	Flag indicating whether the survey represents an inBrain Profiler survey	true
currencySale	boolean	Flag indicating whether Currency Sale multiplier was applied to survey reward	true
multiplier	decimal	Currency Sale multiplier applied to survey reward	true
deviceTypes	DeviceType[]	Allowed device types for survey	true
categoryIds	integer[]	Ids of categories associated with the survey. See possible values here.	true

Error model

Error response is a JSON object with the properties given below.

Property	Type	Description	Required
code	string	API error code	true
description	string	API error description	true
messages	string[]	Error messages providing further error details	false

Examples

Success (200)

[
  {
    "id": "Q2ltdWxh",
    "link": "https://surveys.inbrain.ai/supplier-surveys/Q2ltdWxh?sid=17&userId=someApiUserId&hash=dace7b8f74d5c0deed7bb6d9388114df0ccbfa684924328913677ab496486c95",
    "cpi": 155.0,
    "revenueAmount": 1.3825,
    "lengthOfInterview": 15.0,
    "conversionRate": 33,
    "conversionThreshold": 5,
    "rank": 1,
    "isProfilerSurvey": false,
    "currencySale": false,
    "multiplier": 1.0,
    "deviceTypes": ["mobile", "tablet", "desktop"],
    "categoryIds": [22]
  },
  {
    "id": "W9ltX0Pd",
    "link": "https://surveys.inbrain.ai/supplier-surveys/W9ltX0Pd?sid=17&userId=someApiUserId&hash=3a18d93ae02454fb64e3b8eab3d48a85b1e854465ba32e3e320b8861863ac4cd",
    "cpi": 99.0,
    "revenueAmount": 0.9725,
    "lengthOfInterview": 13.0,
    "conversionRate": 28,
    "conversionThreshold": 5,
    "rank": 2,
    "isProfilerSurvey": false,
    "currencySale": false,
    "multiplier": 1.0,
    "deviceTypes": ["desktop"],
    "categoryIds": [7, 28]
  }
  // ...
]

Bad Request (400)

{
  "code": "C1001",
  "description": "One or more validation errors occurred",
  "messages": [
    "'userId' is required parameter",
    "'ipAddress' is required parameter",
    "'zipCodeUs' parameter has invalid format"
  ]
}

Internal Server Error (500)

{
  "code": "C1148",
  "description": "Fetching of supplier surveys failed"
}

Schema

Enumerations

Enum	Values
DeviceType	mobile, tablet, desktop

Pass User Profile Data

Profiler data parameters represent user answers for given questions used as survey qualifications.
You do not have to pass these, as we will collect this data as needed. If you would like to initially pass data for a user, please see the full list of profiler data parameters to get all supported parameters and their value options per language.

info

All profiler data parameters other than the ones listed as required above are optional and can be omitted in the request.