BasicPage API
A basic page is a non-scored, non-question item that appears to candidates during a test. Basic pages are either Introduction Pages, Information Pages, or Finish Pages.
This article explains what calls can be made to the Surpass API using the BasicPage resource.
Import this API into your Postman Workspace
In This Article
Basic Pages
The BasicPage API resource can be used to retrieve, create, and update Introduction Pages, Information Pages, and Finish Pages. For information on question items and surveys, read Item API.
To learn more about items, see the Item Authoring section of the Surpass documentation.
Retrieving basic page information
Send a request to the endpoint to retrieve information for a specific basic page using its ID. 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 MANDATORY |
/api/v2/BasicPage/{id} |
Returns information for the specified basic page, where {id} is the basic page’s unique identifier. |
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": [
{
"subject": {
"id": 1,
"reference": "Subject1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1",
"name": "Geography Subject"
},
"folder": null,
"name": "Geography Test Form 1 - Finish Page",
"type": "FinishPage",
"questionText": "You have finished your test. Your results will be available in due course.",
"htmlText": "You have finished your test. Your results will be available in due course.",
"contentType": "RichText",
"mathMl": null,
"assistiveMedia": null,
"additionalHtmlText": null,
"additionalMathMl": null,
"additionalContentType": "RichText",
"status": "Live",
"comment": "",
"commentIsPrivate": false,
"mediaItems": [],
"sourceMaterials": [],
"itemTagValues": [],
"stemComponents": [
{
"id": 0,
"text": "You have finished your test. Your results will be available in due course.",
"mathMl": null,
"media": null
}
],
"allowOpenImageInPopup": false,
"mediaLayout": "AutoSelect",
"deleted": false,
"tools": [],
"owner": {
"id": 1,
"reference": "User1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/User/1"
},
"comments": [],
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/BasicPage/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 basic pages there are in total. This is null because the information retrieved is for a specific basic page.
top integer
Details number of basic pages returned in the response. This is null because the information retrieved is for a specific basic page.
skip integer
Details how many basic pages were skipped to display those in the response. This is null because the information retrieved is for a specific basic page.
pageCount integer
Details how many pages of basic pages there are. This is null because the information retrieved is for a specific basic page.
nextPageLink string
The endpoint to call the next page of basic pages. This is null because the information retrieved is for a specific basic page.
prevPageLink string
The endpoint to call the previous page of basic pages. This is null because the information retrieved is for a specific basic page.
response array
Contains the rest of the response.
subject object
Contains the subject that the item is in.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
subject/href string
The endpoint to call the subject’s information, such as /api/v2/Subject/{id} where {id} is the subject’s unique identifier.
subject/name string
The subject’s name.
folder object
Contains the folder that the item is in. If null, the item is not in a folder.
folder/id integer
The folder’s unique identifier.
folder/href string
The endpoint to call the folder’s information, such as /api/v2/Folder/{id} where {id} is the folder’s unique identifier.
folder/position integer
The position of the item within the folder.
name string
The item’s name.
type enumeration
The item type, which can be one of IntroductionPage, InformationPage, or FinishPage.
questionText string
The first question stem block in HTML format. If the item has multiple question stem blocks, see the stemComponents object. If null, the item does not have any question text.
htmlText string
The first question stem block in HTML format.
contentType enumeration
Determines the content type for the first question stem block. This can be either RichText, an Image, or MathML.
mathML string
If the first question stem block contains formula authored using the Equation Editor (Mixed subjects) or WIRIS EDITOR math (HTML subjects), this information is returned in MathML format. If null, the item does not contain any formula.
assistiveMedia object
Contains any assistive media if it has been attached to the first question stem block. If null, the item does not contain any assistive media.
assistiveMedia/id integer
The assistive media’s unique identifier.
assistiveMedia/href string
The endpoint to call the assistive media’s information, such as /api/v2/BasicPage/{id}/AssistiveMedia/{id} where {id} is the basic page’s unique identifier and {id} is the assistive media’s unique identifier.
additionalHTMLText string
Contains any additional information in HTML format if the item is an Introduction Page or Finish Page.
additionalMathMl string
Contains any additional formula in MathML format if the item is an Introduction Page or Finish Page.
additionalContentType enumeration
Determines the content type for the additional information if the item is an Introduction Page or Finish Page. This can be either RichText or MathML.
status enumeration
The item’s workflow status. The default workflow statuses are Draft, To Review, Reviewed, Live, and Withdrawn. Every item starts at Draft and must be set to Live before being able to be added to a test form. Custom workflow statuses can also be created and assigned to items.
comment string
Any comment left on the item in text format.
commentIsPrivate Boolean
Determines whether the comment is a private comment (only viewable by users with the Comment Manager permission) or not.
mediaItems array
Contains any media embedded on the item.
mediaItems/externalId string
The media’s name in Surpass.
mediaItems/id integer
The media’s unique identifier.
sourceMaterials array
Contains any source material attached to the item.
sourceMaterials/externalId string
The source material’s name in Surpass.
sourceMaterials/id integer
The source material’s unique identifier.
itemTagValues array
Contains the information of any tags added to the item.
itemTagValues/id integer
The tag value’s unique identifier.
itemTagValues/href string
The endpoint to call the tag value’s information, such as /api/v2/ItemTagValue/{id} where {id} is the tag value’s unique identifier.
stemComponents array
A collection of text, images or equations that form each question stem.
stemComponents/id integer
The question stem’s unique identifier.
stemComponents/text string
The question stem’s text in HTML format.
stemComponents/mathML string
If the question stem contains any formula authored using the Equation Editor (Mixed subjects) or WIRIS EDITOR math (HTML subjects), this information is returned in MathML format. If null, the item does not contain any formula.
stemComponents/media object
Contains any media in the question stem for items in Mixed subjects.
stemComponents/media/externalId string
The media’s name in Surpass.
stemComponents/media/id integer
The media’s unique identifier.
allowOpenImageInPopup Boolean
Determines whether the Allow image to be opened in popup setting is enabled if an image is added to Step 3 of the item.
mediaLayout enumeration
The media layout if media is added to Step 3 of the item. The layout options are AutoSelect, LeftAnswer, RightAnswer, AboveQuestionText, AboveAnswer, and BelowAnswer.
deleted Boolean
Determines whether the item is in its subject’s recycle bin.
tools array
Contains the information of any tools added to the item.
tools/name enumeration
The type of tool. The available tools are Calculator and Caliper (HTML subjects only).
tools/settings array
Contains the tool’s name and settings.
tools/settings/mode enumeration
The tool mode. The available modes are Basic (calculator), Pixels (caliper; HTML subjects only), and Scientific (calculator).
tools/settings/label string
The name given to the tool.
owner object
The item owner’s information.
owner/id integer
The item owner’s unique identifier.
owner/reference string
The item owner’s unique reference code.
owner/href string
The endpoint to call the item owner’s information, such as /api/v2/User/{id} where {id} is the item owner’s unique identifier.
comments array
Contains the information for any comments left on the item.
comments/id integer
The comment’s unique identifier.
comments/text string
The comment.
comments/private Boolean
Determines whether the comment is a private comment (only viewable by users with the Comment Manager permission) or not.
comments/dateCreated string
The date the comment was left, in YYYY/MM/DD format.
comments/createdBy array
Contains the user who left the comment’s information.
comments/createdBy/id integer
The user’s unique identifier.
comments/createdBy/reference string
The user’s unique reference code.
comments/createdBy/href string
The endpoint to call the user’s information, such as /api/v2/User/{id} where {id} is the user’s unique identifier.
id integer
The item’s unique identifier.
href string
The endpoint to call the item’s information, such as /api/v2/BasicPage/{id} where {id} is the basic page’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 basic page
Send a request to the endpoint to create a basic page.
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 basic page.
{
"type": "IntroductionPage",
"subject": {
"reference": "Subject1"
},
"name": "Introduction Page"
}The following requests contain the minimum required request body to create each basic page at Live status.
Introduction Pages
{
"type": "IntroductionPage",
"subject": {
"reference": "Subject1"
},
"name": "Introduction Page 2",
"status": "live",
"stemComponents": [
{
"text": "Your test is 60 minutes long and contains 3 sections with 10 questions in each section."
}
]
}Information Pages
{
"type": "InformationPage",
"subject": {
"reference": "Subject1"
},
"name": "Information Page",
"status": "live",
"stemComponents": [
{
"text": "You have 20 minutes to complete the next section."
}
]
}Finish Pages
{
"type": "FinishPage",
"subject": {
"reference": "Subject1"
},
"name": "Finish Page",
"status": "live",
"stemComponents": [
{
"text": "You have finished your test. Your results will be available in due course."
}
]
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
type enumeration mandatory
The item type, which can be one of IntroductionPage, InformationPage, or FinishPage.
subject object mandatory
Contains the subject that the item is in.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
name string mandatory
The item’s name.
htmlText string optional
The first question stem block in HTML format.
mathML string optional
If the first question stem block contains formula authored using the Equation Editor (Mixed subjects) or WIRIS EDITOR math (HTML subjects), pass this information in MathML format.
contentType enumeration optional
Determines the content type for the first question stem block. This can be either RichText, an Image, or MathML.
additionalHTMLText string optional
Contains any additional information in HTML format if the item is an Introduction Page or Finish Page.
additionalMathMl string optional
Contains any additional formula in MathML format if the item is an Introduction Page or Finish Page.
additionalContentType enumeration optional
Determines the content type for the additional information if the item is an Introduction Page or Finish Page. This can be either RichText or MathML.
folder object optional
Contains the folder that the item is in. If null, the item is not in a folder.
folder/id integer
The folder’s unique identifier.
folder/position integer
The position of the item within the folder.
status enumeration optional
The item’s workflow status. The default workflow statuses are Draft, To Review, Reviewed, Live, and Withdrawn. Every item starts at Draft and must be set to Live before being able to be added to a test form. Custom workflow statuses can also be created and assigned to items.
Defaults to Draft if omitted.
comment string optional
Any comment left on the item in text format.
commentIsPrivate Boolean optional
Determines whether the comment is a private comment (only viewable by users with the Comment Manager permission) or not. Defaults to false if omitted.
mediaItems array optional
Contains any media embedded on the item.
mediaItems/externalId string
The media’s name in Surpass.
mediaItems/id integer
The media’s unique identifier.
sourceMaterials array optional
Contains any source material attached to the item.
sourceMaterials/externalId string
The source material’s name in Surpass.
sourceMaterials/id integer
The source material’s unique identifier.
stemComponents array optional
A collection of text, images or equations that form each question stem.
stemComponents/id integer
The question stem’s unique identifier.
stemComponents/text string
The question stem’s text in HTML format.
stemComponents/mathML string
Any formula authored using the Equation Editor in Mixed subjects.
stemComponents/media object
Contains any media in the question stem for items in Mixed subjects.
stemComponents/media/externalId string
The media’s name in Surpass.
stemComponents/media/id integer
The media’s unique identifier.
allowOpenImageInPopup Boolean optional
Determines whether the Allow image to be opened in popup setting is enabled if an image is added to Step 3 of the item. Defaults to false if omitted.
mediaLayout enumeration optional
The media layout if media is added to Step 3 of the item. The layout options are AutoSelect, LeftAnswer, RightAnswer, AboveQuestionText, AboveAnswer, and BelowAnswer.
assistiveMedia object optional
Contains any assistive media if it has been attached to the first question stem block.
assistiveMedia/name string
The assistive media’s name. This has to include the filetype extension.
assistiveMedia/data string
The assistive media’s file data in encoded Base64 format.
tools array optional
Contains the information of any tools added to the item.
tools/name enumeration
The type of tool. The available tools are Calculator and Caliper (HTML subjects only).
tools/settings array
Contains the tool’s name and settings.
tools/settings/mode enumeration
The tool mode. The available modes are Basic (calculator), Pixels (caliper; HTML subjects only), and Scientific (calculator).
tools/settings/label string
The name given to the tool.
owner object optional
The item owner’s information.
owner/id integer
The item owner’s unique identifier.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the new basic page’s details.
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/BasicPage/1",
"errors": null
}Updating a basic page
Send a request to the endpoint to update a specific basic page.
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 MANDATORY |
/api/v2/BasicPage/{id} |
Update specified basic page, where {id} is the basic page’s unique identifier. |
Sample request
At least one property must be updated in the request. The following request contains the minimum required request body to update a basic page. Refer to the request body schema for all properties that can be updated.
{
"name": "Geography Test Form 2 - Finish Page"
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
name string
The item’s name.
htmlText string
The first question stem block in HTML format.
mathML string
If the first question stem block contains formula authored using the Equation Editor (Mixed subjects) or WIRIS EDITOR math (HTML subjects), pass this information in MathML format.
contentType enumeration
Determines the content type for the first question stem block. This can be either RichText, an Image, or MathML.
additionalHTMLText string
Contains any additional information in HTML format if the item is an Introduction Page or Finish Page.
additionalMathMl string
Contains any additional formula in MathML format if the item is an Introduction Page or Finish Page.
additionalContentType enumeration
Determines the content type for the additional information if the item is an Introduction Page or Finish Page. This can be either RichText or MathML.
folder object
Contains the folder that the item is in. If null, the item is not in a folder.
folder/id integer
The folder’s unique identifier.
folder/position integer
The position of the item within the folder.
status enumeration
The item’s workflow status. The default workflow statuses are Draft, To Review, Reviewed, Live, and Withdrawn. Every item starts at Draft and must be set to Live before being able to be added to a test form. Custom workflow statuses can also be created and assigned to items.
comment string
Any comment left on the item in text format.
commentIsPrivate Boolean
Determines whether the comment is a private comment (only viewable by users with the Comment Manager permission) or not. Defaults to false if omitted.
mediaItems array
Contains any media embedded on the item.
mediaItems/externalId string
The media’s name in Surpass.
mediaItems/id integer
The media’s unique identifier.
sourceMaterials array
Contains any source material attached to the item.
sourceMaterials/externalId string
The source material’s name in Surpass.
sourceMaterials/id integer
The source material’s unique identifier.
stemComponents array
A collection of text, images or equations that form each question stem.
stemComponents/id integer
The question stem’s unique identifier.
stemComponents/text string
The question stem’s text in HTML format.
stemComponents/mathML string
Any formula authored using the Equation Editor in Mixed subjects.
stemComponents/media object
Contains any media in the question stem for items in Mixed subjects.
stemComponents/media/externalId string
The media’s name in Surpass.
stemComponents/media/id integer
The media’s unique identifier.
allowOpenImageInPopup Boolean
Determines whether the Allow image to be opened in popup setting is enabled if an image is added to Step 3 of the item.
mediaLayout enumeration
The media layout if media is added to Step 3 of the item. The layout options are AutoSelect, LeftAnswer, RightAnswer, AboveQuestionText, AboveAnswer, and BelowAnswer.
assistiveMedia object
Contains any assistive media if it has been attached to the first question stem block.
assistiveMedia/name string
The assistive media’s name. This has to include the filetype extension.
assistiveMedia/data string
The assistive media’s file data in encoded Base64 format.
tools array
Contains the information of any tools added to the item.
tools/name enumeration
The type of tool. The available tools are Calculator and Caliper (HTML subjects only).
tools/settings array
Contains the tool’s name and settings.
tools/settings/mode enumeration
The tool mode. The available modes are Basic (calculator), Pixels (caliper; HTML subjects only), and Scientific (calculator).
tools/settings/label string
The name given to the tool.
owner object
The item owner’s information.
owner/id integer
The item owner’s unique identifier.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the updated basic page’s details.
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/BasicPage/1",
"errors": null
}Assistive Media
Assistive media are small audio and video files that can be added to items so that candidates can hear content in a chosen language or watch a visual aid. Assistive media can be used to improve the accessibility of your items or create unique assessment materials (for example, language testing).
The BasicPage API resource can be used to retrieve and update assistive media.
To learn more about assistive media, read Adding assistive media to an item and Using assistive media in the test driver.
Retrieving assistive media information
Send a request to the endpoint to retrieve information for a specific piece of assistive media using its ID. 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. |
|
id |
path MANDATORY |
/api/v2/BasicPage/{id}/AssistiveMedia/{id} |
Returns information for the specified item, where {id} is the item’s unique identifier, and {id} is the assistive media’s unique identifier. |
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": "Question text.mp3",
"data": "QEBA",
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/BasicPage/1/AssistiveMedia/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 pieces of assistive media there are in total. This is null because the information retrieved is for a specific piece of media.
top integer
Details number of pieces of assistive media returned in the response. This is null because the information retrieved is for a specific piece of media.
skip integer
Details how many pieces of assistive media were skipped to display those in the response. This is null because the information retrieved is for a specific piece of media.
pageCount integer
Details how many pages of assistive media there are. This is null because the information retrieved is for a specific piece of media.
nextPageLink string
The endpoint to call the next page of assistive media. This is null because the information retrieved is for a specific piece of media.
prevPageLink string
The endpoint to call the previous page of assistive media. This is null because the information retrieved is for a specific piece of media.
response array
Contains the rest of the response.
name string
The assistive media’s name.
data string
The assistive media’s file data in encoded Base64 format.
id integer
The assistive media’s unique identifier.
href string
The endpoint to call the assistive media’s information, such as /api/v2/BasicPage/{id}/AssistiveMedia/{id} where {id} is the item’s unique identifier and {id} is the assistive media’s unique identifier.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Updating assistive media
Send a request to the endpoint to update a specific basic page’s assistive media.
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 MANDATORY |
/api/v2/BasicPage/{id}/AssistiveMedia/{id} |
Update specified item, where {id} is the item’s unique identifier, and {id} is the assistive media’s unique identifier. |
Sample request
At least one property must be updated in the request. The following request contains the minimum required request body to update an item and its assistive media. Refer to the request body schema for all properties that can be updated.
{
"name": "Finish text.mp3",
"data": "QEBA"
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
name string
The assistive media’s name.
data string
The assistive media’s file data in encoded Base64 format.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the updated item’s details.
{
"id": null,
"href": null,
"errors": 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. |
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: