MediaGroup API
You can combine images and PDF into media groups, which allows them to be used in the high-fidelity image viewer or PDF viewer in SecureClient. This gives lets you create more dynamic content by giving candidates greater interactivity with item media.
You can add 25 images or 60 PDFs to a group. You cannot mix images and PDFs in a single group. Grouped media are always delivered together.
The MediaGroup API resource is used to retrieve, create, and update media groups.
This article explains what calls can be made to the Surpass API using the MediaGroup resource.
Import this API into your Postman Workspace
In This Article
Retrieving media group information
Send a request to the endpoint to retrieve information for a specific media group using its ID. 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/MediaGroup/{id} |
Returns information for the specified media group, where {id} is the media group’s unique identifier. |
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"
},
"name": "Maps",
"description": "Maps of the World",
"media": [
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Media/1"
},
{
"id": 2,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Media/2"
},
],
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/MediaGroup/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 media groups there are in total. This is null because the information retrieved is for a specific media group.
top integer
Details number of media groups returned in the response. This is null because the information retrieved is for a specific media group.
skip integer
Details how many media groups were skipped to display those in the response. This is null because the information retrieved is for specific a media group.
pageCount integer
Details how many pages of media groups there are. This is null because the information retrieved is for a media group.
nextPageLink string
The endpoint to call the next page of media groups. This is null because the information retrieved is for a media group.
prevPageLink string
The endpoint to call the previous page of media groups. This is null because the information retrieved is for a specific media group.
response array
Contains the rest of the response.
subject object
Contains the subject’s information.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
subject/href string
The endpoint to call the subject’s information, such as /api/v2/Subject/{id} where {id} is the subject’s unique identifier.
subject/name string
The subject’s name.
name string
The media group’s name.
description string
The media group’s description.
media array
Contains the media in the group’s information.
media/id integer
The media’s unique identifier.
media/reference string
The media’s unique reference code.
id integer
The media group’s unique identifier.
href string
The endpoint to call the media group’s information, such as /api/v2/MediaGroup/{id} where {id} is the media group’s unique identifier.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Creating a media group
Send a request to the endpoint to create a media group.
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. |
|
content-type |
header MANDATORY |
application/json or application/xml |
Determines data format of the request, which can be either JSON or XML. |
|
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 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 media group.
{
"subject": {
"reference": "Subject1"
},
"name": "Maps of the World",
"media": [
{
"id": 1
}
]
}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’s information.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
name string mandatory
The media group’s name.
description string optional
The media group’s description.
media array mandatory
Contains the media in the group’s information. A media group must contain at least one piece of media.
media/id integer
The media’s unique identifier.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the new media group’s details.
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/MediaGroup/1",
"errors": null,
}Updating a media group
Send a request to the endpoint to update a specific media group.
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. |
|
content-type |
header MANDATORY |
application/json or application/xml |
Determines data format of the request, which can be either JSON or XML. |
|
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 or application/xml |
Determines data format of the response, which can be either JSON or XML. |
|
id |
path MANDATORY |
/api/v2/MediaGroup/{id} |
Updates specified media group, where {id} is the media group’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 a media group. Refer to the request body schema for all properties that can be updated.
{
"name": "Historic Maps"
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
name string
The media group’s name.
description string
The media group’s description.
media array
Contains the media in the group’s information.
media/id integer
The media group’s unique identifier.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the updated media group’s details.
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/MediaGroup/1",
"errors": 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. |
|
InvalidInputParameters |
15 |
There is an issue with the path or query parameters. Or the media isn’t in the subject’s media library. |
|
InvalidId |
16 |
The ID number used in the request is invalid. |
Further reading
Read the following articles to learn more about similar APIs, how to get started with the Surpass API v2, and how to get the best out of this reference documentation: