Building an assessment app

This is a high level overview of how to build an assessment app for use in the Talent App Store platform. Please check our Assessments article for more detailed information.

The assessment app sits as a connector between the Talent App Store platform and your own platform.

Define your app in Talent App Store

  • Create an app
  • Take note of the HMAC secret for your app, you’ll need this for making/receiving API calls, as it acts like an API key
  • Browse to the APIs tab and define your app as per below
Producing
Method
API
SoT (Source of Truth)
GET
/appStatus
No
GET
/assessmentTypes/forApp
No
POST
/assessments/byID/{id}/tenantDeltaPings
No
You don't need to define the install / uninstall APIs here
Consuming
Method
API
SoT (Source of Truth)
GET
/assessments/byID/{id}
Yes
GET
/applications/views/byKey/{key}
Yes
PATCH
/assessments/byID/{id}/appDetails
Yes
POST
/assessmentTypes/forApp/deltaPings/1
Yes
  • Browse to the Tazzy tab, and enter your backend server URL. For testing purposes you might want to use ngrok (https://ngrok.com/) to expose your locally running code
  • Browse to the Single sign on tab and set the principal type to “User”

TAS APIs your app must expose

Check that the value of the `tazzy-secret` header on all API calls matches the HMAC secret for your app.
App install
Core / Lifecycle API
This API is called when your app is installed by a tenant in the Talent App Store.
App uninstall
Core / Lifecycle API
This API is called when your app is uninstalled by a tenant in the Talent App Store.
App Status
Optional
This API is called when someone who has your app installed in their tenant, views your app in the Talent App Store marketplace. It is used to indicate if the app is ready to use for them, or if any further configuration is required.
Assessment Types
This API will be called to retrieve the different types of assessments that your app has available for the given tenant.
Start / Update / Delete Assessment
This API will be called on your app to let you know that an assessment has been requested to be started / updated / deleted.We recommend that you add the assessment id here to a queue and respond to this call immediately rather than making the subsequent calls to retrieve assessment data synchronously, for a better user experience.

APIs your app will call

These API calls can not be made from the front end, as that would result in exposing the HMAC secret for the app.

Set the tazzy-secret header with your app's HMAC secret value.

The host you call for these APIs will be https://{yourAppShortcode}.tazzy.io

Retrieve assessment details
This will retrieve the assessment details by the provided id. This is the id passed in the Start / Update / Delete Assessment call.
This contains who raised the assessment, and the type of assessment it is, and a field called “view” which can be used in the subsequent API call to retrieve details about the application/candidate the assessment is for.
Retrieve application details by view
Call this API to retrieve information about the application / candidate that the assessment is for. These views are application specific so if there is additional data you require, tenants who install your app will need to know the fields they need to add to your app's view.
Update Assessment
Call this API to update the assessment status and/or details.
Status updates
Status
Description
In Progress
Once the assessment has been started.
Complete
Once the assessment has been finished.
Opted Out
If the candidate has rejected/refused to complete the assessment.
Error
If there are any errors with the assessment for any reason that means it can not be completed. It’s important to set the error status, otherwise assessments can be left in limbo.
Image updates

The image will usually be displayed in the ATS and is a good way to visually indicate the status of the assessment.

userInteractionMessage

A quick and easy way to provide a message to the recruiter/user. This field is markdown so you can include links to results.

userInteractionUri

When provided, the webpage at the provided URI will be iframed into the ATS to provide results/information about the current status of the assessment

Pass

Flag to indicate a pass or fail if applicable.

AssessmentTypes changed
This notifies any other parts of the system which may have cached the assessment types available from your app that assessment types have changed and they should refetch them.