Skip to content

Teams API (v5)

Teams

v6 (latest) - v5

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
{
  "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

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