Software Architect / Microsoft MVP (AI) and Technical Author

AI, Azure, Cognitive Services, Text Analytics

Cognitive Services Text Analytics: Custom Question Answering REST API(Preview)

In an earlier blog post I shared a demo and information about a new feature that was shipped with the Text Analytics API “Custom Question Answering”.

In that demo, you saw how the QnA Maker instance could be configured to use unstructured data which could then be queried using natural language.

At the time of writing this blog there is also REST API endpoint you can consume to use the same functionality programmatically. In this blog post you’ll see how to use it.

Constructing The Request Using Postman

First, set the Ocp-Apim-Subscription-Key in the Header in Postman. You can see this here:

Next, set the Body type to raw and JSON.

In the JSON you can see the following:


  "question": "when are you open?",

  "documents": [


      "text": "we are open 7 days a week",

      "id": "1"



      "text": "what do you sell?",

      "id": "2"



  "language": "en"



We have a question “when are you open”. We also have 2 documents. Each “document” has a unique id and some text. These are simple sentences but could contain much more text.

Testing The Request

After sending this request we get the following JSON response in Postman. The response contains each answer along with an associated confidence scoring of how relevant each answer is to our original question (when are you open?).

From the below we can see that answer “answer”: “we are open 7 days a week” has a confidence score of 0.97 / 0.0485 and is the winner.


    "answers": [


            "answer": "we are open 7 days a week",

            "answerSpan": {

                "text": "7 days a week",

                "score": 0.97199804,

                "startIndex": 11,

                "endIndex": 24


            "score": 0.04851992428302765,

            "id": "1",

            "answerStartIndex": 0,

            "answerEndIndex": 24



            "answer": "what do you sell?",

            "answerSpan": {

                "text": "what do you sell?",

                "score": 0.53296316,

                "startIndex": 0,

                "endIndex": 16


            "score": 0.006258996669203043,

            "id": "2",

            "answerStartIndex": 0,

            "answerEndIndex": 16





Thoughts and Ideas

Being able to consume this capability programmatically using a REST API has given me a few thoughts and ideas.

Enhanced Querying – ingest, pre-process and parse internal documentation. After initial ingestion, use this API to let customers or the business issue queries against existing document stores.

Optimise Workflow and Business Processes – use the API to perform programmatic lookups against data, augment this with Named Entity Recognition (NER) or Key Phrase Extraction. This can improve decision making. Use the returned answers and associated confidence scoring to help with this.

Chatbots – plug this API into a chatbot. The human can then interact with a document but in a more friendly manner. This can provide a better customer experience. One example of this might be reading length legal documents.


In this blog post we’ve seen the preview API endpoint “custom question answering”, how to use it, the data an insight it returns and looked at some ideas.

Drop me a message below or connect with me on Twitter if you have any questions or ideas.

Get the latest content and code from the blog posts!
I respect your privacy. No spam. Ever.

Leave a Reply