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, Lumoa will translate all feedback 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
It is highly recommended that external Id 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
Incorrect tags were sent and need to be updated
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"}
]
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
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 different KPIs, conversational data or plain open end responses. For open ended responses without a score, you will still need to add a score (value doesn't matter as the score will not be taken into account in calculations).
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 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",
"translatedComment": "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",
"translatedComment": "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].