Use the API to manage users

Step 1 – Provision a user account

To provision a user account a POST request must be made to:

POST ​/api​/v2​/schools​/{school_id}​/users

The attributes for provisioning users are listed in the schema section of the user documentation.

Role
If no role is set, the default role of ‘student’ will be given to the user. In this case it is also required to send a value for the student number. You can either set one of the default school roles that Ans provided, as mentioned in the documentation, or you can use it in combination with a custom role. In that case you'll need to set the role_id attribute. This can also be used to set the role of the user in a course of question bank.

External_id
The external_id can be used to add a reference to a unique id of a user in your own organisation. You can use the external_id in step 2 to find a user in Ans based on the provided external_id to update or deprovision a user.

Step 2 – Find/Search a user account 

To search for a user account a GET request must be made to:

GET ​/api​/v2​/search​/users

A query must be sent along with the request URL, which consists of an attribute and a value associated with it in order to search for a specific value, or a range between numeric and date values. Additional information about the Search API can be found in the search documentation.

Example:  /api/v2/search/users?query=first_name:John last_name:Doe

Curl example: curl -H "Authorization: Bearer token=<token>" "https://ans.app/api/v2/search/users?query=first_name:John%20last_name:Doe"

Step 3 – View a user account

To view a user account a GET request can be made to several endpoints:

To list all the users in the school a GET request must be made to:

GET ​/api​/v2​/schools/{school_id}/users

This will retrieve all the users within that school and display general information about the users, such as: name, email and role. Please note that the Ans API uses pagination, so you will need to implement logic to go through the pages if you want to list more than 20 users.

To show a specific user a GET request must be made to:

GET ​/api​/v2​/users/{user_id}

This will retrieve a single user but will also display more information, such as:

• Which courses the user belongs to and what their role is within that course.
• Which question banks belong to the user.
• Which departments belong to the user, if they have the operator role.

Step 4 – Update a user account

To update a user account a PATCH request must be made to:

PATCH ​/api​/v2​/users/{user_id}

Alongside updating user information, a user can also be added or removed from courses, question banks or departments using the PATCH request. 

If a user is already enrolled in a course and needs to be enrolled in another course without being removed from the old course, then the information of the old course must be sent alongside the information of the new course with the same request. Otherwise the user will be enrolled in the new course and removed from the old course. The same applies for question banks.

If a user has results for an assignment within the course, then this user cannot be removed from the course. 

Step 5 – Deprovision a user account

To deprovision the user a DELETE request must be made to:

DELETE ​/api​/v2​/users/{user_id}

An alternative option is to set the user account to inactive by updating the user active attribute to ‘false’ with the PATCH request in Step 4. This will not delete the user account, but it will make sure that the user will only see a message that their account has been deactivated after logging in to Ans.

Deprovisioning users will remove all personal information except for the student number. Deprovisioned students can be provisioned again by searching for the student number and setting the user active attribute to ‘true’. After deprovisioning an employee account, you can only create a new employee account, as the employee is no longer able to reuse its deprovisioned account.