Developer API

KPI Entries

These are the KPI data entries added by a user for a specific date based on the entry frequency. The user's group items are associated with the KPI entry on adding a new entry. KPI Entries are removed permanently with their associated group items when deleted.

List of API Actions

  1. Get all KPI entries
  2. Get a KPI entry
  3. Add a KPI entry
  4. Add/Update a list of KPI entries
  5. Update a KPI entry
  6. Delete a KPI entry

KPI entry object

The object has the following properties:

NameTypeRead OnlyMandatoryMax Len.Notes
id integer yes no   Automatically generated for the KPI entry
user_id integer no yes   An id of an active user to assign to the KPI entry
kpi_id integer no yes   The kpi must be active and cannot be a calculated KPI. The KPI must also be assigned to the user
entry_date datetime no yes   The date of the entry
actual decimal no no   The actual value cannot be null if the target and notes are both null
target decimal no no   The target value of the entry. This value will be ignored if the KPI has a null target
notes string no no 500 The note associated with the KPI entry
created_at datetime yes no   The UTC date and time the KPI entry was created
updated_at datetime yes no   The UTC date and time the KPI entry was updated

JSON Example

{
      "id":         12345,
      "user_id":    1234,
      "kpi_id":     5678,
      "entry_date": "2012-06-25",
      "actual":     50.0000,
      "target":     110.0000,
      "notes":      "This is a note",
      "created_at": "2012-11-30T11:20:00",
      "updated_at": "2013-02-15T16:01:00"
    }

XML Example

<KPIEntry xmlns="http://schemas.datacontract.org/2004/07/SimpleKPI.Application.Areas.Api.Models" 
            xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
      <id>12345</id>
      <user_id>1234</user_id>
      <kpi_id>5678</kpi_id>
      <entry_date>2012-06-25</entry_date>
      <actual>50.0000</actual>
      <target>110.0000</target>
      <notes>This is a note</notes>
      <created_at>2013-02-21T10:12:00</created_at>
      <updated_at>2013-02-21T10:12:00</updated_at>
    </KPIEntry>

 

Get all KPI entries

The KPI entries are filtered based on the search query string. All the search criteria is optional and the dateFrom and dateTo will default to today's date if not sent. The action will return a maximum of 500 entries per page. If the result set has the amount of rows you set &rows=100, it's your responsibility to check the next page to see if there are any more -- you do this by adding &page=2 to the query, then &page=3 and so on.

GET /api/kpientries?userid=123&kpiid=456&dateFrom=YYYY-MM-DD&dateTo=YYYY-MM-DD&rows=100&page=2

Using curl

curl https://{subdomain}.simplekpi.com/api/kpientries?userid=123&kpiid=456&dateFrom=2012-01-01&dateTo=2012-02-01
          -v -u {email_address}:{token}

Example Response

Status: 200 OK
        [
          {
            "id":         12345,
            "user_id":    1234,
            "kpi_id":     5678,
            "entry_date": "2012-06-25",
            "actual":     50.0000,
            "target":     110.0000,
            "notes":      "This is a note",
            "created_at": "2012-11-30T11:20:00",
            "updated_at": "2013-02-15T16:01:00"
          },
          {
            "id":         12346,
            "user_id":    1235,
            "kpi_id":     5679,
            "entry_date": "2012-08-25",
            "actual":     55.0000,
            "target":     10.0000,
            "notes":      "This is a note",
            "created_at": "2012-11-30T11:20:00",
            "updated_at": "2013-02-15T16:01:00"
          }
        ]

 

Get a KPI entry

GET /api/kpientries/{id}

Using curl

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

Example Response

Status: 200 OK
    {
      "id":         12345,
      "user_id":    1234,
      "kpi_id":     5678,
      "entry_date": "2012-06-25",
      "actual":     50.0000,
      "target":     110.0000,
      "notes":      "This is a note",
      "created_at": "2012-11-30T11:20:00",
      "updated_at": "2013-02-15T16:01:00"
    }

 

Add a KPI entry

For ease of use you are able to pass in the user's email address instead of the user_id using the property name email.

POST /api/kpientries

KPI Entry Object to POST

The object has the following properties:

NameTypeRead OnlyMandatoryMax Len.Notes
user_id integer no yes if no email   The user id of an active user to assign to the KPI entry.
email string no yes if no user_id   The email address of an active user to assign to the KPI entry instead of using the user_id.
kpi_id integer no yes   The kpi must be active and cannot be a calculated KPI. The KPI must also be assigned to the user.
entry_date datetime no yes   The date of the entry
actual decimal no no   The actual value cannot be null if the target and notes are both null
target decimal no no   The target value of the entry. This value will be ignored if the KPI has a null target
notes string no no 500 The note associated with the KPI entry
setActual boolean no no   Defaults to true and when set to false, will leave the actual value as is if you only want to update the target or notes
setTarget boolean no no   Defaults to true and when set to false, will leave the target value as is if you only want to update the actual value or notes
setNotes boolean no no   Defaults to true and when set to false, will leave the notes as is if you only want to update the actual or target values
addToActual boolean no no   Defaults to false and when set to true, will add to your existing actual value. It can be used to increment or decrement the value as needed.

JSON POST Example

{
          "email":    "john@simplekpi.com",
          "kpi_id":     5678,
          "entry_date": "2012-06-25",
          "actual":     50.0000,
          "target":     110.0000,
          "notes":      "This is a note",
          "setActual":  true,
          "setTarget":  false,
          "setNotes":   false,
          "addToActual": true
        }

Using curl

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.0000, 
               "target": 110.0000, "notes": "This is a note"}'
          -v -u {email_address}:{token} -X POST

Example Response

Status: 201 Created
        Location: https://{subdomain}.simplekpi.com/api/kpientries/{id}
        {
          "id":         12345,
          "user_id":    1234,
          "kpi_id":     5678,
          "entry_date": "2012-06-25",
          "actual":     50.0000,
          "target":     110.0000,
          "notes":      "This is a note",
          "created_at": "2012-11-30T11:20:00",
          "updated_at": "2013-02-15T16:01:00"
        }

 

Add/Update a list of KPI entries

Post a list of KPI entries to batch load for speed.

POST /api/kpientries/list

KPI batch object to POST

The object has the following properties:

NameTypeRead OnlyMandatoryMax Len.Notes
entries Array of KPI Entry Objects no yes 5000 An array of KPI Entry Objects as described in Add a KPI Entry.
hasActuals boolean no no   Defaults to true and when set to false, will leave the actual values as is if you only want to update the target or notes for the batch
hasTargets boolean no no   Defaults to true and when set to false, will leave the target values as is if you only want to update the actual value or notes for the batch
hasNotes boolean no no   Defaults to true and when set to false, will leave the notes as is if you only want to update the actual or target values for the batch

JSON POST Example

        {
            "entries": [
            {
                "email":    "john@simplekpi.com",
                "kpi_id":     5678,
                "entry_date": "2012-06-25",
                "actual":     50.0000,
                "target":     110.0000,
                "notes":      "This is a note"
            },
            {
                "email":    "john@simplekpi.com",
                "kpi_id":     5678,
                "entry_date": "2012-06-26",
                "actual":     80.0000,
                "target":     50.0000,
                "notes":      "This is a note"
            }],
            "hasActuals": true,
            "hasTargets": true,
            "hasNotes": true
        }

Using curl

curl https://{subdomain}.simplekpi.com/api/kpientries/list
          -H "Content-Type: application/json" 
          -d '{"entries":[{"user_id": 1234, "kpi_id": 5678, "entry_date": "2012-06-25", "actual": 50.0000, 
               "target": 110.0000, "notes": "This is a note"}], "hasActuals": true}'
          -v -u {email_address}:{token} -X POST

Example Response

Status: 201 Created
        {
          "rows_added":   2
        }

 

 

Update a KPI entry

PUT /api/kpientries/{id}

Using curl

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

Example Response

Status: 200 OK
        {
          "id":         12345,
          "user_id":    1234,
          "kpi_id":     5678,
          "entry_date": "2012-06-25",
          "actual":     50.0000,
          "target":     110.0000,
          "notes":      "This is a note",
          "created_at": "2012-11-30T11:20:00",
          "updated_at": "2013-02-15T16:01:00"
        }

 

Delete a KPI entry

DELETE /api/kpientries/{id}

Using curl

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

Example Response

Status: 200 OK