Centre API
In Surpass, a “centre” is a virtual space in which tests are created by users and delivered to candidates. All items, users, candidates, subjects, tests, and test forms are associated with a particular parent centre. A Surpass centre may be linked to a physical location like a school or workplace or it can be a purely digital environment.
The Centre API resource is used to list, retrieve, create, and update centres.
This article explains what calls can be made to the Surpass API using the Centre resource.
Import this API into your Postman Workspace
In This Article
Listing centres
Send a request to the endpoint to retrieve a list of centres. Refer to the available parameters to influence the response. No request body is required.
Parameters
Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ? after any path parameters.
|
Name |
Parameter |
Input |
Description |
|---|---|---|---|
|
authorization |
header MANDATORY |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
|
top |
query OPTIONAL |
/api/v2/Centre?$top={top} |
Defines number of responses to return when paging a response, where {top} is a number between 1 and 40. |
|
skip |
query OPTIONAL |
/api/v2/Centre?$skip={skip} |
Defines how many responses to skip when paging a response, where {skip} is a number that should not exceed the total number of responses. |
|
filter |
query OPTIONAL |
/api/v2/Centre?$filter={filter} {operator} {value} |
Filters results, searching either for an exact match or for the data to contain a defined value. For an exact match: {filter} is one of id, reference, name, randomiseTestForms, hideSubjectsIncludedInSubjectGroups, excludeItemStatistics; {operator} is eq (equal to); and {value} is the string, integer or Boolean the filter query looks for an exact match for in the request. For a greater than query: {filter} is id, {operator} is ge (greater than), and {value} is the integer the filter looks for more than in the request. For a less than query: {filter} is id, {operator} is le (less than), and {value} is the integer the filter looks for less than in the request. For a contains query: {filter} is contains({attribute}, '{value}'), where {attribute} is one of reference, name; and {value} is the string or integer the filter query looks for the data to contain in the request. |
|
orderBy |
query OPTIONAL |
/api/v2/Centre?$orderBy={attribute} |
Determines order of results, where {attribute} is one of id, reference, name. |
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the information in either JSON or XML format as requested.
{
"count": 100,
"top": 10,
"skip": 0,
"pageCount": 10,
"nextPageLink": "https://{your Surpass instance}.com:443/api/v2/Centre?$top=10&$skip=10",
"prevPageLink": null,
"response": [
{
"id": 1,
"reference": "Centre1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Centre/1"
},
{
"id": 2,
"reference": "Centre2",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Centre/2"
},
{
"id": 3,
"reference": "Centre3",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Centre/3"
},
{
"id": 4,
"reference": "Centre4",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Centre/4"
},
{
"id": 5,
"reference": "Centre5",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Centre/5"
},
{
"id": 6,
"reference": "Centre6",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Centre/6"
},
{
"id": 7,
"reference": "Centre7",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Centre/7"
},
{
"id": 8,
"reference": "Centre8",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Centre/8"
},
{
"id": 9,
"reference": "Centre9",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Centre/9"
},
{
"id": 10,
"reference": "Centre10",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Centre/10"
}
],
"errors": null,
"serverTimeZone": "GMT Standard Time"
}Response schema
The response schema contains a description of every property that can be returned for this endpoint.
count integer
Details how many centres there are in total.
top integer
Details number of centres returned in the response.
skip integer
Details how many centres were skipped to display those in the response.
pageCount integer
Details how many pages of centres there are.
nextPageLink string
The endpoint to call the next page of centres. If null, the response is the last page of centres.
prevPageLink string
The endpoint to call the previous page of centres. If null, the response is the first page of centres.
response array
Contains the rest of the response.
id integer
The centre’s unique identifier.
reference string
The centre’s unique reference code.
href string
The endpoint to call the centre’s information, such as /api/v2/Centre/{id} where {id} is the centre’s unique identifier.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Retrieving centre information
Send a request to the endpoint to retrieve information for a specific centre using either its ID or reference. No request body is required.
Parameters
Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ? after any path parameters.
|
Name |
Parameter |
Input |
Description |
|---|---|---|---|
|
authorization |
header MANDATORY |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
|
id |
path OPTIONAL |
/api/v2/Centre/{id} |
Returns information for the specified centre, where {id} is the centre’s unique identifier. |
|
reference |
query OPTIONAL |
/api/v2/Centre?reference={reference} |
Returns information for the specified centre, where {reference} is the centre’s unique reference code. |
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the information in either JSON or XML format as requested.
{
"count": null,
"top": null,
"skip": null,
"pageCount": null,
"nextPageLink": null,
"prevPageLink": null,
"response": [
{
"id": 1,
"reference": "Centre1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Centre/1",
"name": "Surpass Centre",
"randomiseTestForms": true,
"hideSubjectsIncludedInSubjectGroups": false,
"excludeItemStatistics": false,
"addressLine1": "Street",
"addressLine2": "Locality",
"town": "Town",
"county": {
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/County/1",
"name": "Greater London"
},
"postCode": "Postcode",
"country": {
"id": 0,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Country/0",
"name": "England"
},
"status": "Active"
}
],
"errors": null,
"serverTimeZone": "GMT Standard Time"
}Response schema
The response schema contains a description of every property that can be returned for this endpoint.
count integer
Details how many centres there are in total. This is null because the information retrieved is for a specific centre.
top integer
Details number of centres returned in the response. This is null because the information retrieved is for a specific centre.
skip integer
Details how many centres were skipped to display those in the response. This is null because the information retrieved is for a specific centre.
pageCount integer
Details how many pages of centres there are. This is null because the information retrieved is for a specific centre.
nextPageLink string
The endpoint to call the next page of centres. This is null because the information retrieved is for a specific centre.
prevPageLink string
The endpoint to call the previous page of centres. This is null because the information retrieved is for a specific centre.
response array
Contains the rest of the response.
id integer
The centre’s unique identifier.
reference string
The centre’s unique reference code.
href string
The endpoint to call the centre’s information, such as /api/v2/Centre/{id} where {id} is the centre’s unique identifier.
name string
The centre’s name.
randomiseTestForms boolean
Enforces the random allocation of test forms to candidates.
hideSubjectsIncludedInSubjectGroups boolean
Determines whether subjects in subject groups are available for selection in Test Creation. If set to true, tests are prevented from being created in subject group subjects.
excludeItemStatistics boolean
Determines whether data from this centre is included in the Reporting screens. If set to true, this centre’s data is prevented from appearing in Reporting. This is useful for centres running practice, pilot, or quality review tests.
addressLine1 string
The centre’s first line of address.
addressLine2 string
The centre’s second line of address.
town string
The centre’s town.
county object
The centre’s county.
county/id integer
The county’s unique identifier.
county/href string
The endpoint to call the county’s information, such as /api/v2/county/{id} where {id} is the county’s unique identifier.
county/name string
The county’s name.
postCode string
The centre’s post code.
country object
The centre’s country.
country/id integer
The country’s unique identifier.
country/href string
The endpoint to call the country’s information, such as /api/v2/country/{id} where {id} is the country’s unique identifier.
country/name string
The country’s name.
status enumeration
Determines whether the centre is Active or Retired. Retiring a centre prevents any further tests from being scheduled at it.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Creating a centre
Send a request to the endpoint to create a centre.
Parameters
Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ? after any path parameters.
|
Name |
Parameter |
Input |
Description |
|---|---|---|---|
|
authorization |
header MANDATORY |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
content-type |
header MANDATORY |
application/json or application/xml |
Determines data format of the request, which can be either JSON or XML. |
|
content-length |
header MANDATORY |
{number} |
Determines the number of characters passed in the body of the request, where {number} is a numerical figure. This is usually automatically calculated when the request is sent. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
Sample request
The following request contains the minimum required request body to create a centre.
{
"name": "Surpass Centre"
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
reference string optional
The centre’s unique reference code. Surpass auto-generates a reference if omitted.
name string mandatory
The centre’s name.
randomiseTestForms boolean optional
Enforces the random allocation of test forms to candidates. Defaults to true if omitted.
hideSubjectsIncludedInSubjectGroups boolean optional
Determines whether subjects in subject groups are available for selection in Test Creation. If set to true, tests are prevented from being created in subject group subjects. Defaults to false if omitted.
excludeItemStatistics boolean optional
Determines whether data from this centre is included in the Reporting screens. If set to true, this centre’s data is prevented from appearing in Reporting. This is useful for centres running practice, pilot, or quality review tests. Defaults to false if omitted.
addressLine1 string optional
The centre’s first line of address.
addressLine2 string optional
The centre’s second line of address.
town string optional
The centre’s town.
county object optional
The centre’s county.
county/id integer
The county’s unique identifier.
county/name string
The county’s name.
postCode string optional
The centre’s post code.
country object optional
The centre’s country.
country/id integer
The country’s unique identifier.
country/name string
The country’s name.
status enumeration optional
Determines whether the centre is Active or Retired. Retiring a centre prevents any further tests from being scheduled there.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the new centre’s details.
{
"id": 1,
"reference": "sHrsEFyJEYyr",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Centre/1",
"errors": null,
"serverTimeZone": null
}Updating a centre
Send a request to the endpoint to update a specific centre.
Parameters
Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ? after any path parameters.
|
Name |
Parameter |
Input |
Description |
|---|---|---|---|
|
authorization |
header MANDATORY |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
content-type |
header MANDATORY |
application/json or application/xml |
Determines data format of the request, which can be either JSON or XML. |
|
content-length |
header MANDATORY |
{number} |
Determines the number of characters passed in the body of the request, where {number} is a numerical figure. This is usually automatically calculated when the request is sent. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
|
id |
path OPTIONAL |
/api/v2/Centre/{id} |
Updates specified centre, where {id} is the centre’s unique identifier. |
|
reference |
query OPTIONAL |
/api/v2/Centre?reference={reference} |
Updates specified centre, where {reference} is the centre’s unique reference code. |
Sample request
At least one property must be updated in the request. The following request contains the minimum required request body to update a centre. Refer to the request body schema for all properties that can be updated.
{
"randomiseTestForms": "true"
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
reference string
The centre’s unique reference code.
name string
The centre’s name.
randomiseTestForms boolean
Enforces the random allocation of test forms to candidates.
hideSubjectsIncludedInSubjectGroups boolean
Determines whether subjects in subject groups are available for selection in Test Creation. If set to true, tests are prevented from being created in subject group subjects.
excludeItemStatistics boolean
Determines whether data from this centre is included in the Reporting screens. If set to true, this centre’s data is prevented from appearing in Reporting. This is useful for centres running practice, pilot, or quality review tests.
addressLine1 string
The centre’s first line of address.
addressLine2 string
The centre’s second line of address.
town string
The centre’s town.
county object
The centre’s county.
county/id integer
The county’s unique identifier.
county/name string
The county’s name.
postCode string
The centre’s post code.
country object
The centre’s country.
country/id integer
The country’s unique identifier.
country/name string
The country’s name.
status enumeration
Determines whether the centre is Active or Retired. Retiring a centre prevents any further tests from being scheduled at it.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the updated centre’s details.
{
"id": 1,
"reference": "sHrsEFyJEYyr",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Centre/1",
"errors": null,
"serverTimeZone": null
}Deleting a centre
Send a request to the endpoint to delete a specific centre. No request body is required.
Parameters
Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ? after any path parameters.
|
Name |
Parameter |
Input |
Description |
|---|---|---|---|
|
authorization |
header MANDATORY |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
|
id |
path OPTIONAL |
/api/v2/Centre/{id} |
Deletes specified centre, where {id} is the centre’s unique identifier. |
|
reference |
query OPTIONAL |
/api/v2/Centre?reference={reference} |
Deletes specified centre, where {reference} is the centre’s unique reference code. |
Sample response
If successful, the HTTP status code will be 200 and the response body will confirm the centre has been deleted by returning a null id.
{
"id": null,
"href": null,
"errors": null,
"serverTimeZone": null
}Error Codes
Refer to the following table for information on error codes that may be encountered when using this resource.
|
Name |
Code |
Description |
|---|---|---|
|
InternalServer |
1 |
Internal server error. |
|
Unauthorized |
3 |
The request has been sent by an unauthorised user. |
|
IncorrectFieldFormat |
4 |
A field in the request has not been completed in the correct format. |
|
InaccessibleOperation |
5 |
The request has been sent by a user with invalid permissions. |
|
InaccessibleData |
6 |
The request has been sent by a user with invalid permissions. |
|
MissingBody |
7 |
There is an issue with the request body. |
|
InvalidReference |
11 |
The unique reference code used in the request is invalid. |
|
InvalidInputParameters |
15 |
There is an issue with the path or query parameters. |
|
InvalidId |
16 |
The ID number used in the request is invalid. |
|
InvalidODataOperation |
19 |
There is an issue with the query parameters. |
|
BadRequest |
20 |
There is an issue with the /api/v2/Centre?$skip={skip} query parameter, where {skip} is a number that should not exceed the total number of responses. |
|
CentreDoesNotExist |
31 |
The centre specified in the request does not exist. |
|
CentreReferenceNotUnique |
32 |
The centre reference code is not unique. |
|
FailedToCreateCentre |
33 |
There is an issue with creating a centre.
EXAMPLE: The request will fail if the specified county does not belong in the specified country.
|
|
FailedToUpdateCentre |
34 |
There is an issue with updating a centre. |
|
FailedToDeleteCentre |
35 |
There is an issue with deleting a centre. |
Further reading
Read the following articles to learn more about similar APIs, how to get started with the Surpass API v2, and how to get the best out of this reference documentation: