Skip to main content

Create Users and Spaces with Aula's Enrolment API

  • Updated

If your institution has the Aula API enabled, you can use it to manage users, spaces (classrooms or modules), as well as assign roles to users in spaces. Read below for annotated request bodies and some guidance on how to best design workflows with the Aula API.

Our full API spec is available here.

We've designed the API to be modular so that IT teams are able to complete tasks separately and create workflows that best suit the problem at hand.

Spaces can be created one at a time or in bulk, and it's not a requirement for students to be enrolled in them at the time they are created.

User creation also has a separate endpoint.

Once both a space has been created and a user has been created, then users can be granted a role in the space using the /sis/import/roles endpoint.

 

Create Users

POST /sis/import/users

{ 
"users": [ 
  { 
    "firstName": "string", 
    "lastName": "string", 
    "externalId": "string", // Unique identifier. This is generally the student ID that is unique to the student across systems
    "email": "string", 
    "sso": boolean, // setting this to false will let the user log in with magic links (one-time password). If empty, it will inherit the default setting for your institution
    "custom": // these are optional
      { 
        "studentId": "string", // in case there are multiple student IDs needed
        "degreeCourse": "string", // their main degree course
        "preEnrollment": boolean, // used to designate stage of enrolment
        "internationalStudent": boolean
      } 
    } 
  ] 
}

 

Create Spaces

POST /sis/import/spaces

{ 
  "spaces": [ 
    { 
      "archived": true, // archived means the space is inactive
      "code": "string", // a module code like 7000HUM
      "name": "string", // the human-readable name of the space. Most institutions choose to also include semester information.
      "externalId": "string" // a unique identifier, used in other calls to the API
    } 
  ] 
}

 

Adding Users to Spaces As Either Students Or Educators

Once users and spaces have been added to Aula, you can grant access to those spaces by assigning a role to a user.

 

POST /sis/import/roles

{ 
  "roles": [ 
    { 
      "role": "student", // or "educator"
      "externalUserId": "string", // unique externalId of the student
      "externalSpaceId": "string" // unique externalId of the space
    } 
  ] 
}

 

View all Users in a space

GET /sis/roles/spaces/SPACE_EXTERNALID

This is a mirror of POST operation above

 

200 Response will include this response body:

{ 
  "roles": [ 
    { 
      "role": "student", // or "educator"
      "externalUserId": "string", // unique externalId of the student
      "externalSpaceId": "string" // unique externalId of the space
    } 
  ] 
}

 

Key points to remember when designing your workflows:

  • Aula grants student or educator roles scoped to a particular space. There is no global educator or student role. This allows Aula to be flexible enough to handle use cases like graduate students, where they may be an educator for one space, but a student in another.
  • Multiple create requests using the same external id(s) will result in an upsert if any of the fields (updated last name, for example) differ.
  • Aula’s API is designed to be idempotent. It’s possible to make the same call repeatedly while producing the same result. Specifically, if multiple requests to create or delete a resource are sent to the API, they will be processed and duplicated calls will not be considered to be an error
  • Aula's enrolment API has a rate limit of 5 requests per second and a concurrent request rate of 1 to limit race conditions. Each call's request body can accommodate a batch of up to 100 records. We trust that your scripts or other programs have robust error handling, and can use exponential backoff when a 429 is returned.

See Also

 

Related articles