Calling the Surpass API

Note: Version 2 of the Surpass API is now available. For any customers not already using API v1, please refer to the API v2 Developer Portal.


The purpose of this page is to provide you with all the details required to call the Surpass API. 

Authentication

Authentication is required to use any of the services available in the Surpass API. The user calling the web 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==”

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 web 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
* The Surpass API will default to JSON format

Testing the API

To test the Surpass API you can directly send a http request to the relevant web method or alternatively you can use the “Test API” feature which is available at the Surpass API’s base URL: 

https://[YourSurpassEnvironment].surpass.com/API

The “Test API” feature 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.

GET Requests

Most GET Requests available within the Surpass API require their parameters to be passed as part of the URL. Below we have provided an example of the URL required to call the GetResult web method, within this call the parameter “keycode” has been passed as part of the URL.

https://[YourSurpassEnvironment].surpass.com/api/v1/TestResults/GetResult?keycode=8ULVLZD12

PUT Requests

PUT Requests should provide their parameters as a query string, this 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 PUT request has been provided below:

https://[YourSurpassEnvironment].surpass.com/api/v1/CandidateRegistration/PutCandidate?

Header:

Content-Length: 432

Content-Type: application/json

Authorization: Basic Q1RMRGVtbzpQYXNzd29yZa==

Body:

{

  "DateOfBirth": "1985-12-17T00:00:00",

  "SpecialRequirements": true,

  "SubjectAssociation": [

    {

      "Reference": "sample string 1"

    },

    {

      "Reference": "sample string 1"

    }

  ],

  "CentreAssociation": [

    {

      "Reference": "sample string 1"

    },

    {

      "Reference": "sample string 1"

    }

  ],

  "Forename": "sample string 3",

  "Surname": "sample string 4",

  "Reference": "sample string 5"

}


Next Article


 




Feedback and Knowledge Base