KPI Integration

This article is for the tech lead handling the integration between the organization’s system and Atobi.

Setting up a Connection

Authentication

Our API layer uses OAuth 2.0 standards. For third-party vendors, we generate a “client secret” token, which is then used to authorize and approve requests from the vendor platform.

This client secret is generated for the testing environment and production environment separately (we provide this client secret upon integration agreement).

The client secret is then used to get the access token, which is used in every request for that session.

Getting the Access Token

To get the access token, you must send a POST request to https://{{client_name}}.erapp.dk/oauth/token with this request body:

Headers

Key	Value
Content-Type	application/x-www-urlencodedBody

Headers

Key	Value	Description
grant-type	client_credentials	Required field
client_id	{{client_id}}	Provided by Atobi, unique per environment.
client_secret	{{client_secret}}	Provided by Atobi, unique per environment.
scope	{{scope}}	Optional field.

IMPORTANT: The server response will return the access token.

Sending KPI Data (NumberType Data Example)

Now when we have the access token, we are ready to send KPI data to the platform. To do so, we have to create a POST request in JSON format to https://{{client_name}}.erapp.dk/api/external/{{api_version}}/kpi:

Headers

Key	Value
Authorization	Bearer {{access_token}}
Accept	application/json
Content-Type	application/json

IMPORTANT: all of the dates and timestamps in your data must be provided in DATETIME format and must be provided in Unix Epoch time. KPI filtering in the application depends highly on Unix Epoch time.

Body

{
  "type": "{{unique_integration_identifier}}",
  "version": "1.0.0",
  "context": "sales",
  "data": [
    {
      "user_id": "123",
      "location_id": "321",
      "elements": [
        {
          "id": 1,
          "kpi": "device_sales",
          "object_type": "number",
          "value": "100",
          "units": "Devices sold",
          "timestamp": "2019-09-10 13:09:23", 
          "date_from": "2019-09-10 13:09:23", 
          "date_to": "2019-09-10 13:09:23"
        },
        {
          "id": 2,
          "kpi": "bonuses",
          "object_type": "number",
          "value": "150.00",
          "units": "Bonus earned",
          "timestamp": "2019-09-10 13:09:23", 
          "date_from": "2019-09-10 13:09:23", 
          "date_to": "2019-09-10 13:09:23"
        }
      ]
    },
    {
      "user_id": "89",
      "elements": [
        {
          "id": 3,
          "kpi": "points",
          "object_type": "number",
          "value": "100",
          "units": "Points",
          "timestamp": "2019-09-10 13:09:23", 
          "date_from": "2019-09-10 13:09:23", 
          "date_to": "2019-09-10 13:09:23"
        },
        {
          "id": 4,
          "kpi": "profit",
          "object_type": "number",
          "value": "250.00",
          "units": "Eur",
          "timestamp": "2019-09-10 13:09:23", 
          "date_from": "2019-09-10 13:09:23", 
          "date_to": "2019-09-10 13:09:23"
        }
      ]
    },
    {
      "location_id": "3",
      "elements": [
        {
          "id": 5,
          "kpi": "points",
          "object_type": "number",
          "value": "100",
          "units": "Points",
          "timestamp": "2019-09-10 13:09:23", 
          "date_from": "2019-09-10 13:09:23", 
          "date_to": "2019-09-10 13:09:23"
        },
        {
          "id": 6,
          "kpi": "experience",
          "object_type": "number",
          "value": "150.00",
          "units": "Experience",
          "timestamp": "2019-09-10 13:09:23", 
          "date_from": "2019-09-10 13:09:23", 
          "date_to": "2019-09-10 13:09:23"
        }
      ]
    }
  ]
}

IMPORTANT: The request body must be in valid JSON.

IMPORTANT: See the Number type section for column breakdown.

Field “Type” (Mandatory)

This field is used for specific platform integration distinctions.

Field “Version” (Mandatory)

This field is used to version the integration for backward compatibility.

Field “Context” (Mandatory)

This field is used to define the context, which helps to group related KPI data. Each unique KPI should have a unique context name.

Fields “User_id” and “Location_id"

We connect sales data through users or locations (departments/shops/countries/etc.). When sending the KPI data, it is mandatory to provide user_id or location_id (you can provide both if it applies).

Field “Data” (Mandatory)

This field is required, but the contents are platform and context-dependent. The object format inside data is described when a specific “object_type” is in use. See the “Supported types” section for more information.

Data Received (“ACK”)

If data transfer was successful - the server response code should be 2XX with status in JSON body.

Data Not Received

If the server response code is not in the 2XX category - you should mark transfer as unsuccessful.

API Throttling

We have a limit of 180 requests/1 minutes by default. This can be adjusted.

Document Variables

Variable	Type	Description
{{client_id}}	string	Unique ID provided by Atobi.
{{client_secret}}	string	Unique secret token provided by Atobi.
{{scope}}	string	Scope descriptor (optional).
{{client_name}}	string	Unique client name.
{{access_token}}	string	Access token, which is generated with client secret.
{{api_version}}	string	API version (for backward compatibility).
{{unique_integration_identifier}}	string	Specific integration identifier. This is provided by Atobi.

Supported Types

Number Type

Defines that the provided value is a number.

Supported Number Formats

integer
float
real
double

{	"id": 1,
	"kpi": "points",
	"object_type": "number",
	"value": "100",
	"units": "Points",
	"timestamp": "2019-09-10 13:09:23",
	"date_from": "2019-09-10 13:09:23",
	"date_to": "2019-09-10 13:09:23",
},

Object Breakdown

Key	Required	Description
id	true	Internal object ID provided from the platform.
kpi	true	KPI identifier used for grouping.
object_type	true	Specifies the type of information.
value	true	The actual value for the KPI, object type, will cast the value to a specific format.
units	optional	Custom field for the units used alongside the value, for example: %, Eur, Points, etc.
timestamp	true	Date format: "Y-m-d H:i:s" (must be UNIX time)
data_from	optional	Date format: "Y-m-d H:i:s" (must be UNIX time)
data_to	optional	Date format: "Y-m-d H:i:s" (must be UNIX time)