Public
Documentation Settings
No Environment
Double Column
cURL - cURL
Lumoa Feedback API
Introduction
API

Lumoa Feedback API

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 help@lumoa.me.

API Location

Production URL should primarily be used, stage access can be granted for testing upcoming features.

Authentication

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

Example:
Authorization: Bearer OTfxMjfxMjftMTMxMjftMTIzMC0xMjM5MTIzOmFzZGfnafprbGfub3BxcnN0eXh2

| Tokens generated after 3rd of August 2021 are already BASE64 encoded

You can get the required API token from Lumoa.

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 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 feedback can contain open-ended feedback given by the end user. 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

||| 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 feedback

Lumoa Feedback API supports overwriting 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 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 collection). 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 existing 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

Enrich feedback

||| This is a beta feature

Lumoa Feedback API now supports enriching existing feedback by adding tags without overwriting score, comment or date of old record. 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.

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 feedbacks 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?updateIfExists=true' --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?updateIfExists=true' --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 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. It is possible to specify which tags should be associated with the feedback you wish to download. Additionally, it is possible to include feedbackCollectionId if only certain data collection needs to be accessed, please contact help@lumoa.me for feedbackCollectionId.

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.

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.

feedbackCollectionId -> Unique integer

Optional: Integer unique to your data collection, this can be used to narrow down the data to specific feedbackCollection.

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&feedbackCollectionId=89' --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

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 help@lumoa.me.
  • 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 help@lumoa.me if you have any questions
Loading