Calling the PutTestSchedule Method in the Surpass Web 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 PutTestSchedule web method in the Surpass API allows you to schedule a test based on the parameters that are passed into the call. Candidates must have associations to the centres and exams for this call to successfully run.

PutTestSchedule


PUT api/v1/TestSchedule/PutTestSchedule?

Input Parameters


The input parameters that are required for the PutTestSchedule web method are as follows:
Input ParameterTypeDescription
TestReference Type: String, max length: 50, mandatory The test reference of the exam you would like to schedule. This is specified in the Test Creation section of Surpass Editions.
CentreReference Type: String, max length: 30, mandatory The reference of the centre you would like to schedule the exam at. This is specified in the Setup section of Surpass Editions
CandidateReference Type: String, max length: 50, mandatory The reference of the candidate you would like to schedule an exam for. This is specified in the Setup section of Surpass Editions.
StartDateTime Type: DateTime, less or equal to EndDateTime, mandatory The web method will only return results on or after this date/time.*

EndDateTime Type: DateTime, greater or equal to StartDateTime, mandatory The web method will only return results before this date/time.*

*The Start/End Dates and Start/End Times are independent of each other i.e. The Start/End Dates mark the available test window and the Start/End Times are the times in which the test can be delivered on all available dates within that window.


e.g. Where StartDateTime is 2013-12-18T09:00:00 and EndDateTime is 2013-12-21T17:00:00, the test will be available for delivery on the following dates/times:

18/12/2013 09:00 - 17:00
19/12/2013 09:00 - 17:00
20/12/2013 09:00 - 17:00
21/12/2013 09:00 - 17:00

Request

The PutTestSchedule web method requires the parameters to be submitted as part of the body of the request. This can be submitted in JSON or XML format, the content-type used will need to be submitted as part of the header of the request. This call should be sent as a PUT REST request to the following address: 

https://[YourSurpassEnvironment]/api/v1/TestSchedule/PutTestSchedule?

  • When scheduling an exam ensure that the Test Reference and Subject Reference are unique, this can be changed in the TestCreation section of SurpassEditions.
  • The DateTime value is any able to parse by C#. This also must be kept inside double quotes. An example datetime is as follows: "2013-12-18T07:23:26.550375+00:00"
An example of the request using both formats can be found by selecting the below links:  

JSON Request
XML Request

Required Permissions


To successfully call PutTestSchedule the user specified in the header of the request must have the 'Schedule' permission in Surpass and be associated to the relevant centre and subject that is contained within the request.

The candidate specified in the request must also be associated to the centre and subject for the test schedule to be successful.

Return


Depending on how the request was submitted the response will be in either JSON or XML format, the response will provide the candidates unique keycode and pin to the new exam that has been scheduled.

If the call was unsuccessful then you will receive an error message, all error messages available in the Surpass API can be found here.

An example of the response in both formats can be found using the below links:  

JSON response 
XML Response



Next Article 

Feedback and Knowledge Base