Using the Surpass API

The purpose of this article is provide you with all the information you need to successfully build a request and get the most out of the Surpass API.


Security, Authentication and Authorization

Authorization is required to use any of the services available in the Surpass API, the Surpass user requesting this information must have sufficient permissions to perform the action they are requesting. For example, a user who does not have the relevant permissions to schedule an exam will not be able to successfully call the POST method for the Test Schedule resource. We recommend creating a dedicated integration user account within the system that can be used when calling the Surpass API.

Authentication is required to use any of the services available in the Surpass API. The user calling the methods will be able to authenticate their user account by providing their Surpass user credentials within the header of their request using Basic Authentication; if this is not provided the user will be prompted to enter their Surpass username and password.

The Request Header name that needs to be specified is “Authorization”. The request header value is constructed as follows:

  • Username and password are combined into the string "username:password".
  • The resulting string literal is then encoded using Base64.
  • The authorization method and a space (i.e. "Basic ") are then put before the encoded string.

Example request header value: “Basic QlRMRGVtbzpQYXNzd29yZA==”.


Resources and HTTP Methods

Within the Surpass API we have defined separate resources that relate to different entities in the Surpass solution. Each resource and its available methods have been defined in the API documentation and can be accessed from the introduction page or developer portal in the Surpass knowledge base. HTTPS methods allow you to communicate and interact with these resources to integrate with the Surpass platform. Below we have listed the methods available:

GET search, filter and order resources using the GET method. This command can be useful to synchronise and integrate an external system with Surpass.

PUT using PUT will allow you to update existing data stored in Surpass, automating and streamlining your process so only one external master system would ever have to be updated.

POST using POST creates Surpass related resources allowing bulk migration of data into the system meaning managing information in Surpass is efficient and simple.  It also offers the functionality to automate and streamline your process so only one external master system would ever have to be updated.

DELETE remove data from Surpass using this command. This method allows a way of synchronising systems and automating housekeeping in the system whilst at the same time making the response to GET requests lighter.

 

GET Requests

When making a GET request, the API will expect either one or more parameters included as part of the querystring OR a separate request just specifying the resource name which will return all entries for that entity (paged). The parameters used in the Surpass API are comparative to the open source protocol “OData” which is well documented online.

Below we have provided a step by step guide on how to get the most out of a GET request when using the Surpass API:

Step 1 – Request all resources

In the first step we are going to see how you can return all resources for a particular entity within Surpass. Simply send a HTTPS request to the API URL and specify the entity you are requesting, for example:

https://...surpass.com/API/v2/Candidate/

This would provide a list of all of the candidates contained within your Surpass environment. It would also give you the id, reference and href to call each of the resources individually. 

Step 2 – Filter resources

The $filter parameter provides a method of searching and filtering for particular resources using Surpass fields. The API allows you to filter resources by stating specific fields as part of the querystring.

Below we have provided an example GET request including the $filter parameter:

https://...surpass.com/API/v2/Candidate?$filter=reference eq 'BTL123'

In the above response “$filter” is the parameter (all parameters are immediately followed by “=”), “reference” is the Surpass field, “eq” is the $filter operator and “BTL123” is what you are searching for.

It is also possible to filter on more than one Surpass attribute in the request. To do this all you have to do is add the command “and”. Below we have provided an example of this:

https://...surpass.com/API/v2/Candidate?$filter=reference eq 'BTL123' and lastName eq 'Flockton'

For some methods it is also possible to filter on resources that are contained within another resource. An example of this would be results, this contains subjects, centres, tests and test forms. Here you would need to specify ID or reference preceded with the resource name and a forward slash, we have provided an example below:

https://...surpass.com/api/v2/Result?$filter=subject/reference eq 'subject ref 1' and centre/reference eq 'centre ref 1’

As well as the example provided in some resources we offer filtering on multiple resources within a resource. A good example of this is the candidate resource where they can be associated to more than one centre and subject. As an example of the querystring has been provided below:

https://...surpass.com/api/v2/Candidate?$filter=subject/any(s: s/reference eq 'subject ref1' or s/reference eq 'subject ref2')

 

