Survey API
Survey API Overview
The Survey API allows you to retrieve surveys for individual users by making calls from either the client side or your backend. Responses are tailored, returning only the surveys for which the user is eligible. You can also use an import to share any previously collected information with us.
As a user-based API, the Survey API requires a separate call each time a user wishes to view available surveys. Ensure that all necessary information is provided to accurately identify the user on our side.
Target Audience / Use Case This API is intended for scenarios where you want to display surveys within your application or design. Your responsibility is limited to presenting the surveys — all other processing is handled by the API.
Get Surveys Endpoint
By calling the Get Surveys Endpoint, you can retrieve an up-to-date list of available surveys for a specific user.
This endpoint is primarily designed for client-side calls. If you intend to call it from your backend, ensure that all client_ parameters (e.g., client_ip) are provided. Backend usage requires prior activation — please contact our team to enable this functionality.
Example Response
{
"data": {
"surveys": [
{
"category": {
"icon_name": "shapes",
"icon_url": "https://static.bitlabs.ai/categories/other.svg",
"name": "Allgemeines",
"name_internal": "Other"
},
"click_url": "https://api.bitlabs.ai/v2/client/clicks?i=7e0ae30e-96af-4843-b447-e86a05688691&s=e59b6d24-c5c0-4b01-9bb0-1a705dd6b59c",
"country": "DE",
"cpi": "1.72",
"cr": 0.42,
"id": "b722f121-484b-4182-832c-849fa5e86cfc",
"language": "de",
"loi": 7,
"rating": 5,
"tags": [],
"type": "survey",
"value": "172"
},
{
"category": {
"icon_name": "shapes",
"icon_url": "https://static.bitlabs.ai/categories/other.svg",
"name": "Allgemeines",
"name_internal": "Other"
},
"click_url": "https://api.bitlabs.ai/v2/client/clicks?i=05fbe72e-5e0a-4ddc-857b-50710b6183dd&s=e59b6d24-c5c0-4b01-9bb0-1a705dd6b59c",
"country": "DE",
"cpi": "0.41",
"cr": 0.29,
"id": "a20fdd9d-bf2f-4e49-af4c-0b1ad2d81e0c",
"language": "de",
"loi": 10,
"rating": 5,
"tags": [],
"type": "survey",
"value": "41"
}
]
},
"status": "success",
"trace_id": "72b27669a61d9888"
}User restrictions
In edge cases, the response may contain a restriction_reason that indicates why we cannot find any surveys for the given user.
Opening surveys
To open a survey, redirect the user to the survey’s click_url. From that point onward, all further processing is handled on our side.
Important: Always refresh the Get Surveys endpoint after opening a survey. This generates a new impression ID and ensures that subsequent survey openings function correctly.
Passing Additional Parameters
If you want to pass additional parameters into the BitLabs system, you can append tags to the click_url or directly into the get surveys request. We will append the passed parameters to the redirects and callbacks as you send them in.
Please encode the parameters before you send them into the tags like this:
&tags=premium_user%3Dtrue%26my_id%3D12345
The callbacks/redirects will process the tags and return them to you in the callbacks:
https://example.com?user_id=12345&premium_user=true&26my_id=12345
If you get traffic from different sub-sources, please make sure to append a tag with the name sub_1 or sub_2.
Importing user data
The Import User Endpoint allows you to import pre-collected information about your users. This endpoint can also update existing profiles based on the updated information you send. Please always send a fully updated profile, not only parts of it.
We highly recommend importing the Birthdate, Gender, and Zip code for new users to avoid duplicate collection.
Example Request
curl --request POST \
--url https://api.bitlabs.ai/v1/publishers/users \
--header 'X-Api-Token: test' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"users": [
{
"uid": "test",
"country": "US",
"zipcode": "90245",
"birthdate": "1998-08-23",
"gender": "FEMALE"
}
]
}User history
If you want to maintain a user history within your product, you can retrieve the latest action for a survey by calling the User History endpoint. This endpoint returns the most recent tracked action — such as opening, leaving, screening out, or completing a survey — along with all stored details associated with the survey.
Privacy actions
We need to be fully transparent about the data we collect. That's why we provide two endpoints to give you control over user data. With these endpoints, you can process data requests (User Data endpoint) and data deletion requests (Delete User Data endpoint).
Please note that you are required by law to forward all privacy requests from your users to all third-party companies with which you work.
Qualification Flow for the Survey API (optional)
The Survey API supports an optional qualification flow that allows you to handle survey qualifications within your own UI. This can help reduce the number of qualifications presented after a user clicks on a survey while giving you full control over the qualification experience.
This flow is not mandatory. Publishers can implement it to display their own UI for qualifications instead of relying on BitLabs’ default UI.
The Survey API must be fully integrated before implementing the qualification flow. This section serves as an appendix to the Survey API documentation.
Starting the Qualification Flow
To retrieve the open questions for a specific survey:
1. Create Click
Make a POST request to the click_url obtained from the Get Surveys Endpoint using the Create Click endpoint.
Example Response
{
"data": {
"id": "edf06866-e477-40a6-8287-ff987863e2e9"
}
}2. Get Next Question
Use the returned click_id to make a GET request to the Get Click endpoint. This retrieves the next question to render for the user.
Example Response
{
"data": {
"answer_question": {
"question": {
"id": "e9bdff4e7d",
"language": "en",
"type": "TEXT",
"localized_text": "What is your favorite color?",
"answers": [
{
"code": "1",
"localized_text": "Red"
}
],
"can_skip": true,
"is_duplicate": false,
"example": null,
"validation_info": {
"min": 1,
"max": 1,
"regex": "^.{1,30}$"
}
}
},
"redirect": {
"url": "https://web.bitlabs.ai"
},
"answered_questions": 0,
"required_questions": 0
},
"status": "success",
"trace_id": "72b27669a61d9888"
}3. Submit Answers
After the user completes a question, POST the answers to the Update Click endpoint. Repeat for each subsequent question. Once all questions are answered, redirect the user to the final URL.
To view all available question types, refer to the Get Click documentation.
Initial Rewarded Profiler (Starting Bonus Survey)
The “Initial Rewarded Profiler” survey for new users follows the same answer structure as qualifications. It is the only survey returned to new users and has the type start_bonus. Learn more about the Initial Rewarded Profile here.
Updated 2 days ago