hi-events-api

Hi.Events API Reference

What we know about the Hi.Events REST API from building the Guild Hall integration. Hi.Events doesn’t publish comprehensive API docs — this is derived from their Postman collection and live sandbox responses.

Connection

• Base URL: https://api.hi.events
• App URL: https://app.hi.events
• Auth: JWT via POST /auth/login with email/password. Token returned in response body, sent as Cookie: token=<jwt>. Expires in ~7 days. Refresh via POST /auth/refresh.
• No long-lived API keys — must store login credentials and re-authenticate periodically.

Event object (actual response)

From GET /organizers/{id}/events:

{
  "id": 7016,
  "title": "Second Event",
  "category": "WORKSHOP",
  "description": null,
  "start_date": "2026-04-01T01:00:00.000000Z",
  "end_date": null,
  "status": "ARCHIVED",
  "lifecycle_status": "ONGOING",
  "currency": "USD",
  "timezone": "America/New_York",
  "slug": "second-event",
  "images": [],
  "settings": {
    "support_email": "hello@dungeonbooks.com",
    "is_online_event": false,
    "location_details": null,
    "homepage_primary_color": "#8b5cf6",
    "homepage_background_color": "#ffffff",
    "payment_providers": ["STRIPE"],
    "...": "many more settings fields"
  },
  "organizer": {
    "id": 5839,
    "name": "Drafts",
    "email": "hello@dungeonbooks.com",
    "slug": "drafts",
    "status": "DRAFT"
  }
}

Key fields

Field	Type	Notes
id	number	Unique event ID
title	string	Event name
slug	string	URL slug, auto-generated from title, updates when title changes
description	string/null	HTML content, can be very long
start_date	ISO string	UTC timestamp
end_date	ISO string/null	Optional
status	string	"DRAFT", "ARCHIVED", etc.
lifecycle_status	string	"UPCOMING", "ONGOING", "ENDED"
timezone	string	IANA timezone (e.g., "America/New_York")
category	string	"WORKSHOP", "OTHER", etc.
images	array	[{ url, type }] — empty if no images uploaded
settings	object	Large config object with colors, payment, etc.
organizer	object	Nested organizer info

Event URL format

https://app.hi.events/event/{id}/{slug}

• The ID is what resolves the event. The slug is required (bare /event/{id} returns 404) but any string works after the ID.
• The real slug is available in the API response.

Endpoints we use

Method	Path	Purpose
POST	/auth/login	Get JWT token
POST	/auth/refresh	Refresh expiring token
GET	/organizers/{id}/events	List events for an organizer
GET	/events/{id}	Single event detail
GET	/events/{id}/attendees	List attendees
GET	/events/{id}/check_in_stats	Check-in counts

Pagination

List endpoints return Laravel-style pagination:

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 42,
    "last_page": 3
  }
}

Query params: page, per_page. Also supports sort and filtering by allowed_filter_fields listed in the meta.

Sorting

Events support sorting by: start_date, end_date, created_at, updated_at. Default sort is start_date ascending.

Endpoints we don’t use yet

Method	Path	Potential use
GET	/events/{id}/images	Event images for richer cards
GET	/events/{id}/products	Ticket types/prices
GET	/events/{id}/stats	Attendance/revenue stats
GET	/public/events/{id}	Public event detail (no auth needed)

Embed widget

Hi.Events provides a JavaScript widget for embedding ticket purchase:

<script async src="https://app.hi.events/widget.js"></script>
<div data-hievents-id="7141"
     data-hievents-primary-color="#8b5cf6"
     data-hievents-widget-type="widget"
     data-hievents-locale="en"
     class="hievents-widget"></div>

This only shows the ticket selection/purchase flow — not the full event page. Not useful for the Guild Hall’s “upcoming events” section, but could be embedded on a dedicated event detail page in the future.

Potential improvements

• Event images: The images array on events could enrich the Guild Hall cards. Requires events to have images uploaded in Hi.Events.
• Category badges: Show category (WORKSHOP, OTHER, etc.) as a badge on event cards.
• Location info: settings.location_details and settings.is_online_event could distinguish in-person vs online events.
• Public API: GET /public/events/{id} doesn’t require auth — could be used for unauthenticated event pages if needed.
• Filtering: The API supports filtering by status and start_date server-side, which could replace our client-side filtering in getUpcomingEvents.
• Webhook for event changes: Currently we only handle checkin.created webhooks. Hi.Events may also send events for event creation/updates, which could trigger cache invalidation.

Environment variables

HI_EVENTS_API_URL=https://api.hi.events     # optional, this is the default
HI_EVENTS_EMAIL=<login email>
HI_EVENTS_PASSWORD=<login password>
HI_EVENTS_ORGANIZER_ID=5839                  # sandbox organizer
HI_EVENTS_WEBHOOK_SECRET=<webhook HMAC key>  # for inbound webhooks (separate from API)

Related

• guild-hi-events-integration — webhook integration design
• hi-events-webhook-testing — E2E testing guide for webhooks