Teams Management Service
The Teams API enables developers to manage team operations including creation, retrieval, updates, and deactivation. The API offers operations for team creation, retrieval, updates, and deactivation. It provides functionality to customize team properties such as operational hours and types, and allows managing team statuses.
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.
Teams can transition between the states. 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 | no further transitions |
Note: For more information on how the transition these states, refer to the Update State Team section.
Use the Teams API to create and manage teams. The implementation include the following process:
- Create a team using the CreateTeam endpoint with required parameters (teamCode and teamName)
- After team creation, you can:
- Add users and facilities using respective APIs
- Update team properties
- Manage team states (activate/deactivate)
- Retrieve team information
- Manage team properties and states as needed
To create a team, call the CreateTeam endpoint.
Use the below cURL command to create a team.
Body Parameters
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.
Sample Request
Sample Response
If successful, the response will include a data object containing the team id. In the example, the id c5d4b3a2-1f9e-4d8c-b7a6-9c8d7e6f5a4b,which will always contain prefix 'teams'.
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. In your API calls, include:
- The team ID (from the team you created)
- The details of users or facilities you want to add
For more information on how to use the User and Facility APIs, refer to their respective documentation.
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.
Query parameters for listing teams
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. For example -properties.homeFacilityId . |
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] |
Sample Request
Sample 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.
Path parameters
Parameter | Description |
|---|---|
teamId | The unique id of the team. |
Sample Request
Sample Response
The response includes various attributes such as ID, state, participantType, owner, properties, and creation/update timestamps.
The UpdateTeam endpoint allows 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.
Note: uniqueCode is non editable.
Body parameters
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 |
Sample Request
The following request updates the following parameters:
- teamName
- startTime
- opaerationHours
- operatingDays
Sample 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.
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.
State transitions
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 | - |
Sample Request
The following request set's the team to an inactive state.
Sample 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.
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.
Sample Request
Sample 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.
Query Parameters
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"} |
Sample Request
Sample 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.