Skip to content

Sharing API

Once you have become partners, you may share resources to your partner organization. Resources that are shared by you or are shared to you are represented by shares. Currently there are the following types of shares:

  • Room shares
  • App shares
  • Team shares

Additionally, each type of share are represented as either outgoing or incoming share, depending on whether you are the sharing or the receiving party.

Room shares

A room share represents a room instance share between two organization. A room share resource has the following attributes:

Attribute Type Editable Description
id UUID read-only Unique identifier for the share resource.
organization_id UUID required ID of the partner organization to whom the room resource is shared. Must be an existing partner. Cannot be changed after creation.
organization object read-only The organization object to whom the room resource was shared.
room_organization_id UUID read-only ID of the organization who shared the room resource.
room_organization object read-only The organization object who shared the room resource.
room_id UUID read-only ID of the room resource.
room object read-only The room object.
created_at datetime read-only When the room resource was shared.
updated_at datetime read-only When was the last time the sharing was updated. This cannot change currently after creation.
created_by_user_id UUID read-only ID of the user who shared the room resource.
created_by_user object read-only The user who shared the room resource, with all of the available attributes.
updated_by_user_id UUID read-only ID of the last user which updated this room resource.
updated_by_user object read-only Last user which updated this room resource. This cannot change currently after creation.

Currently sharing a room between organization can be only done by giosg's support. If you wish to share a room to your partner, please contact support@giosg.com.

List outgoing room shares of an organization

Example request for listing an organization's outgoing room shares

1
GET https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/outgoing_room_shares

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
{
  "next": "https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/outgoing_room_shares?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
      "organization": {
        "id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
        "name": "Company X"
      },
      "room_organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
      "room_organization": {
        "id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "name": "giosg.com"
      },
      "created_at": "2015-02-13T11:31:36.042",
      "updated_at": "2015-02-13T12:38:36.431",
      "created_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "created_by_user": {
        "id": "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Robotti Ruttunen",
        "first_name": "Robotti",
        "last_name": "Ruttunen",
        "organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "avatar_id": null,
        "avatar": null,
        "is_bot": false
      },
      "updated_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "updated_by_user": {
        "id": "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Robotti Ruttunen",
        "first_name": "Robotti",
        "last_name": "Ruttunen",
        "organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "avatar_id": null,
        "avatar": null,
        "is_bot": false
      },
      "room_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
      "room": {
        "id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "display_name": "Shared room",
        "domain": "giosg.com",
        "organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "organization": {
          "id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
          "name": "giosg.com"
        }
      }
    }
  ]
}

You can list outgoing room shares for an organization:

GET /api/v5/orgs/<organization_id>/outgoing_room_shares

This API endpoint returns a paginated collection. They are sorted by the creation time of the room share, in ascending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have settings or reports permission

Retrieve details of room share

You can retrieve details of organization's room share:

GET /api/v5/orgs/<organization_id>/outgoing_room_shares/<room_share_id>

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have settings or reports permission
  • 404 if the room share with given room_share_id was not found

List incoming room shares

You can list incoming room shares for an organization:

GET /api/v5/orgs/<organization_id>/incoming_room_shares

This API endpoint returns a paginated collection. They are sorted by the creation time of the room share, in ascending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have settings or reports permission

Retrieve details of incoming room share

You can retrieve details of organization incoming room share:

GET /api/v5/orgs/<organization_id>/incoming_room_shares/<room_share_id>

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have settings or reports permission
  • 404 if the room share with given room_share_id was not found

App shares

An app share represents a giosg app instance share between two organization. An app share resource has the following attributes:

Attribute Type Editable Description
id UUID read-only Unique identifier for the share resource.
organization_id UUID required ID of the partner organization to whom the app resource is shared. Must be an existing partner. Cannot be changed after creation.
organization object read-only The organization object to whom the app resource was shared.
app_organization_id UUID read-only ID of the organization who shared the app resource.
app_organization object read-only The organization object who shared the app resource.
app_id UUID read-only ID of the app (owned app) resource.
app object read-only The app (owned app) object.
created_at datetime read-only When the app resource was shared.
updated_at datetime read-only When was the last time the sharing was updated. This cannot change currently after creation.
created_by_user_id UUID read-only ID of the user who shared the app resource.
created_by_user object read-only The user who shared the app resource, with all of the available attributes.
updated_by_user_id UUID read-only ID of the last user which updated this app resource.
updated_by_user object read-only Last user which updated this app resource. This cannot change currently after creation.

