Lumoa Feedback API

With the Lumoa Feedback API, you can create a connection that will automatically flow data to or from Lumoa's service.

Feedback API can be used to import single or multiple Feedbacks into Lumoa's service.

Each Feedback must contain a numerical score between 0 and 10 set to parameter 'score'. If the score is missing, the API will return 'HTTP 400 Bad Data' with descriptive error message. Lumoa can process NPS, CSAT, CES or plain open end responses. For the open end responses without a score you will still need to add a score (value doesnt matter as the score will not be taken into account in calculations in this case)

Each feedback can also optionally contain

open-ended feedback that will be used for the Impact analysis.
date of the feedback
externalId that can be used for identifying the feedback in external services.
tags that are used for filtering the feedbacks in Lumoa's service

API Location

PRODUCTION: https://feedback-api.lumoa.me/api/v1/feedback
STAGING: https://stage-feedback-api.lumoa.me/api/v1/feedback
TESTING: https://test-feedback-api.lumoa.me/api/v1/feedback

Flow

The Feedback API authenticates and validates all incoming requests. After successful authentication and validations, the API will return 'HTTP 200 OK' with a copy of the data that was sent to the API.

After authentication and validation steps, the feedback processing is asynchronous which means that it can take some time before the feedback is visible in Lumoa's service. For single feedbacks the delay is few seconds but during mass imports it may take up to hours depending from the amount of imported data.

In case authentication or data validation error(s) the API returns HTTP-based error codes. Each error also contains a descriptive message about the cause of the error. The format of the returned error is JSON.

Example of a returned error message:

'{"error":"Content-Type must be application/json"}'

Translations

Each customer feedback can contain open-ended feedback given by the end customer. By default, Lumoa will translate all feedbacks to English.
In case the language of the open-ended feedback is English or the feedback has already been translated to English, the translation phase can be skipped by setting the English language version of the feedback to 'translatedComment'-attribute.

Note: While setting 'translatedComment' to any non-empty value skips translation phase, only the english translation of the open-ended feedback should be set to the parameter as otherwise the analytics may not work properly.

Feedback Date

Each feedback contains a date that can be set to a specific moment (typically the moment when the feedback was given). If the 'date' parameter is empty, it will be automatically set to the moment when the feedback is imported to Lumoa's service. All dates will be processed as UTC.

Supported Date Formats

yyyy-MM-dd
yyyy-MM-dd HH:mm:ss.SSS
yyyy-MM-ddTHH:mm:ss.SSSZ

External Id

Each imported feedback can have an unique identifier that is used to identify the feedback in external systems.
The external id can be used identifying the feedback for example when Lumoa pushes the analytics results back to the customer's own systems or third party services.

Tags

Tags are used for filtering feedback in Lumoa's service. Each feedback can have multiple tags. For example, tag with name 'gender' and value 'female' or 'male' can be used in the service to filter answers and calculate impact based on the respondents gender.

Tag names and values must be type of String and the maximum length is 64 characters.

Example:

"tags": [
{"name": "gender", "value":"female"},
{"name": "age", "value":"20-30"}
]


Masking the tag names and values

If tag names and/or values are sensitive, the name and/or value can be masked. For example tag with name 'a' and value of '1' or '2' could be used as a masked version of the 'gender' tag.
Even though the tag name and/or value is masked, Lumoa's service can display 'user friendly' names of the tags in the User Interface of the service. For example, the tag 'a' can be displayed as 'gender' in the User Interface.

Example:

"tags": [
{"name": "a", "value":"1"},
{"name": "b", "value":"2"}
]


Multiple Tag Values with the Same tagName

Lumoa supports the ability for each tagName to have multiple values associated with it.
You can do it like this:
“tags": [
{“name”: “product”, “value”:“product1”},
{“name”: “product”, “value”:“product2”}
]


Updating existing feedback

Lumoa Feedback API supports updating existing feedback. This feature is valuable for example in situations where

