BackAPI reference
- Overview
- Authentication
- Errors and limits
- Code examples
- Moving from Classic
- KPIs
- KPI Categories
- KPI Categories / KPIs
- Breakdown Items
- KPI Entries
- KPI Frequencies
- KPI Icons
- KPI Units
- Reports
- Users
SimpleKPI AI › API reference
KPI Categories / KPIs
The same KPI object as KPIs, reached through its category. Use these when you already know the category and want to list or create KPIs inside it without filtering the whole account.
A KPI created here takes the category from the URL, so
category_id in the body is ignored.
Base URL https://api.simplekpi.com/v1
Endpoints
- List the KPIs in a category —
GET /v1/kpicategories/{category_id}/kpis - Create a KPI in a category —
POST /v1/kpicategories/{category_id}/kpis - Get a KPI in a category —
GET /v1/kpicategories/{category_id}/kpis/{id} - Update a KPI in a category —
PUT /v1/kpicategories/{category_id}/kpis/{id} - Delete a KPI in a category —
DELETE /v1/kpicategories/{category_id}/kpis/{id}
KPI object
| Name | Type | Read Only | Mandatory | Max Len. | Notes |
|---|---|---|---|---|---|
id | integer | yes | no | Assigned by SimpleKPI when the KPI is created. | |
category_id | integer | no | no | The category the KPI belongs to. | |
icon_id | integer (16 bit) | no | no | The icon shown against the KPI. Although the contract does not mark it mandatory, the value is checked — omitting it sends 0, which is not a real icon, and the request fails with 400. Read the ids from KPI Icons. | |
unit_id | integer | no | no | How the KPI's values are formatted. Checked against your account for the same reason as icon_id, so send a real id from KPI Units rather than leaving it out. | |
frequency_id | string | no | yes | How often data is entered against the KPI. Case sensitive, and must be one of the ids returned by KPI Frequencies. D Daily, W Weekly, M Monthly, Q Quarterly, Y Yearly. | |
name | string | no | yes | 100 | What the KPI is called. |
description | string | no | no | 150 | Nullable. Free text shown alongside the KPI. |
target_default | decimal | no | no | Nullable. The target applied to new entries when none is given. | |
value_direction | string | no | yes | Which way the KPI has to move to be doing well. Case sensitive. U Up is good, D Down is good, N Neither. | |
aggregate_function | string | no | yes | How the KPI's values roll up across a period. Case sensitive. SUM Add the values together, AVG Average the values. | |
is_calculated | boolean | yes | no | True when the KPI is derived from other KPIs. Calculated KPIs are maintained in the app and their entries cannot be written through the API. | |
sort_order | integer (16 bit) | no | no | Position of the KPI within its category. | |
is_active | boolean | no | no | Inactive KPIs stay on the account but are hidden from day-to-day views. | |
created_at | datetime | yes | no | ||
updated_at | datetime | yes | no |
List the KPIs in a category
GET /v1/kpicategories/{category_id}/kpis
Requires kpis:read on the API key.
Parameters
| Name | Type | Required | Default | Notes |
|---|---|---|---|---|
category_id | integer | yes | The category to list. | |
page | integer | no | 1 | Which page to return, counting from 1. |
rows | integer | no | 500 | How many rows per page. Defaults to 500. |
Using curl
curl https://api.simplekpi.com/v1/kpicategories/{category_id}/kpis \
-H "Authorization: Bearer skpi_your_api_key"Status codes
| Code | Meaning |
|---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
429 | Too Many Requests |
Create a KPI in a category
POST /v1/kpicategories/{category_id}/kpis
The category comes from the URL, so category_id in the body is ignored.
Requires kpis:write on the API key.
Parameters
| Name | Type | Required | Default | Notes |
|---|---|---|---|---|
category_id | integer | yes | The category to create the KPI in. |
Using curl
curl https://api.simplekpi.com/v1/kpicategories/{category_id}/kpis \
-X POST \
-H "Authorization: Bearer skpi_your_api_key" \
-H "Content-Type: application/json" \
-d '{"category_id":5478,"icon_id":1,"unit_id":123,"frequency_id":"W","name":"New Sales","description":"Closed-won deals per week","target_default":100,"value_direction":"U","aggregate_function":"SUM","sort_order":1,"is_active":true}'Example request body
{
"category_id": 5478,
"icon_id": 1,
"unit_id": 123,
"frequency_id": "W",
"name": "New Sales",
"description": "Closed-won deals per week",
"target_default": 100,
"value_direction": "U",
"aggregate_function": "SUM",
"sort_order": 1,
"is_active": true
}Status codes
| Code | Meaning |
|---|---|
201 | Created |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
429 | Too Many Requests |
Get a KPI in a category
GET /v1/kpicategories/{category_id}/kpis/{id}
Returns 404 if the KPI exists but sits in a different category.
Requires kpis:read on the API key.
Parameters
| Name | Type | Required | Default | Notes |
|---|---|---|---|---|
category_id | integer | yes | The category the KPI is in. | |
id | integer | yes | The KPI to return. |
Using curl
curl https://api.simplekpi.com/v1/kpicategories/{category_id}/kpis/{id} \
-H "Authorization: Bearer skpi_your_api_key"Status codes
| Code | Meaning |
|---|---|
200 | OK |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
429 | Too Many Requests |
Update a KPI in a category
PUT /v1/kpicategories/{category_id}/kpis/{id}
Requires kpis:write on the API key.
Parameters
| Name | Type | Required | Default | Notes |
|---|---|---|---|---|
category_id | integer | yes | The category the KPI is in. | |
id | integer | yes | The KPI to replace. |
Using curl
curl https://api.simplekpi.com/v1/kpicategories/{category_id}/kpis/{id} \
-X PUT \
-H "Authorization: Bearer skpi_your_api_key"Status codes
| Code | Meaning |
|---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
429 | Too Many Requests |
Delete a KPI in a category
DELETE /v1/kpicategories/{category_id}/kpis/{id}
Deletes the KPI and its entries.
Requires kpis:write on the API key.
Parameters
| Name | Type | Required | Default | Notes |
|---|---|---|---|---|
category_id | integer | yes | The category the KPI is in. | |
id | integer | yes | The KPI to delete. |
Using curl
curl https://api.simplekpi.com/v1/kpicategories/{category_id}/kpis/{id} \
-X DELETE \
-H "Authorization: Bearer skpi_your_api_key"Status codes
| Code | Meaning |
|---|---|
204 | No Content |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
429 | Too Many Requests |