Eventera API

Introduction

The Eventera API is organized around REST. It has predictable, resource-oriented URLs, returns JSON, and uses standard HTTP verbs and status codes. All requests are made over HTTPS to a single base URL:

https://eventera.so/api/v1

Every request must be authenticated with an API key and the account must be on the Studio plan. Data is always scoped to the key's owner — a key can only ever read or modify that account's own events and attendees.

Quick start

1. Open Settings → Developer and create an API key. Copy it — it is shown only once. 2. Choose the scopes the key needs. 3. Make your first request:

curl "https://eventera.so/api/v1/events?status=published&limit=20" \
  -H "Authorization: Bearer sk_live_your_key"

Authentication

Authenticate by passing your secret key as a Bearer token in the Authorization header on every request. Keys look like sk_live_…. Keep them server-side and never expose them in browser or mobile client code.

Authorization: Bearer sk_live_your_key

If a key is missing or revoked you get 401. If the account is not on Studio you get 402. You can rotate or revoke a key at any time from the dashboard; rotating immediately invalidates the old secret.

Scopes

Each key holds a set of scopes. A request that needs a scope the key doesn't have returns 403 with the required scope named in the body.

Rate limits

Requests are rate-limited per IP address. When you exceed the limit you receive a 429 Too Many Requests response with a Retry-After header (in seconds). Back off for that many seconds before retrying. Design bulk syncs to page steadily rather than firing many requests in parallel.

Errors

Eventera uses conventional HTTP status codes. Errors return a JSON body with an error message (and sometimes extra context like required_scope).

{ "error": "This key is missing the required scope: checkin:write", "required_scope": "checkin:write" }

Pagination

List endpoints accept limit (default 50, max 100) and offset (default 0). Every list response includes a pagination object so you know when to stop.

{
  "data": [ /* … */ ],
  "pagination": { "limit": 50, "offset": 0, "total": 128 }
}

To fetch the next page, add limit to your current offset. Keep going while offset + data.length < total.

Events

An event object includes its status, public slug, schedule, and view/download counts. The single-event endpoint also returns its ticket types.

List events

Query parameters: status (draft · published · archived), limit, offset. Requires events:read.

curl "https://eventera.so/api/v1/events?status=published&limit=20" \
  -H "Authorization: Bearer sk_live_your_key"

Response:

{
  "data": [
    {
      "id": "e_123",
      "name": "Tech Summit",
      "slug": "tech-summit-a1b2",
      "status": "published",
      "title": "Tech Summit 2026",
      "starts_at": "2026-09-01T09:00:00Z",
      "ends_at": "2026-09-01T17:00:00Z",
      "timezone": "Africa/Nairobi",
      "venue_name": "Nairobi Expo",
      "is_online": false,
      "view_count": 1240,
      "download_count": 312,
      "created_at": "2026-06-01T10:00:00Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 1 }
}

Retrieve an event

Requires events:read. Returns the event plus its ticket_types.

curl "https://eventera.so/api/v1/events/EVENT_ID" \
  -H "Authorization: Bearer sk_live_your_key"

{
  "id": "e_123",
  "name": "Tech Summit",
  "slug": "tech-summit-a1b2",
  "status": "published",
  "title": "Tech Summit 2026",
  "description": "A day of talks…",
  "starts_at": "2026-09-01T09:00:00Z",
  "venue_name": "Nairobi Expo",
  "ticket_types": [
    { "id": "t_1", "name": "General", "price": 25, "currency": "USD",
      "quantity_total": 500, "quantity_sold": 188 }
  ]
}

Registrations

Registrations are the attendees who signed up for an event. Fields include contact details, ticket type, payment status, check-in time, and any custom form fields collected at registration.

List an event's registrations

Query: status (pending · confirmed · checked_in · cancelled · refunded), limit, offset. Requires registrations:read.

curl "https://eventera.so/api/v1/events/EVENT_ID/registrations?status=confirmed&limit=50" \
  -H "Authorization: Bearer sk_live_your_key"

{
  "data": [
    {
      "id": "r_789",
      "event_id": "e_123",
      "attendee_name": "Ada Lovelace",
      "attendee_email": "ada@example.com",
      "attendee_phone": "+254700000000",
      "status": "confirmed",
      "payment_status": "paid",
      "ticket_type": "General",
      "amount_paid": 25,
      "currency": "USD",
      "checked_in_at": null,
      "custom_fields": { "company": "Analytical Engines" },
      "qr_code_token": "abc123",
      "created_at": "2026-07-01T12:00:00Z"
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "total": 1 }
}

Retrieve a registration

Requires registrations:read. Returns the same shape as a list item.

curl "https://eventera.so/api/v1/registrations/REG_ID" \
  -H "Authorization: Bearer sk_live_your_key"

Check-in

Check an attendee in from your own scanner or kiosk. Identify them by their qr_code_token (from the ticket QR) or their registration_id. The call is idempotent — checking in someone who is already checked in returns already_checked_in: true with the original timestamp.

Requires checkin:write. Body: { qr_code_token } or { registration_id }.

curl -X POST "https://eventera.so/api/v1/checkin" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "qr_code_token": "abc123" }'

{
  "ok": true,
  "already_checked_in": false,
  "registration_id": "r_789",
  "attendee_name": "Ada Lovelace",
  "checked_in_at": "2026-09-01T09:12:00Z"
}

Card rendering

Generate an Eventera Card as a PNG. Provide a card variantId and the fields to fill its text zones; optionally a photoDataUrl (base64) for a photo zone. The response body is the PNG binary. Requires full_access.

curl -X POST "https://eventera.so/api/v1/render" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "variantId": "VARIANT_ID",
    "fields": { "name": "Ada Lovelace", "title": "Speaker" }
  }' --output card.png

Returns Content-Type: image/png. On error you get a JSON body with an error field instead.

Webhooks

Rather than polling, subscribe to events and Eventera will POST to your URL when they happen. Add a webhook in Settings → Developer and pick the events you want:

Each delivery is a JSON POST that includes an X-Eventera-Signature header — sha256= followed by the HMAC-SHA256 of the raw request body, keyed with your webhook secret. Verify it before trusting the payload:

# Signature is sent in the X-Eventera-Signature header:
#   sha256=<hex HMAC-SHA256 of the raw body using your webhook secret>

Your endpoint should respond 2xx quickly. Non-2xx responses count as failures and are surfaced in the dashboard; only HTTPS URLs that resolve to public hosts are accepted.

Support

Questions or something not behaving as documented? Email support@eventera.so or reach us from the contact page. Manage your keys and webhooks any time in Settings → Developer.