Developer API

Groups

Groups are used to define grouping of users and user's data or your company hierarchy. The groups may be Countries, Offices, Teams etc.
Group items are added to a group and can then be assigned to a user. The group items are then used as part of user access rights and to determine how the user's KPI entries are grouped for analytics and reporting purposes.

Group Object

The object has the following properties:

Name Type Is Read Only Is Mandatory Max Length Notes
id integer (16 bit) yes no   Automatically assigned when creating a group
name string no yes 50 The name of the group
sort_order integer (16 bit) no yes   The display order of the group
created_at datetime yes no   The date and time the group was created
updated_at datetime yes no   The date and time of the last update of the group

JSON Example

{
  "id":		1,
  "name":	"Offices",
  "sort_order": 1,
  "created_at": "2011-11-20T10:40:00",
  "updated_at": "2012-11-30T11:40:00"
}

XML Example

<group xmlns="http://schemas.datacontract.org/2004/07/SimpleKPI.Application.Areas.Api.Models" 
      xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <id>1</id>
  <name>Offices</name>
  <sort_order>1</sort_order>
  <created_at>2012-11-30T10:40:00</created_at>
  <updated_at>2012-11-30T10:40:00</updated_at>
</group>

 

Get All Groups

GET /api/groups

Using curl

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

Example Response

Status: 200 OK
[
 {
    "id":         1,
    "name":       "Offices",
    "sort_order": 1,
    "created_at": "2012-11-30T10:40:00",
    "updated_at": "2012-11-30T10:40:00"
  },
  {
    "id":         2,
    "name":       "Departments",
    "sort_order": 2,
    "created_at": "2013-02-06T17:08:00",
    "updated_at": "2013-02-06T17:08:00"
  }
]

 

Get a Group

GET /api/groups/{id}

Using curl

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

Example Response

Status: 200 OK
{
  "id":1,
  "name":"Offices",
  "sort_order":1,
  "created_at":"2012-11-30T10:40:00",
  "updated_at":"2012-11-30T10:40:00"
}

 

Add a Group

POST /api/groups

Using curl

curl https://{subdomain}.simplekpi.com/api/groups
  -H "Content-Type: application/json" -d '{"name": "My Group", "sort_order": 1}'
  -v -u {email_address}:{token} -X POST

Example Response

Status: 201 Created
Location: https://{subdomain}.simplekpi.com/api/groups/{id}
{
  "id":1,
  "name":"Offices",
  "sort_order":1,
  "created_at":"2012-11-30T10:40:00",
  "updated_at":"2012-11-30T10:40:00"
}

 

Update a Group

PUT /api/groups/{id}

Using curl

curl https://{subdomain}.simplekpi.com/api/groups/{id}
  -H "Content-Type: application/json" -d '{"name": "My Group", "sort_order": 1}'
  -v -u {email_address}:{token} -X PUT

Example Response

Status: 200 OK
{
  "id":1,
  "name":"Offices",
  "sort_order":1,
  "created_at":"2012-11-30T10:40:00",
  "updated_at":"2012-11-30T10:40:00"
}

 

Delete Group

DELETE /api/groups/{id}

Using curl

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

Example Response

Status: 200 OK