Reward Actions

Let users complete tasks to earn points and move up the waitlist.

Pro Plan Required Reward actions require a Pro plan.

Reward actions are tasks users complete to earn points and move up the waitlist — like visiting a URL, following your social accounts, or completing a survey. Each completed action earns points that boost the user’s position.

How It Works

Define a set of reward actions on your waitlist (e.g., “Follow us on Twitter”, “Share on LinkedIn”)
After signing up, users see the available actions
When a user completes an action, they call the API with their referral token to claim it
Their position is boosted by the action’s points value
Each action can only be completed once per user

Configure Actions

Set up reward actions by updating your waitlist’s reward_actions array:

API: PATCH /waitlists/{waitlist_id}

{
  "settings": {
    "reward_actions": [
      {
        "id": "follow_twitter",
        "label": "Follow us on Twitter",
        "type": "url_visit",
        "url": "https://twitter.com/yourhandle",
        "points": 3
      },
      {
        "id": "share_linkedin",
        "label": "Share on LinkedIn",
        "type": "self_report",
        "points": 5
      },
      {
        "id": "complete_survey",
        "label": "Complete our survey",
        "type": "url_visit",
        "url": "https://forms.example.com/survey",
        "points": 2
      }
    ]
  }
}

Field	Type	Required	Description
`id`	string	Yes	Unique identifier for the action (e.g., `follow_twitter`)
`label`	string	Yes	Short label shown to users (e.g., “Follow us on Twitter”)
`type`	string	Yes	`"url_visit"` (links to a URL) or `"self_report"` (user self-reports completion)
`url`	string (HTTPS URL)	Only for `url_visit`	The URL the user should visit. Must start with `https://`.
`points`	integer (1-100)	Yes	How many points the user earns when they complete this action

You can configure up to 10 reward actions per waitlist.

Complete an Action

When a user completes a reward action, call this endpoint with their referral token as proof of identity:

API: POST /public/waitlists/{waitlist_id}/signups/{email}/actions/{action_id}?token={referral_token}

The referral token is passed as a query parameter. It must match the referral token assigned to the specified email.

Response (200):

{
  "action_id": "follow_twitter",
  "points_earned": 3,
  "new_position": 12,
  "completed_at": "2025-03-15T10:30:00.000Z"
}

Error responses:

Status	Description
`403`	The referral token does not match the signup
`404`	The signup email or action ID was not found
`409`	The user has already completed this action

List Completed Actions

Check which actions a user has completed:

API: GET /public/waitlists/{waitlist_id}/signups/{email}/actions?token={referral_token}

The referral token is passed as a query parameter for identity verification.

Response:

{
  "completed_actions": [
    {
      "action_id": "follow_twitter",
      "action_label": "Follow us on Twitter",
      "points": 3,
      "completed_at": "2025-03-15T10:30:00.000Z"
    }
  ]
}

Points and Position Boost

When a user completes an action, their position is boosted using the same formula as referral boosts:

new_position = max(1, current_position - points)

The max(1, ...) ensures the position never goes below 1. The position update is performed atomically in the database.

Each action can only be completed once per user. Attempting to complete the same action again returns a 409 error.

Referral System — how referral-based position boosts work
Creating Waitlists — configure waitlist settings
Signup Form — how the signup flow and success page work

Previous Invitation Codes Next Hosted Pages