Introduction

The Underlined Text Mining API provides natural language processing for plain text customer feedback and contact channels with a lot of textual information. The API uses AI technologies to automatically process data and generate valuable insights, enabling companies to make data-driven decisions.

The API allows to text mine Topic detection customer feedback and Topic detection customer contact data for the following channels:

  • Chat conversations.
  • Email conversations.
  • CRM logs with conversation notes.

The Text Mining API looks for an explanation of the impact on:

  • Net promoter score (tNPS/rNPS/eNPS).
  • Customer satisfaction (KTV/CSAT/AW).
  • Customer effort score (CES).
  • Employee score.
  • Emotion question.


API specification

Test the API on SwaggerHub


Base URL

https://api-prd.kpn.com/data/underlined


Conceptual model

Conceptual model


Definitions

Channel

Chat conversations, support tickets, emails, customer satisfaction surveys, remote helpdesk, physical helpdesk, etc.

Customer contact data (CC)

For example: CRM logging, sales, life events, area.

Customer experience data (CX)

Feedback data, for example: CSAT, CES, tNPS , rNPS , employee, FTF, suggestion, emotion.

Customer satisfaction score (CSAT)

Measures customer satisfaction with regards to your business, product, or service. The score is the average of all customer responses.

Customer effort score (CES)

Measures how much effort your customers put into getting an issue resolved or obtaining a service your business offers.

Driver tree

Topics and subtopics that apply in your texts are grouped together in a driver tree.

Emotion

Also called Emoscore. Measures the emotional value or benefit of products and services.

Employee

Employee engagement/satisfaction. Measures how satisfied employees are with their jobs.

Employee net promoter score (eNPS)

This is a method for measuring how willing the employees are to recommend their workplace to friends and acquaintances.

Key performance indicator (KPI)

This value demonstrates how effective a company is in achieving key business objectives.

Relationship net promoter score (rNPS)

Known as on-demand or regular NPS, this value is designed to assess your business’s relationship with its customers, serving as the starting point for measuring your customer satisfaction and spotting the gaps which need attention.

Text mining

Text mining is the process of transforming unstructured text data into meaningful and actionable information.

Topic

Topics and subtopics are a group of words from a collection of documents that best represents the information in the collection.

Transactional net promoter score (tNPS)

Assess the customer’s opinion on a certain business transaction.


API workflow

Workflow diagram


Requirements

The file provided to the Text Mining API must meet the following conditions:

  • Respondent ID:
    • A unique code for each respondent.
  • The file must not contain any personal data:
    • Items that can be traced back to a person or personal information must be taken off the file (for example, email, customer number, place of residence).
  • The scores on the KPI to be tested.
  • The explanations on the scores:
    • The open answers to the chosen KPI in one column (e.g. NPS groups).
  • Up to 500 records if the file will be used for the initial quality insurance check:
    • Make sure that the explanatory column is filled as well as possible so that as many records as possible can be supplemented with text mining.

Features

  • Topic detection customer feedback.
  • Topic detection customer contact data.


Topic detection customer feedback

This service extracts the most important topics from the open customer feedback you get from questionnaires. Texts are divided into:

  • A topic (main topic) and,
  • A subtopic (detailed topic related to the main topic).

This form of text mining is linked to the most important customer metrics, in order to achieve the highest possible reliability of the returned topics and subtopics.

Text mining on this type of open text fields is often company-specific or industry-specific. There are models available for the following industries:

  • Automotive
  • Banking
  • Energy
  • Healthcare
  • Health Insurance
  • Insurance
  • Municipalities
  • Pension
  • Publisher
  • Retail
  • Telecom

Topic detection customer contact data

This service extracts the most important topics from customer contact data (CC). For example, there can be topic detection for customer relationship management (CRM) logging at customer contact centers, web reviews, chat traffic, email conversations and so on.

The Text Mining API currently has text mining solutions for:

  • CC – Areas:
    • Provides insight into which areas recur in the text. For example: healthcare, pension or more specific own risk.
  • CC – Life events:
    • Provides insight into which life events can be discovered in the text. For example: turning 18 years old, moving away, divorce.
  • CC – Logging:
    • Provides insight into the loggings of a helpdesk employee.
  • CC – Sales

Text mining of this type of open text fields is often company-specific or industry-specific. The following industry-specific dictionaries are available:

  • Banking
  • Health Insurance
  • Insurance
  • Publisher

Text mining results

Text mining algorithms return the most important topics from the customer feedback texts.

  • Subtopics are defined, which can be classified under a broader main subject.
  • All topics and subtopics that apply in your texts are brought together in a so-called driver tree.

The topics in the driver tree vary by KPI, channel, industry and organization.

In addition to the topics and subtopics, two extra topics are defined:

NULL(?)

These are records that don't contain valuable text, such as blank fields or fields that can be seen as "no opinion." To classify these records, Underlined uses an exclusion list. Once the text appears in this exclusion list, the record is not included for text mining and the text will be addressed as Null category.

This exclusion list contains explanatory notes such as:

  • No explanation given.
  • Only punctuation or numbers in explanatory notes.
  • Explanations with no opinion.
  • Explanations with I don't know.
  • Notes with no additions.
  • Explanations with only yes or no.
  • Notes with ditto/see previous.
  • Explanations with n.v.t.

No (sub)topic found

These are valid records that are included for text mining, but where the text mining algorithm cannot find a relevant topic. These are often texts that relate to a unique topic that does not appear in the driver tree (because there is simply too little volume to make it a topic) or texts that do not contain valuable information (and do not appear in the exclusion list).

Example: Driver tree

Drivertree example


Getting started

Make sure you've read Getting Started for more info on how to register your application and start trying out our APIs.

Authentication

The API follows the KPN Store API authentication standard to secure the API. It includes the use of OAuth 2.0 client_id and client_secret to receive an access token.

Go to the Authentication tab to find out how to:

  • Authenticate to an API using cURL.
  • Authenticate to an API on Swaggerhub.
  • Import Open API Specifications (OAS), also called Swagger files into Postman.

API keys for sandbox users

If you are using the Sandbox, you can use the following ApiKeys for free models or branches. These API keys might not have the best quality results for the text classifications.

Model Key
Banking rYLVYhzp3ljvDvTr4wXtujH874kvOoTDyBYxdUPCYvKsFMeXyVrZeGAHRMXe7DaPRg7CWgOjgUV9ZY3vaM7364isAQfR6vFUU4aiPcARHI2KvBr2SmEuGhSW8OBFA7n
Insurance EVHvPzpnhItFejd421L4FK5G8xltAW51ZcU0QGjp1VzMYCIcRbNRtbQ4ZBwcN6nKN1qCPmnwRgDuVsr5oIbjJoH8LZaPUHb4ro9hWFNoxa9NXgjqT0xEeEAjts1zMYc


How to...

Classify a single text

POST ​/api​/textmining​/classification

This endpoint returns one topic and one sub-topic per text. You can:

  • Obtain topics and subtopics from (open) text fields of customer experience feedback.
  • Obtain topics and subtopics from (open) text fields of customer contact (CRM) data.

Request

Send a JSON object with the following properties:

  • Id
  • ApiKey
  • Type
  • IncludeTextsInResult
  • Language
  • TextInput
^^Request example^^
{
  "Id": "1",
  "ApiKey": "8hjguyjgfyuvv76567t8tgiugbuftyfytfvjhvcfnjrIww",
  "Type": "CC - Logging",
  "IncludeTextsInResult": false,
  "Language": "NL",
  "TextInput": [
    {
      "Id": "2",
      "Text": "Klant wil graag zijn adres wijzigen. Hij is vorige week verhuisd."
    }
  ]
}
Parameter Description
Id The Id of the text. This is the same as given the Id from the input.
ApiKey The Apikey for the requested model or branch.
Sandbox customers can use the API keys for sandbox users. These might not have the best quality results for the text classifications.
Production customers can request API keys for a certain branch.
Type The type of texts in this call. There are two main categories with sub categories: customer contact data (CC) and customer experience data (CX). Both of these categories can have a few subcategories.
IncludeTextsInResult Indication whether the given text property must be added to in the output. If the value is true then the original texts are returned. Otherwise the text property is not included in the output.
Language | Optional. If this parameter is not in the input or null then the language is retrieved from the license information. Languages are accepted in two letter codes. For example: NL for Dutch, EN for English.
Text The text from the input, only if the input property IncludeTextsInResult is true. Otherwise, the value is always null.


Response

The response will return a topic and a sub topic for the requested text.

^^Response example^^
{
  "id": "string",
  "success": true,
  "errorMessage": "string",
  "result": [
    {
      "id": "2",
      "text": null,
      "topic": "Houding & Gedrag medewerker",
      "subtopic": "Vriendelijkheid"
    }
  ]
}


Classify multiple texts

POST /api/textmining/multi-classification

This endpoint returns more than one topic and sub-topics per text. You can:

  • Obtain topics and subtopics from (open) text fields of customer experience feedback.
  • Obtain topics and subtopics from (open) text fields of customer contact (CRM) data.

Request

Send a JSON object with the following properties:

  • Id
  • ApiKey
  • Type
  • IncludeTextsInResult
  • Language
  • TextInput
^^Request example
{
  "Id": "1",
  "ApiKey": "8hjguyjgfyuvv76567t8tgiugbuftyfytfvjhvcfnjrIww",
  "Channel": "RemoteHelpdesk",
  "Type": "CX - tNPS",
  "IncludeTextsInResult": false,
  "Language": "NL",
  "TextInput": [
    {
      "id": "2",
      "text": "Geen idee...De prijs was erg hoog. Het personeel was zeer vriendelijk. Verder was het wel prima."
    },
    {
      "id": "3",
      "text": "De prijs was erg hoog."
    }
  ]
}
Parameter Description
Id The Id of the text. This is the same as given the Id from the input.
ApiKey The Apikey for the requested model or branch.
Sandbox customers can use the API keys for sandbox users. These might not have the best quality results for the text classifications.
Production customers can request API keys for a certain branch.
Channel | The channel used during the request. In case of customer feedback, the channel represents the channel of the contact over which the feedback is asked. The possible values for this property may differ per company. Please check the functional documentation to see which channels are available. Please note that the values are case independent. The default value for this property is RemoteHelpdesk.
Type The type of texts in this call. There are two main categories with sub categories: customer contact data (CC) and customer experience data (CX). Both of these categories can have a few subcategories.
IncludeTextsInResult Indication whether the given text property must be added to in the output. If the value is true then the original texts are returned. Otherwise the text property is not included in the output.
Language | Optional. If this parameter is not in the input or null then the language is retrieved from the license information. Languages are accepted in two letter codes. For example: NL for Dutch, EN for English.
Text The text from the input, only if the input property IncludeTextsInResult is true. Otherwise, the value is always null.


Response

The response will return a topic and a sub topic for each requested text.

^^Response example^^
{
  "Id": "1",
  "ApiKey": "8hjguyjgfyuvv76567t8tgiugbuftyfytfvjhvcfnjrIww",
  "Channel": "RemoteHelpdesk",
  "Type": "CX - tNPS",
  "IncludeTextsInResult": false,
  "Language": "NL",
  "TextInput": [
    {
      "id": "2",
      "text": "Geen idee...De prijs was erg hoog. Het personeel was zeer vriendelijk. Verder was het wel prima."
    },
    {
      "id": "3",
      "text": "De prijs was erg hoog."
    }
  ]
}


Request API keys for a certain branch

