Schemas

Schemas show example responses of common objects like Waitlists, Waiters and Leaderboard.

Waiter

A waiter represents an individual participant who has signed up on a Waitlist.

This is an unauthenticated view of a Waiter, meaning that it is visible to anyone. It differs from an authenticated view in that personal details, such as name, phone number, etc. are all removed.

Properties

Name
amount_referred
Type
integer
Description
The number of other Waiters referred by this one. Immediately after submission, it'll always be zero.
Name
created_at
Type
string
Description
Serialized UTC timestamp of when the Waiter was created.
Name
email
Type
string
Description
The email address of this Waiter.
Name
priority
Type
integer
Description
The priority of the Waiter on the Waitlist. Zero is best. A priority of 123 represents that there are 123 Waiters in line before this one.
Name
referral_link
Type
string
Description
The referral link of the waiter. They use this referral link when sharing with others.
Name
referral_token
Type
string
Description
Unique token to credit this Waiter when they refer other people to sign up. It's like an affiliate code.
Name
referred_by_waiter_token
Type
string
Description
The referral_token of the Waiter who referred this one, if applicable.
Name
removed_date
Type
string
Description
Serialized UTC timestamp of when the Waiter was removed from the Waitlist. Immediately after submission, it'll always be null.
Name
total_waiters_currently
Type
integer
Description
The number of Waiters on the Waitlist.
Name
uuid
Type
string
Description
A UUID that uniquely identifies this Waiter.
Name
verified
Type
string
Description
True if the waiter has verified their email address, False otherwise. Immediately after submission, it'll always be False.
Name
waitlist_api_key
Type
string
Description
The API key of the waitlist that the waiter is part of.
Name
removed_priority
Type
integer
Description
The Waiter's priority when they were removed from the Waitlist. Immediately after submission, it'll always be null.

Optional Properties

Name
question_1
Type
string
Description
The first question that the waiter responded to. We include this in case you edit your questions later.
Name
question_2
Type
string
Description
The second question that the waiter responded to. We include this in case you edit your questions later.
Name
question_3
Type
string
Description
The third question that the waiter responded to. We include this in case you edit your questions later.
Name
answer_1
Type
string
Description
The waiter's answer to the first question.
Name
answer_2
Type
string
Description
The waiter's answer to the second question.
Name
answer_3
Type
string
Description
The waiter's answer to the third question.

Waiter Object Example

{
  "amount_referred": 0,
  "created_at": "2022-04-10_18-34-28",
  "email": "maya@getwaitlist.com",
  "priority": 4985,
  "referral_link": "https://www.getwaitlist.com?ref_id=4F0BTBMAB",
  "referral_token": "4F0BTBMAB",
  "referred_by_waiter_token": null,
  "removed_date": null,
  "removed_priority": null,
  "total_waiters_currently": 4986,
  "uuid": "c60ff9f2-1a58-4551-87ea-414991184fba",
  "verified": false,
  "waitlist_api_key": "0RN8X1",
  "question_1": "Where did you hear about us?",
  "answer_1": "Twitter",
  "question_2": "Are you considering any alternatives?",
  "answer_2": "No",
  "question_3": "Can we add you to our newsletter?",
  "answer_3": "Yes"
  }

This is an unauthenticated view of a Waitlist, meaning that it is visible to anyone. It differs from an authenticated view in that sensitive configuration details, such as webhook URLs, are not included here.

Properties

Name
id
Type
integer
Description
The ID of your waitlist. This is mostly used for internal purposes.
Name
api_key
Type
string
Description
The API key that uniquely identifies this Waitlist.
Name
created_at
Type
string
Description
Serialized UTC timestamp of when this Waitlist was created.
Name
configuration_style_json
Type
object
Description
Options to configure the no-code widget and status page for this Waitlist.
Name
widget_background_color
Type
string
Description
Hex string for the background color of the no-code widget.
Name
widget_button_color
Type
string
Description
Hex string for the primary button color of the no-code widget.
Name
widget_button_font_color
Type
string
Description
Hex string for the font color on the primary button of the no-code widget.
Name
widget_font_color
Type
string
Description
Hex string for the font color of the no-code widget.
Name
border_color
Type
string
Description
Hex string for the color of the 1px border around areas in the widget
Name
logo
Type
string
Description
URL to the unique logo for this Waitlist. If no logo has been configured, the getwaitlist.com logo acts as a placeholder.
Name
spots_to_move_upon_referral
Type
integer
Description
How many other Waiters this Waiter gets to skip in line (i.e. by how much their priority improves) if they make a referral.
Name
uses_firstname_lastname
Type
boolean
Description
If True, then Waiters are required to submit their first and last names when signing up to this Waitlist.
Name
uses_leaderboard
Type
boolean
Description
If True, then /api/v1/waitlist/{api_key}/leaderboard can return a Leaderboard. Otherwise, the Leaderboard is not available for this Waitlist.
Name
uses_waiter_verification
Type
boolean
Description
If True, then Waiters are required to verify their email addresses when signing up for this Waitlist. Otherwise they will have no priority.
Name
waitlist_name
Type
string
Description
Name of the Waitlist. This shows prominently on the no-code widgets.
Name
waitlist_url_location
Type
string
Description
Where the Waitlist is hosted. This is not necessarily the current window URL, but the URL that the Waitlist Owner has configured for this Waitlist.
Name
statistics
Type
object
Description
Name
total_signups
Type
integer
Description
Total number of Waiters who have ever signed up to the Waitlist. This includes Waiters who have been offboarded, or not verified.
Name
current_waiters
Type
integer
Description
Total number of Waiters currently on the Waitlist, i.e. all those that have an active priority.
Name
title
Type
string
Description
Title to display at the top of the Widget.
Name
waitlist_size_cap
Type
integer
Description
Maximum size of the Waitlist, no Waiters will be admitted beyond this number
Name
required_contact_detail
Type
string
Description
Enum for whether the user needs to supply an email, a phone number, either, or both to sign up.
Name
widget_shows_social_links
Type
boolean
Description
Whether to show the social media links on the Widget. They always show on the hosted page.
Name
signup_button_title
Type
string
Description
Custom text on the Widget's signup call to action.
Name
id
Type
integer
Description
Integer ID of the waitlist.
Name
twitter_message
Type
string
Description
Default message to display for the "Share on Twitter" call to action after joining the Waitlist.
Name
leaderboard
Type
Leaderboard
Description
Optional, only if you have leaderboards enabled. See Leaderboard schema.

Waitlist Response Example

{
  "api_key": "0X1ABN",
  "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"
  },
  "created_at": "2022-04-10_18-34-28",
  "logo": "https://waitlist-image-bucket.s3.us-east-2.amazonaws.com/logo1.svg",
  "redirects_to_status_page": false,
  "spots_to_move_upon_referral": 10,
  "uses_firstname_lastname": true,
  "uses_leaderboard": true,
  "uses_waiter_verification": false,
  "waitlist_name": "My Example Waitlist",
  "waitlist_url_location": "https://example.com/my_custom_page",
  "statistics": {
    "current_waiters": 123,
    "total_signups": 456
  }
}