Test Partnership Application Integration Guide

Prepared by Oliver Savill
Version Number: 1.8
Version Date: 02 March 2017
Version Notes: Added TScore to example /assessments/scores output

1.1 Integrator Access Details

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

1.2 Process Flow

The basic flow between the Integrator and the Test Partnership Platform is as follows:

Client Integrator
Test Partnership Platform
  • 1. Candidate Registers / Is imported

     

  • 2. Call /api/candidate API to register Candidate on Test Partnership Platform

     

  • 3. When ready Candidate seamlessly logged into Test Partnership Platform

     

  • 4. Redirect to Test Partnership Autologin endpoint

     

    5. Candidate progresses through Test Partnership Assessment process

     

    6. When Candidate has completed process redirected to Integrator Autologin endpoint

     

  • 7. Candidate seamlessly logged back into Integrator’s platform and this triggers the system to retrieve scores and reports from Test Partnership Platform

     

  • 8. Call /api/assessment/scores/<Id> API to get back Candidate’s scores

     

    9. Call /api/assessment/reports/<Id> API to get back Candidate’s PDF Reports

     

In addition to the above flow the following will be allowed any time after No.2 above:

Client Integrator
Test Partnership Platform
  • 1. Update Candidate Progress Status on UI

     

  • 2. Call /api/assessment/status/<Id> API

     

Client Integrator
Test Partnership Platform
  • 1. Update Latest Test Scores on UI

     

  • 2. Call /api/assessment/scores/<Id> API

     


1.3 RESTful API Methods

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.
Password The password of the Client to access Test Partnership.

Example Request

https://tptests.com/api/client/token?/&Username=TPTESTUSER&Password=TPTESTPASS

Example Error Response

{“Errors": [
             {
             "Key":"Username",
             "Message":"Username is required"
             },
             {
             "Key":"Password",
             "Message":"Password is required"
             }
           ],
"AccessToken": null
}

Example Successful Response

{
"Errors": [],
"AccessToken":"84a057ac-d4d3-4baa-bf35-5a4197a9f543"
}

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 rest of the APIs.

/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 new Assessment is simply added. 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. Parameters GenderType, Qualifications, HasDemographicData and HideInstructions are all 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.
Username The username for the Candidate to access Test Partnership. This should ideally be the same as the Candidate would use to login to the Integrator’s platform for simplicity.
Password The password for the Candidate to access Test Partnership. This should ideally be the same as the Candidate would use to login to the Integrator’s platform for simplicity.
Title The Candidate’s Title (not mandatory).
FirstName The Candidate’s First Name.
LastName The Candidate’s Surname.
Email The email address to which Test Partnership mail servers will send the candidate's login details (Username and Password). This is usually the candidate's email address but it can be wherever you wish the details to be sent to.
Telephone The Candidate’s Telephone Number (not mandatory).
RedirectURL The URL that Test Partnership will redirect the Candidate back to following the completion of their Assessment. 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)
GenderType The Candidate’s Gender Number (not mandatory).
Qualifications The Candidates highest level of education. Valid values are 1 – 7. These represent:
1 – GCSE or Highschool
2 – A Levels or College
3 – Undergraduate Degree (BSc / BA)
4 – Postgraduate Degree (MSc / MA)
5 – Doctorate (PhD / DPhil)
7 – Prefer not to say
Number (not mandatory).
HasDemographicData A Boolean value to enable a shortened user journey Number (not mandatory).
HasExtraTime A Boolean value that sets the candidate's assessment time factor to 1.25% the normal time value (not mandatory).
FactorPercentage An integer value that sets the candidate's assessment time factor to 1.X% the normal time value (not mandatory).
HideInstructions A Boolean value to enable a shortened user journey Number (not mandatory).
DemographicData A dynamic JSON object. Attributes are defined by the Client in the Client portal. Object key's are equal to question text. Contact Test Partnership to enable this in your Client portal (not mandatory).

Example Request

{
   "AccessToken": "00000000-0000-0000-0000-000000000000",
   "ProjectAccessKey": "AccessKey",
   "Username": "TPCandidate",
   "Password": "TpCandidatePass",
   "FirstName": "TPCandidate",
   "LastName": "TpCandidate",
   "Email": "TpCandidate@Test.com",
   "Telephone": null,
   "RedirectURL": "www.google.com",
   "GenderType": "male",
   "Qualifications": 7
}


Example Error Response

{“Errors": [
             {
             "Key":"AccessToken",
             "Message":"Access token is invalid"
             },
             {
             "Key":"Username",
             "Message":"Username is required"
             },
             {
             "Key":"Password",
             "Message":"Password is required"
             },
             {
             "Key":"Email”,
             "Message":"Email is required"
             }
           ],
"Assessment":{
             "Id":0,
             "Tests":[]
             }
}

Example Successful Response

{“Errors"[],
"Assessment":{
             "Id":1182,
             "Tests":[
                   {
                   "Id":377,
                   "TestName":"Verbal Test",
                   "TestMinutes":20
                   },
                   {
                   "Id":378,
                   "TestName":"Numerical Test",
                   "TestMinutes":15
                   }
                   ,{to N Test Details}
                   ]
             }
}

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. 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.

/api/candidate/IsCandidate – GET METHOD

This API call returns whether a username has been registered as a candidate. 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.
AccessToken As detailed above.

Example Error Response

{
 "Errors": [
             {
             "Key": "IsCandidate",
             "Message": "False"
             }
           ]
}


Example Successful Response

{"IsCandidate":"True"}

/api/candidate/GetAssessmentsForCandidate – GET METHOD

This API call returns all the assessments a candidate has been registered for. 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.
AccessToken As detailed above.

Example Error Response

{
 "Errors": [
           {
           "Key": "Assessments",
           "Message": "Assessments not found"
           }
           ]
}


Example Successful Response

{
 "Assessments": [
                {
                "Id":1109,
                "ProjectsID": 1041,
                "CandidatesID": 1027,
                "ProjectName": "Manager Assessments"
                "AssessmentSections": [
                    {
                    "AssessmentSectiondId": 91833,
                    "AssessmentSectionName": "Sample Abstract Reasoning"
                    }
                ]
                }
                ]
}


/api/assessment/verificaton/<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 a shorter time limit 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.

Example Error Response

{
 "Errors": [
           {
           "Key": "AssessmentSectiondId",
           "Message": "Verification assessment already created for this assessment section"
           }
           ]
}


Example Successful Response

{
 "Errors": [],
 "AssessmentToken":”97a057ac-d4d3-4baa-bf35-5a4197a9f543”
}


/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.

Example Error Response

{"Errors":[
            {
            "Key":"AccessToken",
            "Message":"Access Token is required"
            },
            {
            "Key":"Id",
            "Message":"Assessment ID is invalid"
            }
           ]
}


Example Successful Response

{"Errors":[
"Status":"Submitted",
"SubmissionDate":"2015-05-28T14:05:29",
"Score":"4",
"Tests":[
        {
        "Id":346,
        "TestName":"16PF Personality",
        "TestStatus":"Completed",
        "TestTime":175,
        "ZScore":"",
        "PercentileScore":"",
        "StenScore":"",
        "Verification": null,
        "TScore": "29",
        "EndTime": "06/03/2017 10:32:20"
        "Scales":[
                 {
                 "Scale":"Approachable",
                 "StenScore":8
                 },
                 {
                 "Scale":"Assertive",
                 "StenScore":4
                 },
                 ]
        },         {
        "Id": 91833,
        "TestName": "Sample Abstract Reasoning",
        "TestStatus": "Completed",
        "TestTime": 0,
        "ZScore": "-2.112551",
        "PercentileScore": "2",
        "StenScore": "1",
        "Verification": null,
        "TScore": "29",
        "EndTime": "06/03/2017 10:38:20"
        "Scales": [],
        },
        {
        "Id": 91834,
        "TestName": "Verification - Sample Abstract Reasoning",
        "TestStatus": null,
        "TestTime": 0,
        "ZScore": null,
        "PercentileScore": null,
        "StenScore": null,
        "Verification": "passed",
        "TScore": null,
        "EndTime": "06/03/2017 10:41:30"
        "Scales": [],
        },

        ]
}

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 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 either a positive or negative number.
<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:
Scalename – name of the PQ Scale
StenScore – PQ Scale Score

/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.

The following data will be returned:

A binary stream will be returned which will contain 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": [
           {
           "Key":"Id",
           "Message":"Assessment ID is required"
           }
           ]
}

/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 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.

Example Error Response

{“Errors": [
           {
           "Key":"Id",
           "Message":"Assessment ID is required"
           }
           ]
"Status":null,
"SubmissionDate":null,
"Tests":[]
}


Example Successful Response

{
 "Errors":[],
 "Status":"Submitted",
 "SubmissionDate":"2015-05-28T14:05:29",
 "Score":"4",
 "Tests":[
         {
         "Id":343,
         "TestName":"Verbal Test",
         "TestStatus":"Completed",
         },
         {to N Test Details}
         ]
}

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 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.

Example Error Response

{“Errors":[
          {
          "Key":"Id",
          "Message":"Assessment ID is required"
          }
          ]
"AssessmentToken":null
}

Example Successful Response

{“Errors":[
          {
          "Key":"Id",
          "Message":"Assessment ID is required"
          }
          ]
"AssessmentToken":”97a057ac-d4d3-4baa-bf35-5a4197a9f543”
}

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.

1.4 Auto Login End Point

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.