TestForm Resource

The TestForm Resource can be used to retrieve:
  • test form information
  • section structure
  • section settings
  • item data
The TestForm Resource can also be used to update a test form, such as section data. However, the user specified in the header of the request must have the 'Create Tests' role in Surpass.

TestForm Resource

Below are a list of operations, HTTP verbs and an example URL for the TestForm Resource within the Surpass API.
OperationHTTP VerbExample URL
Read test form information using the IDGEThttps://...surpass.com/api/v2/TestForm/{id}?includeItems=true
Read test form information using the test form referenceGEThttps://...surpass.com/api/v2/TestForm/{reference}?includeItems=true  
Read section data using the test form ID and section IDGEThttps://...surpass.com/api/v2/TestForm/{reference}?includeItems=true   
Read section data using the test form reference and section IDGEThttps://...surpass.com/api/v2/TestForm/{reference}/section/{sectionID]
Update section using test form ID and section IDPUThttps://...surpass.com/api/v2/TestForm/{id}/section/{sectionID}
Update section using test form reference and section IDPUThttps://...surpass.com/api/v2/TestForm/{reference}/section/{sectionID}
Read specific test form metadata using test form ID and metadata IDGEThttps://...surpass.com/api/v2/TestForm/{id}/metadata/{metadataID}
Read specific test form metadata using test form reference and metadata IDGEThttps://...surpass.com/api/v2/TestForm/{reference}/section/{sectionID}
Attributes for the TestForm resource

The table below lists all the attributes included in the TestForm Resource for the GET request. This includes the attribute name, data type, as well as some further information about those attributes.
Attribute NameTypeNotes
idintegerThe test form ID.
referencestringThe test form reference.
hrefstringThe URL.
namestringThe test form name.
subject / idintegerThe subject ID.
subject / referencestringThe subject reference.
test / idintegerThe test ID.
test / referencestringThe test reference.
section / namestringThe section name.
typestringThe section type, such as 'Fixed', 'Dynamic', 'External Optimiser' or 'Section Selector'.
itemsCountintegerThe number of items in the section.
items / idintegerThe item ID.
surpassIdintegerThe item ID prefixed with the subject ID. This is the subject where the item is stored.
metadatalist <MetadataBaseResource>
The additional uploaded data from Test Creation, such as an uploaded scale score.
statusstringThe test form workflow status.
validFromDatedate/timeWhen the test form is valid from. Format: YYYY-MM-DDT00:00:00.
validToDatedate/timeWhen the test form is valid to. Format: YYYY-MM-DDT00:00:00.
errorsstringA list of any errors made from the GET call.

The table below lists all the attributes included in the TestForm Resource for the PUT request. This includes the attribute name, data type, as well as some further information about those attributes.

Attribute NameTypeNotes
namestringThe section name.
decisionPointDecisionPointIn the section properties, you can change the pass type to 'Progress Range' for HTML tests with timed sections. The below attributes set up the values for the progress range in either marks or percentages.
upperValueintegerThe number of marks a candidate should achieve to complete a test, so they won't have to move on to further sections.
lowerValueintegerCandidates who fall within the lower and upper value will have to continue to the next section in the test in order to complete it.
valueTypestring'Mark' or 'Percentage' (for the progress range).
sectionsToCheckstringWhich section the range should apply to (such as 'Current Only').
additionalMediaReplaysadditionalMediaReplaysIf you want to set a section-level media replay limit, enable this setting. This is only available via the API.
valueintegerThe number of media replays allowed in a section.

Example GET response

Below are two examples of successful GET responses. One is a JSON response, the other is an XML response.


Feedback and Knowledge Base