○ API calls - Users
These API calls make it possible to:
- get information about existing users
- set an external ID for an existing user
- create new users
- edit existing users
- set user roles
- link authors/designers to content libraries
Context
aNewSpring has users that can have one or more roles:
- Learners can be subscribed to a course.
- Instructors and observers have a supervising/guiding role.
- Authors and designers are involved in creating the course. For this, they need to be linked to content libraries. Authors can modify the actual content in a content library and designers can use the content to build a learning journey in a template. Users are often both author and designer.
For authors to be able to edit content, they will need author rights for the content library.
A template can use multiple content libraries. For a designer to be able to edit a template, they will need designer rights for all the content libraries that are linked to the template. - Administrators can manage users and courses.
Courses are created (instantiated) from templates. - Resellers have limited options to manage courses, they can create access codes that learners can use to get access and they can manage the catalogue and orders.
- Tenants are the "owners" of the learning environment and have access to some top level settings and can buy licences (to subscribe learners to courses)
Support articles:
For historical reasons and to continue to support old API integrations, the terminology of the API and the front-end for administrators does not always match completely. In the API:
- A Learner is called a Student.
- An Instructor is called a Teacher.
- An Observer is called a Mentor.
- A Content library is called a ContentLabel.
API calls
You can view more information and an example of each API call in the API Documentation by clicking the titles below. However, all links go to the /apidocs page of a demo environment that you cannot use for your own testing purposes.
To test the API calls, you will need to change the first part of the URL to match the right learning environment.
GET requests
GET /userExists/{userID}
or GET /userExists?userUID={userUID}
Use this to check if a specific user already exsts. The output will contain a parameter result with value true or false. You will need to use the external ID (userID) or the UID (userUID) of the user.
GET /getUser/{userID}
or GET /getUser?userUID={userUID}
Use this to get the details of a specific user. You will need to use the external ID (userID) or the UID (userUID) of the user.
GET /getUsers
Use this to get all users. This includes users without external IDs, inactive users and archived users.
POST requests
POST /initializeId/{login}/{userID}
Use this to set an external ID for an existing user that does not have an external ID yet. You will need to use the email address (or login name*) of the existing user and a new unique external ID for this user.
*By default, users log in with an email address, but some learning environments have login names instead. In that case, you need to use the login name here.
POST /addUser/{userID}
Use this to add a new user. The user will get the external ID that you specify as userID.
The user roles can be sent as an array in the parameter role, by repeating the same parameter with different values.
If you want to send a profile picture in the avatar parameter, you need to set Content-Type to multipart/form-data.
POST /updateUser/{userID}
or POST /updateUser?userUID={userUID}
Use this to change the details of an existing user. You will need to use the external ID (userID) or the UID (userUID) of the user.
If you want to send a profile picture in the avatar parameter, you need to set Content-Type to multipart/form-data.
POST /addOrUpdateUser/{userID}
You can use this if you're not sure if a user already exists. If the user already exists, it will work as /updateUser and only accept those parameters. If the user doesn't exist yet, it will work as /addUser and only accept those parameters. You will need to use the external ID (userID) of the user.
POST /addUserRoles/{userID}
or POST /addUserRoles?userUID={userUID}
Use this to set the roles of a user. You can only add roles and not remove them. The user roles can be sent as an array in the parameter role, by repeating the same parameter with different values.
You will need to use the external ID (userID) or the UID (userUID) of the user.
POST /deleteUser/{userID}
or POST /deleteUser?userUID={userUID}
Use this to delete a user. This cannot be undone. You will need to use the external ID (userID) or the UID (userUID) of the user.
POST /linkAuthorToContentLabels/{userID}
or POST /linkAuthorToContentLabels?userUID={userUID}
Use this to assign author rights for one or more content libraries to a user. If the user doesn't have the author role yet, use /addUserRoles first to assign this role. You will need to use the external ID (userID) or the UID (userUID) of the user and the external IDs of the content libraries that you want to assign this user to. The external IDs of the content libraries can be sent as an array in the parameter contentLabel, by repeating the same parameter with different values.
POST /linkDesignerToContentLabels/{userID}
or POST /linkDesignerToContentLabels?userUID={userUID}
Use this to assign designer rights for one or more content libraries to a user. If the user doesn't have the designer role yet, use /addUserRoles first to assign this role. You will need to use the external ID (userID) or the UID (userUID) of the user and the external IDs of the content libraries that you want to assign this user to. The external IDs of the content libraries can be sent as an array in the parameter contentLabel, by repeating the same parameter with different values.
POST /unlinkAuthorFromContentLabels/{userID}
or POST /unlinkAuthorFromContentLabels?userUID={userUID}
Use this to take away the author rights for one or more content libraries from a user. You will need to use the external ID (userID) or the UID (userUID) of the user and the external IDs of the content libraries that you want to take away from the user. The external IDs of the content libraries can be sent as an array in the parameter contentLabel, by repeating the same parameter with different values.
POST /unlinkDesignerFromContentLabels/{userID}
or POST /unlinkDesignerFromContentLabels?userUID={userUID}
Use this to take away the designer rights for one or more content libraries from a user. You will need to use the external ID (userID) or the UID (userUID) of the user and the external IDs of the content libraries that you want to take away from the user. The external IDs of the content libraries can be sent as an array in the parameter contentLabel, by repeating the same parameter with different values.