Forms API

The Forms API exposes your SMASHSEND waitlist and referral forms: where a participant sits in the queue, how many people they have referred, and which rewards they have unlocked. Use it to render a referral dashboard inside your own product instead of sending people to a hosted page.

No add-on required. Unlike the Broadcasts API, the Forms API is available on any workspace with an API key. Rate limits are applied per workspace.

Authentication

Server-side endpoints authenticate with your API key as a Bearer token. The workspace is derived from the key, so there is no workspace ID in the URL.

Authorization: Bearer YOUR_API_KEY

The public endpoints further down use a form's public key instead. That key is safe to ship in a browser: it can only submit entries and read participant-scoped status for the form it belongs to.

Get a participant's position

GET/v1/forms/{formId}/entries/{entryIdOrEmail}/position

Looks up a single entry by its ID or by email address. This is the endpoint to call when someone returns to your site and you want to show "you are #128 of 4,000".

curl https://api.smashsend.com/v1/forms/frm_123/entries/ada@example.com/position \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "position": 128,
  "points": 30,
  "referralCount": 3,
  "participantCount": 4000
}

Display offsets are applied. position and participantCount respect the offsets configured on the form, so they match what the participant sees on the hosted referral page. points and referralCount are always the real values. position is null when the entry is not ranked yet (for example before it has been confirmed).

List an entry's rewards

GET/v1/forms/{formId}/entries/{entryId}/rewards

Returns the reward ledger for one entry: every reward tier the participant has reached and its current review state. Use it to render "2 of 3 rewards unlocked" next to their position.

curl https://api.smashsend.com/v1/forms/frm_123/entries/fen_456/rewards \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "rewards": {
    "items": [
      {
        "id": "frw_789",
        "entryEmail": "ada@example.com",
        "status": "EARNED",
        "createdAt": "2026-08-01T10:12:00.000Z"
      }
    ]
  }
}

Public (browser-safe) endpoints

These use the form's public key and need no API key, so you can call them straight from your own signup page or a custom referral dashboard.

POST/v1/forms/{publicKey}/submit

Submits an entry. Pass referredBy with the referrer's public entry ID to attribute the signup and award points.

curl -X POST https://api.smashsend.com/v1/forms/pk_live_123/submit \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "answers": { "firstName": "Ada" },
    "referredBy": "ent_abc"
  }'

GET/v1/forms/{publicKey}

Returns the form's public configuration — fields, copy and reward tiers — so you can render it yourself.

GET/v1/forms/{publicKey}/entries/{publicId}/referral-status

The participant-facing view of position, points and rewards, scoped to a single entry's public ID.

GET/v1/forms/{publicKey}/leaderboard

The public leaderboard for the form, with emails masked according to the form's privacy settings.

POST/v1/forms/{publicKey}/status-link

Emails a participant a magic link back to their referral status, so you never have to store their entry ID.

POST/v1/forms/{publicKey}/entries/{publicId}/tasks/{taskId}/complete

Marks a referral task (for example "follow us on X") as completed for that entry.

Errors

Errors return a JSON body with a machine-readable code. A 404 means the form or entry does not exist in the workspace tied to your API key.

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Form entry not found"
}