Subject API
In Surpass, a subject is where you create and manage items for use in tests. Subjects can hold folders and sub-folders of items, allowing for flexible organisation of your test content. You can also upload media to your subject’s media library for use in its items. A subject is associated with at least one centre. Any tests created in the subject can be scheduled at the associated centre(s).
The Subject API resource is used to list, retrieve, create, update, and delete subjects.
This article explains what calls can be made to the Surpass API using the Subject resource.
Import this API into your Postman Workspace
In This Article
Listing subjects
Send a request to the endpoint to retrieve a list of subjects. 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/Subject?$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/Subject?$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/Subject?$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, status, deliveryType, htmlOnly, subjectMasterList, enableCheckboxesInItemAuthoring; {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/Subject?$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/api/v2/Subject?$top=10&$skip=10",
"prevPageLink": null,
"response": [
{
"id": 1,
"reference": "Subject1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1"
"name": "Subject 1"
},
{
"id": 2,
"reference": "Subject2",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/2"
"name": "Subject 2"
},
{
"id": 3,
"reference": "Subject3",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/3"
"name": "Subject 3"
},
{
"id": 4,
"reference": "Subject4",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/4"
"name": "Subject 4"
},
{
"id": 5,
"reference": "Subject5",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/5"
"name": "Subject 5"
},
{
"id": 6,
"reference": "Subject6",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/6"
"name": "Subject 6"
},
{
"id": 7,
"reference": "Subject7",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/7"
"name": "Subject 7"
},
{
"id": 8,
"reference": "Subject8",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/8"
"name": "Subject 8"
},
{
"id": 9,
"reference": "Subject9",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/9"
"name": "Subject 9"
},
{
"id": 10,
"reference": "Subject10",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/10"
"name": "Subject 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 subjects there are in total.
top integer
Details number of subjects returned in the response.
skip integer
Details how many subjects were skipped to display those in the response.
pageCount integer
Details how many pages of subjects there are.
nextPageLink string
The endpoint to call the next page of subjects. If null, the response is the last page of subjects.
prevPageLink string
The endpoint to call the previous page of subjects. If null, the response is the first page of subjects.
response array
Contains the rest of the response.
id integer
The subject’s unique identifier.
reference string
The subject’s unique reference code.
href string
The endpoint to call the subject’s information, such as /api/v2/Subject/{id} where {id} is the subject’s unique identifier.
name string
The subject’s name.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Retrieving subject information
Send a request to the endpoint to retrieve information for a specific subject 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/Subject/{id} |
Returns information for the specified subject, where {id} is the subject’s unique identifier. |
|
reference |
query OPTIONAL |
/api/v2/Subject?reference={reference} |
Returns information for the specified subject, where {reference} is the subject’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": [
{
"name": "Geography Subject",
"primaryCentre": {
"id": 1,
"reference": "Centre1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Centre/1"
},
"status": "Active",
"deliveryType": "OnScreen",
"htmlOnly": false,
"subjectMasterList": false,
"enableCheckboxesInItemAuthoring": false,
"language": {
"name": "English (UK)",
"code": "en"
},
"itemNamePrefix": null,
"itemNameIsReadOnly": false,
"id": 1,
"reference": "Subject1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1"
}
],
"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 subjects there are in total. This is null because the information retrieved is for a specific subject.
top integer
Details number of subjects returned in the response. This is null because the information retrieved is for a specific subject.
skip integer
Details how many subjects were skipped to display those in the response. This is null because the information retrieved is for a specific subject.
pageCount integer
Details how many pages of subjects there are. This is null because the information retrieved is for a specific subject.
nextPageLink string
The endpoint to call the next page of subjects. This is null because the information retrieved is for a specific subject.
prevPageLink string
The endpoint to call the previous page of subjects. This is null because the information retrieved is for a specific subject.
response array
Contains the rest of the response.
name string
The subject’s name.
primaryCentre object
The subject’s primary centre. Subjects can only be associated with one centre by default, but can also be shared with other centres. Any tests created in the subject can be scheduled at the associated centre(s).
primaryCentre/id integer
The unique identifier of the subject’s primary centre.
primaryCentre/reference string
The unique reference code of the subject’s primary centre.
primaryCentre/href string
The endpoint to call the information of the subject’s primary centre, such as /api/v2/Centre/{id} where {id} is the centre’s unique identifier.
status enumeration
Determines whether the subject is Active, ActiveRegistrationClosed, or Archived. Archiving a subject prevents it from being available for item creation and test scheduling. Archived subjects with registration closed prevents candidates from being associated with the subject.
deliveryType enumeration
Determines whether the subject’s delivery type is OnScreen or OnPaper.
htmlOnly Boolean
Determines whether the subject’s content type is Mixed (false) or HTML (true).
subjectMasterList Boolean
Determines whether the subject has an active master list. A master list contains all items from its parent subject.
enableCheckboxesInItemAuthoring Boolean
Determines whether checkboxes display in delivery on Multiple Choice, Multiple Response, and Either/Or items, and Multiple Choice and Multiple Response survey items in this subject.
language object
If item language variants are enabled, determines the default language for the subject.
language/name string
The name of the language.
language/code enumeration
The language’s ISO code. The available language codes are amh, ar, arm, pob, bul, mya, zh, zho, hrv, ces, dan, nl, en-int, en, us, est, per, tgl, fin, frc, ga, gle, glg, ge, gre, heb, hun, ind, ita, jpn, kk, khm, kor, lao, la, lav, lit, mlt, mon, nep, no, pol, por, iir, ron, rus, smo, slk, slv, som, sp, es-int, lac, es-pa, es-pr, swe, tha, tur, ukr, vie, and we.
itemNamePrefix string
If the Item Prefixes and Sequential Numbering site setting is enabled, determines the prefix automatically added to the name of all new items. For more information, read ‘About Item Authoring settings’ in About Site Settings options.
itemNameIsReadOnly Boolean
If the Item Prefixes and Sequential Numbering site setting is enabled, determines whether item authors can edit item names in this subject. For more information, read ‘About Item Authoring settings’ in About Site Settings options.
id integer
The subject’s unique identifier.
reference string
The subject’s unique reference code.
href string
The endpoint to call the subject’s information, such as /api/v2/Subject/{id} where {id} is the subject’s unique identifier.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Creating a subject
Send a request to the endpoint to create a subject.
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 subject.
{
"name": "Geography Subject",
"primaryCentre": {
"reference": "Centre1"
}
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
reference string optional
The subject’s unique reference code. Surpass auto-generates a reference if omitted.
name string mandatory
The subject’s name.
primaryCentre object mandatory
The subject’s primary centre. Subjects can only be associated with one centre by default, but can also be shared with other centres. Any tests created in the subject can be scheduled at the associated centre(s).
Either the primary centre’s id or reference is required.
primaryCentre/id integer
The unique identifier of the subject’s primary centre.
primaryCentre/reference string
The unique reference code of the subject’s primary centre.
status enumeration optional
Determines whether the subject is Active, ActiveRegistrationClosed, or Archived. Archiving a subject prevents it from being available for item creation and test scheduling. Archived subjects with registration closed prevents candidates from being associated with the subject. Defaults to Active if omitted.
deliveryType enumeration optional
Determines whether the subject’s delivery type is OnScreen or OnPaper. Defaults to OnScreen if omitted.
htmlOnly Boolean optional
Determines whether the subject’s content type is Mixed (false) or HTML (true). Defaults to false if omitted.
subjectMasterList Boolean optional
Determines whether the subject has an active master list. A master list contains all items from its parent subject. Defaults to false if omitted.
language object mandatory
If item language variants are enabled, determines the default language for the subject.
language/name string
The name of the language.
language/code enumeration
The language’s ISO code. The available language codes are amh, ar, arm, pob, bul, mya, zh, zho, hrv, ces, dan, nl, en-int, en, us, est, per, tgl, fin, frc, ga, gle, glg, ge, gre, heb, hun, ind, ita, jpn, kk, khm, kor, lao, la, lav, lit, mlt, mon, nep, no, pol, por, iir, ron, rus, smo, slk, slv, som, sp, es-int, lac, es-pa, es-pr, swe, tha, tur, ukr, vie, and we.
itemNamePrefix string mandatory
If the Item Prefixes and Sequential Numbering site setting is enabled, determines the prefix automatically added to the name of all new items. For more information, read ‘About Item Authoring settings’ in About Site Settings options.
itemNameIsReadOnly Boolean optional
If the Item Prefixes and Sequential Numbering site setting is enabled, determines whether item authors can edit item names in this subject. For more information, read ‘About Item Authoring settings’ in About Site Settings options. Defaults to false if omitted.
enableCheckboxesInItemAuthoring Boolean optional
Determines whether checkboxes display in delivery on Multiple Choice, Multiple Response, and Either/Or items, and Multiple Choice and Multiple Response survey items in this subject. Defaults to false if omitted.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the new subject’s details.
{
"id": 1,
"reference": "Nxpov1jTxqG0",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1",
"errors": null,
"serverTimeZone": null
}Updating a subject
Send a request to the endpoint to update a specific subject.
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/Subject/{id} |
Updates specified subject, where {id} is the subject’s unique identifier. |
|
reference |
query OPTIONAL |
/api/v2/Subject?reference={reference} |
Updates specified subject, where {reference} is the subject’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 subject. Refer to the request body schema for all properties that can be updated.
{
"subjectMasterList": "true"
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
reference string
The subject’s unique reference code.
name string
The subject’s name.
primaryCentre object
The subject’s primary centre. Subjects can only be associated with one centre by default, but can also be shared with other centres. Any tests created in the subject can be scheduled at the associated centre(s).
primaryCentre/id integer
The unique identifier of the subject’s primary centre.
primaryCentre/reference string
The unique reference code of the subject’s primary centre.
status enumeration
Determines whether the subject is Active, ActiveRegistrationClosed, or Archived. Archiving a subject prevents it from being available for item creation and test scheduling. Archived subjects with registration closed prevents candidates from being associated with the subject.
htmlOnly Boolean
Determines whether the subject’s content type is Mixed (false) or HTML (true).
subjectMasterList Boolean
Determines whether the subject has an active master list. A master list contains all items from its parent subject.
language object
If item language variants are enabled, determines the default language for the subject.
language/name string
The name of the language.
language/code enumeration
The language’s ISO code. The available language codes are amh, ar, arm, pob, bul, mya, zh, zho, hrv, ces, dan, nl, en-int, en, us, est, per, tgl, fin, frc, ga, gle, glg, ge, gre, heb, hun, ind, ita, jpn, kk, khm, kor, lao, la, lav, lit, mlt, mon, nep, no, pol, por, iir, ron, rus, smo, slk, slv, som, sp, es-int, lac, es-pa, es-pr, swe, tha, tur, ukr, vie, and we.
itemNamePrefix string
If the Item Prefixes and Sequential Numbering site setting is enabled, determines the prefix automatically added to the name of all new items. For more information, read ‘About Item Authoring settings’ in About Site Settings options.
itemNameIsReadOnly Boolean
If the Item Prefixes and Sequential Numbering site setting is enabled, determines whether item authors can edit item names in this subject. For more information, read ‘About Item Authoring settings’ in About Site Settings options.
enableCheckboxesInItemAuthoring Boolean
Determines whether checkboxes display in delivery on Multiple Choice, Multiple Response, and Either/Or items, and Multiple Choice and Multiple Response survey items in this subject.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the updated subject’s details.
{
"id": 1,
"reference": "Nxpov1jTxqG0",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1",
"errors": null,
"serverTimeZone": null
}Deleting a subject
Send a request to the endpoint to delete a specific subject. 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/Subject/{id} |
Deletes specified subject, where {id} is the subject’s unique identifier. |
|
reference |
query OPTIONAL |
/api/v2/Subject?reference={reference} |
Deletes specified subject, where {reference} is the subject’s unique reference code. |
Sample response
If successful, the HTTP status code will be 200 and the response body will confirm the subject 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/Subject?$skip={skip} query parameter, where {skip} is a number that should not exceed the total number of responses. |
|
SubjectDoesNotExist |
43 |
The subject specified in the request does not exist. |
|
FailedToCreateSubject |
44 |
There is an issue with creating a subject. |
|
FailedToDeleteSubject |
45 |
There is an issue with deleting the subject.
|
|
FailedToUpdateSubject |
47 |
There is an issue with updating a subject. |
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: