Authenticated API Documentation for Developers using Waitlist API

This is an authenticated API. Authentication is required, because objects returned may expose sensitive data. In order to call authenticated routes, you will first need to authenticate and obtain either an api-key or an access_token.

Developers are encouraged to utilize API keys to access authenticated routes, as they are straightforward to generate and manage. They facilitate quick implementation ensuring a smooth and uncomplicated experience for developers. Access tokens on the other hand involve a more complex authentication flow, including token acquisition and renewal.

API Key

Developers can generate and use API keys to access authenticated routes in this API by including the API Key in the request header as follows:

Request Using API Key

curl --request GET
--url "https://api.getwaitlist.com/api/v1/signup/waitlist/1234?offset=10" \
--header 'api-key: 0ef6967e622d5e3d21ed6313eb428e51d2d43cd07b20816234a4bfaeac5b6857' \
--header 'Content-Type: application/json'

Steps to Generate an API Key

Navigate to "My Account" on the left side of your dashboard and scroll down to the API Keys Section.
Click on the "Add API Key", which will then prompt you to provide a desirable name to your key.
Click on the "Create API Key" button to finally generate an API Key. The generated API key will now be available in the table records. API keys do not expire and must be manually deleted to be revoked.

POST/api/v1/auth/create_tokens

Access Token

Create an access_token and a refresh_token. You can use the access_token to call other routes in this authenticated API.

Required Attributes

Name
email
Type
string
Description
The email address for your GetWaitlist account.
Name
password
Type
string
Description
The password for your GetWaitlist account.

Response

Name
access_token
Type
string
Description
The access token. This lasts for three days before it needs to be refreshed via /api/v1/auth/refresh_access_token.
Name
refresh_token
Type
string
Description
The refresh token. This lasts for thirty days before you need to either re-authenticate using this route, or obtain a new one via /api/v1/auth/refresh_access_token.

Request

POST

/api/v1/auth/create_tokens

curl --request POST \
--url https://api.getwaitlist.com/api/v1/auth/create_tokens \
--header 'Content-Type: application/json' \
--data '{
"email": "[email protected]",
"password": "password1234"
}'

Authentication Response Example

{
    "access_token": "qwertyuiop1234567890",
    "refresh_token": "asdfghjkl098765321"
}

GET/api/v1/auth/refresh_access_token

Refresh Access Token

Obtain a new access_token and refresh_token pair using your existing refresh_token.

Required Headers

Name
Authorization
Type
string
Description
Example: Bearer {my_refresh_token}

Response

Name
access_token
Type
string
Description
A new access token. This lasts for three days before it needs to be refreshed via this route.
Name
refresh_token
Type
string
Description
A new refresh token that is distinct from the one submitted in the request. This lasts for thirty days before you need to either re-authenticate using /api/v1/auth/create_tokens or refresh via this route.

Request

GET

/api/v1/auth/refresh_access_token

curl --request GET \
--url https://api.getwaitlist.com/api/v1/auth/refresh_access_token \
--header 'Authorization: Bearer zxcvbnm1234567890' \
--header 'Content-Type: application/json'

Refresh Response Example

{
    "access_token": "qwertyuiop1234567890",
    "refresh_token": "asdfghjkl098765321"
}

GET/api/v1/signup/waitlist/<waitlist_id>

Query all Signups belonging to a waitlist that you own.

You can filter to the set of Signups referred by a particular Signup, using the referral_token attribute.
This is a paginated view that returns by default 25 Signups at a time. If you need to retrieve more Signups than that, you can use offset and limit.
The query result is always ordered, so repeated pagination will return the set of all Signups. A normal query will be ordered by priority (best priority first). If you request offboarded Signups, they are ordered by when they were offboarded (most recent first).

Required attributes

Name
waitlist_id
Type
integer
Description
The ID of your waitlist.

Optional Attributes

Name
offset
Type
integer
Description
Number of Signups to skip. For example, if you send offset=250 then you will skip the first 250 Signups. Default is 0.
Name
limit
Type
integer
Description
Number of Signups per page of results. For example, limit=100 will return one page of 100 Signups. Default is 25.
Name
referral_token
Type
string
Description
Referral token of the Signup whose referrals you would like to see listed. Returns users who were referred by this token.
Name
referral_tokens
Type
array of strings
Description
A list of referral tokens to query at once. When used without include_referrer=true, this returns a grouped response with each token as a key and its referred users as values.
Name
questions_request
Type
boolean
Description
Include this parameter as questions_request=true if you want the Signup's answers to your questions included.
Name
include_referrer
Type
boolean
Description
Include this parameter as include_referrer=true if you want to get information about the owner of the referral token instead of users referred by the token.
- When used with referral_token, it will return information about the owner of that token.
- When used with referral_tokens, it will return information about all owners of the provided tokens.
- When not provided with either referral_token or referral_tokens, it returns all referrals organized by referrer.
Name
offboarded_request
Type
boolean
Description
Include this parameter as offboarded_request=true if you want to get all Signups who have been offboarded.

Response

Standard Response Format

When using a single referral_token or not using referral filtering, the response is an array of Authenticated Signup Objects.

Grouped Response Format

When using referral_tokens (multiple tokens) without include_referrer=true, the response format changes to a grouped structure:

Name
referrers
Type
object
Description
An object where each key is a referral token and each value contains:
Name
signups
Type
array
Description
Array of users referred by this token (using the Authenticated Signup Object format)
Name
count
Type
integer
Description
Number of users referred by this token
Name
total_results_count
Type
integer
Description
Total number of referred users across all referral tokens

This grouped format makes it easy to see which users were referred by each referral token and quickly identify referral patterns.

Request

GET

/api/v1/signup/waitlist/<waitlist_id>

curl --request GET \
--url https://api.getwaitlist.com/api/v1/signup/waitlist/1234 \
--header '{
Content-Type: application/json,
Authorization: Bearer qwertyuiop1234567890
}'
--data '{
"offset": 10,
"referral_token": "4F0BTBMAB",
"questions_request": true
}'

Standard Response (single token)

[
{
    "amount_referred": 0,
    "created_at": "2022-04-10_18-34-28",
    "email": "[email protected]",
    "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": "Where did you hear about us?", "optional": false, "answer_value": "Twitter"}],
    "phone": null,
    "first_name": "Maya",
    "last_name": "Kyler",
    "metadata": {},
    "waitlist_id": 1234
}
]

Grouped Response (multiple tokens)

{
  "referrers": {
    "4F0BTBMAB": {
      "signups": [
        {
          "amount_referred": 0,
          "created_at": "2022-04-10_18-34-28",
          "email": "[email protected]",
          "priority": 4985,
          "referral_link": "https://getwaitlist.com?ref_id=ABCDEFG123",
          "referral_token": "ABCDEFG123",
          "referred_by_signup_token": "4F0BTBMAB",
          "removed_date": null,
          "removed_priority": null,
          "uuid": "c60ff9f2-1a58-4551-87ea-414991184fba",
          "verified": true,
          "phone": null,
          "first_name": "Referred",
          "last_name": "User1",
          "metadata": {},
          "waitlist_id": 1234
        },
        {
          "amount_referred": 1,
          "created_at": "2022-05-15_12-20-45",
          "email": "[email protected]",
          "priority": 5102,
          "referral_link": "https://getwaitlist.com?ref_id=XYZ987DEF",
          "referral_token": "XYZ987DEF",
          "referred_by_signup_token": "4F0BTBMAB",
          "removed_date": null,
          "removed_priority": null,
          "uuid": "d72ff9f2-3b28-5661-90ea-524991184123",
          "verified": false,
          "phone": null,
          "first_name": "Referred",
          "last_name": "User2",
          "metadata": {},
          "waitlist_id": 1234
        }
      ],
      "count": 2
    },
    "XYZ123ABC": {
      "signups": [
        {
          "amount_referred": 0,
          "created_at": "2022-06-20_14-34-28",
          "email": "[email protected]",
          "priority": 6123,
          "referral_link": "https://getwaitlist.com?ref_id=QWERTY789",
          "referral_token": "QWERTY789",
          "referred_by_signup_token": "XYZ123ABC",
          "removed_date": null,
          "removed_priority": null,
          "uuid": "e83ff9f2-2c15-4531-82eb-614991184321",
          "verified": true,
          "phone": null,
          "first_name": "Referred",
          "last_name": "User3",
          "metadata": {},
          "waitlist_id": 1234
        }
      ],
      "count": 1
    }
  },
  "total_results_count": 3
}

PATCH/api/v1/signup

Offboard a Signup from your waitlist.

Required attributes

