BitLabs Client API
1.0.67

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. Additionally, X-Mparticle-Platform (one of: android, ios, web) can be used for proper platform
targeting.

This is the documentation for version 1.0.67 of the API. Last update on Nov 25, 2022.

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

Authentication

The API accepts 5 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.

Header user (http_api_key)

Unique identifier of the user you are sending to BitLabs. These are passed back to you in callbacks to allow
you to identify your users. If possible, use UUIDs, numerical IDs or ASCII strings to avoid formatting issues.
Do NOT use JWT or other sensitive tokens to identify your users. We only support up to 65 character long ids.

Query user (http_api_key)

Unique identifier of the user you are sending to BitLabs. These are passed back to you in callbacks to allow
you to identify your users. If possible, use UUIDs, numerical IDs or ASCII strings to avoid formatting issues.
Do NOT use JWT or other sensitive tokens to identify your users. We only support up to 65 character long ids.

Client

Get Actions

GET /client/actions
Header api token & Header user Query api token & Query user

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 string Required

    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 boolean Required

        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 array[object] Required
        • network_id integer Required

          ID of the network. Required in survey specific requests.

        • id integer(int64) Required

          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 string(ISO 3166-1 alpha-2) Required
        • language string(ISO 639-1) Required

          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 string Required

          CPI of this survey in USD without any formatting applied.

        • value string Required

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

        • loi number(float) Required

          Assumed length of the survey in minutes

        • remaining integer Required

          Amount of users that can still open the survey

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

              Localized category name

            • icon_url string Required

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

            • name_internal string Required

              Internal, unlocalized, machine-friendly name of the category

          • network object Required
            • name string Required

              Displayable name of the network the survey came from

            • icon_url string Required

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

          • difficulty string Required Deprecated

            Is the difficulty rating for this survey

            Values are EASY, MEDIUM, or HARD.

        • rating integer Required

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

          Minimum value is 1, maximum value is 5.

        • tags array[string] Required

          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 integer Required
        • link string Required

          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 number(float) Required

          The survey's score determined by the ranking algorithm.

        • sequence integer Required

          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 integer Required

            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 string Required

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

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

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

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

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

      • qualification object
        • network_id integer Required

          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 string Required

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

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

            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 string Required

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

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

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

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

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

        • is_standard_profile boolean Required

          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 boolean Required

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

        • score number(float) Required

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

        • sequence integer Required

          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 \
 -H "X-Api-Token: $API_KEY" \
 -H "X-User-Id: $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 & Header user Query api token & Query user

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 string Required

    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 \
 -H "X-Api-Token: $API_KEY" \
 -H "X-User-Id: $API_KEY"
Response example (200) 
{
  "data": {
    "has_surveys": true
  }
}

Get Surveys

GET /client/surveys
Header api token & Header user Query api token & Query user

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 string Required

    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 array[object] Required
        • network_id integer Required

          ID of the network. Required in survey specific requests.

        • id integer(int64) Required

          ID of the survey. Only unique per network_id.

        • cpi string Required

          CPI of this survey in USD without any formatting applied.

        • loi number(float) Required

          Assumed length of the survey in minutes

        • remaining integer Required

          Amount of users that can still open the survey

        • rating integer Required

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

          Minimum value is 1, maximum value is 5.

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

              Localized category name

            • icon_url string Required

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

            • name_internal string Required

              Internal, unlocalized, machine-friendly name of the category

          • network object Required
            • name string Required

              Displayable name of the network the survey came from

            • icon_url string Required

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

          • difficulty string Required 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 \
 -H "X-Api-Token: $API_KEY" \
 -H "X-User-Id: $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 & Header user Query api token & Query user

Responses

GET /client/offers 
curl \
 -X GET https://api.bitlabs.ai/v1/client/offers \
 -H "X-Api-Token: $API_KEY" \
 -H "X-User-Id: $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 & Header user Query api token & Query user

Path parameters

  • zipcode string Required

    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 \
 -H "X-Api-Token: $API_KEY" \
 -H "X-User-Id: $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

Responses

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

Get Question Deprecated

GET /client/networks/{networkId}/questions/{questionId}
Header api token & Header user Query api token & Query user

Path parameters

Query parameters

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

    country of the survey

  • language string(ISO 639-1) Required

    language of the survey

Responses

  • • 200 object

    OK

    • data object
      • network_id integer Required

        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 string Required

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

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

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

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

        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 \
 -H "X-Api-Token: $API_KEY" \
 -H "X-User-Id: $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 & Header user Query api token & Query user

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} \
 -H "X-Api-Token: $API_KEY" \
 -H "X-User-Id: $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 & Header user Query api token & Query user

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 \
 -H "X-Api-Token: $API_KEY" \
 -H "X-User-Id: $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 & Header user Query api token & Query user

Path parameters

Responses

POST /client/networks/{networkId}/surveys/{surveyId}/skip 
curl \
 -X POST https://api.bitlabs.ai/v1/client/networks/{networkId}/surveys/{surveyId}/skip \
 -H "X-Api-Token: $API_KEY" \
 -H "X-User-Id: $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 & Header user Query api token & Query user

Path parameters

Query parameters

  • platform string Required

    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 \
 -H "X-Api-Token: $API_KEY" \
 -H "X-User-Id: $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 & Header user Query api token & Query user

Path parameters

Query parameters

  • platform string Required

    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 integer Required
  • cr number(float) Required
  • loi integer Required
  • cpi string Required
  • rr number(float) Required
  • stats string(date-time)

    optional internal debugging timestamp

  • its string(date-time)

    optional internal debugging timestamp

  • mts 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 string Required

    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.0&loi=42&cpi=string&rr=42.0&hash=string \
 -H "X-Api-Token: $API_KEY" \
 -H "X-User-Id: $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 & Header user Query api token & Query user

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} \
 -H "X-Api-Token: $API_KEY" \
 -H "X-User-Id: $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 & Header user Query api token & Query user

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 string Required

    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 \
 -H "X-Api-Token: $API_KEY" \
 -H "X-User-Id: $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"
    }
  }
}

Rate survey

POST /client/networks/{networkId}/surveys/{surveyId}/rate
Header api token & Header user Query api token & Query user

Path parameters

Body Required

  • stars integer Required

    Minimum value is 1, maximum value is 5.

Responses

POST /client/networks/{networkId}/surveys/{surveyId}/rate 
curl \
 -X POST https://api.bitlabs.ai/v1/client/networks/{networkId}/surveys/{surveyId}/rate \
 -H "X-Api-Token: $API_KEY" \
 -H "X-User-Id: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"stars":42}'
Request example 
{
  "stars": 42
}
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 & Header user Query api token & Query user

Path parameters

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 \
 -H "X-Api-Token: $API_KEY" \
 -H "X-User-Id: $API_KEY"
Response example (406) 
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Get user history

GET /client/user/history
Header api token & Header user Query api token & Query user

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 \
 -H "X-Api-Token: $API_KEY" \
 -H "X-User-Id: $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 & Header user Query api token & Query user

Returns information and identifier of the requesting user

Responses

GET /client/user 
curl \
 -X GET https://api.bitlabs.ai/v1/client/user \
 -H "X-Api-Token: $API_KEY" \
 -H "X-User-Id: $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 settings Deprecated

GET /client/settings
Header api token & Header user Query api token & Query user

Responses

GET /client/settings 
curl \
 -X GET https://api.bitlabs.ai/v1/client/settings \
 -H "X-Api-Token: $API_KEY" \
 -H "X-User-Id: $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 & Header user Query api token & Query user

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 \
 -H "X-Api-Token: $API_KEY" \
 -H "X-User-Id: $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",
      "enable_additional_qualifications": true
    },
    "enable_mparticle_events": true
  }
}
Response example (406) 
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Get app's leaderboard, if enabled

GET /client/leaderboard
Header api token & Header user Query api token & Query user

Responses

GET /client/leaderboard 
curl \
 -X GET https://api.bitlabs.ai/v1/client/leaderboard \
 -H "X-Api-Token: $API_KEY" \
 -H "X-User-Id: $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
    }
  }
}

Download GDPR file

GET /client/gdpr/files/{filename}/{hash}

Path parameters

GET /client/gdpr/files/{filename}/{hash} 
curl \
 -X GET https://api.bitlabs.ai/v1/client/gdpr/files/{filename}/{hash}

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!
If more than one user is sent in a request, that request is treated as a bulk import. Only
one bulk import can be issued at a time. If only one user is set, you can call the endpoint in
parallel.

Body Required

Responses

  • • 200 object

    OK

    • data object
      • success_count integer Required

        Number of successfully imported users from the request

      • errors array[object] Required

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

POST /publishers/users 
curl \
 -X POST https://api.bitlabs.ai/v1/publishers/users \
 -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,
        "invalid_answer_format": {
          "question": "string",
          "reason": "string"
        }
      }
    ]
  }
}

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!

Responses

  • • 202 object

    Accepted

    • data object
      • id integer Required

        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 user GDPR requests

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

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",
        "first_accessed_at": "2022-01-15T12:00:00Z"
      }
    ]
  }
}

Create GDPR data request

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

Posts an access user data request for the specific user

Responses

  • • 202 object

    Accepted

    • data object
      • id integer Required

        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

Query parameters

  • limit integer

    Default value is 100.

  • page integer

    Default value is 1.

Responses

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"
      }
    ],
    "pagination": {
      "offers_per_page": 42,
      "offers_total": 42,
      "current_page": 42,
      "pages_total": 42
    }
  }
}