Item OAPI

An item is a page that appears in a test. Items may be scored questions (for example, Multiple Choice items), non-scored surveys (for example, Likert items), basic pages (for example, Introduction, Information, and Finish Pages), or item sets.

The Item OAPI resource can be used to list, retrieve, create, and delete scored question items. Essay items can be updated. If item language variants are enabled, you can also use the Item OAPI to list, retrieve, and create item language variants.

To learn more about items, see the Item Authoring section of the Surpass documentation.

This article explains what calls can be made to the Surpass OAPI using the Item resource.

Import this API into your Postman Workspace

Listing items

get /oapi/Item

Send a request to the endpoint to retrieve a list of items. 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.

EXAMPLE: The endpoint /oapi/Item?filter=type eq MultipleChoice would return Multiple Choice questions only.

NOTE: An authorization header is mandatory, but the required input may vary. Read Connecting to the Surpass OAPI for more information on authentication and authorisation.

Name	Parameter	Input	Description
authorization	header OPTIONAL	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
authorization	header OPTIONAL	`Bearer {token}`	A bearer token must be passed to authorise the user’s request, where `{token}` is a JWT (JSON web token).
accept	header OPTIONAL	`application/json`	Determines data format of the response (JSON).
fieldsNames	query OPTIONAL	`/oapi/Item?fieldsNames={fieldsNames}`	Includes additional properties in the response not returned as standard, where `{fieldsNames}` is one of the following properties returned when retrieving information for a specific item: `reference`, `createdBy`, `lastEditedBy`, `parent`, `createDate`, `updateDate`, `contentUpdateDate`, `tagGroups`, `enemyItems`, `status`, `mark`, `owner`, `stemComponents`, `purpose`, `markingType`, `citations`, `version`, `comments`, `assistiveMedia`, `sourceMaterials`, `mediaLayout`, `allowOpenImageInPopup`, `itemTools`, `standardLists`, `sharedWith`, `sharedMediaItems`.
filter	query OPTIONAL	`/oapi/Item?filter={filter} {operator} {value}`	Filters results, searching for an exact match or for the data to contain a defined value. For an exact match: `{filter}` is one of `id`, `name`, `type`, `subject.id`, `subject.reference`, `isDeleted`; `{operator}` is `eq` (equal to); and `{value}` is the string, Boolean, or integer the filter query looks for an exact match for in the request. For a greater than query: `{filter}` is `id`, `subject.id`; `{operator}` is `ge` (greater than); and `{value}` is the integer the filter looks for more than in the request. For a less than query: `{filter}` is `id`, `subject.id`; `{operator}` is `le` (less than); and `{value}` is the integer the filter looks for less than in the request. For a contains query: `{filter}` is one of `name`, `subject.name`; `{operator}` is `contains`; and `{value}` is the string the filter query looks for an exact match for in the request.
filterGrouping	query OPTIONAL	`/oapi/Item?filter={filter} {operator} {value}&filter={filter} {operator} {value}&filterGrouping={integer} {operator} {integer}`	Used to create different Boolean combinations when multiple properties are joined within a filter query parameter. See filter above. Each `{integer}` represents a respective filter starting at `0`, which are then combined using an `AND` or `OR` Boolean `{operator}`. EXAMPLE: The endpoint `/oapi/Item?filter=type eq MultipleChoice&filter=type eq MultipleResponse&filterGrouping=0 OR 1` would return both Multiple Choice (`0`) and Multiple Response (`1`) questions. TIP: More than two filter parameters can be combined, for example you might group three filters as follows: `0 AND 1 OR 2`.
orderBy	query OPTIONAL	`/oapi/Item?orderBy=fieldName={fieldName}&ascending={operator}`	Determines order of results, where `{fieldName}` is one of `id`, `reference`, `type`, `isDeleted`; and `{operator}` is `true` or `false`.
take	query OPTIONAL	`/oapi/Item?take={take}`	Defines number of responses to return when paging a response, where `{take}` is a number between 1 and 100.
skip	query OPTIONAL	`/oapi/Item?skip={skip}`	Defines how many responses to skip when paging a response, where `{skip}` is a number that should not exceed the total number of responses.

TIP: Multiple query parameters can be joined using &, for example the endpoint /oapi/Item?take=10&skip=25 would skip the first 25 results and return 10.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the information in JSON format as requested.

{
    "count": 14975,
    "top": 10,
    "skip": 0,
    "totalPages": 1498,
    "nextPageLink": "https://{your Surpass instance}.surpass.com:443/oapi/Item?Skip=10&Take=10",
    "previousPageLink": null,
    "results": [
        {
            "id": 1,
            "name": "Multiple Choice question 1",
            "type": "MultipleChoice",
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1",
                "centre": {
                    "id": 1,
                    "reference": "Centre1",
                    "name": "Surpass Centre"
                }
            },
            "isDeleted": false
        },
        {
            "id": 2,
            "name": "Multiple Choice question 2",
            "type": "MultipleChoice",
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1",
                "centre": {
                    "id": 1,
                    "reference": "Centre1",
                    "name": "Surpass Centre"
                }
            },
            "isDeleted": false
        },
        {
            "id": 3,
            "name": "Multiple Choice question 3",
            "type": "MultipleChoice",
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1",
                "centre": {
                    "id": 1,
                    "reference": "Centre1",
                    "name": "Surpass Centre"
                }
            },
            "isDeleted": false
        },
        {
            "id": 4,
            "name": "Multiple Choice question 4",
            "type": "MultipleChoice",
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1",
                "centre": {
                    "id": 1,
                    "reference": "Centre1",
                    "name": "Surpass Centre"
                }
            },
            "isDeleted": false
        },
        {
            "id": 5,
            "name": "Multiple Choice question 5",
            "type": "MultipleChoice",
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1",
                "centre": {
                    "id": 1,
                    "reference": "Centre1",
                    "name": "Surpass Centre"
                }
            },
            "isDeleted": false
        },
        {
            "id": 6,
            "name": "Multiple Choice question 6",
            "type": "MultipleChoice",
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1",
                "centre": {
                    "id": 1,
                    "reference": "Centre1",
                    "name": "Surpass Centre"
                }
            },
            "isDeleted": false
        },
        {
            "id": 7,
            "name": "Multiple Choice question 7",
            "type": "MultipleChoice",
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1",
                "centre": {
                    "id": 1,
                    "reference": "Centre1",
                    "name": "Surpass Centre"
                }
            },
            "isDeleted": false
        },
        {
            "id": 8,
            "name": "Multiple Choice question 8",
            "type": "MultipleChoice",
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1",
                "centre": {
                    "id": 1,
                    "reference": "Centre1",
                    "name": "Surpass Centre"
                }
            },
            "isDeleted": false
        },
        {
            "id": 9,
            "name": "Multiple Choice question 9",
            "type": "MultipleChoice",
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1",
                "centre": {
                    "id": 1,
                    "reference": "Centre1",
                    "name": "Surpass Centre"
                }
            },
            "isDeleted": false
        },
        {
            "id": 10,
            "name": "Multiple Choice question 10",
            "type": "MultipleChoice",
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1",
                "centre": {
                    "id": 1,
                    "reference": "Centre1",
                    "name": "Surpass Centre"
                }
            },
            "isDeleted": false
        }
    ],
    "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 items there are in total.

top integer

Details number of items returned in the response.

skip integer

Details how many items were skipped to display those in the response.

totalPages integer

Details how many pages of items there are.

nextPageLink string

The endpoint to call the next page of items. If null, the response is the last page of items.

previousPageLink string

The endpoint to call the previous page of items. If null, the response is the first page of items.

results array

Contains the rest of the response.

NOTE: If the response contains multiple items, a separate object is returned for each item.

id integer

The item’s unique identifier.

name string

The item’s name.

type enumeration

The item type, which can be one of MultipleChoice, MultipleResponse, EitherOr, NumericalEntry, FillInTheBlank, ShortAnswer, Essay, SelectFromAList, MatchingBoxes (Extended Matching questions), FileAttach, DragAndDrop, EquationEntry, HotSpot, Spreadsheet, VoiceCapture, CqtItem (Custom Question type questions), FractionEntryItem, MultipleChoiceSurvey, MultipleResponseSurvey, Likert, or ItemSet.

subject object

Contains the subject that the item is in.

subject/id integer

The subject’s unique identifier.

NOTE: The subject/id returned by the Surpass OAPI is from a different database to the one returned by the Surpass API v2; these values may be in sync, but that might not always be the case. If you are receiving different identifiers for the same subject from the OAPI and API v2, you can use subject/reference to reconcile your subject's properties instead.

subject/reference string

The subject’s unique reference code.

subject/name string

The subject’s name.

subject/href string

The endpoint to call the subject’s information, such as /api/v2/Subject?reference={reference} where {reference} is the subject’s unique reference code.

subject/centre object

The subject’s primary centre. Subjects can only be associated with one centre by default, but can also be shared with other centres. Any tests created in the subject can be scheduled at the associated centre(s).

subject/centre/id integer

The unique identifier of the subject’s primary centre.

subject/centre/reference string

The unique reference code of the subject’s primary centre.

subject/centre/name string

The name of the subject’s primary centre.

isDeleted Boolean

Determines whether the item is in its subject’s recycle bin.

serverTimeZone enumeration

The timezone of the server sending the response.

Listing item versions

get /oapi/Item/versions/{id}

Send a request to the endpoint to retrieve a list of items. Refer to the available parameters to influence the response. No request body is required.

IMPORTANT: Version Compare must be enabled on your Surpass instance for this endpoint to work. If you would like Version Compare enabled on your Surpass instance, speak to your Surpass Customer Success Manager.

Parameters

NOTE: An authorization header is mandatory, but the required input may vary. Read Connecting to the Surpass OAPI for more information on authentication and authorisation.

Name	Parameter	Input	Description
authorization	header OPTIONAL	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
authorization	header OPTIONAL	`Bearer {token}`	A bearer token must be passed to authorise the user’s request, where `{token}` is a JWT (JSON web token).
accept	header OPTIONAL	`application/json`	Determines data format of the response (JSON).
id	path MANDATORY	`/oapi/Item/versions/{id}`	Returns a list of versions for the specified item, where `{id}` is the item’s unique identifier.
languageCode	path OPTIONAL	`/oapi/Item/versions/{id}/LanguageVariant/{languageCode}`	Returns a list of versions for the specified item language variant, where `{id}` is the item’s unique identifier and `{languageCode}` is the language variant’s ISO code. NOTE: Item language variants are not available by default. If you would like item language variants enabled on your Surpass instance, contact your Surpass Customer Success Manager.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the information in JSON format as requested.

{
    "count": 5,
    "top": null,
    "skip": null,
    "totalPages": null,
    "nextPageLink": null,
    "previousPageLink": null,
    "results": [
        {
            "version": "1.1",
            "href": "https://{your Surpass instance}.surpass.com/oapi/Item/1?version=1"
        },
        {
            "version": "2.0",
            "href": "https://{your Surpass instance}.surpass.com/oapi/Item/1?version=2"
        },
        {
            "version": "3.0",
            "href": "https://{your Surpass instance}.surpass.com/oapi/Item/1?version=3"
        },
        {
            "version": "4.0",
            "href": "https://{your Surpass instance}.surpass.com/oapi/Item/1?version=4"
        },
        {
            "version": "5.0",
            "href": "https://{your Surpass instance}.surpass.com/oapi/Item/1?version=5"
        }
    ],
    "serverTimeZone": "GMT Standard Time"
}

Retrieving item information

get /oapi/Item/{id}

Send a request to the endpoint to retrieve information for a specific item using its ID. No request body is required.

If item language variants are enabled, you can also use the Item OAPI to retrieve specific item language variant information by passing a languageCode path parameter in a request’s header.

Parameters

NOTE: An authorization header is mandatory, but the required input may vary. Read Connecting to the Surpass OAPI for more information on authentication and authorisation.

Name	Parameter	Input	Description
authorization	header OPTIONAL	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
authorization	header OPTIONAL	`Bearer {token}`	A bearer token must be passed to authorise the user’s request, where `{token}` is a JWT (JSON web token).
accept	header OPTIONAL	`application/json`	Determines data format of the response (JSON).
id	path OPTIONAL	`/oapi/Item/{id}`	Returns information for the specified item, where `{id}` is the item’s unique identifier.
version	query OPTIONAL	`/oapi/Item/{id}?version={version}`	Returns information for the specified item version, where `{id}` is the item’s unique identifier and `{version}` is the item’s major version number. NOTE: Version Compare must be enabled on your Surpass instance for this endpoint to work. If you would like Version Compare enabled on your Surpass instance, speak to your Surpass Customer Success Manager.
languageCode	path OPTIONAL	`/oapi/Item/{id}/LanguageVariant/{languageCode}`	Returns information for the specified item language variant, where `{id}` is the item’s unique identifier and `{languageCode}` is the language variant’s ISO code. NOTE: Item language variants are not available by default. If you would like item language variants enabled on your Surpass instance, contact your Surpass Customer Success Manager.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the information in JSON format as requested.

{
    "response": {
        "name": "Geography MCQ1",
        "id": 1,
        "reference": "MCQ1",
        "type": "MultipleChoice",
        "subject": {
            "id": 1,
            "reference": "Subject1",
            "name": "Geography Subject",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1",
            "centre": {
                    "id": 1,
                    "reference": "Centre1",
                    "name": "Surpass Centre"
                }
        },
        "createdBy": {
            "id": 1,
            "reference": "User1",
            "name": "Stuart Fenwick",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/User?reference=User1"
        },
        "lastEditedBy": {
            "id": 1,
            "reference": "User1",
            "name": "Stuart Fenwick",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/User?reference=User1"
        },
        "parent": null,
        "createDate": "2022-09-21T18:17:54.213",
        "updateDate": "2023-02-10T10:36:29.397",
        "contentUpdateDate": "2023-02-10T10:19:34.203",
        "isDeleted": false,
        "language": {
            "code": "en",
            "name": "UK"
        },
        "tagGroups": [],
        "enemyItems": [
            {
                "isSectionOnly": false,
                "isPrincipal": false,
                "child": null,
                "item": {
                    "id": 2,
                    "reference": "MCQ2",
                    "type": "MultipleChoice",
                    "name": "Geography MCQ2",
                    "position": 0,
                    "href": "https://{your Surpass instance}.surpass.com/oapi/Item/2",
                    "subjectId": 1
                }
            }
        ],
        "status": "Live",
        "mark": 1,
        "owner": {
            "id": 1,
            "reference": "User1",
            "name": "Stuart Fenwick",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/User?reference=User1"
        },
        "stemComponents": [
            {
                "contentType": "RichText",
                "content": "<p>What is the capital of France?</p>"
            }
        ],
        "purpose": "Unspecified",
        "markingType": "Computer",
        "citations": null,
        "version": "2.0",
        "languageVariants": [],
        "comments": [],
        "generalFeedback": null,
        "correctFeedback": {
            "text": "<p>Correct</p>",
            "mediaItems": [],
            "sourceMaterials": []
        },
        "incorrectFeedback": {
            "text": "<p>Incorrect</p>",
            "mediaItems": [],
            "sourceMaterials": []
        },
        "sourceMaterials": [],
        "assistiveMedia": null,
        "mediaItems": [],
        "mediaLayout": "AutoSelect",
        "allowOpenImageInPopup": false,
        "itemTools": [],
        "sharedWith": [],
        "standardLists": [],
        "sharedQuestionText": null,
        "sharedMediaItems": null,
        "answerOptions": [
            {
                "id": 1,
                "label": "A",
                "answerColumns": [
                    {
                        "contentType": "RichText",
                        "content": "<p><span style="font-size:14px">Paris</span></p>",
                        "media": null
                    }
                ],
                "assistiveMedia": null,
                "rationaleText": null,
                "exclusiveOption": false,
                "correct": true
            },
            {
                "id": 2,
                "label": "B",
                "answerColumns": [
                    {
                        "contentType": "RichText",
                        "content": "<p><span style="font-size:14px">London</span></p>",
                        "media": null
                    }
                ],
                "assistiveMedia": null,
                "rationaleText": null,
                "exclusiveOption": false,
                "correct": false
            },
            {
                "id": 3,
                "label": "C",
                "answerColumns": [
                    {
                        "contentType": "RichText",
                        "content": "<p><span style="font-size:14px">Madrid</span></p>",
                        "media": null
                    }
                ],
                "assistiveMedia": null,
                "rationaleText": null,
                "exclusiveOption": false,
                "correct": false
            }
        ],
        "randomise": true,
        "exclusiveOptionEnabled": false,
        "answerWidthRatio": null,
        "addLabelsToOptions": true,
        "tableOptionsHtml": null,
        "markType": "Standard",
        "rationaleEnabled": false
    },
    "serverTimeZone": "GMT Standard Time"
}

Response schema

The response schema contains a description of every of every property that can be returned for this endpoint.

response object

Contains the rest of the response.

name string

The item’s name.

id integer

The item’s unique identifier.

reference string

The item’s unique reference code.

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/name string

The subject’s name.

subject/href string

The endpoint to call the subject’s information, such as /api/v2/Subject?reference={reference} where {reference} is the subject’s unique reference code.

subject/centre object

subject/centre/id integer

The unique identifier of the subject’s primary centre.

subject/centre/reference string

The unique reference code of the subject’s primary centre.

subject/centre/name string

The name of the subject’s primary centre.

createdBy object

Contains the item creator’s information.

createdBy/id integer

The item creator’s unique identifier.

createdBy/reference string

The item creator’s unique reference code.

createdBy/name string

The item creator’s name.

createdBy/href string

The endpoint to call the item creator’s information, such as /api/v2/User?reference={reference} where {reference} is the item creator’s unique reference code.

lastEditedBy object

Contains the user who last edited the item’s information.

lastEditedBy/id integer

The user who last edited the item’s unique identifier.

lastEditedBy/reference string

The user who last edited the item’s unique reference code.

lastEditedBy/name string

The user who last edited the item’s name.

lastEditedBy/href string

The endpoint to call the user who last edited the item’s information, such as /api/v2/User?reference={reference} where {reference} is the user who last edited the item’s unique reference code.

parent object

Contains the information of any parent relationship with the item (if the item is in a folder or an item set).

parent/id integer

The parent’s unique identifier.

parent/reference string

The parent’s unique reference code.

parent/name string

The parent’s name.

parent/type string

The type of parent relationship (Folder or ItemSet).

createDate string

The date the item was created, in YYYY-MM-DDTHH:SS format.

updateDate string

The date the item was last updated, in YYYY-MM-DDTHH:SS format.

contentUpdateDate string

The date the item’s content was last updated, in YYYY-MM-DDTHH:SS format.

isDeleted Boolean

Determines whether the item is in its subject’s recycle bin.

language object

If item language variants are enabled, contains the information related to the item’s language (the default language of the item, unless the languageCode path parameter is passed in the request’s header).

language/code enumeration

The language’s ISO code. The available language codes are amh, ar, arm, pob, bul, mya, zh, zho, hrv, ces, dan, nl, en-int, en, us, est, per, tgl, fin, frc, ga, gle, glg, ge, gre, heb, hun, ind, ita, jpn, kk, khm, kor, lao, la, lav, lit, mlt, mon, nep, no, pol, por, iir, ron, rus, smo, slk, slv, som, sp, es-int, lac, es-pa, es-pr, swe, tha, tur, ukr, vie, and we.

language/name string

The name of the language.

tagGroups array

Contains the information of any tags assigned to the item.

NOTE: If the item has tags from multiple tag groups assigned to it, a separate object is returned for each tag group.

tagGroups/id integer

The tag group’s unique identifier.

tagGroups/name string

The tag group’s name.

tagGroups/tagCategories array

Contains the information of any tag categories the tag group is in.

NOTE: If the tag group is in multiple tag categories, a separate object is returned for each tag category.

tagGroups/tagCategories/id integer

The tag category’s unique identifier.

tagGroups/tagCategories/name string

The tag category’s name.

tagGroups/tagValues array

Contains the information of the tag value(s) assigned to the item.

NOTE: If the item has multiple tag values assigned to it, a separate object is returned for each tag value.

tagGroups/tagValues/id integer

The tag value’s unique identifier.

tagGroups/tagValues/value string

The tag value.

tagGroups/tagValues/isItemSetTag Boolean

If true, the tag value is inherited from the item set.

tagGroups/isDeleted Boolean

Determines whether the tag group is deleted.

enemyItems array

Contains the information of any items the item has an enemy relationship with.

NOTE: If the item has multiple enemy relationships, a separate object is returned for each item.

enemyItems/isSectionOnly Boolean

Determines whether the enemy relationship is section-level (true) or test form-level (false).

enemyItems/isPrincipal Boolean

Determines whether the enemy relationship is a principal (true) or acquired relationship (false).

enemyItems/child object

If the item is an item set, contains the information for the item in the item set with an enemy relationship.

enemyItems/child/id integer

The item’s unique identifier.

enemyItems/child/reference string

The item’s unique reference code.

enemyItems/child/type enumeration

enemyItems/child/name string

The item’s name.

enemyItems/child/position integer

NOTE: This property is not supported and only returns 0.

enemyItems/child/href string

The endpoint to call the item’s information, such as /api/v2/Item/{id} where {id} is the item’s unique identifier.

enemyItems/item object

Contains the enemy item’s information.

enemyItems/item/id integer

The enemy item’s unique identifier.

enemyItems/item/reference string

The enemy item’s unique reference code.

enemyItems/item/type enumeration

The enemy item type, which can be one of MultipleChoice, MultipleResponse, EitherOr, NumericalEntry, FillInTheBlank, ShortAnswer, Essay, SelectFromAList, MatchingBoxes (Extended Matching questions), FileAttach, DragAndDrop, EquationEntry, HotSpot, Spreadsheet, VoiceCapture, CqtItem (Custom Question type questions), FractionEntryItem, MultipleChoiceSurvey, MultipleResponseSurvey, Likert, or ItemSet.

enemyItems/item/name string

The enemy item’s name.

enemyItems/item/position integer

NOTE: This property is not supported and only returns 0.

enemyItems/item/href string

The endpoint to call the enemy item’s information, such as /api/v2/Item/{id} where {id} is the item’s unique identifier.

enemyItems/item/subjectId integer

The unique identifier of the enemy item’s subject.

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.

mark integer

The item’s assigned mark.

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/name string

The item owner’s name.

owner/href string

The endpoint to call the item owner’s information, such as /api/v2/User?reference={reference} where {reference} is the item owner’s unique reference code.

stemComponents array

A collection of text, images or equations that form each question stem.

NOTE: If the item contains multiple question stems, a separate object for each stem is returned. Media or formula cannot be part of the first question stem for items in Mixed subjects.

stemComponents/contentType enumeration

Determines the content type for the question stem. This can be either RichText, an Image, or MathML (Mixed subjects only).

stemComponents/content string

The question stem’s content in HTML format.

stemComponents/media object

If the contentType is an Image, contains the media’s information.

stemComponents/media/id integer

The media’s unique identifier.

stemComponents/media/externalId string

If using the Nuxeo media repository: the media’s external reference. Otherwise this property always returns null. For more information about Nuxeo, read ‘About Media settings’ in About Site Settings options.

stemComponents/media/name string

The media’s name in Surpass.

stemComponents/id integer

The question stem’s unique identifier.

purpose enumeration

The item’s assigned purpose. This can be either Summative, Formative, or Unspecified. If 3 is returned, the item is a sample item.

markingType enumeration

Determines whether the item is set to be Computer or Human-marked.

citations string

Any citations added to the item in HTML format. If null, the item does not have any citations.

version string

The item’s version.

Whenever an item is changed and saved, Surpass creates a new item version. Items can have major versions (whole integers like 1, 2, and 3) and minor versions (non-integer decimals like 1.1, 1.2, and 1.3). A new major item version is created every time there are saved changes to the item owner or workflow status. Any changes made to live items create a new major version.

NOTE: Version Compare must be enabled on your Surpass instance for this property to be returned. If you would like Version Compare enabled on your Surpass instance, speak to your Surpass Customer Success Manager.

languageVariants array

If item language variants are enabled, contains the language variant(s) information.

NOTE: If the item contains multiple language variants, a separate object for each language variant is returned.

languageVariants/code enumeration

languageVariants/name string

The name of the language.

languageVariants/isDeleted Boolean

Determines whether the language variant has been deleted. Deleted language variants can be stored or permanently deleted.

languageVariants/href string

The endpoint to call the language variant’s information, such as /oapi/Item/{id}/LanguageVariant/{languageCode} where {id} is the item’s unique identifier and {languageCode} is the language variant’s ISO code.

comments array

Contains the information for any comments left on the item.

NOTE: If the the item contains multiple comments, a separate object for each comment is returned.

comments/id integer

The comment’s unique identifier.

comments/text string

The comment.

comments/isPrivate 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/name string

The user’s name.

comments/createdBy/href string

The endpoint to call the user’s information, such as /api/v2/User?reference={reference} where {reference} is the user’s unique reference code.

generalFeedback object

Contains any general candidate feedback added to the item.

generalFeedback/text string

The feedback text in HTML format.

generalFeedback/mediaItems array

Contains any media added to the feedback.

NOTE: If the feedback contains multiple pieces of media, a separate object is returned for each piece of media.

generalFeedback/mediaItems/id integer

The media’s unique identifier.

generalFeedback/mediaItems/externalId string

generalFeedback/mediaItems/name string

The media’s name in Surpass.

generalFeedback/sourceMaterials array

Contains any source material added to the feedback.

generalFeedback/sourceMaterials/id integer

The source material’s unique identifier.

generalFeedback/sourceMaterials/externalId string

generalFeedback/sourceMaterials/name string

The source material’s name in Surpass.

correctFeedback object

Contains any correct candidate feedback added to the item.

NOTE: Only items in Mixed subjects can contain correct feedback.

correctFeedback/text string

The feedback text in HTML format.

correctFeedback/mediaItems array

Contains any media added to the feedback.

NOTE: If the feedback contains multiple pieces of media, a separate object is returned for each piece of media.

correctFeedback/mediaItems/id integer

The media’s unique identifier.

correctFeedback/mediaItems/externalId string

correctFeedback/mediaItems/name string

The media’s name in Surpass.

correctFeedback/sourceMaterials array

Contains any source material added to the feedback.

correctFeedback/sourceMaterials/id integer

The source material’s unique identifier.

correctFeedback/sourceMaterials/externalId string

correctFeedback/sourceMaterials/name string

The source material’s name in Surpass.

incorrectFeedback object

Contains any incorrect candidate feedback added to the item.

NOTE: Only items in Mixed subjects can contain incorrect feedback.

incorrectFeedback/text string

The feedback text in HTML format.

incorrectFeedback/mediaItems array

Contains any media added to the feedback.

NOTE: If the feedback contains multiple pieces of media, a separate object is returned for each piece of media.

incorrectFeedback/mediaItems/id string

The media’s unique identifier.

incorrectFeedback/mediaItems/externalId string

incorrectFeedback/mediaItems/name string

The media’s name in Surpass.

incorrectFeedback/sourceMaterials array

Contains any source material added to the feedback.

incorrectFeedback/sourceMaterials/id integer

The source material’s unique identifier.

incorrectFeedback/sourceMaterials/externalId string

incorrectFeedback/sourceMaterials/name string

The source material’s name in Surpass.

sourceMaterials array

Contains any source material attached to the item.

sourceMaterials/id integer

The source material’s unique identifier.

sourceMaterials/externalId string

sourceMaterials/name string

The source material’s name.

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/name string

The assistive media’s name in Surpass.

mediaItems array

Contains any media embedded on the item.

NOTE: If the item contains multiple pieces of embedded media, a separate object for each piece of media is returned.

mediaItems/id integer

The media’s unique identifier.

mediaItems/externalId string

mediaItems/name string

The media’s name in Surpass.

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.

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.

itemTools array

Contains the information of any tools added to the item.

NOTE: If the item contains multiple tools, a separate object is returned for each tool.

itemTools/id integer

The tool’s unique identifier.

itemTools/type enumeration

The type of tool. The available tools are BasicCalculator, ScientificCalculator, Caliper (3), Notepad (4), and Protractor (5).

itemTools/label string

The name given to the tool.

sharedWith array

Contains the information for any subject the item is shared with.

NOTE: If the item is shared with multiple subjects, a separate object for each subject is returned.

sharedWith/id integer

The subject’s unique identifier.

sharedWith/reference string

The subject’s’s unique reference code.

sharedWith/name string

The subject’s name.

sharedWith/href string

The endpoint to call the subject’s information, such as /api/v2/{id} where {id} is the subject’s unique identifier.

standardLists array

Contains the information for any item list the item is a part of.

NOTE: If the item is in multiple item lists, a separate object for each item list is returned.

standardLists/id integer

The item list’s unique identifier.

standardLists/reference string

The item list’s unique reference code.

standardLists/href string

The endpoint to call the item list’s information, such as /api/v2/ItemList/{id} where {id} is the item list’s unique identifier.

standardLists/subject object

Contains the information of the item list’s subject.

standardLists/subject/id integer

The subject’s unique identifier.

standardLists/subject/reference string

The subject’s unique reference code.

sharedQuestionText object

If the item is in an item set, shared text is a collection of text, images or equations that are shared from the item set with its items.

sharedQuestionText/contentType enumeration

Determines the content type for the shared text. This can be either RichText, an Image, or MathML (Mixed subjects only).

sharedQuestionText/content string

The shared text’s content in HTML format.

sharedMediaItems array

If the item is in an item set, contains any media embedded on the item set and shared with its items.

NOTE: If the item set contains multiple pieces of embedded media, a separate object for each piece of media is returned.

sharedMediaItems/id integer

The shared media’s unique identifier.

sharedMediaItems/externalId string

sharedMediaItems/name string

The shared media’s name in Surpass.

answerOptions array

Contains the item’s answer options’ information.

NOTE: A separate object is returned for each answer option.

answerOptions/id integer

The answer option’s unique identifier.

answerOptions/label string

The answer option’s label. If null, answer option labels are not enabled for the item.

answerOptions/answerColumns array

Contains the text, media, or mathML for each answer option column. The first array returns information for the answer option in the first column regardless of the Layout options, but the second array contains the second column’s information if set to Two columns.

answerOptions/answerColumns/contentType enumeration

Determines the content type for the shared text. This can be either RichText, an Image, or MathML (Mixed subjects only).

answerOptions/answerColumns/content string

The answer option text in HTML format.

If set to Answer options as a table (HTML subjects only), the first row is returned separated by the pipe symbol (for example, Paris|Berlin|Madrid|Copenhagen).

answerOptions/answerColumns/media array

Contains any media used as the answer option. If null, the answer option is not an image.

answerOptions/answerColumns/media/id integer

The media’s unique identifier.

answerOptions/answerColumns/media/externalId string

answerOptions/answerColumns/media/name string

The media’s name in Surpass.

answerOptions/assistiveMedia object

Contains the information of any assistive media attached to the answer option.

answerOptions/assistiveMedia/id integer

The assistive media’s unique identifier.

answerOptions/assistiveMedia/name string

The assistive media’s name in Surpass.

answerOptions/rationaleText string

The rationale text for the answer option if Show Answer Rationale has been enabled.

answerOptions/exclusiveOption Boolean

Determines whether the answer option is set to be an Exclusive Option, meaning it cannot be selected in conjunction with other answer options.

answerOptions/correct Boolean

Determines whether the answer option is the correct answer if the Marking type is set to Standard.

randomise Boolean

Determines whether the answer options are to be randomised for the candidate.

exclusiveOptionEnabled Boolean

Determines whether the answer option is set to be an Exclusive Option, meaning it cannot be selected in conjunction with other answer options.

NOTE: This property is not supported for Either/Or questions.

answerWidthRatio enumeration

Determines whether the answer option column width ratio is 50/50, 20/80, or 80/20 if the Layout options are set to Two columns. Defaults to 50/50 if omitted.

addLabelsToOptions Boolean

Determines whether the answer options have added labels for candidate delivery.

tableOptionsHtml string

The answer options as a table in HTML format if the Layout option is set to Answer options as a table (HTML subjects only).

markType enumeration

Determines whether the Marking type for the question is Standard, Weighted, or Combination.

multipleChoiceQuestions/rationaleEnabled Boolean

Determines whether the Show Answer Rationale setting has been enabled.

serverTimeZone enumeration

The timezone of the server sending the response.

Creating an item

The Item OAPI resource can be used to create Either/Or, Multiple Choice, Multiple Response, and Essay question items.

If item language variants are enabled, you can also use the Item OAPI to create specific item language variants of an item by passing a LanguageVariant path parameter in a request’s header.

Creating a Multiple Choice question

post /oapi/Item/MCQ

Send a request to the endpoint to create a Multiple Choice question.

Parameters

NOTE: An authorization header is mandatory, but the required input may vary. Read Connecting to the Surpass OAPI for more information on authentication and authorisation.

Name	Parameter	Input	Description
authorization	header OPTIONAL	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
authorization	header OPTIONAL	`Bearer {token}`	A bearer token must be passed to authorise the user’s request, where `{token}` is a JWT (JSON web token).
content-type	header MANDATORY	`application/json`	Determines data format of the request (JSON).
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`	Determines data format of the response (JSON).
LanguageVariant	path OPTIONAL	`/oapi/Item/MCQ/{id}/LanguageVariant`	Creates a new item language variant for the specified item, where `{id}` is the item’s unique identifier and the item’s language code is specified in the request body. NOTE: Item language variants are not available by default. If you would like item language variants enabled on your Surpass instance, contact your Surpass Customer Success Manager.

Sample request

The following request contains the minimum required request body to create a live Multiple Choice question.

{
    "subject": {
        "reference": "Subject1"
    },
    "name": "Multiple Choice question",
    "status": "Live",
    "stemComponents": [
        {
            "contentType": "RichText",
            "content": "What is the capital city of Belgium?"
        }
    ],
    "mark": 1,
    "answerOptions": [
        {
            "correct": true,
            "answerColumns": [
                {
                    "contentType": "RichText",
                    "content": "Brussels"
                }
            ]
        },
                {
            "correct": false,
            "answerColumns": [
                {
                    "contentType": "RichText",
                    "content": "Brugge"
                }
            ]
        },
                        {
            "correct": false,
            "answerColumns": [
                {
                    "contentType": "RichText",
                    "content": "Antwerp"
                }
            ]
        }
    ]
}

EXAMPLE: In this sample request, a live Multiple Choice item is created.

Request body schema

The request body schema contains a description of every property that can be passed with this endpoint.

NOTE: If creating an item language variant by passing a LanguageVariant path parameter in the request's header, subject, name, owner, tagGroups, enemyItems, parentId, and citations cannot be included in the request body.

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.

status enumeration optional

Defaults to Draft if omitted.

stemComponents array optional

A collection of text, images or equations that form each question stem.

NOTE: If the item contains multiple question stems, a separate object for each stem is returned. Media or formula cannot be part of the first question stem for items in Mixed subjects.

stemComponents/contentType enumeration

Determines the content type for the question stem. This can be either RichText, an Image, or MathML (Mixed subjects only).

stemComponents/content string

The question stem’s content in HTML format.

stemComponents/media object

If the contentType is an Image, contains the media’s information.

stemComponents/media/id integer

The media’s unique identifier.

stemComponents/media/externalId string

If using the Nuxeo media repository: the media’s external reference. For more information about Nuxeo, read ‘About Media settings’ in About Site Settings options.

stemComponents/media/type enumeration

The type of media, Image or Video.

stemComponents/media/width integer

The media’s width in pixels.

stemComponents/media/height integer

The media’s height in pixels.

stemComponents/media/name string

The media’s name in Surpass.

stemComponents/id integer

The question stem’s unique identifier.

owner object optional

The item owner’s information.

owner/id integer

The item owner’s unique identifier.

owner/reference string

The item owner’s unique reference code.

tagGroups

Contains the information of any tags assigned to the item.

NOTE: To assign multiple tag values from multiple tag groups or collections to the item, pass a separate object for each tag group.

tagGroups/id integer

The tag group’s unique identifier.

tagGroups/name string

The tag group’s name.

tagGroups/tagCategories array

Contains the information of any tag categories the tag group is in.

NOTE: This property is not currently supported and will not assign any tag groups to a defined tag category.

tagGroups/tagValues array

Contains the information of the tag value(s) assigned to the item.

NOTE: To assign multiple tag values to the item, pass a separate object for each tag value.

tagGroups/tagValues/id integer

The tag value’s unique identifier.

tagGroups/tagValues/value string

The tag value.

tagGroups/tagValues/isItemSetTag Boolean

If true, the tag value is inherited from the item set.

tagGroups/tagValues/collection object

Contains the information of any tag collections the tag value is in.

NOTE: To add the tag value to multiple tag collections, pass a separate tag group object for each tag collection.

tagGroups/tagValues/collection/id integer

The tag collection’s unique identifier.

tagGroups/tagValues/collection/reference string

The tag collection’s unique reference code.

tagGroups/tagValues/collection/name string

The tag collection’s name.

tagGroups/tagValues/collection/order integer

The tag collection’s position within the tag collection group.

tagGroups/tagValues/collection/isCurrent Boolean

Determines whether the tag collection is the latest tag collection. Only the latest tag values can be returned when searching for items in Item Search.

tagGroups/tagValues/collection/collectionGroup object

Contains the tag collection’s tag collection group information.

tagGroups/tagValues/collection/collectionGroup/id integer

The tag collection group’s unique identifier.

tagGroups/tagValues/collection/collectionGroup/reference string

The tag collection group’s unique reference code.

tagGroups/tagValues/collection/subCollection object

Contains the information of any subcollections the tag value is in.

tagGroups/tagValues/collection/subCollection/reference string

The subcollection’s unique reference code.

tagGroups/tagValues/collection/subCollection/name string

The subcollection’s name.

tagGroups/tagValues/collection/subCollection/order integer

The subcollection’s position within the subcollection group.

tagGroups/tagValues/subCollection/collectionGroup object

Contains the subcollection’s subcollection group information.

tagGroups/tagValues/subCollection/collectionGroup/id integer

The subcollection group’s unique identifier.

tagGroups/tagValues/subCollection/collectionGroup/reference string

The subcollection group’s unique reference code.

tagGroups/isDeleted Boolean

Determines whether the tag group has been deleted.

enemyItems array optional

Contains the information of any items the item has an enemy relationship with.

enemyItems/id integer

The item’s unique identifier.

enemyItems/isSectionOnly Boolean

Determines whether the enemy relationship is section-level (true) or test form-level (false).

mark integer optional

The item’s assigned mark.

parentId integer optional

If the item is in an item set, the item set’s unique identifier.

citations string optional

Any citations added to the item in HTML format.

comment object optional

Contains the information of any comment left on the item.

comment/text string

Any comment left on the item in text format.

comment/isPrivate 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.

generalFeedback object optional

Contains any general candidate feedback added to the item.

generalFeedback/text string

The feedback text in HTML format.

generalFeedback/sourceMaterials array

Contains any source material added to the feedback.

generalFeedback/sourceMaterials/id integer

The source material’s unique identifier.

generalFeedback/sourceMaterials/externalId string

If using the Nuxeo media repository: the media’s external reference. For more information about Nuxeo, read ‘About Media settings’ in About Site Settings options.

generalFeedback/sourceMaterials/type enumeration

The type of media, Image or Video.

generalFeedback/sourceMaterials/width integer

The media’s width in pixels.

generalFeedback/sourceMaterials/height integer

The media’s height in pixels.

generalFeedback/media object

Contains the information of any media attached to the general feedback.

generalFeedback/media/id integer

The media’s unique identifier.

generalFeedback/media/externalId string

If using the Nuxeo media repository: the media’s external reference. For more information about Nuxeo, read ‘About Media settings’ in About Site Settings options.

generalFeedback/media/type enumeration

The type of media, Image or Video.

generalFeedback/media/width integer

The media’s width in pixels.

generalFeedback/media/height integer

The media’s height in pixels.

mediaItems array optional

Contains any media embedded on the item.

NOTE: If the item contains multiple pieces of embedded media, pass a separate object for each piece of media.

mediaItems/id integer

The media’s unique identifier.

mediaItems/externalId string

If using the Nuxeo media repository: the media’s external reference. For more information about Nuxeo, read ‘About Media settings’ in About Site Settings options.

mediaItems/name string

The media’s name in Surpass.

language object optional

If item language variants are enabled and the LanguageVariant path parameter is passed in the request’s header, contains the information for the new language variant.

language/code enumeration

answerOptions array mandatory

Contains the item’s answer options’ information.

NOTE: A separate object must be passed for each answer option.

answerOptions/correct Boolean

Determines whether the answer option is the correct answer.

answerOptions/weight integer

The answer option’s mark if the item’s answer options are weighted.

answerOptions/label string

The label text for the answer option if Add Labels for Candidate Delivery has been enabled.

answerOptions/answerColumns array

Contains the text, media, or mathML for each answer option column. Passing two arrays, one for each column, sets the Layout options to Two columns.

answerOptions/answerColumns/contentType enumeration

Determines the content type for the answer option. This can be either RichText, an Image, or MathML (Mixed subjects only).

answerOptions/answerColumns/content string

The answer option text in HTML format.

If set to Answer options as a table (HTML subjects only), the first row is returned separated by the pipe symbol (for example, Paris|Berlin|Madrid|Copenhagen).

answerOptions/answerColumns/media array

Contains any media used as the answer option.

answerOptions/answerColumns/media/id integer

The media’s unique identifier.

answerOptions/answerColumns/media/externalId string

If using the Nuxeo media repository: the media’s external reference. For more information about Nuxeo, read ‘About Media settings’ in About Site Settings options.

answerOptions/answerColumns/media/type enumeration

The type of media, Image or Video.

answerOptions/answerColumns/media/width integer

The media’s width in pixels.

answerOptions/answerColumns/media/height integer

The media’s height in pixels.

answerOptions/answerColumns/media/name string

The media’s name in Surpass.

answerOptions/assistiveMedia object

Contains the information of any assistive media attached to the answer option.

answerOptions/assistiveMedia/name string

The assistive media’s name in Surpass.

answerOptions/assistiveMedia/data string

The assistive media’s file data in encoded Base64 format.

answerOptions/rationaleText string

The rationale text for the answer option if Show Answer Rationale has been enabled.

answerOptions/exclusiveOption Boolean

Determines whether the answer option is set to be an Exclusive Option, meaning it cannot be selected in conjunction with other answer options.

randomise Boolean optional

Determines whether the answer options are to be randomised for the candidate.

answerWidthRatio enumeration optional

Determines whether the answer option column width ratio is 50/50, 20/80, or 80/20 if the Layout options are set to Two columns.

useLabels Boolean optional

Determines whether the answer options have added labels for candidate delivery. Defaults to false if omitted.

markType enumeration optional

Determines whether the Marking type for the question is Standard or Weighted. Defaults to Standard if omitted.

tableOptionsHtml string optional

The answer options as a table in HTML format if the Layout option is set to Answer options as a table (HTML subjects only).

rationaleEnabled Boolean optional

Determines whether the Show Answer Rationale setting has been enabled. Defaults to false if omitted.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the new item’s details (the response value is the item’s unique identifier).

{
    "response": 1,
    "serverTimeZone": "GMT Standard Time"
}

Creating a Multiple Response question

post /oapi/Item/MRQ

Send a request to the endpoint to create a Multiple Response question.

Parameters

NOTE: An authorization header is mandatory, but the required input may vary. Read Connecting to the Surpass OAPI for more information on authentication and authorisation.

Name	Parameter	Input	Description
authorization	header OPTIONAL	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
authorization	header OPTIONAL	`Bearer {token}`	A bearer token must be passed to authorise the user’s request, where `{token}` is a JWT (JSON web token).
content-type	header MANDATORY	`application/json`	Determines data format of the request (JSON).
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`	Determines data format of the response (JSON).
LanguageVariant	path OPTIONAL	`/oapi/Item/MRQ/{id}/LanguageVariant`	Creates a new item language variant for the specified item, where `{id}` is the item’s unique identifier and the item’s language code is specified in the request body. NOTE: Item language variants are not available by default. If you would like item language variants enabled on your Surpass instance, contact your Surpass Customer Success Manager.

Sample request

The following request contains the minimum required request body to create a live Multiple Response question.

{
    "subject": {
        "reference": "Subject1"
    },
    "name": "Multiple Response question",
    "status": "Live",
    "stemComponents": [
        {
            "contentType": "RichText",
            "content": "Which of the following cities are in the Netherlands?"
        }
    ],
    "mark": 1,
    "answerOptions": [
        {
            "correct": true,
            "answerColumns": [
                {
                    "contentType": "RichText",
                    "content": "Maastricht"
                }
            ]
        },
                {
            "correct": false,
            "answerColumns": [
                {
                    "contentType": "RichText",
                    "content": "Ghent"
                }
            ]
        },
                        {
            "correct": true,
            "answerColumns": [
                {
                    "contentType": "RichText",
                    "content": "Utrecht"
                }
            ]
        }
    ]
}

EXAMPLE: In this sample request, a live Multiple Response item is created.

Request body schema

The request body schema contains a description of every property that can be passed with this endpoint.

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.

status enumeration optional

Defaults to Draft if omitted.

stemComponents array optional

A collection of text, images or equations that form each question stem.

NOTE: If the item contains multiple question stems, a separate object for each stem is returned. Media or formula cannot be part of the first question stem for items in Mixed subjects.

stemComponents/contentType enumeration

Determines the content type for the question stem. This can be either RichText, an Image, or MathML (Mixed subjects only).

stemComponents/content string

The question stem’s content in HTML format.

stemComponents/media object

If the contentType is an Image, contains the media’s information.

stemComponents/media/id integer

The media’s unique identifier.

stemComponents/media/externalId string

If using the Nuxeo media repository: the media’s external reference. For more information about Nuxeo, read ‘About Media settings’ in About Site Settings options.

stemComponents/media/type enumeration

The type of media, Image or Video.

stemComponents/media/width integer

The media’s width in pixels.

stemComponents/media/height integer

The media’s height in pixels.

stemComponents/media/name string

The media’s name in Surpass.

stemComponents/id integer

The question stem’s unique identifier.

owner object optional

The item owner’s information.

owner/id integer

The item owner’s unique identifier.

owner/reference string

The item owner’s unique reference code.

tagGroups

Contains the information of any tags assigned to the item.

NOTE: To assign multiple tag values from multiple tag groups or collections to the item, pass a separate object for each tag group.

tagGroups/id integer

The tag group’s unique identifier.

tagGroups/name string

The tag group’s name.

tagGroups/tagCategories array

Contains the information of any tag categories the tag group is in.

NOTE: This property is not currently supported and will not assign any tag groups to a defined tag category.

tagGroups/tagValues array

Contains the information of the tag value(s) assigned to the item.

NOTE: To assign multiple tag values to the item, pass a separate object for each tag value.

tagGroups/tagValues/id integer

The tag value’s unique identifier.

tagGroups/tagValues/value string

The tag value.

tagGroups/tagValues/isItemSetTag Boolean

If true, the tag value is inherited from the item set.

tagGroups/tagValues/collection object

Contains the information of any tag collections the tag value is in.

NOTE: To add the tag value to multiple tag collections, pass a separate tag group object for each tag collection.

tagGroups/tagValues/collection/id integer

The tag collection’s unique identifier.

tagGroups/tagValues/collection/reference string

The tag collection’s unique reference code.

tagGroups/tagValues/collection/name string

The tag collection’s name.

tagGroups/tagValues/collection/order integer

The tag collection’s position within the tag collection group.

tagGroups/tagValues/collection/isCurrent Boolean

Determines whether the tag collection is the latest tag collection. Only the latest tag values can be returned when searching for items in Item Search.

tagGroups/tagValues/collection/collectionGroup object

Contains the tag collection’s tag collection group information.

tagGroups/tagValues/collection/collectionGroup/id integer

The tag collection group’s unique identifier.

tagGroups/tagValues/collection/collectionGroup/reference string

The tag collection group’s unique reference code.

tagGroups/tagValues/collection/subCollection object

Contains the information of any subcollections the tag value is in.

tagGroups/tagValues/collection/subCollection/reference string

The subcollection’s unique reference code.

tagGroups/tagValues/collection/subCollection/name string

The subcollection’s name.

tagGroups/tagValues/collection/subCollection/order integer

The subcollection’s position within the subcollection group.

tagGroups/tagValues/subCollection/collectionGroup object

Contains the subcollection’s subcollection group information.

tagGroups/tagValues/subCollection/collectionGroup/id integer

The subcollection group’s unique identifier.

tagGroups/tagValues/subCollection/collectionGroup/reference string

The subcollection group’s unique reference code.

tagGroups/isDeleted Boolean

Determines whether the tag group has been deleted.

enemyItems array optional

Contains the information of any items the item has an enemy relationship with.

enemyItems/id integer

The item’s unique identifier.

enemyItems/isSectionOnly Boolean

Determines whether the enemy relationship is section-level (true) or test form-level (false).

mark integer optional

The item’s assigned mark.

parentId integer optional

If the item is in an item set, the item set’s unique identifier.

citations string optional

Any citations added to the item in HTML format.

comment object optional

Contains the information of any comment left on the item.

comment/text string

Any comment left on the item in text format.

comment/isPrivate 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.

generalFeedback object optional

Contains any general candidate feedback added to the item.

generalFeedback/text string

The feedback text in HTML format.

generalFeedback/sourceMaterials array

Contains any source material added to the feedback.

generalFeedback/sourceMaterials/id integer

The source material’s unique identifier.

generalFeedback/sourceMaterials/externalId string

If using the Nuxeo media repository: the media’s external reference. For more information about Nuxeo, read ‘About Media settings’ in About Site Settings options.

generalFeedback/sourceMaterials/type enumeration

The type of media, Image or Video.

generalFeedback/sourceMaterials/width integer

The media’s width in pixels.

generalFeedback/sourceMaterials/height integer

The media’s height in pixels.

generalFeedback/media object

Contains the information of any media attached to the general feedback.

generalFeedback/media/id integer

The media’s unique identifier.

generalFeedback/media/externalId string

If using the Nuxeo media repository: the media’s external reference. For more information about Nuxeo, read ‘About Media settings’ in About Site Settings options.

generalFeedback/media/type enumeration

The type of media, Image or Video.

generalFeedback/media/width integer

The media’s width in pixels.

generalFeedback/media/height integer

The media’s height in pixels.

mediaItems array optional

Contains any media embedded on the item.

NOTE: If the item contains multiple pieces of embedded media, pass a separate object for each piece of media.

mediaItems/id integer

The media’s unique identifier.

mediaItems/externalId string

If using the Nuxeo media repository: the media’s external reference. For more information about Nuxeo, read ‘About Media settings’ in About Site Settings options.

mediaItems/name string

The media’s name in Surpass.

language object optional

If item language variants are enabled and the LanguageVariant path parameter is passed in the request’s header, contains the information for the new language variant.

language/code enumeration

answerOptions array mandatory

Contains the item’s answer options’ information.

NOTE: A separate object must be passed for each answer option.

answerOptions/correct Boolean

Determines whether the answer option is the correct answer.

answerOptions/weight integer

The answer option’s mark if the item’s answer options are weighted.

answerOptions/label string

The label text for the answer option if Add Labels for Candidate Delivery has been enabled.

answerOptions/answerColumns array

Contains the text, media, or mathML for each answer option column. Passing two arrays, one for each column, sets the Layout options to Two columns.

answerOptions/answerColumns/contentType enumeration

Determines the content type for the answer option. This can be either RichText, an Image, or MathML (Mixed subjects only).

answerOptions/answerColumns/content string

The answer option text in HTML format.

If set to Answer options as a table (HTML subjects only), the first row is returned separated by the pipe symbol (for example, Paris|Berlin|Madrid|Copenhagen).

answerOptions/answerColumns/media array

Contains any media used as the answer option.

answerOptions/answerColumns/media/id integer

The media’s unique identifier.

answerOptions/answerColumns/media/externalId string

If using the Nuxeo media repository: the media’s external reference. For more information about Nuxeo, read ‘About Media settings’ in About Site Settings options.

answerOptions/answerColumns/media/type enumeration

The type of media, Image or Video.

answerOptions/answerColumns/media/width integer

The media’s width in pixels.

answerOptions/answerColumns/media/height integer

The media’s height in pixels.

answerOptions/answerColumns/media/name string

The media’s name in Surpass.

answerOptions/assistiveMedia object

Contains the information of any assistive media attached to the answer option.

answerOptions/assistiveMedia/name string

The assistive media’s name in Surpass.

answerOptions/assistiveMedia/data string

The assistive media’s file data in encoded Base64 format.

answerOptions/rationaleText string

The rationale text for the answer option if Show Answer Rationale has been enabled.

answerOptions/exclusiveOption Boolean

Determines whether the answer option is set to be an Exclusive Option, meaning it cannot be selected in conjunction with other answer options.

randomise Boolean optional

Determines whether the answer options are to be randomised for the candidate.

answerWidthRatio enumeration optional

Determines whether the answer option column width ratio is 50/50, 20/80, or 80/20 if the Layout options are set to Two columns.

useLabels Boolean optional

Determines whether the answer options have added labels for candidate delivery. Defaults to false if omitted.

markType enumeration optional

Determines whether the Marking type for the question is Standard, Combination, or Weighted. Defaults to Standard if omitted.

tableOptionsHtml string optional

The answer options as a table in HTML format if the Layout option is set to Answer options as a table (HTML subjects only).

rationaleEnabled Boolean optional

Determines whether the Show Answer Rationale setting has been enabled. Defaults to false if omitted.

combinations array optional

Contains the answer option combinations’ information if the Marking type is set to Combination.

NOTE: Pass a separate object for each combination.

combinations/mark integer

The number of marks for the answer option combination.

combinations/labels array

Contains the labels of the answer options included in the combination.

combinations/title string

The answer option combination’s title.

awardAllCorrect Boolean

Determines whether the Only award mark if candidate selects all correct options setting is enabled (true) or not (false). Defaults to false if omitted.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the new item’s details (the response value is the item’s unique identifier).

{
    "response": 1,
    "serverTimeZone": "GMT Standard Time"
}

Creating an Either/Or question

post /oapi/Item/EitherOr

Send a request to the endpoint to create an Either/Or question.

Parameters

NOTE: An authorization header is mandatory, but the required input may vary. Read Connecting to the Surpass OAPI for more information on authentication and authorisation.

Name	Parameter	Input	Description
authorization	header OPTIONAL	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
authorization	header OPTIONAL	`Bearer {token}`	A bearer token must be passed to authorise the user’s request, where `{token}` is a JWT (JSON web token).
content-type	header MANDATORY	`application/json`	Determines data format of the request (JSON).
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`	Determines data format of the response (JSON).
LanguageVariant	path OPTIONAL	`/oapi/Item/EitherOr/{id}/LanguageVariant`	Creates a new item language variant for the specified item, where `{id}` is the item’s unique identifier and the item’s language code is specified in the request body. NOTE: Item language variants are not available by default. If you would like item language variants enabled on your Surpass instance, contact your Surpass Customer Success Manager.

Sample request

The following request contains the minimum required request body to create a live Either/Or question.

{
    "subject": {
        "reference": "Subject1"
    },
    "name": "Either/Or question",
    "status": "Live",
    "stemComponents": [
        {
            "contentType": "RichText",
            "content": "Halley's Comet returns to Earth approximately every 75 years. True or false?"
        }
    ],
    "mark": 1,
    "answerOptions": [
        {
            "correct": true,
            "answerColumns": [
                {
                    "contentType": "RichText",
                    "content": "True"
                }
            ]
        },
                {
            "correct": false,
            "answerColumns": [
                {
                    "contentType": "RichText",
                    "content": "False"
                }
            ]
        }
    ]
}

EXAMPLE: In this sample request, a live Either/Or item is created.

Request body schema

The request body schema contains a description of every property that can be passed with this endpoint.

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.

status enumeration optional

Defaults to Draft if omitted.

stemComponents array optional

A collection of text, images or equations that form each question stem.

NOTE: If the item contains multiple question stems, a separate object for each stem is returned. Media or formula cannot be part of the first question stem for items in Mixed subjects.

stemComponents/contentType enumeration

Determines the content type for the question stem. This can be either RichText, an Image, or MathML (Mixed subjects only).

stemComponents/content string

The question stem’s content in HTML format.

stemComponents/media object

If the contentType is an Image, contains the media’s information.

stemComponents/media/id integer

The media’s unique identifier.

stemComponents/media/externalId string

If using the Nuxeo media repository: the media’s external reference. For more information about Nuxeo, read ‘About Media settings’ in About Site Settings options.

stemComponents/media/type enumeration

The type of media, Image or Video.

stemComponents/media/width integer

The media’s width in pixels.

stemComponents/media/height integer

The media’s height in pixels.

stemComponents/media/name string

The media’s name in Surpass.

stemComponents/id integer

The question stem’s unique identifier.

owner object optional

The item owner’s information.

owner/id integer

The item owner’s unique identifier.

owner/reference string

The item owner’s unique reference code.

tagGroups

Contains the information of any tags assigned to the item.

NOTE: To assign multiple tag values from multiple tag groups or collections to the item, pass a separate object for each tag group.

tagGroups/id integer

The tag group’s unique identifier.

tagGroups/name string

The tag group’s name.

tagGroups/tagCategories array

Contains the information of any tag categories the tag group is in.

NOTE: This property is not currently supported and will not assign any tag groups to a defined tag category.

tagGroups/tagValues array

Contains the information of the tag value(s) assigned to the item.

NOTE: To assign multiple tag values to the item, pass a separate object for each tag value.

tagGroups/tagValues/id integer

The tag value’s unique identifier.

tagGroups/tagValues/value string

The tag value.

tagGroups/tagValues/isItemSetTag Boolean

If true, the tag value is inherited from the item set.

tagGroups/tagValues/collection object

Contains the information of any tag collections the tag value is in.

NOTE: To add the tag value to multiple tag collections, pass a separate tag group object for each tag collection.

tagGroups/tagValues/collection/id integer

The tag collection’s unique identifier.

tagGroups/tagValues/collection/reference string

The tag collection’s unique reference code.

tagGroups/tagValues/collection/name string

The tag collection’s name.

tagGroups/tagValues/collection/order integer

The tag collection’s position within the tag collection group.

tagGroups/tagValues/collection/isCurrent Boolean

Determines whether the tag collection is the latest tag collection. Only the latest tag values can be returned when searching for items in Item Search.

tagGroups/tagValues/collection/collectionGroup object

Contains the tag collection’s tag collection group information.

tagGroups/tagValues/collection/collectionGroup/id integer

The tag collection group’s unique identifier.

tagGroups/tagValues/collection/collectionGroup/reference string

The tag collection group’s unique reference code.

tagGroups/tagValues/collection/subCollection object

Contains the information of any subcollections the tag value is in.

tagGroups/tagValues/collection/subCollection/reference string

The subcollection’s unique reference code.

tagGroups/tagValues/collection/subCollection/name string

The subcollection’s name.

tagGroups/tagValues/collection/subCollection/order integer

The subcollection’s position within the subcollection group.

tagGroups/tagValues/subCollection/collectionGroup object

Contains the subcollection’s subcollection group information.

tagGroups/tagValues/subCollection/collectionGroup/id integer

The subcollection group’s unique identifier.

tagGroups/tagValues/subCollection/collectionGroup/reference string

The subcollection group’s unique reference code.

tagGroups/isDeleted Boolean

Determines whether the tag group has been deleted.

enemyItems array optional

Contains the information of any items the item has an enemy relationship with.

enemyItems/id integer

The item’s unique identifier.

enemyItems/isSectionOnly Boolean

Determines whether the enemy relationship is section-level (true) or test form-level (false).

mark integer optional

The item’s assigned mark.

parentId integer optional

If the item is in an item set, the item set’s unique identifier.

citations string optional

Any citations added to the item in HTML format.

comment object optional

Contains the information of any comment left on the item.

comment/text string

Any comment left on the item in text format.

comment/isPrivate 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.

generalFeedback object optional

Contains any general candidate feedback added to the item.

generalFeedback/text string

The feedback text in HTML format.

generalFeedback/sourceMaterials array

Contains any source material added to the feedback.

generalFeedback/sourceMaterials/id integer

The source material’s unique identifier.

generalFeedback/sourceMaterials/externalId string

If using the Nuxeo media repository: the media’s external reference. For more information about Nuxeo, read ‘About Media settings’ in About Site Settings options.

generalFeedback/sourceMaterials/type enumeration

The type of media, Image or Video.

generalFeedback/sourceMaterials/width integer

The media’s width in pixels.

generalFeedback/sourceMaterials/height integer

The media’s height in pixels.

generalFeedback/media object

Contains the information of any media attached to the general feedback.

generalFeedback/media/id integer

The media’s unique identifier.

generalFeedback/media/externalId string

If using the Nuxeo media repository: the media’s external reference. For more information about Nuxeo, read ‘About Media settings’ in About Site Settings options.

generalFeedback/media/type enumeration

The type of media, Image or Video.

generalFeedback/media/width integer

The media’s width in pixels.

generalFeedback/media/height integer

The media’s height in pixels.

mediaItems array optional

Contains any media embedded on the item.

NOTE: If the item contains multiple pieces of embedded media, pass a separate object for each piece of media.

mediaItems/id integer

The media’s unique identifier.

mediaItems/externalId string

If using the Nuxeo media repository: the media’s external reference. For more information about Nuxeo, read ‘About Media settings’ in About Site Settings options.

mediaItems/name string

The media’s name in Surpass.

language object optional

If item language variants are enabled and the LanguageVariant path parameter is passed in the request’s header, contains the information for the new language variant.

language/code enumeration

answerOptions array mandatory

Contains the item’s answer options’ information.

NOTE: A separate object must be passed for each answer option.

answerOptions/correct Boolean

Determines whether the answer option is the correct answer.

answerOptions/weight integer

The answer option’s mark if the item’s answer options are weighted.

answerOptions/label string

The label text for the answer option if Add Labels for Candidate Delivery has been enabled.

answerOptions/answerColumns array

Contains the text, media, or mathML for each answer option column. Passing two arrays, one for each column, sets the Layout options to Two columns.

answerOptions/answerColumns/contentType enumeration

Determines the content type for the answer option. This can be either RichText, an Image, or MathML (Mixed subjects only).

answerOptions/answerColumns/content string

The answer option text in HTML format.

If set to Answer options as a table (HTML subjects only), the first row is returned separated by the pipe symbol (for example, Paris|Berlin|Madrid|Copenhagen).

answerOptions/answerColumns/media array

Contains any media used as the answer option.

answerOptions/answerColumns/media/id integer

The media’s unique identifier.

answerOptions/answerColumns/media/externalId string

If using the Nuxeo media repository: the media’s external reference. For more information about Nuxeo, read ‘About Media settings’ in About Site Settings options.

answerOptions/answerColumns/media/type enumeration

The type of media, Image or Video.

answerOptions/answerColumns/media/width integer

The media’s width in pixels.

answerOptions/answerColumns/media/height integer

The media’s height in pixels.

answerOptions/answerColumns/media/name string

The media’s name in Surpass.

answerOptions/assistiveMedia object

Contains the information of any assistive media attached to the answer option.

answerOptions/assistiveMedia/name string

The assistive media’s name in Surpass.

answerOptions/assistiveMedia/data string

The assistive media’s file data in encoded Base64 format.

answerOptions/rationaleText string

The rationale text for the answer option if Show Answer Rationale has been enabled.

NOTE: Rationale text is not supported for Either/Or questions.

answerOptions/exclusiveOption Boolean

Determines whether the answer option is set to be an Exclusive Option, meaning it cannot be selected in conjunction with other answer options.

NOTE: This property is not supported for Either/Or questions.

randomise Boolean optional

Determines whether the answer options are to be randomised for the candidate.

answerWidthRatio enumeration optional

Determines whether the answer option column width ratio is 50/50, 20/80, or 80/20 if the Layout options are set to Two columns.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the new item’s details (the response value is the item’s unique identifier).

{
    "response": 1,
    "serverTimeZone": "GMT Standard Time"
}

Creating an Essay question

post /oapi/Item/Essay

Send a request to the endpoint to create an Essay question.

Parameters

NOTE: An authorization header is mandatory, but the required input may vary. Read Connecting to the Surpass OAPI for more information on authentication and authorisation.

Name	Parameter	Input	Description
authorization	header OPTIONAL	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
authorization	header OPTIONAL	`Bearer {token}`	A bearer token must be passed to authorise the user’s request, where `{token}` is a JWT (JSON web token).
content-type	header MANDATORY	`application/json`	Determines data format of the request (JSON).
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`	Determines data format of the response (JSON).
LanguageVariant	path OPTIONAL	`/oapi/Item/Essay/{id}/LanguageVariant`	Creates a new item language variant for the specified item, where `{id}` is the item’s unique identifier and the item’s language code is specified in the request body. NOTE: Item language variants are not available by default. If you would like item language variants enabled on your Surpass instance, contact your Surpass Customer Success Manager.

Sample request

The following request contains the minimum required request body to create a live Essay question.

{
    "subject": {
        "reference": "TCS"
    },
    "name": "Essay question",
    "status": "Live",
    "stemComponents": [
        {
            "contentType": "RichText",
            "content": "Summarise the key differences between Aldous Huxley's 'Brave New World' and George Orwell's '1984' in under 750 words."
        }
    ],
    "mark": 1,
    "maxCharacters": 8000
}

EXAMPLE: In this sample request, a live Essay item is created.

Request body schema

The request body schema contains a description of every property that can be passed with this endpoint.

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.

status enumeration optional

Defaults to Draft if omitted.

stemComponents array optional

A collection of text, images or equations that form each question stem.

NOTE: If the item contains multiple question stems, a separate object for each stem is returned. Media or formula cannot be part of the first question stem for items in Mixed subjects.

stemComponents/contentType enumeration

Determines the content type for the question stem. This can be either RichText, an Image, or MathML (Mixed subjects only).

stemComponents/content string

The question stem’s content in HTML format.

stemComponents/media object

If the contentType is an Image, contains the media’s information.

stemComponents/media/id integer

The media’s unique identifier.

stemComponents/media/externalId string

If using the Nuxeo media repository: the media’s external reference. For more information about Nuxeo, read ‘About Media settings’ in About Site Settings options.

stemComponents/media/type enumeration

The type of media, Image or Video.

stemComponents/media/width integer

The media’s width in pixels.

stemComponents/media/height integer

The media’s height in pixels.

stemComponents/media/name string

The media’s name in Surpass.

stemComponents/id integer

The question stem’s unique identifier.

owner object optional

The item owner’s information.

owner/id integer

The item owner’s unique identifier.

owner/reference string

The item owner’s unique reference code.

tagGroups

Contains the information of any tags assigned to the item.

NOTE: To assign multiple tag values from multiple tag groups or collections to the item, pass a separate object for each tag group.

tagGroups/id integer

The tag group’s unique identifier.

tagGroups/name string

The tag group’s name.

tagGroups/tagCategories array

Contains the information of any tag categories the tag group is in.

NOTE: This property is not currently supported and will not assign any tag groups to a defined tag category.

tagGroups/tagValues array

Contains the information of the tag value(s) assigned to the item.

NOTE: To assign multiple tag values to the item, pass a separate object for each tag value.

tagGroups/tagValues/id integer

The tag value’s unique identifier.

tagGroups/tagValues/value string

The tag value.

tagGroups/tagValues/isItemSetTag Boolean

If true, the tag value is inherited from the item set.

tagGroups/tagValues/collection object

Contains the information of any tag collections the tag value is in.

NOTE: To add the tag value to multiple tag collections, pass a separate tag group object for each tag collection.

tagGroups/tagValues/collection/id integer

The tag collection’s unique identifier.

tagGroups/tagValues/collection/reference string

The tag collection’s unique reference code.

tagGroups/tagValues/collection/name string

The tag collection’s name.

tagGroups/tagValues/collection/order integer

The tag collection’s position within the tag collection group.

tagGroups/tagValues/collection/isCurrent Boolean

Determines whether the tag collection is the latest tag collection. Only the latest tag values can be returned when searching for items in Item Search.

tagGroups/tagValues/collection/collectionGroup object

Contains the tag collection’s tag collection group information.

tagGroups/tagValues/collection/collectionGroup/id integer

The tag collection group’s unique identifier.

tagGroups/tagValues/collection/collectionGroup/reference string

The tag collection group’s unique reference code.

tagGroups/tagValues/collection/subCollection object

Contains the information of any subcollections the tag value is in.

tagGroups/tagValues/collection/subCollection/reference string

The subcollection’s unique reference code.

