BasicPage Resource

In Surpass, there are three different types of basic pages that can be created for use in your tests. These are introduction pages, information pages and finish pages. Basic pages can be utilised to provide the candidate with additional instructions or materials before, during or after a test delivery.

The Surpass API offers the ability to submit a GET request to return all attributes for an individual basic page, create basic pages via the POST method and update existing basic pages by calling the PUT method.

BasicPage Resource

Below we have listed the operations, http verbs and an example URL for the BasicPage resource within the Surpass API.
Operation HTTP Verb Example URL
Read (Individual by ID) GET
Create POST
Update PUT
Attributes for the BasicPage Resource

Within the table below we have provided all of the attributes included in the BasicPage resource. This includes the attribute name, data type, if the attribute is a unique identifer and if the attribute is mandatory when sending a POST request.
Attribute Name Type Notes Unique Identifier Mandatory for Create (POST)
id int Unable to POST/PUT X N/A
type enum, string Will define if this is an Introduction, Information or Finish page. X
subject Resource ID or Ref can be supplied. X
name string X
htmlText string Allows for HTML formatting
mathMl string Determines whether the main text box is rendered in MathML.
contentType string "RichText" for example
additionalHTMLText string Allows for HTML formatting. This text will appear in the additional information box.
additionalMathMl string Enables the additional information box to be formatted in MathML.
additionalContentType string
folder Resource ID and Position can be supplied.
status enum, string Can be "Draft", "To Review", "Reviewed", "Live" and "Withdrawn".
comment string Adds a new comment to the item.
mediaItems object ID should be supplied. Only one media item accepted.
sourceMaterials object ID should be supplied.
stemComponents collection A collection of text, images or equations that make up the question text. These will be added directly after one another rather than inline. This property is expected to be used rather than questionText. Only text, media or MathML can be supplied in each object, media is not allowed in the first object to follow UI validation.
stemComponents / text HTML Text included in the question stem. Formatting can be applied using HTML.
stemComponents / mathMl MathML Formula can be added to the question stem using this property or returned if this was authored in the user interface. It must be passed in using valid MathML.
stemComponents / media resource Any media embedded into the question stem.
stemComponents / media / id int The id of the media embedded into the question stem. This id relates to the media resource.
allowOpenImageInPopup boolean If the item contains an image, this option will allow the image to be opened in a popup window.
mediaLayout string "AutoSelect", "LeftTitle", "RightTitle".
assistiveMedia object This object refers to assistive media that can be assigned to page text to help provide an alternative method of providing the question text to the candidate e.g. in audio format.
tools object This object refers to Tools that can be associated with a page to help a candidate familiarise themselves before working their way through the test. At current, only a calculator can be used, and choose from 'basic' or 'scientific' to enter in the 'Settings' field.
owner id The user who owns the particular item.
Additional Notes
  • ID is the unique identifier for this resource in the Database. 

GET Request and Return

The GET BasicPage resource can be called directly by browsing to the URL, any required parameters such as $filter, $orderBy, $skip and $top would need to form part of the URL that is sent. Below we have provided examples of JSON and XML responses that would be returned from the Surpass API when requesting the GET method for the BasicPage resource. It is important to remember that the return information will be included within the response object that forms part of the standard GET response; this is detailed in the page understanding the Surpass API.

Example GET request and response (JSON)
Example GET request and response (XML)

POST Request and Return

The POST BasicPage method requires the attributes listed above to be submitted as part of the body of the HTTPS request. This can be submitted in either JSON or XML format, the content-type used will need to be submitted as part of the header of the request. An example of the address, header and body of the request (for both formats) can be found below.

Example POST request and response (JSON)
Example POST request and response (XML)

PUT Request and Return

PUT Requests should reference the ID within the resource. The resource being updated should be included in the body of the request and can be sent in either JSON or XML format. Only the field you want to be updated needs to be included within the request all others can be omitted; these fields will retain their current values. The content-length, content-type and Authorization will also be required in the header of the request. All attributes included in the body of the PUT request are optional if an attribute is omitted it will retain its current value set in the DB.

Example PUT request and response (JSON)
Example PUT request and response (XML)

Required Permissions

To successfully call the BasicPage methods, the user specified in the header of the request must have the "Item Writer", "Item Reviewer" or "Item Publisher" role for the subject specified. The item status that is being set in the request must correspond to the user’s permission.

Feedback and Knowledge Base