How Can I Programmatically Create Or Update Users?

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, follow these 2 steps:
  • Step 1 - Get Your API key
  • Step 2 - Submit User 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 User Changes
To add or update a user:
       "emailAddress": "test@example.com",
       "role": "FullAdmin",             // ex: "LimitedAdmin", "Participant", "Deactivated"
       "firstName": "Bob",            // optional
       "lastName": "Smith",          // optional
       "tags": "AE|SouthEast",     // optional
       "aliases": "ID-123",            // optional
   }

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

// Create a user
dynamic expando = new ExpandoObject();
expando.emailAddress = "test@example.com";
expando.role = "FullAdmin";
expando.firstName = "Bob";
expando.lastName = "Smith";
expando.tags = "AE|SouthEast";
expando.aliases = "ID-123";
string json = JsonConvert.SerializeObject(expando);
WebClient webClient = new WebClient();
webClient.Headers.Add("X-ApiKey", apiKey);
string result = webClient.UploadString(url, json);

Updating Users
Step 2 is often used to create (add) users. However, you can also use step 2 to update existing users (i.e. users you previously added via the web interface or via API calls). To update users, make sure the email address matches the user 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 user with a matching email address within your workspace. On update, specified aliases and tags are additive. In other words, your specified aliases and tags are added to existing ones.

Getting Users
To retrieve users and their workspace roles, 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

Why Set Aliases?
Aliases on users make it easy to credit them for transactions. Refer to this article. You can use "|" as a separator to specify multiple aliases.

Why Set Tags?
Tags on users allow you to classify them, or to identify them as plan targets. Refer to this article. You can use "|" as a separator to specify multiple tags.

Deactivating Users
You cannot delete users, but you can deactivate them. Simply set the role to "Deactivated".
Valid role values are:
  • "FullAdmin"
  • "LimitedAdmin"
  • "Participant"
  • "Deactivated"