Connect your BI tool via the API
Pull your feedback data into Power BI, Tableau, Looker or another tool.
- You need admin access to do this. About roles
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.
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:
| Field | What it does |
|---|---|
startDateTime, endDateTime | Limit the responses to a time span. |
organisationNodeId | Only responses from this node and the nodes below it. |
touchpointIds | Only responses from these touchpoints. |
blockIds | Only answers to these questions. |
startSequenceId | Start from this sequence ID. |
startSequenceIdInclusive | Whether to include the response with the start sequence ID. Default: true. |
Add these to the URL to control the pages:
| Parameter | What it does |
|---|---|
limit | Responses per page. Default 1,000, at most 5,000. |
sort | dateTime or sequenceId. Put a hyphen in front for descending order, for example -dateTime. |
pageToken | The 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
| Field | What it means |
|---|---|
sid | The submission ID: all answers given in one go. |
tpId | The touchpoint that collected the response. |
br.bid | The block (question) that this answer belongs to. |
br.dt | When the answer was given. |
br.seqId | The sequence ID: when the answer reached Yump. Unique for each answer. |
ctx | The 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)
- Store the highest sequence ID from your last pull. Store it as text: the number is too big for some tools.
- On the next pull, set
startSequenceIdto that value. - Set
startSequenceIdInclusivetofalse, so you skip the answer you already have. - Set
sorttosequenceId. - Fetch page after page with
pageTokenuntil there is nonextPageToken.
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 want | Endpoint |
|---|---|
| List your streams | GET /api/v2/streams |
| Fetch responses from a stream | POST /api/v2/streams/{streamId}/submissions/blockResponses |
| Get one submission | GET /api/v2/submissions/{submissionId} |
| List touchpoints | GET /api/v2/touchpoints |
| Get a stream and its questions | GET /api/v2/streams/{streamId} |
If you get stuck, contact Yump support.