ItemSetLanguageVariant API

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

Item (set) language variants let you author variations of an item set in different languages and only exist across the Item Authoring and Tasks screens.

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

Import this API into your Postman Workspace

Retrieving item set language variant information

get /api/v2/ItemSet/{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/ItemSet/{id}/LanguageVariant/{languageCode}`	Returns information for the specified language variant, where `{id}` is the item set’s unique identifier.
languageCode	path MANDATORY	`/api/v2/ItemSet/{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": [
        {
            "sourceMaterials": [],
            "comment": "",
            "comments": [],
            "language": {
                "name": "French",
                "code": "fr"
            },
            "id": 39486,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/ItemSet/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 item set language variants there are in total. This is null because the information retrieved is for a specific item set language variant.

top integer

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

skip integer

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

pageCount integer

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

nextPageLink string

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

prevPageLink string

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

response array

Contains the rest of the response.

sourceMaterials array

Contains any source material added to the item set language variant.

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

sourceMaterials/externalId string

The source material’s name.

sourceMaterials/id integer

The source material’s unique identifier.

comment string

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

comments array

Contains the information for any comments left on the item set 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 string

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

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

comments/createdBy object

Contains the user who left the comment’s information.

comments/createdBy/id integer

The user’s unique identifier.

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 related to the item set language variant.

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 item set language variant’s unique identifier.

href string

The endpoint to call the language variant’s information, such as /api/v2/ItemSet/{id}/LanguageVariant/{languageCode} where {id} is the item set’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 an item set language variant

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

Send a request to the endpoint to create an item set 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 an item set language variant.

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

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

Sample response

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

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

Updating an item set language variant

put /api/v2/ItemSet/{id}/LanguageVariant/{languageCode}

Send a request to the endpoint to update details of a specific item set 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.
id	path MANDATORY	`/api/v2/ItemSet/{id}/LanguageVariant/{languageCode}`	Update information for the specified language variant, where `{id}` is the item set’s unique identifier.
languageCode	path MANDATORY	`/api/v2/ItemSet/{id}/LanguageVariant/{languageCode}`	Update 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.

{
    "commentIsPrivate": true
}

EXAMPLE: In this sample request, the comment left on the item set has been made private.

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/ItemSet/1/LanguageVariant/fr",
    "errors": null
}

Deleting an item set language variant

delete /api/v2/ItemSet/{id}/LanguageVariant/{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 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/ItemSet/{id}/LanguageVariant/{languageCode}`	Deletes the specified language variant, where `{id}` is the item set’s unique identifier.
languageCode	path MANDATORY	`/api/v2/ItemSet/{id}/LanguageVariant/{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 set language variant you are trying to create already exists for the specified parent item set.
InvalidId	16	The ID number used in the request is invalid.
InvalidODataOperation	19	There is an issue with the query parameters.
ItemSetDoesNotExist	163	The item specified in the request does not exist.

ItemSetLanguageVariant API

In This Article

Retrieving item set language variant information

Parameters

Sample response

Response schema

Creating an item set language variant

Parameters

Sample request

Request body schema

Sample response

Updating an item set language variant

Parameters

Sample request

Request body schema

Sample response

Deleting an item set language variant

Parameters

Sample response

Error Codes

About the site