How Can I Programmatically Create Or Update Teams?

How Can I Programmatically Create Or Update Teams?


This article explains how you can create or update teams using simple API calls. To add or remove users from teams, see this article. To add or remove custom variables from teams, see this article. 

Create Or Update Teams
To create or update teams, follow these 2 steps:
  • Step 1 - Get Your API key
  • Step 2 - Submit Team Changes

Step 1 - Get Your API Key
To obtain your API key:
  • Login to your workspace
  • On the left pane, click on "Account > My Profile"
  • Click on the "Security" tab (if needed)
  • Copy the API key
  • Note: you must be full admin in your workspace

Step 2 - Submit Team Changes
To add or update a team:
       "name": "West",
       "description": "West Coast",                                                        // optional
       "managerId": "b0c14677-5551-4641-855e-99ba49eb5156",      // optional
       "parentTeamId": "036cf924-45f4-4d81-b9d9-5a22fa455018",    // optional
       "managerCanViewResults": true,                                                 // optional
       "managerCanViewCredits": true,                                                 // optional
       "membersCanViewCredits": false,                                               // optional
   }

Sample Code
The following samples show how to make calls (using C#):

// Create a team
expando = new ExpandoObject();
expando.name = name;
expando.description = "description 1";
expando.managerId = "b0c14677-5551-4641-855e-99ba49eb5156";
expando.parentTeamId = "036cf924-45f4-4d81-b9d9-5a22fa455018";
expando.managerCanViewResults = true;
expando.managerCanViewCredits = true;
expando.membersCanViewCredits = false;
string json = JsonConvert.SerializeObject(expando);
string url = iisExpress.AppWebAppUrl + "/Api/SetTeam";
WebClient webClient = new WebClient();
webClient.Headers.Add("X-ApiKey", apiKey);
string result = webClient.UploadString(url, json);

Updating Teams
Step 2 is often used to create (add) teams. However, you can also use step 2 to update existing teams (i.e. teams you previously added via the web interface or via API calls). To update teams, make sure the name matches the team you want to update. That's it - the system will handle your action as a create or update depending on whether it can find a team with a matching name within your workspace.

Getting Teams
To retrieve teams and their members, you can make OData API calls.

To visually explore the API:
  • Login to your workspace
  • On the left pane, click on "Settings > Connections > OData API"
  • Alternatively, you can connect using a BI tool such as Microsoft Power BI to view entities

Clearing Parent Teams Or Managers
To clear parent teams or managers, make sure to specify properties "managerId" / "parentTeamId" in your payload. If they are not within your payload, no changes will occur. You can either set them to null, or to "00000000-0000-0000-0000-000000000000" to clear them.

    • Related Articles

    • How Can I Programmatically Create Or Update Users?

      This article explains how you can create or update users using simple API calls. To add or remove users from teams, see this article. To add or remove custom variables from users, see this article. Create Or Update Users To create or update users, ...

    • How Can I Programmatically Add Or Remove Users From Teams?

      This article explains how you can add or remove users from teams using simple API calls. To do this, you will either create or delete team member records which represent membership of users within teams. Create Or Delete Team Members To add or remove ...

    • How Can I Programmatically Retrieve Or Set Custom Variables

      This article explains how you can retrieve or set custom variables on users, teams, plans within your workspace using simple API calls. Retrieve Custom Variables To retrieve custom variables, follow these 2 steps: Step 1 - Get Your API key Step 2 - ...

    • Commission Software Checklist

      Don't be fooled by slick demos. Can other providers really handle your data and your commission structure? Ask the right questions. Choosing Commission Software At Sales Cookie, we want you to make an informed decision. The reality is that many of ...

    • How Does The Payroll Gateway Work?

      You can always retrieve commission-related data using the OData API (programmatically - or using BI tools such as Excel, Tableau, Microsoft Power BI). This lets you retrieve transactions, rewards, users, teams, plans, calculations, etc. However, ...