Skip to main content

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

HeaderDescriptionRequired
X-InBrain-Api-KeyAuthentication API Keytrue

Parameters

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

Root parameters

ParameterDescriptionRequired
userIdUnique user identifiertrue
ipAddressIP address of the usertrue
languageUser language preference. See list of supported languages.false
deviceTypesUser device type. One of DeviceType values.false
placementIdId of placement defined in Publisher dashboardfalse

Examples

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'

Response

Response codes

CodeDescriptionReason
200Success
400Bad RequestSome of the request parameters are missing or invalid
401UnauthorizedInvaild API Key
403ForbiddenUser geo is unsupported/User reached surveys limit/User banned
429Too Many RequestsToo many requests in a given amount of time
500Internal Server ErrorServer error occured while processing the request

Success model

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

PropertyTypeDescriptionRequired
idstringId of the surveytrue
linkstringSurvey entry link for the user. See Survey entry link section for more details.true
cpidecimalReward in partner defined currencytrue
lengthOfInterviewdecimalLength of interview (minutes)true
conversionRateintegerConversion rate (%)true
conversionThresholdintegerSurvey conversion indicator. See possible values here.true
rankintegerinBrain survey ranktrue
isProfilerSurveybooleanFlag indicating whether the survey represents an inBrain Profiler surveytrue
currencySalebooleanFlag indicating whether Currency Sale multiplier was applied to survey rewardtrue
multiplierdecimalCurrency Sale multiplier applied to survey rewardtrue
deviceTypesDeviceType[]Allowed device types for surveytrue
categoryIdsinteger[]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.

PropertyTypeDescriptionRequired
codestringAPI error codetrue
descriptionstringAPI error descriptiontrue
messagesstring[]Error messages providing further error detailsfalse

Examples

[
{
"id": "Q2ltdWxh",
"link": "https://surveys.inbrain.ai/supplier-surveys/Q2ltdWxh?sid=17&userId=someApiUserId&hash=dace7b8f74d5c0deed7bb6d9388114df0ccbfa684924328913677ab496486c95",
"cpi": 155.0,
"lengthOfInterview": 15.0,
"conversionRate": 33,
"conversionThreshold": 5,
"rank": 1,
"isProfilerSurvey": false,
"currencySale": false,
"multiplier": 1.00,
"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,
"lengthOfInterview": 13.0,
"conversionRate": 28,
"conversionThreshold": 5,
"rank": 2,
"isProfilerSurvey": false,
"currencySale": false,
"multiplier": 1.00,
"deviceTypes": [
"desktop"
],
"categoryIds": [
7,
28
]
},
// ...
]

Schema

Enumerations

EnumValues
DeviceTypemobile, 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.