Note! Organization can share apps only if it has "App provider" feature(s).

List outgoing app shares of an owned app

Example request for listing an owned app's shares

1
GET https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/owned_apps/7f9e9580-095b-42c7-838c-c04e667b26f7/outgoing_app_shares

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
{
  "next": "https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/owned_apps/7f9e9580-095b-42c7-838c-c04e667b26f7/outgoing_app_shares?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
      "organization": {
        "id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
        "name": "Company X"
      },
      "app_organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
      "app_organization": {
        "id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "name": "giosg.com"
      },
      "created_at": "2015-02-13T11:31:36.042",
      "updated_at": "2015-02-13T12:38:36.431",
      "created_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "created_by_user": {
        "id": "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Robotti Ruttunen",
        "first_name": "Robotti",
        "last_name": "Ruttunen",
        "organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "avatar_id": null,
        "avatar": null,
        "is_bot": false
      },
      "updated_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "updated_by_user": {
        "id": "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Robotti Ruttunen",
        "first_name": "Robotti",
        "last_name": "Ruttunen",
        "organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "avatar_id": null,
        "avatar": null,
        "is_bot": false
      },
      "app_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
      "app": {
        "name": "Flappy giosg Balls",
        "description": "My cool application",
        "owned_by_organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "owned_by_organization": {
          "id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
          "name": "giosg.com"
        },
        "created_at": "2017-01-01T12:00:00.123Z",
        "updated_at": "2017-01-02T15:00:00.123Z"
      }
    }
  ]
}

You can list outgoing app shares for an organization's owned app:

GET /api/v5/orgs/<organization_id>/owned_apps/<app_id>/outgoing_app_shares

This API endpoint returns a paginated collection. They are sorted by the creation time of the app share, in ascending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have settings permission
  • 404 if no owned app is found with the given ID

Sharing an owned app to partner organization

Example request for sharing an owned app to partner organization

1
POST https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/owned_apps/7f9e9580-095b-42c7-838c-c04e667b26f7/outgoing_app_shares

Example request payload

1
2
3
{
  "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3"
}

You can share an owned app to a partner organization by:

POST /api/v5/orgs/<organization_id>/owned_apps/<app_id>/outgoing_app_shares

This endpoint returns:

  • 201 if the request was successful
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 400 if there is no partnership between your organization and the given organization_id
  • 401 if you are not authenticated
  • 402 if the organization does not have "App provider" feature(s)
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have settings permission
  • 404 if no owned app is found with the given ID

Retrieve details of owned app's share

You can retrieve details of organization's owned app's share:

GET /api/v5/orgs/<organization_id>/owned_apps/<app_id>/outgoing_app_shares/<target_organization_id>

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have settings permission
  • 404 if the owned app was not found
  • 404 if the app share to target_organization_id was not found

Unshare owned app's share from partner organization

Example request for unsharing an owned app

1
DELETE https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/owned_apps/7f9e9580-095b-42c7-838c-c04e667b26f7/outgoing_app_shares/e68220e1-9072-11e6-bf95-f45c89c72de3

You can unshare a brand by:

DELETE /api/v5/orgs/<organization_id>/owned_apps/<app_id>/outgoing_app_shares/<app_id>

Note that this will uninstall the app from the partner organization!

This endpoint returns:

  • 204 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have settings permission
  • 404 if the owned app was not found
  • 404 if the app share to target_organization_id was not found

List incoming app shares

You can list incoming app shares for an organization:

GET /api/v5/orgs/<organization_id>/incoming_app_shares

This API endpoint returns a paginated collection. They are sorted by the creation time of the app share, in ascending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have settings permission

Retrieve details of incoming app share

You can retrieve details of organization incoming app share:

GET /api/v5/orgs/<organization_id>/incoming_app_shares/<app_id>

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have settings permission
  • 404 if the app share with given app_id was not found

Team shares

A team share represents a team instance share between two organization. A team share resource has the following attributes:

Attribute Type Editable Description
id UUID read-only Unique identifier for the share resource.
organization_id UUID required ID of the partner organization to whom the team resource is shared. Must be an existing partner. Cannot be changed after creation.
organization object read-only The organization object to whom the team resource was shared.
team_organization_id UUID read-only ID of the organization who shared the team resource.
team_organization object read-only The organization object who shared the team resource.
team_id UUID read-only ID of the Team resource.
team object read-only The Team object.
created_at datetime read-only When the team resource was shared.
updated_at datetime read-only When was the last time the sharing was updated. This cannot change currently after creation.
created_by_user_id UUID read-only ID of the user who shared the team resource.
created_by_user object read-only The user who shared the team resource, with all of the available attributes.
updated_by_user_id UUID read-only ID of the last user which updated this team resource.
updated_by_user object read-only Last user which updated this team resource. This cannot change currently after creation.

