Subject Resource

Subjects are the body of questions and content used to compile a test in Surpass. Item authors create questions within Subjects and once these have been quality reviewed and made live these items are built into tests, the tests are then created but also are assigned to subjects so in the hierarchy this is the highest level (Subjects > Tests > Test Forms > Items). It is possible with the Surpass API to retrieve information for a subject as well as create, update and delete them offering an efficient way of automating your processes.

Subject Resource

Below we have listed the operations, HTTP verbs and an example URL for the Subject resource within the Surpass API.
Operation HTTP Verb Example URL
List GET
Filter GET$filter=name eq 'JL Test Subject'
Read (Individual) GET By ID:

By Reference:
Create POST
Update PUT By ID:

By Reference:
Delete DELETE By ID:

By Reference:
Attributes for the Subject Resource

Within the table below we have provided all of the attributes included in the Subject Resource. This includes the attribute name, data type, if the attribute is orderable when requesting the GET method, if the attribute is available to filter when requesting the GET method, and if the attribute is mandatory when creating a Subject. Remember that if an attribute is not mandatory it can be omitted from the body of the POST request.
Attribute Name Type Description Order (GET) Filter (GET) Available Operators (GET) Unique Identifier Mandatory for Create (POST)
id Int The unique identifier for the subject. Unable to POST/PUT. X X eq, gt, it X N/A
reference String The unique subject reference as set in Surpass. If reference is omitted from POST request, Surpass will automatically generate a reference. X X eq, contains X
href String The link to call the Subject Resource. Unable to POST/PUT. N/A
name String The name of the subject. X X eq, contains X
primaryCentre Resource The primary centre assigned to the subject. ID or Ref can be supplied for POST request. X X
deliveryType String The content type of the Subject determining whether the subject is used for the creation of 'OnScreen' or 'OnPaper'.
Default value: OnScreen
x eq
htmlOnly Boolean Determines whether or not the subject created should contain HTML-only content.
Default Value: false
x eq
subjectMasterList Boolean If 'true', creates a 'Subject Master List' for the subject. Subject master lists contain all items within a subject and any items that have been shared with it.

status Enum The status of the subject. Either 'Active', 'ActiveRegistrationClosed' or 'Archived'.
Default value: Active
x eq
Additional Notes
  • ID is the unique identifier for this resource in the Database.
  • Resource reference is the reference allocated to the resource within Surpass. 
  • ID or reference can be used with this resource. 
  • Primary indicates whether the centre specified as part of the POST request will be set as the primary centre allocated to the subject in Surpass. As a default, content can only be delivered to one centre for a subject. However, you can deliver at more than one centre by sharing the subject. 

GET Request and Return

The GET Subject 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 Subject 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 Subject method requires the attributes listed above to be submitted as part of the body of the 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. Depending on how the request was submitted the response will be returned in either JSON or XML format. If the call was unsuccessful then you will receive an error message; all error messages available in the Surpass API can be found here.

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

PUT Request and Return

PUT Requests should reference the ID or Reference 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.

Example PUT request & response (JSON & XML)

DELETE Request and Return

DELETE Requests should use the ID or Reference of the Subject you want to delete. Successful deletes will return a status of 200 and will return the base resource with all values set to null. It is only possible to delete ‘archived’ subjects. Attempting to delete an ‘active’ subject will return and error. An example of the DELETE Subject request has been provided below:

Using ID

Using Reference

Required Permissions

To successfully call the Subject methods, the user specified in the header of the request must have the 'Manage Subjects' permission in Surpass.

Feedback and Knowledge Base