User Management API

Overview - User Management API

Are you sure you want to remove this component?

If you want to modify users programatically rather than manually through the user interface, a user management API exists where you can create, update, read, and delete users. You can find the details necessary in this guide.

On this page, you will find the following information:

API Configuration

Instructions - User Management API

Examples

NOTE: this feature is being deprecated and it is recommended to instead use the Schoolbox API.

API Configuration

Are you sure you want to remove this component?

1. Navigate to Administration > Settings > Security.

image.php?hash=8f1f337042d310c1f838886490495bf84c1fea3c

2. Set a complex API Key (suggestion - no spaces).

image.php?hash=6d602e10df905f98456c12230743d5c5d090a454

3. Select 'Save'.

User Management API

Are you sure you want to remove this component?

Authentication

This API uses the 'key' field for authentication. The value for this is set in the Schoolbox admin system under Admin > Settings > Security > API Key.

Create

Creates a new user.

URL

http://schoolbox.yourschool.edu.au/api/admin/user.php?action=create

Format

XML

HTTP Method

GET

Authentication

Required

Parameters

  • action (String) Should be set to 'create'. Determines which function is to be performed.
  • key (String) Used for authentication.
  • username (String) The desired username for the new user. The username must be unique.
  • password (String) An unencrypted password. This password should match the user's mail server password.
  • title (String) The user's salutation e.g. Mr or Mrs
  • firstname (String) The user's first name
  • lastname (String) The user's last name
  • database_id (Integer) The corresponding ID found in a foreign database. e.g. Synergetic
  • group (String) The name of the user's primary group. e.g. Teachers
  • campus (String) A comma separated list of the campus' the user is involved with.
  • default_campus (String) The name of the user's default campus.
  • local_email (Integer) Also referred to as 'Email Address from Username'. 1 = enabled, 0 = disabled
  • alt_email (String) The user's external email address.
  • su (Integer) Should be set to either 1 or 0 to invoke either superuser status or not respectively.
  • year (String) The current relevant year of the student. If irrelevant, this should be set to an empty string. (Integer pre-18.0.16)
  • eportfolio_enabled (Integer) Whether or not the e-portfolio module is enabled for the user. 1 = enabled, 0 = disabled
  • hide_contacts (Integer) Whether or not the contact details should appear on that user's profile page. 1 = enabled, 0 = disabled (Only in v15.5.4 onwards)
  • enabled (Integer) Whether or not the account is enabled for the new user.

Response Codes

The user management API uses an error code system loosely based on the set of HTTP status codes. This includes codes from IETF internet standards as well as unstandardised RFCs, other specifications and some additional commonly used codes. The first digit of the status code specifies one of five classes of response; the bare minimum for an HTTP client is that it recognises these five classes. The following list of codes is a sub set of codes used by the API.

201 Created The request has been fulfilled and resulted in a new user being created.

400 Bad Request The request cannot be fulfilled due to bad syntax. Missing fields or incorrect data types will often be the cause of this error.

401 Unauthorized This error is caused by an invalid API key.

409 Conflict Indicates that the request could not be processed because of conflict in the request, this is usually due to an existing user having the same username as the new user.

500 Generic Error A generic error message, given when no more specific message is suitable.

 

Update

Updates a user's details.

URL

http://schoolbox.yourschool.edu.au/api/admin/user.php?action=update

Format

XML

HTTP Method

GET

Authentication

Required

Parameters

  • action (String) Should be set to 'update'. Determines which function is to be performed.
  • key (String) Used for authentication.
  • user_id (String) The existing user's id. Note: This ID is returned when creating users.
  • username (String) The desired username for the new user. The username must be unique.
  • password (String) An unencrypted password. This password should match the user's mail server password.
  • title (String) The user's salutation e.g. Mr or Mrs
  • firstname (String) The user's first name
  • lastname (String) The user's last name
  • database_id (Integer) The corresponding ID found in a foreign database. e.g. Synergetic
  • group (String) The name of the user's primary group. e.g. Teachers
  • campus (String) A comma separated list of the campus' the user is involved with.
  • default_campus (String) The name of the user's default campus.
  • local_email (Integer) Also referred to as 'Email Address from Username'. 1 = enabled, 0 = disabled
  • alt_email (String) The user's external email address.
  • su (Integer) Should be set to either 1 or 0 to invoke either superuser status or not respectively.
  • year (String) The current relevant year of the student. If irrelevant, this should be set to an empty string. (Integer pre-18.0.16)
  • eportfolio_enabled (Integer) Whether or not the e-portfolio module is enabled for the user. 1 = enabled, 0 = disabled
  • hide_contacts (Integer) Whether or not the contact details should appear on that user's profile page. 1 = enabled, 0 = disabled (Only in v15.5.4 onwards)
  • enabled (Integer) Whether or not the account is enabled for the new user.

Note: The update action accepts updating a subset of all the fields.

Response Codes

The user management API uses an error code system loosely based on the set of HTTP status codes. This includes codes from IETF internet standards as well as unstandardised RFCs, other specifications and some additional commonly used codes. The first digit of the status code specifies one of five classes of response; the bare minimum for an HTTP client is that it recognises these five classes. The following list of codes is a sub set of codes used by the API.

201 Created The request has been fulfilled and resulted in a new user being created.

400 Bad Request The request cannot be fulfilled due to bad syntax. Missing fields or incorrect data types will often be the cause of this error.

401 Unauthorized This error is caused by an invalid API key.

404 Not Found The user to be updated could not be found.

409 Conflict Indicates that the request could not be processed because of conflict in the request, this is usually due to an existing user having the same username as the new user.

500 Generic Error A generic error message, given when no more specific message is suitable.

 

Delete

Deletes a user's account.

URL

http://schoolbox.yourschool.edu.au/api/admin/user.php?action=delete

Format

XML

HTTP Method

GET

Authentication

Required

Parameters

  • action (String) Should be set to 'delete'. Determines which function is to be performed.
  • key (String) Used for authentication.
  • user_id (String) Either the user_id or the username field will be used to find and delete the user.
  • username (String) Either the user_id or the username field will be used to find and delete the user.

Response Codes

The user management API uses an error code system loosely based on the set of HTTP status codes. This includes codes from IETF internet standards as well as unstandardised RFCs, other specifications and some additional commonly used codes. The first digit of the status code specifies one of five classes of response; the bare minimum for an HTTP client is that it recognises these five classes. The following list of codes is a sub set of codes used by the API.


400 Bad Request The request cannot be fulfilled due to bad syntax. Missing fields or incorrect data types will often be the cause of this error.

401 Unauthorized This error is caused by an invalid API key.

404 Not Found The user to be updated could not be found.

500 Generic Error A generic error message, given when no more specific message is suitable.

Examples

Are you sure you want to remove this component?

The following example use curl to initiated an HTTP GET request which receives an HTTP response code and XML response text.

Example: Creating a user

curl 'https://schoolbox.school.edu/api/admin/user.php?action=create&key=ComplexAPIKeySomething&username=testaccount&password=&title=&firstname=TestFirstname&lastname=TestLastname&database_id=P1234&group=Parents&campus=Senior&default_campus=Senior&local_email=0&alt_email=myusername%40somedomain.tld&su=0&year=&eportfolio_enabled=0&hide_contacts=0&enabled=1'

Successful Response:    201
    User successfully created.        3

Failure Response:

    409
    A user already exists with the same username. 

 

Example: Updating a users email address

curl 'https://schoolbox.school.edu/api/admin/user.php?action=update&key=ComplexAPIKeySomething&user_id=3&alt_email=myusername%40somedifferentdomain.tld'

Successful Response:

    201
    User successfully updated.

Failure Response:

    401
    You are not authorized to use this service.

 

Example: Deleting a user

curl 'https://schoolbox.school.edu/api/admin/user.php?action=delete&key=ComplexAPIKeySomething&user_id=3'OR
curl 'https://schoolbox.school.edu/api/admin/user.php?action=delete&key=ComplexAPIKeySomething&username=testaccount'

Successful Response:

    201
    User successfully deleted.

Failure Response:

    404
    User not found.