Back to Top

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:

  • GET /client/actions
  • POST /client/networks/{networkId}/questions/{questionId}
  • DELETE /client/user

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 completness 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.

This is the documentation for version 1.0.46 of the API. Last update on Aug 11, 2022.

Base URL
https://api.bitlabs.ai/v1

Header api token (http_api_key)

ApiToken of your BitLabs app.

Query api token (http_api_key)

ApiToken of your BitLabs app.

Header s2s token (http_api_key)

S2S (server to server) token of your BitLabs app.


Get Actions

GET /client/actions

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.

Query parameters
  • platform Required / string

    Platform/Device type of the user

    Values are MOBILE, TABLET, or WEB.

  • os string

    Operating System of the user

    Values are ANDROID, IOS, or DESKTOP.

  • sdk string

    SDK the user is using

    Values are CUSTOM, IFRAME, TAB, NATIVE, or UNITY.

  • optional fingerprint for survey filtering

  • client_country string(ISO 3166-1 alpha-2)

    Allows overriding the country that is used for this request. This feature must be enabled by your account manager!

  • client_ip string

    Allows overriding the ip that is used for this request. This feature must be enabled by your account manager!

Responses
GET /client/actions
curl \
 -X GET https://api.bitlabs.ai/v1/client/actions?platform=MOBILE&token=api_token_value \
 -H "X-Api-Token: $API_KEY"
Response example (200)
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}

Check surveys

GET /client/check

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.

Query parameters
  • platform Required / string

    Platform/Device type of the user

    Values are MOBILE, TABLET, or WEB.

  • os string

    Operating System of the user

    Values are ANDROID, IOS, or DESKTOP.

  • sdk string

    SDK the user is using

    Values are CUSTOM, IFRAME, TAB, NATIVE, or UNITY.

  • optional fingerprint for survey filtering

Responses
GET /client/check
curl \
 -X GET https://api.bitlabs.ai/v1/client/check?platform=MOBILE&token=api_token_value \
 -H "X-Api-Token: $API_KEY"
Response example (200)
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}
Responses
GET /client/offers
curl \
 -X GET https://api.bitlabs.ai/v1/client/offers?token=api_token_value \
 -H "X-Api-Token: $API_KEY"
Response example (200)
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}

Validate zipcode

GET /client/zipcodes/{zipcode}/valid
Path parameters
  • zipcode Required / string

    A path-encoded zipcode. We validate it against rules for the country the request is coming from.

Responses
GET /client/zipcodes/{zipcode}/valid
curl \
 -X GET https://api.bitlabs.ai/v1/client/zipcodes/{zipcode}/valid
Response example (200)
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}
Response example (406)
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Get network privacy policy

GET /client/networks/{networkId}/privacy
Path parameters
Responses
  • 307

    Redirect

GET /client/networks/{networkId}/privacy
curl \
 -X GET https://api.bitlabs.ai/v1/client/networks/{networkId}/privacy

Get QuestionDeprecated

GET /client/networks/{networkId}/questions/{questionId}
Path parameters
Query parameters
  • country Required / string(ISO 3166-1 alpha-2)

    country of the survey

  • language Required / string(ISO 639-1)

    language of the survey

Responses
GET /client/networks/{networkId}/questions/{questionId}
curl \
 -X GET https://api.bitlabs.ai/v1/client/networks/{networkId}/questions/{questionId}?country=US&language=en&token=api_token_value \
 -H "X-Api-Token: $API_KEY"
Response example (200)
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}
Response example (406)
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Set question answer

POST /client/networks/{networkId}/questions/{questionId}

This endpoint store the answer for a question in the requesting user's profile. It also performs validation on
the input data:

  • at least one answer value has to be given
  • only MULTI questions support multiple answer values
  • all answers value must be strings, regardless of their value

Some 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.

Path parameters
Body Required
Responses
POST /client/networks/{networkId}/questions/{questionId}
curl \
 -X POST https://api.bitlabs.ai/v1/client/networks/{networkId}/questions/{questionId}?token=api_token_value \
 -H "X-Api-Token: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"answers":["string"]}'
Request example
{
  "answers": [
    "string"
  ]
}
Response example (200)
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}
Response example (406)
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Skip question

POST /client/networks/{networkId}/questions/{questionId}/skip

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.

Path parameters
Responses
POST /client/networks/{networkId}/questions/{questionId}/skip
curl \
 -X POST https://api.bitlabs.ai/v1/client/networks/{networkId}/questions/{questionId}/skip?token=api_token_value \
 -H "X-Api-Token: $API_KEY"
Response example (200)
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}
Response example (406)
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Skip survey

POST /client/networks/{networkId}/surveys/{surveyId}/skip
Path parameters
Responses
POST /client/networks/{networkId}/surveys/{surveyId}/skip
curl \
 -X POST https://api.bitlabs.ai/v1/client/networks/{networkId}/surveys/{surveyId}/skip?token=api_token_value \
 -H "X-Api-Token: $API_KEY"