incorrect data has been sent earlier and it needs to be updated with correct values
when there is need to add new variables to existing feedback (like adding new tags)
when only part of feedbacks were sent (for example only 500 feedback were sent instead of 1000 that were supposed to be sent)

To locate existing feedback, the value of the attribute externalId is used. So in order to update existing feedbacks, the attribute externalId must be set to unique value (per company). If multiple feedback is found with given externalId, the first will be updated (based on date and time when the feedbacks are imported).

To update exising feedback add 'updateIfExists=true' flag to the URL like in following example

https://feedback-api.lumoa.me/api/v1/feedback?updateIfExists=true

Following cases are supported:

updateIfExists is not set: New feedback will be created
updateIfExists is set to false: New feedback will be created
updateIfExists is set to true, but feedback cannot be found with given externalId: New feedback will be created
updateIfExists is set to true but externalId is not specified: New feedback will be created
updateIfExists is set to true and existing feedback with given externalId is found: Update the existing feedback

Downloading existing feedback

Lumoa Feedback API supports downloading existing analyzed feedbacks. This feature is valuable for accessing and using enriched feedbacks from internal applications.

Start and end dates can be used to specify the range of feedback to download. Additionally, it is possible to specify which tags should be associated with the feedback you wish to download.

Start and end dates are used to specify the range of feedbacks to download. The maximum number of feedbacks which may be downloaded in one request is limited to 1000. If there are more than 1000 feedbacks within the specified date range, the limit and offset parameters can be used for paging.

Authorization

Feedback API requires 'Authorization' -header with value of 'Bearer <BASE64_ENCODED_API_KEY_AND_SECRET>'. The format for the BASE64 encoded data before encoding is '<API_KEY>:<API_SECRET>'

Example:
Authorization: Bearer OTfxMjfxMjftMTMxMjftMTIzMC0xMjM5MTIzOmFzZGfnafprbGfub3BxcnN0eXh2

You can get the required API KEY and API SECRET from Lumoa.

API

POST https://feedback-api.lumoa.me/api/v1/feedback

https://feedback-api.lumoa.me/api/v1/feedback

HEADERS

Content-Type -> application/json

Authorization -> Bearer <TOKEN>

Example Request

https://feedback-api.lumoa.me/api/v1/feedback

curl --location --request POST 'https://feedback-api.lumoa.me/api/v1/feedback' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data-raw
'{ "score": "Mandatory: the Score. Value must be between 0 and 10.",
"comment": "Optional: The freetext comment.",
"translatedComment": "Optional: Translated comment. If missing, '\''comment'\'' will be translated to english and the translated version will be set here.",
"date": "date feedback was created",
"externalId": "Optional: Identifier that can be used in external systems to identify the feedback.",
"tags": {"name": "gender", "value":"female"}, {"name": "age", "value":"20-30"}


GET https://feedback-api.lumoa.me/api/v1/feedback?startDate=yyyy-MM-dd&endDate=yyyy-MM-dd&offset=0&limit=100

https://feedback-api.lumoa.me/api/v1/feedback?startDate=yyyy-MM-dd&endDate=yyyy-MM-dd&offset=0&limit=100

HEADERS

Content-Type -> application/json

Authorization -> Bearer <TOKEN>

PARAMS

startDate -> yyyy-MM-dd

Mandatory: Start of date range in yyyy-MM-dd format.

endDate ->yyyy-MM-dd

Mandatory: End of date range in yyyy-MM-dd format.

offset -> 0

Optional: The offset used when returning the feedbacks. Offset 1000 means that the returned list will be the feedbacks 1000 - 1100 (in case limit is 100). Defaults to 0.

limit -> 100

Optional: How many feedbacks should be returned. Allowed values are 100 - 1000. Defaults to 100.

filters -> [{"name":"age","type":"numeric", "min":30,"max":60}, {"name":"product","type":"multiselect", "value":["product1","product2"]}

Optional: Which tag values need to be present in feedback. Different tag value type "numeric" or "multislect" must be used depending if tags are strictly integers or strings. Multiple values can be selected by separating them with commas.
Was this article helpful?
Cancel
Thank you!