NAV

Teams API (v5)

Teams

v6 (latest) v5

A team object contains the following attributes.

Attribute Type Editable Description
id ID read-only The unique identifier of this team
organization_id ID 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 in this team. Available only to your own organization.
present_member_count integer read-only Number of present both members 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 ID 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 ID 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 date/time read-only When the team resource was created
updated_at date/time read-only When the team resource was updated last time
group_chat_id ID 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:

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:

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:

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:

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:

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:

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:

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:

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 ID 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 ID 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 ID 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 date/time 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:

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:

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:

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:

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:

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: