TestForm API
Test forms are the digital equivalent of examination papers that are delivered to candidates. Test forms can contain items, sections, timers, grade boundaries, and dynamic content rules. A single test can have many associated test forms with different items and content rules.
This article explains what calls can be made to the Surpass API using the TestForm resource.
Import this API into your Postman Workspace
In This Article
Test Forms
The TestForm API resource can be used to retrieve, create, and update test forms.
To learn more about test forms, see the About test forms article in the Test Creation section of the Surpass documentation.
Retrieving test form information
Send a request to the endpoint to retrieve information for a specific test form 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/TestForm/{id} |
Returns information for the specified test form, where {id} is the test form’s unique identifier. |
|
reference |
path OPTIONAL |
/api/v2/TestForm/{reference} |
Returns information for the specified test form, where {reference} is the test form’s unique reference code. |
|
includeItems |
query OPTIONAL |
/api/v2/TestForm/{id}?includeItems={Boolean} |
If {Boolean} is true, returns information about the items in the test form, where {id} is the test form’s unique identifier (or 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": "TestForm1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TestForm/1",
"name": "Final Year Geography Test Form January 2022",
"subject": {
"id": 1,
"reference": "Subject1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1",
"name": "Geography Subject"
},
"test": {
"id": 1,
"reference": "Test1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Test/1"
},
"section": [
{
"name": "Introduction Section",
"type": "Intro",
"itemsCount": 1,
"items": [
{
"id": 1,
"surpassId": "0000P1",
"nonScored": true
}
],
"description": "Introduction Section."
},
{
"name": "Finish Section",
"type": "Finish",
"itemsCount": 1,
"items": [
{
"id": 5,
"surpassId": "0000P5",
"nonScored": true
}
],
"description": "Finish Section."
},
{
"name": "Tools",
"type": "Tools",
"itemsCount": 0,
"items": [],
"description": "Tools."
},
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TestForm/1/section/1",
"name": "Question Section",
"type": "Fixed",
"itemsCount": 3,
"items": [
{
"id": 2,
"surpassId": "0000P2",
"nonScored": false
},
{
"id": 3,
"surpassId": "0000P3",
"nonScored": false
},
{
"id": 4,
"surpassId": "0000P4",
"nonScored": false
}
],
"description": "Question Section.",
"passMarkType": "Percentage"
}
],
"metadata": [],
"status": "Draft",
"validFromDate": "2019-12-09T00:00:00",
"validToDate": "2029-12-09T00:00:00",
"timing": {
"type": "Timed",
"testDuration": 15,
"addBreak": false,
"addBreakType": "Fixed",
"addBreakPoolDuration": 0
},
"reasonableAdjustmentsStandard": 15,
"reasonableAdjustmentsMax": 30,
"excludeFromRandomTestFormSelection": false,
"gradeBoundaries": {
"type": "Percentage",
"irtRangeLower": -4.0,
"irtRangeHigher": 4.0,
"boundaries": [
{
"name": "Fail",
"value": 50.0
},
{
"name": "Pass",
"value": 50.0
},
{
"name": "Grade B",
"value": 75.0
},
{
"name": "Grade A",
"value": 90.0
}
]
},
"roundToDecimalPlaces": null,
"printable": true,
"allowCloseWithoutSubmit": true,
"allowUseAsTemplate": true,
"requiresModeration": false,
"requiresSecureMarker": false,
"advanceContentDownloadTimespan": 0,
"testFeedbackPassFail": true,
"testFeedbackPercentageMark": true,
"testFeedbackShowFeedbackButtonDuringTest": false,
"testFeedbackSummaryFeedback": {
"type": "EndOfSection",
"reviewAnswers": false,
"printableSummary": false,
"showCandidateDetails": false,
"displayFeedbackByLearningOutcome": false,
"showViewFeedbackButton": false
},
"itemComments": false,
"testFormComments": null
}
],
"errors": null
}Response schema
The response schema contains a description of every property that can be returned for this endpoint.
count integer
Details how many test forms there are in total. This is null because the information retrieved is for a specific test form.
top integer
Details number of test forms returned in the response. This is null because the information retrieved is for a specific test form.
skip integer
Details how many test forms were skipped to display those in the response. This is null because the information retrieved is for a specific test form.
pageCount integer
Details how many pages of test forms there are. This is null because the information retrieved is for a specific test form.
nextPageLink string
The endpoint to call the next page of test forms. This is null because the information retrieved is for a specific test form.
prevPageLink string
The endpoint to call the previous page of test forms. This is null because the information retrieved is for a specific test form.
response array
Contains the rest of the response.
id integer
The test form’s unique identifier.
reference string
The test form’s unique reference code.
href string
The endpoint to call the test form’s information, such as /api/v2/TestForm/{id} where {id} is the test form’s unique identifier.
name string
The test form’s name.
subject object
Contains the subject that the test 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.
test object
Contains the test’s information.
test/id integer
The test’s unique identifier.
test/reference string
The test’s unique reference code.
test/href string
The endpoint to call the test’s information, such as /api/v2/Test/{id} where {id} is the test’s unique identifier.
section array
Contains the test form’s sections’ information.
section/name string
The section’s name.
section/type enumeration
The type of section. The available options are:
- Intro – Introduction sections contain any non-scored Introduction Pages presented to candidates at the beginning of a test.
- Finish – Finish sections contain any non-scored Finish Pages presented to candidates at the end of a test.
- Tools – Tools sections contain any tools (images or PDF source materials).
- Fixed – Items in fixed sections are given to candidates in the order specified by the test creator, using “fixed” rules.
- Dynamic – Items in dynamic sections allow items to be automatically pulled from an item pool based on “dynamic” rules.
- SurveyFixed – Survey sections contain non-scored items. Items in survey sections can be delivered using fixed rules.
- SurveyDynamic – Survey sections contain non-scored items. Items in survey sections can be delivered using dynamic rules.
- Adaptive – In adaptive tests, candidates receive items based on their learning ability. For example, if a candidate answers an item incorrectly, they will then receive an easier item.
- ExternalOptimiser – An external optimiser section is used to create LOFT tests. The LOFT/Adaptive screen displays all test forms containing external optimiser sections.
- SectionSelector – Section selectors allow candidates to choose which section(s) to attempt. The test form must be using timed sections to contain a section selector section.
section/itemsCount integer
The number of items in the section.
section/projectIds array
Contains the unique identifiers of any dynamic rules.
section/items array
Contains the items in the section.
section/items/id integer
The item’s unique identifier.
section/items/surpassId string
The item’s Surpass unique identifier (ID). A Surpass ID is the item ID prefixed with the subject ID.
section/items/nonScored Boolean
Determines whether the item is a scored (false) or non-scored (true) item.
section/duration integer
The section’s duration if the test form is set to Timed Sections.
section/description string
The section description.
section/unlockSection Boolean
Determines whether the Unlock Section setting is enabled. If true, unlocks SecureClient only for the section, allowing candidates to access apps (including the internet) and their local files if the test form is set to Timed Sections.
section/passMarkType enumeration
Determines whether the pass mark type is Percentage or Score. If this property is omitted, the pass mark type is Score.
section/passMark integer
The section’s pass mark.
metadata array
status enumeration
The test form’s workflow status. The available workflow statuses are Draft, Live, Retired, and QualityReview. Every test form starts at Draft and must be set to Live before it can be scheduled.
validFromDate string
Sets the Valid From date for the date range in which the test form can be scheduled for candidates, in YYYY/MM/DD format.
validToDate string
Sets the Expires date for the date range in which the test can be scheduled for candidates, in YYYY/MM/DD format. Defaults to 10 years.
timing array
Contains the Test Duration settings’ information.
timing/type enumeration
Determines the test form’s timing type. The available options are:
- Untimed – Candidates have unlimited time to complete and submit their responses.
- Timed – The whole test form has a specified time limit in which candidates must complete and submit their responses.
- Timed Sections – Each section in the test form has an individual time limit. Candidates can only work in one timed section at a time. If the candidate decides to leave the section, they cannot return and their remaining time in that section is lost. You can combine timed sections into pools to allow candidates to manage their time between them.
timing/testDuration integer
The test form’s duration. Defaults to 10 minutes. Ignored if the timing/type is Untimed.
timing/addBreak Boolean
If the test form’s timing/type is Timed Sections, determines whether the test form has candidate breaks enabled.
timing/addBreakType enumeration
Determines whether the candidate breaks are Fixed or Pooled.
timing/addBreakPoolDuration integer
The pooled break’s duration. Ignored if the timing/addBreakType is Fixed.
reasonableAdjustmentsStandard integer
The extra time given to all candidates with reasonable adjustments, in minutes.
reasonableAdjustmentsMax integer
How much extra time invigilators can award to candidates with reasonable adjustments, in minutes.
excludeFromRandomTestFormSelection Boolean
Determines whether the Exclude from Random Test Form Selection setting is enabled. If true, prevents the test form from being randomly selected at the point of scheduling if Randomise Test Forms is enabled in the parent test’s Advanced Test Delivery Options.
gradeBoundaries object
Contains the grade boundaries’ information. You can set up to ten custom grade boundaries for your test form. Grade boundaries can be defined on either percentages or numerical scores.
gradeBoundaries/type enumeration
Determines whether the grade boundaries are Percentage, Score, or Irt-based.
gradeBoundaries/irtRangeLower integer
The lower IRT theta value. For more information on IRT grade boundaries, read Setting up grade boundaries and About IRT tags.
gradeBoundaries/irtRangeHigher integer
The higher IRT theta value. For more information on IRT grade boundaries, read Setting up grade boundaries and About IRT tags.
gradeBoundaries/boundaries array
Contains each grade boundary’s information.
gradeBoundaries/boundaries/name string
The grade boundary’s name.
gradeBoundaries/boundaries/value integer
The grade boundary’s value.
roundToDecimalPlaces integer
Determines how many decimal places candidates’ scores are rounded to when retrieved using the Result, AnalyticsResult, or HistoricalResult APIs. If null, candidates’ scores are not rounded.
printable Boolean
Determines whether the Printable setting is enabled. If true, allows you to print the test form.
allowCloseWithoutSubmit Boolean
Determines whether the Allow Close Without Submit setting is enabled. If true, allows candidates to exit the test without submitting their answers. Candidates can continue the test at a later stage.
allowUseAsTemplate Boolean
Determines whether the Allow use as template setting is enabled. If true, enables test form cloning. For more information, read Cloning test forms.
requiresModeration Boolean
Determines whether the Requires Moderation to release results setting is enabled. If true, prevents candidate scripts from appearing in the Results screen of Test Administration until they have been reviewed by another marker in the Moderate screen.
requiresSecureMarker Boolean
Determines whether the Mark Scripts in SecureMarker setting is enabled. If true, exports candidate scripts to SecureMarker for marking and moderation. For more information, read Configuring a test form for SecureMarker.
advanceContentDownloadTimespan integer
Determines whether the Pre-session Download Window (hours) setting is enabled. If an integer is provided, determines how far in advance of the test’s start time candidate test forms are generated and made available for download. Test form content and settings (including item content) are locked once generated and cannot be edited for the scheduled test session.
testFeedbackPassFail Boolean
Determines whether the Pass/Fail test feedback setting is enabled. If true, shows candidates whether they have passed or failed the test after submission. Summary Feedback must also be enabled.
testFeedbackPercentageMark Boolean
Determines whether the Percentage Mark test feedback setting is enabled. If true, shows candidates their percentage mark after submission. Summary Feedback must also be enabled.
testFeedbackShowFeedbackButtonDuringTest Boolean
Determines whether the Show Feedback Button During Test test feedback setting is enabled. If true, displays the Feedback button during the test, allowing candidates to see any Correct/Incorrect/General feedback added to items in Item Authoring (legacy tests only). For more information, read Adding candidate feedback to items.
testFeedbackSummaryFeedback object
Contains the Summary Feedback settings. Candidates are shown a summary of their performance on the test, including which items were answered correctly or incorrectly.
testFeedbackSummaryFeedback/type enumeration
Determines the type of Summary Feedback. The available options are:
- EndOfTest – Candidates receive summary feedback after submitting their test.
- EndOfSection (HTML tests only) – Candidates receive summary feedback after each section in the test. This is only available for HTML tests with timed sections.
- EndOfSectionAndTest (HTML tests only) – Candidates receive summary feedback after each section and after submitting the test. This is only available for HTML tests with timed sections.
Pass/Fail or Percentage Mark must be enabled if you want to use End of Section or End of Section & Test in HTML tests. If null, summary feedback is not required.
testFeedbackSummaryFeedback/reviewAnswers Boolean
Determine whether the Review Answers test feedback setting is enabled. If true, allows candidates to review their responses during the summary feedback. If false, candidates can only see if their answers were correct or incorrect.
testFeedbackSummaryFeedback/printableSummary Boolean
Determines whether the Printable Summary test feedback setting is enabled. If true, allows candidates to print the summary feedback.
testFeedbackSummaryFeedback/showCandidateDetails Boolean
Determines whether the Show Candidate Details test feedback setting is enabled. If true, displays candidates’ details (name, reference, and so on) during the summary feedback.
testFeedbackSummaryFeedback/displayFeedbackByLearningOutcome Boolean
Determines whether the Display Feedback by Learning Outcome test feedback setting is enabled. If true, displays how candidates scored on items with shared tag values.
testFeedbackSummaryFeedback/showViewFeedbackButton Boolean
Determines whether the Show View Feedback Button test feedback setting is enabled. If true, allows candidates to view Correct/Incorrect/General feedback left on items during the summary feedback. Review Answers must also be enabled for a candidate to access the feedback button.
itemComments Boolean
Determines whether the Allow Item Comments test feedback setting is enabled. If true, allows candidates to leave a comment on items during the test for feedback purposes. These comments are viewable in Test Administration (legacy tests only).
You can view comments left by candidates on HTML tests in Reporting. Read ‘About the Candidate Comments panel’ in Viewing Items Delivered Reports for more information.
testFormComments array
Contains any Test Form Comments information.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Creating a test form
Send a request to the endpoint to create a test form.
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 requests contains the minimum required request body to create a test form.
{
"reference": "TestForm1",
"name": "Final Year Geography Test Form January 2022",
"subject": {
"id": 1
},
"test": {
"reference": "Test1"
},
"status": 1,
"validFromDate": "2019-10-09T00:00:00",
"validToDate": "2029-10-09T00:00:00",
"timing": {
"type": "Untimed"
},
"gradeBoundaries": {
"type": "Score",
"irtRangeLower": -4,
"irtRangeHigher": 4,
"boundaries": [
{
"name": "Fail",
"value": null
},
{
"name": "Pass",
"value": 1
}
]
},
"section": [
{
"name": "Section 1",
"type": "Fixed",
"items": [
{
"id": 1
}
]
}
]
}{
"reference": "TestForm1",
"name": "Final Year Geography Test Form January 2022",
"subject": {
"id": 1
},
"test": {
"reference": "Test1"
},
"status": 1,
"validFromDate": "2019-10-09T00:00:00",
"validToDate": "2029-10-09T00:00:00",
"timing": {
"type": "Untimed"
},
"gradeBoundaries": {
"type": "Score",
"irtRangeLower": -4,
"irtRangeHigher": 4,
"boundaries": [
{
"name": "Fail",
"value": null
},
{
"name": "Pass",
"value": 1
}
]
},
"section": [
{
"name": "Introduction Section",
"type": "Intro",
"items": [
{
"id": 2
}
]
},
{
"name": "Finish Section",
"type": "Finish",
"items": [
{
"id": 3
}
]
},
{
"name": "Tools Section",
"type": "Tools",
"items": [
{
"id": 1
}
]
},
{
"name": "Section 1",
"type": "Fixed",
"items": [
{
"id": 1
}
]
}
]
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
reference string mandatory
The test form’s unique reference code.
name string mandatory
The test form’s name.
subject object mandatory
Contains the subject that the test is in.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
test object mandatory
Contains the test’s information.
test/id integer
The test’s unique identifier.
test/reference string
The test’s unique reference code.
test/href string
The endpoint to call the test’s information, such as /api/v2/Test/{id} where {id} is the test’s unique identifier.
metadata array optional
status enumeration optional
The test form’s workflow status. The available workflow statuses are Draft, Live, Retired, and QualityReview. Every test form starts at Draft and must be set to Live before it can be scheduled. Defaults to Retired if omitted.
Each status also has a unique identifier that can be used instead:
- 0 – Retired
- 1 – Draft
- 2 – Live
- 3 – QualityReview
validFromDate string mandatory
Sets the Valid From date for the date range in which the test form can be scheduled for candidates, in YYYY/MM/DD format.
validToDate string mandatory
Sets the Expires date for the date range in which the test can be scheduled for candidates, in YYYY/MM/DD format. Defaults to 10 years.
timing array mandatory
Contains the Test Duration settings’ information.
timing/type enumeration
Determines the test form’s timing type. The available options are:
- Untimed – Candidates have unlimited time to complete and submit their responses.
- Timed – The whole test form has a specified time limit in which candidates must complete and submit their responses.
- Timed Sections – Each section in the test form has an individual time limit. Candidates can only work in one timed section at a time. If the candidate decides to leave the section, they cannot return and their remaining time in that section is lost. You can combine timed sections into pools to allow candidates to manage their time between them.
timing/testDuration integer
The test form’s duration. Defaults to 10 minutes. Ignored if the timing/type is Untimed.
timing/addBreak Boolean
If the test form’s timing/type is Timed Sections, determines whether the test form has candidate breaks enabled.
timing/addBreakType enumeration
Determines whether the candidate breaks are Fixed or Pooled.
timing/addBreakPoolDuration integer
The pooled break’s duration. Ignored if the timing/addBreakType is Fixed.
reasonableAdjustmentsStandard integer optional
The extra time given to all candidates with reasonable adjustments, in minutes. Defaults to 0 if omitted.
reasonableAdjustmentsMax integer optional
How much extra time invigilators can award to candidates with reasonable adjustments, in minutes. Defaults to 0 if omitted.
excludeFromRandomTestFormSelection Boolean optional
Determines whether the Exclude from Random Test Form Selection setting is enabled. If true, prevents the test form from being randomly selected at the point of scheduling if Randomise Test Forms is enabled in the parent test’s Advanced Test Delivery Options. Defaults to false if omitted.
gradeBoundaries object mandatory
Contains the grade boundaries’ information. You can set up to ten custom grade boundaries for your test form. Grade boundaries can be defined on either percentages or numerical scores. Grade boundaries cannot exceed the total marks of all the items in the test form.
gradeBoundaries/type enumeration
Determines whether the grade boundaries are Percentage, Score, or Irt-based.
gradeBoundaries/irtRangeLower integer
The lower IRT theta value. For more information on IRT grade boundaries, read Setting up grade boundaries and About IRT tags.
gradeBoundaries/irtRangeHigher integer
The higher IRT theta value. For more information on IRT grade boundaries, read Setting up grade boundaries and About IRT tags.
gradeBoundaries/boundaries array
Contains each grade boundary’s information.
gradeBoundaries/boundaries/name string
The grade boundary’s name.
gradeBoundaries/boundaries/value integer
The grade boundary’s value. If the gradeBoundaries/type is Irt, the value must be within the set IRT range.
roundToDecimalPlaces integer optional
Determines how many decimal places candidates’ scores are rounded to when retrieved using the Result, AnalyticsResult, or HistoricalResult APIs. If null, candidates’ scores are not rounded. Defaults to null if omitted.
printable Boolean optional
Determines whether the Printable setting is enabled. If true, allows you to print the test form. Defaults to false if omitted.
allowCloseWithoutSubmit Boolean optional
Determines whether the Allow Close Without Submit setting is enabled. If true, allows candidates to exit the test without submitting their answers. Candidates can continue the test at a later stage. Defaults to false if omitted.
allowUseAsTemplate Boolean optional
Determines whether the Allow use as template setting is enabled. If true, enables test form cloning. For more information, read Cloning test forms. Defaults to false if omitted.
requiresModeration Boolean optional
Determines whether the Requires Moderation to release results setting is enabled. If true, prevents candidate scripts from appearing in the Results screen of Test Administration until they have been reviewed by another marker in the Moderate screen. Defaults to false if omitted.
requiresSecureMarker Boolean optional
Determines whether the Mark Scripts in SecureMarker setting is enabled. If true, exports candidate scripts to SecureMarker for marking and moderation. For more information, read Configuring a test form for SecureMarker. Defaults to false if omitted.
advanceContentDownloadTimespan integer optional
Determines whether the Pre-session Download Window (hours) setting is enabled. If an integer is provided, determines how far in advance of the test’s start time candidate test forms are generated and made available for download. Test form content and settings (including item content) are locked once generated and cannot be edited for the scheduled test session. Defaults to 0 if omitted.
testFeedbackPassFail Boolean optional
Determines whether the Pass/Fail test feedback setting is enabled. If true, shows candidates whether they have passed or failed the test after submission. Summary Feedback must also be enabled. Defaults to false if omitted.
testFeedbackPercentageMark Boolean optional
Determines whether the Percentage Mark test feedback setting is enabled. If true, shows candidates their percentage mark after submission. Summary Feedback must also be enabled. Defaults to false if omitted.
testFeedbackShowFeedbackButtonDuringTest Boolean optional
Determines whether the Show Feedback Button During Test test feedback setting is enabled. If true, displays the Feedback button during the test, allowing candidates to see any Correct/Incorrect/General feedback added to items in Item Authoring (legacy tests only). For more information, read Adding candidate feedback to items. Defaults to false if omitted.
testFeedbackSummaryFeedback object optional
Contains the Summary Feedback settings. Candidates are shown a summary of their performance on the test, including which items were answered correctly or incorrectly.
testFeedbackSummaryFeedback/type enumeration
Determines the type of Summary Feedback. The available options are:
- EndOfTest – Candidates receive summary feedback after submitting their test.
- EndOfSection (HTML tests only) – Candidates receive summary feedback after each section in the test. This is only available for HTML tests with timed sections.
- EndOfSectionAndTest (HTML tests only) – Candidates receive summary feedback after each section and after submitting the test. This is only available for HTML tests with timed sections.
Pass/Fail or Percentage Mark must be enabled if you want to use End of Section or End of Section & Test in HTML tests. Can be null if summary feedback is not required. Defaults to EndOfTest if omitted.
testFeedbackSummaryFeedback/reviewAnswers Boolean
Determine whether the Review Answers test feedback setting is enabled. If true, allows candidates to review their responses during the summary feedback. If false, candidates can only see if their answers were correct or incorrect. Defaults to false if omitted.
testFeedbackSummaryFeedback/printableSummary Boolean
Determines whether the Printable Summary test feedback setting is enabled. If true, allows candidates to print the summary feedback. Defaults to false if omitted.
testFeedbackSummaryFeedback/showCandidateDetails Boolean
Determines whether the Show Candidate Details test feedback setting is enabled. If true, displays candidates’ details (name, reference, and so on) during the summary feedback. Defaults to false if omitted.
testFeedbackSummaryFeedback/displayFeedbackByLearningOutcome Boolean
Determines whether the Display Feedback by Learning Outcome test feedback setting is enabled. If true, displays how candidates scored on items with shared tag values. Defaults to false if omitted.
testFeedbackSummaryFeedback/showViewFeedbackButton Boolean
Determines whether the Show View Feedback Button test feedback setting is enabled. If true, allows candidates to view Correct/Incorrect/General feedback left on items during the summary feedback. Review Answers must also be enabled for a candidate to access the feedback button. Defaults to false if omitted.
itemComments Boolean optional
Determines whether the Allow Item Comments test feedback setting is enabled. If true, allows candidates to leave a comment on items during the test for feedback purposes. These comments are viewable in Test Administration (legacy tests only).
You can view comments left by candidates on HTML tests in Reporting. Read ‘About the Candidate Comments panel’ in Viewing Items Delivered Reports for more information. Defaults to false if omitted.
testFormComments array optional
Contains any Test Form Comments information.
section array mandatory
Contains the test form’s sections’ information. Each section must contain at least one item.
section/id integer
The section’s unique identifier.
section/reference string
The section’s unique reference code.
section/name string
The section’s name.
section/type enumeration
The type of section. The available options are:
- Intro – Introduction sections contain any non-scored Introduction Pages presented to candidates at the beginning of a test.
- Finish – Finish sections contain any non-scored Finish Pages presented to candidates at the end of a test.
- Tools – Tools sections contain any tools (images or PDF source materials).
- Fixed – Items in fixed sections are given to candidates in the order specified by the test creator, using “fixed” rules.
- Dynamic – Items in dynamic sections allow items to be automatically pulled from an item pool based on “dynamic” rules.
- SurveyFixed – Survey sections contain non-scored items. Items in survey sections can be delivered using fixed rules.
- SurveyDynamic – Survey sections contain non-scored items. Items in survey sections can be delivered using dynamic rules.
- Adaptive – In adaptive tests, candidates receive items based on their learning ability. For example, if a candidate answers an item incorrectly, they will then receive an easier item.
- ExternalOptimiser – An external optimiser section is used to create LOFT tests. The LOFT/Adaptive screen displays all test forms containing external optimiser sections.
- SectionSelector – Section selectors allow candidates to choose which section(s) to attempt. The test form must be using timed sections to contain a section selector section.
section/duration integer
The section’s duration if the test form is set to Timed Sections.
section/description string
The section description.
section/randomiseItems Boolean
Determines whether the Randomise Items setting is enabled. If true, presents section items to candidates in a random order. Defaults to false if omitted.
section/passMarkType enumeration
Determines whether the pass mark type is Percentage or Score. If this property is omitted, the pass mark type is Score.
section/passMark integer
The section’s pass mark. This cannot exceed the total marks available for the items in the section. Defaults to 0 if omitted.
section/numberOfItemsToMark integer
Determines the Number of items to mark setting, which is the number of items you want to include in a candidate’s final mark. This can be between 1 and 5. Can be null or omitted if the number of items to mark does not need defining, in which case all items are required to be marked. Defaults to null if omitted.
section/unlockSection Boolean
Determines whether the Unlock Section setting is enabled. If true, unlocks SecureClient only for the section, allowing candidates to access apps (including the internet) and their local files if the test form is set to Timed Sections. Defaults to false if omitted.
section/forwardOnlySection Boolean
Determines whether the Forward only section setting is enabled. If true, prevents candidates from returning to items that have already been answered. Candidates can only progress to the next item in the test. Defaults to false if omitted.
section/allowItemReview Boolean
Determines whether the Allow item review setting is enabled. If true, allows candidates in a forward-only section to view previously answered items in a read-only mode. Defaults to false if omitted.
section/allowItemReview Boolean
Determines whether the Items require response setting is enabled. If true, prevents candidates from submitting a test if they have not attempted all items. If the test or section is forward only, candidates must attempt the item before they can move onto the next question. Defaults to false if omitted.
section/sectionBreak object
Contains any candidate break information for the section.
section/sectionBreak/enableBreak Boolean
Determines whether the Enable break after section setting is enabled. If true, adds a break after this section. Defaults to false if omitted.
section/sectionBreak/breakDuration integer
Determines the break duration in minutes.
section/sectionBreak/cancellable Boolean
Determines whether the Cancellable setting is enabled. If true, allows candidates to choose when to leave the break and return to the test. If false, candidates must wait for the break time to expire before returning to the test. Defaults to true if omitted.
section/items array
Contains the items in the section.
section/items/id integer
The item’s unique identifier.
section/items/nonScored Boolean
Determines whether the item is a scored (false) or non-scored (true) item. Defaults to true for questions or false for basic pages, if omitted.
section/items/group object
Contains any item groups’ information. You can group items so they appear on a single scrollable page when delivered to candidates.
section/items/group/name string
The item group’s name.
section/items/group/items array
Contains the items in the group’s information.
section/items/group/items/id integer
The item’s unique identifier.
section/items/group/items/nonScored Boolean
Determines whether the item is a scored (false) or non-scored (true) item. Defaults to true for questions or false for basic pages, if omitted.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the new test form’s details.
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TestForm/1",
"errors": null
}Updating a test form
Send a request to the endpoint to update a specific test form.
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 update a test form. Refer to the request body schema for all properties that can be updated.
{
"id": 1,
"reference": "TestForm1",
"name": "Final Year Geography Test Form July 2022",
"subject": {
"id": 1
},
"test": {
"reference": "Test1"
},
"status": 1,
"validFromDate": "2019-10-09T00:00:00",
"validToDate": "2029-10-09T00:00:00",
"timing": {
"type": "Untimed"
},
"gradeBoundaries": {
"type": "Score",
"irtRangeLower": -4,
"irtRangeHigher": 4,
"boundaries": [
{
"name": "Fail",
"value": null
},
{
"name": "Pass",
"value": 1
}
]
},
"section": [
{
"name": "Section 1",
"type": "Fixed",
"items": [
{
"id": 1
}
]
}
]
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
id integer mandatory
The test form’s unique identifier.
reference string mandatory
The test form’s unique reference code.
name string mandatory
The test form’s name.
subject object mandatory
Contains the subject that the test is in.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
test object mandatory
Contains the test’s information.
test/id integer
The test’s unique identifier.
test/reference string
The test’s unique reference code.
test/href string
The endpoint to call the test’s information, such as /api/v2/Test/{id} where {id} is the test’s unique identifier.
metadata array optional
status enumeration optional
The test form’s workflow status. The available workflow statuses are Draft, Live, Retired, and QualityReview. Every test form starts at Draft and must be set to Live before it can be scheduled.
Each status also has a unique identifier that can be used instead:
- 0 – Retired
- 1 – Draft
- 2 – Live
- 3 – QualityReview
validFromDate string mandatory
Sets the Valid From date for the date range in which the test form can be scheduled for candidates, in YYYY/MM/DD format.
validToDate string mandatory
Sets the Expires date for the date range in which the test can be scheduled for candidates, in YYYY/MM/DD format.
timing array mandatory
Contains the Test Duration settings’ information.
timing/type enumeration
Determines the test form’s timing type. The available options are:
- Untimed – Candidates have unlimited time to complete and submit their responses.
- Timed – The whole test form has a specified time limit in which candidates must complete and submit their responses.
- Timed Sections – Each section in the test form has an individual time limit. Candidates can only work in one timed section at a time. If the candidate decides to leave the section, they cannot return and their remaining time in that section is lost. You can combine timed sections into pools to allow candidates to manage their time between them.
timing/testDuration integer
The test form’s duration. Ignored if the timing/type is Untimed.
timing/addBreak Boolean
If the test form’s timing/type is Timed Sections, determines whether the test form has candidate breaks enabled.
timing/addBreakType enumeration
Determines whether the candidate breaks are Fixed or Pooled.
timing/addBreakPoolDuration integer
The pooled break’s duration. Ignored if the timing/addBreakType is Fixed.
reasonableAdjustmentsStandard integer optional
The extra time given to all candidates with reasonable adjustments, in minutes.
reasonableAdjustmentsMax integer optional
How much extra time invigilators can award to candidates with reasonable adjustments, in minutes.
excludeFromRandomTestFormSelection Boolean optional
Determines whether the Exclude from Random Test Form Selection setting is enabled. If true, prevents the test form from being randomly selected at the point of scheduling if Randomise Test Forms is enabled in the parent test’s Advanced Test Delivery Options.
gradeBoundaries object mandatory
Contains the grade boundaries’ information. You can set up to ten custom grade boundaries for your test form. Grade boundaries can be defined on either percentages or numerical scores. Grade boundaries cannot exceed the total marks of all the items in the test form.
gradeBoundaries/type enumeration
Determines whether the grade boundaries are Percentage, Score, or Irt-based.
gradeBoundaries/irtRangeLower integer
The lower IRT theta value. For more information on IRT grade boundaries, read Setting up grade boundaries and About IRT tags.
gradeBoundaries/irtRangeHigher integer
The higher IRT theta value. For more information on IRT grade boundaries, read Setting up grade boundaries and About IRT tags.
gradeBoundaries/boundaries array
Contains each grade boundary’s information.
gradeBoundaries/boundaries/name string
The grade boundary’s name.
gradeBoundaries/boundaries/value integer
The grade boundary’s value. If the gradeBoundaries/type is Irt, the value must be within the set IRT range.
roundToDecimalPlaces integer optional
Determines how many decimal places candidates’ scores are rounded to when retrieved using the Result, AnalyticsResult, or HistoricalResult APIs. If null, candidates’ scores are not rounded.
printable Boolean optional
Determines whether the Printable setting is enabled. If true, allows you to print the test form.
allowCloseWithoutSubmit Boolean optional
Determines whether the Allow Close Without Submit setting is enabled. If true, allows candidates to exit the test without submitting their answers. Candidates can continue the test at a later stage.
allowUseAsTemplate Boolean optional
Determines whether the Allow use as template setting is enabled. If true, enables test form cloning. For more information, read Cloning test forms.
requiresModeration Boolean optional
Determines whether the Requires Moderation to release results setting is enabled. If true, prevents candidate scripts from appearing in the Results screen of Test Administration until they have been reviewed by another marker in the Moderate screen.
requiresSecureMarker Boolean optional
Determines whether the Mark Scripts in SecureMarker setting is enabled. If true, exports candidate scripts to SecureMarker for marking and moderation. For more information, read Configuring a test form for SecureMarker.
advanceContentDownloadTimespan integer optional
Determines whether the Pre-session Download Window (hours) setting is enabled. If an integer is provided, determines how far in advance of the test’s start time candidate test forms are generated and made available for download. Test form content and settings (including item content) are locked once generated and cannot be edited for the scheduled test session.
testFeedbackPassFail Boolean optional
Determines whether the Pass/Fail test feedback setting is enabled. If true, shows candidates whether they have passed or failed the test after submission. Summary Feedback must also be enabled.
testFeedbackPercentageMark Boolean optional
Determines whether the Percentage Mark test feedback setting is enabled. If true, shows candidates their percentage mark after submission. Summary Feedback must also be enabled.
testFeedbackShowFeedbackButtonDuringTest Boolean optional
Determines whether the Show Feedback Button During Test test feedback setting is enabled. If true, displays the Feedback button during the test, allowing candidates to see any Correct/Incorrect/General feedback added to items in Item Authoring (legacy tests only). For more information, read Adding candidate feedback to items.
testFeedbackSummaryFeedback object optional
Contains the Summary Feedback settings. Candidates are shown a summary of their performance on the test, including which items were answered correctly or incorrectly.
testFeedbackSummaryFeedback/type enumeration
Determines the type of Summary Feedback. The available options are:
- EndOfTest – Candidates receive summary feedback after submitting their test.
- EndOfSection (HTML tests only) – Candidates receive summary feedback after each section in the test. This is only available for HTML tests with timed sections.
- EndOfSectionAndTest (HTML tests only) – Candidates receive summary feedback after each section and after submitting the test. This is only available for HTML tests with timed sections.
Pass/Fail or Percentage Mark must be enabled if you want to use End of Section or End of Section & Test in HTML tests. Can be null if summary feedback is not required.
testFeedbackSummaryFeedback/reviewAnswers Boolean
Determine whether the Review Answers test feedback setting is enabled. If true, allows candidates to review their responses during the summary feedback. If false, candidates can only see if their answers were correct or incorrect.
testFeedbackSummaryFeedback/printableSummary Boolean
Determines whether the Printable Summary test feedback setting is enabled. If true, allows candidates to print the summary feedback.
testFeedbackSummaryFeedback/showCandidateDetails Boolean
Determines whether the Show Candidate Details test feedback setting is enabled. If true, displays candidates’ details (name, reference, and so on) during the summary feedback.
testFeedbackSummaryFeedback/displayFeedbackByLearningOutcome Boolean
Determines whether the Display Feedback by Learning Outcome test feedback setting is enabled. If true, displays how candidates scored on items with shared tag values.
testFeedbackSummaryFeedback/showViewFeedbackButton Boolean
Determines whether the Show View Feedback Button test feedback setting is enabled. If true, allows candidates to view Correct/Incorrect/General feedback left on items during the summary feedback. Review Answers must also be enabled for a candidate to access the feedback button.
itemComments Boolean optional
Determines whether the Allow Item Comments test feedback setting is enabled. If true, allows candidates to leave a comment on items during the test for feedback purposes. These comments are viewable in Test Administration (legacy tests only).
You can view comments left by candidates on HTML tests in Reporting. Read ‘About the Candidate Comments panel’ in Viewing Items Delivered Reports for more information.
testFormComments array optional
Contains any Test Form Comments information.
section array mandatory
Contains the test form’s sections’ information. Each section must contain at least one item.
section/id integer
The section’s unique identifier.
section/reference string
The section’s unique reference code.
section/name string
The section’s name.
section/type enumeration
The type of section. The available options are:
- Intro – Introduction sections contain any non-scored Introduction Pages presented to candidates at the beginning of a test.
- Finish – Finish sections contain any non-scored Finish Pages presented to candidates at the end of a test.
- Tools – Tools sections contain any tools (images or PDF source materials).
- Fixed – Items in fixed sections are given to candidates in the order specified by the test creator, using “fixed” rules.
- Dynamic – Items in dynamic sections allow items to be automatically pulled from an item pool based on “dynamic” rules.
- SurveyFixed – Survey sections contain non-scored items. Items in survey sections can be delivered using fixed rules.
- SurveyDynamic – Survey sections contain non-scored items. Items in survey sections can be delivered using dynamic rules.
- Adaptive – In adaptive tests, candidates receive items based on their learning ability. For example, if a candidate answers an item incorrectly, they will then receive an easier item.
- ExternalOptimiser – An external optimiser section is used to create LOFT tests. The LOFT/Adaptive screen displays all test forms containing external optimiser sections.
- SectionSelector – Section selectors allow candidates to choose which section(s) to attempt. The test form must be using timed sections to contain a section selector section.
section/duration integer
The section’s duration if the test form is set to Timed Sections.
section/description string
The section description.
section/randomiseItems Boolean
Determines whether the Randomise Items setting is enabled. If true, presents section items to candidates in a random order.
section/passMarkType enumeration
Determines whether the pass mark type is Percentage or Score. If this property is omitted, the pass mark type is Score.
section/passMark integer
The section’s pass mark. This cannot exceed the total marks available for the items in the section.
section/numberOfItemsToMark integer
Determines the Number of items to mark setting, which is the number of items you want to include in a candidate’s final mark. This can be between 1 and 5. Can be null or omitted if the number of items to mark does not need defining, in which case all items are required to be marked.
section/unlockSection Boolean
Determines whether the Unlock Section setting is enabled. If true, unlocks SecureClient only for the section, allowing candidates to access apps (including the internet) and their local files if the test form is set to Timed Sections.
section/forwardOnlySection Boolean
Determines whether the Forward only section setting is enabled. If true, prevents candidates from returning to items that have already been answered. Candidates can only progress to the next item in the test.
section/allowItemReview Boolean
Determines whether the Allow item review setting is enabled. If true, allows candidates in a forward-only section to view previously answered items in a read-only mode.
section/allowItemReview Boolean
Determines whether the Items require response setting is enabled. If true, prevents candidates from submitting a test if they have not attempted all items. If the test or section is forward only, candidates must attempt the item before they can move onto the next question.
section/sectionBreak object
Contains any candidate break information for the section.
section/sectionBreak/enableBreak Boolean
Determines whether the Enable break after section setting is enabled. If true, adds a break after this section.
section/sectionBreak/breakDuration integer
Determines the break duration in minutes.
section/sectionBreak/cancellable Boolean
Determines whether the Cancellable setting is enabled. If true, allows candidates to choose when to leave the break and return to the test. If false, candidates must wait for the break time to expire before returning to the test.
section/items array
Contains the items in the section.
section/items/id integer
The item’s unique identifier.
section/items/nonScored Boolean
Determines whether the item is a scored (false) or non-scored (true) item.
section/items/group object
Contains any item groups’ information. You can group items so they appear on a single scrollable page when delivered to candidates.
section/items/group/name string
The item group’s name.
section/items/group/items array
Contains the items in the group’s information.
section/items/group/items/id integer
The item’s unique identifier.
section/items/group/items/nonScored Boolean
Determines whether the item is a scored (false) or non-scored (true) item.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the updated test form’s details.
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TestForm/1",
"errors": null,
}Test Form Sections
The TestForm API resource can be used to retrieve and update test form sections.
To learn more about test form sections, see the About test form content article in the Test Creation section of the Surpass documentation.
Retrieving test form section information
Send a request to the endpoint to retrieve information for a specific test form section 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/TestForm/{id}/Section/{id} |
Returns information for the specified test form, where {id} is the test form’s unique identifier, and {id} is the section’s unique identifier. |
|
reference |
path OPTIONAL |
/api/v2/TestForm/{reference}/Section/{id} |
Returns information for the specified test form, where {reference} is the test form’s unique reference code, and {id} is the section’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": [
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TestForm/1/section/1",
"name": "Section",
"decisionPoint": null,
"type": "Fixed",
"additionalMediaReplays": null,
"itemsCount": 3
}
],
"errors": null
}Response schema
The response schema contains a description of every property that can be returned for this endpoint.
count integer
Details how many sections there are in total. This is null because the information retrieved is for a specific section.
top integer
Details number of sections returned in the response. This is null because the information retrieved is for a specific section.
skip integer
Details how many sections were skipped to display those in the response. This is null because the information retrieved is for a specific section.
pageCount integer
Details how many pages of sections there are. This is null because the information retrieved is for a specific section.
nextPageLink string
The endpoint to call the next page of sections. This is null because the information retrieved is for a specific section.
prevPageLink string
The endpoint to call the previous page of sections. This is null because the information retrieved is for a specific section.
response array
Contains the rest of the response.
id integer
The section’s unique identifier.
href string
The endpoint to call the section’s information, such as /api/v2/TestForm/{id}/Section/{id} where {id} is the test form’s unique identifier and {id} is the section’s unique identifier.
name string
The section’s name.
decisionPoint object
type enumeration
The type of section. The available options are:
- Intro – Introduction sections contain any non-scored Introduction Pages presented to candidates at the beginning of a test.
- Finish – Finish sections contain any non-scored Finish Pages presented to candidates at the end of a test.
- Tools – Tools sections contain any tools (images or PDF source materials).
- Fixed – Items in fixed sections are given to candidates in the order specified by the test creator, using “fixed” rules.
- Dynamic – Items in dynamic sections allow items to be automatically pulled from an item pool based on “dynamic” rules.
- SurveyFixed – Survey sections contain non-scored items. Items in survey sections can be delivered using fixed rules.
- SurveyDynamic – Survey sections contain non-scored items. Items in survey sections can be delivered using dynamic rules.
- Adaptive – In adaptive tests, candidates receive items based on their learning ability. For example, if a candidate answers an item incorrectly, they will then receive an easier item.
- ExternalOptimiser – An external optimiser section is used to create LOFT tests. The LOFT/Adaptive screen displays all test forms containing external optimiser sections.
- SectionSelector – Section selectors allow candidates to choose which section(s) to attempt. The test form must be using timed sections to contain a section selector section.
additionalMediaReplays object
Contains the section-level media replay limit.
itemsCount integer
The number of items in the section.
errors string
Information about any errors that occurred during the request.
Updating a test form section
Send a request to the endpoint to update a specific test form section.
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/TestForm/{id}/Section/{id} |
Updates specified test form, where {id} is the test form’s unique identifier, and {id} is the section’s unique identifier. |
|
reference |
path OPTIONAL |
/api/v2/TestForm/{reference}/Section/{id} |
Updates specified test form, where {reference} is the test form’s unique reference code, and {id} is the section’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.
{
"name": "Easy Section"
}Response schema
The response schema contains a description of every property that can be returned for this endpoint.
name string
The section’s name.
decisionPoint object
additionalMediaReplays object
Contains the section-level media replay limit.
errors string
Information about any errors that occurred during the request.
Test Form Metadata
The TestForm API resource can be used to retrieve metadata.
Retrieving test form metadata information
Send a request to the endpoint to retrieve information for specific test form metadata using either its ID or reference. No request body is required.
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.
EXAMPLE: The test form’s unique reference code is not unique. In this instance, use its unique identifier instead.
|
|
InvalidId |
16 |
The ID number used in the request is invalid. |
|
InvalidODataOperation |
19 |
There is an issue with the query parameters. |
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: