Users (API) - Get a list of users, Create & Edit users

The following requests relate to creating, updating and getting users via the Litmos Training Engine API. Note: All requests must be Authenticated.

Get User List

Returns a list of people in your organisation including active and inactive people. By default only the first 100 people are returned. The list can be filtered on first or last name and paged using the optional paging parameters.

To page through users add "&limit=####" to the end of the request.  For example:  

GET https://api.litmos.com/v1.svc/users?apikey=MY-KEY&source=MY-APP&limit=1000

 

AccessLevel:Administrators Only

Request Uri

GET /users

Response

<Users>
   <User>
   <Id>string [max length 50]</Id>
   <UserName> string [max length 255]</UserName>
   <FirstName> string [max length 50]</FirstName>
   <LastName> string [max length 50]</LastName>
   </User>

Get User

Returns a single user profile for the given user Id. AccessLevel:Administrators Only

Request Uri

GET /users/{user-id}

Response

Returns HTTP status code 200 on success and the user profile in the response body

<User>
   <Id>string [max length 50]</Id>
   <UserName>string [max length 255]</UserName>
   <FirstName>string [max length 50]</FirstName>
   <LastName>string [max length 50]</LastName>
   <FullName>string [max length 200]</FullName>
   <Email>string [max length 255]</Email>
   <AccessLevel>string [Trainee or Trainer]</AccessLevel>
   <DisableMessages>true/false</DisableMessages>
   <Active>true/false</Active>
   <Skype>string[max length 100]</Skype>
   <PhoneWork>string[max length 50]</PhoneWork>
   <PhoneMobile>string[max length 50]</PhoneMobile>
   <LastLogin>datetime [iso 8601 format, empty if never logged in]</LastLogin>
   <LoginKey>string [max length 512]</LoginKey>
   <TimeZone>string [see time zone list]</TimeZone>
   <OriginalId>integer</OriginalId>
   <Street1>string[optional, max length 100]</Street1>
   <Street2>string[optional, max length 100]</Street2>
   <City>string[optional, max length 100]</City>
   <State>string[optional, max length 100]</State>
   <PostalCode>string[optional, max length 100]</PostalCode>
   <Country>string[optional, max length 100]</Country>
   <CompanyName>string[optional, max length 100]</CompanyName>
   <JobTitle>string[optional, max length 100]</JobTitle>
   <CustomField1>string[optional, max length 500]</CustomField1>
   <CustomField2>string[optional, max length 500]</CustomField2>
   <CustomField3>string[optional, max length 500]</CustomField3>
<CustomField4>string[optional, max length 500]</CustomField4>
<CustomField5>string[optional, max length 500]</CustomField5>
<CustomField6>string[optional, max length 500]</CustomField6>
<CustomField7>string[optional, max length 500]</CustomField7>
<CustomField8>string[optional, max length 500]</CustomField8>
<CustomField9>string[optional, max length 500]</CustomField9>
<CustomField10>string[optional, max length 500]</CustomField10>
<Culture>string[optional, max length 500]</Culture>
<SalesforceContactId></SalesforceContactId>
<SalesforceAccountId></SalesforceAccountId>
<CreatedDate>2010-01-07T04:37:06.23 [ISO8601]</CreatedDate>
<Points>int</Points>
<Brand>String</Brand>
<ManagerId>string [max length 50]</ManagerId>
<ManagerName>string [max length 200]</ManagerName>
<EnableTextNotification>true/false</EnableTextNotification>
</User>

Get User by Using Username

Returns a single user for the given username. AccessLevel:Administrators Only

Request

GET https://api.litmos.com/v1.svc/users?apikey=YOUR_API_KEY&source=sampleapp&search=rich@litmos.com

Response Body

<Users> 
   <User>  
   <Id>abc12345678</Id>  
   <UserName>rich_demo@litmos.com</UserName>  
   <FirstName>Rich</FirstName>  
   <LastName>Chetwynd</LastName>  
   </User>  
</Users>

Create User

Creates a new user profile in your organisation. By default, no emails will be sent when the user is created. To have an email sent to the user when they are created, the following query string parameter needs to be added to the request: &sendmessage=true

Note: By default all new users that you create will be prompted to change their password the first time they login. If you are using the single sign-on approach then this may not be desirable. To stop this from happening you need to set the SkipFirstLogin field to true. By default it is assumed that a username will be a valid email address. If you want to use a non-email address as username you must also set the IsCustomUsername property to true. AccessLevel:Administrators Only

Request Uri

