General Idea

With basic 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, we will handle everything else.

📘

VERIFY YOUR ACCOUNT FOR API USAGE

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

Import User

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 reccomend to ask the basic profilers like Birthdate, Gender, Zip Code and spoken languages on your end!

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"
          }
     ]
}
'

Get Surveys

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

Most importantly, you must decide if you would like to call this endpoint from the client or your backend. If you are going with your backend, please remember that you have to use the client_country and client_ip to tell our backend the required information about the user.

Example Response

{
  "data": {
    "restriction_reason": {
      "not_verified": true,
      "using_vpn": true,
      "banned_until": "2020-05-04T17:01:30.000Z",
      "reason": "string",
      "unsupported_country": "string"
    },
    "surveys": [
      {
        "network_id": 0,
        "id": 0,
        "cpi": "string",
        "loi": 0,
        "remaining": 0,
        "rating": 0,
        "link": "string",
        "missing_questions": 0,
        "details": {
          "category": {
            "name": "string",
            "icon_url": "string",
            "name_internal": "string"
          },
          "network": {
            "name": "string",
            "icon_url": "string"
          }
        }
      }
    ]
  }
}

Leave a Survey

You can optionally pass back a reason if a user leaves a survey. This helps us to improve the ranking of a survey. Simply call Leave Survey with the right reason code.

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.