Setting up the TeamTailor Integration

This guide explains the field requirements and expectations for Sona integration on Teamtailor.

---

Overview

When a candidate is hired in TeamTailor, the integration:

1. Creates a User in Sona
2. Creates an Employment period with contract, pay, and hours information 

---

To set up the integration

Step 1: Sona will provide a secret identifier to activate the integration. This identifier is for your organisation only, and must not be shared.

You must paste this secret identifier in your TeamTailor instance. Go into Settings, scroll down to "Marketplace activations" and paste your organisation's identifier there

Step 2: Make sure all Sona required fields are created in TeamTailor. 

Some fields exists by default in TeamTailor but there are requirements for the integration to work properly:

TeamTailor field	Field type	Description	Requirement
Department	-	TeamTailor department	Must match an Org Unit name in Sona (case-insensitive)
Job	-	TeamTailor job	Must match a Type of Work name in Sona (case-insensitive)

Additionally, in order for a candidate to be created as an employee in Sona, some non default fields are required. Make sure you create those in TeamTailor so that they can be filled out before sending the hired candidate to Sona. 

To create a new field, go to Settings > Recruitment > Custom fields. You can read more about it on the TeamTailor support website. 

When creating a custom field, you will be able to provide: 

1. A title : this will be displayed in each candidate's page and can be what makes most sense to you
2. A field type: this must match the column 'field type" as described below for the integration to work
3. An API name: this must match the column 'TeamTailor API name field' as described below for the integration to work
    

The REQUIRED fields are
 

TeamTailor API name field	Field type	Description	Requirement
start-date	Date	Employment start date	Must be a valid date (YYYY-MM-DD)
contract-type	Select	Contract type	Must match a Contract Type name in Sona (case-insensitive)
level	Select	Employee level/grade	Must match a Level name in Sona (case-insensitive)
contracted-hours	Number	Weekly contracted hours	Must be a number >= 0
contracted-days	Number	Days per week	Must be a number between 1 and 7
pay-rate	Number	Annual salary or hourly rate	Must be a number (in pounds, e.g. 50000 for £50,000)
pay-type	Select	How the employee is paid	Must be exactly "Salaried" or "Hourly"

There are also OPTIONAL fields that can be used to fill in information from TeamTailor into Sona but don't have to. These fields are optional but have specific format requirements if provided:

TeamTailor Field	Field Type	Description	Format Requirement
phone	Phone	Mobile phone number	Must be a valid UK mobile number (see below)
email	Email	Email address	Must be a valid email format
title	Select	Title	Must be one of: Mr, Mrs, Miss, Dr, Ms, Mx
insurance-number	Text	National Insurance number	Must be format: 2 letters + 6 digits + 1 letter (A-D), e.g. AB123456C
date-of-birth	Date	Date of birth	Must be a valid date (YYYY-MM-DD)
gender	Select	Gender	Must be "Male" or "Female" (maps to sex field)
marital-status	Select	Marital status	Must be one of: Single, Married, Divorced, Widowed, Civil Partnership, Separated
middle-name	Text	Middle name	Any text
probation-end-date	Date	End of probation period	Must be a valid date (YYYY-MM-DD)
address-line-1	Text	Street address	Any text
city	Text	City/town	Any text
postcode	Text	Postal code	Any text
country	Text	Country name	Any text (e.g. "United Kingdom")
job-title	Text	Job	Any text

Step 3: Once the setup has been done, there are 2 ways for a candidate to be sent to Sona. 
 

1.  A candidate can be sent to Sona by clicking on the menu bar, the 3 vertical dots and then select "Add integrations". 
    

2. A candidate can be sent automatically if the Job Posting has a Trigger associated to it. To add a Trigger to your Job, you can read the TeamTailor support article here.