The purpose of this document is to outline changes to existing Litmos API endpoints, as well as new endpoints, to be used when Custom Roles & Permissions is enabled.  

Updated GET Endpoints 

Get Paginated 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.  

Request URL 

GET /users/paginated?

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

GET/users?source={{source}}&limit=200

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

Response Body 

<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>
            <Brand>string</Brand>
<RoleID>string</RoleID>
<RoleName>string</RoleName>
        </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>
            <Brand>string</Brand>
<RoleID>string</RoleID>
<RoleName>string</RoleName>
        </User>
    </Items>
</UserCollection>

Summary of Changes 

• No change to the Request URL 
• The Response will return a user’s profile RoleID and RoleName. Roles include Account Owner, Administrator, Learner, a Custom Account Role, or Team Role. Team Role will be returned for any user that has a custom team role assigned on a team and does not have Account Owner, Administrator, or a Custom Account Role as their profile role. 
• Please note that Team_Leader will no longer be a valid response value.   
• The Role ID is an encrypted ID for the user’s assigned role. 
• RoleName will return the name of the user’s role. Please note that this value may be different from the legacy return value- e.g. Account_Owner (Legacy) vs. Account Owner (CRP). 
• The Response will no longer return Access Level. 

Get User  

Request URLs 

To return a single user record: 

GET /users/{userid}?

To return user data for a user that matches the UserName string: 

GET /users/{username}?

To return a user that matches the user’s originalID: 

GET /users?source={source}&originalID={originalID}


GET /users/details?source={source}&originalID={originalID}

To return a user that matches exactly the user’s email address: 

GET https://api.litmos.com/v1.svc/users/details?source=test&email={email}

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>
    <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>
<RoleID>string</RoleID>
<RoleName>string</RoleName>
</User>

Summary of Changes 

• No change to the Request URL 
• The Response will return a user’s Profile Role Name and ID. Profile Roles include Account Owner, Administrator, Learner, a Custom Account Role, or Team Role. Team Role will be returned for any user that has a custom team role assigned on a team and does not have Account Owner, Administrator, or a Custom Account Role as their Profile Role. 
• Please note that Team_Leader will no longer be a valid response value.  
• The RoleID is an encrypted ID for the user’s assigned role. 
• RoleName will return the name of the user’s role. Please note that this value may be different from the legacy return value- e.g. Account_Owner (Legacy) vs. Account Owner (CRP). 
• The Response will no longer return Access Level. 

Get User Details 

Returns a detailed 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, paged using the optional paging parameters, and created date. 

Request URL 

GET /users/details?

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

Response Body 

<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>
        <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>
<RoleID>string</RoleID>
<RoleName>string</RoleName>
    </User>
</Users>

Summary of Changes 

• No change to the Request URL 
• The Response will return a user’s profile RoleID and RoleName. Roles include Account Owner, Administrator, Learner, a Custom Account Role, or Team Role. Team Role will be returned for any user that has a custom team role assigned on a team and does not have Account Owner, Administrator, or a Custom Account Role as their profile role. 
• Please note that Team_Leader will no longer be a valid response value.   
• The RoleID is an encrypted ID for the user’s assigned role. 
• RoleName will return the name of the user’s role. Please note that this value may be different from the legacy return value- e.g. Account_Owner (Legacy) vs. Account Owner (CRP). 
• The Response will no longer return Access Level. 

Get User Details with Date Range 

Returns a list of people including ‘active’ and ‘inactive’ people that have been created or updated within a given date range. 

The “&since=[DATE]&to=[DATE]” parameter is required for each of these delta API’s. 

NOTE: When using the “since” and “to” date range parameters in the request URI, the date formats adhere to the standard date=time format ‘YYYY-MM-DD HH:MM:SS’. This will return all records that were created/updated between the dates specified. The date range must be equal or less than 7 days. 

To get results for the current day, the “to” date must be set to a future date to return results successfully. 

By default, all API responses will return 100 results. You can return up to 1,000 records by adding the ‘limit’ query parameter to your URI. See the Search & Paging Parameters section for pagination and other query parameters you can use. 

Request URL 

GET /org/users/details?source={source}&since=[YYYY-MM-DD HH:MM:SS]&to=[YYYY-MM-DD HH:MM:SS]

Response Body 

