Integrations

Connect job boards, HR systems and SMS under Settings, test each connection, and see what every one of them switches on.

Settings > Integrations is where a System Admin links Recruit to the outside services your organisation uses. Each service has its own card with a switch, a status badge and buttons for entering and testing its details. Some services need nothing from you, either because HireRoad runs them centrally or because they are set up somewhere else in Recruit. This article covers every section of the page, what to enter for each provider, and what a working connection does afterwards.

Who can do this

Only System Admins can open Settings > Integrations, and only System Admins can change anything on it: saving details, testing, resetting, switching a provider on or off, and managing TotalJobs advert templates. HR, Member, hiring manager and Agency users cannot open the page. They still feel the result, because a board that a System Admin has connected and switched on appears as a choice when HR and System Admin users publish a job.

If your account belongs to a group of companies, a company selector sits beside the page title. Everything you change applies to the company you have selected.

Have the provider's details ready before you start. Boards issue them when you become a customer of that board, and Recruit cannot create them for you.

What the page shows

Providers are grouped into sections in this order: Job Boards, Email & Calendar, HRIS (your HR system) and Messaging. A section appears only when it has something to show, and Messaging appears only for organisations that have the SMS add-on. Video interviewing has no section, because there is nothing to connect (see below).

Each card shows:

• The provider name. Boards that cost nothing to post to carry a Free badge: Indeed (Direct API), LinkedIn Limited, Adzuna and GOV.UK Find a Job.
• A status badge: Pending, Configured or Error.
• A Last tested date and time once you have run a test.
• Configure, which becomes Manage once details have been saved. Providers with nothing to enter have no such button.
• Reset, once the provider is Configured.
• Test Connection and an on/off switch.

If the page cannot load, you see "Couldn't load integrations" with a Try again button. The page also refreshes itself every minute, so a status change made in the background shows up without you reloading.

Connecting a provider

1. Go to Settings > Integrations and find the provider's card.
2. Select Configure. A dialog titled "Configure [provider]" opens.
3. Fill in the fields. Fields marked as required must be completed, and Save Configuration stays greyed out until every field passes. The checks are: "This field is required", "Please enter a valid URL", "URL must start with https://", "Please enter a valid email address" and "Please enter a numeric value".
4. Select Save Configuration. You see "Configuration saved successfully", the dialog closes and the badge changes to Configured. The first save also switches the provider on, so you do not need to touch the switch afterwards.
5. Select Test Connection. The result appears as "Connection successful", or "Connection failed" followed by the reason.

Passwords, keys and tokens are hidden as you type. Use the eye icon (Show field value) to check what you entered. After saving, a secret is shown only in part: the first three and last three characters with dots between them, or dots alone when the value is short. Leave that text as it is to keep the saved value, or type over it to replace it.

Test Connection is greyed out until details are saved, with the hint "Save credentials first to test the connection". For most boards the test signs in to the board with your saved details. For a few connections, including iTrent, TotalJobs, CharityJob and GOV.UK Find a Job, Recruit has no live check to run, so the test confirms that every required field is filled and reports "Configuration validated (no live connection test available)". If a required field is empty, the result reads "Missing required fields:" followed by the names.

To change details later, select Manage, edit the fields and save again.

Status badges and connection errors

• Pending: no details have been saved yet.
• Configured: details are saved.
• Error: Recruit tried to send jobs to the board and the board rejected the details or they were missing. A message appears reading "[Provider] integration is reporting errors", explaining that postings are paused until the next successful attempt.

To clear an Error, select Manage, correct the details, save, then select Test Connection to see the underlying reason if it still fails. When the next delivery succeeds the badge returns to Configured and a message reads "[Provider] integration is working again". Paused postings resume on the next delivery run. Postings that failed in the meantime can be retried from the Job Boards page, which is covered in the article "Troubleshooting failed job board postings".

Switching a provider on or off

The switch on each card controls whether Recruit uses the connection. A board that is switched off, or is still Pending, does not appear as a choice when a job is published. Switching it back on restores it. If you switch on a board that needs details you have not saved yet, a "Failed to update integration" message appears and the switch returns to off. Use Configure first.

Providers with nothing to enter (Adzuna and GOV.UK Find a Job) need only the switch. Indeed needs only the switch too, and has optional settings.

Resetting a provider

Select Reset on a Configured card and confirm in the "Reset Integration Configuration" dialog by selecting Reset Configuration. This deletes every detail you saved for that provider and cannot be undone. The card goes back to Pending and you must enter the details again. Anything HireRoad manages centrally for that provider is restored automatically. You see "Configuration has been reset".

