---
url: "https://smashsend.com/docs/api/forms"
title: Forms API - SMASHSEND
domain: smashsend.com
locale: en
type: docs
words: 511
cited_by: 0
indexed_by: stealpage
---

1.  [
    
    Home
    
    ](https://smashsend.com/)

/

3.  [
    
    Docs
    
    ](https://smashsend.com/docs)

/

5.  [
    
    API Reference
    
    ](https://smashsend.com/docs/api)

/

7.  [
    
    Forms
    
    ](https://smashsend.com/docs/api/forms)

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"
}
```