Event Discovery API
Event Discovery API
The Event Discovery API provides a read-only endpoint for listing all events within a Jomablue instance. It is designed for third-party systems - such as CRM platforms, marketing automation tools, or scheduling systems - to programmatically discover events, their associated programs, and their Ingest endpoint and Updates endpoint URLs.
Endpoint
Authentication
Requests must include a valid instance-level bearer token in the Authorization header. This is the same token generated when authenticating via the Updates API (see Instance Settings in the Jomablue Portal).
Query Parameters
Parameter | Required | Description |
|---|---|---|
page-size | No | Number of results per page. Maximum and default is 100. |
only-active | No | When present, filters results to only include events with an active status. No value required — include the parameter name to enable. |
only-upcoming | No | When present, filters results to only include events whose finish_time has not yet passed. No value required — include the parameter name to enable. |
cursor | No | Cursor string from a previous response, used to retrieve the next page of results. When a cursor is supplied, all other parameters are ignored — the original request's parameters are preserved in the cursor. |
Pagination
The endpoint uses cursor-based pagination. Each response includes a cursor value that can be passed in subsequent requests to retrieve the next page. When using a cursor, filter and page-size parameters from the original request are preserved automatically — any additional parameters supplied alongside the cursor are ignored.
Pagination order is by descending created_at time, with id as a tiebreaker for events created at the same time.
Example Requests
List active, upcoming events (20 per page):
Fetch the next page using a cursor:
Response Format
Response Fields
Top-level
Field | Type | Description |
|---|---|---|
results | Integer | Number of event records returned in this response. |
data | Array | Array of event objects (see below). |
cursor | String | Opaque cursor string to pass as a query parameter to retrieve the next page. null if there are no more results. |
page_size | Integer | The page size used for this request. |
filters | Object | Shows which filters were applied to this request. |
instance | String | The Jomablue instance name. |
Event Object
Field | Type | Description |
|---|---|---|
id | String | Event identifier in instance/resource/id format (e.g. my-instance/event/1155). |
name | String | Event name. |
start_time | String | Event start time as ISO 8601 datetime in UTC. |
finish_time | String | Event finish time as ISO 8601 datetime in UTC. |
description | String | Event description text. |
venue_name | String | Name of the event venue. |
venue_address | String | Full address of the event venue. |
timezone | String | IANA timezone identifier for the event (e.g. Australia/Sydney, America/Los_Angeles). |
status | String | Current event status (e.g. active). |
metadata | Object | Arbitrary key-value metadata associated with the event. Structure varies per instance configuration. |
created_at | String | ISO 8601 datetime (UTC) when the event was created. |
updated_at | String | ISO 8601 datetime (UTC) when the event was last updated. |
programs | Array | List of programs associated with the event (see below). |
ingest_urls | Array | List of ingest endpoints configured for this event (see below). |
updates_endpoints | Array | List of Updates API integrations configured for this event, including the URLs to poll for each resource type (see below). |
Program Object
Field | Type | Description |
|---|---|---|
program_uid | String | UUID of the program. |
program_name | String | Display name of the program. |
Ingest URL Object
Field | Type | Description |
|---|---|---|
uuid | String | UUID of the ingest endpoint. |
type | String | The ingest endpoint type (e.g. EventPerson, Session, Vendor). |
name | String | Display name of the ingest endpoint. |
url | String | Full URL to send ingest payloads to for this endpoint. |
Updates Endpoints Object
Field | Type | Description |
|---|---|---|
uuid | String | UUID of the Updates API integration. |
name | String | Display name of the Updates API integration. |
urls | Array | List of Updates API URLs for this integration, one per resource type. Each item contains a type — the resource type the URL serves (Lead, EventPerson, Session, SessionParticipation, Vendor) — and a url — the full Updates API URL to poll for that resource type. |
Common Integration Pattern
The Event Discovery API is typically used as the discovery step in an integration workflow. A third-party system uses this endpoint to:
- Poll /integration/api/events to discover available events and their programs.
- Use the ingest_urls from the response to know where to send people, session, or vendor data for each event.
- Use the updates_endpoints URLs from the response to poll the Updates API for each resource type (e.g. event-people, sessions, vendor-leads), to read back data that has been created or modified in Jomablue.
- Use the Ingest API to write back external identifiers (e.g. CRM Campaign IDs) via organisation_uid updates.
Notes
- All datetime values in the response are in UTC (ISO 8601 with Z suffix).
- Archived events are included by default. Use only-active to exclude them.
- Historical events (past finish_time) are included by default. Use only-upcoming to exclude them.
- All programs for an event are returned, including those with no people yet — this is by design, as programs (e.g. campaigns) are often created before attendees are assigned.
- The metadata field structure is configurable per instance and may vary.