Candidate API
Candidates (also known as “students” or “learners”) are people that take tests using Surpass. Unlike users, candidates do not log in to Surpass. Candidates only access their tests in the test driver—either in a web browser or SecureClient.
Candidates are created and managed in the Candidates screen in the Setup section of Surpass.
The Candidate API resource is used to list, retrieve, create, and update candidates.
This article explains what calls can be made to the Surpass API using the Candidate resource.
Import this API into your Postman Workspace
In This Article
Listing candidates
Send a request to the endpoint to retrieve a list of candidates. Refer to the available parameters to influence the response. No request body is required.
Parameters
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.
|
Name |
Parameter |
Input |
Description |
|---|---|---|---|
|
authorization |
header MANDATORY |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
|
top |
query OPTIONAL |
/api/v2/Candidate?$top={top} |
Defines number of responses to return when paging a response, where {top} is a number between 1 and 40. |
|
skip |
query OPTIONAL |
/api/v2/Candidate?$skip={skip} |
Defines how many responses to skip when paging a response, where {skip} is a number that should not exceed the total number of responses. |
|
filter |
query OPTIONAL |
/api/v2/Candidate?$filter={filter} {operator} {value} |
Filters results, searching either for an exact match or for the data to contain a defined value. For an exact match: {filter} is one of reference, firstName, middleName, lastName, dateOfBirth, gender, email, tel, reasonableAdjustments, retired, centres, subjects, tags; {operator} is eq (equal to); and {value} is the string, integer or Boolean the filter query looks for an exact match for in the request.
NOTE: The formats to filter by centres and subjects are:
NOTE: The format to filter by tags is:
For a contains query: {filter} is contains({attribute}, '{value}'), where {attribute} is one of firstName, middleName, lastName, email, tel; and {value} is the string or integer the filter query looks for the data to contain in the request. |
|
orderBy |
query OPTIONAL |
/api/v2/Candidate?$orderBy={attribute} |
Determines order of results, where {attribute} is one of firstName, middleName, lastName. |
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the information in either JSON or XML format as requested.
{
"count": 615,
"top": 10,
"skip": 0,
"pageCount": 62,
"nextPageLink": "https://{your Surpass instance}.surpass.com:443/api/v2/Candidate?$skip=10",
"prevPageLink": null,
"response": [
{
"id": 1,
"reference": "Candidate1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Candidate/1"
},
{
"id": 2,
"reference": "Candidate2",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Candidate/2"
},
{
"id": 3,
"reference": "Candidate3",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Candidate/3"
},
{
"id": 4,
"reference": "Candidate4",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Candidate/4"
},
{
"id": 5,
"reference": "Candidate5",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Candidate/5"
},
{
"id": 6,
"reference": "Candidate6",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Candidate/6"
},
{
"id": 7,
"reference": "Candidate7",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Candidate/7"
},
{
"id": 8,
"reference": "Candidate8",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Candidate/8"
},
{
"id": 9,
"reference": "Candidate9",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Candidate/9"
},
{
"id": 10,
"reference": "Candidate10",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Candidate/10"
}
],
"errors": null,
"serverTimeZone": "GMT Standard Time"
}Response schema
The response schema contains a description of every property that can be returned for this endpoint.
count integer
Details how many candidates there are in total.
top integer
Details number of candidates returned in the response.
skip integer
Details how many candidates were skipped to display those in the response.
pageCount integer
Details how many pages of candidates there are.
nextPageLink string
The endpoint to call the next page of candidates. If null, the response is the last page of candidates.
prevPageLink string
The endpoint to call the previous page of candidates. If null, the response is the first page of candidates.
response array
Contains the rest of the response.
id integer
The candidate’s unique identifier.
reference string
The candidate’s unique reference code.
href string
The endpoint to call the candidate’s information, such as /api/v2/Candidate/{id} where {id} is the candidate’s unique identifier.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Retrieving candidate information
Send a request to the endpoint to retrieve information for a specific candidate using either their ID or reference. No request body is required.
Parameters
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.
|
Name |
Parameter |
Input |
Description |
|---|---|---|---|
|
authorization |
header MANDATORY |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
|
id |
path OPTIONAL |
/api/v2/Candidate/{id} |
Returns information for the specified candidate, where {id} is the candidate’s unique identifier. |
|
reference |
query OPTIONAL |
/api/v2/Candidate?reference={reference} |
Returns information for the specified candidate, where {reference} is the candidate’s unique reference code. |
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the information in either JSON or XML format as requested.
{
"count": null,
"top": null,
"skip": null,
"pageCount": null,
"nextPageLink": null,
"prevPageLink": null,
"response": [
{
"id": 1,
"reference": "Candidate1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Candidate/1",
"firstName": "Sanjib",
"middleName": "",
"lastName": "Datta",
"dateOfBirth": "1981-07-15T00:00:00",
"gender": "Male",
"email": "sanjib.datta@surpass.com",
"tеl": "",
"uln": "8935818598",
"reasonableAdjustments": true,
"retired": false,
"expiryDate": "2031-04-13T00:00:00",
"isExternal": false,
"centres": [
{
"id": 1,
"reference": "Centre1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Centre/1"
},
{
"id": 2,
"reference": "Centre2",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Centre/2"
}
],
"subjects": [
{
"id": 1,
"reference": "Subject1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1"
},
{
"id": 2,
"reference": "Subject2",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/2"
}
],
"tagGroups": [
{
"id": 1,
"name": "Place of Graduation",
"values": []
},
{
"id": 2,
"name": "Language",
"values": [
{
"id": 1,
"name": "English"
},
{
"id": 7,
"name": "Hindi"
}
]
},
{
"id": 3,
"name": "Location",
"values": [
{
"id": 16,
"name": "London"
}
]
},
{
"id": 4,
"name": "Email Address",
"values": []
}
],
"extendedDemographics": null,
"reasonableAdjustmentType": null,
"reasonableAdjustmentPercentage": 25
}
],
"errors": null,
"serverTimeZone": "GMT Standard Time"
}Response schema
The response schema contains a description of every property that can be returned for this endpoint.
count integer
Details how many candidates there are in total. This is null because the information retrieved is for a specific candidate.
top integer
Details number of candidates returned in the response. This is null because the information retrieved is for a specific candidate.
skip integer
Details how many candidates were skipped to display those in the response. This is null because the information retrieved is for a specific candidate.
pageCount integer
Details how many pages of candidates there are. This is null because the information retrieved is for a specific candidate.
nextPageLink string
The endpoint to call the next page of candidates. This is null because the information retrieved is for a specific candidate.
prevPageLink string
The endpoint to call the previous page of candidates. This is null because the information retrieved is for a specific candidate.
response array
Contains the rest of the response.
id integer
The candidate’s unique identifier.
reference string
The candidate’s unique reference code.
href string
The endpoint to call the candidate’s information, such as /api/v2/Candidate/{id} where {id} is the candidate’s unique identifier.
firstName string
The candidate’s first name.
middleName string
The candidate’s middle name.
lastName string
The candidate’s last name.
dateOfBirth string
The candidate’s date of birth in DD/MM/YYYY format.
gender enumeration
The candidate’s gender, if specified.
email string
The candidate’s email address.
tel string
The candidate’s telephone number.
uln integer
The candidate’s Unique Learner Number (ULN). A ULN consists of 10 numbers, and its visibility is determined by a Site Setting. For more information, read About Site Settings options.
reasonableAdjustments Boolean
Whether the candidate has been granted additional time during tests.
retired Boolean
Whether the candidate has been retired. Retired candidates are not available for test scheduling.
expiryDate string
The candidate’s expiry date, in YYYY/MM/DD format. Defaults to 10 years.
isExternal Boolean
If set to true, the candidate can only be edited via the Surpass API. This prevents synchronisation issues where candidates also exist on databases external to Surpass.
centres array
Contains centres a candidate is associated with. Candidates are eligible to take tests at these centre(s).
centres/id integer
The centre’s unique identifier.
centres/reference string
The centre’s unique reference code.
centres/href string
The endpoint to call the centre’s information, such as /api/v2/Centre/{id} where {id} is the centre’s unique identifier.
subjects array
Contains subjects a candidate is associated with. Candidates are eligible to take tests within the associated subject(s).
subjects/id integer
The subject’s unique identifier.
subjects/reference string
The subject’s unique reference code.
subjects/href string
The endpoint to call the subject’s information, such as /api/v2/Subject/{id} where {id} is the subject’s unique identifier.
tagGroups array
Contains any tags added to the candidate. For more information, read Setting up candidate tags.
tagGroups/id integer
The tag group’s unique identifier.
tagGroups/name string
The name of the tag group.
tagGroups/values array
Contains tag values in the tag group.
tagGroups/values/id integer
The tag value’s unique identifier.
tagGroups/values/name string
The name of the tag value.
extendedDemographics blob
Any additional demographical information associated with a candidate.
reasonableAdjustmentType enumeration
reasonableAdjustmentPercentage integer
The custom reasonable adjustment value. If reasonableAdjustments is true and this property returns 0, the candidate is given the standard amount of extra time given to candidates with reasonable adjustments (defined at test form-level).
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Creating a candidate
Send a request to the endpoint to create a candidate.
Parameters
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.
|
Name |
Parameter |
Input |
Description |
|---|---|---|---|
|
authorization |
header MANDATORY |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
content-type |
header MANDATORY |
application/json or application/xml |
Determines data format of the request, which can be either JSON or XML. |
|
content-length |
header MANDATORY |
{number} |
Determines the number of characters passed in the body of the request, where {number} is a numerical figure. This is usually automatically calculated when the request is sent. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
Sample request
The following request contains the minimum required request body to create a candidate.
{
"centres": [
{
"id": 1
}
],
"firstName": "Sanjib",
"lastName": "Datta",
"dateOfBirth": "1981-07-15"
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
reference string optional
The candidate’s unique reference code. Surpass auto-generates a reference if omitted.
firstName string mandatory
The candidate’s first name.
middleName string optional
The candidate’s middle name.
lastName string mandatory
The candidate’s last name.
dateOfBirth string optional
The candidate’s date of birth in DD/MM/YYYY format.
gender enumeration optional
The candidate’s gender. The available inputs are Male, Female, or Unspecified. Defaults to Unspecified if omitted.
email string optional
The candidate’s email address.
tel string optional
The candidate’s telephone number.
uln integer optional
The candidate’s Unique Learner Number (ULN). A ULN consists of 10 numbers, and its visibility is determined by a Site Setting. For more information, read About Site Settings options.
reasonableAdjustments Boolean optional
Whether the candidate has been granted additional time during tests. Defaults to false if omitted.
reasonableAdjustmentPercentage integer optional
If reasonableAdjustments is true, assigns a custom reasonable adjustments value.
retired Boolean optional
Whether the candidate has been retired. Retired candidates are not available for test scheduling. Defaults to false if omitted.
expiryDate string optional
The candidate’s expiry date, in YYYY/MM/DD format. Defaults to 10 years.
isExternal Boolean optional
If set to true, the candidate can only be edited via the Surpass API. This prevents synchronisation issues where candidates also exist on databases external to Surpass. Defaults to false if omitted.
centres array mandatory
Contains centres a candidate is associated with. Candidates are eligible to take tests at these centre(s).
centres/id integer
The centre’s unique identifier.
centres/reference string
The centre’s unique reference code.
subjects array optional
Contains subjects a candidate is associated with. Candidates are eligible to take tests within the associated subject(s).
subjects/id integer
The subject’s unique identifier.
subjects/reference string
The subject’s unique reference code.
tagGroups array optional
Contains any tags added to the candidate. For more information, read Setting up candidate tags.
tagGroups/id integer
The tag group’s unique identifier.
tagGroups/name string
The name of the tag group.
tagGroups/values array optional
Contains tag values in the tag group.
tagGroups/values/id integer
The tag value’s unique identifier.
tagGroups/values/name string
The name of the tag value.
extendedDemographics blob optional
Any additional demographical information associated with a candidate.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the new candidate’s details.
{
"id": 1,
"reference": "7IarVvvfmkfdBzuHjYhxQFY1AwVe4KW0u9XEVcYGlpUMjl1LuF",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Candidate/1",
"errors": null,
"serverTimeZone": null
}Updating a candidate
Send a request to the endpoint to update a specific candidate.
Parameters
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.
|
Name |
Parameter |
Input |
Description |
|---|---|---|---|
|
authorization |
header MANDATORY |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
content-type |
header MANDATORY |
application/json or application/xml |
Determines data format of the request, which can be either JSON or XML. |
|
content-length |
header MANDATORY |
{number} |
Determines the number of characters passed in the body of the request, where {number} is a numerical figure. This is usually automatically calculated when the request is sent. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
|
postIfNew |
header OPTIONAL |
{Boolean} |
If {Boolean} is true, creates the candidate if they do not exist.
TIP: This is useful if you want to both create (POST) and update (PUT) candidates in the same call.
|
|
id |
path OPTIONAL |
/api/v2/Candidate/{id} |
Updates specified candidate, where {id} is the candidate’s unique identifier. |
|
reference |
query OPTIONAL |
/api/v2/Candidate?reference={reference} |
Updates specified candidate, where {reference} is the candidate’s unique reference code. |
Sample request
At least one property must be updated in the request. The following request contains the minimum required request body to update a candidate. Refer to the request body schema for all properties that can be updated.
{
"reasonableAdjustments": "false"
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
reference string
The candidate’s unique reference code.
firstName string
The candidate’s first name.
middleName string
The candidate’s middle name.
lastName string
The candidate’s last name.
dateOfBirth string
The candidate’s date of birth in DD/MM/YYYY format.
gender enumeration
The candidate’s gender. The available inputs are Male, Female, or Unspecified.
email string
The candidate’s email address.
tel string
The candidate’s telephone number.
uln integer
The candidate’s Unique Learner Number (ULN). A ULN consists of 10 numbers, and its visibility is determined by a Site Setting. For more information, read About Site Settings options.
reasonableAdjustments Boolean
Whether the candidate has been granted additional time during tests.
reasonableAdjustmentPercentage integer
If reasonableAdjustments is true, assigns a custom reasonable adjustments value.
retired Boolean
Whether the candidate has been retired. Retired candidates are not available for test scheduling.
expiryDate string
The candidate’s expiry date, in YYYY/MM/DD format. Defaults to 10 years.
isExternal Boolean
If set to true, the candidate can only be edited via the Surpass API. This prevents synchronisation issues where candidates also exist on databases external to Surpass.
centres array
Contains centres a candidate is associated with. Candidates are eligible to take tests at these centre(s).
centres/id integer
The centre’s unique identifier.
centres/reference string
The centre’s unique reference code.
subjects array
Contains subjects a candidate is associated with. Candidates are eligible to take tests within the associated subject(s).
subjects/id integer
The subject’s unique identifier.
subjects/reference string
The subject’s unique reference code.
tagGroups array
Contains any tags added to the candidate. For more information, read Setting up candidate tags.
tagGroups/id integer
The tag group’s unique identifier.
tagGroups/name string
The name of the tag group.
tagGroups/values array
Contains tag values in the tag group.
tagGroups/values/id integer
The tag value’s unique identifier.
tagGroups/values/name string
The name of the tag value.
extendedDemographics blob
Any additional demographical information associated with a candidate.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the updated candidate’s details.
{
"id": 1,
"reference": "7IarVvvfmkfdBzuHjYhxQFY1AwVe4KW0u9XEVcYGlpUMjl1LuF",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Candidate/1",
"errors": null,
"serverTimeZone": null
}Error Codes
Refer to the following table for information on error codes that may be encountered when using this resource.
|
Name |
Code |
Description |
|---|---|---|
|
InternalServer |
1 |
Internal server error. |
|
Unauthorized |
3 |
The request has been sent by an unauthorised user. |
|
IncorrectFieldFormat |
4 |
A field in the request has not been completed in the correct format. |
|
InaccessibleOperation |
5 |
The request has been sent by a user with invalid permissions. |
|
InaccessibleData |
6 |
The request has been sent by a user with invalid permissions. |
|
MissingBody |
7 |
There is an issue with the request body. |
|
InvalidReferences |
8 |
The unique reference code used in the request is invalid (specific to candidates). |
|
InvalidReference |
11 |
The unique reference code used in the request is invalid. |
|
InaccessibleCandidate |
13 |
The candidate defined in the request cannot be accessed. |
|
InvalidInputParameters |
15 |
There is an issue with the path or query parameters. |
|
InvalidId |
16 |
The ID number used in the request is invalid. |
|
InvalidODataOperation |
19 |
There is an issue with the query parameters. |
|
BadRequest |
20 |
There is an issue with the /api/v2/Candidate?$skip={skip} query parameter, where {skip} is a number that should not exceed the total number of responses. |
|
FailedToCreateCandidate |
21 |
There is an issue with creating a candidate. |
|
FailedToUpdateCandidate |
22 |
There is an issue with updating a candidate. |
|
CandidateDoesNotExist |
23 |
The candidate specified in the request does not exist. |
Further reading
Read the following articles to learn more about similar APIs, how to get started with the Surpass API v2, and how to get the best out of this reference documentation: