API Reference

Start Here

Are you looking for Help? Are you looking for Support?

Developers can build their own apps with the API. The API supports building apps to get your textual insights programmatically.

When using the methods in the provided client libraries for Android and iOS, the API also supports adding our voice reply functions into your mobile app (Bring Your Own UI).

Credentials are created and managed in the Developer Console. Sign up for X Class here to access the Developer Console.

Client Libraries

The easiest and recommended way for most users to use the API is with our provided client libraries. They provide an optimized developer experience by using each supported language’s natural conventions and styles. They also reduce the boilerplate code you have to write because they’re designed to enable you to work with service metaphors in mind, rather than implementation details or service API concepts.

Android

We provide a client library for developers to add our voice reply functions into your Android app.

Github

iOS

We provide a client library for iOS developers to add our voice reply functions into your iOS app.

Github

Java

We provide a client library for Java developers to get your textual insights programmatically.

Github

We also provide a client library for Java developers to access new API methods that we are testing. Request testing credentials before using this library.

Github

Authentication

Authentication refers to the process of determining a client’s identity. Authorization refers to the process of determining what permissions an authenticated client has for a set of resources. That is, authentication identifies who you are, and authorization determines what you can do.

AimMatic provide various way to authenticate with the API. Each of them is suitable for a different use case. The following information will help developers to choose their authentication carefully and select the authentication method that is suitable to your use case.

Using API Key to authenticate

An API key is a simple encrypted string that identifies an project within an account on AimMatic services. API keys can be used when calling an AimMatic API that doesn’t require user-specific authentication.

API Key authentication is only supported by the following AimMatic Services:

  1. Upload Audio API for Natural Voice sessions

API Key authentications have limitations:

For security reasons, our services recommend using other authentication methods if possible.

See how to create API Key in our developer console.

Using API Key plus Secret Key or KeyPair to authenticate

On top of API Key above, A Secret Key is an additional hashed binary used to create signature from your request. The Secret Key provide an additional security layer on top of API Key. We recommend using API Key plus Secret Key in trusted environments where your Secret Key is safe especially in the Backend applications.

Most AimMatic Services are enabled for this type of authentication. See how to create an API Key plus Secret Key or KeyPair in our developer console

Build Your Own Authentication

The SDKs available on our github account provide a complete functionality to access our API including authentication with Secret Key or KeyPair. If there is no SDK available for your preferred language, you would like to access to our API, please read the below criteria for a complete algorithms to authenticate with our API using API Key and Secret Key.

API Header required

Header Name Header Value Description
Authorization AimMatic API Key:Signature The Authentication Header use as a validation on the request. See below how to calculate signature.
Content-Type Example: application/json The content type of the resource in case the request content in the body.
Content-MD5 Example: rL0Y20zC+Fzt72VPzMSk2A The base64 encoded 128-bit MD5 digest of the message according to RFC 1864.
Date Example: Mon, 02 Jan 2006 15:04:05 GMT The current date and time according to the requester and following RFC 1123
X-PlaceNext-Date Example: Mon, 02 Jan 2006 15:04:05 GMT The current date and time according to the requester and following RFC 1123

Calculate Signature

To Calculate API signature for backend validation please follow the formula below:

Note: We use Base64 encode and decode without padding.

Authorization = "AimMatic" + " " + SecurePlaceApiKey + ":" + Signature

Signature = Base64(HMAC-SHA256(SecurePlaceApiSecretKey, dataToSign))

dataToSign = Content-MD5 + "\n" + Content-Type + "\n" + Date + "\n" + headerConcat + "\n" + url

HTTP Header Concatenation

headerConcat is the concatenation of our header with the pair key value.

Rule:

Order Rule Sample data Description
1 all keys are lower case X-Placenext-Date The header X-Placenext-Date should transform into x-placenext-date
2 merge identical key X-Placenext-A: 123, X-Placenext-A: 456 The two header of X-Placenext-A should merge into X-Placenext-A: 123,456. Of course, rule number 1 is also apply.
3 remove all space round colon X-Placenext-A: 123 The whole string should transform into X-Placenext-A:123 and rule number 1 and number 2 also apply
4 all header key sorted concatenate the header with key alphabetic order from a to b

Example: If the contents below are found from the header in the request (of course it excludes Authorization)

Then headerConcat value is:

x-placenext-a:abcx-placenext-b:123x-placenext-date:Mon, 02 Jan 2006 15:04:05 GMT

URL

The value of the url is:

url = "https://" + host + "/" + apiEndpoint path + "?" + queryKey + "=" + queryValue

Example: https://api.aimmaitc.com/v1/insight/query?start=1&end=2

API Methods

All endpoints are available via https and are located at:

api.aimmatic.com/v1/insights

The API allows developers to safely and securely access the cloud. You can use the API to build private services. To learn how to create apps and create API keys and key pairs, please read about the Developer Console.

text (GA)

Developers use the method text to query for transcript data and trends data. Optionally, the request can provide a start and end date range to get the results from a corpus.

HTTP Request

GET https://api.aimmatic.com/v1/insights/text

API Request Query Parameter

Parameter Default Description
audioId (required, except when start and end params are provided) String
start (optional) UTC start time in millisecond, must not include audioId
end (optional) UTC end time in millisecond, must not include audioId
page (optional) Integer, for paginated results the page of the desired results
count (optional) Integer, for paginated results the count per page of results
skipMetaData (optional) Boolean, always set this parameter to “true” (not case sensitive) for requests that do not include audioID
trends (optional) Get trend data appended to the results set this parameter to “true” (not case sensitive)

API Response

Response JSON Object

Parameter Default Description
Code 200 (Good response) or 401 (Unauthorized)
Message A response message (Good response or Unauthorized)
TranscriptData Array of TranscriptData JSON Object

TranscriptData JSON Object

Parameter Default Description
confidence Floating point number, confidence estimate between 0.0 and 1.0, higher number indicates an estimated greater likelihood that the recognized words are correct, by default the transcript is merged (UploadAudio merge=“true”) and the API returns the weighted average confidence estimate for all transcripts, with the weight determined by the number of characters in each transcript
transcript String, transcript(s) of the document
language_code String, language code from metadata (omitted if metadata is skipped)
sentimentType A nested SentimentType JSON Object
audioId String
appId String
metadataAudio Object
unixTimeCreated Unix Time (https://en.wikipedia.org/wiki/Unix_time) in nanoseconds
audioLink String, a link to download the audio recording if available

SentimentType JSON Object

Parameter Default Description
score Floating point number, sentiment score between -1.0 (negative sentiment) and 1.0 (positive sentiment)
magnitude Floating point number, non-negative number in the [0, +inf) range, which represents the absolute magnitude of sentiment regardless of score (positive or negative)

nss (GA)

Developers use the method nss to query the NSS (Net Sentiment Score) calculation for a provided audioId. Optionally, the request can provide a start and end date range to get the results from a corpus. This method uses the NLP results to intelligently classify the predicted sentiment using NSS methodology, which is a proprietary algorithm to interpret the sentiment score and magnitude of a transcript.

HTTP Request

POST https://api.aimmatic.com/v1/insights/nss

API Request Query Parameter

Parameter Default Description
audioId (required, except when start and end params are provided) String
start (optional) UTC start time in millisecond, must not include audioId
end (optional) UTC end time in millisecond, must not include audioId

API Response

Response JSON Object

Parameter Default Description
Code 200 (NSS Score) or 401 (Unauthorized)
Message A response message (NSS Score or Unauthorized)
score Integer, value of Net Sentiment Score (NSS) for a provided audioId or document corpus, range of values is -1000 to 1000

ess (TEST)

Developers use the method ess to query the ESS (Entity Sentiment Score) calculation for a provided start and end date to get the results from a corpus. This method uses the NLP results to intelligently classify the predicted sentiment of the entity using ESS methodology, which is a proprietary algorithm to interpret the sentiment score and magnitude of an entity.

HTTP Request

POST https://api.aimmatic.com/v1/insights/ess

API Request Query Parameter

Parameter Default Description
saliencevalue (required) Floating point number, 0 is the recommended value, 1 and 2 are also accepted, value indicates the salience factor applied in the calculation of ESS weights
start (optional) UTC start time in millisecond, must not include audioId
end (optional) UTC end time in millisecond, must not include audioId

API Response

Response JSON Object

Parameter Default Description
Code 200 (Good response) or 401 (Unauthorized)
Message A response message (Good response or Unauthorized)
essData Array of essData JSON Object

essData JSON Object

Parameter Default Description
value Floating point number, value of Entity Sentiment Score (ESS) for a named entity, range of values is -1000 to 1000
name String, the name of the entity

categories (TEST)

Developers use the method categories to query the content classification for a provided audioId. Optionally, the request can provide a start and end date range to get the results from a corpus.

HTTP Request

POST https://api.aimmatic.com/v1/insights/categories

API Request Query Parameter

Parameter Default Description
audioId (required, except when start and end params are provided) String
start (optional) UTC start time in millisecond, must not include audioId
end (optional) UTC end time in millisecond, must not include audioId

API Response

Response JSON Object

Parameter Default Description
Code 200 (Natural Voice Categories Summary) or 401 (Unauthorized) or 403 (Forbidden)
Message A response message (Natural Voice Categories Summary or Unauthorized or Forbidden)
account String, the API Key used for authentication
numtexts Integer, the number of transcripts in the document corpus where the content category is found
records Array of Record JSON Object

Record JSON Object

Parameter Default Description
confidence A double-precision floating point number, average confidence returned for the content category, with a range of values between 0 and 1
name String, name of the content category
textpercentage A double-precision floating point number, calculated as numtexts divided by the total texts in the document corpus, with a range of values between 0 and 1

HasNLPResults/{audioId} (TEST)

Developers use the method HasNLPResults to query the status of NLP results for a provided audioId. TRUE means there is an NLP result, FALSE means there is not an NLP result. If the speech recognition result for a provided audioId is not high confidence then there is not an NLP result.

HTTP Request

POST https://api.aimmatic.com/v1/insights/HasNLPResults/{audioId}

API Request Path Parameter

Parameter Default Description
audioId (required) String

API Response

Response JSON Object

Parameter Default Description
Code 200 (Good response) or 401 (Unauthorized)
Message A response message (Good response or Unauthorized)
BooleanResponse Boolean value, TRUE means there is an NLP result, FALSE means there is not an NLP result

NLPResults (TEST)

Developers use the method NLPResults to query documents with NLPResults. The method returns sentiment, named entities, and syntax analysis after natural language processing (NLP). Optionally, the request can provide a start and end date range to get the results from a corpus.

HTTP Request

POST https://api.aimmatic.com/v1/insights/NLPResults

API Request Query Parameter

Parameter Default Description
audioId (required, except when start and end params are provided) String
start (optional) UTC start time in millisecond, must not include audioId
end (optional) UTC end time in millisecond, must not include audioId

API Response

Response JSON Object

Parameter Default Description
Code 200 (Good response) or 401 (Unauthorized)
Message A response message (Good response or Unauthorized)
transcriptData Array of NLPResults JSON Object

TranscriptData JSON Object

Parameter Default Description
sentimentType A nested sentimentType JSON Object
entities A nested entities JSON Object
syntax A nested syntax JSON Object

sentimentType JSON Object

Parameter Default Description
score Floating point number, sentiment score between -1.0 (negative sentiment) and 1.0 (positive sentiment)
magnitude Floating point number, non-negative number in the [0, +inf) range, which represents the absolute magnitude of sentiment regardless of score (positive or negative)

entities JSON Object

Parameter Default Description
name String, name of entity
type String, type of entity
salience Floating point number, with a range of values between 0 and 1

syntax JSON Object

Parameter Default Description
text A nested text JSON Object
part_of_speech A nested part_of_speech JSON Object
dependency_edge A nested dependency_edge JSON Object
lemma String, value of lemma
text JSON Object
Parameter Default Description
content String, transcribed text
begin_offset Integer, value of begin_offset
part_of_speech JSON Object
Parameter Default Description
tag String, identified part of speech
number String, identified plurality for tag NOUN
proper String, for tag NOUN identified as PROPER
dependency_edge JSON Object
Parameter Default Description
head_token_index Integer, value of head_token_index
label String, label of dependency_edge

sentibot/{audioId} (TEST)

Developers use the method sentibot to query the Sentibot response for a provided audioId. This method uses the NLP results to intelligently classify the predicted sentiment using NSS methodology, which is a proprietary algorithm to interpret the sentiment score and magnitude of a transcript.

Sentibot Responses:

Example:

If the provided audioId has an NSS score of -401, then this method returns:

{} is returned if there is not an NLP result.

HTTP Request

POST https://api.aimmatic.com/v1/insights/sentibot/{audioId}

API Request Path Parameter

Parameter Default Description
audioId (required) String

API Response

Response JSON Object

Parameter Default Description
Code 200 (Good response) or 401 (Unauthorized)
Message A response message (Good response or Unauthorized)
SentimentScript Array of SentimentScript JSON Object

SentimentScript JSON Object

Parameter Default Description
name String, name of response
value String, “true” or “false” for each name