Small Improvements Web API
*This page documents our user provisioning API. Work on a more comprehensive REST services (using OAuth for authentication) has started in July 2013, but it's a long term project. Get in touch if you need specific enhancements.
There are several ways to set up SI users. You can run a manual import, using an Excel worksheet, or you can integrate with BambooHR or Google Apps to synchronize users with them. But for full control you can use our JSON based Web API to create, modify and delete users.
Even if you have never used a JSON-based web API before, it's pretty simple and straightforward. Your script makes a web request to a certain URL, and thereby tells our system what to do (e.g. "import john smith"). You can even perform these steps from within your browser, by simply typing in a URL, and have a look at the results. This makes it great for testing things out.
Common mandatory parameters
Our API is stateless, so you need to provide your credentials during each request. You need to provide an administrator's username and password, and in addition you need to provide your company ID and the company API token each time. You will find company ID and company token on the Global Settings advanced tab.
|companyId||ErU99w8xRZapAnwi6Z0KtQ||You can find your organization's companyId in the company settings screen, in the advanced options. Your companyId never changes.|
|companyToken||ErU99w8xRZapAnwi6Z0KtQ||You can find the token in the company settings screen, in the advanced options. You can change the token! It is like a master password, so you should change it every now and then. Also, you must not spread it. And if you don't intend to perform any imports, you should remove the token altogether, thus disabling the Web API.|
|adminIdemail@example.com||This is the administrator's login email, which is usually the same as his or her email address. The import is done in the name of this administrator, and the administrator needs to have admin rights of course (check in the staff directory)|
|adminPassword||1a45c!94||This is the administrator's actual login password. If you use the URL in your browser, just type it in. If you are using a script, make sure to never embed the password into the script. Your script should require the password as a parameter instead. Oh, and do make sure you're using https so the password does not get sent over the wire in plaintext.|
A sample request
So here's how a proper request would look like:
Try it! It simply lists your company's users. If you mistype a parameter or provide the wrong credentials, you will typically get an error code and a message explaining what went wrong, e.g.
List all users
This lists all users in your organization, and also returns a user count.
|includeLocked||true||Default is false, so by default the query does not list your locked users. Provide includedLocked=true to also see your locked user accounts.|
You can search users by providing a query string. You will get back a sorted list of usernames
|query||joe||The query term is used to look at user's first names and last names.|
You can display any user's details to check their firstname, lastname, status, etc.
|userIdfirstname.lastname@example.org||The user's login email which you want to get additional data for.|
Creates a new user in the database.
|userIdemail@example.com||This is the new user's login email. It has to be an email address, and we strongly recommend you pick an email address from your company.|
|firstName||Alice||First name of the employee to be created|
|lastName||Andersson||Surname of the employee to be created|
|gender||m or f||Most system emails and screens use this data to make proper sentences like "Sarah finished her performance review" or "Don just provided his feedback to your question". You don't want to read "Don just provided her feedback", so try to fill this properly.|
|bossIdfirstname.lastname@example.org||If you are importing an employee whose boss is already in the system, you can pass the id in and the employee gets their boss set instantly. However, when importing from scratch and the boss hasn't been created yet, you can leave this empty, and do a second pass in which you set the boss ID using the setUserBoss API, shown below.|
|role||"Business Analyst" or "CEO" or "Sales Assistant" or "Junior Developer"||The role (or title) is crucial to tell users with similar names apart. For instance, you may have two "John Smith" in your company. When a employee types in their name into a search field, the role is also displayed, enabling you to tell John (the Senior Developer) apart from John Smith (Sales Intern).|
|department||"Development", "Marketing", "Sales"||This data can be useful when looking for someone in the staff directory, since you can quickly filter by department.|
|group||"Web Development Berlin", "Product Management EMEA", "Marketing Team San Francisco", "Stan's Sales Squad"||If your departments are large, then specify a group to make clearer where people work|
|description||"John, the fearless Support Team leader, donut-munching world champion, and aspiring pro golfer"||Not really required, but IF you have the data already, you can put any form of employee self-description in here, or other bio that you gleaned from your previous systems.|
|location||Berlin||Useful to keep different offices apart (people may be in the same group, but at different locations). Again, this is mainly useful to find people in the staff directory|
|userMailemail@example.com||You may provide a different email address than the login email. But this is rarely needed. One usecase we encountered was when a company wanted to set up 20 employees to evaluate the system, but also wanted to set up these employees' managers and reports to make the system feel real. Those additional employees' were not supposed to take part in the evaluation, and therefore should not even receive notification emails from the system. Hence the email address for all those additional users were set to be the same: the mail address of one of the HR administrators.|
|execute||execute, or simulate (default)||Important: If you don't provide the execute parameter, we assume you are just experimenting! So "simulate" is the default value. Only if you provide "execute" for the execute parameter, we will assume you are serious and do want to create the employee account. (Yes, we really mean that you have say "...&execute=execute" in the URL)|
This call takes almost exactly the same parameters as the Create User call, except you cannot modify the boss like this (see below for changing the reporting structure), and the actual user ID cannot be changed anymore. In the following example, the user "Alice" is moved to a different department in a different city, while the name and userID (firstname.lastname@example.org) are unchanged.
Set the manager of a user
As you saw, you can define a manager right away in the Create User API call. However, if you want to change the reporting structure later, or if you can't sort your users so that managers get imported first, you will want to use the API for setting the manager individually.
|userIdemail@example.com||This is the user's login email.|
|bossIdfirstname.lastname@example.org||This is the user's manager's login email.|
Set the status of a user (locking and unlocking)
You can change a user's status to lock or unlock them, without deleting their account and all their associated data like performance reviews or messages. So if an employee leaves the company, you can keep the data, and if you ever rehire them, you just need to re-enable their account. For historic reasons, these status values are 100 (active) and 2 (locked), no other numbers are supported any longer.
|userIdemail@example.com||This is the user's login email.|
|status||100||Use 100 to set the user to active, and 2 to lock a user. Other values are not acceptable.|
This deletes a user and all their content!. You typically don't delete a user just because they left the company, because then all their performance reviews, 360 degree feedback and public messages get deleted as well. Lock those users instead. Only delete accounts that were created accidentally.