Forms API - SMASHSEND

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