LanguageVariant 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, and only exist across the Item Authoring and Tasks screens.

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

Import this API into your Postman Workspace

Retrieving language variant information

get /api/v2/Item/{id}/LanguageVariant/{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.
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/Item/{id}/LanguageVariant/{languageCode}`	Returns information for the specified language variant, where `{id}` is the item’s unique identifier.
languageCode	path MANDATORY	`/api/v2/Item/{id}/LanguageVariant/{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": [
        {
            "itemMajorVersion": 0,
            "itemVersion": 0,
            "deleted": false,
            "questionText": "Quel continent est mis en évidence dans l'image ci-dessous?",
            "htmlText": null,
            "mathMl": null,
            "assistiveMedia": null,
            "mark": 1,
            "status": "Live",
            "comment": "",
            "generalFeedback": null,
            "correctFeedback": null,
            "incorrectFeedback": null,
            "mediaItems": null,
            "sourceMaterials": [],
            "stemComponents": [
                {
                    "id": 0,
                    "text": "Quel continent est mis en évidence dans l'image ci-dessous?",
                    "mathMl": null,
                    "media": null
                }
            ],
            "multipleChoiceQuestions": [
                {
                    "answerWidthRatio": "50/50",
                    "optionList": {
                        "options": [
                            {
                                "assistiveMedia": null,
                                "id": 1,
                                "contentType": "RichText",
                                "text": "<p>Amérique du Sud</p>",
                                "htmlText": null,
                                "mathMl": null,
                                "mediaItem": null,
                                "answerColumns": [
                                    {
                                        "text": "<p>Amérique du Sud</p>",
                                        "mathMl": null,
                                        "media": null
                                    }
                                ],
                                "correct": true,
                                "label": null,
                                "rationaleText": null,
                                "exclusiveOption": false
                            },
                            {
                                "assistiveMedia": null,
                                "id": 2,
                                "contentType": "RichText",
                                "text": "<p>L'Europe</p>",
                                "htmlText": null,
                                "mathMl": null,
                                "mediaItem": null,
                                "answerColumns": [
                                    {
                                        "text": "<p>L'Europe</p>",
                                        "mathMl": null,
                                        "media": null
                                    }
                                ],
                                "label": null,
                                "rationaleText": null,
                                "exclusiveOption": false
                            },
                            {
                                "assistiveMedia": null,
                                "id": 3,
                                "contentType": "RichText",
                                "text": "<p>Asie</p>",
                                "htmlText": null,
                                "mathMl": null,
                                "mediaItem": null,
                                "answerColumns": [
                                    {
                                        "text": "<p>Asie</p>",
                                        "mathMl": null,
                                        "media": null
                                    }
                                ],
                                "label": null,
                                "rationaleText": null,
                                "exclusiveOption": false
                            },
                            {
                                "assistiveMedia": null,
                                "id": 4,
                                "contentType": "RichText",
                                "text": "<p>Afrique</p>",
                                "htmlText": null,
                                "mathMl": null,
                                "mediaItem": null,
                                "answerColumns": [
                                    {
                                        "text": "<p>Afrique</p>",
                                        "mathMl": null,
                                        "media": null
                                    }
                                ],
                                "label": "D",
                                "rationaleText": null,
                                "exclusiveOption": false
                            }
                        ]
                    },
                    "randomise": false,
                    "addLabelsToOptions": false,
                    "markType": "Standard",
                    "tableOptionsHtml": null
                }
            ],
            "multipleResponseQuestions": null,
            "essayQuestions": null,
            "eitherOrQuestions": null,
            "allowOpenImageInPopup": false,
            "mediaLayout": "AutoSelect",
            "tools": [],
            "comments": [],
            "language": {
                "name": "French",
                "code": "fr"
            },
            "id": 1,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/Item/1/LanguageVariant/fr"
        }
    ],
    "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.

itemMajorVersion integer

The language variant’s major version.

Whenever a language variant is changed and saved, Surpass creates a new language variant version. Language variants 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 language variant version is created every time there are saved changes to the language variant owner or workflow status. Any changes made to live language variants 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 Account Manager.

itemVersion integer

The language variant’s minor version. See the itemMajorVersion object above for more information.

EXAMPLE: If the itemVersioninteger returned is 2 and the itemMajorVersion returned is 4, the language variant’s version is 4.2.

deleted Boolean

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

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 as null.

mathML string

If the first question stem block contains formula authored using the Equation Editor (Mixed subjects) or WIRIS EDITOR math (HTML subjects), this information is returned in MathML format. If null, the 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/Item/{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.

mark integer

The language variant’s assigned mark.

status enumeration

The language variant’s workflow status. The default workflow statuses are Draft, To Review, Reviewed, Live, and Withdrawn. Custom workflow statuses can also be created and assigned to language variants.

comment string

Any comment left on the language variant in text format. If blank, the language variant does not contain a comment.

generalFeedback object

Contains any general candidate feedback added to the language variant. If null, the language variant does not contain any feedback.

generalFeedback/text string

The feedback text in HTML format.

generalFeedback/htmlText string

The feedback text in HTML format.

NOTE: This is a retired property and therefore returns as null.

generalFeedback/mediaItems array

Contains any media added to the feedback.

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

generalFeedback/mediaItems/id integer

The media’s unique identifier.

generalFeedback/sourceMaterials array

Contains any source material added to the feedback.

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

generalFeedback/sourceMaterials/id integer

The source material’s unique identifier.

correctFeedback object

Contains any correct candidate feedback added to the language variant. If null, the language variant does not contain any feedback.

NOTE: Only language variants in Mixed subjects can contain correct feedback.

correctFeedback/text string

The feedback text in HTML format.

correctFeedback/htmlText string

The feedback text in HTML format.

NOTE: This is a retired property and therefore returns as null.

correctFeedback/mediaItems array

Contains any media added to the feedback.

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

correctFeedback/mediaItems/id integer

The media’s unique identifier.

correctFeedback/sourceMaterials array

Contains any source material added to the feedback.

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

correctFeedback/sourceMaterials/id integer

The source material’s unique identifier.

incorrectFeedback object

Contains any incorrect candidate feedback added to the language variant. If null, the language variant does not contain any feedback.

NOTE: Only language variants in Mixed subjects can contain incorrect feedback.

incorrectFeedback/text string

The feedback text in HTML format.

incorrectFeedback/htmlText string

The feedback text in HTML format.

NOTE: This is a retired property and therefore returns as null.

incorrectFeedback/mediaItems array

Contains any media added to the feedback.

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

incorrectFeedback/mediaItems/id integer

The media’s unique identifier.

incorrectFeedback/sourceMaterials array

Contains any source material added to the feedback.

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

incorrectFeedback/sourceMaterials/id integer

The source material’s unique identifier.

mediaItems array

Contains any media embedded on the language variant. If null, the language variant does not contain any embedded media.

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

mediaItems/id integer

The media’s unique identifier.

sourceMaterials array

Contains any source material attached to the language variant. If null, the language variant does not contain any source material.

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

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, a separate object for each stem is returned. Media or formula cannot be part of the first question stem for language variants in Mixed subjects.

stemComponents/text string

The question stem’s text in HTML format.

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

stemComponents/id integer

The question stem’s unique identifier.

stemComponents/mathML string

If the question stem contains any formula authored using the Equation Editor (Mixed subjects) or WIRIS EDITOR math (HTML subjects), this information is returned in MathML format. If null, the language variant does not contain any formula.

stemComponents/media object

Contains any media in the question stem for language variants in Mixed subjects.

NOTE: Any media added to the question stem in HTML subjects is returned in the stemComponents/text property.

stemComponents/media/id integer

The media’s unique identifier.

multipleChoiceQuestions array

Contains information relating to the Multiple Choice question type.

A Multiple Choice question offers candidates a set of possible answers to a problem. One of these answers is the correct answer and the others are plausible but incorrect answers (also known as “distractors”). Candidates can select one answer option as their response.

If null, the language variant is not a Multiple Choice question.

multipleChoiceQuestions/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.

multipleChoiceQuestions/optionList object

Contains the answer options’ information.

multipleChoiceQuestions/optionList/options array

Contains each answer option’s information.

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

multipleChoiceQuestions/optionList/options/assistiveMedia object

Contains any assistive media’s information. If null, the answer option does not contain any assistive media.

multipleChoiceQuestions/optionList/options/assistiveMedia/id integer

The assistive media’s unique identifier.

multipleChoiceQuestions/optionList/options/assistiveMedia/href string

multipleChoiceQuestions/optionList/options/id integer

The answer option’s unique identifier.

multipleChoiceQuestions/optionList/options/contentType enumeration

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

NOTE: Answer options can only be either text (RichText) or media (Image).

multipleChoiceQuestions/optionList/options/text string

The answer option text in HTML format. If the Layout options are set to Two columns, this only returns the text in the first column.

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).

multipleChoiceQuestions/optionList/options/htmlText string

The answer option text in HTML format.

NOTE: This is a retired property and therefore returns as null.

multipleChoiceQuestions/optionList/options/mathML string

If the answer option contains formula authored using the Equation Editor (Mixed subjects) or WIRIS EDITOR math (HTML subjects), this information is returned in MathML format. If null, the content type is not MathML.

multipleChoiceQuestions/optionList/options/mediaItem object

Contains any media used as the answer option. If null, the content type is not Image.

multipleChoiceQuestions/optionList/options/mediaItem/id integer

The media’s unique identifier.

multipleChoiceQuestions/optionList/options/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.

multipleChoiceQuestions/optionList/options/answerColumns/text 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).

multipleChoiceQuestions/optionList/options/answerColumns/mathML string

multipleChoiceQuestions/optionList/options/answerColumns/media object

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

multipleChoiceQuestions/optionList/options/answerColumns/media/id integer

The media’s unique identifier.

multipleChoiceQuestions/optionList/options/correct Boolean

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

multipleChoiceQuestions/optionList/options/label string

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

multipleChoiceQuestions/optionList/options/weightedMark integer

The mark assigned to the answer option if the Marking type is set to Weighted.

multipleChoiceQuestions/optionList/options/rationaleText string

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

multipleChoiceQuestions/optionList/options/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 Multiple Choice questions.

multipleChoiceQuestions/randomise Boolean

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

multipleChoiceQuestions/addLabelsToOptions Boolean

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

multipleChoiceQuestions/markType enumeration

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

multipleChoiceQuestions/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).

multipleResponseQuestions array

Contains information relating to the Multiple Response question type.

A Multiple Response question offers candidates a set of possible answers to a question. The options contain correct answers and plausible but incorrect answers (also known as distractors). Candidates can select multiple answer options as their response.

If null, the language variant is not a Multiple Response question.

multipleResponseQuestions/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.

multipleResponseQuestions/optionList object

Contains the answer options’ information.

multipleResponseQuestions/optionList/options array

Contains each answer option’s information.

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

multipleResponseQuestions/optionList/options/assistiveMedia object

Contains any assistive media’s information. If null, the answer option does not contain any assistive media.

multipleResponseQuestions/optionList/options/assistiveMedia/id integer

The assistive media’s unique identifier.

multipleResponseQuestions/optionList/options/assistiveMedia/href string

multipleResponseQuestions/optionList/options/id integer

The answer option’s unique identifier.

multipleResponseQuestions/optionList/options/contentType enumeration

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

NOTE: Answer options can only be either text (RichText) or media (Image).

multipleResponseQuestions/optionList/options/text string

The answer option text in HTML format. If the Layout options are set to Two columns, this only returns the text in the first column.

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).

multipleResponseQuestions/optionList/options/htmlText string

The answer option text in HTML format.

NOTE: This is a retired property and therefore returns as null.

multipleResponseQuestions/optionList/options/mathML string

multipleResponseQuestions/optionList/options/mediaItem object

Contains any media used as the answer option. If null, the content type is not Image.

multipleResponseQuestions/optionList/options/mediaItem/id integer

The media’s unique identifier.

multipleResponseQuestions/optionList/options/answerColumns array

multipleResponseQuestions/optionList/options/answerColumns/text 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).

multipleResponseQuestions/optionList/options/answerColumns/mathML string

multipleResponseQuestions/optionList/options/answerColumns/media object

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

multipleResponseQuestions/optionList/options/answerColumns/media/id integer

The media’s unique identifier.

multipleResponseQuestions/optionList/options/correct Boolean

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

multipleResponseQuestions/optionList/options/label string

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

multipleResponseQuestions/optionList/options/weightedMark integer

The mark assigned to the answer option if the Marking type is set to Weighted.

multipleResponseQuestions/optionList/options/rationaleText string

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

multipleResponseQuestions/optionList/options/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.

multipleResponseQuestions/randomise Boolean

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

multipleResponseQuestions/addLabelsToOptions Boolean

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

multipleResponseQuestions/markType enumeration

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

