Get User List
Returns a list of people in your organization 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?source={source}&limit=1000
To retrieve only active users, add the parameter “&showInactive=false” to the end of the request.
GET https://api.litmos.com/v1.svc/users?source={source}&showInactive=false
Request URI
GET /users?
Response Body (XML)
<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>
</Users>
Get Paginated User List
Returns a collection of records including a list of people in your organization (active and inactive) along with a summary of the user pagination information. 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/paginated?source={source}&limit=1000
To retrieve only active users, add the parameter “&showInactive=false” to the end of the request.
GET https://api.litmos.com/v1.svc/users/paginated?source={source}&showInactive=false
Request URI
GET /users/paginated?
Response Body (XML)
<UserCollection xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Pagination>
<BatchParam>Limit</BatchParam>
<BatchSize>integer</BatchSize>
<Start>integer</Start>
<TotalCount>integer</TotalCount>
</Pagination>
<Items>
<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>
<Active>true/false</Active>
<Email>string [max length 255]</Email>
<AccessLevel>string</AccessLevel>
<Brand>string</Brand>
</User>
<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>
<Active>true/false</Active>
<Email>string [max length 255]</Email>
<AccessLevel>string</AccessLevel>
<Brand>string</Brand>
</User>
</Items>
</UserCollection>
Get User
Returns a single user record.
Request URI
GET /users/{userid}?
Response Body (XML)
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</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>
<Website></Website>
<Twitter></Twitter>
<ExpirationDate></ExpirationDate>
<JobRole></JobRole>
<ExternalEmployeeId>string[optional, max length 100]</ExternalEmployeeId>
<ProfileType>Null/Internal/External</ProfileType>
</User>
Get User by Username
Returns user data for a user that matches the username string.
Request URI
GET /users/{username}?
Response Body (XML)
<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>string</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 Org 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>
<Website></Website>
<Twitter></Twitter>
<ExpirationDate></ExpirationDate>
<JobRole></JobRole>
<ExternalEmployeeId>string[optional, max length 100]</ExternalEmployeeId>
<ProfileType>Null/Internal/External</ProfileType>
</User>
Get User by originalID
Returns a user that matches the user’s originalID.
For example: https://api.litmos.com/v1.svc/users/details?source=test&originalID=123. This returns ONLY a user with originalID 123.
Request URI
GET /users?source={source}&originalID={originalID}
Request URI
GET /users/details?source={source}&originalID={originalID}
Get Users by Using Username, First/Last Name, Email, or Company Name
Returns all users with a matching username, first name, last name, email address, or company name.
Request URI
GET /users?source={source}&search={username}
Response Body (XML)
<Users>
<User>
<Id>abc12345678</Id>
<UserName>rich_demo@litmos.com</UserName>
<FirstName>Rich</FirstName>
<LastName>Demo</LastName>
</User>
</Users>
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 Created Date 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?source=MY-APP&since=2015-12-09
Request URI
GET /users/details?
Response Body (XML)
<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</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>
<IsCustomUsername>true/false</IsCustomUsername>
<SkipFirstLogin>true/false</SkipFirstLogin>
<TimeZone>string [see time zone list*]</TimeZone>
<SalesforceId i:nil="true"/>
<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>
<Culture>string[optional, max length 500]</Culture>
<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>
<Brand>String</Brand>
<ManagerId>string [max length 50]</ManagerId>
<ManagerName>string [max length 200]</ManagerName>
<EnableTextNotification>true/false</EnableTextNotification>
<Website></Website>
<Twitter></Twitter>
<ExpirationDate></ExpirationDate>
<JobRole></JobRole>
<ExternalEmployeeId>string[optional, max length 100]</ExternalEmployeeId>
<ProfileType>Null/Internal/External</ProfileType>
</User>
<User>
...
</User>
</Users>
Response Header
200 OK
Create User
Creates a new user profile in your organization. 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.
Note: You will need to use the same order listed below to update the information. Do not change the order of items or the PUT or POST request will not update/create the users. You can either use the short body or the full body for the request.
Request URI:
POST /users?
Request Body (XML)
Entire 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>Account_Owner/Admin/Team_Leader/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>
<Website></Website>
<Twitter></Twitter>
<ExpirationDate></ExpirationDate>
<JobRole></JobRole>
<ExternalEmployeeId>string[optional, max length 100]</ExternalEmployeeId>
<ProfileType>Null/Internal/External</ProfileType>
</User>
Mandatory list of fields:
<User>
<Id>[Mandatory for PUT]</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 Body (XML)
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</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>
<IsCustomUsername>true</IsCustomUsername>
<Password></Password>
<SkipFirstLogin>false</SkipFirstLogin>
<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>
<Website></Website>
<Twitter></Twitter>
<ExpirationDate></ExpirationDate>
<JobRole></JobRole>
<ExternalEmployeeId>string[optional, max length 100]</ExternalEmployeeId>
<ProfileType>Null/Internal/External</ProfileType>
</User>
Important Note: Although many of the fields of the body request are optional, the order of the included fields must be in the same default order.
Update User
Update a user record.
Important Note: The user Id in the uri must match the Id specified in the request body.
Request URI
PUT /users/{userid}?
Request Body (XML)
<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>Account_Owner/Admin/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>
<Website></Website>
<Twitter></Twitter>
<ExpirationDate></ExpirationDate>
<JobRole></JobRole>
<ExternalEmployeeId>string[optional, max length 100]</ExternalEmployeeId>
<ProfileType>Null/Internal/External</ProfileType>
</User>
Response Body (JSON)
Returns a HTTP status code 200 on success
{
"Id": "",
"UserName": "",
"FirstName": "",
"LastName": "",
"FullName": "",
"Email": "",
"AccessLevel": "",
"DisableMessages": "",
"Active": "",
"Skype": "",
"PhoneWork": "",
"PhoneMobile": "",
"LastLogin": "",
"LoginKey": "",
"Password": "",
"SkipFirstLogin": "",
"TimeZone": "",
"Street1": "",
"Street2": "",
"City": "",
"State": "",
"PostalCode": "",
"Country": "",
"CompanyName": "",
"JobTitle": "",
"CustomField1": "",
"CustomField2": "",
"CustomField3": "",
"CustomField4": "",
"CustomField5": "",
"CustomField6": "",
"CustomField7": "",
"CustomField8": "",
"CustomField9": "",
"CustomField10": "",
"Culture": "",
"Brand": "",
"ManagerId": "",
"ManagerName": "",
"EnableTextNotification": "",
"Website": "",
"Twitter": "",
"ExpirationDate": "",
"JobRole": "",
"ExternalEmployeeId": "",
"ProfileType": ""
}
Mandatory list of fields:
<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 record
Important Note: User records are hard deleted, they are not soft deleted and therefore cannot be recovered. Perform user deletions with caution.
Request URI
DELETE /users/{userid}?
Response Header
200 OK
Get a List of All the Teams that a User is Assigned to
Returns a list of all the Teams a specific user is assigned to.
Request URI
GET /users/{user_id}/teams?source={source}&format=json
Response Body (JSON)
Returns a HTTP status code 200 on success with the following body.
[
{
"Id": "",
"Name": "",
"TeamCodeForBulkImport": "",
"ParentTeamId": ""
}
]
Assign a User to a List of Teams
Add a user to multiple teams. If the user is already assigned to one or more teams in the request, the request will be ignored.
By default, no emails will be sent when the user is added to a team. To have an email sent to the user when they are added to a team, the following query string parameter needs to be added to the request: &sendmessage=true
Request URI
POST /users/{user-id}/teams?
Request Body (XML)
<Teams>
<Team>
<Id>string [max length 50]</Id>
</Team>
<Team>
<Id>string [max length 50]</Id>
</Team>
<Team>
<Id>string [max length 50]</Id>
</Team>
<Team>
<Id>string [max length 50]</Id>
</Team>
</Teams>
Request Body (JSON)
[
{
"Id": "string [max length 50]"
},
{
"Id": "string [max length 50]"
},
{
"Id": "string [max length 50]"
},
{
"Id": "string [max length 50]"
}
]
Remove a User from All the Teams that User is Assigned to
Often when syncing teams with a third party system it’s easiest to remove all teams assigned to a user and add them again. This is a bulk operation to make removing all teams form a specific user much faster.
Request URI
DELETE /users/{userid}/teams?
Response
200 OK