Events

Events and their registrations. Create the event your form or system knows about, register people into it, and move them through the roster — every write here fires exactly what the same action fires inside oToK: the reminders and automations, the event.attendance.changed webhook, lead scoring, and the Zoom registrant push that produces an attendee's personal join link.

Plan feature required: these endpoints require the Events feature on the workspace's plan. Without it, calls return 403 with error_code: "FEATURE_NOT_INCLUDED_IN_PLAN" — see feature-gated resource groups.

The event object

The registration object

The payment block. Present on every registration read (the list, the POST and the PATCH answers):

Status vocabulary. These five values are what oToK stores and what every surface returns — this API, the contact object's event_attendances[], and the event.attendance.changed webhook. On writes only, cancelled is accepted as an alias for unregistered; it is never returned, so a round-trip settles on the stored spelling.

GET /api/v1/events

curl "https://app.otok.io/api/v1/events?external_id=autumn-webinar-2026" \
  -H "Authorization: Bearer otok_live_abc123..."

Response 200: { "data": [ … ], "limit": 50, "offset": 0 }, newest start date first.

GET /api/v1/events/:id

Response 200: the event object. A non-UUID id → 400; an event in another workspace → 404 event_not_found.

POST /api/v1/events — upsert

Creates an event, or updates the one already carrying this external_id.

external_provider is not writable. It is how oToK knows a meeting belongs to a connected Zoom account, and a caller claiming it would make us push registrants at a meeting nobody owns.

curl -X POST "https://app.otok.io/api/v1/events" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Autumn webinar","external_id":"autumn-webinar-2026","start_at":"2026-10-06T14:00:00Z"}'

Response 201: the event object plus "duplicate": true | false.

Idempotency. Send the same external_id on every submission. The first call creates the event; the rest update it. There is no PATCH /v1/events/:id — the upsert is the update path.

Saved events

A saved event is a reusable event definition managed in the oToK app (Events → Saved events): a name plus a template of event-form defaults. Filing an event under one — by event_type_id, or by event_type_name when you only know the name — makes it show on that saved event's page, count in its statistics, and match automations scoped to it.

• Resolve-only. The API never creates a saved event, so a typo can't spawn a definition: an unknown id or name is refused. Archived saved events still resolve, so an integration keeps working until you re-point it.
• The template is not applied. Linking records where the event came from; send the fields you want on the event yourself.
• Both keys together must name the same saved event.
• On the external_id update path, sending neither key leaves the existing link untouched.

curl -X POST "https://app.otok.io/api/v1/events" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Weekly yoga — October","external_id":"yoga-2026-10","event_type_name":"Weekly yoga","start_at":"2026-10-06T18:00:00Z"}'

Response 201: the event object with "event_type": { "id": "…", "name": "Weekly yoga" }.

Priced events

With collect_payment_on_registration: true, a new registration — made through POST /v1/events/:id/attendances, by an automation, or in the app's registration dialogs — records a sale of the event's product (at the cycle's price when the event has a cycle with one) and sends the contact a payment link. The registration's payment block then reports the sale and the live link.

• It applies only to an event with a priced product that does not already grant attendance when sold, and only when the workspace's plan includes Sales, automatic sale recording is on, and a connected payment provider can issue payment links in the workspace currency. Otherwise registrations go through as usual with no sale and payment: null.
• There is no per-call opt-out: on an opted-in event every API registration is charged.
• Re-sending a registration that is already registered does not charge twice. Moving a registration back to registered from another status charges like a new registration.
• Unregistering someone whose sale is still unpaid cancels the sale and its payment link within a few minutes; money already paid is kept.
• Zoom-synced and imported registrations never charge.

POST /api/v1/events/:id/attendances — register

Registers a contact for the event, or sets their status directly.

curl -X POST "https://app.otok.io/api/v1/events/7f3c.../attendances" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
        "contact": { "name": "Jane Cohen", "email": "jane@example.com" },
        "acquisition": { "event_id": "webinar-signup-8891", "utm_source": "newsletter" }
      }'

Response 201: the registration object plus:

Registering the same person twice does nothing twice. One registration per person per event: a retried form submission answers the same row with created: false, and fires no automation a second time.

Zoom. On a Zoom-linked event, auto registers the attendee with Zoom exactly as an in-app registration does, so their personal join link exists and the reminders that carry it work. Use skip only when you registered them with Zoom yourself, and pass the join_url you were given — a blank value never clears a link that is already there.

Refusals.

An event that has merely ended still accepts registrations and roster marking.

GET /api/v1/events/:id/attendances

Response 200: { "data": [ … ], "limit": 50, "offset": 0 }, newest first.

PATCH /api/v1/attendances/:id

Moves an existing registration.

curl -X PATCH "https://app.otok.io/api/v1/attendances/9a1e.../" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"status":"attended"}'

Response 200: the registration object plus created: false and previous_status. On a priced event, moving someone back to registered charges like a new registration. The same refusals as the POST apply — an archived event takes no move, and a canceled one takes no move back to registered or waitlist.

Automations this fires

A registration made here is a registration like any other. It triggers the Event Activity automations (registered / unregistered / attended / waitlist), wakes any Wait-until-condition parked on the contact, records the lead-scoring signal, and emits event.attendance.changed — each exactly once per real status change, even if two of your servers call at the same moment.

Marking someone no_show records and scores like the rest, and wakes a waiting automation, but has no trigger of its own: automate no-shows with an Event Date/Time trigger targeting that status.

Related

• Contacts — the identity resolution the inline contact uses, and the acquisition object
• Webhooks — event.attendance.changed
• Sales — the sale a priced-event registration records