Teams Management Service
Developers can use the Teams API for team creation, retrieval, updates, and deactivation. The API makes it easy to customize team properties such as operational hours and types and allows managing team statuses. The API includes multiple endpoints and operations that simplify team management and can integrate seamlessly with applications.
The Teams API offers the following operations:
- CreateTeam: Create a new team by providing the necessary details such as team name, team code, owner, operating hours, and team type.
- UpdateTeam: Modify the properties of an existing team, including the team name, owner, operating hours, and operating days.
- ListTeams: Retrieve a list of all teams, with options for pagination, sorting, and filtering based on specific criteria.
- UpdateTeamState: Perform state transitions to change the state of a team, such as activating or deactivating it.
Use the Teams API to create and manage teams.
To create a team, call the CreateTeam endpoint and provide the required teamCode and teamName in the request body. Additionally, you can provide the team owner ID, team type, start time, operating hours, and operating days if necessary. If you require a callback URL or metadata, you can also specify those.
Parameter | Description |
|---|---|
teamCode* | The unique id for the team |
teamName* | The team name
|
teamOwnerId | The unique id for the owner of the team. |
teamType | Defines the team type. Acceptable values:
|
startTime | The time at which the team starts operations on a given day. |
operatingHours | The hours for which the team is operational from the Start Time. |
operatingDays | The days of the week on which the team is operational. List [ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" ] |
callback | Callback configuration |
callback.url* | Callback URL |
callback.metaData | Callback metadata |
Note: Parameters marked with an asterisk (*) are required.
Example request
Example response
If successful, the response will include a data object containing the team id. In the example, the id is c5d4b3a2-1f9e-4d8c-b7a6-9c8d7e6f5a4b.
Once a team is created using the Teams API, developers can add users and facilities using the User and Facility APIs. This is done by associating them with the desired team through the appropriate API calls and providing the necessary information, such as the team ID and the details of the users or facilities. For more information on how to use the User and Facility APIs, please refer to their respective documentation.
Call the ListTeams endpoint to retrieve teams based on various query parameters. The API supports pagination, allowing you to specify the number of teams per page and the page number. You can also filter teams using the query parameter to sort the results based on specific criteria.
Parameter | Description |
|---|---|
size | Number of items in a page.
|
page | Page number to return (starting from 1)
|
select_ | Specifies list of attributes to be included in response (id is always included in response). If not specified, all attributes are included in response. |
query | Query criteria. Refer to the API reference for the supported query syntax. |
sortBy | The sorting order.
|
sortKey | The key to be used for sorting data. |
additionalInfo | Toggle fetching of additional info.
|
memberCount | Toggle fetching the number of members of a designation in a team. enum: [true, false] |
Example request
Example response
The example response includes teams is array containing the team objects. Each team object includes various attributes such as ID, state, name, owner, properties, creation and update timestamps, and associated user information.
The GetTeam endpoint allows you to retrieve a specific team using its unique identifier or external reference.
Parameter | Description |
|---|---|
teamId | The unique id of the team. |
Example request
Example response
The response includes various attributes such as ID, state, participantType, owner, properties, and creation/update timestamps.
Call the UpdateTeam endpoint to modify the details of an existing team with the updated team information in the request body. You can update parameters such as the name, owner, start time, operating hours, and operating days. The teamId parameter in the URL path represents the ID of the team you want to update.
Parameter | Description |
|---|---|
teamName | The team name. |
teamOwnerId | The unique id for the owner of the team. |
teamType | Defines the team type. Acceptable values:
|
startTime | The time at which the team starts operations on a given day. |
operatingHours | The hours for which the team is operational from the Start Time. |
operatingDays | The days of the week on which the team is operational. List [ "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" ] |
callback | Callback configuration |
callback.url* | Callback URL |
callback.metaData | Callback metadata |
Example request
The following request updates the following parameters:
- teamName
- startTime
- opaerationHours
- operatingDays
Example response
If the team is updated successfully, the API will respond with a 202 Accepted status code and a success response object similar to the CreateTeam response.
Call the UpdateTeamState endpoint to update the state of a team with the desired state transition details in the request body. You can change the team's state, such as activating or deactivating the team. The teamId parameter in the URL path represents the ID of the team whose state you want to update.
The following table lists the allowed state transitions:
From State | To State |
|---|---|
onboarding:onboarding | active:active |
active:active | inactive:inactiveactive:deboardactive:pause |
active:pause | active:active |
active:deboard | active:activeinactive:inactive |
inactive:inactive | active:active |
inactive:terminal | - |
Parameter | Description |
|---|---|
toState* | Destination state with the format state:substate. Example: active:available |
reasonCode | Reason code for transition. Example: R-123 |
data | Additional data if available. |
callback | Callback configuration |
callback.url* | Callback URL.: |
callback.metaData | Callback metadata. |
Note: Parameters marked with an asterisk (*) are required.
Example request
The following request set's the team to an inactive state.
Example response
If the team state is updated successfully, the API will respond with a 202 Accepted status code and a success response object similar to the CreateTeam response.
Call the GetTeamState endpoint to retrieve the current state of a specific team. The teamId parameter in the URL path represents the ID of the team whose state you want to retrieve.
Example request
Example response
If the request is successful, the API will respond with a 200 OK status code and a JSON object containing the team's state information in the following format:
The response includes the current state of the team and its ID.
The FilterTeams endpoint allows you to retrieve aggregate counts of teams based on specified filters. By calling FilterTeam with the appropriate query parameters, you can retrieve the count of teams that match the specified criteria.
Parameter | Description |
|---|---|
aggregateQuery* | Aggregate query for retrieving count of teams based on specified criteria. Example: [{"name":"state_count","field":"state.keyword","aggregation":"terms"}] |
query* | Query criteria for filtering teams. The arr field is an array of query conditions nd the op field specifies the logical operator to combine the conditions (e.g., "and" for all conditions to be true) Example: {"arr":[{"term":{"properties.teamType.keyword":"Operations"}}],"op":"and"} |
Example request
Example response
If the request is successful, the API will respond with a 200 OK status code and a JSON object containing the aggregate count results in the following format:
The response includes the aggregate count results based on the specified filters. In this example, it shows the count of teams in different states (active and inactive) for teams with the "Operations" team type.