Tutorial: Get exact text-matched data from an utterance

In this tutorial, understand how to get entity data that matches a predefined list of items.

In this tutorial, you learn how to:

  • Create app
  • Add intent
  • Add list entity
  • Train
  • Publish
  • Get intents and entities from endpoint

For this article, you can use the free LUIS account in order to author your LUIS application.

What is a list entity?

A list entity is an exact text match to the words in the utterance.

Each item on the list can include a list of synonyms. For the human resources app, a company department can be identified by several key pieces of information such as an official name, common acronyms, and billing department codes.

The Human Resources app needs to determine the department an employee is transferring to.

A list entity is a good choice for this type of data when:

  • The data values are a known set.
  • The set doesn't exceed the maximum LUIS boundaries for this entity type.
  • The text in the utterance is an exact match with a synonym or the canonical name. LUIS doesn't use the list beyond exact text matches. Stemming, plurals, and other variations are not resolved with just a list entity. To manage variations, consider using a pattern with the optional text syntax.

Create a new app

  1. Sign in to the LUIS portal with the URL of https://www.luis.ai.

  2. Select Create new app.

    Screenshot of Language Understanding (LUIS) My Apps page

  3. In the pop-up dialog, enter the name HumanResources and keep the default culture, English. Leave the description empty.

    Create LUIS new HumanResources app

  4. Select Done.

Create an intent to transfer employees to a different department

  1. Make sure your Human Resources app is in the Build section of LUIS. You can change to this section by selecting Build on the top, right menu bar.

  2. Select Create new intent.

  3. Enter TransferEmployeeToDepartment in the pop-up dialog box then select Done.

    Screenshot of create new intent dialog with

  4. Add example utterances to the intent.

    Example utterances
    move John W. Smith to the accounting department
    transfer Jill Jones from to R&D
    Dept 1234 has a new member named Bill Bradstreet
    Place John Jackson in Engineering
    move Debra Doughtery to Inside Sales
    mv Jill Jones to IT
    Shift Alice Anderson to DevOps
    Carl Chamerlin to Finance
    Steve Standish to 1234
    Tanner Thompson to 3456

    Screenshot of intent with example utterances

    These few utterances are for demonstration purposes only. A real-world app should have at least 15 utterances of varying length, word order, tense, grammatical correctness, punctuation, and word count.

Department list entity

Now that the TransferEmployeeToDepartment intent has example utterances, LUIS needs to understand what is a department.

The primary, canonical, name for each item is the department name. Examples of the synonyms of each canonical name are:

Canonical name Synonyms
Accounting acct
Development Operations Devops
Engineering eng
Finance fin
Information Technology IT
Inside Sales isale
Research and Development R&D
  1. Select Entities in the left panel.

  2. Select Create new entity.

  3. In the entity pop-up dialog, enter Department for the entity name, and List for entity type. Select Done.

    Screenshot of creating new entity pop-up dialog

  4. On the Department entity page, enter Accounting as the new value.

  5. For Synonyms, add the synonyms from the previous table.

  6. Continue adding all the canonical names and their synonyms.

Add example utterances to the None intent

The client application needs to know if an utterance is not meaningful or appropriate for the application. The None intent is added to each application as part of the creation process to determine if an utterance can't be answered by the client application.

If LUIS returns the None intent for an utterance, your client application can ask if the user wants to end the conversation or give more directions for continuing the conversation.


Do not leave the None intent empty.

  1. Select Intents from the left panel.

  2. Select the None intent. Add three utterances that your user might enter but are not relevant to your Human Resources app:

    Example utterances
    Barking dogs are annoying
    Order a pizza for me
    Penguins in the ocean

Train the app so the changes to the intent can be tested

  1. In the top right side of the LUIS website, select the Train button.

    Train button

  2. Training is complete when you see the green status bar at the top of the website confirming success.

    Trained status bar

Publish the app so the trained model is queryable from the endpoint

In order to receive a LUIS prediction in a chat bot or other client application, you need to publish the app to the endpoint.

  1. Select Publish in the top right navigation.

    LUIS publish to endpoint button in top right menu

  2. Select the Production slot and the Publish button.

    LUIS publish to endpoint

  3. Publishing is complete when you see the green status bar at the top of the website confirming success.

    LUIS publish to endpoint

  4. Select the endpoints link in the green status bar to go to the Keys and endpoints page. The endpoint URLs are listed at the bottom.

Get intent and entity prediction from endpoint

  1. In the Manage section (top right menu), on the Keys and endpoints page (left menu), select the endpoint URL at the bottom of the page. This action opens another browser tab with the endpoint URL in the address bar.

    The endpoint URL looks like https://<region>.api.cognitive.microsoft.com/luis/v2.0/apps/<appID>?verbose=true&subscription-key=<YOUR_KEY>&<optional-name-value-pairs>&q=<user-utterance-text>.

  2. Go to the end of the URL in the address and enter shift Joe Smith to IT. The last querystring parameter is q, the utterance query. This utterance is not the same as any of the labeled utterances so it is a good test and should return the TransferEmployeeToDepartment intent with Department extracted.

       "query": "shift Joe Smith to IT",
       "topScoringIntent": {
         "intent": "TransferEmployeeToDepartment",
         "score": 0.9775754
       "intents": [
           "intent": "TransferEmployeeToDepartment",
           "score": 0.9775754
           "intent": "None",
           "score": 0.0154493852
       "entities": [
           "entity": "it",
           "type": "Department",
           "startIndex": 19,
           "endIndex": 20,
           "resolution": {
             "values": [
               "Information Technology"

Clean up resources

When no longer needed, delete the LUIS app. To do so, select My apps from the top left menu. Select the ellipsis (...) to the right of the app name in the app list, select Delete. On the pop-up dialog Delete app?, select Ok.

Next steps

This tutorial created a new intent, added example utterances, then created a list entity to extract exact text matches from utterances. After training, and publishing the app, a query to the endpoint identified the intention and returned the extracted data.

Continue with this app, adding a composite entity.