---
title: Quick Start Guide
slug: docs/quick-start-guide
createdAt: 2026-09-22T06:56:07.800Z
---

This guide gets you from nothing to a working API request. You create an Integration Consumer, get an access token, then set up whichever APIs you need. Each step links to a detailed article where you need more depth.

Jomablue APIs are organised around Integration Consumers. An Integration Consumer can access the Ingest API, the Updates API, and the Event Discovery API, so you set up authentication once and reuse it across all three. You can have multiple Integration Consumers to scope access that different systems have, if desired.

## Before you start

You need:

- Portal access with the trusted-admin-integrator or owner role.
- The system you are connecting (for example a CRM, registration platform, or exhibitor database) ready to send or receive data.

## Step 1: Create a Consumer and get a long-lived token

An Integration Consumer represents a system that connects to the Jomablue APIs. It holds its own access scope and its own tokens.

1. Open the **Settings** tab, then the **Integration Consumers** tab.
2. Add a Consumer, name it after the connecting system, and leave it **active**.
3. Configure its access scope. Grant only the APIs and endpoints the connecting system needs.
4. Generate a long-lived token and copy it. The token is shown only once, so store it securely.

For the full walkthrough, including scoping and token rotation, see [Integration Consumers](https://apidocs.jomablue.com/docs/integration-consumers).

![](https://api.archbee.com/api/optimize/DHKOH0YwbTGPz2KqdQjth/hB7N5J6AtW7KwsEuzqCTG_cleanshot-2026-09-22-at-171614.png)

## Step 2: Exchange the long-lived token for an access token

API requests use a short-lived access token, not the long-lived token. Exchange one for the other at the auth endpoint:

:::BlockQuote
curl --request POST \\
&#x20; \--url https\://your-instance.jomablue.com/integration/api/auth \\
&#x20; \--header 'Authorization: Bearer \<long-lived-token>' \\
&#x20; \--header 'User-Agent: your-system-name' \\
&#x20; \--header 'Accept: application/json' \\
&#x20; \--header 'Content-Type: application/json'
:::

The short-lived access token is returned in the data field:

:::BlockQuote
\{
&#x20; "success": true,
&#x20; "data": "\<short-lived-token>",
&#x20; "included": \[]
}
:::

Send that token as the Bearer token on your API requests. When it expires, request a new one from the auth endpoint with your long-lived token. The same auth endpoint serves all three APIs.

For headers, examples, and token handling, see [Ingest API Authentication](https://apidocs.jomablue.com/docs/TSQe-authentication) or [Updates API Authentication](https://apidocs.jomablue.com/docs/authentication).

## The APIs you can use

Your access token works with the three APIs below. Grant each one on the Consumer in Step 1.

| API                 | What it does                                                                                      | Direction       |
| ------------------- | ------------------------------------------------------------------------------------------------- | --------------- |
| Ingest API          | Receives data from your systems and turns it into People, Sessions, and Vendors in your event.    | Into Jomablue   |
| Updates API         | Exposes People, Sessions, Vendors, and related resources at a stable URL your systems poll.       | Out of Jomablue |
| Event Discovery API | Lists the events your Consumer can access, so your systems can find the right event to work with. | Out of Jomablue |

## Set up the Event Discovery API

Use the Event Discovery API to list the events your Consumer can access. There is no endpoint to create. Grant it on the Consumer in Step 1, then call it with your access token:

:::BlockQuote
curl --request GET \\
&#x20; \--url https\://your-instance.jomablue.com/integration/api/events \\
&#x20; \--header 'Authorization: Bearer \<short-lived-token>' \\
&#x20; \--header 'User-Agent: your-system-name' \\
&#x20; \--header 'Accept: application/json'
:::

The response lists the events available to your Consumer. Use it to resolve which event your other API calls should target.

## Set up the Ingest API

Use the Ingest API to send data in. You create an ingest endpoint, give it a field map that reads your payload, then post payloads to its URL.

1. Create an ingest endpoint in the portal and choose its type: People, Session, or Vendor.
2. Add a field map. The field map tells the endpoint how to read your payload and which Jomablue fields to write.
3. Optionally add validation rules, so payloads that do not fit are rejected before any record is created.
4. Copy the endpoint URL and post your payload to it with your access token:

:::BlockQuote
curl --request POST \\
&#x20; \--url https\://your-instance.jomablue.com/api/webhook/ingest/&#x7B;ingest-endpoint-uuid} \\
&#x20; \--header 'Authorization: Bearer \<short-lived-token>' \\
&#x20; \--header 'User-Agent: your-system-name' \\
&#x20; \--header 'Accept: application/json' \\
&#x20; \--header 'Content-Type: application/json' \\
&#x20; \--data '\{ "contact": \{ "first\_name": "Jane", "last\_name": "Doe", "email": "jane.doe\@example.com" } }'
:::

A 200 response means the payload was accepted and queued. For the full walkthrough, see [Creating an Ingest API Endpoint](https://apidocs.jomablue.com/docs/creating-an-endpoint). For complete, copy-and-adapt field maps per type, see [Ingest API Mapping Examples](https://apidocs.jomablue.com/docs/wUWG-mapping-examples).

## Set up the Updates API

Use the Updates API to read data back out. You create an endpoint, add a mapping that shapes the payload, then poll its URL.

1. Create an Updates API endpoint in the portal and add a type, for example People.
2. Add a mapping. The mapping is the JSON shape you want out, with a merge tag in each value that the endpoint fills per record at send time.
3. Copy the endpoint URL and call it with your access token:

:::BlockQuote
curl --request GET \\
&#x20; \--url https\://your-instance.jomablue.com/updates/api/&#x7B;endpoint-uuid}/event-people \\
&#x20; \--header 'Authorization: Bearer \<short-lived-token>' \\
&#x20; \--header 'User-Agent: your-system-name' \\
&#x20; \--header 'Accept: application/json'
:::

A successful response returns an array of records shaped by your mapping. For the full walkthrough, see [Creating an Updates API Endpoint](https://apidocs.jomablue.com/docs/ER7m-creating-an-endpoint). For mapping templates per resource, see [Updates API Mapping Examples](https://apidocs.jomablue.com/docs/mapping-examples).

## Next steps

- Scope each Consumer tightly and rotate tokens on a schedule. See [Creating an Integration Consumer](https://apidocs.jomablue.com/docs/integration-consumers).
- Build your Ingest field maps and Updates mappings from the worked examples rather than a blank page. See [Ingest API Mapping Examples](https://apidocs.jomablue.com/docs/wUWG-mapping-examples)] and [Updates API Mapping Examples](https://apidocs.jomablue.com/docs/mapping-examples).
