Assessment
The Assessment API enables external providers to integrate directly with the Page Up recruitment process.
Contents
Overview
The Assessment API provides methods to register assessment providers and packages, creating assessments, updating the status of assessment and posting assessment results.
Sandbox
A mock API which returns the examples defined in this spec (with the exception of access token endpoints) is available at: https://assessment-mock-api.dc0.pageuppeople.com/.
| NOTE |
|---|
Directly accessing the above mock root URI, or any other endpoint or URI not part of the documentation below, will typically have a response other than HTTP 200 OK; it would usually return HTTP 403 Forbidden instead. |
Although there is no endpoint to retrieve an access token for the mock API, you will be expected to provide Authorization headers in the correct format, without requiring a valid access token. For example, providing an Authorization header with the value Bearer <any-string-value> will work.
Assessment States
- Invited - An invited assessment is a state where the candidate has been invited to take an assessment but has not yet shown intention to take it yet.
- Ordered - An ordered assessment is a state where the assessment provider has created the assessment and it is ready to be taken.
- Completed - Once the candidate has completed taking an assessment, the assessment moves to a completed state.
- Scored - The assessment provider has successfully sent the report on the result of the assessment to PageUp.
Registering Assessment Providers and Creating Assessment Packages
PageUp account managers are responsible for managing the integrations with assessment providers. This includes registering assessment providers into the PageUp system and configuring them in case there are changes. Once an assessment provider has been created, Super Users may add assessment packages via the PageUp Admin system. Candidates can then be invited to take assessments using the assessment packages.
Taking an assessment
Flow
- When the candidate shows intention to take an assessment, an assessment order is placed by notifying the assessment provider.
- The assessment provider is expected to retrieve the assessment order via the
GET /assessmentorders/{assessmentOrderId}endpoint and process the order. Once processed, thePOST /assessmentorders/{assessmentOrderId}/acknowledgeendpoint is used to project the newly created assessment back into the PageUp system. - At this point, the candidate is redirected to the assessment page and can start to take the tests.
- Upon completion of the assessment, the assessment provider should redirect the candidate back to the PageUp system.
- Upon scoring, the assessment provider can project the results to the PageUp system using the
POST /assessments/notifyassessmentreport?assessmentOrderId={assessmentOrderId}endpoint.
Integration Points
HTTPS and TLS
To secure communications between PageUp and its partners, the Assessment API requires that API calls into it as well as webhook calls into partner systems should be encrypted using HTTPS over TLS version 1.2 or higher. The API cannot call or receive requests from servers that do not have HTTPS enabled, or use obsolete versions of TLS (e.g., 1.1 and below) or any version of SSL.
Assessment Order Event [Webhook]
This is the webhook notification body which contains metadata and hyperlinks for processing an assessment. This body is included as part of the request body whenever the webhook is called.
Format
{
"event": "assessmentorder_requested",
"instanceId": "218",
"assessmentOrder": {
"id": "6b806b55-e2da-42e8-91cf-51d48f448050"
},
"_links": {
"auth": {
"href": "https://login.dc2.pageuppeople.com/"
},
"host": {
"href": "https://api.dc2.pageuppeople.com/v3/218/recruitment/"
}
}
}
The attributes above are as follows:
event- the descriptive name of the eventinstanceId- a reference to the InstanceId used for requesting an access token. This is unique for every clientassessmentOrder.id- the identifier for each individual assessment, used for acknowledging, scoring and resetting the assessment_links.auth.href- the root URI for retrieving the access token. For example, appending/connect/tokento this value to retrieve a token_links.host.href- the root URI for calling the Assessment API. For example, appending/assessments/assessmentorders/{guid}to this value will retrieve an assessment order PageUp expects an HTTP status code 200 response from the webhook request to continue the begin assessment flow. If the provider responds with a non-200 status code, the begin assessment flow is stopped and the candidate is redirected to an error page.
Retrieving and Using Access Tokens
To invoke any of the endpoints, an access token must be acquired through the PageUp Auth service using credentials provided by the PageUp team. Results from the Access token request will include an expires_in field which indicates the number of seconds before the token expires (as of time of writing, 600 seconds). It is recommended that the token be reused until it expires (or nears expiry).
To retrieve an access token, the assessment provider must use the clientId and clientSecret the match the tenant from which the assessment order originated. The section below describes the concepts around multi-tenancy and access tokens.
Multi-tenancy and Access Tokens
Ubiquitous Language
| Language | Definition |
|---|---|
| Client | An organisation using the PageUp product. |
| Data Centre | A client's data is only located in the region closest to them, we call these Data Centres (dc). |
| Instance | We refer to the client as an instance, and each instance is identified by an integer instance id. |
| Tenant | A provisioned client environment of the PageUp Product. |
A client usually has a Live and UAT (User Acceptance Testing) environment available to them. Partner development is done against the HR Tech Implementation instance (1101) in Live. When a partner's implementation is completed, User Acceptance Testing (UAT) is performed in the initial client's UAT environment. Upon completion and confirmation that the behavior of the system is correct, the configuration against the Live environment is performed:
Sample Hashmap
The following is an example hashmap of tenants and credentials.
| Client | InstanceId | AuthUrl | ClientId | ClientSecret | Tenant |
|---|---|---|---|---|---|
| HR Tech | 1101 | https://login.dc2.pageuppeople.com | HR Tech Live Id | HR Tech Live Secret | 1101_LIVE |
| Client_A | 218 | https://login.dc4.pageuppeople.com | Client_A Live Id | Client_A Live Secret | 218_LIVE |
| Client_B | 543 | https://login.dc2.pageuppeople.com | Client_B UAT Id | Client_B UAT Secret | 543_UAT |
Using the webhook instanceId and _links.auth.href properties, assessment providers should map the corresponding credentials to use in retrieving the access token. Using an incorrect credential will cause security or access errors.
Access Token Request
During the initial implementation of your integration, you will be given credentials for matching the HR Tech Implementation (1101) environment. Please note that a different set of credentials will be required for every client that you integrate with. The format for requesting a token is as follows:
Url: <authLink>connect/token
Method: POST
Header:
Content-Type:application/x-www-form-urlencoded
Body:
client_id:<clientId>
client_secret:<clientSecret>
grant_type:client_credentials
scope:Public.Assessment.Read Public.Assessment.Write
Where
<authLink> - the authentication endpoint supplied in the assessment order event (e.g. https://login.dc3.pageuppeople.com)
<clientId> - the partner id supplied by PageUp
<clientSecret> - the partner secret supplied by PageUp
Once the initial integration is successful, credentials for your client's UAT environment will be provided first. When User Acceptance is completed, Live credentials will then be provided to you by PageUp. Please use the webhook body's attribute values to correctly determine the endpoints to use.
Using the Access Token
When making a request to the API, the Access Token must be included as an Authorization header value matching the format Bearer <your-token-here>.
Assessment API Operations
Url: <hostLink>v3/<instanceId>/recruitment/assessment
Where
<hostLink> - the host endpoint supplied in the assessment order event
<instanceId> = the instance id supplied in the assessment order event
Example - connect to the 218 production environment on dc2
https://api.dc2.pageuppeople.com/v3/218/recruitment/assessment
GET /assessmentorders/
Using the webhook payload, the assessment order aggregate ID is assembled to retrieve the assessment order.
POST /assessmentorders/
After creating the assessment, use this endpoint to project the assessment onto the PageUp system.
Redirect the candidate to the PageUp completion page [Redirect]
After a candidate completes the assessment, the assessment provider should redirect the candidate to the onCompletionURL. If there was a failure in the operation, redirect the candidate to the onFailedURL.
POST /assessment/notifyreadyforreview
This is an optional step. If a manual review of an assessment is required after a candidate completes the assessment, the assessment provider should notify PageUp and supply a URL where reviewers can perform this action.
POST /assessments/notifyassessmentreport
Providers can send a Report on the Results or any other updates for the Assessment. This includes an optional field showing the state of the Assessment /Report/AssessmentResults/AssessmentStatus which can have either of two values:
- CompletedTest - indicating that the candidate has Completed the test, but has not yet received a Score
- Scored - indicating that the Assessment is Scored and ready to be considered for Screening purposes NOTE that although the HR-JSON format allows multiple comments and descriptions to be provided for each result object, only the first one will be used in the PageUp interface at this time.
POST /assessments/reset
Reset Assessment is an action that allows an candidate to restart taking a test due to errors encountered (i.e. power/connection outage while taking a test, the candidate encountered an emergency in the middle of taking an exam, or similar non-technical reasons where a test has to be restarted.) The state of the assessment would be anywhere between ordered and completed, and once a reset is done, the state of the assessment should return the candidate back to the invited state to allow the candidate to re-take the test. Assessment resets are usually performed upon the request or confirmation of the client and usage is as-needed.
PUT /assessments/assessmentpackages/
This endpoint allows Providers to create and update Assessment Packages in the PageUp system.
POST /assessments/assessmentpackages/
This endpoint allows Providers to archive Assessment Packages in the PageUp system.
Frequently Asked Questions (FAQs)
1. The fields are not sequential and there are UUID fields that are not documented, why?
The JSON responses are subject to a fuzzy serializer to loosen coupling (https://www.abhayachauhan.com/2017/10/fuzzy-serializer/) and as part of this operation, two things happen: a random property is added and the response is shuffled.
2. What happens if the same assessment order is created multiple times?
Only the first received POST /assessmentorders/{assessmentOrderId}/acknowledge call for each assessment is successful. Subsequent calls will return 409 Conflict unless the assessment is reset.
3. How long do I have to create an assessment after responding to the webhook?
PageUp waits for ~10secs after a successful webhook response for the assessment to be created (via the POST /assessmentorders/{assessmentOrderId}/acknowledge endpoint). If the operation times out and no assessment was created, the candidate is redirected to an error page with advice to retry.
Note that if the POST /assessmentorders/{assessmentOrderId}/acknowledge call comes after the timeout, this can still succeed but will not result in the redirect unless the candidate re-attempts to begin the assessment.
This timeout may be revisited/negotiated depending on the assessment providers workflows.
4. What happens when an acknowledged assessment order's webhook notification is triggered two or more times?
Although it is not part of the normal workflow, there are usage or error scenarios which may result in the webhook getting invoked two or more times for the same assessment order. It is expected that in this scenario that the assessment provider invokes the POST /assessmentorders/{assessmentOrderId}/acknowledge endpoint with the same metadata as the already acknowledged order. Note that there is no need to invoke GET /assessmentorders/{assessmentOrderId} if the assessment provider already has the metadata they need to invoke POST /assessmentorders/{assessmentOrderId}/acknowledge.
5. Why am I getting a 404 Http Error when I try to retrieve or update assessment orders?
This is usually accompanied by the following HTTP response message:
The id (aaaaaaaa-1111-2222-3333-bbbbbbbbbbbbb) provided does not exist or is not accessible. Please check the API documentation in https://developers.pageuppeople.com/Api/Recruitment/Assessment or verify your credentials with PageUp Support.
This error can occur when an incorrect access token is used, which can be explained by one of these 3 scenarios:
Sample Error Scenario 1
An assessment provider is integrated with client A and client B. When an assessment order webhook from client B is received, the access token was generated using client A's credentials.
Sample Error Scenario 2
An assessment provider uses the same credentials for client A as was used in the HR Tech Implementation (1101_LIVE) development instance. This will not work as credentials are specific to each client instance and different from the HR Tech Implementation credentials.
Sample Error Scenario 3
An assessment provider is integrated with client A who has a Live and UAT environment. However, when the webhook from the Live environment was received, the credentials for the UAT environment were used instead. This will not work as credentials are specific to each environment.
Please make sure to use an access token generated from the matching client and environment credentials as highlighted in the Retrieving and Using Access Tokens section.