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 |
Examples
- cURL
- C#
- Node.js
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'
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
}
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 |
lengthOfInterview | decimal | Length of interview (minutes) | true |
conversionRate | integer | Conversion rate (%) | true |
rank | integer | inBrain survey rank | true |
deviceTypes | DeviceType[] | Allowed device types for survey | 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)
- Bad Request (400)
- Internal Server Error (500)
[
{
"id": "Q2ltdWxh",
"link": "https://surveys.inbrain.ai/supplier-surveys/Q2ltdWxh?sid=17&userId=someApiUserId&hash=dace7b8f74d5c0deed7bb6d9388114df0ccbfa684924328913677ab496486c95",
"cpi": 155.0,
"lengthOfInterview": 15.0,
"conversionRate": 33,
"rank": 1,
"deviceTypes": [
"mobile",
"tablet",
"desktop"
]
},
{
"id": "W9ltX0Pd",
"link": "https://surveys.inbrain.ai/supplier-surveys/W9ltX0Pd?sid=17&userId=someApiUserId&hash=3a18d93ae02454fb64e3b8eab3d48a85b1e854465ba32e3e320b8861863ac4cd",
"cpi": 99.0,
"lengthOfInterview": 13.0,
"conversionRate": 28,
"rank": 2,
"deviceTypes": [
"desktop"
]
},
// ...
]
{
"code": "C1001",
"description": "One or more validation errors occurred",
"messages": [
"'userId' is required parameter",
"'ipAddress' is required parameter",
"'zipCodeUs' parameter has invalid format"
]
}
{
"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.
All profiler data parameters other than the ones listed as required above are optional and can be omitted in the request.