General idea

With Survey API, you can get surveys for your user by calling the API either from the client side or from your backend. The response will only include surveys the user isn't excluded from. You can use an import to give us a heads-up on the information you have already collected.

Target Group or Use Case: Use this API if you want to display surveys in your design. You only need to think of displaying the survey itself, and we will handle everything else.

Get surveys

By calling the Get Surveys Endpoint you will receive an updated list of available surveys for a specific user.

The endpoint is designed to be called by the client. If you want to call this from your backend, make sure you pass all client_ parameters accordingly (e.g.,client_country). Once you create a user with a specific country, you cannot change the country by simply calling the API with a different client_country.

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",
                "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",
                "id": "a20fdd9d-bf2f-4e49-af4c-0b1ad2d81e0c",
                "language": "de",
                "loi": 10,
                "rating": 5,
                "tags": [],
                "type": "survey",
                "value": "41"
            }
        ]
    }
}

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, simply redirect the user to each survey'sclick_url. From here on, we will worry about the rest. Please make sure to refresh the get survey endpoint after opening a survey. This will generate a new impression id and allows the next opening.

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 pick up the tags and return them to you:

https://example.com?user_id=12345&premium_user=true&26my_id=12345

Skip Surveys (optional)

If you want to offer users to skip surveys returned by the endpoint above, look at the Skip Survey Endpoint.

Importing users

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.

You can download the qualification mapping here: Google Drive

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": [
          {
               "questions": [
                    {
                         "direct_values": [
                              "1"
                         ],
                         "id": "employment_status"
                    }
               ],
               "uid": "test",
               "country": "US",
               "zipcode": "90245",
               "birthdate": "1998-08-23",
               "gender": "FEMALE"
          }
     ]
}

User history

If you like to build a user history in your product, you can receive the latest action for a survey by calling the User History endpoint. It will always return the latest tracked action (opening, leave, screen out, or complete) for a survey. In addition to that, it returns all the stored details about a survey.

Privacy actions

It is very important for us 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 the different privacy requests of your users to all third-party companies you work with.