POST /users

Request Body

Full  list of fields for a PUT or POST request:

<User>
   <Id>[ignored]</Id>
   <UserName>string [max length 255]</UserName>
   <FirstName>string [max length 50]</FirstName>
   <LastName>string [max length 50]</LastName>
   <FullName>[ignored]</FullName>
   <Email>string [optional, max length 255]</Email>
   <AccessLevel>[Administrator/Learner/Team_Leader defaults to Learner]</AccessLevel>
   <DisableMessages>true/false</DisableMessages>
   <Active>true [all new users are created as active]</Active>
   <Skype>string[optional, max length 100]</Skype>
   <PhoneWork>string[optional, max length 50]</PhoneWork>
   <PhoneMobile>string[optional, max length 50]</PhoneMobile>
   <LastLogin>[ignored]</LastLogin>
   <LoginKey>[ignored]</LoginKey>
   <IsCustomUsername>true/false - set to true if UserName field is not an email address</IsCustomUsername>
   <Password>string [optional. If used must be at least 6 characters, max length 20]</Password>
   <SkipFirstLogin>true/false</SkipFirstLogin>
   <TimeZone>string [see time zone list | optional defaults to Organisation Time Zone]</TimeZone>
   <Street1>string[optional, max length 100]</Street1>
   <Street2>string[optional, max length 100]</Street2>
   <City>string[optional, max length 100]</City>
   <State>string[optional, max length 100]</State>
   <PostalCode>string[optional, max length 100]</PostalCode>
   <Country>string[optional, max length 100]</Country>
   <CompanyName>string[optional, max length 100]</CompanyName>
   <JobTitle>string[optional, max length 100]</JobTitle>
   <CustomField1>string[optional, max length 500]</CustomField1>
   <CustomField2>string[optional, max length 500]</CustomField2>
   <CustomField3>string[optional, max length 500]</CustomField3>
<CustomField4>string[optional, max length 500]</CustomField4>
<CustomField5>string[optional, max length 500]</CustomField5>
<CustomField6>string[optional, max length 500]</CustomField6>
<CustomField7>string[optional, max length 500]</CustomField7>
<CustomField8>string[optional, max length 500]</CustomField8>
<CustomField9>string[optional, max length 500]</CustomField9>
<CustomField10>string[optional, max length 500]</CustomField10>
<Culture>string[optional, max length 500]</Culture>
<Brand></Brand>
<ManagerId>string [max length 50]</ManagerId>
<ManagerName>string [max length 200]</ManagerName>
<EnableTextNotification>true/false</EnableTextNotification>
</User>

Minimum list of fields for a PUT or POST request:

<User> 
<Id></Id> 
<UserName>MyUserName</UserName> 
<FirstName>MyFirstName</FirstName> 
<LastName>MyLastName</LastName> 
<FullName></FullName> 
<Email>testing124@test.com</Email> 
<AccessLevel>Learner</AccessLevel> 
<DisableMessages>false</DisableMessages> 
<Active>true</Active> 
<LastLogin></LastLogin> 
<LoginKey></LoginKey> 
<IsCustomUsername>true</IsCustomUsername> 
<SkipFirstLogin>false</SkipFirstLogin> 
<TimeZone></TimeZone> 
</User>

Response

Returns a HTTP status code 201 (Created) on success with the new user Id populated in the response body.

<User>
   <Id>string [max length 50]</Id>
   <UserName>string [max length 255]</UserName>
   <FirstName>string [max length 50]</FirstName>
   <LastName>string [max length 50]</LastName>
   <FullName>string [max length 200]</FullName>
   <Email>string [optional, max length 255]</Email>
   <LoginKey>string [max length 50]</LoginKey>
   <AccessLevel>string [Trainee or Trainer]</AccessLevel>
   <DisableMessages>true/false</DisableMessages>
   <Active>true/false</Active>
   <Skype>string[optional, max length 100]</Skype>
   <PhoneWork>string[optional, max length 50]</PhoneWork>
   <PhoneMobile>string[optional, max length 50]</PhoneMobile>
   <LastLogin>datetime [iso 8601 format, empty if never logged in]</LastLogin>
   <TimeZone>string [see time zone list]</TimeZone>
   <OriginalId>integer</OriginalId>
   <Street1>string[optional, max length 100]</Street1>
   <Street2>string[optional, max length 100]</Street2>
   <City>string[optional, max length 100]</City>
   <State>string[optional, max length 100]</State>
   <PostalCode>string[optional, max length 100]</PostalCode>
   <Country>string[optional, max length 100]</Country>
   <CompanyName>string[optional, max length 100]</CompanyName>
   <JobTitle>string[optional, max length 100]</JobTitle>
   <CustomField1>string[optional, max length 500]</CustomField1>
   <CustomField2>string[optional, max length 500]</CustomField2>
   <CustomField3>string[optional, max length 500]</CustomField3>
