BitLabs Client API
1.0.57

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

This is the documentation for version 1.0.57 of the API. Last update on Oct 5, 2022.

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

Authentication

The API accepts 3 different authentication methods:

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.

Client

Get Actions

GET /client/actions
Header api token Query api token

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.

  • sc_fingerprint string

    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!

  • username string

    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.

  • ufm boolean

    For internal usage only. Triggers user friendly api mode.

Responses
  • • 200 object

    OK

    • data object
      • is_new_user Required / boolean

        Is true until the user joins their first survey.

      • start_bonus object
      • restriction_reason object
        • not_verified boolean

          The publisher account that owns this app has not been verified and therefore cannot receive surveys.

        • using_vpn boolean

          The user is using a VPN and cannot access surveys. This is the only endpoint that does not return HTTP 406 in this case.

        • banned_until string(RFC3339)

          It can happen that we ban users temporarily if we deem necessary. The time is in RFC3339 and represents the end of the ban.

        • reason string

          A translated reason for the ban.

        • unsupported_country string

          In case users from a country that we do not offer surveys for are trying to access this endpoint.

      • surveys Required / array[object]
        • network_id Required / integer

          ID of the network. Required in survey specific requests.

        • id Required / integer(int64)

          ID of the survey. Required in survey specific requests. This int is represented as a string because it may become an int64 at some point.

        • country Required / string(ISO 3166-1 alpha-2)
        • language Required / string(ISO 639-1)

          Some surveys may have 'xx' as their language. This is a valid code in our case and indicates that the survey is available for all languages in the given country.

        • cpi Required / string

          CPI of this survey in USD without any formatting applied.

        • value Required / string

          CPI formatted according to your app settings. Can be shown to the user directly.

        • loi Required / number(float)

          Assumed length of the survey in minutes

        • remaining Required / integer

          Amount of users that can still open the survey

        • details Required / object
          • category Required / object
            • name Required / string

              Localized category name

            • icon_url Required / string

              If not empty: url to an icon for the cateogry.

            • name_internal Required / string

              Internal, unlocalized, machine-friendly name of the category

          • network Required / object
            • name Required / string

              Displayable name of the network the survey came from

            • icon_url Required / string

              If not empty: url to an icon for the network.

          • difficulty Required / string Deprecated

            Is the difficulty rating for this survey

            Values are EASY, MEDIUM, or HARD.

        • rating Required / integer

          Difficulty ranking of this survey. 1-5 (1 = hard, 5 = easy)

          Minimum value is 1, maximum value is 5.

        • tags Required / array[string]

          recontact = this is a follow-up survey for specific users that completed a different survey before;
          pii = this survey might collect sensitive information from the user;
          recruitment = an offer recruiting users for external use;

          Values are recontact, pii, or recruitment.

        • test_group_id Required / integer
        • link Required / string

          This link can be used as it to open the survey. All relevant details are inserted on the server.
          For more information or how to manually construct these links take a look at /client/networks/_/surveys/_/open.

        • score Required / number(float)

          The survey's score determined by the ranking algorithm.

        • sequence Required / integer

          The index of this action item in spacial relation to all other action items. Can be used to order surveys and qualifications.

        • missing_questions integer

          The amount of questions that have to be answered before the survey is guaranteed to be openable by the user.
          If the number is larger than zero, next_missing_question contains the next question to ask the user. This
          property might be unpopulated if the feature is not enabled for your app.

        • next_missing_question object
          • network_id Required / integer

            ID of the network. Required in question specific requests. 0 in this case is a valid network_id can be passed to our servers for getting/answering questions.

          • id Required / string

            The id of the question the user has to answer. Note that this is a string not an integer!

          • country Required / string(ISO 3166-1 alpha-2)
          • language Required / string(ISO 639-1)
          • type Required / string

            Values are TEXT, SINGLE, MULTI, NUMBER, or DATE.

          • localized_text Required / string
          • answers Required / array[object]
          • can_skip Required / boolean
          • is_duplicate Required / boolean

            Indicates if a similar question was already asked to the user.

      • qualification object
        • network_id Required / integer

          ID of the network. Required in question specific requests. 0 in this case is a valid network_id can be passed to our servers for getting/answering questions.

        • question_id Required / string

          The id of the question the user has to answer. Note that this is a string not an integer!

        • country Required / string(ISO 3166-1 alpha-2)
        • language Required / string(ISO 639-1)
        • question Required / object
          • network_id Required / integer

            ID of the network. Required in question specific requests. 0 in this case is a valid network_id can be passed to our servers for getting/answering questions.

          • id Required / string

            The id of the question the user has to answer. Note that this is a string not an integer!

          • country Required / string(ISO 3166-1 alpha-2)
          • language Required / string(ISO 639-1)
          • type Required / string

            Values are TEXT, SINGLE, MULTI, NUMBER, or DATE.

          • localized_text Required / string
          • answers Required / array[object]
          • can_skip Required / boolean
          • is_duplicate Required / boolean

            Indicates if a similar question was already asked to the user.

        • is_standard_profile Required / boolean

          Flag is true if this question is asked because of our standard user profile that is asked for every user before we can filter surveys.

        • is_start_bonus Required / boolean

          Flag is true if this is part of the questions being asked until the user receives their start bonus reward.

        • score Required / number(float)

          The score of the question's survey, determined by the ranking algorithm.

        • sequence Required / integer

          The index of this action item in spacial relation to all other action items. Can be used to order surveys and qualifications.

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) 
{
  "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
    }
  }
}

Check surveys

GET /client/check
Header api token Query api token

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.

  • sc_fingerprint string

    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) 
{
  "data": {
    "has_surveys": true
  }
}

Get Surveys

GET /client/surveys
Header api token Query api token

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.

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.

  • 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!

  • username string

    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.

Responses
  • • 200 object

    OK

    • data object
      • restriction_reason object
        • not_verified boolean

          The publisher account that owns this app has not been verified and therefore cannot receive surveys.

        • using_vpn boolean

          The user is using a VPN and cannot access surveys. This is the only endpoint that does not return HTTP 406 in this case.

        • banned_until string(RFC3339)

          It can happen that we ban users temporarily if we deem necessary. The time is in RFC3339 and represents the end of the ban.

        • reason string

          A translated reason for the ban.

        • unsupported_country string

          In case users from a country that we do not offer surveys for are trying to access this endpoint.

      • surveys Required / array[object]
        • network_id Required / integer

          ID of the network. Required in survey specific requests.

        • id Required / integer(int64)

          ID of the survey. Only unique per network_id.

        • cpi Required / string

          CPI of this survey in USD without any formatting applied.

        • loi Required / number(float)

          Assumed length of the survey in minutes

        • remaining Required / integer

          Amount of users that can still open the survey

        • rating Required / integer

          Difficulty ranking of this survey. 1-5 (1 = hard, 5 = easy)

          Minimum value is 1, maximum value is 5.

        • link Required / string
        • missing_questions Required / integer
        • details Required / object
          • category Required / object
            • name Required / string

              Localized category name

            • icon_url Required / string

              If not empty: url to an icon for the cateogry.

            • name_internal Required / string

              Internal, unlocalized, machine-friendly name of the category

          • network Required / object
            • name Required / string

              Displayable name of the network the survey came from

            • icon_url Required / string

              If not empty: url to an icon for the network.

          • difficulty Required / string Deprecated

            Is the difficulty rating for this survey

            Values are EASY, MEDIUM, or HARD.

GET /client/surveys 
curl \
 -X GET https://api.bitlabs.ai/v1/client/surveys?platform=MOBILE&token=api_token_value \
 -H "X-Api-Token: $API_KEY"
Response example (200) 
{
  "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,
        "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"
        }
      }
    ]
  }
}

Get Offers

GET /client/offers
Header api token Query api token
Responses
  • • 200 object

    OK

    • data object
      • offers Required / array[object]
        • id Required / integer(int64)
        • title Required / string
        • description Required / string
        • icon Required / string
        • image string
        • link Required / string
        • is_live Required / boolean
        • target_os Required / array[string]

          Values are all, android, ios, or desktop.

        • tasks Required / array[object]
          • id Required / integer(int64)
          • description Required / string
          • cpa Required / string

            CPI of this survey in USD without any formatting applied.

          • value Required / string

            CPI formatted according to your app settings. Can be shown to the user directly.

          • is_live Required / boolean
          • completed_at string(date-time)
          • reconciled_at string(date-time)
        • score Required / number(float)

          The offers's score determined by the ranking algorithm. Higher is better.

        • opened_at string(date-time)
        • completed_at string(date-time)
        • duration number(float)

          The average duration for offer completion in minutes

        • tags Required / array[string]
        • is_promoted Required / boolean
        • support_url string

          Optional url that redirects to a support page if provided by the offer source.

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) 
{
  "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"
      }
    ]
  }
}

Validate zipcode

GET /client/zipcodes/{zipcode}/valid
Header api token Query api token
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?token=api_token_value \
 -H "X-Api-Token: $API_KEY"
Response example (200) 
{
  "data": {
    "valid": true
  }
}
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}
Header api token Query api token
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
  • • 200 object

    OK

    • data object
      • network_id Required / integer

        ID of the network. Required in question specific requests. 0 in this case is a valid network_id can be passed to our servers for getting/answering questions.

      • id Required / string

        The id of the question the user has to answer. Note that this is a string not an integer!

      • country Required / string(ISO 3166-1 alpha-2)
      • language Required / string(ISO 639-1)
      • type Required / string

        Values are TEXT, SINGLE, MULTI, NUMBER, or DATE.

      • localized_text Required / string
      • answers Required / array[object]
      • can_skip Required / boolean
      • is_duplicate Required / boolean

        Indicates if a similar question was already asked to the user.

  • • 406 object

    VPN detected

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) 
{
  "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
  }
}
Response example (406) 
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Set question answer

POST /client/networks/{networkId}/questions/{questionId}
Header api token Query api token

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) 
{
  "data": {},
  "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
Header api token Query api token

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) 
{
  "data": {},
  "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
Header api token Query api token
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) 
{
  "data": {},
  "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
Header api token Query api token
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.

  • sc_fingerprint string

    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) 
{
  "data": {
    "can_open": true
  }
}
Response example (406) 
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Open survey

GET /client/networks/{networkId}/surveys/{surveyId}/open
Header api token Query api token
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}
Header api token Query api token
Path parameters
Body Required
  • sc object
  • cid object
    • token string

      the CleanID token that is generated on the client side

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"},"cid":{"token":"string"}}'
Request example 
{
  "sc": {
    "search_token": "string"
  },
  "cid": {
    "token": "string"
  }
}
Response example (200) 
{
  "data": {
    "link": "string"
  }
}

Leave survey

POST /client/networks/{networkId}/surveys/{surveyId}/leave
Header api token Query api token

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) 
{
  "data": {},
  "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
Header api token Query api token
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
Header api token Query api token

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
  • • 200 object

    OK

    • data array[object]
      • type Required / string

        Values are OPEN, LEAVE, SCREENOUT, or COMPLETE.

      • survey_id Required / integer(int64)
      • details Required / object
        • category Required / object
          • name Required / string

            Localized category name

          • icon_url Required / string

            If not empty: url to an icon for the cateogry.

          • name_internal Required / string

            Internal, unlocalized, machine-friendly name of the category

        • network Required / object
          • name Required / string

            Displayable name of the network the survey came from

          • icon_url Required / string

            If not empty: url to an icon for the network.

      • user_value Required / string
      • rating Required / integer
      • created_at Required / string
      • duration Required / string
      • reconciled Required / boolean
      • callback_delay_seconds integer

        Optional delay in seconds after which the callback will be sent, if not reconciled until that point.

  • • 406 object

    VPN detected

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) 
{
  "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
    }
  ]
}
Response example (406) 
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Get user

GET /client/user
Header api token Query api token

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) 
{
  "data": {
    "app_id": 42,
    "uid": "string",
    "user_id": 42
  }
}
Response example (406) 
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Get app settingsDeprecated

GET /client/settings
Header api token Query api token
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) 
{
  "data": {
    "visual": {
      "color_dark": "string",
      "color_light": "string",
      "color_accent": "string"
    }
  }
}
Response example (406) 
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Get app settings v2

GET /client/settings/v2
Header api token Query api token
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) 
{
  "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"
    }
  }
}
Response example (406) 
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Get app's leaderboard, if enabled

GET /client/leaderboard
Header api token Query api token
Responses
GET /client/leaderboard 
curl \
 -X GET https://api.bitlabs.ai/v1/client/leaderboard?token=api_token_value \
 -H "X-Api-Token: $API_KEY"
Response example (200) 
{
  "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
    }
  }
}

Publishers

Import Users

POST /publishers/users
Header api token Query api token

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

Body Required
  • users Required / array[object]
    • uid Required / string
    • country Required / string
    • languages Required / array[string]
    • zipcode Required / string
    • birthdate Required / string
    • gender Required / string

      Values are MALE, FEMALE, or OTHER.

    • questions Required / array[object]
    • username string

      Allows specifying a display name for the requesting user which is used for features such as the leaderboard.

Responses
  • • 200 object

    OK

    • data object
      • success_count Required / integer

        Number of successfully imported users from the request

      • errors Required / array[object]

        Contains all users that could not be imported due to an error

        • uid Required / string
        • invalid_birthdate string

          If this field is not null, the birthdate cannot be validated

        • invalid_gender string

          If this field is not null, the gender cannot be validated

        • invalid_zipcode string

          If this field is not null, the zipcode cannot be validated

        • invalid_question string

          If this field is not null, the question was not found or there is no mapping for the given answer values

        • unsupported_languages boolean

          If this field is true, the user was ignored because it did not have any supported languages.

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"]}],"username":"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"
          ]
        }
      ],
      "username": "string"
    }
  ]
}
Response example (200) 
{
  "data": {
    "success_count": 42,
    "errors": [
      {
        "uid": "string",
        "invalid_birthdate": "string",
        "invalid_gender": "string",
        "invalid_zipcode": "string",
        "invalid_question": "string",
        "unsupported_languages": true
      }
    ]
  }
}

Delete user

DELETE /publishers/users/{userId}
Header s2s token

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

Path parameters
Responses
  • • 202 object

    Accepted

    • data object
      • id Required / integer

        the id assigned to the given request

  • • 404

    User not found

  • • 409

    Delete Request already exist

DELETE /publishers/users/{userId} 
curl \
 -X DELETE https://api.bitlabs.ai/v1/publishers/users/{userId} \
 -H "X-S2S-Token: $API_KEY"
Response example (202) 
{
  "data": {
    "id": 42
  }
}

Get all gdpr requests for the specific user

GET /publishers/users/{userId}/gdpr-requests
Header s2s token
Path parameters
Responses
GET /publishers/users/{userId}/gdpr-requests 
curl \
 -X GET https://api.bitlabs.ai/v1/publishers/users/{userId}/gdpr-requests \
 -H "X-S2S-Token: $API_KEY"
Response example (200) 
{
  "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": "2022-05-04T09:42:00+00:00"
      }
    ]
  }
}

Access user data

POST /publishers/users/{userId}/gdpr-requests
Header s2s token

Posts an access user data request for the specific user

Path parameters
Responses
  • • 202 object

    Accepted

    • data object
      • id Required / integer

        the id assigned to the given request

  • • 404

    User not found

  • • 409

    Access Request already exist

POST /publishers/users/{userId}/gdpr-requests 
curl \
 -X POST https://api.bitlabs.ai/v1/publishers/users/{userId}/gdpr-requests \
 -H "X-S2S-Token: $API_KEY"
Response example (202) 
{
  "data": {
    "id": 42
  }
}

Get Offers for Publishers

GET /publishers/offers
Header s2s token
Responses
  • • 200 object

    OK

    • data object
      • offers Required / array[object]
        • id Required / integer(int64)
        • title Required / string
        • description Required / string
        • icon Required / string
        • image string
        • link Required / string
        • is_live Required / boolean
        • target_os Required / array[string]

          Values are all, android, ios, or desktop.

        • tasks Required / array[object]
          • id Required / integer(int64)
          • description Required / string
          • cpa Required / string

            CPI of this survey in USD without any formatting applied.

          • is_live Required / boolean
        • score Required / number(float)

          The offers's score determined by the ranking algorithm. Higher is better.

        • duration number(float)

          The average duration for offer completion in minutes

        • tags Required / array[string]
        • is_promoted Required / boolean
        • country Required / string
GET /publishers/offers 
curl \
 -X GET https://api.bitlabs.ai/v1/publishers/offers \
 -H "X-S2S-Token: $API_KEY"
Response example (200) 
{
  "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"
      }
    ]
  }
}