Accounts

An endpoint to provide for remote account administration. You can interact with this API via Swagger at https://global.royalabc.com/thirdparty/swagger/index.html

Note

This API requires a valid access token. Please see Authentication for more information.

All requests are made to the following endpoint https://global.royalabc.com/thirdparty/accounts

PUT - Enrol

PUT https://global.royalabc.com/thirdparty/accounts

Creates a new account in the RoyalABC system and adds it to any School or Class that you specify. If the account already exists, it will be added to the School or Class that you specify. If the class or school does not exist, it will be created with the details you provide in the Request.

All Students and Teachers created as part of this API consume licences from the School Group's licence pool. To manage the number of licences available to a given school group please use the Admin Portal at https://admin.royalabc.com

Headers

• Authorization - string. The access token obtained from the OAuth server. This must be a valid access token for the ThirdPartyApi scope. The access token must be placed after Bearer in the value string.
• Content-Type - string. The content type of the request body. This must be application/json.

Request Body

Endpoints accepts an EnrolRequest object in JSON format with the following properties

• account - Account. The account to enrol.
• schoolGroupId - string. The ID of the school group to enrol the account in, it must be provided if a SchoolGroupName is not provided.
• schoolGroupName - string. The name of the school group to enrol the account in, it must be provided if a SchoolGroupId is not provided.
• schoolId - string. The ID of the school to enrol the account in, optional.
• schoolName - string. The name of the school to enrol the account in, optional.
• classId - string. The ID of the class to enrol the account in, optional.
• className - string. The name of the class to enrol the account in, optional.

Note

If you don't provide a 'SchoolId' or 'SchoolName' then the account will be enrolled into a new School under the School Group you specify with a name based on the School Group. If you don't provide a 'ClassId' or 'ClassName' then the account will be enrolled into a new class with a name based on the School Group, but will consume a license.

Note