<CustomField4>string[optional, max length 500]</CustomField4>
<CustomField5>string[optional, max length 500]</CustomField5>
<CustomField6>string[optional, max length 500]</CustomField6>
<CustomField7>string[optional, max length 500]</CustomField7>
<CustomField8>string[optional, max length 500]</CustomField8>
<CustomField9>string[optional, max length 500]</CustomField9>
<CustomField10>string[optional, max length 500]</CustomField10>
<Culture>string[optional, max length 500]</Culture>
<Brand></Brand>
<ManagerId>string [max length 50]</ManagerId>
<ManagerName>string [max length 200]</ManagerName>
<EnableTextNotification>true/false</EnableTextNotification>
</User>

Note:  Although many of the fields of the body request is optional, the order of the tags must be in order.

Update User

Update a single user profile in your organisation.  The user Id in the uri must match the Id specified in the request body. AccessLevel:Administrators Only

Request Uri

PUT /users/{user-id}

Request Body

<User>
   <Id>string [user id to update, max length 50]</Id>
   <UserName>string [max length 255]</UserName>
   <FirstName>string [max length 50]</FirstName>
   <LastName>string [max length 50]</LastName>
   <FullName>[ignored]</FullName>
   <Email>[ignored, change UserName to change this]</Email>
   <AccessLevel>[Administrator/Learner/Team_Leader/Learner]</AccessLevel>
   <DisableMessages>true/false [optional, default to false]</DisableMessages>
   <Active>true/false</Active>
   <Skype>string[optional, max length 100]</Skype>
   <PhoneWork>string[optional, max length 50]</PhoneWork>
   <PhoneMobile>string[optional, max length 50]</PhoneMobile>
   <LastLogin>[ignored]</LastLogin>
   <LoginKey>[ignored]</LoginKey>
   <Password>string [optional. If used must be at least 6 characters, max length 20]</Password>
   <SkipFirstLogin>true/false</SkipFirstLogin>
   <TimeZone>string [see time zone list | optional]</TimeZone>
   <Street1>string[optional, max length 100]</Street1>
   <Street2>string[optional, max length 100]</Street2>
   <City>string[optional, max length 100]</City>
   <State>string[optional, max length 100]</State>
   <PostalCode>string[optional, max length 100]</PostalCode>
   <Country>string[optional, max length 100]</Country>
   <CompanyName>string[optional, max length 100]</CompanyName>
   <JobTitle>string[optional, max length 100]</JobTitle>
   <CustomField1>string[optional, max length 500]</CustomField1>
   <CustomField2>string[optional, max length 500]</CustomField2>
   <CustomField3>string[optional, max length 500]</CustomField3>
<CustomField4>string[optional, max length 500]</CustomField4>
<CustomField5>string[optional, max length 500]</CustomField5>
<CustomField6>string[optional, max length 500]</CustomField6>
<CustomField7>string[optional, max length 500]</CustomField7>
<CustomField8>string[optional, max length 500]</CustomField8>
<CustomField9>string[optional, max length 500]</CustomField9>
<CustomField10>string[optional, max length 500]</CustomField10>
<Culture>string[optional, max length 500]</Culture>
<Brand>String</Brand>
<ManagerId>string [max length 50]</ManagerId>
<ManagerName>string [max length 200]</ManagerName>
<EnableTextNotification>true/false</EnableTextNotification>
</User>

Response

Returns a HTTP status code 200 on success

Minimum Field for updating the user

<User> 
<Id></Id> 
<UserName>MyUserName</UserName> 
<FirstName>MyFirstName</FirstName> 
<LastName>MyLastName</LastName> 
<FullName></FullName> 
<Email>testing124@test.com</Email> 
<AccessLevel>Learner</AccessLevel> 
<DisableMessages>false</DisableMessages> 
<Active>true</Active> 
<LastLogin></LastLogin> 
<LoginKey></LoginKey> 
<IsCustomUsername>true</IsCustomUsername> 
<SkipFirstLogin>false</SkipFirstLogin> 
<TimeZone></TimeZone> 
</User>

 

Delete User

