Using the Surpass API v2 reference documentation

The Surpass API v2 Reference documentation details each endpoint, parameter, property, and error code, including sample requests and responses, for all of the APIs in the Surpass API v2.

This article contains some instruction on how best to read the Surpass API v2 reference documentation, including information on how to make use of the Surpass Platform Postman Workspace.

In this section

Postman

Postman is an API platform used for building, using, and testing APIs. You can therefore use Postman as an HTTP client to send requests to Surpass APIs.

Each Surpass API resource has its own Postman collection in our Surpass Platform Postman Workspace. This allows you to import a copy of or fork a resource and all its endpoints, wherever you see this button in our reference documentation:

Select the Run in Postman button and then choose to either import a copy of the collection, or Fork Collection.

Forking a collection lets you pull any updates made by us to the parent collection through to your collection at any time. For more information on version control in Postman, read Using version control on Postman’s documentation.

Once you have a Surpass Platform API collection in your Postman Workspace, you can view all the available HTTP requests for that resource.

To use these APIs, you will need to amend your authorisation details for the collection (each endpoint inherits these from the collection). Ensure you use variables to protect your data. To learn more about variables, read Using variables on Postman’s documentation.

Replace {your Surpass instance}.com in the endpoint field with the URL of your Surpass instance.

If a request body is required, the Body section of the Postman request contains the minimum required request body needed to achieve a successful request, with a description in the place of the value for each property.

Press Send to send the request.

Parameters

The parameters tables in the reference documentation detail which header, path, or query parameters are available for each endpoint.

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.

The Parameter column indicates the type of parameter and whether it is mandatory or optional.

Typically, only authorization is required for GET requests, along with content-type and content-length for POST and PUT requests. The header parameters listed in the reference documentation are not exhaustive; other standard HTTP header parameters may be passed in a request, for example: connection (keep-alive).

Path parameters are usually used to identify the unique identifier (id) of a particular object in Surpass targeted in the request, or a candidate’s unique keycode used to enter their test (keycode).

Query parameters allow you to page, filter, or order listed results. The properties for which you can perform these actions are detailed in the Description column of the parameters tables.

Instead of a unique identifier, the unique reference code of objects in Surpass (reference) can sometimes be used as a query parameter (?reference={reference}) to identify the target of a request.

Sample Request/Response Bodies

The sample request bodies provided in the reference documentation contain the minimum required request body needed to achieve a successful request. Any more properties that can be included in the request are detailed in the request schema.

Sample response bodies contain a sample response to a successful request.

You can copy the request/response bodies from the embedded code blocks using the clipboard icon.

The icon changes to a checked clipboard and the text ‘Copied!’ appears to confirm you have copied the code to your clipboard.

Request/Response Schemas

The reference documentation contains detailed schema for every property that can be sent to or returned from the Surpass APIs.

The property’s data type is listed next to each property’s name. The available data types are: array, Boolean, enumeration, integer, object, and string.

For POST requests, whether the property is mandatory or optional is indicated next to the property’s name and data type.

Error Codes

Error codes for the API are detailed in a table at the end of each article. A lot of API error codes listed are standard and may be returned for several or all APIs. If you encounter an error code not included in these tables, contact support@surpass.com.