<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 [optional, max length 255]</Email>
        <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, blank if never logged in]</LastLogin>
        <LoginKey>/login.aspx?loginkey=</LoginKey>
        <IsCustomUsername>true/false</IsCustomUsername>
        <TimeZone>string [max length 50, see time zone list]</TimeZone>
        <SalesforceId>string [optional, max length 50]</SalesforceId>
        <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 [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 50]</SalesforceContactId>
        <SalesforceAccountId>string [optional, max length 50]</SalesforceAccountId>
        <CreatedDate>datetime [iso 8601 format]</CreatedDate>
        <UpdatedDate>datetime [iso 8601 format]</UpdatedDate>
        <CreatedBy>integer</CreatedBy>
        <UpdatedBy>integer</UpdatedBy>
        <Brand>string [max length 200]</Brand>
        <ManagerId>string [optional, max length 50]</ManagerId>
        <ManagerName>string [optional, max length 200]</ManagerName>
        <EnableTextNotification>true/false</EnableTextNotification>
        <Website>string[optional, max length 100]</Website>
        <Twitter>string[optional, max length 100]</Twitter>
        <ExpirationDate>datetime [optional, iso 8601 format]</ExpirationDate>
        <ExternalEmployeeId>string[optional, max length 100]</ExternalEmployeeId>
<RoleID>string</RoleID>
<RoleName>string</RoleName>
    </User>
    <User>
        ..........
    </User>
</Users>

Summary of Changes 

• No change to the Request URL 
• The Response will return a user’s profile RoleID and RoleName. Roles include Account Owner, Administrator, Learner, a Custom Account Role, or Team Role. Team Role will be returned for any user that has a custom team role assigned on a team and does not have Account Owner, Administrator, or a Custom Account Role as their profile role. 
• Please note that Team_Leader will no longer be a valid response value.   
• The RoleID is an encrypted ID for the user’s assigned role. 
• RoleName will return the name of the user’s role. Please note that this value may be different from the legacy return value- e.g. Account_Owner (Legacy) vs. Account Owner (CRP). 
• The Response will no longer return Access Level. 

Get Instructors for Instructor-led Training (ILT) 

Returns a list of instructors for Instructor-led Training (ILT) 

Request URL 

GET /instructors?source={{source}}

Response Body 

<UserCollection xmlns_i="http://www.w3.org/2001/XMLSchema-instance">;
    <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>
            <Brand>string</Brand>
<RoleID>string</RoleID>
<RoleName>string</RoleName>

</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>
<Brand>string</Brand>
<RoleID>string</RoleID>
<RoleName>string</RoleName>
</User>
</Items>
</UserCollection>

Summary of Changes 

• No change to the Request URL 
• The Response will return a user’s profile RoleID and RoleName. Roles include Account Owner, Administrator, Learner, a Custom Account Role, or Team Role. Team Role will be returned for any user that has a custom team role assigned on a team and does not have Account Owner, Administrator, or a Custom Account Role as their profile role. 
• Please note that Team_Leader will no longer be a valid response value.   
• The RoleID is an encrypted ID for the user’s assigned role. 
• RoleName will return the name of the user’s role. Please note that this value may be different from the legacy return value- e.g. Account_Owner (Legacy) vs. Account Owner (CRP). 
• The Response will no longer return Access Level. 

Get Users Assigned to a Team 

Returns a list of active users assigned to a Team. 

Request URL 

GET /teams/{team-id}/users?

Response Body 

<Users>
    <User>
        <Id>string [max length 50]</Id>
        <UserName>string</UserName>
        <FirstName>string</FirstName>
        <LastName>string</LastName>
        <Active>true/false</Active>
        <Email></Email>
        <TeamRole i_nil="true">
          <Id>string</Id>
          <Name>string</Name>
        </TeamRole>
        <Brand i_nil="true"/>
    </User>
    <User>
        <Id>string [max length 50]</Id>
        <UserName>ignored</UserName>
        <FirstName>ignored</FirstName>
        <LastName>ignored</LastName>
        <Active>true/false</Active>
        <Email></Email>
        <TeamRole i_nil="true">
          <Id>string</Id>
          <Name>string</Name>
        </TeamRole>
        <Brand i_nil="true"/>
    </User>
</Users>

Summary of Changes 

• No change to the Request URL 
• The Response will return a user’s Team Role Name and Team Role ID if the user has a role within this team. The Team Role Name will dis