Examples use a fictional festival, summer-fest. Sign in at events.grofomo.com and they switch to your own events.

Mailing-list signup

POST/v1/events/{slug}/subscribe

Post an email address straight into the organiser's mailing list, so your site can host its own signup block rather than embedding a hosted form.

Consent is the organiser's to collect. Only submit an address when the visitor has actively asked to hear from them — this endpoint records a signup, it does not make one lawful.

Requires a Cloudflare Turnstile token, so it is not usable from a script.

Send ?surface=webOmit it and the request is treated as coming from the mobile app, which is gated on a different visibility setting — so a perfectly live event can return 404 not_found for no visible reason.

Bot check requiredThis write needs a Cloudflare Turnstile token, so it cannot be driven from a script. Render the widget in your form and post the token it produces.

Request

curl -sS \
  -X POST \
  -H 'X-Grofomo-Key: pk_live_YOUR_PUBLISHABLE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"email":"fan@example.com","name":"Alex Doe","turnstileToken":"<token from the Turnstile widget>"}' \
  'https://api.grofomo.com/v1/events/summer-fest/subscribe?surface=web'

Path parameters

slugstringrequired: The event's URL slug. Globally unique, and fixed once the event is created. Example: `summer-fest`.

Query parameters

surface'web'required: Must be `web` for a website. Omit it and you get the mobile-app surface, which is gated on a different visibility setting — so a perfectly live event can return 404. Example: `web`.

Response

200 OK

{
  "apiVersion": 1,
  "data": {
    "ok": true,
    "submissionId": "a7b8c9d0-e1f2-4345-8678-9abcdef01234"
  }
}

okbooleanmay be absent: Always `true` on success.
submissionIduuidmay be absent: Identifies this signup, so a second step can attach a phone number within the hour.

Errors

unauthorizedHTTP 401: No key was sent and the organiser requires one — or the key is invalid, revoked, belongs to another organisation, or is scoped to a different event.
origin_not_allowedHTTP 403: Your site's domain is not on the organiser's allowed list. Browser calls only: a server sends no Origin header and is unaffected.
not_foundHTTP 404: No event with that slug is published on this surface. Check the slug, and check you sent `?surface=web`.
turnstile_failedHTTP 400: The bot-check token was missing or invalid.
bad_requestHTTP 400: The email address was not valid.

Notes

Rate limited to roughly 30 requests per minute per caller. Guidance, not a contract — see caching and rate limits.
Cache-Control: no-store