Integrations | API

An API (Application Programming Interface) is software that allows different (3rd party) applications to talk to each other and obtain or manipulate information.

Configuration & Settings
Integrations
Nancy Cusack itris Expert

itris API configurations can be set up in the itris Management Utility (IMU).

Introduction

The itris API integration provides endpoints (itris fields/data) that allows a 3rd party to create, read and/or update in itris.

In the context of itris the API is most commonly used to pass information between a website and itris. For example by posting your itris jobs to your website, or allowing applicants to register on your website and passing that data back into itris to create an applicant record.

Other API integrations allow you to exchange applicant, company and contact information to/from various other sources beyond your website. This might be to create new or update existing records in itris or send data from itris to a 3rd party.

For more details on how the API works with SourceWhale please see the article Integrations | SourceWhale.

Full details of the available API endpoints are available in the Technical Documentation (Swagger).

Initial Set up Steps

There are a few initial steps to take to prior to setting up the API: a system user needs to be created, you need an itris API license and a Windows IIS connection needs to be set up.

System User

The itris API integration requires you to create a system user, please see the article System | System Users for further information.

Licensing

In order to configure an itris API you will require a license, please speak with your Account Executive to obtain this. Once your Account Executive has issued the licenses you will need to refresh within the itris Management Utility (IMU) > System > Licenses. This will force the system to pull through the newly applied licenses. Please see the article System | Licences for further information.

Windows IIS Connection

A Windows IIS connection (sometimes called a Web Proxy) needs to be set up, this allows connections to be made from the Internet to an application on the server (in this case the server where itris sits). For our fully-hosted clients this is already in place. For our self-hosted clients we will set this up for you on your itris server, however there are a number of pre-requisites that must be met in for this connection., further details can be provided upon request.

itris API & your Website

When using the API to post jobs to your website, or allowing applicants to register you will need your website developer to configure the API endpoints.

The API end points are essentially the fields/data you want to show on, or retrieve from, your website, which will then be matched to the fields/data available in itris.

Example API Endpoints:

  • Job Posting: Job title, Job description, Job ID, Keywords and so forth. See section below itris Job & API Output Comparison for a visualisation of this.

    • By default, itris will send all your live jobs that contain a job description to your website. If you want only specified jobs posted we recommend using a Keyword to identify these jobs. Your web developer can then use this information to determine which jobs are displayed on your website.

  • Applicant Registrations: Name, Keywords, Contact Details, status etc.

    • When the applicants are added to itris, the created by user will be the System User (see above) that is assigned to the User Impersonation field in the configuration (see below). We recommend using an Applicant Status such as “PreRegistered” and having the API assign this to any applicant registering via your website. This is a Status normally configured when itris is installed, however, if for any reason this Status is not on your itris you can create this in the IMU, see the Data | List items article for how to create an Applicant Status.Additionally, if an applicant applies to a job on your website, as long as the JobID is provided as part of the Job Posting Endpoints, that applicant can be linked to the job in itris under the Applications area.

  • Applicant Inbox - similar to the applicant Registrations API Endpoints above, but with the added bonus of an itris interface where you can process applications and registrations, either updating or creating applicant records.

    • A user can be set up to be notified when an entry is made into the Applicant Inbox. Unlike the Applicant Registrations API End Point any records created in the Applicant Inbox will assign the processing user as the Created by. For more information on managing the Applicant Inbox in itris please see the article Applicant Inbox & Update Utility. You may also find Applicant Inbox | Payload Examples helpful.

Full details of the available API endpoints, which website developer will need to know, are available in the Technical Documentation (Swagger).

Creating a New API Configuration

In order for your website (or 3rd party application) and itris to communicate, an API needs to be configured.

You can have multiple API’s configured, depending on your needs and the number of websites/3rd Parties you wish itris to communicate with.

The majority of the work is then done on your website by your website developer in terms of matching the fields.

Configuration Name is the display name for your configuration, this can act as a label for you to identify what has been configured in each instance.

Username and Password are created by yourself. These credentials will be required by anyone that wants to connect to the API for example your web developer.

User Impersonation is a list of System Users (see the article System | System Users for more information), this will determine which user will display when this API user creates or modifies data in itris. As an example, if you choose to have applicants register through your website, when the record is created in itris the system user will show as the creator in the top right of itris.

Permissions allow you to decide what API functionality the API user can use, as an example, allowing the Job Posting permission will enable this API user to pull live job details from itris and display them on your website (how they are displayed is managed by your website developer).

Throttle Policy is a threshold you can put in place which limits the number of requests that can occur between itris and the application you are integrating with. This limits the amount of data being pulled to and from your server at any one time and reduces the risk of data overload which can potentially slow your itris down. Though they can be changed, please note, that if set too high it may have an adverse effect on itris performance. Defaults are as shown in the image below: 4 requests per second, 10 requests per minute, 80 requests per hour and 1440 requests per day.

itris Job & API Output Comparison

The images below will give you a visualisation of an itris job and the corresponding data produced for the job by the API.

By comparing the two you can see the format that the data is sent by the API. Some data uses integers which your web developer will need to translate for you website, for example where work type is Permanent, this shows on the API data as the number 6, keywords are referred to by their ID number. Your developer can use the Technical Documentation (see Additional articles) to translate this data.

Example itris Job:

Example API Data End Points: