Surpass API v2 - Introduction

The Surpass API has been created to provide a way for you to automate how you interact with Surpass. The methods we have available allow an external system to synchronise its candidate, centre and test schedule records and extract important result and report data.

To communicate with the Surpass API all we require is a HTTPS request to the relevant resource. The Surpass API has been built to use Representational State Transfer (REST) and HTTPS based protocols.

Integrating with the Surpass API offers many benefits such as:
  • The ability to automate your internal processes so only one master system has to be updated which removes administration resource.
  • Bulk migrate candidate, centre, and test schedule records to avoid manual input into the Surpass system.
  • Provide certification and statistical analysis externally by extracting all results and reporting information from Surpass.
  • The Surpass API is an open API which allows you to pull and send data when you want; you are not restricted to specific times like overnight jobs.
  • The Surpass API uses common HTTP errors (401…) and methods (GET, POST, PUT, and DELETE) this will provide immediate familiarity with the API and will simplify the process of integrating with the solution.
  • The Surpass API is stateless so all the required information is contained within the request this helps simplify programming by: being able to understand exactly what the request is doing, doesn’t tie the service to a particular server which makes the solution scalable, and you are able to use or recover from failed requests easily.
Surpass Model 

Before utilising the Surpass API and beginning to integrate your organization’s systems with Surpass, It is beneficial to have an understanding of 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 exam 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 API:
Method Description
Centre
GET Retrieve and filter centres in Surpass via the API. Integrate and sync centres with your external system.
POST Create centres in Surpass using this method. Integrate so your external system automatically creates centres in Surpass when they are added to your external system.
PUT Update centre information and associations in Surpass using this method. Integrate so centres in Surpass are automatically updated when changes are made to your external system.
DELETE Remove centres in Surpass using this method. Integrate with Surpass so your external system automatically removes centres when they are deleted from your external system.
Subject
GET Retrieve and filter subjects in Surpass via the API. Integrate and sync subjects with your external system.
POST Creates subjects in Surpass using this method. Integrate with Surpass so your external system automatically creates subjects in Surpass when they are added to your external system.
PUT Update subject information and associations in Surpass using this method. Integrate so subjects in Surpass are automatically updated when changes are made to your external system.
DELETE Remove subjects in Surpass using this method. Integrate with Surpass so your external system automatically removes subjects when they are deleted from your external system.
User
GET Retrieve and filter users in Surpass via the API. Integrate and sync users with your external system.
POST Create users in Surpass using this method. Integrate so your external system automatically creates users in Surpass when they are added to your external system.
PUT Update user information and associations in Surpass using this method. Integrate so users in Surpass are automatically updated when changes are made to your external system.
DELETE Remove users in Surpass using this method. Integrate with Surpass so your external system automatically removes users when they are deleted from your external system.
Candidate
GET Retrieve and filter candidates in Surpass via the API. Integrate and sync candidates with your external system.
POST Create candidates in Surpass using this method. Integrate so your external system automatically creates candidates in Surpass when they are added to your external system.
PUT Update candidate information and associations in Surpass using this method. Integrate so candidates in Surpass are automatically updated when changes are made to your external system.
TestSchedule
POST Schedule tests via the API. This can be synced with an external booking system to automate the scheduling process.
DELETE Delete scheduled tests via the API. This can be synced with an external booking system to automate the scheduling process.
TestSession
GET Retrieve information on a particular candidate Test Session. Integrate so that your external systems can receive detailed information about a candidate's test.
PUT Update a test session state information in Surpass using this method. This can be synced with an external system to automate invigilation processes such as voiding tests.
POST Upload candidate marks and responses for a particular Test Session. Integrate with external systems so that marks and responses to questions can be automatically synced.
Result
GET Extract detailed information regarding candidate's test results. This includes item response and candidate interaction level information and provides away to offer your own certification and track candidates' progress externally.
SummaryResult
GET Extract a summary of candidate test results. This is a lighter response, providing necessary result information. Use this data to provide your own certification and track candidate's progress externally.
Report
GET Extract all Surpass reporting information from the API for external analysis.
Token
GET Generate a Surpass user token specific to the keycode included in the request, the Surpass player can then use this token to integrate with the Surpass internal web service to display the "View Responses" functionality that is available in the 'Audit' screen in Test Administration. This is a permission driven integration method and not exposed in the UI, please contact BTL to discuss the use of this method.
Permission
GET Retrieve a list of all the permission types in Surpass. These permission types can be used with requests to the UserPermission resource to grant users a particular role in Surpass.
UserPermission
GET Retrieve and filter user permissions in Surpass via the API. Integrate and sync user permissions with your external system.
POST Create user permissions in Surpass using this method. Integrate so your external system automatically creates user permissions in Surpass when they are added to your external system.
DELETE Remove user permissions in Surpass using this method. Integrate with Surpass so your external system automatically removes user permissions when they are deleted from your external system.
CentreSubjectAssociation
GET Retrieve and filter the associated centres and subjects in Surpass via the API. Integrate and sync your centre and subject associations with your external system.
POST Create new associations between centres and subjects in Surpass using this method. Integrate so your external system automatically creates these associations in Surpass when they are added to your external system.
PUT Update existing associations between centres and subjects in Surpass using this method. Integrate so these associations in Surpass are automatically updated when changes are made to your external system.
DELETE Remove centre and subject associations in Surpass using this method. Integrate with Surpass so your external system automatically removes these associations when they are deleted from your external system.
TagCategory
GET Search and filter tag categories in Surpass. Use this method to return all attributes for an individual tag category record.
POST Create tag categories in Surpass using this method. Integrate so Surpass automatically creates tag categories when they are added to your external system.
PUT Update tag categories in Surpass using this method. Integrate so tag categories in Surpass automatically updates when they are updated in your external system.
DELETE Remove a tag category in Surpass. Integrate so that when a tag category is removed in your external system, it is deleted in Surpass.
TagGroup
GET Search and filter tag groups in Surpass. You can also use this method to return all attributes for an individual tag group record.
POST Create tag groups in Surpass using this method. Integrate so your external system automatically creates tag groups in Surpass when they are added to your external system.
PUT Update tag groups in Surpass using this method. Integrate so tag groups in Surpass are automatically updated when changes are made to your external system.
TagValue
GET Retrieve and filter tag values in Surpass via the API. Integrate and sync tag values with your external system.
POST Create tag values in Surpass using this method. Integrate so your external system automatically creates tag values in Surpass when they are added to your external system.
PUT Update tag values in Surpass using this method. Integrate so tag values in Surpass are automatically updated when changes are made to your external system.
ItemTagValue
POST Associate tag values to a particular item using this method. Integrate so your items can be updated with tag values using your external system.
DELETE Remove a tag value from an item in Surpass. Integrate so tag values are automatically removed from items when changes are made in your external system.
GET Retrieve all attributes for an individual item tag value record from Surpass, displaying what items have a particular value applied. Integrate with your external system so you can see what items have been tagged with a particular value.
Media
POST Add media to the media library in Surpass using this method. Integrate so your external system automatically adds media in Surpass when they are added to your external system.
Folder
GET Retrieve and filter folders in Surpass via the API, as well as return all attributes for an individual folder record. Integrate and sync folders with your external system.
POST Create folders in Surpass using this method. Integrate so your external system automatically creates folders in Surpass when they are added to your external system.
PUT Update folders in Surpass. Integrate so your external system automatically updates folders in Surpass when they are updated in your external system.
Item
GET Allows to check existing item records in Surpass and to return all attributes for an individual item record. You can also retrieve any information on Assistive Media that has been added. Integrate and sync item information with your external system.
POST Create items in Surpass using this method. Integrate so your external system automatically creates items in Surpass when they are added to your external system.
PUT Update items in Surpass using this method. You can also update Assistive Media on your items. Integrate so items in Surpass are automatically updated when changes are made to your external system.
ItemList
GET Search and filter item lists in Surpass, as well as return items and information regarding an individual item list. Integrate and sync your external system to retrieve information on item lists.
POST Create items in Surpass using this method. Integrate so item lists are automatically created in Surpass when they are created in your external system.
PUT Update an item list in Surpass. Integrate so lists in Surpass are automatically updated when changes are made to your external system.
DELETE Remove an item list from Surpass. Integrate so items are automatically removed from Surpass when changes are made in your external system.
BasicPage
GET Use this method to return attributes for all basic page types (Introduction, Information and Finish pages) in Surpass. You also retrieve information on Assistive Media that has been added to the page. Integrate and sync your external system to retrieve information to item lists.
POST Create basic pages in Surpass using this method. Integrate so your external system automatically creates basic pages in Surpass when they are added to your external system.
PUT Update basic pages in Surpass using this method. Integrate so basic pages in Surpass are automatically updated when changes are made to your external system.
TestProfile
GET Return all attributes for an individual test profile. Integrate and sync test profiles with your external system to retrieve information on test profiles.
POST Create test profiles in Surpass using this method. Integrate so your external system automatically creates test profiles in Surpass when they are added to your external system.
Test
GET Search and filter tests in Surpass, as well as return all settings by Surpass ID. Integrate and sync your tests so you can view all test information in your external system.
POST Create tests in Surpass using this method. Integrate so your external system automatically creates tests in Surpass when they are added to your external system.
AnalyticsResult
GET Extract the latest result information from the reporting screen after statistical analysis and amendments have been applied to candidate results. You are also able to retrieve specific Item Responses for a candidate.
HistoricalResult
GET We keep track of all changes that are applied to results after statistical analysis has been applied, using the historical result resource you are able to extract result information after every change that has been made effectively providing versioned analytics results.
RescoringRule
GET When statistical analysis and amendments have taken place on a test, rescoring rules are applied to analytics results. This resource and method provides the ability to extract information on the changes that were made using the Rescoring functionality.
ScaleScoreMapping
GET This method can be used to find a full scale score mapping that has been applied to a test. The AnalyticsScaleScoreMapping will provide information on a scale score mapping that was provided in Reporting.
ItemSet
GET Search and filter ItemSets in Surpass, as well as return all attributes for an individual Item Set record.
DELETE Remove an item set in Surpass.
POST Create item sets using the Surpass API, you can also pass in the id of items to add to an Item Set, creating a friend relationship between them.
PUT Update item sets in Surpass using this method. The name and what specific items in the set can be updated.
Country/County
GET Search and filter for the list of all counties and countries that are available in Surpass to associate with centres. You can also return individual records for what centres have been associated with specific counties and countries.

Feedback and Knowledge Base