Sign in

Waitlist API Endpoint Documentation for Developers using Waitlist API

This is an unauthenticated API, meaning that there is no authentication required. All objects returned are publicly viewable and do not expose sensitive data.

GET/api/v1/waitlist?waitlist_id=<waitlist_id>

Get Waitlist

This endpoint returns everything that you need in order to render your Waitlist and create Signups on your front-end.

Query String Attributes

  • Name
    id
    Type
    integer
    Description

    The ID of your waitlist. This can be found on your dashboard.

Response

The response is a Waitlist object.

Request

GET
/api/v1/waitlist?waitlist_id=<waitlist_id>
curl --request GET \
    --url https://api.getwaitlist.com/api/v1/waitlist?waitlist_id=1234

Waitlist Response Example

  "id": 213,
  "configuration_style_json": {
    "social_links": {
      "facebook": "",
      "instagram": "",
      "linkedin": "",
      "pinterest": "",
      "twitter": "https://twitter.com/WaitlistAPI"
    },
    "status_description": "Thanks for signing up!",
    "status_font_color": "#000000",
    "status_main_color": "#222222",
    "widget_background_color": "#4937E7",
    "widget_button_color": "#000000",
    "widget_font_color": "#000000"
  },
  "logo": null,
  "spots_to_move_upon_referral": 3,
  "uses_firstname_lastname": false,
  "uses_leaderboard": true,
  "uses_signup_verification": false,
  "waitlist_name": "Title",
  "waitlist_url_location": "https://getwaitlist.com",
  "statistics": {
      'total_signups': 2200,
      'current_signups': 2200,
  },
  "title": null,
  "success_title": null,
  "required_contact_detail": "EMAIL",
  "widget_shows_social_links": false,
  "signup_button_title": "Sign Up",
  "hide_counts": false,
  "leaderboard_length": 5,
  "remove_widget_headers": false,
  "questions": [{'question_value': "What is your favorite animal?", 'optional': false, "answer_value": ["Cat", "Dog", "Duck", "Other"]}],
  "twitter_message": "",
  "organization_uuid_fk": "30120c24-0ddc-4f35-9bc6-f5e3c7b09257",
}
GET/api/v1/signup/<ID>/leaderboard

Get Waitlist Leaderboard

This route returns the Leaderboard for a Waitlist, if enabled.

Optional Query String Attributes

  • Name
    total_signups
    Type
    string
    Description

    The total number of Signups you want to return as part of the response. Otherwise, this is set by the Leaderboard length parameter that you can configure on your Waitlist's dashboard. (The default for this is 5.)

Response

The response is a Leaderboard object. This response allows you to display a competitive leaderboard, that you use to motivate users to increase their referral count.

Use Case Examples

Here are a few common scenarios where you might use the Leaderboard endpoint:

  • Motivating Users: Displaying a leaderboard on your landing page or within your application can motivate users to refer more people to your waitlist.
  • Gamification: Incorporating the leaderboard into a gamified experience can increase user engagement and retention.
  • Transparency: Providing a transparent view of the top referrers can build trust and encourage competition among users.

Request

GET
/api/v1/waitlist/<ID>/leaderboard
curl --request GET \
    --url https://api.getwaitlist.com/api/v1/waitlist/1234/leaderboard?total_signups=5

Leaderboard Response Example

{
  'leaderboard': [
    {'amount_referred': 5, 'email': 'b***@g**************', 'first_name': 'Brittany', 'last_name': 'S.', 'phone': '415 *** ****'},
    {'amount_referred': 4, 'email': 'b*****@g**************', 'first_name': 'Bianca', 'last_name': 'G.', 'phone': '234 *** ****'},
    {'amount_referred': 1, 'email': 'b*****@g**************', 'first_name': 'Bonnie', 'last_name': 'L.', 'phone': '123 *** ****'},
    {'amount_referred': 1, 'email': 'b*****@g**************', 'first_name': 'Brian', 'last_name': 'N.', 'phone': '117 *** ****'},
    {'amount_referred': 0, 'email': 'b*****@g**************', 'first_name': 'Breanna', 'last_name': 'K.', 'phone': '324 *** ****'},
  ]
}

Troubleshooting Guide

If you encounter issues when using any of the endpoints, refer to the following troubleshooting tips:

  1. Invalid ID Parameter

    • Issue: You receive an error stating that the ID parameter is invalid or not found.
    • Solution: Verify that the ID parameter you are using is correct. This should be the unique identifier of the waitlist as found on your dashboard. Ensure there are no typos or missing digits.

  2. Empty Leaderboard Response

    • Issue: The API returns an empty leaderboard even though you expect entries.
    • Solution: Check the configuration of your waitlist to ensure that the leaderboard feature is enabled and that there are users who have referred others. If the leaderboard length is set to 0, adjust it to the desired number of entries.

  3. Incorrect Total Signups Returned

    • Issue: The total_signups parameter does not return the expected number of entries.
    • Solution: Ensure that the total_signups parameter is correctly included in your request URL. If you still encounter issues, check your waitlist's dashboard to confirm the default leaderboard length setting.

  4. Network Errors

    • Issue: You experience network-related issues such as timeouts or inability to reach the API.
    • Solution: Verify your internet connection and ensure that the API endpoint URL is correct. If the problem persists, reach out to us via chat on the lower right corner.