SimpleKPI Logo
Talk to us
BackDeveloper APITake a Trial

Groups / Group Items

Group items belong to groups and form part of the user grouping or company hierarchy. Possible group item examples for group 'Countries' might be United Kingdom, Australia, Brazil 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 Item Object

The object has the following properties:

NameTypeIs Read OnlyIs MandatoryMax LengthNotes
idintegeryesno Automatically assigned when creating a group item
group_idinteger (16 bit)noyes The id of the group the item belongs in
namestringnoyes100The name of the item
sort_orderinteger (16 bit)noyes The display order of the item
created_atdatetimeyesno The UTC date and time the item was created
updated_atdatetimeyesno The UTC date and time of the last update of the item

JSON Example

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

XML Example

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

 

Get all Group items

GET /api/groups/{group_id}/items

Using curl

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

Example Response

Status: 200 OK
[
  {
      "id":         2263,
      "group_id":   1,
      "name":       "Sales",
      "sort_order": 1,
      "created_at": "2012-11-30T10:41:00",
      "updated_at": "2012-11-30T10:41:00"
    },
    {
      "id":         2264,
      "group_id":   1,
      "name":       "Human Resources",
      "sort_order": 2,
      "created_at": "2012-11-30T10:41:00",
      "updated_at": "2012-11-30T10:41:00"
    }
]

 

Get a Group Item

GET /api/groups/{group_id}/items/{id}

Using curl

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

Example Response

Status: 200 OK
{
  "id":         2263,
  "group_id":   1,
  "name":       "Sales",
  "sort_order": 1,
  "created_at": "2011-11-20T10:40:00",
  "updated_at": "2012-11-30T11:40:00"
}

 

Add a Group Item

POST /api/groups/{group_id}/items

Using curl

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

Example Response

Status: 201 Created
Location: https://{subdomain}.simplekpi.com/api/groups/{group_id}/items/{id}
{
  "id":         2263,
  "group_id":   1,
  "name":       "Sales",
  "sort_order": 1,
  "created_at": "2011-11-20T10:40:00",
  "updated_at": "2012-11-30T11:40:00"
}

 

Update a Group Item

PUT /api/groups/{group_id}/items/{id}

Using curl

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

Example Response

Status: 200 OK
{
  "id":         2263,
  "group_id":   1,
  "name":       "Sales",
  "sort_order": 1,
  "created_at": "2011-11-20T10:40:00",
  "updated_at": "2012-11-30T11:40:00"
}

 

Delete Group Item

DELETE /api/groups/{group_id}/items/{id}

Using curl

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

Example Response

Status: 200 OK