Name
waitlist_id
Type
integer
Description
The ID of your waitlist.
Name
offboard_request
Type
boolean
Description
Should be true. Cannot be set back to false.
Name
signups
Type
array of objects
Description
An array of all the Signups you are intending to offboard. To offboard, you only need the UUID of the Signup.
Name
uuid
Type
string
Description
The UUID of the Signup that is being offboarded.

Response

The response is an array of Authenticated Signup Objects that were offboarded. As shown in the response, for each offboarded Signup, removed_date will be the datetime of removal from the waitlist and removed_priority will show the Signup's priority at the time of offboarding.

Request

PATCH

/api/v1/signup

curl --request PATCH \
--url https://api.getwaitlist.com/api/v1/signup \
--header '{
Content-Type: application/json,
Authorization: Bearer qwertyuiop1234567890
}'
--data '{
"waitlist_id": 123,
"offboard_request": true,
"signups": [
{"uuid": "c60ff9f2-1a58-4551-87ea-414991184fba"}
]
}'

Response

[
{
    "amount_referred": 0,
    "created_at": "2022-04-10_18-34-28",
    "email": "[email protected]",
    "priority": 4985,
    "referral_link": "https://getwaitlist.com?ref_id=4F0BTBMAB",
    "referral_token": "4F0BTBMAB",
    "referred_by_signup_token": null,
    "removed_date": "2023-03-15_04-40-39",
    "removed_priority": 123,
    "uuid": "c60ff9f2-1a58-4551-87ea-414991184fba",
    "verified": false,
    "phone": null,
    "first_name": "Maya",
    "last_name": "Kyler",
    "metadata": {},
    "waitlist_id": 123
}
]

PATCH/api/v1/signup/<uuid>

Move a Signup forward in your waitlist. Include the uuid of the waiter whose position you wish to advance in the API path.

Required attributes

Name
spots_to_advance
Type
integer
Description
Specifies the number of positions you wish to advance the waiter by.

Optional attributes

Name
metadata
Type
JSON
Description
Any JSON object you would want to associate with the signup/waiter.

Response

The response is an Authenticated Signup Object corresponding to the updated waiter.

Request

PATCH

/api/v1/signup/

curl --request PATCH \
--url https://api.getwaitlist.com/api/v1/signup/c60ff9f2-1a58-4551-87ea-414991184fba \
--header '{
Content-Type: application/json,
Authorization: Bearer qwertyuiop1234567890
}'
--data '{
"spots_to_advance": 2,
}'

Response

{
    "amount_referred": 0,
    "created_at": "2022-04-10_18-34-28",
    "email": "[email protected]",
    "priority": 4985,
    "referral_link": "https://getwaitlist.com?ref_id=4F0BTBMAB",
    "referral_token": "4F0BTBMAB",
    "referred_by_signup_token": null,
    "removed_date": "2023-03-15_04-40-39",
    "removed_priority": 123,
    "uuid": "c60ff9f2-1a58-4551-87ea-414991184fba",
    "verified": false,
    "phone": null,
    "first_name": "Maya",
    "last_name": "Kyler",
    "metadata": {},
    "waitlist_id": 123
}

DELETE/api/v1/signup

Delete a Signup from your waitlist.

Required attributes

Name
waitlist_id
Type
integer
Description
The ID of your waitlist.
Name
signups
Type
array of objects
Description
An array of all the Signups you are intending to delete. To delete, you only need the UUID of the Signup.
Name
uuid
Type
string
Description
The UUID of the Signup that is being deleted.

Response

The response is a status code 204 that indicates a successful delete operation.

Request

DELETE

/api/v1/signup

curl --request DELETE \
--url https://api.getwaitlist.com/api/v1/signup \
--header '{
Content-Type: application/json,
Authorization: Bearer qwertyuiop1234567890
}'
--data '{
"waitlist_id": 123,
"signups": [
{"uuid": "a7aa6ae2-3c42-4fe1-a15c-2652c93022b4"}
]
}'

Authenticated API Documentation for Developers using Waitlist API

API Key

Request Using API Key

Steps to Generate an API Key

Access Token

Required Attributes

Response

Request

Authentication Response Example

Refresh Access Token

Required Headers

Response

Request

Refresh Response Example

Get Signup

Required attributes

Optional Attributes

Response

Standard Response Format

Grouped Response Format

Request

Standard Response (single token)

Grouped Response (multiple tokens)

Offboard Signup

Required attributes

Response

Request

Response

Advance a Signup

Required attributes

Optional attributes

Response

Request

Response

Delete Signup

Required attributes

Response

Request