---
title: Event Discovery API
slug: docs/event-discovery-api
createdAt: 2026-04-21T19:38:51.726Z
---

## 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

:::BlockQuote
GET /integration/api/events
:::

## 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).

:::BlockQuote
Authorization: Bearer \<instance-level-token>
:::

## 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):**

:::BlockQuote
curl -X GET "[https://instance.jomablue.com/integration/api/events?page-size=20\&only-active\&only-upcoming](https://instance.jomablue.com/integration/api/events?page-size=20\&only-active\&only-upcoming)" \\
&#x20; -H "Accept: application/json" \\
&#x20; -H "Content-Type: application/json" \\
&#x20; -H "Authorization: Bearer \<token>"
:::

**Fetch the next page using a cursor:**

:::BlockQuote
curl -X GET "[https://instance.jomablue.com/integration/api/events?cursor=\<cursor-string](https://instance.jomablue.com/integration/api/events?cursor=\<cursor-string)>" \\
&#x20; -H "Accept: application/json" \\
&#x20; -H "Content-Type: application/json" \\
&#x20; -H "Authorization: Bearer \<token>"
:::

## Response Format

:::BlockQuote
\{
&#x20; "results": 1,
&#x20; "data": \[
&#x20;   \{
&#x20;     "id": "instance-name/event/1155",
&#x20;     "name": "Global Tech Summit 2026",
&#x20;     "start\_time": "2026-12-01T00:00:00.000000Z",
&#x20;     "finish\_time": "2026-12-05T00:00:00.000000Z",
&#x20;     "description": "Annual technology conference and exhibition.",
&#x20;     "venue\_name": "Melbourne Convention Centre",
&#x20;     "venue\_address": "1 Convention Centre Pl, South Wharf VIC 3006",
&#x20;     "timezone": "Australia/Melbourne",
&#x20;     "status": "active",
&#x20;     "metadata": \{
&#x20;       "region": "north-america",
&#x20;       "tier": "flagship"
&#x20;     },
&#x20;     "created\_at": "2026-06-15T09:30:00.000000Z",
&#x20;     "updated\_at": "2026-09-20T14:12:45.000000Z",
&#x20;     "programs": \[
&#x20;       \{
&#x20;         "program\_uid": "6ea0f651-2641-4e3d-9a93-0cd1f704cfb1",
&#x20;         "program\_name": "Main Conference Registration"
&#x20;       },
&#x20;       \{
&#x20;         "program\_uid": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
&#x20;         "program\_name": "VIP Executive Program"
&#x20;       }
&#x20;     ],
&#x20;     "ingest\_urls": \[
&#x20;       \{
&#x20;         "uuid": "546cc552-e6bc-4e16-b90e-554513338c13",
&#x20;         "type": "EventPerson",
&#x20;         "name": "CRM People Ingest",
&#x20;         "url": "[https://instance-name.jomablue.com/api/webhook/ingest/546cc552-e6bc-4e16-b90e-554513338c13](https://instance-name.jomablue.com/api/webhook/ingest/546cc552-e6bc-4e16-b90e-554513338c13)"
&#x20;       },
&#x20;       \{
&#x20;         "uuid": "7a8b9c0d-1234-5678-abcd-ef0123456789",
&#x20;         "type": "Session",
&#x20;         "name": "Session Ingest",
&#x20;         "url": "[https://instance-name.jomablue.com/api/webhook/ingest/7a8b9c0d-1234-5678-abcd-ef0123456789](https://instance-name.jomablue.com/api/webhook/ingest/7a8b9c0d-1234-5678-abcd-ef0123456789)"
&#x20;       }
&#x20;     ],
&#x20;     "updates\_endpoints": \[
&#x20;       \{
&#x20;         "uuid": "0d6ec355-776e-4055-8a70-56ef305cadb8",
&#x20;         "name": "CRM Updates Integration",
&#x20;         "urls": \[
&#x20;           \{
&#x20;             "type": "Lead",
&#x20;             "url": "[https://instance-name.jomablue.com/updates/api/0d6ec355-776e-4055-8a70-56ef305cadb8/vendor-leads](https://instance-name.jomablue.com/updates/api/0d6ec355-776e-4055-8a70-56ef305cadb8/vendor-leads)"
&#x20;           },
&#x20;           \{
&#x20;             "type": "EventPerson",
&#x20;             "url": "[https://instance-name.jomablue.com/updates/api/0d6ec355-776e-4055-8a70-56ef305cadb8/event-people](https://instance-name.jomablue.com/updates/api/0d6ec355-776e-4055-8a70-56ef305cadb8/event-people)"
&#x20;           },
&#x20;           \{
&#x20;             "type": "Session",
&#x20;             "url": "[https://instance-name.jomablue.com/updates/api/0d6ec355-776e-4055-8a70-56ef305cadb8/sessions](https://instance-name.jomablue.com/updates/api/0d6ec355-776e-4055-8a70-56ef305cadb8/sessions)"
&#x20;           },
&#x20;           \{
&#x20;             "type": "SessionParticipation",
&#x20;             "url": "[https://instance-name.jomablue.com/updates/api/0d6ec355-776e-4055-8a70-56ef305cadb8/session-participation](https://instance-name.jomablue.com/updates/api/0d6ec355-776e-4055-8a70-56ef305cadb8/session-participation)"
&#x20;           },
&#x20;           \{
&#x20;             "type": "Vendor",
&#x20;             "url": "[https://instance-name.jomablue.com/updates/api/0d6ec355-776e-4055-8a70-56ef305cadb8/vendors](https://instance-name.jomablue.com/updates/api/0d6ec355-776e-4055-8a70-56ef305cadb8/vendors)"
&#x20;           }
&#x20;         ]
&#x20;       }
&#x20;     ]
&#x20;   }
&#x20; ],
&#x20; "cursor": "eyJjcmVhdGVkX2F0Ijo...",
&#x20; "page\_size": 20,
&#x20; "filters": \{
&#x20;   "only\_active": true,
&#x20;   "only\_upcoming": true
&#x20; },
&#x20; "instance": "instance-name"
}
:::

## 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:

1. Poll /integration/api/events to discover available events and their programs.
2. Use the ingest\_urls from the response to know where to send people, session, or vendor data for each event.
3. 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.
4. 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.
