Skip to content

Teams API

Teams

v6 (latest) - v5

A team object contains the following attributes.

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

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/v6/orgs/<organization_id>/teams

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at
is_deleted boolean (none) By default returns all teams. If true, returns only deleted teams. If false, returns only active teams.

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/v6/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/v6/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/v6/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/v6/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
{
  "name": "Test team"
}

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

Attribute Required Value
name required Must be a non-empty string

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 name of a team (<team_id>) that belongs to an organization (<organization_id>). You may also restore a deleted team.

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

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

Attribute Required Value
name optional Must be a non-empty string
is_deleted optional Set as false to restore a deleted team. true is not a valid value - use DELETE request to delete a team instead.

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
  • 400 if trying to update is_deleted to true
  • 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

Warning

Deleting a team will set the team and all its memberships as deleted. It will unshare the team from your partners!

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

DELETE https://service.giosg.com/api/v6/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 Description
team_id UUID ID of the team to which this member belongs.
team object The Team to which this member belongs, with attributes id, name, display_name, and organization_id.
user_id UUID ID of the member user.
user object The member user resource, with attributes id, first_name, last_name, full_name and organization_id.
created_by_user_id UUID The ID of the user who created the membership.
created_by_user object The user who created the membership.
created_at datetime When the membership resource was created.
is_deleted boolean Whether the membership has been deleted.
deleted_at datetime When the membership has been deleted. null if not deleted.

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 memberships

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

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

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at
is_deleted boolean (none) By default returns all memberships. If true, returns only deleted memberships. If false, returns only active 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
{
  "user_id": "ab98bd97-872c-11e7-921d-60f81dcf1946"
}

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

Attribute Required Value
user_id required UUID of the member user

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

Restore deleted member

You may restore a deleted membership to a team.

PUT https://service.giosg.com/api/v6/orgs/<organization_id>/teams/<team_id>/memberships/<user_id>

PATCH https://service.giosg.com/api/v6/orgs/<organization_id>/teams/<team_id>/memberships/<user_id>

Attribute Required Value
is_deleted required Set as false to restore a deleted membership. true is not a valid value - use DELETE request to delete a membership instead.

This endpoint returns:

  • 200 if the membership was successfully restored
  • 400 if required attributes are missing from the request
  • 400 if the request payload is in wrong format
  • 400 if trying to update is_deleted to true
  • 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/v6/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/v6/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/v6/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/v6/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