$filter operators supported have been provided below:

Operator

Description

Example request

eq

Exact match, the value you are searching for must match the value set in the Surpass database.

API/v2/Candidate?$filter=reference eq 'BTL123'

le

Less than or equal to, the value set in the Surpass database must be less than or equal to what is stated in the request.

API/v2/result?$filter=warehousedDate le '2015-06-11T00:00:00'

ge

Greater than or equal to, the value set in the Surpass database must be less than or equal to what is stated in the request.

API/v2/result?$filter=warehousedDate ge '2015-06-11T00:00:00'

contains({surpass field},{value})

returns all resources that contain the value set within the brackets of the   contains operator. Similar to LIKE in SQL. 

API/v2/Candidate?$filter=contains(reference, 'BTL123')

NOTE - Not all Surpass fields are queryable and not all operators can be used on queryable fields; the fields and operators that are available to query have been defined for each resource in their specific knowledge base article.

 

Step 3 - Order resources

The $orderby parameter determines the order that results are returned in; the Surpass fields that are available to order have been defined in the resources section of this documentation.

Below we have provided an example GET request including the $orderby parameter:

https://...surpass.com/API/v2/Candidate/?$orderby=lastName

 

Step 4 - Paging responses

Paging is managed by stating the $top and $skip parameters as part of the querystring. $top defines the size of the page returned and $skip defines how many responses to skip. These parameters allow you to define your own page size when calling the method. The response will also return a total count, page count and next/previous page link.

https://...surpass.com/API/v2/Candidate/?$top=10&$skip=10

NOTE – The ampersand character allows additional parameters ($filter, $top, $skip, $orderby) to be defined as part of the querystring. This can be seen in the above example.

 

Step 5 – Request Individual resources

Using the above steps you will be able to find all of the relevant Surpass resources you were looking for, this will have only returned the ID, reference and href. This information on its own doesn’t give you the whole picture of the resource but what the Surpass API allows you to do is request each one individually which will return all of the detail about the resource. This is done by adding the ID or the Reference to the HTTPS request for example:

 https://...surpass.com/API/v2/Candidate/1

The above request would provide detailed information about the candidate with ID 1.

https://...surpass.com/API/v2/Candidate?reference=JLcand1

The above request would provide detailed information about the candidate with the reference JLcand1.

 

GET Responses

All resources inherit from BaseResource and so all resources will return, as a minimum, a URI that is a link to the full resource, an ID that is the unique object ID for that resource, and the unique reference.

 

Get Operations

Responses to GET requests will be returned in the following format:

Attribute Name

Type

Notes

count

Int

Total number of items available for this request.

top

Int

The page size that was passed in the request.

skip

Int

The number of items to skip. Used to determine which page is viewed.

pageCount

Int

The number of pages returned.

nextPageLink

String

URL to call the next page.

prevPageLink

String

URL to call the previous page.

response

Object

List of the requested resources.

errors

List of Error

Errors encountered by this request. (Should be accompanied with a 40x code in the header).

ServerTimeZone

String

ServerTimeZone will provide the user with the relevant time zone the server/hub is located. This is so the user knows what date/time to enter for requests.  The response will return Microsoft time zone index values that .NET returns as standard.

 

 

Within this documentation the resources defined WILL ONLY describe what is returned within the RESPONSE object. Below is an example of a full JSON GET response:

{

  "count": 3442,

  "top": 10,

  "skip": 0,

  "pageCount": 345,

  "nextPageLink": "https://...surpass.com/api/v2/Candidate/?$skip=20",

  "prevPageLink": "https://...surpass.com/api/v2/Candidate/",

  "response": [

    {

      "id": 17,

      "reference": "Candidate1",

      "href": "https://...surpass.com/api/v2/Candidate/17"

    },….

  ],

  "errors": null,

  "serverTimeZone": "GMT Standard Time"

 

PUT Requests and Responses

To send PUT Requests to the Surpass API you need to include the ID or Reference of the resource you want to update in the URL; this information can be gathered using the GET request. Both XML and JSON format are supported. Header requests will also be required including the content-length, content-type and authorization.

It is possible to update and create candidate, centre, subject and user entries in Surpass using a PUT request to cut down on the amount of communication required with the Surpass API. To achieve this, you must add a line to the header - postIfNew:true. If this is added, the request will check if the reference provided exists and if it does not, the entry will be created. If the reference exists, the candidate will be updated.

Successful PUT requests where a candidate, centre, subject or user is created will return a HTTP response code of 201.

Successful PUT requests where a candidate, centre, subject or user is updated will return a HTTP response code of 200.


An example PUT request has been provided below:

https://...surpass.com/API/v2/Candidate/1

Method: PUT

Header:

Content-Length: 528

Content-Type: application/json

Authorization: Basic Q1RMRGVtbzpQYXNzd29yZa==

Accept: application/json

Body:

    {

      "firstName": "Scott",

      "lastName": "Flockton",

      "dateOfBirth": "2000-04-20T00:00:00",

      "email": "scott.flock@btl.com",

      "tеl": "1234",

      "reasonableAdjustments": false,

      "retired": false,

      "centres": [

        {

          "id": 31,

          "reference": "bkQ0Ti28UWL8",

          "href": null

        }….

      ],

      "subjects": [

        {

          "id": 685,

          "reference": "w91eFWyZ9wob",

          "href": null

        }….

      ],

      "reference": "Candidate1"

    }

The response of the request will provide the user with an object containing, as a minimum, a URI that is a link to the full resource, an ID that is the unique object ID for that resource and the unique reference.

 

POST Requests and responses

POST Requests should reference the resource but not specify any further information. The resource being created should be included in the body of the request and can be sent in either JSON or XML format. Header requests will also be required including the content-length, content-type and Authorization. An example POST request has been provided below:

https://...surpass.com/API/v2/Candidate/

Method: POST

Header:

Content-Length: 528
Content-Type: application/json
Authorization: Basic Q1RMRGVtbzpQYXNzd29yZa==
Accept: application/json

Body:

    {

      "firstName": "Scott",

      "lastName": "Flockton",

      "dateOfBirth": "2000-04-20T00:00:00",

      "email": "scott.flock@btl.com",

      "tеl": "1234",

      "reasonableAdjustments": false,

      "retired": false,

      "centres": [

        {

          "id": 31,

          "reference": "bkQ0Ti28UWL8",

          "href": null

        }….

      ],

      "subjects": [

        {

          "id": 685,

          "reference": "w91eFWyZ9wob",

          "href": null

        }….

      ],

      "reference": "Candidate1"

    }

 

The response of the request will provide the user with an object containing, as a minimum, a URI that is a link to the full resource, an ID that is the unique object ID for that resource and the unique reference. Further information about the response will be unique to the resource.

DELETE Requests

To run DELETE Requests users should provide the ID or Reference of the resource they want to delete. DELETE commands will only be used if the Surpass user interface references the delete function and will perform the exact same logic as the UI. Candidates are retired (PUT), Centres are deleted (DELETE).

 

Response Format

The Surpass API allows users to define if the response is returned in XML or JSON format. To specify the format of the response the user calling the method must include this in the header of the request, the request header required for this has been provided below:

  • Accept: application/json
  • Accept: application/xml

NOTE - The Surpass API will default to JSON format

Previous Versions

Previous versions of the Surpass API are also available to integrate with and can be accessed by browsing to the relative link:

https://...surpass.com/API/v1

https://...surpass.com/API/v2

We strongly recommend that you do not combine different versions of the API as the data may be requested and returned in a different way which can make it difficult to implement and support. 

Testing the API

To test the Surpass API you can directly send a HTTPS request to the relevant method and resource or alternatively you can use the “API help page” feature which is available at the below links: 

https://...surpass.com/API/

https://...surpass.com/API/v1

https://...surpass.com/API/v2

The “API help page” will automatically generate the URL, header and body of the request, all you will be required to do is fill in the parameters and send the request.

 

Feedback and Knowledge Base