Object Schema Documentation for Developers using Waitlist API
Schemas show example responses for main API objects like Waitlists, Signups and Leaderboard.
Signup (Unauthenticated)
A Signup represents an individual participant who has signed up on a Waitlist.
This is an unauthenticated view of a Signup, so it is publicly visible. However, the only unauthenticated way to currently obtain a Signup is via the Create Signup route, so the returned information is only what the Signup submitted in that call, and some GetWaitlist metadata.
Properties
- Name
amount_referred- Type
- integer
- Description
The number of other Signups referred by this one. Immediately after submission, it'll always be zero.
- Name
created_at- Type
- string
- Description
Serialized UTC timestamp of when the Signup was created.
- Name
email- Type
- string
- Description
The email address of this Signup.
- Name
priority- Type
- integer
- Description
The priority of the Signup on the Waitlist. Zero is best. A priority of 123 represents that there are 123 Signups in line before this one.
- Name
referral_link- Type
- string
- Description
The referral link of the Signup. They use this referral link when sharing with others.
- Name
referral_token- Type
- string
- Description
Unique token to credit this Signup when they refer other people to sign up. It's like an affiliate code.
- Name
referred_by_signup_token- Type
- string
- Description
The
referral_tokenof the Signup who referred this one, if applicable.
- Name
removed_date- Type
- string
- Description
Serialized UTC timestamp of when the Signup was removed from the Waitlist. Immediately after submission, it'll always be null.
- Name
uuid- Type
- string
- Description
A UUID that uniquely identifies this Signup.
- Name
verified- Type
- string
- Description
True if the Signup has verified their email address, False otherwise. Immediately after submission, it'll always be False.
- Name
removed_priority- Type
- integer
- Description
The Signup's priority when they were removed from the Waitlist. Immediately after submission, it'll always be null.
Unauthenticated Signup Object Example
{
"amount_referred": 0,
"created_at": "2022-04-10_18-34-28",
"email": "example9911@example.com",
"priority": 4985,
"referral_link": "https://getwaitlist.com?ref_id=4F0BTBMAB",
"referral_token": "4F0BTBMAB",
"referred_by_signup_token": "REFTOKEN1",
"removed_date": null,
"removed_priority": null,
"uuid": "c60ff9f2-1a58-4551-87ea-414991184fba",
"verified": false,
"waitlist_id": 12345
}
Signup (Authenticated)
A Signup represents an individual participant who has signed up on a Waitlist.
This is an authenticated view of a Signup, meaning that it is only visible to the owner of the Waitlist for which the Signup has signed up. All information is returned.
Properties
- Name
amount_referred- Type
- integer
- Description
The number of other Signups referred by this one. Immediately after submission, it'll always be zero.
- Name
created_at- Type
- string
- Description
Serialized UTC timestamp of when the Signup was created.
- Name
email- Type
- string
- Description
The email address of this Signup.
- Name
priority- Type
- integer
- Description
The priority of the Signup on the Waitlist. Zero is best. A priority of 123 represents that there are 123 Signups in line before this one.
- Name
referral_link- Type
- string
- Description
The referral link of the Signup. They use this referral link when sharing with others.
- Name
referral_token- Type
- string
- Description
Unique token to credit this Signup when they refer other people to sign up. It's like an affiliate code.
- Name
referred_by_signup_token- Type
- string
- Description
The
referral_tokenof the Signup who referred this one, if applicable.
- Name
removed_date- Type
- string
- Description
Serialized UTC timestamp of when the Signup was removed from the Waitlist. Immediately after submission, it'll always be null.
- Name
uuid- Type
- string
- Description
A UUID that uniquely identifies this Signup.
- Name
verified- Type
- string
- Description
True if the Signup has verified their email address, False otherwise. Immediately after submission, it'll always be False.
- Name
removed_priority- Type
- integer
- Description
The Signup's priority when they were removed from the Waitlist. Immediately after submission, it'll always be null.
Optional Properties
- Name
first_name- Type
- string
- Description
The first name of the Signup.
- Name
last_name- Type
- string
- Description
The last name of the Signup.
- Name
phone- Type
- string
- Description
The phone number of the Signup.
- Name
metadata- Type
- object
- Description
You may supply any JSON object as metadata about the Signup.
- Name
answers- Type
- object
- Description
A JSON object of Waitlist questions to be shown on the Widget and answered by the Signup. This is an array of dictionaries, where in each dictionary the keys are
question_value,optional, andanswer_value. Thequestion_valueis the question text,optionalis a boolean indicating whether the question is optional or not, and "answer_value" can be null (for a freeform text answer), or a list of strings for options to select from. Note: Make sure thequestion_valuematches the saved values via the getwaitlist.com dashboard (in widget builder).
Authenticated Signup Object Example
{
"amount_referred": 0,
"created_at": "2022-04-10_18-34-28",
"email": "maya@getwaitlist.com",
"priority": 4985,
"referral_link": "https://getwaitlist.com?ref_id=4F0BTBMAB",
"referral_token": "4F0BTBMAB",
"referred_by_signup_token": null,
"removed_date": null,
"removed_priority": null,
"uuid": "c60ff9f2-1a58-4551-87ea-414991184fba",
"verified": false,
"answers": [{'question_value': "What is your favorite animal?", 'optional': false, "answer_value": "Cat"}],
"phone": null,
"first_name": "Maya",
"last_name": "Kyler",
"metadata": {},
"waitlist_id": 1234
}
Waitlist
This is an unauthenticated view of a Waitlist, meaning that it is visible to anyone. Sensitive configuration details are not visible.
Properties
- Name
id- Type
- integer
- Description
The ID of your 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 Signups this Signup 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 Signups 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/{waitlist_id}/leaderboardcan return a Leaderboard. Otherwise, the Leaderboard is not available for this Waitlist.
- Name
uses_signup_verification- Type
- boolean
- Description
If True, then Signups 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 Signups who have ever signed up to the Waitlist. This includes Signups who have been offboarded, or not verified.
- Name
current_signups- Type
- integer
- Description
Total number of Signups 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
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
questions- Type
- object
- Description
A JSON object of Waitlist questions to be shown on the Widget and answered by the Signup. This is an array of dictionaries, where in each dictionary the keys are
question_value,optional, andanswer_value. Thequestion_valueis the question text,optionalis a boolean indicating whether the question is optional or not, and "answer_value" can be null (for a freeform text answer), or a list of strings for options to select from. Note: Make sure thequestion_valuematches the saved values via the getwaitlist.com dashboard (in widget builder).
- Name
uses_zapier- Type
- boolean
- Description
This is true if you have configured Zapier to be on
- Name
uses_waitlist_widget_branding- Type
- boolean
- Description
If this is true, the Waitlist branding shows up on no code widgets
- Name
email_configuration_json- Type
- object
- Description
This object contains information that is passed through in emails we send on signups and referrals
- Name
twitter_message- Type
- string
- Description
Default message to display for the "Share on Twitter" call to action after joining the Waitlist.
- Name
send_email_congratulations_on_referral- Type
- boolean
- Description
If true, we send the referrer an email congratulating them on referring someone else
- Name
organization_uuid_fk- Type
- string
- Description
Contains your Organization UUID
- Name
hide_counts- Type
- boolean
- Description
If on, the no-code widget do not show the total number of signups or the position in line after signing up
- Name
leaderboard_length- Type
- integer
- Description
Stores the length of the leaderboard that we return on an API call. It's 5 by default
- Name
remove_widget_headers- Type
- boolean
- Description
If true, the no-code widget stops displaying headers over input fields -- like "Email", "First Name" and more.
Waitlist 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",
}
Leaderboard
This is an unauthenticated view of a Leaderboard. A leaderboard is a list of the highest-priority Signups on a Waitlist. It does not include Signups who have been removed from the Waitlist (i.e. offboarded/deleted). A Leaderboard is publicly available if you have enabled it on your Waitlist.
Properties
- Name
leaderboard- Type
- array of objects
- Description
An array with all the leaders in your waitlist ordered by the total referrals they have made. The highest referrer will be first in the array.
- Name
amount_referred- Type
- string
- Description
Total number of referrals a Signup has made.
- Name
email- Type
- string
- Description
The censored email of the Signup. For example
bani@getwaitlist.comis censored asb***@g**************.
- Name
first_name- Type
- string
- Description
The first name of the Signup. We show the full name.
- Name
last_name- Type
- string
- Description
The last name of the Signup. We only show the first letter of their last name. For example
Sawyeris censored asS.
- Name
phone- Type
- string
- Description
The censored phone number of the Signup. This is helpful for mobile-only waitlists. We only show the three first digits of the phone number. For example
123 456 7891is censored as123 *** ****.
Leaderboard 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 *** ****'},
]
}