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"
  }

Waitlist

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
  }
}