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.

📘

VERIFY YOUR ACCOUNT FOR SERVER API USAGE

To use our API from a backend, please introduce yourself in a quick email to [email protected], our partnerships team will verify your account, and you are ready to go!

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, it can happen that the response contains 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

📘

VERIFY YOUR ACCOUNT FOR THE USER IMPORT

To import users, please introduce yourself in a quick email to [email protected], our partnerships team will verify your account, and you are ready to go!

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.

Migrating from legacy user-based API

If you are migrating from the /v1/surveys to /v2/surveys, the following differences apply:

• We no longer expose a numeric network_id and id for each survey. There is now a new unique id string (example: b722f121-484b-4182-832c-849fa5e86cfc) identifying a survey.
• We no longer expose remaining or missing_questions to all publishers.
• The details object has been removed. Instead, there is a category object now.
• link has been renamed to click_url but follows the same logic as before.
• If you used any custom parameters in the past, please pass them to the tags field into the get Survey endpoint or append them with tagsto the entry URL.
• We introduced impressions, so please make sure to refresh the get surveys endpoint after each click to generate a new impression. We are not allowing multiple clicks on the same impression.