Delete a single user profile in your organisation.  The user will be deleted completely from the system.

Note: Please be careful with the use of this function as once the user is deleted from the system there is no way to re-activate the user.

AccessLevel: Administrators Only

Request Uri

 DELETE/users/{user-id}?apikey={apikey}&source={source}

Response

Returns a HTTP status code 200 on success

Get User Details

Returns a detailed list of people in your organisation including active and inactive people. By default only the first 100 people are returned. The list can be filtered on first or last name, paged using the optional paging parameters, and created date.

To return users with a CreatedDate after a specific date add "&since=YYYY-MM-DD" to the end of the request.  For example:  

GET https://api.litmos.com/v1.svc/users/details?apikey=MY-KEY&source=MY-APP&since=2015-12-09

AccessLevel: Administrators Only

Request Uri

GET /users/details

Response

<Users>
<User> <Id>string [max length 50]</Id> <UserName>string [max length 255]</UserName> <FirstName>string [max length 50]</FirstName> <LastName>string [max length 50]</LastName> <FullName>string [max length 200]</FullName> <Email>string [max length 255]</Email> <AccessLevel>string [Trainee or Trainer]</AccessLevel> <DisableMessages>true/false</DisableMessages> <Active>true/false</Active> <Skype>string[max length 100]</Skype> <PhoneWork>string[max length 50]</PhoneWork> <PhoneMobile>string[max length 50]</PhoneMobile> <LastLogin>datetime [iso 8601 format, empty if never logged in]</LastLogin> <LoginKey>string [max length 512]</LoginKey> <TimeZone>string [see time zone list]</TimeZone> <OriginalId>integer</OriginalId> <Street1>string[optional, max length 100]</Street1> <Street2>string[optional, max length 100]</Street2> <City>string[optional, max length 100]</City> <State>string[optional, max length 100]</State> <PostalCode>string[optional, max length 100]</PostalCode> <Country>string[optional, max length 100]</Country> <CompanyName>string[optional, max length 100]</CompanyName> <JobTitle>string[optional, max length 100]</JobTitle> <CustomField1>string[optional, max length 500]</CustomField1> <CustomField2>string[optional, max length 500]</CustomField2> <CustomField3>string[optional, max length 500]</CustomField3>
<CustomField4>string[optional, max length 500]</CustomField4>
<CustomField5>string[optional, max length 500]</CustomField5>
<CustomField6>string[optional, max length 500]</CustomField6>
<CustomField7>string[optional, max length 500]</CustomField7>
<CustomField8>string[optional, max length 500]</CustomField8>
<CustomField9>string[optional, max length 500]</CustomField9>
<CustomField10>string[optional, max length 500]</CustomField10>
<SalesforceContactId>string[optional, max length 500]</SalesforceContactId>
<SalesforceAccountId>string[optional, max length 500]</SalesforceAccountId>
<CreatedDate>datetime [iso 8601 format]</CreatedDate>
<Points>integer</Points>
<Brands>String</Brands>
<ManagerId>string [max length 50]</ManagerId>
<ManagerName>string [max length 200]</ManagerName>
<EnableTextNotification>true/false</EnableTextNotification>
 </User>
<User>
...
</User>
</Users>

Returns a HTTP status code 200 on success

Get User Custom Fields (Non-legacy)

Returns a list of Custom Fields set up in Accounts > Integrations > Custom Fields > User Custom Fields in your organisation per user.

GET https://api.litmos.com/v1.svc/users/{userID}/usercustomfields?apikey=MY-KEY&source=MY-APP

AccessLevel: Administrators Only

Request Uri

GET users/{userID}/usercustomfields

Response

<UserCustomField>   
  <Parameter fieldname="[unique custom field label]">[custom field value]</Parameter>  
<Parameter fieldname="[unique custom field label]">[custom field value]</Parameter>
...
</UserCustomField>

Post User Custom Fields (Non-legacy)

Post a list of Custom Fields set up in Accounts > Integrations > Custom Fields > User Custom Fields in your organisation per user.

POST https://api.litmos.com/v1.svc/users/{userID}/usercustomfields?apikey=MY-KEY&source=MY-APP

AccessLevel: Administrators Only

Request Uri

POST users/{userID}/usercustomfields

Request Body

<UserCustomField>   
  <Parameter fieldname="[unique custom field label]">[custom field value]</Parameter>  
<Parameter fieldname="[unique custom field label]">[custom field value]</Parameter>
...
</UserCustomField>
Have more questions? Submit a request

0 Comments

Article is closed for comments.