Back to Top

BitLabs Client API

1.0.46

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 completness 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.46 of the API. Last update on Aug 11, 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.

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!

Responses
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) 
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}

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) 
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}

Get Offers

GET /client/offers
Header api token Query api token
Responses
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) 
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}

Validate zipcode

GET /client/zipcodes/{zipcode}/valid
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
Response example (200) 
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}
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
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) 
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}
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) 
{
  "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) 
{
  "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) 
{
  "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) 
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}
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
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","activity_token":"string","review":{"token":"string","q_id":42,"text":"string","c_text":"string","t_page_load":"string","t_text_typed":"string","t_submit":"string"}},"cid":{"token":"string","request_id":"string","os":"string","browser":"string","platform":"string","device_id":"string","hardware_name":"string","hardware_model":"string","hardware_vendor":"string","markers":{"is_event_unique":true,"is_sub_event_unique":true,"is_known_user_agent":true,"is_known_browser":true,"is_obsolete_browser":true,"is_known_os":true,"is_obsolete_os":true,"is_known_device_type":true,"is_known_domain":true,"is_bot":true,"is_blacklisted":true,"is_tampered":true,"is_anonymous":true,"is_resist":true,"is_velocity":true,"is_oscillating":true,"is_lang":true,"is_geo_lang":true,"is_geo_os_lang":true,"is_geo_tz":true,"is_geo_country":true,"is_geo_postal":true,"is_geo_off_hrs":true,"invalid_count":42,"score":42,"anonymous_reason":[42],"tampered_reason":[42],"postal_reason":[42]}}}'
Request example 
{
  "sc": {
    "search_token": "string",
    "activity_token": "string",
    "review": {
      "token": "string",
      "q_id": 42,
      "text": "string",
      "c_text": "string",
      "t_page_load": "string",
      "t_text_typed": "string",
      "t_submit": "string"
    }
  },
  "cid": {
    "token": "string",
    "request_id": "string",
    "os": "string",
    "browser": "string",
    "platform": "string",
    "device_id": "string",
    "hardware_name": "string",
    "hardware_model": "string",
    "hardware_vendor": "string",
    "markers": {
      "is_event_unique": true,
      "is_sub_event_unique": true,
      "is_known_user_agent": true,
      "is_known_browser": true,
      "is_obsolete_browser": true,
      "is_known_os": true,
      "is_obsolete_os": true,
      "is_known_device_type": true,
      "is_known_domain": true,
      "is_bot": true,
      "is_blacklisted": true,
      "is_tampered": true,
      "is_anonymous": true,
      "is_resist": true,
      "is_velocity": true,
      "is_oscillating": true,
      "is_lang": true,
      "is_geo_lang": true,
      "is_geo_os_lang": true,
      "is_geo_tz": true,
      "is_geo_country": true,
      "is_geo_postal": true,
      "is_geo_off_hrs": true,
      "invalid_count": 42,
      "score": 42,
      "anonymous_reason": [
        42
      ],
      "tampered_reason": [
        42
      ],
      "postal_reason": [
        42
      ]
    }
  }
}
Response example (200) 
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}

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

Get user data

GET /client/user/data
Header api token Query api token

Returns GDPR user data of the requesting user in a JSON format.

Responses
GET /client/user/data 
curl \
 -X GET https://api.bitlabs.ai/v1/client/user/data?token=api_token_value \
 -H "X-Api-Token: $API_KEY"
Response example (200) 
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}
Response example (406) 
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Get user data (as page)

GET /client/user/data/web
Header api token Query api token

Returns the requesting user's data as HTML to be displayed in the browser.

Responses
GET /client/user/data/web 
curl \
 -X GET https://api.bitlabs.ai/v1/client/user/data/web?token=api_token_value \
 -H "X-Api-Token: $API_KEY"
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) 
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}
Response example (406) 
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Delete userDeprecated

DELETE /client/user
Header api token Query api token

Deletes the requesting user's data. This operation cannot be un-done!

Responses
DELETE /client/user 
curl \
 -X DELETE https://api.bitlabs.ai/v1/client/user?token=api_token_value \
 -H "X-Api-Token: $API_KEY"
Response example (200) 
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}
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) 
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}
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) 
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}
Response example (406) 
{
  "error": {
    "details": {
      "http": "406 Not Acceptable",
      "msg": "vpn detected"
    }
  }
}

Get Offers for Publishers

GET /publishers/offers
Header api token Query api token
Responses
GET /publishers/offers 
curl \
 -X GET https://api.bitlabs.ai/v1/publishers/offers?token=api_token_value \
 -H "X-Api-Token: $API_KEY"
Response example (200) 
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}

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
Responses
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"]}]}]}'
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"
          ]
        }
      ]
    }
  ]
}
Response example (200) 
{
  "error": {
    "details": {
      "http": "string",
      "msg": "string"
    }
  },
  "status": "success",
  "trace_id": "1dc6786b10a62ec6"
}

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

    OK

  • • 404

    User not found

DELETE /publishers/users/{userId} 
curl \
 -X DELETE https://api.bitlabs.ai/v1/publishers/users/{userId} \
 -H "X-S2S-Token: $API_KEY"