Response example (200)
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}
Response example (406)
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Check Survey

GET /client/networks/{networkId}/surveys/{surveyId}/check
Path parameters
Query parameters
  • platform Required / string

    Platform/Device type of the user

    Values are MOBILE, TABLET, or WEB.

  • os string

    Operating System of the user

    Values are ANDROID, IOS, or DESKTOP.

  • sdk string

    SDK the user is using

    Values are CUSTOM, IFRAME, TAB, NATIVE, or UNITY.

  • optional fingerprint for survey filtering

  • sc_token string

    optional token for survey deduplication

Responses
GET /client/networks/{networkId}/surveys/{surveyId}/check
curl \
 -X GET https://api.bitlabs.ai/v1/client/networks/{networkId}/surveys/{surveyId}/check?platform=MOBILE&token=api_token_value \
 -H "X-Api-Token: $API_KEY"
Response example (200)
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}
Response example (406)
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Open survey

GET /client/networks/{networkId}/surveys/{surveyId}/open
Path parameters
Query parameters
  • platform Required / string

    Platform/Device type of the user

    Values are MOBILE, TABLET, or WEB.

  • os string

    Operating System of the user

    Values are ANDROID, IOS, or DESKTOP.

  • sdk string

    SDK the user is using

    Values are CUSTOM, IFRAME, TAB, NATIVE, or UNITY.

  • rating Required / integer

    rating of the survey when the user opened it

  • cr Required / integer

    estimated conversion rate of the survey

  • loi Required / integer

    estimated length of the survey

  • cpi Required / string

    revenue in dollar for this survey

  • stats string(date-time)

    optional internal debugging timestamp

  • test_group integer

    optional test group id

  • tags string(URL-encoded query)

    optional set of custom tags

  • data string(URL-encoded query)

    optional set of internal information

  • maid string

    optional mobile advertising id (MAID)

  • hash Required / string

    url hash (for security reasons)

Responses
GET /client/networks/{networkId}/surveys/{surveyId}/open
curl \
 -X GET https://api.bitlabs.ai/v1/client/networks/{networkId}/surveys/{surveyId}/open?platform=MOBILE&rating=42&cr=42&loi=42&cpi=string&hash=string&token=api_token_value \
 -H "X-Api-Token: $API_KEY"
Response example (406)
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Continue survey

POST /client/networks/{networkId}/surveys/{surveyId}/continue/{txId}
Path parameters
Body Required
Responses
POST /client/networks/{networkId}/surveys/{surveyId}/continue/{txId}
curl \
 -X POST https://api.bitlabs.ai/v1/client/networks/{networkId}/surveys/{surveyId}/continue/{txId}?token=api_token_value \
 -H "X-Api-Token: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"sc":{"search_token":"string","activity_token":"string","review":{"token":"string","q_id":42,"text":"string","c_text":"string","t_page_load":"string","t_text_typed":"string","t_submit":"string"}},"cid":{"token":"string","request_id":"string","os":"string","browser":"string","platform":"string","device_id":"string","hardware_name":"string","hardware_model":"string","hardware_vendor":"string","markers":{"is_event_unique":true,"is_sub_event_unique":true,"is_known_user_agent":true,"is_known_browser":true,"is_obsolete_browser":true,"is_known_os":true,"is_obsolete_os":true,"is_known_device_type":true,"is_known_domain":true,"is_bot":true,"is_blacklisted":true,"is_tampered":true,"is_anonymous":true,"is_resist":true,"is_velocity":true,"is_oscillating":true,"is_lang":true,"is_geo_lang":true,"is_geo_os_lang":true,"is_geo_tz":true,"is_geo_country":true,"is_geo_postal":true,"is_geo_off_hrs":true,"invalid_count":42,"score":42,"anonymous_reason":[42],"tampered_reason":[42],"postal_reason":[42]}}}'
Request example
{
  "sc": {
    "search_token": "string",
    "activity_token": "string",
    "review": {
      "token": "string",
      "q_id": 42,
      "text": "string",
      "c_text": "string",
      "t_page_load": "string",
      "t_text_typed": "string",
      "t_submit": "string"
    }
  },
  "cid": {
    "token": "string",
    "request_id": "string",
    "os": "string",
    "browser": "string",
    "platform": "string",
    "device_id": "string",
    "hardware_name": "string",
    "hardware_model": "string",
    "hardware_vendor": "string",
    "markers": {
      "is_event_unique": true,
      "is_sub_event_unique": true,
      "is_known_user_agent": true,
      "is_known_browser": true,
      "is_obsolete_browser": true,
      "is_known_os": true,
      "is_obsolete_os": true,
      "is_known_device_type": true,
      "is_known_domain": true,
      "is_bot": true,
      "is_blacklisted": true,
      "is_tampered": true,
      "is_anonymous": true,
      "is_resist": true,
      "is_velocity": true,
      "is_oscillating": true,
      "is_lang": true,
      "is_geo_lang": true,
      "is_geo_os_lang": true,
      "is_geo_tz": true,
      "is_geo_country": true,
      "is_geo_postal": true,
      "is_geo_off_hrs": true,
      "invalid_count": 42,
      "score": 42,
      "anonymous_reason": [
        42
      ],
      "tampered_reason": [
        42
      ],
      "postal_reason": [
        42
      ]
    }
  }
}
Response example (200)
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}

Leave survey

POST /client/networks/{networkId}/surveys/{surveyId}/leave

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.

Path parameters
Body Required
  • reason Required / string

    Values are OTHER, TECHNICAL, SENSITIVE, TOO_LONG, or UNINTERESTING.

Responses
POST /client/networks/{networkId}/surveys/{surveyId}/leave
curl \
 -X POST https://api.bitlabs.ai/v1/client/networks/{networkId}/surveys/{surveyId}/leave?token=api_token_value \
 -H "X-Api-Token: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"reason":"OTHER"}'
Request example
{
  "reason": "OTHER"
}
Response example (200)
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}
Response example (406)
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Open offer

GET /client/offers/{offerId}/open
Path parameters
  • offerId Required / integer(int64)
Query parameters
  • maid string

    optional mobile advertising id (MAID)

  • tags string(URL-encoded query)

    optional set of custom tags

Responses
GET /client/offers/{offerId}/open
curl \
 -X GET https://api.bitlabs.ai/v1/client/offers/{offerId}/open?token=api_token_value \
 -H "X-Api-Token: $API_KEY"
Response example (406)
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Get user history

GET /client/user/history

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.

Responses
GET /client/user/history
curl \
 -X GET https://api.bitlabs.ai/v1/client/user/history?token=api_token_value \
 -H "X-Api-Token: $API_KEY"
Response example (200)
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}
Response example (406)
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Get user data

GET /client/user/data

Returns GDPR user data of the requesting user in a JSON format.

Responses
GET /client/user/data
curl \
 -X GET https://api.bitlabs.ai/v1/client/user/data?token=api_token_value \
 -H "X-Api-Token: $API_KEY"
Response example (200)
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}
Response example (406)
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Get user data (as page)

GET /client/user/data/web

Returns the requesting user's data as HTML to be displayed in the browser.

Responses
GET /client/user/data/web
curl \
 -X GET https://api.bitlabs.ai/v1/client/user/data/web?token=api_token_value \
 -H "X-Api-Token: $API_KEY"
Response example (406)
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Get user

GET /client/user

Returns information and identifier of the requesting user

Responses
GET /client/user
curl \
 -X GET https://api.bitlabs.ai/v1/client/user?token=api_token_value \
 -H "X-Api-Token: $API_KEY"
Response example (200)
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}
Response example (406)
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Delete userDeprecated

DELETE /client/user

Deletes the requesting user's data. This operation cannot be un-done!

Responses
DELETE /client/user
curl \
 -X DELETE https://api.bitlabs.ai/v1/client/user?token=api_token_value \
 -H "X-Api-Token: $API_KEY"
Response example (200)
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}
Response example (406)
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}
Responses
GET /client/settings
curl \
 -X GET https://api.bitlabs.ai/v1/client/settings?token=api_token_value \
 -H "X-Api-Token: $API_KEY"
Response example (200)
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}
Response example (406)
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}
Query parameters
  • color_scheme string

    optional paremeter for setting color scheme of application (if appropriate visual object available)

    Values are LIGHT or DARK.

Responses
GET /client/settings/v2
curl \
 -X GET https://api.bitlabs.ai/v1/client/settings/v2?token=api_token_value \
 -H "X-Api-Token: $API_KEY"
Response example (200)
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}
Response example (406)
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Responses
GET /publishers/offers
curl \
 -X GET https://api.bitlabs.ai/v1/publishers/offers?token=api_token_value \
 -H "X-Api-Token: $API_KEY"
Response example (200)
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}

Import Users

POST /publishers/users

Bulk imports given user accounts. This feature must be enabled by your account manager!

Body Required
Responses
POST /publishers/users
curl \
 -X POST https://api.bitlabs.ai/v1/publishers/users?token=api_token_value \
 -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","direct_values":["string"]}]}]}'
Request example
{
  "users": [
    {
      "uid": "your_unique_id",
      "country": "DE",
      "languages": [
        "de,en"
      ],
      "zipcode": "00000",
      "birthdate": "1999-01-01",
      "gender": "MALE",
      "questions": [
        {
          "id": "string",
          "direct_values": [
            "string"
          ]
        }
      ]
    }
  ]
}
Response example (200)
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}

Delete user

DELETE /publishers/users/{userId}

Delete the user account and all associated data for the given id. This operation cannot be un-done!

Path parameters
Responses
  • 200

    OK

  • 404

    User not found

DELETE /publishers/users/{userId}
curl \
 -X DELETE https://api.bitlabs.ai/v1/publishers/users/{userId} \
 -H "X-S2S-Token: $API_KEY"