Litmos recommends the User Bulk Import API endpoint for business scenarios that require creating or updating a set of users at once. This endpoint works for creating and updating users, both of which use the POST request method and accept either XML or JSON data formats. The user bulk import API invokes the same import process that an administrator would invoke on the user interface.
Create a new Bulk Import for an organization
Create a new user bulk import job. This API Path can be used to create and update user records in bulk. Username is the unique identifier in the import, the username cannot be changed through the use of the user bulk import job. All other fields can be updated, and the current value of a user field will not be nullified if a value is not specified for the same field in the import.
Request URI
POST /bulkimports?source={source}
Response Body (XML)
<UserBulkImport xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Id>string</Id>
<ImportDate>YYYY-MM-DDTHH:MM:SS</ImportDate>
<Status>Waiting</Status>
<TotalRecords>integer</TotalRecords>
<TotalUsersCreated>integer</TotalUsersCreated>
<Failed>integer</Failed>
<Duplicate>integer</Duplicate>
<InvalidEmail>integer</InvalidEmail>
<SendEmails>true/fase</SendEmails>
<SkipFirstLogin>true/false</SkipFirstLogin>
<IsAPIImport>true/false</IsAPIImport>
</UserBulkImport>
Response Header
200 Ok
Important Notes:
- Body size max: 2000KB, which will be equivalent to nearly 2000 users.
- Required Fields: UserName, FirstName, LastName are required fields.
- By default, the “Enable notifications for messages” value is set to “Enabled” for all users imported with the bulk feature.
- Values must be given if InactiveDate and AccessLevel fields are passed in the request body, these fields cannot be passed with a null value. AccessLevel can be ‘L‘ for Learner or ‘TL‘ or ‘TA‘ for Team Leader or Team Admin (they will still need to be promoted within a team), or use number values: ‘2‘ is Account Owner, ‘3‘ is Administrator, ‘4‘ is Team Leader, ‘5‘ is Learner.
- The CustomFields are based on org setup. If the org has mandatory custom fields, these become required in the import else they’re optional.
- The <Team> and <Course> fields require the use of the TeamCodeForBulkImport and CourseCodeForBulkImport. These codes can be located in the UI on the Team and Course settings pages, otherwise they are available via the API GET /Teams? and GET /Courses? endpoints.
- Manager field accepts both manager Id and manager username.
Query string parameters:
&sendmessage=[true/false]set true if you want to send login emails&skipfirstlogin=[true/false]set to true if you want to skipfirstlogin&format=jsonsets json format
Request Body (XML)
<UserImports>
<UserImport>
<Username></Username>
<Email></Email>
<FirstName></FirstName>
<LastName></LastName>
<Password></Password>
<Phone></Phone>
<Mobile></Mobile>
<Skype></Skype>
<Title></Title>
<CompanyName></CompanyName>
<WebSite></WebSite>
<Twitter></Twitter>
<Team1></Team1>
<Team2></Team2>
<Team3></Team3>
<Team4></Team4>
<Team5></Team5>
<Course1></Course1>
<Course2></Course2>
<Course3></Course3>
<Address1></Address1>
<Address2></Address2>
<City></City>
<State></State>
<Zip></Zip>
<Country></Country>
<CustomField1></CustomField1>
<CustomField2></CustomField2>
<CustomField3></CustomField3>
<CustomField4></CustomField4>
<CustomField5></CustomField5>
<CustomField6></CustomField6>
<CustomField7></CustomField7>
<CustomField8></CustomField8>
<CustomField9></CustomField9>
<CustomField10></CustomField10>
<SalesforceId></SalesforceId>
<SalesforceAccountId></SalesforceAccountId>
<SalesforceContactId></SalesforceContactId>
<Active>true/false</Active>
<InactiveDate></InactiveDate>
<AccessLevel>L,TA,TL,2,3,4,5</AccessLevel>
<Brand></Brand>
<Culture></Culture>
<Manager></Manager>
<UserCustomField1></UserCustomField1>
<UserCustomField2></UserCustomField2>
<UserCustomField3></UserCustomField3>
<UserCustomField4></UserCustomField4>
<UserCustomField5></UserCustomField5>
<UserCustomField6></UserCustomField6>
<UserCustomField7></UserCustomField7>
<UserCustomField8></UserCustomField8>
<UserCustomField9></UserCustomField9>
<UserCustomField10></UserCustomField10>
<UserCustomField11></UserCustomField11>
<UserCustomField12></UserCustomField12>
<UserCustomField13></UserCustomField13>
<UserCustomField14></UserCustomField14>
<UserCustomField15></UserCustomField15>
<UserCustomField16></UserCustomField16>
<UserCustomField17></UserCustomField17>
<UserCustomField18></UserCustomField18>
<UserCustomField19></UserCustomField19>
<UserCustomField20></UserCustomField20>
<UserCustomField21></UserCustomField21>
<UserCustomField22></UserCustomField22>
<UserCustomField23></UserCustomField23>
<UserCustomField24></UserCustomField24>
<UserCustomField25></UserCustomField25>
<JobRole></JobRole>
<ExternalEmployeeID></ExternalEmployeeID>
<ProfileType></ProfileType>
</UserImport>
</UserImports>
Request Body (JSON)
[
{
"Id": "",
"Username": "",
"Email": "",
"FirstName": "",
"LastName": "",
"Password": "",
"Phone": "",
"Mobile": "",
"Skype": "",
"Title": "",
"CompanyName": "",
"WebSite": "",
"Twitter": "",
"Team1": "",
"Team2": "",
"Team3": "",
"Team4": "",
"Team5": "",
"Course1": "",
"Course2": "",
"Course3": "",
"Address1": "",
"Address2": "",
"City": "",
"State": "",
"Zip": "",
"Country": "",
"CustomField1": "",
"CustomField2": "",
"CustomField3": "",
"CustomField4": "",
"CustomField5": "",
"CustomField6": "",
"CustomField7": "",
"CustomField8": "",
"CustomField9": "",
"CustomField10": "",
"SalesforceId": "",
"SalesforceAccountId": "",
"SalesforceContactId": "",
"Active": "true/false",
"InactiveDate": "",
"AccessLevel": "L,TA,TL,2,3,4,5",
"Brand": "",
"Culture": "",
"Manager": "",
"UserCustomField1": "",
"UserCustomField2": "",
"UserCustomField3": "",
"UserCustomField4": "",
"UserCustomField5": "",
"UserCustomField6": "",
"UserCustomField7": "",
"UserCustomField8": "",
"UserCustomField9": "",
"UserCustomField10": "",
"UserCustomField11": "",
"UserCustomField12": "",
"UserCustomField13": "",
"UserCustomField14": "",
"UserCustomField15": "",
"UserCustomField16": "",
"UserCustomField17": "",
"UserCustomField18": "",
"UserCustomField19": "",
"UserCustomField20": "",
"UserCustomField21": "",
"UserCustomField22": "",
"UserCustomField23": "",
"UserCustomField24": "",
"UserCustomField25": "",
"JobRole": "",
"ExternalEmployeeID": "",
"ProfileType": ""
}
]
Gets the latest Bulk Imports for an organization
Get the most recent user bulk import jobs (1000 max).
Request URI
GET /bulkimports?source={source}
Response Body (XML)
<UserBulkImports>
<UserBulkImport>
<Id>string [max length 50]</Id>
<ImportDate>YYYY-MM-DDTHH:MM:SS</ImportDate>
<Status>Waiting/Queued/Completed/Failed</Status>
<TotalRecords>integer</TotalRecords>
<TotalUsersCreated>integer</TotalUsersCreated>
<Failed>integer</Failed>
<Duplicate>integer</Duplicate>
<InvalidEmail>integer</InvalidEmail>
<SendEmails>true/false</SendEmails>
<SkipFirstLogin>true/false</SkipFirstLogin>
<IsAPIImport>true/fase</IsAPIImport>
</UserBulkImport>
<UserBulkImport>
<Id>string [max length 50]</Id>
<ImportDate>YYYY-MM-DDTHH:MM:SS</ImportDate>
<Status>Completed/Failed/Queued</Status>
<TotalRecords>integer</TotalRecords>
<TotalUsersCreated>integer</TotalUsersCreated>
<Failed>integer</Failed>
<Duplicate>integer</Duplicate>
<InvalidEmail>integer</InvalidEmail>
<SendEmails>true/false</SendEmails>
<SkipFirstLogin>true/false</SkipFirstLogin>
<IsAPIImport>true/fase</IsAPIImport>
</UserBulkImport>
</UserBulkImports>
Response Header
200 Ok
Get a specific Bulk Import:
Get the status of a specific user bulk import job.
Request URI
GET /bulkimports/{bulkimportid}?source={source}
Response Body (XML)
<UserBulkImport xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Id>string [max length 50]</Id>
<ImportDate>YYYY-MM-DDTHH:MM:SS</ImportDate>
<Status>Waiting/Queued/Completed/Failed</Status>
<TotalRecords>integer</TotalRecords>
<TotalUsersCreated>integer</TotalUsersCreated>
<Failed>integer</Failed>
<Duplicate>integer</Duplicate>
<InvalidEmail>integer</InvalidEmail>
<SendEmails>true/false</SendEmails>
<SkipFirstLogin>true/false</SkipFirstLogin>
<IsAPIImport>true/false</IsAPIImport>
</UserBulkImport>
Response Header
200 Ok
Get errors for a User Bulk Import:
Get the import processing errors for user records in a user bulk import job.
Query string parameters:
&IsAPI=[false]including this parameter will fetch the list of user import errors for a user import job performed within the application from the user interface. Without this query string parameter, the call will fetch only user import errors for user import jobs performed from the API.
Request URI
GET /bulkimports/{bulkimportid}/usererrors?source={source}
Response Body (XML)
<Users xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<User>
<Username>string [max length 255]</Username>
<ImportStatus>Failed - Error Message</ImportStatus>
</User>
<User>
<Username>string [max length 255]</Username>
<ImportStatus>Failed - Error Message</ImportStatus>
</User>
<User>
<Username>string [max length 255]</Username>
<ImportStatus>Failed - Error Message</ImportStatus>
</User>
</Users>