BasicPageLanguageVariant API

IMPORTANT: Item language variants are not available by default. For more information, read Creating and managing language variants.

Item language variants let you author variations of an item in different languages. Language variants can only be created for Multiple Choice, Multiple Response, Either/Or, and Essay item types (read LangaugeVariant API for more information); and Introduction, Information, and Finish Pages.

This article explains what calls can be made to the Surpass API using the BasicPageLanguageVariant resource.

Import this API into your Postman Workspace

Retrieving basic page language variant information

get /api/v2/BasicPage/{id}/BasicPageLanguageVariant/{languageCode}

Send a request to the endpoint to retrieve information for a specific language variant using its ISO language code. No request body is required.

Parameters

Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ? after any path parameters.

Name	Parameter	Input	Description
authorization	header MANDATORY	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
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` or `application/xml`	Determines data format of the response, which can be either JSON or XML.
id	path MANDATORY	`/api/v2/BasicPage/{id}/BasicPageLanguageVariant/{languageCode}`	Returns information for the specified language variant, where `{id}` is the item’s unique identifier.
languageCode	path MANDATORY	`/api/v2/BasicPage/{id}/BasicPageLanguageVariant/{languageCode}`	Returns information for the specified language variant, where `{languageCode}` is the language variant’s ISO language code.

Sample response

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

{
    "count": null,
    "top": null,
    "skip": null,
    "pageCount": null,
    "nextPageLink": null,
    "prevPageLink": null,
    "response": [
        {
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1",
                "name": "Geography Subject"
            },
            "folder": null,
            "name": "Geography Test Form 1 - Finish Page | French",
            "type": "FinishPage",
            "questionText": "Vous avez terminé votre test. Vos résultats seront disponibles prochainement.",
            "htmlText": "Vous avez terminé votre test. Vos résultats seront disponibles prochainement.",
            "contentType": "RichText",
            "mathMl": null,
            "assistiveMedia": null,
            "additionalHtmlText": null,
            "additionalMathMl": null,
            "additionalContentType": "RichText",
            "status": "Live",
            "comment": "",
            "commentIsPrivate": false,
            "mediaItems": [],
            "sourceMaterials": [],
            "itemTagValues": [],
            "stemComponents": [
                {
                    "id": 0,
                    "text": "Vous avez terminé votre test. Vos résultats seront disponibles prochainement.",
                    "mathMl": null,
                    "media": null
                }
            ],
            "allowOpenImageInPopup": false,
            "mediaLayout": "AutoSelect",
            "deleted": false,
            "tools": [],
            "owner": {
                "id": 1,
                "reference": "User1",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/User/1"
            },
            "comments": [],
            "id": 1,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/BasicPage/1"
        }
    ],
    "errors": null,
    "serverTimeZone": "GMT Standard Time"
}

Response schema

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

count integer

Details how many language variants there are in total. This is null because the information retrieved is for a specific language variant.

top integer

Details number of language variants returned in the response. This is null because the information retrieved is for a specific language variant.

skip integer

Details how many language variants were skipped to display those in the response. This is null because the information retrieved is for a specific language variant.

pageCount integer

Details how many pages of language variants there are. This is null because the information retrieved is for a specific language variant.

nextPageLink string

The endpoint to call the next page of language variant. This is null because the information retrieved is for a specific language variant.

prevPageLink string

The endpoint to call the previous page of language variants. This is null because the information retrieved is for a specific language variant.

response array

Contains the rest of the response.

folder object

Contains the folder that the language variant is in. If null, the language variant is not in a folder.

folder/id integer

The folder’s unique identifier.

folder/href string

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

folder/position integer

The position of the language variant within the folder.

name string

The language variant’s name. This is the item’s name with the name of the language following a pipe symbol, for example “Item 1 | Arabic“.

type enumeration

The item type, which can be one of IntroductionPage, InformationPage, or FinishPage.

questionText string

The first question stem block in HTML format. If the language variant has multiple question stem blocks, see the stemComponents object. If null, the language variant does not have any question text.

htmlText string

The first question stem block in HTML format.

NOTE: This is a retired property and therefore returns the same information as the questionText and stemComponents objects.

contentType enumeration

Determines the content type for the first question stem block. This can be either RichText or an Image.

mathML string

If the first question stem block contains formula authored using WIRIS EDITOR math, this information is returned in MathML format. If null, the language variant does not contain any formula.

assistiveMedia object

Contains any assistive media if it has been attached to the first question stem block. If null, the language variant does not contain any assistive media.

assistiveMedia/id integer

The assistive media’s unique identifier.

assistiveMedia/href string

The endpoint to call the assistive media’s information, such as /api/v2/BasicPage/{id}/LanguageVariant/{languageCode}/AssistiveMedia/{id} where {id} is the item’s unique identifier, {languageCode} is the language variant’s ISO code, and {id} is the assistive media’s unique identifier.

additionalHTMLText string

Contains any additional information in HTML format if the language variant is an Introduction Page or Finish Page.

additionalMathMl string

Contains any additional formula in MathML format if the language variant is an Introduction Page or Finish Page.

additionalContentType enumeration

Determines the content type for the additional information if the language variant is an Introduction Page or Finish Page. This can be either RichText or MathML.

status enumeration

The language variant’s workflow status. The default workflow statuses are Draft, To Review, Reviewed, Live, and Withdrawn. Every language variant 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 language variants.

comment string

Any comment left on the language variant in text format.

commentIsPrivate Boolean

Determines whether the comment is a private comment (only viewable by users with the Comment Manager permission) or not.

mediaItems array

Contains any media embedded on the language variant.

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

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/id integer

The media’s unique identifier.

sourceMaterials array

Contains any source material attached to the language variant.

NOTE: If the language variant contains multiple source materials, a separate object for each source material is returned.

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.

sourceMaterials/id integer

The source material’s unique identifier.

itemTagValues array

Contains the information of any tags added to the language variant.

itemTagValues/id integer

The tag value’s unique identifier.

itemTagValues/href string

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

stemComponents array

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

NOTE: If the language variant contains multiple question stems, a separate object for each stem is returned.

stemComponents/id integer

The question stem’s unique identifier.

stemComponents/text string

The question stem’s text in HTML format.

NOTE: Any media added to the question stem or formula authored using WIRIS EDITOR math is also returned in this property.

stemComponents/mathML string

If the question stem contains any formula authored using WIRIS EDITOR math, this information is returned in MathML format. If null, the language variant does not contain any formula.

stemComponents/media object

NOTE: This property is for use in legacy (mixed) subjects and is therefore obsolete. Any media added to the question stem in standard subjects is returned in the stemComponents/text property.

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/id integer

The media’s unique identifier.

allowOpenImageInPopup Boolean

Determines whether the Allow image to be opened in popup setting is enabled if an image is added to Step 3 of the language variant.

mediaLayout enumeration

The media layout if media is added to Step 3 of the language variant. The layout options are AutoSelect, LeftAnswer, RightAnswer, AboveQuestionText, AboveAnswer, and BelowAnswer.

deleted Boolean

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

tools array

Contains the information of any tools added to the language variant.

tools/name enumeration

The type of tool. The available tools are Calculator and Caliper (HTML subjects only).

tools/settings array

Contains the tool’s name and settings.

tools/settings/mode enumeration

The tool mode. The available modes are Basic (calculator), Pixels (caliper; HTML subjects only), and Scientific (calculator).

tools/settings/label string

The name given to the tool.

owner object

The language variant owner’s information.

owner/id integer

The language variant owner’s unique identifier.

owner/reference string

The language variant owner’s unique reference code.

owner/href string

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

comments array

Contains the information for any comments left on the language variant.

NOTE: If the the language variant 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/private Boolean

Determines whether the comment is a private comment (only viewable by users with the Comment Manager permission) or not.

comments/dateCreated string

The date the comment was left, in YYYY/MM/DD format.

comments/createdBy array

Contains the user who left the comment’s information.

comments/createdBy/id integer

The user’s unique identifier.

comments/createdBy/reference string

The user’s unique reference code.

comments/createdBy/href string

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

id integer

The language variant’s unique identifier, which is the same as its parent item.

href string

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

errors string

Information about any errors that occurred during the request.

serverTimeZone enumeration

The timezone of the server sending the response.

Creating a basic page language variant

post /api/v2/BasicPage/{id}/BasicPageLanguageVariant

Send a request to the endpoint to create a language variant.

Parameters

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 OPTIONAL	`application/json` or `application/xml`	Determines data format of the request, which can be either JSON or XML.
accept	header OPTIONAL	`application/json` or `application/xml`	Determines data format of the response, which can be either JSON or XML.

Sample request

The following request contains the minimum required request body to create a language variant.

{
  "language": {
    "code": "fr"
  }
}

EXAMPLE: In this sample request, a French language variant of the item is created.

Request body schema

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

language object mandatory

Contains the information for the language variant’s language.

language/code enumeration

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

htmlText string optional

The first question stem block in HTML format.

NOTE: This is a retired property and should therefore not be used.

mathML string optional

If the first question stem block contains formula authored using WIRIS EDITOR math, pass this information in MathML format.

contentType enumeration optional

Determines the content type for the first question stem block. This can be either RichText or an Image.

additionalHTMLText string optional

Contains any additional information in HTML format if the language variant is an Introduction Page or Finish Page.

additionalMathMl string optional

Contains any additional formula in MathML format if the language variant is an Introduction Page or Finish Page.

additionalContentType enumeration optional

Determines the content type for the additional information if the language variant is an Introduction Page or Finish Page. This can be either RichText or MathML.

status enumeration optional

comment string optional

Any comment left on the language variant in text format.

commentIsPrivate Boolean optional

Determines whether the comment is a private comment (only viewable by users with the Comment Manager permission) or not.

mediaItems array optional

Contains any media to be embedded on the language variant.

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

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/id integer

The media’s unique identifier.

sourceMaterials array optional

Contains any source material to be attached to the language variant.

NOTE: If the language variant contains multiple source materials, pass a separate object for each source material.

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.

sourceMaterials/id integer

The source material’s unique identifier.

stemComponents array optional

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

NOTE: If the language variant contains multiple question stems, pass a separate object for each stem.

stemComponents/id integer

The question stem’s unique identifier.

stemComponents/text string

The question stem’s text in HTML format.

NOTE: Any media added to the question stem or formula authored using WIRIS EDITOR math should also be passed in this property.

stemComponents/mathML string

If the question stem contains any formula authored using WIRIS EDITOR math, pass this information in MathML format.

stemComponents/media object

NOTE: This property is for use in legacy (mixed) subjects and is therefore obsolete. Any media added to the question stem in standard subjects must be passed in the stemComponents/text property.

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/id integer

The media’s unique identifier.

allowOpenImageInPopup Boolean optional

Determines whether the Allow image to be opened in popup setting is enabled if an image is added to Step 3 of the language variant.

mediaLayout enumeration optional

The media layout if media is added to Step 3 of the language variant. The layout options are AutoSelect, LeftAnswer, RightAnswer, AboveQuestionText, AboveAnswer, and BelowAnswer.

deleted Boolean optional

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

tools array optional

Contains the information of any tools to be added to the language variant.

tools/name enumeration

The type of tool. The available tools are Calculator and Caliper (HTML subjects only).

tools/settings array

Contains the tool’s name and settings.

tools/settings/mode enumeration

The tool mode. The available modes are Basic (calculator), Pixels (caliper; HTML subjects only), and Scientific (calculator).

tools/settings/label string

The name given to the tool.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the new language variant’s details.

{
    "language": {
        "name": "Français",
        "code": "fr"
    },
    "id": 1,
    "href": "https://{your Surpass instance}.surpass.com/api/v2/BasicPage/1/LanguageVariant/fr",
    "errors": null
}

Updating a basic page language variant

put /api/v2/BasicPage/{id}/BasicPageLanguageVariant/{languageCode}

Send a request to the endpoint to update a specific language variant.

Parameters

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 OPTIONAL	`application/json` or `application/xml`	Determines data format of the request, which can be either JSON or XML.
accept	header OPTIONAL	`application/json` or `application/xml`	Determines data format of the response, which can be either JSON or XML.
id	path MANDATORY	`/api/v2/BasicPage/{id}/BasicPageLanguageVariant/{languageCode}`	Updates information for the specified language variant, where `{id}` is the item’s unique identifier.
languageCode	path MANDATORY	`/api/v2/BasicPage/{id}/BasicPageLanguageVariant/{languageCode}`	Updates information for the specified language variant, where `{languageCode}` is the language variant’s ISO language code.

Sample request

At least one property must be updated in the request. The following request contains the minimum required request body to update a language variant. Refer to the request body schema for all properties that can be updated.

{
    "status": "To review"
}

EXAMPLE: In this sample request, the language variant’s status is updated.

Request body schema

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

language object

Contains the information for the language variant’s language.

language/code enumeration

htmlText string

The first question stem block in HTML format.

NOTE: This is a retired property and should therefore not be used.

mathML string

If the first question stem block contains formula authored using WIRIS EDITOR math, pass this information in MathML format.

contentType enumeration

Determines the content type for the first question stem block. This can be either RichText or an Image.

additionalHTMLText string

Contains any additional information in HTML format if the language variant is an Introduction Page or Finish Page.

additionalMathMl string

Contains any additional formula in MathML format if the language variant is an Introduction Page or Finish Page.

additionalContentType enumeration

Determines the content type for the additional information if the language variant is an Introduction Page or Finish Page. This can be either RichText or MathML.

status enumeration

comment string

Any comment left on the language variant in text format.

commentIsPrivate Boolean

Determines whether the comment is a private comment (only viewable by users with the Comment Manager permission) or not.

mediaItems array

Contains any media to be embedded on the language variant.

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

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/id integer

The media’s unique identifier.

sourceMaterials array

Contains any source material to be attached to the language variant.

NOTE: If the language variant contains multiple source materials, pass a separate object for each source material.

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.

sourceMaterials/id integer

The source material’s unique identifier.

stemComponents array

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

NOTE: If the language variant contains multiple question stems, pass a separate object for each stem.

stemComponents/id integer

The question stem’s unique identifier.

stemComponents/text string

The question stem’s text in HTML format.

NOTE: Any media added to the question stem or formula authored using WIRIS EDITOR math should also be passed in this property.

stemComponents/mathML string

If the question stem contains any formula authored using WIRIS EDITOR math, pass this information in MathML format.

stemComponents/media object

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/id integer

The media’s unique identifier.

allowOpenImageInPopup Boolean

Determines whether the Allow image to be opened in popup setting is enabled if an image is added to Step 3 of the language variant.

mediaLayout enumeration

The media layout if media is added to Step 3 of the language variant. The layout options are AutoSelect, LeftAnswer, RightAnswer, AboveQuestionText, AboveAnswer, and BelowAnswer.

deleted Boolean

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

tools array

Contains the information of any tools to be added to the language variant.

tools/name enumeration

The type of tool. The available tools are Calculator and Caliper (HTML subjects only).

tools/settings array

Contains the tool’s name and settings.

tools/settings/mode enumeration

The tool mode. The available modes are Basic (calculator), Pixels (caliper; HTML subjects only), and Scientific (calculator).

tools/settings/label string

The name given to the tool.

Sample response

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

{
    "language": {
        "name": null,
        "code": "fr"
    },
    "id": 1,
    "href": "https://{your Surpass instance}.surpass.com/api/v2/BasicPage/1/LanguageVariant/fr",
    "errors": null
}

Deleting a basic page language variant

delete /api/v2/BasicPage/{id}/BasicPageLanguageVariant/{languageCode}

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

IMPORTANT: The first request archives the language variant and then the second request permanently deletes the language variant.

Parameters

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` or `application/xml`	Determines data format of the response, which can be either JSON or XML.
id	path MANDATORY	`/api/v2/BasicPage/{id}/BasicPageLanguageVariant/{languageCode}`	Deletes the specified language variant, where `{id}` is the item’s unique identifier.
languageCode	path MANDATORY	`/api/v2/BasicPage/{id}/BasicPageLanguageVariant/{languageCode}`	Deletes the specified language variant, where `{languageCode}` is the language variant’s ISO language code.

Sample response

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

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

Error Codes

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

Name	Code	Description
InternalServer	1	Internal server error.
Unauthorized	3	The request has been sent by an unauthorised user.
IncorrectFieldFormat	4	A field in the request has not been completed in the correct format.
InaccessibleOperation	5	The request has been sent by a user with invalid permissions.
InaccessibleData	6	The request has been sent by a user with invalid permissions.
MissingBody	7	There is an issue with the request body.
InvalidReference	11	The unique reference code used in the request is invalid.
InvalidInputParameters	15	There is an issue with the path or query parameters.
LanguageVariantAlreadyExists	15	The item language variant you are trying to create already exists for the specified parent item.
InvalidId	16	The ID number used in the request is invalid.
InvalidODataOperation	19	There is an issue with the query parameters.
ItemDoesNotExist	158	The item specified in the request does not exist.
UnmatchedItem	247	The question type array included in the request does not match the question type of the default language (parent item).

BasicPageLanguageVariant API

In This Article

Retrieving basic page language variant information

Parameters

Sample response

Response schema

Creating a basic page language variant

Parameters

Sample request

Request body schema

Sample response

Updating a basic page language variant

Parameters

Sample request

Request body schema

Sample response

Deleting a basic page language variant

Parameters

Sample response

Error Codes

About the site