Groups

Groups are places for discussions where anyone can participate across units and user types.

Groups can be public (anyone can see and join, in order to participate in the group discussions), private (anyone can see the group and request to join, but not see content until request is approved) or hidden (group is not listed anywhere, but group administrators can manually add members)

Get Groups

curl "https://example.ziik.io/api/groups"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
{
  "hits": [
    {
      "id": 543,
      "content_type": "group",
      "name": "Discussion Group",
      "description": "This is a group for discussions",
      "type": "public",
      "stats": {
          "active": 4,
          "pending": 1,
          "blocked": 0
      },
      "permission": {
          "member": false,
          "edit": false,
          "delete": false
      },
      "url": "api/groups/543",
      "image": {
         "id":"345",
         "name":"avatar.png",
         "mime":"image/png",
         "size":"54314",
         "type":"image",
         "source":"https://example.ziik.io/api/file/default_images/avatar.png",
         "versions":{
             "listing":"https://example.ziik.io/api/file/styles/article_listing/private/default_images/avatar.png",
             "detail":"https://example.ziik.io/api/file/styles/article_desktop/private/default_images/avatar.png",
             "thumbnail":"https://example.ziik.io/api/file/styles/media_thumbnail/private/default_images/avatar.png"
         }
      }
    },
    {
      "id": 544,
      "content_type": "group",
      "name": "Another Discussion Group",
      "description": "This is a group for discussing other things",
      "type": "private",
      "stats": {
          "active": 4,
          "pending": 1,
          "blocked": 0
      },
      "permission": {
          "member": "member",
          "edit": false,
          "delete": false
      },
      "url": "api/groups/544",
      "image": null
    }
  ],
  "meta": {
      "pagination": {
          "total": 315,
          "count": 50,
          "per_page": 50,
          "current_page": 2,
          "total_pages": 7,
          "links": []
      }
  }
}

This endpoint retrieves a list of groups.

By default groups, the user is a member of, are returned, but it can also return non-member groups, the user can join or request to join.

HTTP Request

GET https://example.ziik.io/api/groups

Query Parameters

ParameterTypeDefaultDescription
modeStringmember'member' or 'available' to return member groups and non-member groups, respectively
pageInteger1Page number for pagination.
limitInteger50Number of records to return per page.

Get Single Group

curl "https://example.ziik.io/api/groups/543"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

  {
    "id": 543,
    "content_type": "group",
    "name": "Discussion Group",
    "description": "This is a group for discussions",
    "type": "public",
    "stats": {
        "active": 4,
        "pending": 1,
        "blocked": 0
    },
    "permission": {
        "member": "admin",
        "edit": true,
        "delete": true
    },
    "url": "api/groups/543",
    "image": {
        "id":"345",
        "name":"avatar.png",
        "mime":"image/png",
        "size":"54314",
        "type":"image",
        "source":"https://example.ziik.io/api/file/default_images/avatar.png",
        "versions":{
             "listing":"https://example.ziik.io/api/file/styles/article_listing/private/default_images/avatar.png",
             "detail":"https://example.ziik.io/api/file/styles/article_desktop/private/default_images/avatar.png",
             "thumbnail":"https://example.ziik.io/api/file/styles/media_thumbnail/private/default_images/avatar.png"
        }
    }
  }

This endpoint returns a single group

HTTP Request

GET https://example.ziik.io/api/groups/ID

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the group

Permissions Required

  • Authenticated user

Search for Groups

