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 an access_token.

POST/api/v1/auth/create_tokens

Authenticate

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": "example@example.com",
  "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>

Get Signup

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.

  • 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
    referral_token
    Type
    boolean
    Description

    Include this parameter as referral_token=true if you want to get all Signups with the same referral_token (i.e. all of them were referred by the same signed-up user). This is useful for keeping track of your most active referrers.

  • 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

The response is an array of Authenticated Signup Objects.

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

Get Signup Response 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": "Where did you hear about us?", "optional": false, "answer_value": "Twitter"}],
      "phone": null,
      "first_name": "Maya",
      "last_name": "Kyler",
      "metadata": {},
      "waitlist_id": 1234
  }
]
PATCH/api/v1/signup

Offboard 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

GET
/api/v1/waitlist?waitlist_id=<waitlist_id>
curl --request PATCH \
  --url https://api.getwaitlist.com/api/v1/signup \
  --header '{
    Content-Type: application/json,
    Authorization: Bearer qwertyuiop1234567890
  }'
  --data '{
    "waitlist_id": 123,
    "signups": [
      {"uuid": "asdf-asdf-asdf-asdf-asdf-asdf"}
    ]
  }'

Response

[
  {
      "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": "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
  }
]