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 can 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 the 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 API Data Dictionary.

  2. 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.

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

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

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

  4. 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, check out 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}

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

Examples

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 API Data Dictionary.

Request

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

Authorization: Bearer 0sjey2…

Content-Type: application/json

Response (JSON)

Headers:

Status: 200

Content-Type: application/json

Body:

Copy
{
"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 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, both child attributes filters and scope must be provided

    • filters provide 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…

        Note: Currently limited to the common field "SessionId".

  • "filters"

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

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

Check out Design a Query for more information.

Request 1

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 only has one column: FlowId

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

Authorization: Bearer 0sjey2…

Content-Type: application/json

Copy
{
 "timestamp": {
   "$gte": "2019-11-25T00:00:00Z",
   "$lte": "2019-11-26T00:00:00Z"
 },
 "data": {
   "ApplicationExitEvent": {
       "fields": ["FlowId"]
   }
 }
}

Response (JSON)

Headers:

Status: 201

Content-Type: application/json

Content-Length: 43

Body:

Copy
{
 "id": "ae9faa8e3cee29e5185578ad028e29f2"
}

Request 2

Request any/all ApplicationExitEvent records associated to FlowId 5dcf48b453e0ab04386da7d1

POST /_rest/v4/dwh/Q

Authorization: Bearer 0sjey2n81hamxis=/

Content-Type: application/json

Copy
{
 "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"}
   }
 }
}

Response (JSON)

Headers:

Status: 201

Content-Type: application/json

Content-Length: 43

Body:

Copy
{
 "id": "8dc9054b258c51f9ecf1f69322d69f9"
}

Related Errors

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

Incorrect Date Format

Dates should be in ISO-8601 format

Status: 400

Copy
{
  "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"
    }
  }
}
Incorrect Operators

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

Status: 400

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

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

Status: 400

Copy
{
  "code": 400,
  "message": "Application ExitEvent is not a valid schema name."
}
Invalid Event Field Name

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

Status: 400

Copy

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

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

Status: 429

Copy
{
  "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:

  • Canceled

    Your query was canceled 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.

Request

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

Authorization: Bearer 0sjey2…

Content-Type: application/json

Response (JSON)

Status: 200

Copy
{
   "status": "Completed",
   "guid": "a3a77e4c44818481c54bdfcf4d0f03bf"
}

Related Errors

ID Not Found

The requested ID doesn’t exist in the database.

Status: 500

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

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

Status: 200

Copy
{
  "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, check out File Storage Setup.

Request

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

Authorization: Bearer 0sjey2…

Content-Type: application/json

Response (JSON)

Status: 200

Copy
{
 "status": "Process finished. Download: [u'reports/guid1/guid2_QueryExport_1579194142011__000000000000.csv.gz']",
 "guid": "6ae69605c6e5ca352e664b0f96c8f84e"
}

Related Errors

ID Not Found

The requested ID doesn’t exist in the database.

Status: 500

Copy
[
  {
    "message": "could not get QueryRequest object: QueryRequest matching query does not exist.",
    "code": 500
  }
]
Process Has Not Finished

The results aren’t ready yet.

Status: 200

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