Centre Resource
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.