About the Surpass API v2

The Surpass API v2 is a REST API: it is client-server based, stateless, layered, uses HTTP requests to send and retrieve data, has a uniform interface (read Using the Surpass API v2 test console), and data accessed can be cached.

Our APIs let you automate how you interact with Surpass. For example, the methods we have available allow an external system to synchronise its candidate, centre, and test session records, or extract important result and reporting data.

Surpass is a .NET MVC application; the Surpass API does not absolutely reflect the Surpass UI, but the majority of the Surpass Platform’s functionality and settings found in the Surpass UI are represented in the API.

Integrating with the Surpass API v2

Integrating with the Surpass API offers many benefits, including the ability to:

• Send and retrieve data whenever you want, meaning you are not restricted to specific time periods.
• Automate your internal processes so that only one master system has to be updated, removing administrative overhead.
• Bulk migrate candidate, centre, and test scheduling records to avoid manual input into the Surpass Platform.
• Provide certification and statistical analysis externally by extracting all results and reporting information.
• Diagnose any issues using common HTTP errors (401…), simplifying integrations.
• Not be tied to a particular server, enabling a more scalable integration from which you can easily recover from failed requests.

Surpass Platform entities

Before using the Surpass API, it is beneficial to have an understanding of the way Surpass works and how the entities all relate to one another. The core Surpass entities are centres, candidates, subjects, and users.

Pre-delivery

The following data model demonstrates the different entities required for the set up of tests prior to delivery and their relationship to one another in the Surpass Platform:

Delivery and post-delivery

The following data model demonstrates the different entities required for test delivery and their relationship to one another in the Surpass Platform:

Test Administration workflow

Test sessions move through different states during the Test Administration workflow, starting with being scheduled and ending with being archived in the Audit warehouse. For information on how you can interact with test sessions at different states using the Surpass API, read the Test Administration API reference documentation.

The following state workflow diagram details each state a test can pass through on its journey through the system:

Each test session state is identified by a state number and state name. The following table contains a description of every test session state and in which screen of Surpass it is related to: