The purpose of this guide is to give you the tools needed to understand and integrate our API into your systems. In the guide we explain the terminology and provide some examples of the Master International REST API.
All development is done against our live PRODUCTION environment. Please contact support for access to a development account to avoid affecting live customer data.
The API authentication is based on a standard Token Based authentication process. Before you can call any endpoint, you must authenticate to get a token. The token can then be used with all subsequent requests. You can reuse the same token until it has expired or until you need to authenticate as a different Client or User.
The basic calling flow is to get an auth token and use it for all subsequent requests for the same request flow. The token is valid until a different user or person is making a request, you will need to generate a new auth token for each separate flow, meaning that user A of your system can use the same authToken within their session, but user B (even if they are from the same company) will need a new authToken. You will also need to generate a new auth token once the flow “stops”, so you can generate a token to create a new project/job position and use the same token to add testtakers, but if the same user returns after 20 mins to add more test takers you should generate a new token.
We recommend one Assessments pr. HR/ATS hiring project or job position. Creating an assessment includes selecting the appropriate tests (OPTO, ACE, BRIGHT etc) and the option for the test taker to download a report at the end of the test, if required. An assessment can be tagged with an ExternalId referencing a local Project or JobPosition.
Then POST some invitations for the people you would like to invite, including the e-mail and name of the person. A URL is returned that is a direct link to the questionnaires for that person, this can be sent to the test taker by you or you can request that master sends the invitation directly by setting the “send email” flag. When creating an invitation you have the option of leaving out the “send email” attribute or setting it to false to handle sending of mails yourself, but if set to true then (on production) the test taker will be sent an e-mail from the Master International system with the link to the questionnaire.
The External ID used when POSTing an invitation request is the unique ID of the person in your system and it can be used to link results between the two systems. It is required to send this to correctly get the Post Back of results to work.
There are currently 2 areas where you can get a “call back” from our system. When a questionnaire has been started and when it has also been completed. We have supplied the format for the JSON request that would be made, and all we need is the end point to post to to set this up.
Real (project) Ids have been used in this documentation and can be used for testing, however we will also provide a list of the available questionnaire Ids for both project and production when needed to allow you to store these for when they are needed.
In summary: