Help
Search

Connect your BI tool via the API

Pull your feedback data into Power BI, Tableau, Looker or another tool.

Last checked: 4 min read
Before you begin

With the Yump API you can pull your responses into your own BI tool. Combine them with your other business data and build the reports you need. This page covers the concepts: what data you get, how to fetch it and how to turn IDs into names. Every BI tool is different, so the tool-specific steps are not covered here.

Tip

For regular pulls, use the sequence ID, not the time. Some responses reach Yump later than they were given. The sequence ID catches them.

Get access

Contact Yump to get your API credentials: a client ID and an API token. Every request must send both, in the headers X-OMBEA-Client-Id and X-OMBEA-Api-Token. A POST request also needs the header Content-Type: application/json.

The API runs at https://insights.ombea.com. The data endpoints below start with /api/v2. ExpressPod results are under /api/reporting/v1.

The full reference is at https://res.ombea.com/api/docs/. The app also shows it at https://insights.ombea.com/api-docs/.

Key concepts

  • Touchpoint: where feedback is collected, for example an ExpressPod or a feedback link.
  • Organisation node: in the API, locations, websites and folders are called organisation nodes.
  • Stream: what you set up to collect feedback: its questions, settings and touchpoints.
  • Block: in the API, each question in a stream is a block.

Find your streams

GET /api/v2/streams

This lists your streams with their IDs and names. Add organisationNodeId to list only the streams of one location or folder.

Fetch responses

POST /api/v2/streams/{streamId}/submissions/blockResponses

Send the query as JSON in the request body. All fields are optional:

FieldWhat it does
startDateTime, endDateTimeLimit the responses to a time span.
organisationNodeIdOnly responses from this node and the nodes below it.
touchpointIdsOnly responses from these touchpoints.
blockIdsOnly answers to these questions.
startSequenceIdStart from this sequence ID.
startSequenceIdInclusiveWhether to include the response with the start sequence ID. Default: true.

Add these to the URL to control the pages:

ParameterWhat it does
limitResponses per page. Default 1,000, at most 5,000.
sortdateTime or sequenceId. Put a hyphen in front for descending order, for example -dateTime.
pageTokenThe nextPageToken from the previous page. Pass it back unchanged. It is text, even where the reference says it is a number.

Each page has items, totalCount and nextPageToken.

Response fields
FieldWhat it means
sidThe submission ID: all answers given in one go.
tpIdThe touchpoint that collected the response.
br.bidThe block (question) that this answer belongs to.
br.dtWhen the answer was given.
br.seqIdThe sequence ID: when the answer reached Yump. Unique for each answer.
ctxThe survey context, for example the parameters of a feedback link. Can be empty.

Fetch only new responses

For a regular pull, for example every hour, fetch only what is new since the last pull.

Sequence ID (recommended)
  1. Store the highest sequence ID from your last pull. Store it as text: the number is too big for some tools.
  2. On the next pull, set startSequenceId to that value.
  3. Set startSequenceIdInclusive to false, so you skip the answer you already have.
  4. Set sort to sequenceId.
  5. Fetch page after page with pageToken until there is no nextPageToken.
Time filter

You can also filter by time with startDateTime. This can miss answers. An ExpressPod can send its button presses up to an hour after they were given, so they arrive with a time in the past.

Turn IDs into names

Touchpoint IDs to names
GET /api/v2/touchpoints

Add organisationNodeId or streamId. The result lists each touchpoint's ID and name, with the name of its location and, when you have access to it, its folder.

Block IDs to question text
GET /api/v2/streams/{streamId}

This returns the stream with its blocks. Each block has its ID and its question text.

Quick reference

What you wantEndpoint
List your streamsGET /api/v2/streams
Fetch responses from a streamPOST /api/v2/streams/{streamId}/submissions/blockResponses
Get one submissionGET /api/v2/submissions/{submissionId}
List touchpointsGET /api/v2/touchpoints
Get a stream and its questionsGET /api/v2/streams/{streamId}

If you get stuck, contact Yump support.

Did this help?