curl "https://example.ziik.io/api/groups/search/group"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
{
  "hits": [
    {
      "id": 543,
      "content_type": "group",
      "name": "Discussion Group",
      "description": "This is a group for discussions",
      "type": "public",
      "stats": {
          "active": 4,
          "pending": 1,
          "blocked": 0
      },
      "permission": {
        "member": false,
        "edit": false,
        "delete": false
      },
      "url": "api/groups/543",
      "image": {
        "id":"345",
        "name":"avatar.png",
        "mime":"image/png",
        "size":"54314",
        "type":"image",
        "source":"https://example.ziik.io/api/file/default_images/avatar.png",
        "versions":{
            "listing":"https://example.ziik.io/api/file/styles/article_listing/private/default_images/avatar.png",
            "detail":"https://example.ziik.io/api/file/styles/article_desktop/private/default_images/avatar.png",
            "thumbnail":"https://example.ziik.io/api/file/styles/media_thumbnail/private/default_images/avatar.png"
        }
      }
    },
    {
      "id": 544,
      "content_type": "group",
      "name": "Another Discussion Group",
      "description": "This is a group for discussing other things",
      "type": "private",
      "stats": {
          "active": 4,
          "pending": 1,
          "blocked": 0
      },
      "permission": {
        "member": false,
        "edit": false,
        "delete": false
      },
      "url": "api/groups/544",
      "image": null
    }
  ],
  "meta": {
      "pagination": {
          "total": 315,
          "count": 50,
          "per_page": 50,
          "current_page": 2,
          "total_pages": 7,
          "links": []
      }
  }
}

This endpoint retrieves a list of groups with a name similar to a search string.

By default groups, the user is a member of, are returned, but it can also return non-member groups, the user can join or request to join.

HTTP Request

GET https://example.ziik.io/api/groups/search/<KEYWORD>

URL Parameters

ParameterTypeDefaultDescription
keywordStringNULLKeyword to search for. Searches group name, not content.

Query Parameters

ParameterTypeDefaultDescription
modeStringmember'member' or 'available' to return member groups and non-member groups, respectively
pageInteger1Page number for pagination.
limitInteger50Number of records to return per page.

Create New Group

curl -i -X POST "https://example.ziik.io/api/groups"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 201 Created with a location header for where to find the new group

HTTP/1.0 201 Created
Location: https://example.ziik.io/api/groups/1234
{
    "message": "Group created"
}

This endpoint creates a new group with the current user as administrator.

HTTP Request

POST https://example.ziik.io/api/groups

Request Parameters

ParameterTypeRequiredDescription
nameStringYesName of the new group.
descriptionStringNoDescription of the new group.
typeStringNo'public', 'private' or 'hidden'. Public means anyone can see and join. Private means anyone can see, but joining requires approval from group administrator. Hidden means only members can see it, but administrators can add members manually.
imageArrayNoFile data for an image for the group. If provided, must be an array with the following values
- typeStringYesType of file - can be either 'upload', 'youtube' or 'vimeo'.
- nameStringYesFile name.
- dataStringYesIf type is 'upload' this must be the base64 encoded content of the file. Else it must be the Youtube/Vimeo embed URL.

Permissions Required

  • Write permission to groups

Edit Existing Group

curl -i -X PATCH "https://example.ziik.io/api/groups/543"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on successful group update.

HTTP/1.0 204 No Content

This endpoint updates an existing group.

HTTP Request

PATCH https://example.ziik.io/api/groups/ID

Request Parameters

ParameterTypeRequiredDescription
nameStringYesName of the new group.
descriptionStringNoDescription of the new group.
typeStringNo'public', 'private' or 'hidden'. Public means anyone can see and join. Private means anyone can see, but joining requires approval from group administrator. Hidden means only members can see it, but administrators can add members manually.
imageArrayNoFile data for an image for the group. If provided, must be an array with the following values
- typeStringYesType of file - can be either 'upload', 'youtube' or 'vimeo'.
- nameStringYesFile name.
- dataStringYesIf type is 'upload' this must be the base64 encoded content of the file. Else it must be the Youtube/Vimeo embed URL.

Permissions Required

  • Administrator of group

Delete a Group

curl -i -X DELETE "https://example.ziik.io/api/groups/543"
  -H "Authorization: Bearer aaaaaa.bbbbbbb.ccccccc"

The above command returns a 204 No Content header on success:

HTTP/1.0 204 No Content

This endpoint deletes a group along with all its debates.

HTTP Request

