Overview

The Insights API is a service to retrieve call, message, and application data. The file that you receive contains detailed information about your programmatic services. The lessons in this document will help you request and access the desired data, which can aid in:

  • general troubleshooting
  • streamlining your processes
  • analyzing customer behavior and experience
  • creating new solutions to serve your customers
  • fine-tuning existing SmartFlows to your customer experience
Using Insights API
  1. GET https://api.intelepeer.com/_rest/v4/dwh/Q

Retrieves the list of fields available to design a custom query. Additional information about each field is available in the Data Dictionary.

  1. POST https://api.intelepeer.com/_rest/v4/dwh/Q

Validates and processes the query in the body of the request. A GUID is returned and subsequently used in later calls to check the status, headers, and location of the report. Your query is now processing.

  1. GET https://api.intelepeer.com/_rest/v4/dwh/Q/{guid}/status

Enables you to see the current status of your query. The API will return a response of “Processing” while your query is still processing. Once the API returns “Completed”, you are ready to download your report.

*The GUID is returned from the initial query request in Step 2.

  1. GET https://api.intelepeer.com/_rest/v4/dwh/Q/{guid}

The above returns the location of the query output file on the SFTP server. For more information on how to access the SFTP server, please visit File Storage Setup.

To retrieve only the HTTP headers associated with the file, change the request to HEAD as shown below.

HEAD https://api.intelepeer.com /_rest/v4/dwh/Q/{guid}

*The GUID is returned from the initial query request in Step 2.

 
Example 1: Get Available Fields

Use this API to get a list of fields available for filtering and report shaping. Note Common Fields can be added to data structure you use. For more information about each field, please visit the Data Dictionary.

GET https://api.intelepeer.com/_rest/v4/dwh/Q

Authorization: Bearer 0sjey2…

Content-Type: application/json

Headers:

Status: 200

Content-Type: application/json

body:

{

"ApplicationExitEvent": {

   "fields": [

     "StartTime",

     "EndTime",

     "Path",

     "ExitReason"

   ]

},

"DtmfEvent": {

   "fields": [

     "DtmfInput",

     "DtmfSource",

     "ErrorReason"

   ]

}

}
 
Example 2: Submit Query

Use the POST to validate and submit your query. The query accepts a JSON body with 4 main attributes:

“timestamp”

Required. Restricts the date/time range of records to analyze during all phases of filtering and processing. If your scoped query is not providing the entire session, expand the range of your timestamp.

 

“data”

Required. Identifies which fields will appear in the final report.

“scope”

Optional. Provides the ability to filter and collect associated records matching its own filters attribute. Similar to website analytics, a session correlates all actions for 1 user within 1 end-to-end execution of a flow.

  • If this attribute is used, the both child attributes filters and scope must be provided
  • filters provides session filtering using MongoDB syntax:
    • $eq – equal to…
    • $gt – greater than…
    • $gte – greater than or equal to…
    • $lt – less than…
    • $lte – less than or equal to…
    • $ne – not equal to…

* Currently limited to the common field “SessionId”

“filters”

Optional. Includes or excludes records during the final phase of filtering and processing; only matching data will be returned.

  • If a scope filter is provided, filters may exclude individual records within a session.

 

See Tutorial: Design a Query for more information.

Request all records that explicitly match criteria. This is the minimum acceptable query.

Explanation: This example limits your data to records occurring on or after ($gte) 2019-11-25 and on or before ($lte) 2019-11-26. The report will only have 1 column: FlowId

POST https://api.intelepeer.com/_rest/v4/dwh/Q

Authorization: Bearer 0sjey2…

Content-Type: application/json




{

 "timestamp": {

   "$gte": "2019-11-25T00:00:00Z",

   "$lte": "2019-11-26T00:00:00Z"

 },

 "data": {

   "ApplicationExitEvent": {

       "fields": ["FlowId"]

   }

 }

}

Headers:

Status: 201

Content-Type: application/json

Content-Length: 43

body:

{

 "id": "ae9faa8e3cee29e5185578ad028e29f2"

}

Request any/all ApplicationExitEvent records associated to FlowId 5dcf48b453e0ab04386da7d1


POST /_rest/v4/dwh/Q

Authorization: Bearer 0sjey2n81hamxis=/

Content-Type: application/json


