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"

    • Related Articles

    • 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, ...

    • 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 Show Users Information About An Upcoming Period?

      Consider the following scenario: You have created a monthly plan and are currently in January You have started a calculation for January and released credits (or rewards) Users can see the January period on their personal incentive dashboard You want ...

    • How Can I Credit Multiple Users For One Transaction?

      You may want to issue commissions to multiple users over the same sales transaction. This may be necessary when multiple users contribute to a sale, or because you have a multi-level commission structure (ex: override commissions). There are two ways ...

    • 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 - ...