Waiting list for Participants (Open Beta)

Waiting list for Participants (Open Beta)

There is an easy way for you to have people sign up to be part of your beta program. In order to do that you can either:

  • build and host an HTML form that will send proper requests to our exposed REST API,
  • send HTTP requests from your web application to our REST API.


When you first go to the Waiting List page, it will be empty.

There is one important piece of information here, though: the Waiting Room API URL of a REST endpoint to which you can send requests from your form. The URL is unique for your application and contains an authorization token.



The request sent from your form must be a valid HTTP POST request containing the following JSON object:


“metadata”: {
“platform”: <PLATFORM>,
“os_version”: <OS_VERSION>,
“ip_address”: <IP_ADDRESS>,
“locale”: <LOCALE>,
“device_type”: <DEVICE_TYPE>
     “custom_tags”: [“custom_tag1”, “custom_tag2”]



EMAIL_ADDRESS required E-mail address of a new beta user.
PLATFORM optional One of: ios, android
OS_VERSION optional Operating system version
IP_ADDRESS optional A valid IP address (v4 or v6) of the user browsing the landing page. Used for reverse geocoding to assign a country tag to the user.
LOCALE optional Locale of the user sending the request. Example: pl_PL, en_US
DEVICE_TYPE optional One of: phone, tablet
CUSTOM_TAGS optional json array of custom tags


Please remember to set the Content-Type header to application/json.

User-Agent header analysis

If a User-Agent header is included in the POST request, it will be parsed and the system will try to extract properties like platform, os_version and locale from it. Whatever you pass explicitly in the JSON metadata field takes precedence over the data extracted from User-Agent.

Sample request


POST /api/v1/companies/1/applications/1/beta_subscriptions/wait_list/opt_in/9bad740abeac81bb406f00c1e3c6fa8f29382550/ HTTP/1.1
Host: https://my.apphance.com
Accept: application/json
User-Agent: Mozilla/5.0 (Linux; Android 4.0.4; Galaxy Nexus Build/IMM76B; en_US) AppleWebKit/535.19 (KHTML, like Gecko) Chrome/18.0.1025.133 Mobile Safari/535.19

  "metadata": {
    "platform": "ios",
    "os_version": "9.0",
    "ip_address": "",
    "locale": "en_US",
    "device_type": "phone",
    "custom_tags": ["open_beta", "external"]



The service returns an HTTP 200 OK status if everything went well. In any case of bad data input an HTTP 400 Bad Request will be returned, together with a JSON object containing error messages for each individual field:

“email”: [“beta@example.com – already subscribed to this application”],
“metadata”: [“This field is required.”]

If the URL is invalid (e.g. contains a wrong token) an HTTP 404 Not Found status will be returned.

Waiting List Management

Once you start getting users to your beta waiting list, you can easily decide who should be promoted to a regular beta participant (by clicking on Add to Participants) and who shouldn’t (by clicking on Reject).

At this stage you can also see the groups that were automatically assigned to each user to help you decide whether they should be included in your next build distribution. You can easily maintain the group list (add new, remove existing) of each user just like you do on the Participants tab.

Building your own landing page

Because the API returns JSON responses, submitting a regular HTML form to add a user to the waiting list might not be a good idea for building the best user experience. We have built an example web form, with jQuery used behind the scenes, to send an AJAX request to our API endpoint and properly react to the received responses.


Click >here< to download the source code of this form.


You can use it as a base for building your own beta landing page. Please remember to replace the API URL used in the form to the one from your very own waiting list.