Introduction

The Jobtrain API is designed to open new ways to use your data and to integrate into the Jobtrain ATS. 

This guide is designed to help facilitate the early stages of this process, to enable clients to test and evaluate the API and its capabilities before committing resources to developing a full integration.

What's included in this guide

• Introduction
• Pre-requisites
  • How to
• Using the API
• More information
  • Username
  • Password

Pre-requisites

• Enabling the API in your solution. This will require you contacting our support team or your Continuous Improvement Consultant to raise a ticket to have it enabled.
  • A designated contact within your organisation is required to clarify the credentials and for any communication regarding the API to be sent to. Typically, this would be someone involved with the IT team/the person doing the testing.
• Sign the API Partnership Agreement, which outlines the terms and conditions of using the API.
  
• A program that allows you to test APIs, such as Postman, which is what this guide will use as an example. Postman can also be used via the web, if installing a new program is not possible.

How to

1. Before starting, check you have received your credentials from us. These will be generated when the API is enabled for your system and the Partnership Agreement has been signed.

2. If using Postman, the easiest way to get started is by clicking the orange button in the top right of the API documentation. This will ask where you want to open it.

Fig 1 – API Documentation and the ‘Run in Postman button, plus options of where to run it.

3. Click into the top section (Jobtrain – OpenAPI 1.0) and go to the Variables tab.

1. Replace the baseURL with the baseURL provided by Jobtrain.
2. Click the three dots at the end of the table and Reset All to update the ‘Current Value’ fields with what was added into the ‘Initial Value’ fields.
3. Remember to click Save in the top right whenever you add something like this.
4. When you generate the API Key later, it will need to be added to this page too.
5. This is telling the program where it needs to send the API requests to.

Fig 2 – Variables section at the top of the API.

4. Navigate to Token > Post /connect/token, then click the Body tag. This is where the rest of the credentials will go. This will allow you to generate the bearer token which has to be sent with each call to authenticate the call.

1. Replace the <string> with the new value but keep the speech marks.
   1. clientID: This will be provided by Jobtrain.
   2. clientSecret: This will be provided by Jobtrain.
   3. username: This is the username of the account you wish to use the API as.
   4. password: This is the API password for that user.

Fig 3 – Token body, and adding credentials.

Fig 4 – Generating the bearer token.

5. Once the token body has been completed, click the save button in the top right, then click the blue Send button, which will send the request to Jobtrain, and a second or two later, should return a long bearer token (Fig 4).

6. This bearer token (not including the speech marks) needs to be copied into the apikey field in the ‘Variables’ section at the top of the hierarchy (shown in Fig 2).

1. Click the three dots and reset the variables to ensure that the current and initial values contain the key.
2. Click Save to ensure that the system remembers the token.
3. This key will only be valid for 30 minutes, so you may need to go back to the Token > Body section and click send again to generate a new token. You do not need to generate a new API Password.
4. In a dedicated API, you would typically generate a new token with each request/set of requests.

7. You are now ready to use the API! A full integration will require scoping with your development team, who will be able to provide steps for using this API in your systems rather than via a third-party program such as Postman (which should only be done for testing/research).

If any assistance is needed with these steps, or you encounter any issues, please reach out to our support team who will assist you or escalate the matter within Jobtrain to the appropriate team.

Using the API

To use the API, click into any of the folders and then into a specific call. 

Some will require specific information to be added before you click Send, in order to provide the relevant information. In this example we will use Jobs > Retrieve a list of Jobs and Candidate > Get Candidate Application Detail By JobId and CandidateId.

For the Retrieve a List of Jobs page, once in the page, simply click Send and it will return a list of jobs. There are certain parameters that can also be sent (defined in the documentation, and shown in the example code) to allow for sorting or paging etc if needed, but these are optional for this call.

Fig 5 – Using the API, List of Jobs.

If you receive an error, saying ‘unauthorised’ for example, then check the credentials and bearer token have been entered correctly, or that the account you’re using has permission to see the jobs.

Some calls require parameters to be sent with them. You can see them in Fig 6 below in the Path Variables section or by reading the documentation. 

This call requires you to add a candidate ID and the JobID of a job the candidate has applied for. These need to be added, then click Send to see the details of that specific application.

Fig 6 - Get Candidate Application Detail By JobId and CandidateId call.

More information

Username

The API is accessed as a Jobtrain user. This means that access controls and Security Role restrictions for that account will apply to the data that can be seen in the API.

As such it is important to ensure that the account being used has the desired permissions/access rights. For some clients, they may wish to be able to pull information just for certain divisions, which can be achieved by using several accounts which only have access to one division each for example.

Password

This is not the password that you login with. Instead, you will need to generate an API password for that account via System Users. There are a couple of things to check here if you are running into trouble.

1. The account you are accessing Jobtrain with to generate the API password needs to have a permission enabled in their Security Role (General Settings: Generate API Password).
2. The account that you want to use the API with/that’s having a password generated for it does not need this permission in its Security Role. It’s only needed to generate the password for any account, rather than being needed on an account for an API password to be created for that same account.
3. If you generate a new password, it will invalidate the old one, so your integration will need to be updated. This should only need to be generated once. You will need to tick the box and click Save before the new password takes effect.

Fig 7 – Generate API Password screens

I’ve followed the guidance notes and have some further questions.

For any questions about using the API (or any other Jobtrain functionality), please contact our Support Team on +44(0)161 8502004.