Centre Resource

Centres might be defined as the faculty or department, or it might be a delivery centre where candidates go to sit tests; this depends on how you have setup your Surpass solution. Subjects, candidates and users can all be associated to a centre, however centres currently only store name, reference and certain configuration settings within Surpass; associations are made at the subject, candidate and user level.  

Centre Resource

Below we have listed the operations, http verbs and an example URL for the Centre resource within the Surpass API. 

Operation HTTP Verb Example URL
Search and Filter GET https://...surpass.com/api/v2/Centre?$filter=contains(name,'test')
Read (individual) GET https://...surpass.com/api/v2/Centre/1
https://...surpass.com/api/v2/Centre?reference=CENTREREF
Create POST https://...surpass.com/api/v2/Centre/
Update PUT https://...surpass.com/api/v2/Centre/1
https://...surpass.com/api/v2/Centre?reference=CENTREREF
Remove DELETE https://...surpass.com/api/v2/Centre/1

Attributes for the Centre Resource

Within the table below we have provided all of the attributes included in the centre 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 candidate. Remember that if an attribute is not mandatory it can be omitted from the body of the POST request.  

Property Name Type Description Order
(GET)
Filter
(GET)
Available Operators
(GET)
Default Value
(POST)
Mandatory for
create (POST)
id int The unique identifier for the centre.
Unable to POST/PUT
x x eq, lt, gt n/a
reference string
30 chars
The reference assigned to the centre x x eq, contains auto generated
href string The unique URL for the centre. n/a
name string
80 chars
The centre name, this does not have to be unique x x eq, contains n/a X
randomiseTestForms boolean When tests are being scheduled for this centre randomised test forms will be selected. x eq true
hideSubjectsIncludedInSubjectGroups boolean Prevents subjects that are included in a subject group from appearing as selectable subjects in Test Creation x eq false
excludeItemStatistics boolean If statistics are being excluded for a centre any tests delivered to this centre will not affect statistics in the reporting screen. x eq false
addressLine1 string
100 chars
The address of the centre

null
addressLine2 string
100 chars
Any additional centre address details required

null
town string
100 chars
The town the centre is based in

null
county resource The county the centre is based in, this is a resource in the surpass API and requires an ID which can be found by requesting the GET county method. 

null
postCode string
12 chars
The postcode for the centre

null
country resource The country the centre is based in, this is a resource in the surpass API and requires an ID which can be found by requesting the GET county method.  


null
status enumeration If statistics are being excluded for a centre any tests delivered to this centre will not affect statistics in the reporting screen.
Available values: Active | Retired 


Active

Additional Notes

  • randomiseTestForms will enforce randomised test forms when a test is being scheduled by users with the relevant permissions as opposed to the user manually selecting a test form to schedule.

  • hideSubjectsIncludedInSubjectGroups will prevent any subjects that are included in a Subject Group from appearing as a selectable subject in Test Creation.


GET Request and Return

The GET Centre 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 Centre 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 & response (JSON)

Example GET request & response (XML)


POST Request and Return

The POST Centre 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.

The body of the request should be formed in the same way as the POST request and the response also returns the same information. An example of this can be found in the “POST Request and Return” section above.


DELETE Request and Return

DELETE Requests should use the ID or Reference of the Centre you want to delete. Successful deletes will return a status of 200 and will return the base resource with all values set to null. An example of the DELETE centre request has been provided below:

DELETE https://...surpass.com/api/v2/Centre/1


Required Permissions

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


Feedback and Knowledge Base