The Surpass OAPI has been created to improve the way you automate interaction with Surpass. It supports some features of the API v2 as well as some additional functionality. The OAPI significantly improves the performance of the Surpass API and is built on the latest .Net Core technologies and adopts the OpenAPI specification (https://www.openapis.org/about).
Note: The Surpass OAPI is new and still under development, therefore the resources currently available are limited. To start using the OAPI, please contact your BTL Account Manager.
Integrating with the Surpass OAPI offers many benefits, including:
- Improved performance
- Automatically generated documentation using
- More control and flexibility with queries
Some features exclusive to the OAPI include the ability to specifically POST multiple choice, multiple response, either/or and essay question types; create and manage tag collections; alter item positions in item sets; and POST tag groups against an item in bulk. The 'Item Search' and 'Item Lists' tabs within 'Item Authoring' are also supported by the Surpass OAPI.
Note: If you are migrating content into Surpass from external systems using the OAPI, you must ensure any HTML is valid to prevent any issues.
Before utilising the Surpass OAPI and beginning to integrate your organization’s systems with Surpass, it is beneficial to understand the way Surpass works and how the entities all relate to one another.
These core entities are:
Centres – A centre refers to the place where a test is taken, e.g. a school or college. A centre needs to be available before any subjects, users or candidates can be created, as these all need to be associated with a centre.
Subjects – A subject is where multiple users collaborate in order to create the questions and content to compile a test in Surpass. Subjects are shared with centres and permissions can be defined to allow users to work on the subject.
Users – A user is a person who interacts with Surpass day to day. Users vary from site administrators to question authors to invigilators. Permissions can be assigned at a site, centre and subject level, and the users’ role is determined by what permissions are granted to them.
Candidates – Candidates are the students or learners that take tests within the system and only see the Surpass delivery engine in the end-to-end test delivery process. Candidates should be associated with the centres and subjects which are relevant to them. They will only be eligible to take tests under associated subjects and at associated centres.
Further information on the basics of Surpass can be found in the ‘Before you begin’ section of the Surpass Knowledge Base.
Below is a list of the resources and methods that are available within the Surpass OAPI:
|GET||Check existing analytics records in Surpass and return attributes for multiple candidate keycodes.
|GET||Check existing item records in
Surpass and return all attributes for an individual item record. You can also retrieve individual versions of items.
|DELETE||Delete existing item records in Surpass.|
|POST||Create items in Surpass using this method. You can also specifically create multiple choice, multiple response, either/or and essay question types.|
|PUT (Essay questions)
||Update existing essay questions in Surpass.
|PUT||Update tag values and enemy relationships in Surpass using this method.|
|POST||Create item sets using the Surpass OAPI.|
|PUT||Update item sets in Surpass using this method. The name and what specific items are in the set can be updated.|
|GET||Retrieve OAPI authentication settings.
|PUT||Update OAPI authentication settings.
|POST||Create a tag collection and define the order of tag groups in the tag collection.
|POST (Bulk)||Create up to 100 tag collections and define the order of tag groups in tag collections.
|GET||Check existing tag collection records in Surpass and to return all attributes for an individual tag collection.
|PUT||Edit the order of tag groups in a tag collection. The name and specific tag values/subcollections in the collection can also be edited.|
|PUT (Bulk)||Edit up to 100 tag collections and define the order of tag groups in tag collections.|
|DELETE||Delete tag collections in Surpass.|
|POST||Create a tag collection group and define the order of tag groups in the tag collection group.
|PUT||Edit a tag collection group and define the order of tag groups in the tag collection group.|
|GET||Retrieve a tag collection group and view the order of tag groups in the tag collection group.|
|DELETE||Delete a tag collection group.|
|POST||Create tag groups in
|GET||Check existing tag group records in Surpass and return all attributes for an individual tag group.|
|PUT||Update tag groups in
Surpass using this method. The name and specifc tag values in teh tag group can be updated.
|DELETE||Delete tag collection groups in Surpass.|