DELETE https://example.ziik.io/api/groups/ID

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the group to delete

Permissions Required

  • Administrator of group

Get Group Members

curl "https://example.ziik.io/api/groups/432/members"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

{
  "hits": [
    {
        "id":234,
        "name":"Test User",
        "avatar": {
            "id":"345",
            "name":"avatar.png",
            "mime":"image/png",
            "size":"54314",
            "type":"image",
            "source":"https://example.ziik.io/api/file/default_images/avatar.png",
            "versions": {
                "listing":"https://example.ziik.io/api/file/styles/article_listing/private/default_images/avatar.png",
                "detail":"https://example.ziik.io/api/file/styles/article_desktop/private/default_images/avatar.png",
                "thumbnail":"https://example.ziik.io/api/file/styles/media_thumbnail/private/default_images/avatar.png"
            }
        },
        "userType": {
            "id":11,
            "name":"Worker",
            "url":"api/user_types/11"
        },
        "url":"api/users/234"
    },
    {
        "id":234,
        "name":"Test User",
        "avatar":{
            "id":"345",
            "name":"avatar.png",
            "mime":"image/png",
            "size":"54314",
            "type":"image",
            "source":"https://example.ziik.io/api/file/default_images/avatar.png",
            "versions":{
                "listing":"https://example.ziik.io/api/file/styles/article_listing/private/default_images/avatar.png",
                "detail":"https://example.ziik.io/api/file/styles/article_desktop/private/default_images/avatar.png",
                "thumbnail":"https://example.ziik.io/api/file/styles/media_thumbnail/private/default_images/avatar.png"
            }
        },
        "userType":{
            "id":11,
            "name":"Worker",
            "url":"api/user_types/11"
        },
        "url":"api/users/234"
    },
  ],
  "meta": {
      "pagination": {
          "total": 315,
          "count": 50,
          "per_page": 50,
          "current_page": 2,
          "total_pages": 7,
          "links": []
      }
  }
}

This endpoint retrieves a list of members of a group.

HTTP Request

GET https://example.ziik.io/api/groups/ID/members

Query Parameters

ParameterTypeDefaultDescription
statusIntegermemberMembership status to fetch - 'member', 'admin' or 'pending'

Permissions Required

  • Member of group

Add New Member

curl -i -X POST "https://example.ziik.io/api/groups/543/members"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 201 Created with a location header for where to find membership details

HTTP/1.0 201 Created
Location: https://example.ziik.io/api/groups/543/members/92
{
    "message": "Test User added"
}

This endpoint adds a user to the group.

IF the current user is not a member of the group, the user ID can be omitted as it will be regarded as a join request (automatically accepted for public groups)

HTTP Request

POST https://example.ziik.io/api/groups/ID/members

Request Parameters

ParameterTypeRequiredDescription
userIntegerYes (for add)User ID of the user to add.

Permissions Required

  • Administrator of group (add)
  • OR not member of group (join)

Edit Membership

curl -i -X PATCH "https://example.ziik.io/api/groups/543/members/321"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on successful update

HTTP/1.0 204 No Content

This endpoint updates a user's membership in the group.

HTTP Request

PATCH https://example.ziik.io/api/groups/ID/members/<USERID>

Request Parameters

ParameterTypeRequiredDescription
statusIntegerNoMembership status to set 1 = member, 2 = administrator

Permissions Required

  • Administrator of group

TIP

Group administrator cannot set themselves as common members. In this case, another administrator must change the membership status.

Delete Membership

curl -i -X DELETE "https://example.ziik.io/api/groups/543/members/321"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns 204 No Content on successful update

HTTP/1.0 204 No Content

This endpoint deletes a user's membership in the group, effectively removing the user from the group

HTTP Request

PATCH https://example.ziik.io/api/groups/ID/members/<USERID>

Permissions Required

  • Either Administrator of group
  • OR User being removed from the group

TIP

Group administrator cannot remove themselves from it. In this case, another administrator must remove the user from the group.

Get Group Debates

