Connecting Ombea to Your BI Tool via API

This is a conceptual guide to help you fetch data using the Ombea API and bring it into your BI tool. Due to different data structures and various ways of working with BI platforms, this is not a one-size-fits-all implementation tutorial. Please refer to this guide together with the API documentation found here.

Understanding Key Concepts

Before we dive in, it’s important to understand a few core concepts used in the Ombea platform and in the API.

Touchpoint
Touchpoints are the building blocks of Ombea. A Touchpoint is a specific point where feedback is collected – a place in a store or office, a page on a website, or a screen in an app.
Organisation Node (OrgNode)
Touchpoints belong to either a Location or a Website and these can be grouped into folders. All of these are referred to programmatically as an Organisation Node.
Stream
A Stream is the central unit that defines which questions are asked, when and how, and from which Touchpoints. Think of it as a survey on steroids.
Block
Each question in a Stream is referred programmatically to as a Block.

Getting Started: Fetching Responses

Every time a respondent answers a question, their response is submitted. You can fetch these responses by targeting a specific Stream.

Fetch All Responses from a Stream

Use the following POST endpoint: /api/v2/streams/{streamId}/submissions/blockResponses
You can find the streamId in the URL when viewing or editing a Stream in Ombea: https://insights.ombea.com/admin/places

Response Fields of Interest

sId: Submission ID (to group responses from the same respondent)
bId: Block ID (to group responses by question)
tpId: Touchpoint ID (to group responses by where feedback was given)
dt: The timestamp in the response may not represent when the answer was submitted. It can reflect the time of the actual experience (e.g., purchase or pickup). Confirm the timestamp definition with the Stream creator before using it in time-based analysis.

Fetching Only New Responses

You generally don’t want to fetch everything every time. You have two options:
Use a Time Filter: You can specify a time range in your request. However, this reflects when the user submitted the response - not when it was received by Ombea. This can be unreliable for e.g., feedback terminals, which might sync later due to offline use (4G dropouts, etc.).
Use Sequence ID (Recommended): Each response has a Sequence ID, which reflects the order it was received by Ombea servers. This is the safest method to ensure no data is missed.

Steps for using Sequence ID:

Formulating the request by specifing startSequenceId as the last Sequence ID from your last successful fetch, set startSequenceIdInclusive to false and sort to sequenceId.
Make sure to follow the pagination until no more data is returned, and store the last Sequence ID.
Repeat.
This ensures you never miss a delayed submission.

Mapping IDs to Human-Readable Data

Once you have the responses, you’ll likely want to associate them with locations, question names, etc., in your BI tool.

Map tpId to Locations or Websites

To fetch a list of Touchpoints under a specific folder, use this GET endpoint: /api/v2/touchpoints
You’ll need to specify organisationNodeId, which is provided by Ombea Support. In the response, you’ll get the ID of the Touchpoint and the parentOrgNodeName which is the Name of the Location or Website the Touchpoint belongs to.

Use a naming convention like #StoreID# Store Name for Locations/Websites in Ombea to simplify matching within your BI tool.

Map bId to Question Titles

To get a list of questions (Blocks) and their current titles in a Stream, use this GET endpoint: /api/v2/streams/{streamId}
In the response, look for the block items, which will give you the ID of the Block and the current title of the question.
This is helpful for reports where questions may change over time.

Summary

Goal	API Endpoint
Fetch responses from a Stream	POST /api/v2/streams/{streamId}/submissions/blockResponses
Get all Touchpoints	GET /api/v2/touchpoints (with organisationNodeId)
Get Stream metadata	GET /api/v2/streams/{streamId}

Using this approach, you can reliably bring Ombea feedback data into your BI tool, structure it properly, and ensure your dashboards reflect the latest customer insights.

For questions or help with your implementation, contact support@ombea.com.

Updated on: 13/05/2025