Student accounts can only be enrolled into a single class. Upon every Enrol request for a student, we un-enrol the student from any other classes. And re-enrol them into the class specified in the request (which may be a new class if one isn't specified). Teacher accounts can be enrolled into multiple classes, currently there is no method to un-enrol them.

Warning

API PERFORMANCE: If you don't specify Ids in requests to the API where possible, the API will have to search for the Ids using the names you provide. If performance is a priority for you, please use Ids where possible.

An Account object has the following properties:

• accountId - UUID. The ID of the account, this is optional and will be generated if not provided. This must be a valid UUID.
• role - string. The role of the account, this must be either Student or Teacher.
• email - string. The email address of the account, this must be unique. Optional for Students, mandatory for Teachers as it is their username.
• name - string. The name of the account, preferably an English name if the account is a student, a student's username is derived from this name.
• localizedName - string. The name of the account in their own language, optional.

Example

Creating a Teacher, where a School Group and School are provided by name, and a Class is provided by ID:

{
  "account": {
    "accountId": "be62ad87-b447-4fe3-a29d-b0de8887f1ab",
    "role": "Teacher",
    "email": "bill_the_teacher_guy@prospereducation.com",
    "name": "Bill Teacher"
  },
  "schoolName": "API Test Users",
  "schoolGroupName": "Prosper Education",
  "classId": "99b0fe6e-3f1e-41ea-9981-2cbb35a0eecd"
}

Creating a Student, where a School Group and School are provided by ID and no class is specified, so one will be made with a randomised name:

{
  "account": {
    "accountId": "0f65b675-c962-455c-825d-9abdda3b4d91",
    "role": "Student",
    "name": "Connor Lee",
    "localizedName": "Lee Su Tsung"
  },
  "schoolId": "4fa8ca23-b813-4ec8-a19b-128a4c018b76",
  "schoolGroupName": "ae42c1ad-90f1-4244-81ba-ad6d02d56a0c"
}

Response Body

The API will respond with an APIResult object. If the request was successful, the result property will contain a EnrolResponse Json Object

An EnrolResponse object has the following properties:

• teacher - AccountCreated. The teacher account that was created, if the account is a teacher.
• student - AccountCreated. The student account that was created, if the account is a student.
• hierarchy - Array of HierarchyMembers. The hierarchy of the account after the enrolment.
• remarks - String. Any remarks about the enrolment, such as if a class was created, a student was un-enrolled from a class, etc.

An AccountCreated object has the following properties:

• account - Account. The account that was created, this will be either a teacher or a student.
• password - string. The password of the account, if the account is a teacher this is a temporary password that must be changed on first login. If the account is a student, this will be an immutable passkey that can be used to login to the RoyalABC World app and retrieved by teachers in the Classroom app.

An Account object has the following properties:

• id - UUID. The ID of the account.
• role - string. The role of the account, this will be either Student or Teacher.
• userName - string. The username of the account, this will be the email address of the account if the account is a teacher, or a username derived from the account's name if the account is a student.
• name - string. The name of the account owner.
• email - string. The email address of the account, this will be null if no email address was provided.
• localizedName - string. The name of the account owner in their own language, only returned for Students.
• createdAt - DateTime. The date and time the account was created.

A HierarchyMember object has the following properties:

• level - string. The level of the hierarchy member, this will be either Distributor, SchoolGroup, School or Class.
• levelId - string. The ID of the level of the hierarchy member. So the DistributorId, SchoolGroupId, SchoolId or ClassId.
• name - string. The name of the level of the hierarchy member. So the name of the Distributor, SchoolGroup, School or Class.

If the request was unsuccessful, the error property will contain a string containing the error message and success will be false.

Example

An example of a Student being created:

{
  "result": {
    "hierarchy": [
      {
        "level": "Class",
        "name": "Class 2A",
        "levelId": "6eb22cf2-6ff0-4204-8a27-0d7b397d31cf"
      },
      {
        "level": "School",
        "name": "API Test Users",
        "levelId": "aa7307d0-ac60-492e-b876-676d0b812839"
      },
      {
        "level": "SchoolGroup",
        "name": "Prosper Education",
        "levelId": "64ad3659-0530-4996-bc3e-d206e602d8ac"
      },
      {
        "level": "Distributor",
        "name": "Prosper Distribution Co. Ltd.",
        "levelId": "0b1bec7f-c204-47d0-97e6-468239d44f75"
      }
    ],
    "student": {
      "account": {
        "id": "d4a2e612-e19a-40b8-bb77-add23481cd7d",
        "role": "Student",
        "userName": "connor",
        "name": "Connor",
        "localizedName": "Lee Su Tsung",
        "email": null,
        "createdAt": "0001-01-01T00:00:00"
      },
      "password": "vvy7bd"
    },
    "teacher": null,
    "remarks": "Created student 'connor' - Enrolled into School 'API Test Users' - Created Class 'Class 2A' - Enrolled into Class 'Class 2A'"
  },
  "error": null,
  "success": true,
  "requestID": "df0b2287-5cbc-4579-a24b-f661f1013b22"
}

An example of where a Teacher was created:

{
  "result": {
    "hierarchy": [
      {
        "level": "Class",
        "name": "Class 2A",
        "levelId": "6eb22cf2-6ff0-4204-8a27-0d7b397d31cf"
      },
      {
        "level": "School",
        "name": "API Test Users",
        "levelId": "aa7307d0-ac60-492e-b876-676d0b812839"
      },
      {
        "level": "SchoolGroup",
        "name": "Prosper Education",
        "levelId": "64ad3659-0530-4996-bc3e-d206e602d8ac"
      },
      {
        "level": "Distributor",
        "name": "Prosper Distribution Co. Ltd.",
        "levelId": "0b1bec7f-c204-47d0-97e6-468239d44f75"
      }
    ],
    "student": null,
    "teacher": {
      "account": {
        "id": "be62ad87-b447-4fe3-a29d-b0de8887f1ab",
        "role": "Teacher",
        "userName": "bill_the_teacher_guy@prospereducation.com",
        "name": "Bill Teacher",
        "createdAt": "2023-11-02T06:21:20.3612496Z"
      },
      "password": "dSR6MHU3"
    }
  },
  "error": null,
  "success": true,
  "requestID": "191cf7df-76ea-47ef-81dc-167f2ae5e7a7"
}

GET - List

GET https://global.royalabc.com/thirdparty/accounts

Gets a paginated list of accounts that match the given search criteria. Accounts can be either Students or Teachers. If no search criteria is provided, the API will return all accounts you have access to.

Headers

• Authorization - string. The access token obtained from the OAuth server. This must be a valid access token for the ThirdPartyApi scope. The access token must be placed after Bearer in the value string.

Request Parameters

• role - string. The RoleType of the accounts to list, this is an optional parameter. If not provided, the default is Student. Accepted values are 'Teacher' or 'Student'.
• schoolGroupId - string. The ID of the school group to list accounts for, this is an optional parameter. If not provided, the default is all school groups.
• schoolGroupName - string. The name of the school group to list accounts for, this is an optional parameter, and is ignored if schoolGroupId is provided. If not provided, the default is all school groups.
• schoolId - string. The ID of the school to list accounts for, this is an optional parameter. If not provided, the default is all schools.
• schoolName - string. The name of the school to list accounts for, this is an optional parameter, and is ignored if schoolId is provided. If not provided, the default is all schools.
• classId - string. The ID of the class to list accounts for, this is an optional parameter. If not provided, the default is all classes.
• className - string. The name of the class to list accounts for, this is an optional parameter, and is ignored if classId is provided. If not provided, the default is all classes.
• page - int. The page number to return, 0-indexed, this is an optional parameter. If not provided, the default is 0.
• pageSize - int. The number of accounts to return per page, this is an optional parameter. If not provided, the default is 20.
• search - string. A search string to filter accounts by, this is an optional parameter. If not provided, the default is all accounts. The search string filters the following fields using a simple 'starts with' function: 'userName', 'name', 'email', 'localizedName'.
• sortType - string. The SortType to sort the accounts by, this is an optional parameter. If not provided, the default is 'Ascending'. Accepts either 'Ascending' or 'Descending'. The Name field is used for sorting.
• hidden - boolean. If true, it will only return accounts that have been hidden, if false, it will only return accounts that have not been hidden. If not provided, the default is false.

Warning

API PERFORMANCE: If you don't specify Ids in requests to the API where possible, the API will have to search for the Ids using the names you provide. If performance is a priority for you, please use Ids where possible.

Response Body

The API will respond with a APIResult object. If the request was successful, the result property will contain a PagedList Json Object

A PagedList object has the following properties:

• result - Array of Accounts, either teachers or students.
• pageIndex - int. The page number of the results.
• pageCount - int. The number of pages.

See the Enrol endpoint for a description of the Account object.

Example

For the request GET https://global.royalabc.com/thirdparty/Accounts?role=Student&schoolName=API%20Test%20Users&className=Class%202&page=0&pageSize=20&search=Con&hidden=false the response would be:

{
  "result": {
    "result": [
      {
        "accountId": "0f65b675-c962-455c-825d-9abdda3b4d91",
        "role": "Student",
        "name": "Connor Lee",
        "localizedName": "Lee Su Tsung"
      },
      {
        "accountId": "e5f0ade2-b05a-48fc-ba8a-560172dc7ecf",
        "role": "Student",
        "name": "Constance Andrews",
        "localizedName": "Constance Andrews"
      }
    ],
    "pageIndex": 0,
    "pageCount": 1
  },
  "error": null,
  "success": true,
  "requestID": "df0b2287-5cbc-4579-a24b-f661f1013b22"
}

GET - Describe

GET https://global.royalabc.com/thirdparty/accounts/{accountId}

Gets a detailed breakdown of the given account as if it were a Student. This breakdown includes the Learning statistics, Engagement statistics and any events that have been recorded for the account in the time period specified in the request (defaults to last 7 days). The response will also include the account's hierarchy. Most of this data is the same as what is provided in the Student Report, you can generate a student report for an account by going to the following URL https://global.royalabc.com/reports/student/{accountId}.

Both Teachers and Students are able to login and participate in the World app, so this endpoint can be used for both account types.

Headers

• Authorization - string. The access token obtained from the OAuth server. This must be a valid access token for the ThirdPartyApi scope. The access token must be placed after Bearer in the value string.

Request Parameters

• accountId - string. The ID of the account to describe, this is a required parameter.
• start - DateTime. The start date and time of the time period to get events for, this is an optional parameter. If not provided, the default is 7 days ago.
• end - DateTime. The end date and time of the time period to get events for, this is an optional parameter. If not provided, the default is now.

Response Body

The API will respond with a APIResult object. If the request was successful, the result property will contain a DescribeResponse Json Object

A DescribeResponse object has the following properties:

• accountDetails - StudentReportModel. The detailed breakdown of the account. This is the same model that is used to generate a student report.
• hierarchy - Array of HierarchyMembers. The hierarchy of the account.

A StudentReportModel object has the following properties:

• accountId - UUID. The ID of the account.
• userName - string. The username of the account.
• name - string. The name of the account owner.
• email - string. The email address of the account if available.
• end - DateTime. The end date and time of the time period the report covers.
• start - DateTime. The start date and time of the time period the report covers.
• learning - StudentLearningStats. The learning statistics for the account.
• engagement - StudentEngagementStats. The engagement statistics for the account.
• eventsStats - EventsStats. The events that have been recorded for the account in the time period specified in the request.

A StudentLearningStats object has the following properties:

• vocabs - Array of VocabStats. The vocabulary statistics for the account, broken down by Vocab and Learning Category.
• progression - Array of ProgressionLevelStats. Breaks down the learning data by Progression Level, students progress through the World application by completing levels, this is a measure of how far through the application the student has progressed.
• totalLearningMastery - float. A single value that represents the total learning mastery of the account, between 0 and 1. Only takes into account vocabulary the student has been exposed to in the World.

Learning Data in RoyalABC is stored uniquely for each pair of Word and Learning Category. So if a student has been exposed to the same word in both categories, there will be two entries in the vocabs array.

A VocabStats object has the following properties:

• documentId - string. The ID of the Vocab, most likely a UUID but not guaranteed.
• word - The english representation of the Vocab. It will be in the same culture as the student's account, so a US student will see the US English version of the word (color), and a UK student will see the UK English version of the word (colour).
• category - enum. The learning category of the Vocab, this will be either ReadUnderstandWord or ListenUnderstandWord.
• timesExposedWorld - int. The number of times the student has been exposed to the Vocab in the World app.
• timesCorrect - int. The number of times the student has answered correctly when exposed to the Vocab in the World app.
• timesIncorrect - int. The number of times the student has answered incorrectly when exposed to the Vocab in the World app.

A ProgressionLevelStats object has the following properties:

• name - string. The name of the Progression Level.
• shortName - string. The short name of the Progression Level (e.g. A1).
• totalLearningElements - int. The total number of learning elements in the Progression Level.
• learningElementsMastered - int. The number of learning elements in the Progression Level that the student has mastered. Mastery is defined as getting a Vocab correct 3 times in a row, in both learning categories.

A StudentEngagementStats object has the following properties:

• totalLessons - int. The total number of lessons the student's class has been taught in the time period specified in the request.
• lessonsAttended - int. The total number of lessons the student has attended in the time period specified in the request.
• lessonsNotAttended - int. The total number of lessons the student has not attended in the time period specified in the request.
• lessonsPresumedAttended - int. The difference between totalLessons and lessonsNotAttended, this presumes users who skip roll call are counting all students as present.
• logins - int. The total number of times the student has logged into the World app in the time period specified in the request. Logging in is defined as opening the application and loading into the menu.
• learningJourneysCompleted - int. The total number of learning journeys the student has completed in the time period specified in the request.
• minutesInWorld - int. The total number of minutes the student has spent in the World app in the time period specified in the request.
• objectInteractions - int. The total number of object interactions the student has performed in the World app in the time period specified in the request.
• activitiesCompleted - int. The total number of activities the student has completed in the World app in the time period specified in the request.

An EventsStats object has the following properties:

• events - Array of Event. The events that have been recorded for the account in the time period specified in the request.

An Event object has the following properties:

• at - DateTime. The date and time the event occurred.
• type - Enum, ReportEventType. Either Lesson, LearningJourney or Login.

Example

For the request GET https://global.royalabc.com/thirdparty/accounts/00000000-0000-0000-0000-000000000000?start=2023-10-31T06:00:05.0774763Z&end=2023-11-07T06:00:05.0774763Z the response would be:

{
  "result": {
    "accountDetails": {
      "accountId": "00000000-0000-0000-0000-000000000000",
      "engagement": {
        "totalLessons": 13,
        "lessonsAttended": 13,
        "lessonsNotAttended": 0,
        "lessonsPresumedAttended": 13,
        "logins": 4,
        "learningJourneysCompleted": 0,
        "minutesInWorld": 24,
        "objectInteractions": 13,
        "activitiesCompleted": 8
      },
      "learning": {
        "vocabs": [
          {
            "documentId": "605586ff-c0be-45ee-9a95-5501246baee0",
            "word": "Mei",
            "category": "ListenUnderstandWord",
            "timesExposedWorld": 1,
            "timesCorrect": 1,
            "timesIncorrect": 0
          },
          {
            "documentId": "15a4ad54-8e90-41ac-9933-b546e8ecf29f",
            "word": "Rusty",
            "category": "ListenUnderstandWord",
            "timesExposedWorld": 1,
            "timesCorrect": 0,
            "timesIncorrect": 1
          }
        ],
        "progression": [
          {
            "name": "Starters A",
            "shortName": "SA",
            "totalLearningElements": 67,
            "learningElementsMastered": 65
          },
          {
            "name": "Starters B",
            "shortName": "SB",
            "totalLearningElements": 80,
            "learningElementsMastered": 19
          }
        ],
        "totalLearningMastery": 1
      },
      "events": {
        "events":  [
          {
            "at": "2023-11-01T04:04:51.679631",
            "type": "Lesson"
          },
          {
            "at": "2023-11-01T01:01:03.173994",
            "type": "Login"
          }
        ]
      },
      "createdAt": "2023-11-07T06:00:05.0774776Z",
      "from": "2023-10-31T06:00:05.0774763Z",
      "userName": "connor",
      "fullName": "Connor",
      "email": null,
      "durationInDays": 7
    },
    "hierarchy": [
      {
        "level": "Class",
        "name": "Class 2A",
        "levelId": "6eb22cf2-6ff0-4204-8a27-0d7b397d31cf"
      },
      {
        "level": "School",
        "name": "API Test Users",
        "levelId": "aa7307d0-ac60-492e-b876-676d0b812839"
      },
      {
        "level": "SchoolGroup",
        "name": "Prosper Education",
        "levelId": "64ad3659-0530-4996-bc3e-d206e602d8ac"
      },
      {
        "level": "Distributor",
        "name": "Prosper Distribution Co. Ltd.",
        "levelId": "0b1bec7f-c204-47d0-97e6-468239d44f75"
      },
      {
        "level": "Global",
        "name": "RoyalABC",
        "levelId": "ffffffff-ffff-ffff-ffff-ffffffffffff"
      }
    ]
  },
  "error": null,
  "success": true,
  "requestID": "4ffd34ff-0279-4cc9-8296-8651eca74269"
}

DELETE - Hide

DELETE https://global.royalabc.com/thirdparty/accounts/{accountId}

Deletes a given account. This is a soft delete, the account will be hidden and the account will no longer be able to login to the World or Classroom apps. The account will still be visible in the Admin Portal and in the API, provided you filter for hidden accounts.

The account is recoverable, see the Recover endpoint for more information.

Warning

When an account is hidden, it's username is freed up for use by another account. This can make a teacher account unrecoverable if the email address used as their username is reused. Student recovery can still occur, though their username will be regenerated in the case of a collision.

Headers

• Authorization - string. The access token obtained from the OAuth server. This must be a valid access token for the ThirdPartyApi scope. The access token must be placed after Bearer in the value string.

Request Parameters

• accountId - string. The ID of the account to hide, this is a required parameter.

Response Body

The API will respond with an APIResult object denoting whether the request was successful or not.

Example

For the request DELETE https://global.royalabc.com/thirdparty/accounts/00000000-0000-0000-0000-000000000000 the response would be:

{
  "result": null,
  "error": null,
  "success": true,
  "requestID": "4ffd34ff-0279-4cc9-8296-8651eca74269"
}

POST - Recover

POST https://global.royalabc.com/thirdparty/accounts/{accountId}/recover

Recovers a given account that has previously be hidden. This will restore the account to the state it was in before it was hidden, but there is a few scenarios where recovery is not possible.

• If the account was a teacher and the email address used as their username has been reused by another account, the account cannot be recovered.
• If the account was a student and the username generated from their name has been reused by another account, and the parameter forceOldUsername is set to true, the account cannot be recovered.
• If the School Group the account belongs to has no licences available, the account cannot be recovered.

Headers

• Authorization - string. The access token obtained from the OAuth server. This must be a valid access token for the ThirdPartyApi scope. The access token must be placed after Bearer in the value string.

Request Parameters

• accountId - string. The ID of the account to recover, this is a required parameter.
• forceOldUsername - boolean. If true, the account will be recovered with the same username it had before it was hidden. If false, the account will be recovered with a new username. This is an optional parameter, if not provided, the default is false.

Response Body

If the account is successfully recovered, the API will respond with an 'APIResult' object with a Teacher or Student account in the result property. If the account cannot be recovered, the API will respond with an 'APIResult' object with an error message in the error property.

Example

For the request POST https://global.royalabc.com/thirdparty/accounts/00000000-0000-0000-0000-000000000000/recover the response would be:

{
  "result": {
    "id": "00000000-0000-0000-0000-000000000000",
    "role": "Student",
    "userName": "connor5",
    "name": "Connor",
    "createdAt": "2023-11-07T06:00:05.0774776Z"
  },
  "error": null,
  "success": true,
  "requestID": "4ffd34ff-0279-4cc9-8296-8651eca74269"
}

Please note that the username of the account has changed from 'connor' to 'connor5' as the username 'connor' was reused by another account.

Troubleshooting

'Invalid API User'

You don't have permission to access this API. Please contact us if you believe this is an error.

'Account not found'

The account does not exist in our system. Please ensure that the account ID is correct.

'School / School Group Not Found'

You must specify a valid school group when enrolling an account. Please ensure that the school group ID or name is correct and that you have permission to access it.

'Failed to create a new prosper account'

The account could not be created. Make sure you are not reusing an account ID, and that the account ID is a valid UUID.

'Not enough schoolgroup licences available to allocate'

The school group does not have enough licences available to enrol the account. Please ensure that the school group has enough licences available.