Assessment

Last updated: 15 Nov 2024

The Assessment API enables external providers to integrate directly with the Page Up recruitment process.

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

picture alt

  • 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.
  • ReportReceived (formerly 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

picture alt

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, the POST /assessmentorders/{assessmentOrderId}/acknowledge endpoint 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 require 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 will no longer call or receive requests to and from servers that either do not have HTTPS enabled, or those that still 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 which contains metadata and hyperlinks processing the assessment order and assessment.

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/"
    }
  }
}
Where
  event - the descriptive name of the event
  instanceId - a reference to the InstanceId used for requesting an access token
  assessmentOrder id - an identifier for acknowledging, scoring and resetting the assessment
  auth link - the endpoint on which an access token is requested. Example usage is appending this value with `/connect/token` to retrieve a token
  host link - the endpoint on which assessment related operations are performed. Example usage is appending this value with `/assessments/assessmentorders/{guid}` to 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 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 Acecss 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 matches the tenant from which the assessment order originated from. 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.
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. UAT is used for ongoing integrations, improvements and validations while Live has the actual production versions and values. Live and UAT may run different versions of the code base and have separate data stores. These two environments are the clients' two tenants. Access tokens are unique per tenant. For example, if an assessment provider is deployed for Client_A and Client_B, both of which have a Live and UAT environment then said assessment provider will have 4 sets of credentials:

Sample Hashmap

The following is an example hashmap of tenants and credentials

Client InstanceId AuthUrl ClientId ClientSecret Tenant
Client_A 218 https://login.dc2.pageuppeople.com Client_A Live Id Client_A Live Secret 218_LIVE
Client_A 218 https://loginuat.dc2.pageuppeople.com Client_A UAT Id Client_A UAT Secret 218_UAT
Client_B 543 https://login.dc3.pageuppeople.com Client_B Live Id Client_B Live Secret 543_LIVE
Client_B 543 https://loginuat.dc3.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

When first testing your integration, you will be given credentials for a single tenant matching one of PageUp's Demo UAT (User Acceptance Testing) environments. During this time, there is only one access token generation endpoint and one set of credentials. 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://loginuat.dc2.pageuppeople.com)
  <clientId> - the partner id supplied by PageUp
  <clientSecret> - the partner secret supplied by PageUp

Once the initial integration is successful, you will be provided Live/UAT credentials for the client's tenants. Please use the webhook properties to correctly map the credentials and 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 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.

Development Notes

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.

Assessments can only be created once

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.

Assessment order timeliness

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

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.

I'm 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.

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 is generated using client A's credentials.

Sample Error Scenario 2

An assessment provider is integrated with client A who has a Live and UAT environment. When an assessment order webhook from the Live environment is received, the access token is generated using the UAT credentials.

Please make sure to use an access token generated from the matching client and environment credentials as highlighted in the Retrieving Access Tokens section.