List outgoing team shares of an organization

Example request for listing an organization's outgoing team shares

1
GET https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/outgoing_team_shares

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
{
  "next": "https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/outgoing_team_shares?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
      "organization": {
        "id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
        "name": "Company X"
      },
      "team_organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
      "team_organization": {
        "id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "name": "giosg.com"
      },
      "created_at": "2015-02-13T11:31:36.042",
      "updated_at": "2015-02-13T12:38:36.431",
      "created_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "created_by_user": {
        "id": "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Robotti Ruttunen",
        "first_name": "Robotti",
        "last_name": "Ruttunen",
        "organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "avatar_id": null,
        "avatar": null,
        "is_bot": false
      },
      "updated_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "updated_by_user": {
        "id": "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Robotti Ruttunen",
        "first_name": "Robotti",
        "last_name": "Ruttunen",
        "organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "avatar_id": null,
        "avatar": null,
        "is_bot": false
      },
      "team_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
      "team": {
        "id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "name": "Shared team",
        "display_name": null,
        "organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "organization": {
          "id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
          "name": "giosg.com"
        }
      }
    }
  ]
}

You can list outgoing team shares for an organization:

GET /api/v5/orgs/<organization_id>/outgoing_team_shares

This API endpoint returns a paginated collection. They are sorted by the creation time of the team share, in ascending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have users permission

Retrieve details of team share

You can retrieve details of organization's team share:

GET /api/v5/orgs/<organization_id>/outgoing_team_shares/<team_share_id>

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have users permission
  • 404 if the team share with given team_share_id was not found

List incoming team shares

Example request for listing an organization's incoming team shares

1
GET https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/incoming_team_shares

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
{
  "next": "https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/incoming_team_shares?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
      "organization": {
        "id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "name": "giosg.com"
      },
      "team_organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
      "team_organization": {
        "id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
        "name": "Company X"
      },
      "created_at": "2015-02-13T11:31:36.042",
      "updated_at": "2015-02-13T12:38:36.431",
      "created_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "created_by_user": {
        "id": "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Robotti Ruttunen",
        "first_name": "Robotti",
        "last_name": "Ruttunen",
        "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
        "avatar_id": null,
        "avatar": null,
        "is_bot": false
      },
      "updated_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "updated_by_user": {
        "id": "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Robotti Ruttunen",
        "first_name": "Robotti",
        "last_name": "Ruttunen",
        "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
        "avatar_id": null,
        "avatar": null,
        "is_bot": false
      },
      "team_id": "7f9e9581-095b-42c7-838c-c04e667b26f7",
      "team": {
        "id": "7f9e9581-095b-42c7-838c-c04e667b26f7",
        "display_name": "Display name of Company X's team",
        "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
        "organization": {
          "id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
          "name": "Company X"
        },
        "is_online": false,
        "is_present": false
      }
    }
  ]
}

You can list incoming team shares for an organization:

GET /api/v5/orgs/<organization_id>/incoming_team_shares

This API endpoint returns a paginated collection. They are sorted by the creation time of the team share, in ascending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization

Retrieve details of incoming team share

You can retrieve details of organization incoming team share:

GET /api/v5/orgs/<organization_id>/incoming_team_shares/<team_share_id>

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 404 if the team share with given team_share_id was not found

Create new outgoing team share

You can create a new outgoing team share:

POST /api/v5/orgs/<organization_id>/outgoing_team_shares

This endpoint returns:

  • 201 if existing team share was found
  • 201 if the request was successful
  • 400 if the organizations are not connected
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have users permission

Example payload

1
2
3
4
{
  "organization_id": "7f9e9581-095b-42c7-838c-c04e667b26f7",
  "team_id": "7f9e9580-095b-42c7-838c-c04e667b26f7"
}

Delete outgoing team share

You can delete an outgoing team share:

DELETE /api/v5/orgs/<organization_id>/outgoing_team_shares/<team_share_id>

This endpoint returns:

  • 204 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
  • 403 if you do not have users permission
  • 404 if the team share with given team_share_id was not found