EFC API Basics

The Etuma Feedback Categorizerâ„¢ system may be accessed through a web service interface.

The SOAP (Simple Object Access Protocol) and interface enables the user to add signals (customer feedbacks, messages, other texts) and make queries into the system to receive analysis results for specific signals, results for specified search terms and the internet addresses for the visualisations for groups of signals.

The WSDL (Web Service Description Language) definition for SOAP-method calls:

The description/documentation for the interface:

The SOAP interface supports both Document/Literal and RPC/Encoded SOAP-bindings.

The RESTful (HTTP request) API exposes the same methods as the SOAP API with an additional GetAccessToken() method or a Data Slot Key which enable the use of a custom header overriding the need for a signature.
The REST API also implements some additional methods that are not in the SOAP interface:

  • GetSignals
  • GetSignalComplex
  • GetSignalsComplex
Please see the REST method reference for further information.

The endpoint for RESTFull HTTP requests is
HTTP verbs POST, GET and PUT are supported. The interface produces JSON encoded results by default and expects input by POST/PUT to be JSON encoded.

The interface may be used after a user has been established in the system with an Etuma Access Key and an Etuma Secret Key for signing the interface call messages. The signing procedure is required to ensure the identity of the user and the validity of the request.
In addition to the access credentials, a user requires at least one data slot, where signals may be added for analysis and visualisation. For data slot specific method calls a Data Slot Key (see Authentication below) may be used instead of the method signing procedure.
A data slot (signal group, storage item) is a collection item specific to the user where the user may add new signals. In the webservice methods the identifier parameter for the data slot is subsignalformid.
Eg. When adding a signal to the system the message (signal) must contain the subject, the text body, possibly a number of background variables, the signature, and the subsignalformid which is the identifier for the system internal storage item (of which a user may have multiple). All incoming material is encrypted with user specific 256-bit AES encryption.

Each SOAP API method call must be validated by including an XML-signature with the call as a parameter (signature).
The signature string:
The RFC 2104 HMAC-SHA1 digest (see of the concatenation of:

  1. 'Semport'
  3. Timestamp

using your Etuma Secret Key as the key.
For example, in an 'AddSignal' function request, the signature element would contain the HMAC-SHA1 digest of the value
given the key 'XXXXX'

Each method call must also include the user's Etuma Access Key (accesskey) and the timestamp (timestamp) that was used to create the signature. The timestamp must be within a few hours of the current time (GMT) on Etuma servers or the request will be refused.

The RESTful API can be used in the same manner as the SOAP API, but also an access token may be used for authentication.

Obtaining an access token:

To obtain an access token one must first make a signature authenticated call to the GetAccessToken() method. The return value of a successful call will contain the 'accesstoken' and 'expiresin' (expiration in seconds) values.

The 'accesstoken' value can then be used in subsequent RESTful API method calls by adding the HTTP header

Authorization: CoCoCo <Etuma Access Key>:<accesstoken>

to any call made to the service.

The access token expires after 10 minutes. It is always best to check elapsed time between time at which token was issued and the current time. If elapsed time exceeds the 10 minute time period, renew the access token by following the 'Obtaining an access token' procedure.

The RESTful API can also be accessed using a Data Slot Key.

A Data Slot Key will allow an EtumaReports user to use the API to access a specific data slot easily.

A Data Slot Key for a specific data slot can be requested from Etuma Support:

The Data Slot Key value can be used in RESTful API method calls simply by adding the HTTP header

Authorization: DataSlotKey <Email or Identifier>:<Data Slot Key>

to any dataslot specific call made to the service. No other authentication (signature, access token) or data slot identifier (subsignalformid) is necessary when making the method call.

Methods that are unavailable when using a Data Slot Key are: GetAccessToken, AddStorage, DeleteStorage, GetStorageList, GetStorageListCounts.

For basic usage only a handfull of methods need to be used.
Provided you have at least one data slot and the corresponding subsignalformid identifier for it, you may use the AddSignal and AddSignals methods to add new signals (messages) to the system.
You may list your current data slot identifiers (subsignalformids) with the GetStorageList method.
You may create new data slots with AddStorage and delete them with DeleteStorage.
GetStorageListCounts tells you how many data slots you are using and how many are available to be created.
To receive a sessioned URL for the Research Tool visualisation, use the GetVisual method.
GetDashboard returns a sessioned URL for the Dashboard visualisation.

Here is an example GET call to GetDashboard using signature authentication: lang=en& useraccesskey=MYUSERACCESSKEY& timestamp=2013-01-01T12:00:00Z& signature=XXXXX
  • The sessioned URLs remain valid for 4 hours after last use and may be used from 3 separate IP addresses (including the maker of the call). Where applicable, a total of 100 sessions (with separate settings) for a given data slot may be created per hour, after that the last created session will be used.
To fetch the analysis results for specific signals you may use GetSignal, GetSignalAdvanced, GetSignalFull or GetSignalComplex. They all take a parameter receipt which is returned by each call to AddSignal and AddSignals (array of receipts).
The receipt is a unique identifier of a signal in the system. To fetch the analysis for a specific signal you need to save the receipts when adding signals and use them when retrieving the analysis. There is also the possibility of adding your own unique identifiers to the signals as background variables and using those to retrieve the analysis.
Using GetSignals and GetSignalsComplex it's possible to fetch all or some of the signals from a data slot.
The system works asynchronously by first receiving a signal to be analysed and returning the receipt for it, and then proceeding to analyse and visualise it. Therefore it's not possible to operate in synchronous manner in analysing material as the queued analysis may take as long as a few minutes under heavy load although under normal circumstances the analysis will be available in near real time. It's advisable to have separate timed jobs sending signals for analysis as they arrive but retrieving the results eg. every hour.
To set private data slot properties:
SetStorageProperty with property parameter values 1-8 are free to use to deposit any string data as the value parameter.
use GetStorageProperty to retrieve the values.
To set data slot analysis segment (may require special privileges):
SetStorageProperty with property parameter value 11 can be used to set the analysis segment value to one of these two character sequences:
XX - Plain - Original (non-customized) ontology
ST - General - General (default) ontology
ED - Demo - General purpose demo ontology
CO - FoodIndustry - Food production vocabulary: groceries, processed food, cookies, candies, bread etc.
CA - Automotive - Ontology for automobile production and retail, deprecated
AU - Automotive2018 - Ontology for automobile production and retail, revised version
ET - Flight - Ontology for airline companies
ME - Telecom - Ontology for telecom companies that have a broad offering. For example, internet, 
     mobile network operating and tv services
FO - Gambling - Ontology for lottery and slot-machine companies
TU - Logistics - Ontology for companies dealing with logistics
FL - Retail - Ontology for small, medium and large retail companies
RL - Webshop - Ontology for internet shopping
TR - Charter - Ontology for companies such as travel agencies, selling package tours, etc.
PS - Healthcare - Ontology for healthcare providers
FC - FinancialServices - Ontology for banks, insurance companies and other financial institutes and
     providers of financial services
LO - Hospitality - Ontology for hotels and restaurants
SA - MobileDevices - Ontology for mobile phone manufactures
MP - Media - Ontology for general media
TI - ITProductsAndServices - Ontology for companies selling IT products and/or offering IT related services
MI - MechanicalEngineeringIndustry - Ontology  for companies providing mechanical operations like
     designing, manufacturing or maintenance of mechanical structures
SO - Transportation - Ontology for companies providing transportation services
FS - FacilityServices - Ontology for public or private sector facility and environment management
AI - Social Services - Ontology for social services for analyzing feedback about the welfare system or
     social services in general					
To delete a specific signal:
Use the ClearSignal method.

General / RESTful