| Prepared by | Vincent Millette |
|---|---|
| Version Number: | 2.00 |
| Version Date: | 2023-07-31 |
| Version Notes: | Added character limits to all input fields |
Before you (the Integrator) can communicate with our API you will need API credentials. We set these up individually for each client. Just drop us an email at info@testpartnership.com and ask us to set you up with API access credentials.
| Access Username: | To be set up by Test Partnership for each new client |
| Access Password: | To be set up by Test Partnership for each new client |
| API Base URI: | https://www.tptests.com |
| Auto Login Base URI: | https://www.tptests.com/auto-login |
The basic flow between the Integrator and the Test Partnership Platform is as follows:
In addition to the above flow the following will be allowed any time after No.2 above:
The Test Partnership Platform uses a series of RESTful API Methods that are invoked using either HTTP GET or POST methods. All data is returned in JSON format.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail.
All API calls must be authenticated as being genuine on our servers and so therefore must always contain the following parameter:
| Parameter Name | Parameter Value |
|---|---|
| AccessToken | The Access token should be a Guid using the details provided in the Integrator Access Details section of this document. Access to the API will then be granted to programs that pass the correct Access Token for a period of 5 minutes. |
The Test Partnership Platform database contains Candidate records all of which have one or more associated Assessment Records. An instance of a Candidate completing Project is called an Assessment. Candidates are permitted to complete multiple Assessments either in the same time frame or in a linear fashion.
The API methods currently available are defined as:
/api/client/token –GET METHOD
This API call is the start point for any client trying to integrate the Test Partnership platform. The API call will return an access token. Access to the API will then be granted to programs that pass the correct Access token for a period of 5 minutes.
The following parameters must be passed to Test Partnership using the HTTP GET method:
| Parameter Name | Parameter Value |
|---|---|
| Username | The username of the Client to access Test Partnership. 30 characters maximum. |
| Password | The password of the Client to access Test Partnership. 50 characters maximum. |
Sample Request Schema
https://www.tptests.com/api/client/token?username=sample&password=sampleExample Error Response
{“Errors": [Example Successful Response
{Where the values are defined as follows:
| Parameter Name | Parameter Value |
|---|---|
| <Errors> | This field will contain error messages in the following format: {“Key”:””, “Message” : “”} where Key is the parameter name and Message is corresponding error message. |
| <AccessToken> | The unique guid to access the rest of the APIs. 36 characters. |
/api/candidate – POST METHOD
This API call adds a new Candidate and Assessment record on to the Test Partnership Platform for the specified Project. When this method is called Test Partnership checks to see if the Candidate record already exists (based on the supplied candidate user name). If the Candidate record exists, a validation error is returned. If the Candidate does not exist then a new Candidate record is created along with a new Assessment record. All Assessment records are associated with a Candidate record.
The candidate method also supports additional parameters that shorten the candidate's journey and removes the Demographic Data, Instructions, and Sub Instruction pages from the flow. Parameter HideInstructions is mandatory for this reduced flow, but not required for a normal journey.
The following parameters must be passed to Test Partnership using the HTTP POST method:
| Parameter Name | Parameter Value |
|---|---|
| AccessToken | As detailed above. |
| ProjectAccessKey | A string value for the access key of the Project you wish the Assessment Record to be added for. This can be edited/viewed for each Project in the Client's portal. 20 characters maximum. |
| Username | A username for the Candidate to access Test Partnership. 60 characters maximum. Optional - we will generate a random username for you if you leave this field empty (or don't include the field). If you wish to keep track of the candidate via their username without passing us personally-identifiable information, we suggest using this field as an anonymous identifier which can then be used by you to identify who scored what. For example only you would know that username ABC3720107 equates to person Joe Bloggs, and Test Partnership would have no record of who ABC3720107 actually is. |
| Password | The password for the Candidate to access Test Partnership. 9 characters minimum, 40 characters maximum. Optional - we will generate a random password for you if you leave this field empty (or don't include the field). |
| FirstName | The Candidate’s First Name. 30 characters maximum. This is mandatory; however, if you want to avoid passing us personally-identifiable data, feel free to send us something like 'AnonymousFirstName'. If you download this candidate's Test Partnership test report(s), this name will appear on the cover. |
| LastName | The Candidate’s Surname. 30 characters maximum. This is mandatory; however, if you want to avoid passing us personally-identifiable data, feel free to send us something like 'AnonymousLastName'. If you download this candidate's Test Partnership test report(s), this name will appear on the cover. |
| The email address to which Test Partnership mail servers will send the candidate's login details (Username and Password). 60 characters maximum. This is usually the candidate's email address but it can be wherever you wish the details to be sent to. Note that if you use the magic string 'anonymous@testpartnership.com', our email system will not send the email. This is also useful to avoid sending Test Partnership personally-identifiable information. If your side is generating the Username and Password there is no need for Test Partnership to also send these credentials to a valid email address. | |
| RedirectURL | The URL that Test Partnership will redirect the Candidate back to following the completion of their Assessment. 1000 characters maximum. If supplied this field should begin http:// or https://, if not the Candidate will be directed back to the home page of the Test Partnership Platform (https://www.tptests.com) A redirect URL may contain applicant data which could be used to signal an applicant's completion of an assessment and readiness for fetching their score. |
| HasExtraTime | Not mandatory. A Boolean value that sets the time allowed for the candidate's assessments to 125% of the the standard time (i.e. extra 25% time). |
| FactorPercentage | Not mandatory. An integer value that sets in percentage terms how much extra time the candidate gets for their assessments. Minimum value is 1 (i.e. 1% extra time) and maximum value is 100 (i.e. double the standard time). |
| HideInstructions | A Boolean value to enable a shortened user journey (not mandatory). If set to true then the candidate skips our test instructions page, our privacy policy page, and our assessment overview page. For projects with multiple sections, this flag also causes candidates to navigate from a section they've just completed directly to their next incomplete section, removing the need for them to use the assessment overview page to navigate manually. |
| DemographicData | A dynamic JSON object (not mandatory). Attributes are defined by the Client in their client portal (tptests.com/client). Object keys are equal to question text. Contact Test Partnership to enable this in your Client portal. This feature is useful if you want to send us your own custom demographic data to be associated with the candidate, for example you might want to pass us year of birth, university, intake stream, length of service....anything. This would be particularly useful if Test Partnership is helping you with predictive analytics. |
Sample Request Schema
https://www.tptests.com/api/candidate/?&AccessToken=sample&ProjectAccessKey=sample&Username=sample&Password=sample&FirstName=sample&LastName=sample&Email=sample&HideInstructions=falseExample Request
{Example Error Response
{“Errors": [Example Successful Response
{“Errors"[],Where the values are defined as follows:
| Parameter Name | Parameter Value |
|---|---|
| <Errors> | This field will contain error messages in the following format: {“Key”:””, “Message” : “”} where Key is the parameter name and Message is corresponding error message. |
| <Assessment><Id> | The unique Id of the Assessment record that was created. Note: This value should be stored in the Integrator’s system as it is needed for future API calls. |
| <Assessment><Tests><Id> | The unique Test Id of the one of the Tests within the Assessment. If a Project has been setup by the Client to contain multiple Tests, then this is where the Tests are identified. For simplicity, most Integrators choose to have just one Test in their Project. Note: This value should be stored in the Integrator’s system as it is needed for future API calls. |
| <Assessment><Tests><TestName> | Test Name – the Name of one of the Tests within the Assessment. |
| <Assessment><Tests><TestMinutes> | TestMinutes - Time in minutes for the test within the Assessment. |
| <Username> | The candidate's username, either a duplicate of what was passed in, or what our system generated if null was passed in. |
/api/candidate/IsCandidate – GET METHOD
This API call returns whether a Username has been registered. The following parameters must be passed to Test Partnership using the HTTP GET method:
| Parameter Name | Parameter Value |
|---|---|
| Username | The Username of the Candidate to access Test Partnership. 60 characters maximum. |
| AccessToken | As detailed above. |
Sample Request Schemas
https://www.tptests.com/api/candidate/iscandidate/?&accessToken=sample&username=sampleExample Error Response
{Example Successful Response
{"IsCandidate":"True"}/api/candidate/GetAssessmentsForCandidate – GET METHOD
This API call returns the Assessment a Candidate has been assigned to. Historically, it was possible to assign multiple assessments to a candidate, but nowadays, all candidates have exactly one assessment assigned to them. (This assessment may have multiple sections in it.) The following parameters must be passed to Test Partnership using the HTTP GET method:
| Parameter Name | Parameter Value |
|---|---|
| Username | The username of the Candidate. 60 characters maximum. |
| AccessToken | As detailed above. |
Sample Request Schemas
https://www.tptests.com/api/candidate/getassessmentsforcandidate/?&AccessToken=sample&Username=sampleExample Error Response
{Example Successful Response
{/api/assessment/verification/<Id> – GET METHOD
This method registers the candidate for a ‘verification’ version for the corresponding assessment section id and returns an assessment token. The ‘verification’ version of a test typically has fewer questions (and therefore a shorter time duration) than the original test.
| Parameter Name | Parameter Value |
|---|---|
| AccessToken | As detailed above. |
| AssessmentSectiondId | This is the assessment section id for one of the assessments within the assessment. The assessment section id can be obtained via the GetAssessmentsForCandidate method. |
Sample Request Schemas
https://www.tptests.com/api/assessment/verification/?&AccessToken=sample&AssessmentSectiondId=sampleExample Error Response
{Example Successful Response
{/api/assessment/scores/<Id> – GET METHOD
This API call returns the current scores for the Assessment specified by making a GET request to the above URL where <Id> is the unique Id of the Assessment record that was returned in the JSON data from the above call to create the Candidate / Assessment record.
The following parameters must be passed to Test Partnership using the HTTP GET method:
| Parameter Name | Parameter Value |
|---|---|
| AccessToken | As detailed above. |
Sample Request Schemas
https://www.tptests.com/api/assessment/scores/?&AccessToken=sample&Id=sampleExample Error Response
{"Errors":[Example Successful Response
{"Errors": [],Where the values are defined as follows:
| Parameter Name | Parameter Value |
|---|---|
| <Errors> | This field will contain error messages in the following format: {“Key”:””, “Message” : “”} where Key is the parameter name and Message is corresponding error message. |
| <Status><Id> | Overall Status for the Assessment, possible values are: In Progress, Submitted and Downloaded. |
| <SubmissionDate> | A string giving the date and time in UTC in ISO 8601 format (yyyy-MM-ddThh:mm:ss) that the Assessment was completed / Submitted. This field is only populated if Status contains Submitted or Downloaded. |
| <Score> | Overall Score for the Assessment – Overall Score is an integer between 1 and 10. |
| <Tests><Id> | The unique Test Id of the one of the Tests within the Assessment. Note: This value should be stored in the Integrator’s system as it is needed for future API calls. |
| <Tests><TestName> | Test Name – the Name of one of the Tests within the Assessment. |
| <Tests><TestStatus> | Test Status – the Status of this test within the Assessment, possible values are: Awaiting Resume, Completed, Not Started, and In Progress. |
| <Tests><TestTime> | Test Time – an integer value indicating the time in minutes it has taken the Candidate to complete the test. This value will be null if the Candidate has not Completed this Test. |
| <Tests><ZScore> | ZScore – the score the Candidate has achieved for this Test within the specified Assessment. This value is either a positive or negative number. |
| <Tests><PercentileScore> | PercentileScore – the score the Candidate has achieved for this Test within the specified Assessment. This value is an integer between 1 and 100. |
| <Tests><StenScore> | StenScore – the score the Candidate has achieved for this Test within the specified Assessment. This value is an integer between 1 and 10. |
| <Tests><Scales> | Scales: This will contain a structure indicating the Scores of each of the Personality Questionnaire Scales. Non PQ tests will not have a value against it. The Scales structure will have: Scale – name of the PQ Scale. StenScore – PQ Scale Score. ZScore – the score the Candidate has achieved for this Scale, for this Test, within the specified Assessment. This value is either a positive or negative number. |
| <Tests><Groups> | Groups: This will contain a structure indicating the Scores of each of the Personality Questionnaire Groups. Each Group represents the combined score of a subset of the Scales. Non PQ tests will not have a value against it. The Groups structure will have: Group – name of the PQ Group. StenScore – PQ Group Score. RoundedStenScore – PQ Group Score, rounded to the nearest integer. ReportType – the name of the report that this group is used on. Different reports are used to represent the same data in different ways. Integrators must not combine the scores for groups from different reports when generating their own custom reports. Test Partnership recommends using groups from the Full Report only. Available reports include:
|
/api/assessment/reports/<Id> – GET METHOD
This API call returns the current reports for the Assessment specified by making a GET request to the above URL where <Id> is the unique Id of the Assessment record that was returned in the JSON data from the above call to create the Candidate / Assessment record.
The following parameters must be passed to Test Partnership using the HTTP GET method:
| Parameter Name | Parameter Value |
|---|---|
| AccessToken | As detailed above. |
Sample Request Schemas
https://www.tptests.com/api/assessment/reports/?&AccessToken=sample&Id=sampleThe following data will be returned:
A file content object will be returned which contains a zip file. The ZIP file will in turn contain all the PDF reports that have been generated for that Candidate’s Assessment.
Example Error Response
{“Errors": [/api/assessment/status/<Id> – GET METHOD
This API call returns the current status (not started, in progress, submitted, downloaded) for the Assessment specified by making a GET request to the above URL where <Id> is the unique Id of the Assessment record that was returned in the JSON data from the above call to create the Candidate / Assessment record.
The following parameters must be passed to Test Partnership using the HTTP GET method:
| Parameter Name | Parameter Value |
|---|---|
| AccessToken | As detailed above. |
Sample Request Schemas
https://www.tptests.com/api/assessment/status/?&AccessToken=sample&Id=sampleExample Error Response
{“Errors": [Example Successful Response
{Where the values are defined as follows:
| Parameter Name | Parameter Value |
|---|---|
| <Errors> | This field will contain error messages in the following format: {“Key”:””, “Message” : “”} where Key is the parameter name and Message is corresponding error message. |
| <Status><Id> | Overall Status for the Assessment, possible values are: In Progress, Submitted and Downloaded. |
| <SubmissionDate> | A string giving the date and time in UTC in ISO 8601 format (yyyy-MM-ddThh:mm:ss) that the Assessment was completed / Submitted. This field is only populated if Status contains Submitted or Downloaded. |
| <Score> | Overall Score for the Assessment – Overall Score is an integer between 1 and 10. |
| <Tests><Id> | The unique Test Id of the one of the Tests within the Assessment. Note: This value should be stored in the Integrator’s system as it is needed for future API calls. |
| <Tests><TestName> | Test Name – the Name of one of the Tests within the Assessment. |
| <Tests><TestStatus> | Test Status – the Status of this test within the Assessment, possible values are: Awaiting Resume, Completed, Not Started, and In Progress. |
/api/assessment/token/<Id> – GET METHOD
This API call returns an assessment token. This token in turn will be used to authenticate the candidate during the Auto login process. Validity of the token is time-limited, in this case 5 minutes.
The following parameters must be passed to Test Partnership using the HTTP GET method:
| Parameter Name | Parameter Value |
|---|---|
| AccessToken | As detailed above. |
Sample Request Schemas
https://www.tptests.com/api/assessment/token/?&AccessToken=sample&Id=sampleExample Error Response
{“Errors":[Example Successful Response
{“Errors":[],Where the values are defined as follows:
| Parameter Name | Parameter Value |
|---|---|
| <Errors> | This field will contain error messages in the following format: {“Key”:””, “Message” : “”} where Key is the parameter name and Message is corresponding error message. |
| <AssessmentToken> | Assessment Token – the unique guid. |
/api/assessment/resetassessmentsection/<Id> – GET METHOD
This API call deletes the results of a candidate’s previously completed assessment section and creates a new assessment section, ready for them to take that part of the assessment again. It may also reset some data on the assessment: for example, if they had already submitted the assessment, then the assessment’s overall score will be wiped too.
The following parameters must be passed to Test Partnership using the HTTP GET method:
| Parameter Name | Parameter Value |
|---|---|
| AccessToken | As detailed above. |
| Id | The ID of the assessment section to reset. Be careful not to pass in the candidate ID nor the assessment ID. |
Sample Request Schemas
https://www.tptests.com/api/assessment/resetassessmentsection/?&AccessToken=sample&Id=sampleExample Error Response
{“Errors":[Example Successful Response
{ 200 }Where the values are defined as follows:
| Parameter Name | Parameter Value |
|---|---|
| <Errors> | This field will contain error messages in the following format: {“Key”:””, “Message” : “”} where Key is the parameter name and Message is corresponding error message. |
In order to automatically log a Candidate into the Test Partnership Platform and back on to a specific Assessment they need to be redirected to the following:
<Auto Login Base URI>/?assessmentToken=<assessmentToken>
Where <assessmentToken> is the guid string using the details provided in the ‘/api/assessment/token/<Id>‘ section of this document.
| Parameter Name | Parameter Value |
|---|---|
| <AssessmentToken> | The assessment token detailed in the section above. |
We have created a sample flow implementation in the form of an HTML file. Please feel free to download it here.
To run the sample flow file on our Staging environment (with staging credentials) just enter the parameters ProjectKey, ApiUsername, and ApiPassword and run. To run using Live credentials you will first need to edit the file so that all URLs point to www.tptests.com rather than staging.tptests.com.
Users of our API are limited to 300 requests every 2 minutes. Sending further requests will result in them being rejected with the HTTP code 429 (TooManyRequests). Normal usage of the API will not trip this limit.
If you trip this limit because you're polling us looking for candidate results, there are better ways of checking whether or not a candidate has finished their assessment, for example, by using the RedirectUrl parameter when creating a candidate.
If you trip this limit because you're trying to create too many candidates at once, consider using the Create CSV feature in the Client platform instead.