{

 "timestamp": {

   "$gte": "2019-11-25T00:00:00Z",

   "$lte": "2019-11-26T00:00:00Z"

 },

 "data": {

   "ApplicationExitEvent": {

     "fields": ["EventName", "EventVersion", "EventSku", "TimeStamp",

       "HostId", "CustomerId", "CustomerName", "Originator",

       "OriginatorId", "FlowId", "FlowName", "ActionId", "ActionName",

       "IsTriggerAction", "SessionId", "TransactionId",

       "ApplicationRegion", "PassthroughVersion", "Passthrough",

       "StartTime", "EndTime", "Path", "ExitReason"]

   }

 },

 "filters": {

   "ApplicationExitEvent": {

     "FlowId": {"$eq": "5dcf48b453e0ab04386da7d1"}

   }

 }

}

Headers:

Status: 201
Content-Type: application/json
Content-Length: 43

Body:

{
 "id": "8dc9054b258c51f9ecf1f69322d69f9"
}
Related Errors

The following errors can occur due to incorrect format or syntax in the Query API request body.

Dates should be in ISO-8601 format

Status: 400
{
  "code": 400,
  "message": {
    "Date_Filters": {
      "message": "Invalid date filters [2019-10-19 01:45:36.123Z]. They must be in ISO8601 format. Example: 'YYYY-MM-DDTHH:MM:SSZ'",
      "code": "422-6"
    }
  }
}

Available operators: ($eq, $gt, $gte, $lt, $lte, $ne)

Status: 400
{
  "code": 400,
  "message": {
    "Operators": "Invalid operators [gte, lte], try to use any of these ($gte, $lte, $gt, $lt, $ne, $eq)."
  }
}

Event names and fields are case sensitive and must match the values provided by Get Available Fields.

Status: 400
{
  "code": 400,
  "message": "Application ExitEvent is not a valid schema name."
}

Event names and fields are case sensitive and must match the values provided by Get Available Fields

Status: 400
{
  "code": 400,
  "message": "Flow Id is not a valid field."
}

There are too many queries/reports currently processing. Please wait for others to finish.

Status: 429
{
  "code": 429,
  "message": "max concurrent queries per user (maximum_number_of_queries) reached"
}
Example 3: Get Status Updates

Provides the ability to query/report status using the guid provided by Example 2. Continue using this API until the report has status “Completed”. All possible statuses are:

  • Cancelled
    Your query was cancelled due to a timeout or other error.
  • Completed
    Report is completed.
  • Pending
    Query is still in flight, keep checking until completed.
  • Failed
    The query returned empty values.
GET https://api.intelepeer.com/_rest/v4/dwh/Q/{guid}/status

Authorization: Bearer 0sjey2…
Content-Type: application/json
Status: 200

{

   "status": "Completed",

   "guid": "a3a77e4c44818481c54bdfcf4d0f03bf"

}
Related Errors

The requested ID doesn’t exist in the database.

Status: 500
[
  {
    "message": "could not get QueryRequest object: QueryRequest matching query does not exist.",
    "code": 500
  }
]

The query returned empty values. Consider adding fields or correcting query to return a result.

Status: 200

{

  "status": "Failed",

  "guid": "cb141a8039e146ad954ca70e5c0d08d6",

  "messages": [ "Query range to wide", "All data fields have empty values, advise adding core fields" ]

}
Example 4: Get Results Download Link

Once the query status is “Completed” a request can be made to get the relative URL for the download. For more information on how to access your file, visit the S3 Setup Page.

GET https://api.intelepeer.com/_rest/v4/dwh/Q/{guid}

Authorization: Bearer 0sjey2…

Content-Type: application/json
Status: 200

{

 "status": "Process finished. Download: [u'reports/guid1/guid2_QueryExport_1579194142011__000000000000.csv.gz']",

 "guid": "6ae69605c6e5ca352e664b0f96c8f84e"

}
Related Errors

The requested ID doesn’t exist in the database.

Status: 500
[
  {
    "message": "could not get QueryRequest object: QueryRequest matching query does not exist.",
    "code": 500
  }
]

The results aren’t ready yet.

Status: 200
{
  "status": "Process has not finish yet, please verify the status of your request", 
  "guid": "6ae69605c6e5ca352e664b0f96c8f84e"
}