multipleResponseQuestions/combinations array

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

multipleResponseQuestions/combinations/Id integer

The answer option combination’s unique identifier.

multipleResponseQuestions/combinations/Mark integer

The number of marks for the answer option combination.

multipleResponseQuestions/combinations/Title string

The name attributed to the answer option combination.

multipleResponseQuestions/combinations/Options array

Contains the information for the individual answer options that make up the answer option combination.

multipleResponseQuestions/combinations/Options/Id integer

The answer option’s unique identifier.

multipleResponseQuestions/combinations/Options/Text string

The answer option’s label.

multipleResponseQuestions/maxSelections integer

The maximum number of answer options the candidate can select. This is determined by the Maximum number of candidate selections setting, the options for which are Equal to correct options, No Limit, or Custom.

multipleResponseQuestions/partialMarks Boolean

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

multipleResponseQuestions/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).

multipleResponseQuestions/exclusiveOptionEnabled Boolean

Determines whether the Exclusive Option setting is enabled, meaning there is an answer option that cannot be selected in conjunction with other answer options.

essayQuestions array

Contains information relating to the Essay question type.

An Essay question asks candidates to provide an extended written response to a prompt.

If null, the language variant is not an Essay question.

essayQuestions/enableTextFormatting Boolean

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

essayQuestions/maxCharacters integer

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

essayQuestions/numberOfLines integer

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

essayQuestions/displayCounter Boolean

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

essayQuestions/numberOfLinesPerResponse integer

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

essayQuestions/wordCounterLabel string

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

essayQuestions/textDirectionMode integer

Determines the Answer Input Direction for candidates. 0 is Left to right and 1 is Right to left.

eitherOrQuestions array

Contains information relating to the Either/Or question type.

An Either/Or question offers candidates two possible answers to a problem: one of these is the correct answer and the other is a plausible but incorrect answer (also known as a distractor). Candidates can select one answer option as their response.

If null, the language variant is not an Either/Or question.

eitherOrQuestions/randomise Boolean

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

eitherOrQuestions/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.

eitherOrQuestions/optionList object

Contains the answer options’ information.

eitherOrQuestions/optionList/options array

Contains each answer option’s information.

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

eitherOrQuestions/optionList/options/assistiveMedia object

Contains any assistive media’s information. If null, the answer option does not contain any assistive media.

eitherOrQuestions/optionList/options/assistiveMedia/id integer

The assistive media’s unique identifier.

eitherOrQuestions/optionList/options/assistiveMedia/href string

eitherOrQuestions/optionList/options/id integer

The answer option’s unique identifier.

eitherOrQuestions/optionList/options/contentType enumeration

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

NOTE: Answer options can only be either text (RichText) or media (Image).

eitherOrQuestions/optionList/options/text string

The answer option text in HTML format. If the Layout options are set to Two columns, this only returns the text in the first column.

eitherOrQuestions/optionList/options/htmlText string

The answer option text in HTML format.

NOTE: This is a retired property and therefore returns as null.

eitherOrQuestions/optionList/options/mathML string

eitherOrQuestions/optionList/options/mediaItem object

Contains any media used as the answer option. If null, the content type is not Image.

eitherOrQuestions/optionList/options/mediaItem/id integer

The media’s unique identifier.

eitherOrQuestions/optionList/options/answerColumns array

eitherOrQuestions/optionList/options/answerColumns/text string

The answer option text in HTML format.

eitherOrQuestions/optionList/options/answerColumns/mathML string

eitherOrQuestions/optionList/options/answerColumns/media object

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

eitherOrQuestions/optionList/options/answerColumns/media/id integer

The media’s unique identifier.

eitherOrQuestions/optionList/options/correct Boolean

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

eitherOrQuestions/optionList/options/label string

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

eitherOrQuestions/optionList/options/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.

eitherOrQuestions/optionList/options/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.

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.

tools array

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

NOTE: If the language variant contains multiple tools, pass a separate object for each tool.

tools/name enumeration

The type of tool. The available tools are Calculator, Caliper, and Protractor (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.

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.

language object

Contains the information for the language variant’s language.

language/name string

The name of the 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.

id integer

The language variant’s unique identifier.

href string

The endpoint to call the language variant’s information, such as /api/v2/Item/{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 language variant

post /api/v2/Item/{id}/LanguageVariant

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

Parameters

Name

Parameter

Input

Description

authorization

header

MANDATORY

Basic {credentials}

Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string.

content-type

header

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"
  },
    "multipleChoiceQuestions": [
        {}
    ]
}