Job boards

Connecting a board here makes it available to choose when you publish a job. Publishing, scheduling and tracking postings are covered in "Publishing a job to job boards". This table lists what each board asks for. Anything marked required must be filled in before you can save.

Astronaut Jobs

Open Configure, enter your Account Email and select Save Configuration. Jobs are published to Astronaut Jobs through your own account. The red note disappears once an email is saved.

Indeed (Direct API)

Indeed needs no credentials from you. Use the switch, or open Configure to adjust these settings:

• Enable Indeed Apply is on by default. Candidates apply through Indeed Apply. Turn it off to post the job for viewing only.
• Send disposition updates to Indeed is on by default. Status changes for applications that came from Indeed are reported back to Indeed. Turn it off to opt out.
• Use the group name as the Indeed source name is off by default. It uses your company group name as the source in the Indeed bulk-posting feed. The company name stays unchanged.
• Recruiter Email, Recruiter Name and Recruiter Phone are optional. If you fill them in, they are sent to Indeed with each posting.

LinkedIn Limited

Company ID is the numeric ID of your LinkedIn Company Page. Poster Email is the address LinkedIn uses to verify who is posting. The other fields are optional: Publisher Name and Publisher URL (which must start with https://) describe the publisher, and Default Country takes a two-letter code such as GB or IE.

At the bottom of the dialog, the Feed URL section shows a Public feed URL with a Copy URL button. It is one shared address for LinkedIn. Your published jobs reach your Company Page through your Company ID, and no access token is needed. Give the address to LinkedIn as part of your Limited Listings setup.

The dialog also holds advanced settings that apply to every job you post to LinkedIn Limited:

• Industry Codes: search and pick the LinkedIn industries that describe your organisation.
• Default Skills: up to 10 skills added to every posting. Type a skill and press Enter.
• Job Posting Availability: PUBLIC makes postings visible to all LinkedIn members. INTERNAL limits them to employees.
• Additional Salary Components: select Add Salary for extra pay blocks such as bonuses. Each has a Currency, a Period (Per Year, Per Month, Per Week, Per Day or Per Hour) and a Min Amount and Max Amount. The base salary always comes from the job itself.
• Job Wrapping Tags: tags that LinkedIn assigns you for its Job Wrapping promotion, one per line, up to 50 characters each. Recruiters choose one per job when they publish.

TotalJobs advert templates

Open the TotalJobs card, select Configure (or Manage) and then Manage advert templates. This leaves the dialog, so save any changes to the connection details first. The TotalJobs advert templates page lists your templates.

1. Select Add template.
2. Enter a Label (up to 100 characters). Recruiters see this name when they publish.
3. Enter the TotalJobs template name (up to 50 characters), exactly as it appears in the TotalJobs back office. It is case-sensitive and sent as typed. A wrong name is posted as a Standard advert with no error, so check the advert type in TotalJobs after your first posting.
4. Select Save.

Use the pencil icon to edit a template and the bin icon to delete one. Deleting does not affect jobs that are already posted. Without any templates, jobs use your TotalJobs account default.

Description length limit

When connected boards have a limit on description length, a banner at the top of the page reads "Description limit: [number] characters (driven by [board])". The lowest limit among your switched-on boards applies. The limits Recruit knows about are Reed 6,500, TotalJobs 5,000, GOV.UK Find a Job 14,000 and LinkedIn Limited 25,000 characters, counted as plain text without formatting. When someone writes a job description, a character counter appears beside it and they cannot continue while it is over the limit.

Email and calendar

The Email & Calendar section lists Google Calendar, but there is nothing to enter on this page. Calendars are personal: each person connects their own Google or Outlook calendar from Settings > My Profile, under Calendar Integrations, and Recruit uses it to read availability and add interview bookings.

The address candidate emails are sent from is a separate System Admin setting. By default emails go out from a HireRoad address. To send from your own domain, and to set a reply-to address, use the Custom Sending Domain card under Settings.

HR systems

The HRIS section connects Recruit to the system that holds your employee records, so a new hire does not have to be typed in twice. It offers iTrent, HiBob, Cintra and Cascade HR. Each has its own set of details.

Your HR system's supplier or your own HR systems team issues these values. Save and test them as described above.

Connecting iTrent

On the iTrent card, select Configure. The dialog has four sections.

1. Under Connection, fill in Endpoint URL (must start with https://), Organisation Code, API Username and API Password. All four are required.
2. Under Webhook Credentials, enter a Webhook Username and Webhook Password. Both are required. They are the username and password iTrent must present when it sends updates back to Recruit.
3. Under Options, turn on Auto-trigger on hire if Recruit should send a candidate to iTrent automatically, and optionally enter a Default Position Reference such as POSN0001.
4. Select Save Configuration, then Test Connection. For iTrent the test confirms that the required fields are complete.

The fourth section, Field Mappings, holds a Configure Field Mappings button. It leaves the dialog for the mappings page, so save first.

Field mappings for iTrent

Field mappings decide which iTrent field each piece of Recruit information is sent to. The defaults are set up for you and most organisations start there. System Admin and HR users can save changes to mappings; in practice you reach the page from the iTrent card, which only a System Admin can open.

The Field Mappings page has a list of Maps on the left. The default maps are Hireroad - People, Hireroad - Email Address, Hireroad - Mobile Number, Hireroad - Attach to Structure, Hireroad - Salary and Hireroad - Basis. Each shows its field count and an Enabled or Disabled badge. Select a map to edit it on the right. Change the Map Name, or use the Enabled switch to turn the whole map off.

Each row is one field, with an iTrent Field name, a Required box, a Source, a Source Value and a Transform. Select Add Field for a new row and the bin icon to remove one. Source is Standard Field (a candidate or offer detail Recruit holds, such as name, contact details, address, start date or salary), Custom Field (one of your own custom fields) or Static Value (text sent exactly as typed for every candidate). Transform can be Uppercase, Lowercase or Title from Gender. Rows that already use Value Mapping, Date Format or Concatenate Fields, as several defaults do, keep them. Leave the Transform on those rows unchanged, because their settings cannot be edited on this page.

Add Map creates a new map. Delete Map removes the selected one after a confirmation. Select Save when you are done. It is available once you have changed something, and "You have unsaved changes" shows in the meantime. Reset to Defaults replaces every mapping with the default set after you confirm. A map can hold up to 200 fields, an organisation can have up to 50 maps, and each name or value can be up to 200 characters.

Sending a new hire to your HR system

Once at least one HR system card is switched on, System Admin and HR users see an HR section on a candidate's profile. Other roles see it only when the candidate already has sync history. It works like this:

• Push to iTrent sends the candidate to iTrent: name, contact details, and the start date and salary from their latest offer, along with anything your field mappings add. The button changes to Pushing... with a Cancel option while it runs. When it finishes, the button reads View synchronisation status. A failed or partial push shows Retry push. The status list on the profile can also be expanded step by step, with its own Retry push button, which is limited to three retries per push.
• With Auto-trigger on hire on for iTrent or HiBob and the card switched on, Recruit sends the candidate automatically when they are moved into the Hired stage. Only one system receives the push, checked in the order iTrent, then HiBob.

Sync statuses are Pending, In progress, Complete, Failed, Partial and Cancelled.

Below the provider cards, the HRIS Synchronisation Activity table shows recent pushes across all candidates, 20 to a page, with Previous and Next. Its columns are Candidate, Provider, Status, Progress, Triggered by, Started and Completed. Filter with All, Complete, Failed or Cancelled. Select a row to open that candidate. On a failed or partial row, the eye icon (View error details) shows the message from the HR system.

Video interviewing

There is no Video interviewing section and nothing to connect. HireFlix, which runs video interviews, is provided and managed by HireRoad for every organisation, so there are no credentials to enter and no card to switch on. Video interview templates and stages are set up in Recruit itself, and they work without anything on this page.

Messaging

If your organisation has the SMS add-on, the Messaging section shows AWS SNS (SMS). Configure opens its settings. Default classification is required and takes Transactional or Promotional. Retention (days) sets how long Recruit keeps SMS audit records: any number from 7 to 3650, and 90 when blank. A value outside that range is moved to the nearest limit. Test Connection checks that Recruit can reach the SMS service and reads "AWS SNS reachable" when it can.

If something goes wrong

• "Failed to save integration": the dialog stays open with your entries intact and gives a reason underneath. Correct it and save again.
• "Connection failed": read the reason shown with it. "Missing required fields" means open Manage and complete them. A message that the credentials were rejected means the board does not accept what is saved, so check them with the board.
• A board is missing when you publish a job: its card is still Pending, or its switch is off.
• The badge shows Error: see the section on connection errors above.
• Reset removed something you needed: enter the details again with Configure. Saved details cannot be recovered.