KPI Categories / KPIs

These are the KPIs that are associated with the KPI category. And allow you to easily list and manage KPIs within a specific category.

KPI Object

The object has the following properties:

Name	Type	Read Only	Mandatory	Max Len.	Notes
id	integer	yes	no		Automatically generated for the KPI
category_id	integer	yes	no		The id of the category the KPI is in
icon_id	integer (16 bit)	no	yes		The id of the icon to assign to the KPI
unit_id	integer	no	yes		The id of the unit of measure to assign to the KPI
frequency_id	character	no	yes	1	The id of the frequency of data entry for the KPI. This field is case sensitive and must be uppercase.
name	string	no	yes	100	The name of the KPI
description	string	no	no	150	The description of the KPI
target_default	decimal	no	no		The default target value for the KPI. If left blank or null the KPI will not have a target
value_direction	character	no	yes	1	The value direction is case sensitive and can only be U(p), D(own) and N(one)
aggregate_function	string	no	yes	3	The aggregate function determines how the KPI is calculated and can be either AVG (Average) or SUM (Total Sum).
sort_order	integer (16 bit)	no	yes		The display order of the KPI
is_active	boolean	no	yes		Active KPIs can have date entered against them otherwise they are display only KPIs
is_calculated	boolean	yes	no		Calculated KPIs cannot be amended via the API and must be added / amended in the interface
created_at	datetime	yes	no		The UTC date and time the KPI was created
updated_at	datetime	yes	no		The UTC date and time the KPI was updated

JSON Example

{
  "id":                 1234,
  "category_id":        5478,
  "icon_id":            1,
  "unit_id":            123,
  "frequency_id":       "W",
  "name":               "Sales KPI",
  "description":        "This is the description",
  "target_default":     null,
  "value_direction":    "N",
  "aggregate_function": "SUM",
  "sort_order":         1,
  "is_active":          true,
  "is_calculated":      false,
  "created_at":         "2013-02-21T10:57:00",
  "updated_at":         "2013-02-21T10:58:00"
}

XML Example

<KPI xmlns="http://schemas.datacontract.org/2004/07/SimpleKPI.Application.Areas.Api.Models" 
     xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <id>1234</id>
  <category_id>5478</category_id>
  <icon_id>1</icon_id>
  <unit_id>123</unit_id>
  <frequency_id>W</frequency_id>
  <name>Sales KPI</name>
  <description>This is the description</description>
  <target_default>null</target_default>
  <value_direction>N</value_direction>
  <aggregate_function>SUM</aggregate_function>
  <sort_order>1</sort_order>
  <is_active>true</is_active>
  <is_calculated>false</is_calculated>
  <created_at>2013-02-21T10:12:00</created_at>
  <updated_at>2013-02-21T10:12:00</updated_at>
</KPI>

 

Get all KPIs in the Category

GET /api/kpicategories/{category_id}/kpis

Using curl

curl https://{subdomain}.simplekpi.com/api/kpicategories/{category_id}/kpis
  -v -u {email_address}:{token}

Example Response

Status: 200 OK
[
  {
    "id":                 1234,
    "category_id":        5478,
    "icon_id":            1,
    "unit_id":            123,
    "frequency_id":       "W",
    "name":               "Sales KPI",
    "description":        "This is the description",
    "target_default":     null,
    "value_direction":    "N",
    "aggregate_function": "SUM",
    "sort_order":         1,
    "is_active":          true,
    "is_calculated":      false,
    "created_at":         "2013-02-21T10:57:00",
    "updated_at":         "2013-02-21T10:58:00"
  },
  {
    "id":                 1235,
    "category_id":        5478,
    "icon_id":            2,
    "unit_id":            125,
    "frequency_id":       "D",
    "name":               "Daily Calls",
    "description":        "This is the description",
    "target_default":     100,
    "value_direction":    "U",
    "aggregate_function": "AVG",
    "sort_order":         2,
    "is_active":          true,
    "is_calculated":      false,
    "created_at":         "2013-02-21T10:57:00",
    "updated_at":         "2013-02-21T10:58:00"
  }
]

 

Get a KPI in the Category

GET /api/kpicategories/{category_id}/kpis/{id}

Using curl

curl https://{subdomain}.simplekpi.com/api/kpicategories/{category_id}/kpis/{id}
  -v -u {email_address}:{token}

Example Response

Status: 200 OK
{
  "id":                 1234,
  "category_id":        5478,
  "icon_id":            1,
  "unit_id":            123,
  "frequency_id":       "W",
  "name":               "Sales KPI",
  "description":        "This is the description",
  "target_default":     null,
  "value_direction":    "N",
  "aggregate_function": "SUM",
  "sort_order":         1,
  "is_active":          true,
  "is_calculated":      false,
  "created_at":         "2013-02-21T10:57:00",
  "updated_at":         "2013-02-21T10:58:00"
}

 

Add a KPI to the Category

POST /api/kpicategories/{category_id}/kpis

Using curl

curl https://{subdomain}.simplekpi.com/api/kpicategories/{category_id}/kpis
  -H "Content-Type: application/json" 
  -d '{"icon_id":1, "unit_id":123, "frequency_id":"W", "name":"Sales KPI", 
       "description":"New description", "target_default":100, "value_direction":"N",
       "sort_order":1, "is_active":true}'
  -v -u {email_address}:{token} -X POST

Example Response

Status: 201 Created
Location: https://{subdomain}.simplekpi.com/api/kpicategories/{category_id}/kpis/{id}
{
  "id":                 1234,
  "category_id":        5478,
  "icon_id":            1,
  "unit_id":            123,
  "frequency_id":       "W",
  "name":               "Sales KPI",
  "description":        "This is the description",
  "target_default":     null,
  "value_direction":    "N",
  "aggregate_function": "SUM",
  "sort_order":         1,
  "is_active":          true,
  "is_calculated":      false,
  "created_at":         "2013-02-21T10:57:00",
  "updated_at":         "2013-02-21T10:58:00"
}

 

Update a KPI in the Category

PUT /api/kpicategories/{category_id}/kpis/{id}

Using curl

curl https://{subdomain}.simplekpi.com/api/kpicategories/{category_id}/kpis/{id}
  -H "Content-Type: application/json" 
  -d '{"icon_id":1, "unit_id":123, "frequency_id":"W", "name":"Sales KPI", 
       "description":"New description", "target_default":100, "value_direction":"N",
       "sort_order":1, "is_active":true}'
  -v -u {email_address}:{token} -X PUT

Example Response

Status: 200 OK
{
  "id":                 1234,
  "category_id":        5478,
  "icon_id":            1,
  "unit_id":            123,
  "frequency_id":       "W",
  "name":               "Sales KPI",
  "description":        "This is the description",
  "target_default":     null,
  "value_direction":    "N",
  "aggregate_function": "SUM",
  "sort_order":         1,
  "is_active":          true,
  "is_calculated":      false,
  "created_at":         "2013-02-21T10:57:00",
  "updated_at":         "2013-02-21T10:58:00"
}

 

Delete a KPI in the Category

DELETE /api/kpicategories/{category_id}/kpis/{id}

Using curl

curl https://{subdomain}.simplekpi.com/api/kpicategories/{category_id}/kpis/{id}
  -v -u {email_address}:{token}

Example Response

Status: 200 OK