Developer API
KPIs
These are the KPIs that are the core of the application.
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 | no | yes | 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
GET /api/kpis
Using curl
curl https://{subdomain}.simplekpi.com/api/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
GET /api/kpis/{id}
Using curl
curl https://{subdomain}.simplekpi.com/api/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
POST /api/kpis
Using curl
curl https://{subdomain}.simplekpi.com/api/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/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
PUT /api/kpis/{id}
Using curl
curl https://{subdomain}.simplekpi.com/api/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
DELETE /api/kpis/{id}
Using curl
curl https://{subdomain}.simplekpi.com/api/kpis/{id}
-v -u {email_address}:{token}
Example Response
Status: 200 OK