Teams API (v5)¶

Teams¶

Warning

This API version is deprecated.

A team object contains the following attributes.

Attribute	Type	Editable	Description
`id`	UUID	read-only	The unique identifier of this team
`organization_id`	UUID	read-only	ID of the organization who owns this team.
`organization`	object	read-only	The organization who owns this team.
`name`	string	required	Name of the team. Must be a non-empty string.
`display_name`	string	read-only	Display name of the team. When a team is shared, this name is shown for the receiving organization.
`member_count`	integer	read-only	Number of members (team membership(s)) in this team. Available only to your own organization.
`present_member_count`	integer	read-only	Number of present both members (team membership(s)) in this team. Available only to your own organization.
`is_online`	boolean	read-only	Whether the team is currently online, i.e. any user member from the team is online. See users for more information.
`is_present`	boolean	read-only	Whether the team is currently present, i.e. any user member from the team is present. See users for more information.
`created_by_user_id`	UUID	read-only	The ID of the user who created the team.
`created_by_user`	object	read-only	The user who created the team.
`updated_by_user_id`	UUID	read-only	The ID of the user who updated the team.
`updated_by_user`	object	read-only	The user who updated the team.
`created_at`	datetime	read-only	When the team resource was created
`updated_at`	datetime	read-only	When the team resource was updated last time
`group_chat_id`	UUID	read-only	Chat session id of the team's fixed group chat
`is_connected_to_room`	boolean	read-only	Whether the team is connected to room

Get a collection of organization's teams¶

Return a paginated collection of all the Team resources of an organization (<organization_id>).

GET https://service.giosg.com/api/v5/orgs/<organization_id>/teams

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 organization's team details¶

Get a single team object (<team_id>) of an organization (<organization_id>). This may be a team shared to the organization.

GET https://service.giosg.com/api/v5/orgs/<organization_id>/teams/<team_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

Get a collection of user's teams¶

Return a paginated collection of all the Team resources of a user (<user_id>).

GET https://service.giosg.com/api/v5/users/<user_id>/teams

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 user

Get a collection of organization's user teams¶

Return a paginated collection of all the Team resources of an organization's (<organization_id>) user (<user_id). This means teams to which the user belongs to.

GET https://service.giosg.com/api/v5/orgs/<organization_id>/users/<user_id>/teams

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
404 if user was not found

Retrieve user's team details¶

Get a single team object (<team_id>) of a user (<user_id>).

GET https://service.giosg.com/api/v5/users/<user_id>/teams/<team_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 user
404 if team was not found

Create a team¶

Create a team for an organization (<organization_id>)

Example request payload

{
  "name": "Test team"
}

POST https://service.giosg.com/api/v5/orgs/<organization_id>/teams

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
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 user was not found

Update a team¶

You may update the editable attributes of a team (<team_id>) that belongs to an organization (<organization_id>). You can make either a PATCH request (update a subset of attributes) or POST request (update all the attributes).

PUT https://service.giosg.com/api/v5/orgs/<organization_id>/teams/<team_id>

PATCH https://service.giosg.com/api/v5/orgs/<organization_id>/teams/<team_id>

This endpoint returns:

200 if the request was successful
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
404 if team was not found

Delete a team¶

You may delete one of your own teams by making a DELETE request.

DELETE https://service.giosg.com/api/v5/orgs/<organization_id>/teams/<team_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 team was not found

Team memberships¶

A team membership represents a user belonging to a specific team. Team memberships are only visible for teams of your own organization. A team membership resource has the following attributes.

Attribute	Type	Editable	Description
`team_id`	UUID	read-only	ID of the team to which this member belongs.
`team`	object	read-only	The Team to which this member belongs, with attributes `id`, `name`, `display_name`, and `organization_id`.
`user_id`	UUID	required	ID of the member user.
`user`	object	read-only	The member user resource, with attributes `id`, `first_name`, `last_name`, `full_name` and `organization_id`.
`created_by_user_id`	UUID	read-only	The ID of the user who created the membership.
`created_by_user`	object	read-only	The user who created the membership.
`created_at`	datetime	read-only	When the membership resource was created.

Team memberships are readable by any member of the same organization. However, they can be created or deleted only by organization users with users permission. Otherwise, the endpoints will return a 403 Forbidden response.

Get a collection of team members¶

Return a paginated collection of all the team membership resources for a specific Team.

GET https://service.giosg.com/api/v5/orgs/<organization_id>/teams/<team_id>/memberships

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 team was not found

Add a member to a team¶

You may add a user of your own organization to one of your teams by creating a team membership object.

Example request payload

{
  "user_id": "ab98bd97-872c-11e7-921d-60f81dcf1946"
}

POST https://service.giosg.com/api/v5/orgs/<organization_id>/teams/<team_id>/memberships

This endpoint returns:

200 if the user was already member of team
201 if user was added to the team
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
404 if team was not found

Remove a member from a team¶

You may remove a user from a team by deleting her membership.

DELETE https://service.giosg.com/api/v5/orgs/<organization_id>/teams/<team_id>/memberships/<user_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 team was not found
404 if user was not found

Retrieve team membership details¶

You may get the a user membership resource in a team:

GET https://service.giosg.com/api/v5/orgs/<organization_id>/teams/<team_id>/memberships/<user_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 team was not found
404 if user was not found

Team users¶

A team user represents a user belonging to a specific team. Team users are only visible for teams of your own organization. Team users are readable by any member of the same organization.

Get a collection of team users¶

Return a paginated collection of all the team user resources of an organization.

GET https://service.giosg.com/api/v5/orgs/<organization_id>/teams/<team_id>/users

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
404 if team was not found

Teamless users¶

A teamless user represents a user that is not a member of any team.

Get a collection of teamless users¶

Return a paginated collection of all the teamless user resources of an organization.

GET https://service.giosg.com/api/v5/orgs/<organization_id>/teamless_users

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