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 Units
A unit controls how a KPI's values are typed in and displayed — currency, percentage, plain number, decimal places. Units belong to your account, so unlike icons and frequencies you can create your own.
A unit still in use by a KPI cannot be deleted.
Base URL https://api.simplekpi.com/v1
Endpoints
- List KPI units —
GET /v1/kpiunits - Create a KPI unit —
POST /v1/kpiunits - Get a KPI unit —
GET /v1/kpiunits/{id} - Update a KPI unit —
PUT /v1/kpiunits/{id} - Delete a KPI unit —
DELETE /v1/kpiunits/{id}
KPI unit object
| Name | Type | Read Only | Mandatory | Max Len. | Notes |
|---|---|---|---|---|---|
id | integer | yes | no | Assigned by SimpleKPI when the unit is created. | |
name | string | no | yes | 25 | What the unit is called, e.g. Pounds or Percent. |
entry_format | string | no | yes | 25 | A numeric format string used when values are typed in. Digits and # are placeholders, , groups thousands, and one decimal group is allowed — for example #,##0.00, 0.## or #.00. |
display_format | string | no | yes | 25 | The format used when the value is shown, in the same notation as entry_format. |
is_percentage | boolean | no | no | True when values are treated as percentages. | |
created_at | datetime | yes | no | ||
updated_at | datetime | yes | no |
List KPI units
GET /v1/kpiunits
Requires kpis:read on the API key.
Parameters
| Name | Type | Required | Default | Notes |
|---|---|---|---|---|
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/kpiunits \ -H "Authorization: Bearer skpi_your_api_key"
Example response
Status: 200 OK
[
{
"id": 123,
"name": "Pounds",
"entry_format": "#,##0.00",
"display_format": "#,##0",
"is_percentage": false,
"created_at": "2026-02-21T10:57:00",
"updated_at": "2026-02-21T10:57:00"
}
]Status codes
| Code | Meaning |
|---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
429 | Too Many Requests |
Create a KPI unit
POST /v1/kpiunits
Requires kpis:write on the API key.
Using curl
curl https://api.simplekpi.com/v1/kpiunits \
-X POST \
-H "Authorization: Bearer skpi_your_api_key" \
-H "Content-Type: application/json" \
-d '{"name":"Pounds","entry_format":"#,##0.00","display_format":"#,##0","is_percentage":false}'Example request body
{
"name": "Pounds",
"entry_format": "#,##0.00",
"display_format": "#,##0",
"is_percentage": false
}Status codes
| Code | Meaning |
|---|---|
201 | Created |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
409 | Conflict |
429 | Too Many Requests |
Get a KPI unit
GET /v1/kpiunits/{id}
Requires kpis:read on the API key.
Parameters
| Name | Type | Required | Default | Notes |
|---|---|---|---|---|
id | integer | yes | The unit to return. |
Using curl
curl https://api.simplekpi.com/v1/kpiunits/{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 unit
PUT /v1/kpiunits/{id}
A full replacement, not a patch.
Requires kpis:write on the API key.
Parameters
| Name | Type | Required | Default | Notes |
|---|---|---|---|---|
id | integer | yes | The unit to replace. |
Using curl
curl https://api.simplekpi.com/v1/kpiunits/{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 |
409 | Conflict |
429 | Too Many Requests |
Delete a KPI unit
DELETE /v1/kpiunits/{id}
A unit still assigned to a KPI cannot be deleted — reassign those KPIs first.
Requires kpis:write on the API key.
Parameters
| Name | Type | Required | Default | Notes |
|---|---|---|---|---|
id | integer | yes | The unit to delete. |
Using curl
curl https://api.simplekpi.com/v1/kpiunits/{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 |