Developer API

The API Overview

This is the overview of the SimpleKPI application programming interface (Rest API). The documentation will outline the usage, restrictions and policy of the API.

When describing a resource, we use curly braces for identifiers, like {subdomain} when talking about the URL for your SimpleKPI account, i.e. https://{subdomain}.simplekpi.com/api/users .

Change Policy

We reserve the right to add to the API without advance notice. Breaking changes such as removing or renaming object properties may happen on the existing version of the API with two weeks notice and any deprecation will be documented in the relevant sections. Major structural changes will only happen within the context of a version update.

Security and Restrictions

This API is SSL-only and can only be accessed via https://{subdomain}.simplekpi.com/api/. The authorization is basic authentication with your username and account API token. This token is available in your SimpleKPI account under the Settings | Developer API section. API access is disabled by default and must be enabled before the API can be accessed. The Individual price plan does not have access to the API and you will need to upgrade your plan to gain access.

Supplying Basic Auth headers

If you need to, you may construct and send basic auth headers yourself. To do this you need to perform the following steps:

  1. Build a string of the form username:token
  2. Base64 encode the string

Supply an Authorization header with content Basic followed by the encoded string, e.g. Basic XZZRtaW46YARtaF8=

curl -H "Authorization: Basic XZZRtaW46YARtaF8="
  -H "Content-Type: application/json"
  https://{subdomain}.simplekpi.com/api/users

JSON or XML

This API will accept and return either JSON or XML. In order tell the API which content type you wish to work with, you must supply a Content-Type: application/json  or a  Content-Type: application/xml header on all GET ,PUT , POST and DELETE requests. You may also set a Accept: application/json or Accept: application/xml header on your requests, but it will be inferred by the Content-Type header.

NOTE: When using cUrl on windows the data will need to be surrounded by quotes " and escaped as following: 

curl https://{subdomain}.simplekpi.com/api/kpientries
  -H "Content-Type: application/json" 
  -d "{\"user_id\": 1234, \"kpi_id\": 5678, \"entry_date\": \"2012-06-25\", \"actual\": 50, \"target\": 110, \"notes\": \"This is a note\"}"
  -v -u {email_address}:{token} -X POST

Handling Errors

If SimpleKPI is having trouble processing your request you will see a 5xx error. 500 means that the application has encountered an unforeseen issue or is down, when this occurs our support team will be notified by the system. It will be your responsibility to retry your request later or contact simplekpi support at support@simplekpi.com.
If you are using .NET then an exception of type System.Net.WebException will be thrown on all 4xx and 5xx http errors.

Rate Limiting

This API is rate limited and will only allow a limited number of requests per minute. We reserve the right to adjust the rate limit for given endpoints in order to provide a high quality of service for all clients. As an API consumer, you should expect to be able to make at least 200 requests per minute.

If the rate limit is exceeded, you will receive a response with a HTTP 403 Forbidden response code and a body that details the reason for the rate limiter kicking in. Further, the response will have a Retry-After header that shows how many seconds you have to wait before sending your next request. You should anticipate this in your API client for the smoothest possible ride.

In addition to the default rate limit headers you will also see:

  • X-RateLimit-Limit
  • X-RateLimit-Requests
  • X-RateLimit-Duration

Active API Controllers

Help us make it better

We want our API to be as clean and simple as our interface. One of the components of the popularity of SimpleKPI is listening to our users and incorporating that feedback into future releases. So please feel free to contact us at support@simplekpi.com to tell us about your experiences, frustrations, suggestions and ideas and we will work hard to make these improvements.