Use this endpoint to request an API keys for a certain branch. Note: This endpoint is only applicable for verified/production customers.

POST ​/api​/key​/request

Request

Send a message in the request body to request the API key for a branch/domain.

^^Request example^^
{
  "message": "Please send me the ApiKey for the banking domain."
}


Upload data via FTP

If you are a production customer, you can upload your data to the Underlined FTP server to train the models for the branch with the uploaded data set. Follow the steps below:

  1. Send an email to support@underlined.nl
  2. Provide your IP address to get it white-listed by Underlined Text Mining.
  3. After having received your FTP server credentials you can upload your data sets.

The file provided to Underlined must meet the following conditions:

  • Respondent ID:
    • A unique code for each respondent.
  • The file must not contain any personal data:
    • Items that can be traced back to a person or personal information must be taken off the file (e.g. email, customer number, place of residence).
  • The scores on the KPI to be tested.
  • The explanations on the scores:
    • The open answers to the chosen KPI in one column (e.g. NPS groups), please also pay attention to unnecessary use of space.
  • Up to 500 records if the file will be used for the initial quality insurance check:
    • Make sure that the explanatory column is filled as well as possible so that as many records as possible can be supplemented with text mining.

This feature is only available for production customers.

Return codes

Code Description
200 Success.
201 Created.
202 Accepted.
302 Found. Link in location header.
400 Bad request.
401 Unauthorized.
403 Forbidden.
404 Not found.
405 Method not allowed.
412 Precondition failed.
429 Too many requests.
500 Internal server error.
502 Bad gateway.
503 Service unavailable.


HTTP response headers

The following tables display the standard response headers that are returned with each API response:

Standard response field name Description
sunset This field will be populated with the deprecation details. By default the value is n/a.
api-version Indicates the API version you have used.
quota-interval Used to specify an integer (for example, 1, 2, 5, 60, and so on) that will be paired with the quota-time-unit you specify (minute, hour, day, week, or month) to determine a time period during which the quota use is calculated.
For example, an interval of 24 with a quota-time-unit of hour means that the quota will be calculated over the course of 24 hours.
quota-limit Number of API calls an user can make within a given time period.
If this limit is exceeded, the user will be throttled and API requests will fail.
quota-reset-UTC All quota times are set to the Coordinated Universal Time (UTC) time zone.
quota-time-unit Used to specify the unit of time applicable to the quota.
For example, an interval of 24 with a quota-time-unit of hour means that the quota will be calculated over the course of 24 hours.
quota-used Number of API calls made within the quota.
strict-transport-security The HTTP Strict-Transport-Security (HSTS) response header lets a website tell browsers that it should only be accessed using HTTPS, instead of using HTTP. All present and future subdomains will be HTTPS for a maximum of 1 year and access is blocked to pages or sub domains that can only be served over HTTP including HSTS preload lists of web browsers.
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload.
Access control field name Description
access-control-allow-credentials Tells browsers whether to expose the response to frontend JavaScript when the request's credentials mode (Request.credentials) is include.
When a request's credentials mode (Request.credentials) is include, browsers will only expose the response to frontend JavaScript if the Access-Control-Allow-Credentials value is true. Boolean.
access-control-allow-origin Indicates whether the response can be shared with requesting code from the given origin.
access-control-allow-headers Used in response to a pre-flight request which includes the Access-Control-Request-Headers to indicate which HTTP headers can be used during the actual request.
access-control-max-age Indicates how long the results of a pre-flight request (that is the information contained in the Access-Control-Allow-Methods and Access-Control-Allow-Headers headers) can be cached.
access-control-allow-methods Indicates which HTTP methods are allowed on a particular endpoint for cross-origin requests.
For example: GET, PUT, POST, DELETE.
content-length The Content-Length entity header indicates the size of the entity-body, in bytes, sent to the recipient.
content-type The Content-Type entity header the client what the content type of the returned content actually is.

Mopinion feedback