{"id":"pg_xtngqcmvvebl","property_id":"prp_pfcr5h8cztsp","domain_id":"dom_gkgeprhezjg4wq","root_domain":"smashsend.com","locale":"en","url":"https://smashsend.com/docs/api/forms","url_hash":"d1b571ba588a404fdb3bcebe4ebf29255d0b740bc1128f33e90299774b07ebde","path":"/docs/api/forms","depth":1,"canonical_url":"https://smashsend.com/docs/api/forms","canonical_page_id":null,"page_type":"docs","page_type_guess":"docs","state":"indexed","skip_reason":null,"priority":"1.4","discovered_via":"sitemap","first_seen_at":"2026-08-28T03:07:01.092Z","last_seen_at":"2026-09-27T04:10:47.779Z","http_status":200,"content_hash":"60c1a6dab1da71185146e04685db0309a73b0f954e9f2bc5ae08760ee7a19191","title":"Forms API - SMASHSEND","description":"Read referral positions, reward ledgers and leaderboards for your SMASHSEND waitlist and referral forms, and submit entries from your own front end.","author":null,"published_at":null,"modified_at":null,"word_count":511,"reading_time_sec":139,"lang_detected":"en","images":[],"links_out":null,"markdown_source":"readability","refresh_interval":"monthly","last_fetched_at":"2026-09-27T04:07:11.528Z","next_refresh_at":"2026-10-27T04:07:11.528Z","runs_count":2,"changes_count":0,"last_changed_at":null,"fail_count":0,"last_error":null,"created_at":"2026-08-28T03:07:01.092Z","updated_at":"2026-08-28T03:07:01.092Z","inlinks":13,"inlinks_body":0,"outlinks":40,"outlinks_external":3,"anchor_terms":[],"template_score":"0.09154929577464788732","cash":"0.497097636646926955","cash_total":"0.6324629686116240392","pagerank":"0.0162500817959562","is_orphan":false,"link_confirmed":true,"discovered_wave":0,"embedded_hash":null,"embedded_at":null,"domain_name":null,"brand_color":null,"domain_rank":null,"spam_score":null,"markdown":"1.  [\n    \n    Home\n    \n    ](https://smashsend.com/)\n\n/\n\n3.  [\n    \n    Docs\n    \n    ](https://smashsend.com/docs)\n\n/\n\n5.  [\n    \n    API Reference\n    \n    ](https://smashsend.com/docs/api)\n\n/\n\n7.  [\n    \n    Forms\n    \n    ](https://smashsend.com/docs/api/forms)\n\nThe 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.\n\n**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.\n\n## Authentication\n\nServer-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.\n\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\nThe 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.\n\n## Get a participant's position\n\nGET/v1/forms/{formId}/entries/{entryIdOrEmail}/position\n\nLooks 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\".\n\n```\ncurl https://api.smashsend.com/v1/forms/frm_123/entries/ada@example.com/position \\\n  -H \"Authorization: Bearer YOUR_API_KEY\"\n```\n\nResponse:\n\n```\n{\n  \"position\": 128,\n  \"points\": 30,\n  \"referralCount\": 3,\n  \"participantCount\": 4000\n}\n```\n\n**Display offsets are applied.** `position`\n\nand `participantCount` respect the offsets configured on the form, so they match what the participant sees on the hosted referral page. `points` and `referralCount`\n\nare always the real values. `position` is\n\n`null` when the entry is not ranked yet (for example before it has been confirmed).\n\n## List an entry's rewards\n\nGET/v1/forms/{formId}/entries/{entryId}/rewards\n\nReturns 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.\n\n```\ncurl https://api.smashsend.com/v1/forms/frm_123/entries/fen_456/rewards \\\n  -H \"Authorization: Bearer YOUR_API_KEY\"\n```\n\nResponse:\n\n```\n{\n  \"rewards\": {\n    \"items\": [\n      {\n        \"id\": \"frw_789\",\n        \"entryEmail\": \"ada@example.com\",\n        \"status\": \"EARNED\",\n        \"createdAt\": \"2026-08-01T10:12:00.000Z\"\n      }\n    ]\n  }\n}\n```\n\n## Public (browser-safe) endpoints\n\nThese 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.\n\nPOST/v1/forms/{publicKey}/submit\n\nSubmits an entry. Pass `referredBy` with the referrer's public entry ID to attribute the signup and award points.\n\n```\ncurl -X POST https://api.smashsend.com/v1/forms/pk_live_123/submit \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"email\": \"ada@example.com\",\n    \"answers\": { \"firstName\": \"Ada\" },\n    \"referredBy\": \"ent_abc\"\n  }'\n```\n\nGET/v1/forms/{publicKey}\n\nReturns the form's public configuration — fields, copy and reward tiers — so you can render it yourself.\n\nGET/v1/forms/{publicKey}/entries/{publicId}/referral-status\n\nThe participant-facing view of position, points and rewards, scoped to a single entry's public ID.\n\nGET/v1/forms/{publicKey}/leaderboard\n\nThe public leaderboard for the form, with emails masked according to the form's privacy settings.\n\nPOST/v1/forms/{publicKey}/status-link\n\nEmails a participant a magic link back to their referral status, so you never have to store their entry ID.\n\nPOST/v1/forms/{publicKey}/entries/{publicId}/tasks/{taskId}/complete\n\nMarks a referral task (for example \"follow us on X\") as completed for that entry.\n\n## Errors\n\nErrors 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.\n\n```\n{\n  \"statusCode\": 404,\n  \"error\": \"Not Found\",\n  \"message\": \"Form entry not found\"\n}\n```","storage":{"htmlKey":"stealpage/html/smashsend.com/pg_xtngqcmvvebl/run_frb1wo7ynefh.html.gz","markdownKey":"stealpage/md/smashsend.com/pg_xtngqcmvvebl/run_frb1wo7ynefh.md.gz"},"facets":null,"assets":[{"kind":"image","src_url":"https://smashsend.com/ogs/home.png","r2_key":null,"alt":null,"caption":null,"width":null,"height":null,"is_hero":true,"zone":"main"},{"kind":"image","src_url":"https://smashsend.com/_next/static/media/smashsend_dark.da05b6ec.svg","r2_key":null,"alt":"SMASHSEND email marketing - The #1 Email Marketing Tool that turns emails into revenue","caption":null,"width":135,"height":30,"is_hero":false,"zone":"unknown"},{"kind":"image","src_url":"https://smashsend.com/dashboard/integrations/zapier_icon_filled.png","r2_key":null,"alt":"Zapier","caption":null,"width":20,"height":20,"is_hero":false,"zone":"nav"},{"kind":"image","src_url":"https://smashsend.com/dashboard/integrations/mailchimp_icon.png","r2_key":null,"alt":"Mailchimp","caption":null,"width":20,"height":20,"is_hero":false,"zone":"nav"},{"kind":"image","src_url":"https://smashsend.com/dashboard/integrations/webhooks_icon_gradient.png","r2_key":null,"alt":"Webhooks","caption":null,"width":20,"height":20,"is_hero":false,"zone":"nav"},{"kind":"image","src_url":"https://smashsend.com/dashboard/integrations/events.png","r2_key":null,"alt":"Events API","caption":null,"width":20,"height":20,"is_hero":false,"zone":"nav"},{"kind":"image","src_url":"https://smashsend.com/_next/image?q=75&url=%2Favatar-profile.png&w=3840","r2_key":null,"alt":"Jorge Ferreiro","caption":null,"width":null,"height":null,"is_hero":false,"zone":"nav"},{"kind":"image","src_url":"https://smashsend.com/_next/image?url=%2Favatar-profile.png&w=3840&q=75","r2_key":null,"alt":"Jorge Ferreiro","caption":null,"width":null,"height":null,"is_hero":false,"zone":"nav"},{"kind":"image","src_url":"https://smashsend.com/_next/static/media/smashsend_light.be8a3849.svg","r2_key":null,"alt":"SMASHSEND email marketing - The #1 Email Marketing Tool that turns emails into revenue","caption":null,"width":171,"height":38,"is_hero":false,"zone":"footer"},{"kind":"image","src_url":"https://smashsend.com/marketing/legal/gdpr_compliance.png","r2_key":null,"alt":"SOC2","caption":null,"width":null,"height":50,"is_hero":false,"zone":"footer"}],"shots":[{"viewport":"mobile","width":390,"height":844,"r2_key":"stealpage/shots/smashsend.com/pg_xtngqcmvvebl/run_frb1wo7ynefh-mobile.png","phash":"2690b0a068ec9486","visual_delta":0,"captured_at":"2026-09-27T04:07:15.702Z"},{"viewport":"desktop","width":1440,"height":900,"r2_key":"stealpage/shots/smashsend.com/pg_xtngqcmvvebl/run_frb1wo7ynefh-desktop.png","phash":"866360606060f0e8","visual_delta":0,"captured_at":"2026-09-27T04:07:15.479Z"},{"viewport":"mobile","width":390,"height":844,"r2_key":"stealpage/shots/smashsend.com/pg_xtngqcmvvebl/run_sapxu3hhimcl-mobile.png","phash":"2690b0a068ec9486","visual_delta":null,"captured_at":"2026-08-28T03:12:51.942Z"},{"viewport":"desktop","width":1440,"height":900,"r2_key":"stealpage/shots/smashsend.com/pg_xtngqcmvvebl/run_sapxu3hhimcl-desktop.png","phash":"866360606060f0e8","visual_delta":null,"captured_at":"2026-08-28T03:12:51.147Z"}],"history":[{"id":"run_frb1wo7ynefh","started_at":"2026-09-27T04:07:11.522Z","http_status":200,"fetcher":"direct","changed":false,"diff":{"added":0,"removed":36,"similarity":null},"word_count":511},{"id":"run_sapxu3hhimcl","started_at":"2026-08-28T03:12:44.052Z","http_status":200,"fetcher":"direct","changed":false,"diff":null,"word_count":547}],"citedBy":[]}