curl "https://example.ziik.io/api/groups/432/debates"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

{
  "hits":
    [{
        "id":123,
        "content_type":"debate",
        "author":{
            "id":234,
            "name":"Test User",
            "avatar": {
                "id":"345",
                "name":"avatar.png",
                "mime":"image/png",
                "size":"54314",
                "type":"image",
                "source":"https://example.ziik.io/api/file/default_images/avatar.png",
                "versions": {
                    "listing":"https://example.ziik.io/api/file/styles/article_listing/private/default_images/avatar.png",
                    "detail":"https://example.ziik.io/api/file/styles/article_desktop/private/default_images/avatar.png",
                    "thumbnail":"https://example.ziik.io/api/file/styles/media_thumbnail/private/default_images/avatar.png"
                }
            },
            "userType": {
                "id":11,
                "name":"Worker",
                "url":"api/user_types/11"
            },
            "url":"api/users/234"
        },
        "date":1470129614,
        "files":[],
        "stats":{
            "seen":1,
            "comments":0,
            "likes": 0,
            "liked": false
        },
        "body":"Hey - this is a discussion....",
        "latest_comment": {
            "id": 45,
            "author": {
                "See user service..."
            },
            "body": "Test comment for debates",
            "date": 1476697957,
            "url": "api/comments/45",
            "permissions": {
                "edit": false,
                "delete": true
            }
        },
        "url":"api/debates/123",
        "comments_url":"api/debates/123/comments"
      },
      {
        "id":124,
        "content_type":"debate",
        "author":{
            "id":234,
            "name":"Test User",
            "avatar":{
                "id":"345",
                "name":"avatar.png",
                "mime":"image/png",
                "size":"54314",
                "type":"image",
                "source":"https://example.ziik.io/api/file/default_images/avatar.png",
                "versions":{
                    "listing":"https://example.ziik.io/api/file/styles/article_listing/private/default_images/avatar.png",
                    "detail":"https://example.ziik.io/api/file/styles/article_desktop/private/default_images/avatar.png",
                    "thumbnail":"https://example.ziik.io/api/file/styles/media_thumbnail/private/default_images/avatar.png"
                }
            },
            "userType":{
                "id":11,
                "name":"Worker",
                "url":"api/user_types/11"
            },
            "url":"api/users/234"
        },
        "date":1465910290,
        "files":[
            {
                "id":"937",
                "name":"begraensningens-kunst.png",
                "mime":"image/png",
                "size":"8731",
                "type":"image",
                "source":"https://example.ziik.io/api/file/groups/files/begraensningens-kunst.png",
                "versions":{
                    "listing":"https://example.ziik.io/api/file/styles/article_listing/private/groups/files/example.png",
                    "detail":"https://example.ziik.io/api/file/styles/article_desktop/private/groups/files/example.png",
                    "thumbnail":"https://example.ziik.io/api/file/styles/media_thumbnail/private/default_images/avatar.png"
                }
            },

        ],
        "stats":{
            "seen":3,
            "comments":0,
            "likes": 1,
            "liked": true
        },
        "body":"This is also a discussion",
        "latest_comment": {
        },
        "url":"api/debates/124",
        "comments_url":"api/debates/124/comments"
      }
  ],
  "meta": {
      "pagination": {
          "total": 315,
          "count": 50,
          "per_page": 50,
          "current_page": 2,
          "total_pages": 7,
          "links": []
      }
  }
}

This endpoint retrieves a list of groups.

By default groups, the user is a member of, are returned, but it can also return non-member groups, the user can join or request to join.

HTTP Request

GET https://example.ziik.io/api/groups/ID/debates

Query Parameters

ParameterTypeDefaultDescription
pageInteger1Page number for pagination.
limitInteger50Number of records to return per page.

Create New Debate

curl -i -X POST "https://example.ziik.io/api/groups/123/debates"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 201 Created with a location header for where to find the new debate

HTTP/1.0 201 Created
Location: https://example.ziik.io/api/debates/1234
{
    "message": "Debate created"
}

This endpoint creates a new comment.

HTTP Request

POST https://example.ziik.io/api/groups/ID/debates

Request Parameters

ParameterTypeRequiredDescription
bodyStringYesDebate body.
fileCountIntegerNoNumber of files that will be uploaded (type 'upload') in total, including subsequent POSTs to /api/debates/ID/files
filesArrayNoFile data for files to accompany the debate. If provided, existing files are cleared. Must be an array of arrays with the following values
- typeStringYesType of file - can be either 'upload', 'youtube' or 'vimeo'.
- nameStringYesFile name.
- dataStringYesIf type is 'upload' this must be the base64 encoded content of the file. Else it must be the Youtube/Vimeo embed URL.

Permissions Required

  • Member of group

Get Group Images

curl -i -X GET "https://example.ziik.io/api/groups/123/images"
  -H "Authorization: Bearer aaaaaa.bbbbbb.cccccc"

The above command returns JSON structured like this:

{
  "hits": [
    {
      "id":"345",
      "name":"avatar.png",
      "mime":"image/png",
      "size":"54314",
      "type":"image",
      "source":"https://example.ziik.io/api/file/default_images/avatar.png",
      "versions":{
          "listing":"https://example.ziik.io/api/file/styles/article_listing/private/default_images/avatar.png",
          "detail":"https://example.ziik.io/api/file/styles/article_desktop/private/default_images/avatar.png",
          "thumbnail":"https://example.ziik.io/api/file/styles/media_thumbnail/private/default_images/avatar.png"
      }
    },
    {
      "id":"345",
      "name":"avatar.png",
      "mime":"image/png",
      "size":"54314",
      "type":"image",
      "source":"https://example.ziik.io/api/file/default_images/avatar.png",
      "versions":{
          "listing":"https://example.ziik.io/api/file/styles/article_listing/private/default_images/avatar.png",
          "detail":"https://example.ziik.io/api/file/styles/article_desktop/private/default_images/avatar.png",
          "thumbnail":"https://example.ziik.io/api/file/styles/media_thumbnail/private/default_images/avatar.png"
      }
    }
  ],
  "meta": {
      "pagination": {
          "total": 315,
          "count": 50,
          "per_page": 50,
          "current_page": 2,
          "total_pages": 7,
          "links": []
      }
  }
}

This endpoints returns a list of files of type image within a given group

HTTP Request

GET https://example.ziik.io/api/groups/ID/images

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the group

Query Parameters

ParameterTypeDefaultDescription
pageInteger1Page number for pagination.
limitInteger50Number of records to return per page.

Get Group Videos

curl -i -X GET "https://example.ziik.io/api/groups/123/videos"
  -H "Authorization: Bearer aaaaaa.bbbbbb.cccccc"

The above command returns JSON structured like this:

{
  "hits": [
    {
      "id":"345",
      "name":"testvideo.mp4",
      "mime":"video/mp4",
      "size":"54314",
      "type":"video",
      "source":"https://example.ziik.io/api/file/groups/files/testvideo.mp4",
      "stream":"https://example.ziik.io/api/file/groups/files/testvideo.mp4"
    },
    {
      "id":"345",
      "name":"testvideo2.mp4",
      "mime":"video/mp4",
      "size":"54314",
      "type":"video",
      "source":"https://example.ziik.io/api/file/groups/files/testvideo2.mp4",
      "stream":"https://example.ziik.io/api/file/groups/files/testvideo2.mp4"
    }
  ],
  "meta": {
      "pagination": {
          "total": 315,
          "count": 50,
          "per_page": 50,
          "current_page": 2,
          "total_pages": 7,
          "links": []
      }
  }
}

This endpoints returns a list of files of type video within a given group. Videos can be both video files and Youtube or Vimeo urls

HTTP Request

GET https://example.ziik.io/api/groups/ID/videos

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the group

Query Parameters

ParameterTypeDefaultDescription
pageInteger1Page number for pagination.
limitInteger50Number of records to return per page.

