Request

Request Signature:

URL: https:/execute
Method: POST (keepalive request is supported as a GET method as well)
Content Encoding: utf-8
Content Type: application/json

Request Parameters

Parameter	Location	Description	Mandatory	Default
body	Body	The request body holds a raw UTF-8 encoded string representing a Command Object	Yes	N/A
authToken	Header	A secure authentication token	Yes	N/A
bankId	Header	The financial institution identifier – will be documented in reporting tables	No	Null
channel	Request Parameter	The name of the channel sending the command.	Yes	N/A

Command Object

Commands are passed as standard JSON objects with the following common fields:

Parameter	Description	Mandatory	Default	Type
type	Specifies the type of command to execute. Each command is identified by a unique string constant.	Yes	N/A	String
protocolVersion	Version number of command protocol - currently 2.6.	Yes	N/A	String
clientVersion	Version number of client code that is calling the API (Personetics widget version\bank client version, depends on the caller)	No	null	String
lang	The language in which the texts fields will be returned.	No	English	String
bankSessionId	When running getInsights or getNumberOfInsights on a session where insights where already generated on, the request will not run the DI process or generate insights again. Furthermore, the bankSessionId appears in the Personetics logs and reporting tables to allow full tractability of the user activity across systems.	No	null	String
hints	A JSON object with arbitrary data hints to accompany the command. The structure and content of the data hints is flexible and can be set for each project independently.	No	Null	object

The Command JSON may include additional fields relevant to specific command types. A sample command in JSON format:

{ 
"type": "getInsights", 
"protocolVersion": "2.6", 
"ctxId": "sampleTopRelevant", 
"lang": "en",
"bankSessionId": "62c2132b-a731-4da3-b6cc-8255fcb52219", 
"hints": { ... } 
}

Command Wrapper

The request command wrapper has three main properties:

Parameter	Description	Mandatory	Type
type	Always has the constant ‘cmdWrapper’.	yes	String
cmd	Contains the list of properties of the original request. For example, in the request type ‘getInsights’, the ‘cmd’ property will include all the properties used by original ‘getInsights’ request.	yes	Object
hints	Contains the hints which is JSON object.	no	Object

Sample command in JSON format:

{ 
"type": "cmdWrapper", 
"cmd": { 
	"type": "getInsights", 
		"protocolVersion": "2.6", 
		"clientVersion": "2.4.X", 
		"ctxId": "sampleTopRelevant",
		"bankSessionId": "62c2132b-a731-4da3-b6cc-8255fcb52219", 
		"lang": "en" 
			}, 
"hints": {"partyData64":"..."} 
}

Authentication Token

Personetics uses secure authentication tokens for single-sign-on with bank systems. The key role of the authentication token is to securely identify the end user for the command.

The following authentication options are available:

Clear text – The user ID is provided as a clear text HTTP header. This is the simplest form of authentication that is often used for early development stages. Note that when encrypted, communication is used (such as mutual SSL encryption). This approach poses no security risks. This option is enabled by default.
Java Web Tokens – User information is provided using the signed JSON objects according to the JWT standard. Personetics servers should be configured with a shared secret and the name of the user ID field in order to use this authentication option.
Custom – User information is provided according to a custom schema defined by the bank. In many cases, this involves custom encryption using shared secrets and keys. Using this option requires custom configuration of Personetics servers in order to enable them to extract user information form the custom token.