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
1 2 3 |
|
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
1 2 3 |
|
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