tagGroups/tagValues/collection/subCollection/name string

The subcollection’s name.

tagGroups/tagValues/collection/subCollection/order integer

The subcollection’s position within the subcollection group.

tagGroups/tagValues/subCollection/collectionGroup object

Contains the subcollection’s subcollection group information.

tagGroups/tagValues/subCollection/collectionGroup/id integer

The subcollection group’s unique identifier.

tagGroups/tagValues/subCollection/collectionGroup/reference string

The subcollection group’s unique reference code.

tagGroups/isDeleted Boolean

Determines whether the tag group has been deleted.

enemyItems array optional

Contains the information of any items the item has an enemy relationship with.

enemyItems/id integer

The item’s unique identifier.

enemyItems/isSectionOnly Boolean

Determines whether the enemy relationship is section-level (true) or test form-level (false).

mark integer optional

The item’s assigned mark.

parentId integer optional

If the item is in an item set, the item set’s unique identifier.

citations string optional

Any citations added to the item in HTML format.

comment object optional

Contains the information of any comment left on the item.

comment/text string

Any comment left on the item in text format.

comment/isPrivate 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.

generalFeedback object optional

Contains any general candidate feedback added to the item.

generalFeedback/text string

The feedback text in HTML format.

generalFeedback/sourceMaterials array

Contains any source material added to the feedback.

generalFeedback/sourceMaterials/id integer

The source material’s unique identifier.

generalFeedback/sourceMaterials/externalId string

If using the Nuxeo media repository: the media’s external reference. For more information about Nuxeo, read ‘About Media settings’ in About Site Settings options.

generalFeedback/sourceMaterials/type enumeration

The type of media, Image or Video.

generalFeedback/sourceMaterials/width integer

The media’s width in pixels.

generalFeedback/sourceMaterials/height integer

The media’s height in pixels.

generalFeedback/media object

Contains the information of any media attached to the general feedback.

generalFeedback/media/id integer

The media’s unique identifier.

generalFeedback/media/externalId string

If using the Nuxeo media repository: the media’s external reference. For more information about Nuxeo, read ‘About Media settings’ in About Site Settings options.

generalFeedback/media/type enumeration

The type of media, Image or Video.

generalFeedback/media/width integer

The media’s width in pixels.

generalFeedback/media/height integer

The media’s height in pixels.

mediaItems array optional

Contains any media embedded on the item.

NOTE: If the item contains multiple pieces of embedded media, pass a separate object for each piece of media.

mediaItems/id integer

The media’s unique identifier.

mediaItems/externalId string

If using the Nuxeo media repository: the media’s external reference. For more information about Nuxeo, read ‘About Media settings’ in About Site Settings options.

mediaItems/name string

The media’s name in Surpass.

language object optional

If item language variants are enabled and the LanguageVariant path parameter is passed in the request’s header, contains the information for the new language variant.

language/code enumeration

maxCharacters integer mandatory

The maximum number of characters allowed for the candidate’s response.

numberOfLinesPerResponse integer optional

The number of lines provided for the candidate’s response if the test is being delivered on paper.

enableTextFormatting Boolean optional

Determines whether the Enable text formatting for candidates setting is enabled, letting candidates use basic formatting tools when writing their response.

displayCounter Boolean optional

Determines whether the Display word counter setting is enabled, letting candidates view their current word count when writing their response.

wordCounterLabel string optional

The name of the word counter if essayQuestions/displayCounter is true.

allowDiagrams Boolean optional

Determines whether the Diagram Creator tool is enabled.

NOTE: This property is only available for Essay questions created in Mixed subjects.

diagramsButtonLabel Boolean optional

The Diagram Creator tool’s button text if allowDiagrams is true.

NOTE: This property is only available for Essay questions created in Mixed subjects.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the new item’s details(the response value is the item’s unique identifier).

{
    "response": 1,
    "serverTimeZone": "GMT Standard Time"
}

Updating an Essay question

put /oapi/Item/Essay/{id}

Send a request to the endpoint to update a specific Essay question. The item’s name, tags, and enemy relationships can be updated using this endpoint.

IMPORTANT: Properties other than the item’s name, tags, and enemy relationships may be passed in the request body and return a 200 HTTP status code, but these changes will not take effect.

Parameters

NOTE: An authorization header is mandatory, but the required input may vary. Read Connecting to the Surpass OAPI for more information on authentication and authorisation.

Name	Parameter	Input	Description
authorization	header OPTIONAL	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
authorization	header OPTIONAL	`Bearer {token}`	A bearer token must be passed to authorise the user’s request, where `{token}` is a JWT (JSON web token).
content-type	header MANDATORY	`application/json`	Determines data format of the request (JSON).
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`	Determines data format of the response (JSON).
id	path MANDATORY	`/oapi/Item/Essay/{id}`	Updates specified item, where `{id}` is the item’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 Essay question. Refer to the request body schema for all properties that can be updated.

{
    "name": "Essay question 2"
}

EXAMPLE: In this sample request, the item’s name is updated to ‘Essay question 2’.

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.

tagGroups array

Contains the information of any tags assigned to the item.

NOTE: To assign multiple tag values from multiple tag groups or collections to the item, pass a separate object for each tag group.

tagGroups/id integer

The tag group’s unique identifier.

tagGroups/name string

The tag group’s name.

tagGroups/tagCategories array

Contains the information of any tag categories the tag group is in.

NOTE: This property is not currently supported and will not assign any tag groups to a defined tag category.

tagGroups/tagValues array

Contains the information of the tag value(s) assigned to the item.

NOTE: To assign multiple tag values to the item, pass a separate object for each tag value.

tagGroups/tagValues/id integer

The tag value’s unique identifier.

tagGroups/tagValues/value string

The tag value.

tagGroups/tagValues/isItemSetTag Boolean

If true, the tag value is inherited from the item set.

tagGroups/tagValues/collection object

Contains the information of any tag collections the tag value is in.

NOTE: To add the tag value to multiple tag collections, pass a separate tag group object for each tag collection.

tagGroups/tagValues/collection/id integer

The tag collection’s unique identifier.

tagGroups/tagValues/collection/reference string

The tag collection’s unique reference code.

tagGroups/tagValues/collection/name string

The tag collection’s name.

tagGroups/tagValues/collection/order integer

The tag collection’s position within the tag collection group.

tagGroups/tagValues/collection/isCurrent Boolean

Determines whether the tag collection is the latest tag collection. Only the latest tag values can be returned when searching for items in Item Search.

tagGroups/tagValues/collection/collectionGroup object

Contains the tag collection’s tag collection group information.

tagGroups/tagValues/collection/collectionGroup/id integer

The tag collection group’s unique identifier.

tagGroups/tagValues/collection/collectionGroup/reference string

The tag collection group’s unique reference code.

tagGroups/tagValues/collection/subCollection object

Contains the information of any subcollections the tag value is in.

tagGroups/tagValues/collection/subCollection/reference string

The subcollection’s unique reference code.

tagGroups/tagValues/collection/subCollection/name string

The subcollection’s name.

tagGroups/tagValues/collection/subCollection/order integer

The subcollection’s position within the subcollection group.

tagGroups/tagValues/subCollection/collectionGroup object

Contains the subcollection’s subcollection group information.

tagGroups/tagValues/subCollection/collectionGroup/id integer

The subcollection group’s unique identifier.

tagGroups/tagValues/subCollection/collectionGroup/reference string

The subcollection group’s unique reference code.

tagGroups/isDeleted Boolean

Determines whether the tag group has been deleted.

enemyItems array

Contains the information of any items the item has an enemy relationship with.

enemyItems/id integer

The item’s unique identifier.

enemyItems/isSectionOnly Boolean

Determines whether the enemy relationship is section-level (true) or test form-level (false).

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the updated Essay question’s details.

{
    "response": 1,
    "serverTimeZone": "GMT Standard Time"
}

Deleting an item

delete /oapi/Item/{id}

Send a request to the endpoint to delete a specific item. No request body is required.

IMPORTANT: Items at any workflow status can be deleted using this API. If the item is not already in the subject’s recycle bin, the first request moves the item into the subject’s recycle bin (the permanentlyDeleted property is false) and then the second request permanently deletes the item (permanentlyDeleted is true).

Parameters

NOTE: An authorization header is mandatory, but the required input may vary. Read Connecting to the Surpass OAPI for more information on authentication and authorisation.

Name	Parameter	Input	Description
authorization	header OPTIONAL	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
authorization	header OPTIONAL	`Bearer {token}`	A bearer token must be passed to authorise the user’s request, where `{token}` is a JWT (JSON web token).
accept	header OPTIONAL	`application/json`	Determines data format of the response (JSON).
id	path MANDATORY	`/oapi/Item/{id}`	Deletes specified item, where `{id}` is the item’s unique identifier.

Sample response

If successful, the HTTP status code will be 200 and the response body will confirm the item has been deleted by returning a null id.

{
    "permanentlyDeleted": true,    
    "id": null,
    "href": null,
    "errors": null,
    "serverTimeZone": null
}

Error Codes

Refer to the following table for information on error codes that may be encountered when using this resource.

Code	Description
400	Indicates one of the following issues: There is an issue with the query parameters. Item is locked by another user. Item cannot be created. Essay item cannot be updated.
401	The request has been sent by an unauthorised user.
403	Item cannot be accessed.
404	Item does not exist.

In This Article

Listing items

Parameters

Sample response

Response schema

Listing item versions

Parameters

Sample response

Response schema

Retrieving item information

Parameters

Sample response

Response schema

Creating an item

Creating a Multiple Choice question

Parameters

Sample request

Request body schema

Sample response

Creating a Multiple Response question

Parameters

Sample request

Request body schema

Sample response

Creating an Either/Or question

Parameters

Sample request

Request body schema

Sample response

Creating an Essay question

Parameters

Sample request

Request body schema

Sample response

Updating an Essay question

Parameters

Sample request

Request body schema

Sample response

Deleting an item

Parameters

Sample response

Error Codes

Further reading

About the site