Getting started with the Surpass API v2

The Surpass API v2 uses standard HTTP protocols to send and retrieve data. Requests can be made to each Surpass API from a Surpass instance’s corresponding test console, or any other HTTP client.

This article explains what makes up a request to and a response from the Surpass API, and how to access your API test console.

What makes up a request?

A request to the Surpass API is made up of header, query, or path parameters, along with properties in a request body if required, sent to an endpoint with a specified method.

The methods available for the Surpass API v2 are:

Requests can be sent from any HTTP client. However, authorisation details must also be passed in an authorization header parameter. Read Connecting to the Surpass API v2 for more information on authorising and authenticating requests to the Surpass API.

The Surpass API can accept data in JSON or XML format. You must specify the data type by sending a content-type header parameter with the value application/json or application/xml, and the data length using a content-length header parameter.

Sample request

Expand the following section for a sample request.

{
    "subject": {
        "reference": "Subject1"
    },
    "name": "Multiple Choice question 1",
    "multipleChoiceQuestions": [
        {}
    ]
}

What makes up a response?

A response from the Surpass API contains a standard HTTP status code to indicate the success or failure of the request, header parameters, and a response body containing any relevant information.

If sent with authenticated authorisation details, the HTTP status code of a successful call is 200. An unsuccessful request may return a HTTP status code of 404, for example, and an ErrorCode property in the response body that indicates what the issue is.

A response body is always returned in the response to a successful request. In the case of successful GET requests, the requested information is returned in the response body.

For most POST, PUT, DELETE, or PATCH requests, the response body simply details the unique identifier and/or unique reference code of the new or affected entity along with href and serverTimeZone properties. The response body sometimes returns more information in response to certain POST or PUT requests, such as the candidate’s unique keycode and the test session’s PIN code being returned in response to a successful request to the TestSchedule API.

The Surpass API can return data in JSON or XML format. By default, JSON is returned. To return XML data, send an accept header parameter with the value application/xml.

Sample response

Expand the following section for a sample response.

{
    "id": 1,
    "href": "https://{your Surpass instance}.surpass.com/api/v2/Item/1",
    "errors": null
}

Surpass API v2 test console

Each instance of Surpass has an API v2 test console. To access it, add /api/v2 to your Surpass instance’s URL.

The test console lets you test the Surpass API by directly sending a HTTPS request to any of the available endpoints for your instance of Surpass. It automatically generates the endpoint URL, header parameters, and request body, leaving you to complete/amend any parameters and properties as needed.

For more information on the Surpass API v2 test console, read Using the Surpass API v2 test console.