Header api token (http_api_key)
ApiToken of your BitLabs app.
BitLabs' public API to be integrated by our own products as well as publishers who desire maximum customization.
For 99% of publishers, the following endpoints are the only ones that must be implemented. Everything is optional and
only required if more advanced behaviour is desired:
NOTE: opening a survey should only be done by using the link
property from surveys returned by GET /client/actions
. Manually
creating these links and calling the GET /client/networks/{networkId}/surveys/{surveyId}/open
endpoint will lead to issues.
The endpoint is only documented for completeness and to understand its behaviour. Do NOT use it manually!
All endpoints optionally accepts a X-Mparticle-Session-Id
header to sync a client mparticle session id for the requesting
user with the backend. Additionally, X-Mparticle-Platform
(one of: android, ios, web) can be used for proper platform
targeting.
This is the documentation for version 1.0.72
of the API. Last update on Mar 17, 2023.
https://api.bitlabs.ai/v1
The API accepts 5 different authentication methods:
ApiToken of your BitLabs app.
ApiToken of your BitLabs app.
S2S (server to server) token of your BitLabs app.
Unique identifier of the user you are sending to BitLabs. These are passed back to you in callbacks to allow
you to identify your users. If possible, use UUIDs, numerical IDs or ASCII strings to avoid formatting issues.
Do NOT use JWT or other sensitive tokens to identify your users. We only support up to 65 character long ids.
Unique identifier of the user you are sending to BitLabs. These are passed back to you in callbacks to allow
you to identify your users. If possible, use UUIDs, numerical IDs or ASCII strings to avoid formatting issues.
Do NOT use JWT or other sensitive tokens to identify your users. We only support up to 65 character long ids.
Get Actions is the main endpoint that returns the next actions a user can perform. This can be a list of
surveys the user can open or qualifications (i.e. questions) the user still has to answer before we can
return more surveys.
If surveys are returned, they are ordered by what we think is the best value for the user. To join a survey,
use the link
property of this reponse and open it in a browser. The user will be redirected from there.
When a survey is completed or a screenout happend, the user is redirected to the sites you specified on
your app's dashboard.
If a qualification is returned the user can answer it to potentially get more surveys. This endpoint returns
all information to display the question to the user. To answer it, look at POST /client/networks/{networkId}/questions/{questionId}
.
After answering a question, call the Actions endpoint again to get updated results.
Platform/Device type of the user
Values are MOBILE
, TABLET
, or WEB
.
Operating System of the user
Values are ANDROID
, IOS
, or DESKTOP
.
SDK the user is using
Values are CUSTOM
, IFRAME
, TAB
, NATIVE
, or UNITY
.
optional fingerprint for survey filtering
Allows overriding the country that is used for this request. This feature must be enabled by your account manager!
Allows overriding the ip that is used for this request. This feature must be enabled by your account manager!
Allows overriding the useragent that is used for this request. This feature must be enabled by your account manager!
Allows specifying a display name for the requesting user which is used for features such as the leaderboard. Nothing happens if it is not set.
For internal usage only. Triggers user friendly api mode.
curl \
-X GET https://api.bitlabs.ai/v1/client/actions?platform=MOBILE \
-H "X-Api-Token: $API_KEY" \
-H "X-User-Id: $API_KEY"
{
"data": {
"is_new_user": true,
"start_bonus": {
"reward": "string"
},
"restriction_reason": {
"not_verified": true,
"using_vpn": true,
"banned_until": "2020-05-04 17:01:30 UTC",
"reason": "string",
"unsupported_country": "string"
},
"surveys": [
{
"network_id": 42,
"id": 42,
"country": "string",
"language": "string",
"cpi": "string",
"value": "string",
"loi": 42.0,
"remaining": 42,
"details": {
"category": {
"name": "string",
"icon_url": "string",
"name_internal": "string"
},
"network": {
"name": "string",
"icon_url": "string"
},
"difficulty": "EASY"
},
"rating": 42,
"tags": [
"recontact"
],
"test_group_id": 42,
"link": "string",
"score": 42.0,
"sequence": 42,
"missing_questions": 42,
"next_missing_question": {
"network_id": 42,
"id": "string",
"country": "US",
"language": "en",
"type": "TEXT",
"localized_text": "string",
"answers": [
{
"code": "string",
"localized_text": "string"
}
],
"can_skip": true,
"is_duplicate": true
}
}
],
"qualification": {
"network_id": 42,
"question_id": "string",
"country": "US",
"language": "en",
"question": {
"network_id": 42,
"id": "string",
"country": "US",
"language": "en",
"type": "TEXT",
"localized_text": "string",
"answers": [
{
"code": "string",
"localized_text": "string"
}
],
"can_skip": true,
"is_duplicate": true
},
"is_standard_profile": true,
"is_start_bonus": true,
"score": 42.0,
"sequence": 42
}
}
}
The endpoint is similar to GET /client/actions
as it returns if the user can perform an action (either opening
a survey or answering qualifications). It is faster than the actual Actions endpoint because it leaves out
additional information fetching. If you want to perform background checks if surveys are available, this is the
best option.
Platform/Device type of the user
Values are MOBILE
, TABLET
, or WEB
.
Operating System of the user
Values are ANDROID
, IOS
, or DESKTOP
.
SDK the user is using
Values are CUSTOM
, IFRAME
, TAB
, NATIVE
, or UNITY
.
optional fingerprint for survey filtering
curl \
-X GET https://api.bitlabs.ai/v1/client/check?platform=MOBILE \
-H "X-Api-Token: $API_KEY" \
-H "X-User-Id: $API_KEY"
{
"data": {
"has_surveys": true
}
}
Returns a list of surveys the user might be able to open. When redirecting the user to the link of one of the
surveys, they will either be redirected to that survey or face pre-qualification questions to determine if they
fit.
Platform/Device type of the user
Values are MOBILE
, TABLET
, or WEB
.
Operating System of the user
Values are ANDROID
, IOS
, or DESKTOP
.
SDK the user is using
Values are CUSTOM
, IFRAME
, TAB
, NATIVE
, or UNITY
.
Allows overriding the country that is used for this request. This feature must be enabled by your account manager!
Allows overriding the ip that is used for this request. This feature must be enabled by your account manager!
Allows overriding the useragent that is used for this request. This feature must be enabled by your account manager!
Allows specifying a display name for the requesting user which is used for features such as the leaderboard. Nothing happens if it is not set.
curl \
-X GET https://api.bitlabs.ai/v1/client/surveys?platform=MOBILE \
-H "X-Api-Token: $API_KEY" \
-H "X-User-Id: $API_KEY"
{
"data": {
"restriction_reason": {
"not_verified": true,
"using_vpn": true,
"banned_until": "2020-05-04 17:01:30 UTC",
"reason": "string",
"unsupported_country": "string"
},
"surveys": [
{
"network_id": 42,
"id": 42,
"language": "string",
"cpi": "string",
"loi": 42.0,
"remaining": 42,
"rating": 42,
"link": "string",
"missing_questions": 42,
"details": {
"category": {
"name": "string",
"icon_url": "string",
"name_internal": "string"
},
"network": {
"name": "string",
"icon_url": "string"
},
"difficulty": "EASY"
}
}
]
}
}
curl \
-X GET https://api.bitlabs.ai/v1/client/offers \
-H "X-Api-Token: $API_KEY" \
-H "X-User-Id: $API_KEY"
{
"data": {
"offers": [
{
"id": 42,
"title": "string",
"description": "string",
"icon": "string",
"image": "string",
"link": "string",
"is_live": true,
"target_os": [
"all"
],
"tasks": [
{
"id": 42,
"description": "string",
"cpa": "string",
"value": "string",
"is_live": true,
"completed_at": "2022-01-01T12:00:00Z",
"reconciled_at": "2022-01-01T12:00:00Z"
}
],
"score": 42.0,
"opened_at": "2022-01-01T12:00:00Z",
"completed_at": "2022-01-01T12:00:00Z",
"duration": 42.0,
"tags": [
"string"
],
"is_promoted": true,
"support_url": "string"
}
]
}
}
A path-encoded zipcode. We validate it against rules for the country the request is coming from.
curl \
-X GET https://api.bitlabs.ai/v1/client/zipcodes/{zipcode}/valid \
-H "X-Api-Token: $API_KEY" \
-H "X-User-Id: $API_KEY"
{
"data": {
"valid": true
}
}
{
"error": {
"details": {
"http": "406 Not Acceptable",
"msg": "vpn detected"
}
}
}
curl \
-X GET https://api.bitlabs.ai/v1/client/networks/{networkId}/privacy
curl \
-X GET https://api.bitlabs.ai/v1/client/networks/{networkId}/questions/{questionId}?country=US&language=en \
-H "X-Api-Token: $API_KEY" \
-H "X-User-Id: $API_KEY"
{
"data": {
"network_id": 42,
"id": "string",
"country": "US",
"language": "en",
"type": "TEXT",
"localized_text": "string",
"answers": [
{
"code": "string",
"localized_text": "string"
}
],
"can_skip": true,
"is_duplicate": true
}
}
{
"error": {
"details": {
"http": "406 Not Acceptable",
"msg": "vpn detected"
}
}
}
This endpoint store the answer for a question in the requesting user's profile. It also performs validation on
the input data:
MULTI
questions support multiple answer valuesSome questions have selectable answer options. Every option's code property, that is selected by the user,
must be passed as a single answer value in this request.
If a question does not have answer options (for example TEXT
or NUMBER
questions), pass the answer of
the user as a single element into the answer array for the endpoint.
After submitting an answer, you most likely want to call GET /client/actions
again to get updated results.
curl \
-X POST https://api.bitlabs.ai/v1/client/networks/{networkId}/questions/{questionId} \
-H "X-Api-Token: $API_KEY" \
-H "X-User-Id: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"answers":["string"]}'
{
"answers": [
"string"
]
}
{
"data": {},
"error": {
"details": {
"http": "string",
"msg": "string"
}
},
"status": "success",
"trace_id": "1dc6786b10a62ec6"
}
{
"error": {
"details": {
"http": "406 Not Acceptable",
"msg": "vpn detected"
}
}
}
Non standard profile questions (network id != 0) can be skipped if the user wants to. This is a permanent
operation and the user will never be asked the question again. Use this feature with caution as it can
significantly reduce the amount of surveys a user receives when used extensively.
curl \
-X POST https://api.bitlabs.ai/v1/client/networks/{networkId}/questions/{questionId}/skip \
-H "X-Api-Token: $API_KEY" \
-H "X-User-Id: $API_KEY"
{
"data": {},
"error": {
"details": {
"http": "string",
"msg": "string"
}
},
"status": "success",
"trace_id": "1dc6786b10a62ec6"
}
{
"error": {
"details": {
"http": "406 Not Acceptable",
"msg": "vpn detected"
}
}
}
curl \
-X POST https://api.bitlabs.ai/v1/client/networks/{networkId}/surveys/{surveyId}/skip \
-H "X-Api-Token: $API_KEY" \
-H "X-User-Id: $API_KEY"
{
"data": {},
"error": {
"details": {
"http": "string",
"msg": "string"
}
},
"status": "success",
"trace_id": "1dc6786b10a62ec6"
}
{
"error": {
"details": {
"http": "406 Not Acceptable",
"msg": "vpn detected"
}
}
}
Platform/Device type of the user
Values are MOBILE
, TABLET
, or WEB
.
Operating System of the user
Values are ANDROID
, IOS
, or DESKTOP
.
SDK the user is using
Values are CUSTOM
, IFRAME
, TAB
, NATIVE
, or UNITY
.
optional fingerprint for survey filtering
optional token for survey deduplication
curl \
-X GET https://api.bitlabs.ai/v1/client/networks/{networkId}/surveys/{surveyId}/check?platform=MOBILE \
-H "X-Api-Token: $API_KEY" \
-H "X-User-Id: $API_KEY"
{
"data": {
"can_open": true
}
}
{
"error": {
"details": {
"http": "406 Not Acceptable",
"msg": "vpn detected"
}
}
}
Platform/Device type of the user
Values are MOBILE
, TABLET
, or WEB
.
Operating System of the user
Values are ANDROID
, IOS
, or DESKTOP
.
SDK the user is using
Values are CUSTOM
, IFRAME
, TAB
, NATIVE
, or UNITY
.
optional internal debugging timestamp
optional internal debugging timestamp
optional internal debugging timestamp
optional test group id
optional set of internal information
optional mobile advertising id (MAID)
url hash (for security reasons)
curl \
-X GET https://api.bitlabs.ai/v1/client/networks/{networkId}/surveys/{surveyId}/open?platform=MOBILE&rating=42&cr=42.0&loi=42&cpi=string&rr=42.0&hash=string \
-H "X-Api-Token: $API_KEY" \
-H "X-User-Id: $API_KEY"
{
"error": {
"details": {
"http": "406 Not Acceptable",
"msg": "vpn detected"
}
}
}
curl \
-X POST https://api.bitlabs.ai/v1/client/networks/{networkId}/surveys/{surveyId}/continue/{txId} \
-H "X-Api-Token: $API_KEY" \
-H "X-User-Id: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"sc":{"search_token":"string"},"cid":{"token":"string"}}'
{
"sc": {
"search_token": "string"
},
"cid": {
"token": "string"
}
}
{
"data": {
"link": "string"
}
}
Usually, we handle completes and screenouts of users. Nontheless, it may happen that a user wants to leave a
survey before it was terminated. In this case, you can report the leave using this endpoint with a reason given
by the user. This endpoint is optional but we use the feedback in real-time to filter out bad surveys to
improve the overall UX for all users.
curl \
-X POST https://api.bitlabs.ai/v1/client/networks/{networkId}/surveys/{surveyId}/leave \
-H "X-Api-Token: $API_KEY" \
-H "X-User-Id: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"reason":"OTHER"}'
{
"reason": "OTHER"
}
{
"data": {},
"error": {
"details": {
"http": "string",
"msg": "string"
}
},
"status": "success",
"trace_id": "1dc6786b10a62ec6"
}
{
"error": {
"details": {
"http": "406 Not Acceptable",
"msg": "vpn detected"
}
}
}
curl \
-X POST https://api.bitlabs.ai/v1/client/networks/{networkId}/surveys/{surveyId}/rate \
-H "X-Api-Token: $API_KEY" \
-H "X-User-Id: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"stars":42}'
{
"stars": 42
}
{
"data": {},
"error": {
"details": {
"http": "string",
"msg": "string"
}
},
"status": "success",
"trace_id": "1dc6786b10a62ec6"
}
{
"error": {
"details": {
"http": "406 Not Acceptable",
"msg": "vpn detected"
}
}
}
optional mobile advertising id (MAID)
curl \
-X GET https://api.bitlabs.ai/v1/client/offers/{offerId}/open \
-H "X-Api-Token: $API_KEY" \
-H "X-User-Id: $API_KEY"
{
"error": {
"details": {
"http": "406 Not Acceptable",
"msg": "vpn detected"
}
}
}
Get User History returns a sorted list of events where the first element is the most recent. It contains up to
four different types of events: OPEN
, LEAVE
, SCREENOUT
, COMPLETE
.
Events in this response are unique per survey so if a survey was completed, only the complete event is returned
and not the corresponding opening. Only non open events contain a duration property. Only screenout and complete
events contain a user value property.
curl \
-X GET https://api.bitlabs.ai/v1/client/user/history \
-H "X-Api-Token: $API_KEY" \
-H "X-User-Id: $API_KEY"
{
"data": [
{
"type": "OPEN",
"survey_id": 42,
"details": {
"category": {
"name": "string",
"icon_url": "string",
"name_internal": "string"
},
"network": {
"name": "string",
"icon_url": "string"
}
},
"user_value": "string",
"rating": 42,
"created_at": "string",
"duration": "string",
"reconciled": true,
"callback_delay_seconds": 42
}
]
}
{
"error": {
"details": {
"http": "406 Not Acceptable",
"msg": "vpn detected"
}
}
}
curl \
-X GET https://api.bitlabs.ai/v1/client/user \
-H "X-Api-Token: $API_KEY" \
-H "X-User-Id: $API_KEY"
{
"data": {
"app_id": 42,
"uid": "string",
"user_id": 42,
"username": "string"
}
}
{
"error": {
"details": {
"http": "406 Not Acceptable",
"msg": "vpn detected"
}
}
}
curl \
-X GET https://api.bitlabs.ai/v1/client/settings \
-H "X-Api-Token: $API_KEY" \
-H "X-User-Id: $API_KEY"
{
"data": {
"visual": {
"color_dark": "string",
"color_light": "string",
"color_accent": "string"
}
}
}
{
"error": {
"details": {
"http": "406 Not Acceptable",
"msg": "vpn detected"
}
}
}
optional paremeter for setting color scheme of application (if appropriate visual object available)
Values are LIGHT
or DARK
.
curl \
-X GET https://api.bitlabs.ai/v1/client/settings/v2 \
-H "X-Api-Token: $API_KEY" \
-H "X-User-Id: $API_KEY"
{
"data": {
"currency": {
"floor_decimal": true,
"factor": "string",
"symbol": {
"content": "string",
"is_image": true
},
"currency_promotion": 40,
"bonus_percentage": 20
},
"logic": {
"mode": "API",
"privacy_enabled": true,
"skip_question_enabled": true,
"header_navigation_visible": true,
"watermark_visible": true,
"survey_bonus_enabled": true,
"demo_mode_enabled": true,
"survey_opening_target": "OPENING_TARGET_NONE",
"survey_complete_target": "COMPLETE_TARGET_CLOSE_TAB",
"first_qualification": {
"start_bonus": "string",
"show": true
},
"survey_complete_target_url": "string",
"survey_bonus_percentage": 50,
"default_tab": "TAB_SURVEYS",
"enabled_widgets": [
"WIDGET_EARNINGS"
]
},
"visual": {
"element_border_radius": "BORDER_RADIUS_NONE",
"custom_logo_url": "string",
"screenout_reward": "string",
"navigation_color": "string",
"background_color": "string",
"interaction_color": "string",
"survey_icon_color": "string",
"color_rating_threshold": 42,
"offerwall_width": "string",
"hide_reward_value": true,
"show_cross_tab_offers": true
},
"promotion": {
"start_date": "2022-01-01T12:00:00Z",
"end_date": "2022-01-15T12:00:00Z",
"bonus_percentage": 20
},
"offers": {
"enabled": true
},
"publisher": {
"is_key_partner": true
},
"user_friendly_api": {
"enable_offerwall": true,
"screenout_redirect": "string",
"enable_additional_qualifications": true
},
"enable_mparticle_events": true
}
}
{
"error": {
"details": {
"http": "406 Not Acceptable",
"msg": "vpn detected"
}
}
}
curl \
-X GET https://api.bitlabs.ai/v1/client/leaderboard \
-H "X-Api-Token: $API_KEY" \
-H "X-User-Id: $API_KEY"
{
"data": {
"next_reset_at": "2022-01-01T12:00:00Z",
"rewards": [
{
"rank": 42,
"reward_raw": 42.0
}
],
"top_users": [
{
"rank": 42,
"name": "string",
"earnings_raw": 42.0
}
],
"own_user": {
"rank": 42,
"name": "string",
"earnings_raw": 42.0
}
}
}
curl \
-X GET https://api.bitlabs.ai/v1/client/gdpr/files/{filename}/{hash}
Bulk imports given user accounts. This feature must be enabled by your account manager!
If more than one user is sent in a request, that request is treated as a bulk import. Only
one bulk import can be issued at a time. If only one user is set, you can call the endpoint in
parallel.
curl \
-X POST https://api.bitlabs.ai/v1/publishers/users \
-H "X-Api-Token: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"users":[{"uid":"your_unique_id","country":"DE","languages":["de,en"],"zipcode":"00000","birthdate":"1999-01-01","gender":"MALE","questions":[{"id":"string","network_id":42,"direct_values":["string"]}],"username":"string"}]}'
{
"users": [
{
"uid": "your_unique_id",
"country": "DE",
"languages": [
"de,en"
],
"zipcode": "00000",
"birthdate": "1999-01-01",
"gender": "MALE",
"questions": [
{
"id": "string",
"network_id": 42,
"direct_values": [
"string"
]
}
],
"username": "string"
}
]
}
{
"data": {
"success_count": 42,
"errors": [
{
"uid": "string",
"invalid_birthdate": "string",
"invalid_gender": "string",
"invalid_zipcode": "string",
"invalid_question": "string",
"unsupported_languages": true,
"invalid_answer_format": {
"question": "string",
"reason": "string"
}
}
]
}
}
Delete the user account and all associated data for the given id. This operation cannot be un-done!
curl \
-X DELETE https://api.bitlabs.ai/v1/publishers/users/{userId} \
-H "X-S2S-Token: $API_KEY"
{
"data": {
"id": 42
}
}
curl \
-X GET https://api.bitlabs.ai/v1/publishers/users/{userId}/profile \
-H "X-S2S-Token: $API_KEY"
{
"data": {
"country": "string",
"main_language": "string",
"spoken_languages": [
"string"
],
"zipcode": "string",
"birthdate": "1999-01-01",
"gender": "MALE",
"username": "string"
}
}
curl \
-X GET https://api.bitlabs.ai/v1/publishers/users/{userId}/gdpr-requests \
-H "X-S2S-Token: $API_KEY"
{
"data": {
"requests": [
{
"action": "DELETE",
"status": "PENDING",
"created_at": "2022-01-15T12:00:00Z",
"completed_at": "2022-01-15T12:00:00Z",
"link": "string",
"link_valid_until": "2023-05-04T09:42:00+00:00",
"first_accessed_at": "2022-01-15T12:00:00Z"
}
]
}
}
Posts an access user data request for the specific user
curl \
-X POST https://api.bitlabs.ai/v1/publishers/users/{userId}/gdpr-requests \
-H "X-S2S-Token: $API_KEY"
{
"data": {
"id": 42
}
}
curl \
-X GET https://api.bitlabs.ai/v1/publishers/offers \
-H "X-S2S-Token: $API_KEY"
{
"data": {
"offers": [
{
"id": 42,
"title": "string",
"description": "string",
"icon": "string",
"image": "string",
"link": "string",
"is_live": true,
"target_os": [
"all"
],
"tasks": [
{
"id": 42,
"description": "string",
"cpa": "string",
"is_live": true
}
],
"score": 42.0,
"duration": 42.0,
"tags": [
"string"
],
"is_promoted": true,
"country": "string"
}
],
"pagination": {
"offers_per_page": 42,
"offers_total": 42,
"current_page": 42,
"pages_total": 42
}
}
}