EXAMPLE: In this sample request, a French language variant of a Multiple Choice question 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

questionText string optional

The first question stem block in HTML format. If the language variant has multiple question stem blocks, use the stemComponents object.

htmlText string optional

The first question stem block in HTML format.

mathML string optional

mark integer optional

The language variant’s assigned mark.

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.

generalFeedback object optional

Contains any general candidate feedback added to the language variant.

generalFeedback/text string

The feedback text in HTML format.

generalFeedback/htmlText string

The feedback text in HTML format.

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

generalFeedback/mediaItems array

Contains any media added to the feedback.

generalFeedback/mediaItems/id integer

The media’s unique identifier.

generalFeedback/sourceMaterials array

Contains any source material added to the feedback.

generalFeedback/sourceMaterials/id integer

The source material’s unique identifier.

correctFeedback object optional

Contains any correct candidate feedback added to the language variant.

NOTE: Only language variants in Mixed subjects can contain correct feedback.

correctFeedback/text string

The feedback text in HTML format.

correctFeedback/htmlText string

The feedback text in HTML format.

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

correctFeedback/mediaItems array

Contains any media added to the feedback.

correctFeedback/mediaItems/id integer

The media’s unique identifier.

correctFeedback/sourceMaterials array

Contains any source material added to the feedback.

correctFeedback/sourceMaterials/id integer

The source material’s unique identifier.

incorrectFeedback object optional

Contains any incorrect candidate feedback added to the language variant.

NOTE: Only language variants in Mixed subjects can contain incorrect feedback.

incorrectFeedback/text string

The feedback text in HTML format.

incorrectFeedback/htmlText string

The feedback text in HTML format.

incorrectFeedback/mediaItems array

Contains any media added to the feedback.

incorrectFeedback/mediaItems/id integer

The media’s unique identifier.

incorrectFeedback/sourceMaterials array

Contains any source material added to the feedback.

incorrectFeedback/sourceMaterials/id integer

The source material’s unique identifier.

mediaItems array optional

Contains any media embedded on the language variant.

mediaItems/id integer

The media’s unique identifier.

sourceMaterials array optional

Contains any source material attached to the language variant.

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: Media or formula cannot be part of the first question stem for language variants in Mixed subjects.

stemComponents/text string

The question stem’s text in HTML format.

stemComponents/id integer

The question stem’s unique identifier.

stemComponents/mathML string

If the question stem contains any formula authored using the Equation Editor (Mixed subjects) or WIRIS EDITOR math (HTML subjects), this information must be passed in MathML format.

stemComponents/media object

Contains any media in the question stem for language variants in Mixed subjects.

stemComponents/media/id integer

The media’s unique identifier.

multipleChoiceQuestions array optional

Contains information relating to the Multiple Choice question type.

IMPORTANT: The question type array included in your request must match the question type of the default language (parent item).

multipleChoiceQuestions/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.

multipleChoiceQuestions/optionList object

Contains the answer options’ information.

multipleChoiceQuestions/optionList/options array

Contains each answer option’s information.

multipleChoiceQuestions/optionList/options/assistiveMedia object

Contains any assistive media’s information.

multipleChoiceQuestions/optionList/options/assistiveMedia/id integer

The assistive media’s unique identifier.

multipleChoiceQuestions/optionList/options/id integer

The answer option’s unique identifier.

multipleChoiceQuestions/optionList/options/contentType enumeration

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

NOTE: Answer options can only be either text (RichText) or media (Image).

multipleChoiceQuestions/optionList/options/text string

The answer option text in HTML format.

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

multipleChoiceQuestions/optionList/options/htmlText string

The answer option text in HTML format.

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

multipleChoiceQuestions/optionList/options/mathML string

If the answer option contains formula authored using the Equation Editor (Mixed subjects) or WIRIS EDITOR math (HTML subjects), this information must be passed in MathML format.

multipleChoiceQuestions/optionList/options/mediaItem object

Contains any media used as the answer option.

multipleChoiceQuestions/optionList/options/mediaItem/id integer

The media’s unique identifier.

multipleChoiceQuestions/optionList/options/answerColumns array

Contains the text, media, or mathML for each answer option column. The first array contains 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.