Get Group Documents

curl -i -X GET "https://example.ziik.io/api/groups/123/documents"
  -H "Authorization: Bearer aaaaaa.bbbbbb.cccccc"

The above command returns JSON structured like this:

{
  "hits": [
    {
      "id":"345",
      "name":"testvideo.xls",
      "mime":"application/excel",
      "size":"54314",
      "type":"document",
      "source":"https://example.ziik.io/api/file/groups/files/testvideo.xls"
    },
    {
      "id":"345",
      "name":"testfile.pdf",
      "mime":"application/pdf",
      "size":"54314",
      "type":"document",
      "source":"https://example.ziik.io/api/file/groups/files/testfile.pdf"
    }
  ],
  "meta": {
      "pagination": {
          "total": 315,
          "count": 50,
          "per_page": 50,
          "current_page": 2,
          "total_pages": 7,
          "links": []
      }
  }
}

This endpoints returns a list of files within a given group that are not either image or video.

HTTP Request

GET https://example.ziik.io/api/groups/ID/documents

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the group

Query Parameters

ParameterTypeDefaultDescription
pageInteger1Page number for pagination.
limitInteger50Number of records to return per page.

Search Users Not In Group

curl -i -X GET "https://example.ziik.io/api/groups/123/users"
  -H "Authorization: Bearer aaaaaa.bbbbbb.cccccc"

The above command returns JSON structured like this:

{
    "hits": [
        {
            "id": 553,
            "name": "Test User",
            "email": "test@example.com",
            "avatar": {
                "id": 387,
                "name": "avatar.png",
                "mime": "image/png",
                "size": 54314,
                "type": "image",
                "source": "https://example.ziik.io/api/file/default_images/avatar.png",
                "versions": {
                    "listing": "https://example.ziik.io/api/file/styles/article_listing/private/default_images/avatar.png?itok=1668nGAk",
                    "detail": "https://example.ziik.io/api/file/styles/article_desktop/private/default_images/avatar.png?itok=d8rftLFt",
                    "thumbnail":"https://example.ziik.io/api/file/styles/media_thumbnail/private/default_images/avatar.png"
                }
            },
            "unit": {
                "id": 104,
                "name": "Country Office Denmark",
                "url": "api/units/104"
            },
            "userType": {
                "id": 115,
                "name": "Country Manager",
                "url": "api/user_types/115"
            },
            "title": null,
            "phone": null,
            "ask_about": null,
            "url": "api/users/553",
            "permissions": {
                "edit": true,
                "delete": true
            }
        },
        {
            "id": 193,
            "name": "Test User 2",
            "email": "test2@example.com",
            "avatar": {
                "id": 551,
                "name": "prolbillede_2.jpg",
                "mime": "image/jpeg",
                "size": 19275,
                "type": "image",
                "source": "https://example.ziik.io/api/file/users/prolbillede_2.jpg",
                "versions": {
                    "listing": "https://example.ziik.io/api/file/styles/article_listing/private/users/prolbillede_2.jpg?itok=PLkSxJBi",
                    "detail": "https://example.ziik.io/api/file/styles/article_desktop/private/users/prolbillede_2.jpg?itok=zrTABSMF",
                    "thumbnail":"https://example.ziik.io/api/file/styles/media_thumbnail/private/default_images/avatar.png"
                }
            },
            "unit": {
                "id": 102,
                "name": "International HQ",
                "url": "api/units/102"
            },
            "userType": {
                "id": 103,
                "name": "System Administrator",
                "url": "api/user_types/103"
            },
            "title": "CEO",
            "phone": "+4500000000",
            "ask_about": null,
            "url": "api/users/193",
            "permissions": {
                "edit": true,
                "delete": false
            }
        }
    ]
}

This endpoints returns a list of users NOT in a group that matches a search string.

HTTP Request

GET https://example.ziik.io/api/groups/ID/users

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the group

Query Parameters

ParameterTypeRequiredDescription
qStringYesSearch string for user's name