Lumoa Feedback API
Table of contents
2. API Location
4. Flow
5. Translations
7. External Id
8. Tags
9. Methods
10. Tips
Getting started
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 send data, download enriched data or update tags of existing data.
If you have any questions, please email us at [email protected].
API Location
Production URL should primarily be used, stage access can be granted for testing upcoming features.
PRODUCTION: https://feedback-api.lumoa.me/api/v1/feedback
Authentication
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 for the above formatting:
Authorization: Bearer OTfxMjfxMjftMTMxMjftMTIzMC0xMjM5MTIzOmFzZGfnafprbGfub3BxcnN0eXh2
Tokens generated after 3rd of August 2021 are already BASE64 encoded
Token access and expiration
Tokens can have Read, Write or Read+Write permissions.
Lumoa API keys and tokens don't currently expire, we will warn developers if there are any changes to this.
Tokens can be generated and disabled by Lumoa, this permission can be extended to admin users.
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 feedback 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 feedback can contain open-ended feedback given by the end user. By default, we will translate all feedback to English. We can also offer translations for feedback in Swedish, German, Finnish, Spanish, Danish, and Norwegian. Which language gets used for translations is determine by collection settings.
If you already have your data translated, or you are comfortable not having your data translated (such as when all data is in English), you can use the translatedComment parameter. This works like the comment param, only anything in translatedComment field will be used as the translation in Lumoa - we will not perform additional translations, and instead use the translations provided in translatedComment param.
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
It is highly recommended that externalId is used as it is required for updating or enriching the feedback.
Each imported feedback can have an unique identifier that is used to identify the feedback in external systems.
The external id can be used to identify feedback after Lumoa has pushed data back to the customers own systems, or to follow the feedback as it travels through third party services.
Overwrite/Enrich existing feedback
Lumoa Feedback API supports overwriting existing feedback. This feature is valuable
in situations where:
incorrect data has been sent earlier and it needs to be updated with correct values
when only part of the feedback was sent (for example only 500 feedback were sent instead of 1000 that were supposed to be sent)
Feedback was initially sent without tags and needs to be enriched with tags
Tags need to be removed from feedback
To locate existing feedback, the value of the attribute externalId is used. So in order to update existing feedback, the attribute externalId must be set to a unique value (per collection). If multiple feedback is found with given externalId, the first will be updated (based on date and time when the feedback are imported).
To update existing feedback, simply submit a new response to Lumoa. That new response must have the "externalId" tag, and the value for "externalId" must match an existing value for a response already in Lumoa. Then, the existing response will be overwritten with the new one.
Note that overwiting/enriching data to Lumoa will count as a new feedback uploaded. This may cause you to go over your limits as defined in your contract. We advise you to upload data to Lumoa correctly the first time.
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 128 characters.
Example:
"tags": [
{"name": "gender", "value":"female"},
{"name": "age", "value":"20-30"}
]
Masking tags
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 Lumoa Dashboard.
Example:
"tags": [
{"name": "a", "value":"1"},
{"name": "b", "value":"2"}
]
Reserved Tags
Same tag value are reserved by the system and cannot be used as background variables. These tags are:
Date
Score
Comment
TranslatedComment
ExternalID
Campaign
Please use different values for tags in your data. Using the ones above for anything other than their intended purpose will throw an error.
Multiple values for same tag
Lumoa supports the ability for each tag to have multiple values associated with it.
You can do it like this:
“tags": [
{“name”: “product”, “value”:“product1”},
{“name”: “product”, “value”:“product2”}
]
Methods
POST feedback
If you are sending score based feedback, such as NPS (0-10), the 'score' parameter must be in your data, but it does not have to have a value for each feedback. If the score is missing for an individual feedback, we will still upload it, but that feedback will not be factored in to:
KPI widget overall score
Topics Impacts
Graphs looking at overall scores
It will be factored into
Topic responses
Summaries and Ask AI
Graphs looking at response rates
Additionally, Lumoa can process different KPIs, conversational data, or even plain open ended responses. For open ended responses or similar data without a score, you do not need to add the 'score' parameter at all.
The only paramater that is required for all feedback, regardless of metric or source, is 'date'.
Each feedback can also optionally contain:
open-ended feedback that will be used for the Impact analysis.
externalId that can be used for identifying the feedback in external services.
tags that are used for filtering the feedback in Lumoa's service.
feedback weight, used for weighted feedback analysis (This setting is disabled by default, ask your CS manager about this).
Example curl:
curl --location --request POST 'https://feedback-api.lumoa.me/api/v1/feedback' --header 'Content-Type: application/json' --header 'Authorization: Bearer OTfxMjfxMjftMTMxMjftMTIzMC0xMjM5MTIzOmFzZGfnafprbGfub3BxcnN0eXh2' --data-raw '{
"score": "8",
"comment": "Lumoa test",
"date": "2021-08-10",
"externalId": "test",
"tags": [
{"name": "gender", "value":"female"},
{"name": "age", "value":"20-30"}
]
}'
POST conversational data
Conversational feedback requires special tags in addition to score and comment, below unique parameters must be included so the conversation can be displayed correctly:
cnv_actor Author of the comment. For example agent/bot/customer.
cnv_index Order of the conversation. Running number from 1 to n
cnv_id Unique id for the conversation, this must be same for all the responses in single conversation.
Example curl:
curl --location --request POST 'https://feedback-api.lumoa.me/api/v1/feedback' --header 'Content-Type: application/json' --header 'Authorization: Bearer OTfxMjfxMjftMTMxMjftMTIzMC0xMjM5MTIzOmFzZGfnafprbGfub3BxcnN0eXh2' --data-raw '{
"score": "8",
"comment": "Lumoa test",
"date": "2021-08-10",
"externalId": "test",
"tags": [
{"name": "cnv_actor", "value":"agent"},
{"name": "cnv_index", "value":"1"},
{"name": "cnv_id", "value":"test123"},
{"name": "gender", "value":"female"},
{"name": "age", "value":"20-30"}
]
}'
PUT enrich data
Lumoa Feedback API now supports enriching existing feedback by adding tags without overwriting score, comment or date of old record. When using this API the Feedback is always updated instantly. This feature is valuable for example in situations where:
Feedback was initially sent without tags and needs to be enriched with tags.
Incorrect tags were sent and need to be updated.
Tags need to be removed from feedback.
Example curl:
curl --location --request PUT 'https://feedback-api.lumoa.me/api/v1/feedback' --header 'Content-Type: application/json' --header 'Authorization: Bearer OTfxMjfxMjftMTMxMjftMTIzMC0xMjM5MTIzOmFzZGfnafprbGfub3BxcnN0eXh2' --data-raw '{
"externalId": "test",
"tags": [
{"name": "gender", "value":"male"},
{"name": "age", "value":"30"},
{"name": "order", "value":"5"},
{"name": "segment", "value":"Q3"},
{"name": "order-size", "value":"LARGE"},
{"name": "season", "value":"summer"}
]
}'
GET feedback
Lumoa Feedback API supports downloading existing analyzed feedback. This feature is valuable for accessing and using enriched feedback from internal applications.
Start and end dates can be used to specify the range of feedback to download. It is possible to specify which tags should be associated with the feedback you wish to download.
Reading Lumoa feedback requires collection specific apikey as of 19/12/2023. An API key can be generated from Lumoa.
The maximum number of feedback which may be downloaded in one request is limited to 1000. If there are more than 1000 feedback within the specified date range, the limit and offset parameters can be used for paging.
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 feedback. Offset 1000 means that the returned list will be the feedback 1000 - 1100 (in case limit is 100). Defaults to 0.
limit -> 100
Optional: How much feedback 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.
Example curl:
curl --location --request
GET 'https://feedback-api.lumoa.me/api/v1/feedback?startDate=2021-08-01&endDate=2021-08-21&offset=0&limit=100'
--header
'Content-Type: application/json'
--header
'Authorization: Bearer OTfxMjfxMjftMTMxMjftMTIzMC0xMjM5MTIzOmFzZGfnafprbGfub3BxcnN0eXh'
GET topic impacts
endpoint /feedback/impacts/{card-id}
Lumoa Feedback API supports downloading topic impacts from a card created in Lumoa UI. This feature can be used to fetch topic impacts for specific card using the API.
To obtain card id, find the card in Lumoa UI for which you want to get the impacts and copy id from browser, example: https://feedback-api.lumoa.me/api/v1/feedback/impacts/4539
Note: Feedback delivered with GET Topic Impacts will include the "General" topic on a per statement basis, assuming that the statement is associated with the "General" topic. Read more about what is a statement.
Example curl:
curl --location --request
GET 'https://feedback-api.lumoa.me/api/v1/feedback/impacts/4539'
--header
'Authorization: Bearer OTfxMjfxMjftMTMxMjftMTIzMC0xMjM5MTIzOmFzZGfnafprbGfub3BxcnN0eXh'
Tips
API token will grant user ability to Read and/or Write data to your account so it should be handled with care and deactivated if no longer in use.
Testing should always be conducted before integrating Lumoa's Feedback API with your systems. If you require test data to be removed, please contact [email protected].
When posting data, externalId is highly recommended as it will not be possible to overwrite or enrich Feedback if one was not initially included.
Please contact [email protected] if you have any questions.
Get in touch
📧 Do you have any questions or comments about using Lumoa? Please don't hesitate to email Lumoa Support at [email protected].