abstract swish line in gradient colouring from pink to blue on a dark blue background

Integrations - Applicant Tracking System

Creating a new employee using PF import APIs

Authentication

To use the import APIs, a PAT Token with a HRM Imports role can be used.

List of APIs

This document assumes ATS->People First integration is one way with ATS making calls to People First only.

Essentially the ATS needs to make API calls to do the following to get an appointed applicant into People First:

  • Create a person record
  • Add sensitive information details
  • Add address & contact details
  • Add right to work details (up to 7 things including passports, permits etc.)
  • Add driver details
  • Create the job / get the job details
  • Add the person into a job
  • Add salary details
  • Add hours and basis details
  • Add working pattern details
  • Add schemes and benefits details
  • Give the person access to People First by creating a user

Alternatively, the People First import APIs can be called. This is less API calls but does require polling to check when import files have validated and imported. The import APIs can handle multiple import records at once which might be easier to manage. Also, any import files can be viewed within People First (by admin users) so any files failing validation can be fixed and re-imported. The People First imports relevant to the data from the ATS include:

  • People (includes sensitive information, address & contact details)
  • Right to work
  • Driver details
  • Job (if job is to be created)
  • Assign Job (add person into the job)
  • Salary for people
  • Salary for people on grade & payscale
  • Hours & basis for people
  • Working patterns
  • Schemes and Benefits for people
  • Create user for a person

People First has a set of import APIs which are used for onboarding data. There are many different import types such as People, Job, Assign Job, Driver details etc. Each type has a different file import layout. The import file templates can be downloaded within People First – these provide guidance on filling in the fields including which ones are mandatory.

The import APIs take the file contents and firstly validate the contents and import the data if the file content passes validation. The loading of the files is recorded in People First in the Administration->Imports and Exports->Imports area.

The process of importing for each import type is the same and will be described before examples of loading each import are given.


Import Process - General Steps

These are the general steps for an external application to call a People First import API:

  • Make the import file according to the People First layout for the import type.
  • Save the import file as a UTF8 csv file (not UTF8 BOM).
  • Convert file contents as base64 string & make People First API call to create a new import – get the id of the import.
  • Make People First API call to check new import’s status – repeat until status is ‘ReadyToImport’ or ‘RecordValidationFailed’.
  • If status is ‘RecordValidationFailed’, perform error processing and end this processing.
  • If status is ‘ReadyToImport’, make People First API call to import the data.
  • Make People First API call to check import’s status – repeat until status is ‘Imported’.


Importing a new person

Make the person import file

The import file fields need to be populated like the example below with a line of headings and then a line for each person to be created.This file needs saving as a UTF8 csv file.

If any of the data contains commas, which we are using as the delimiter, the individual data in that field can be wrapped in double quotes. It is possible to wrap all fields in double quotes but beware some of the imports such as User will not work with double quotes around the fields.

Personal reference number,Title,First name,Last name,Start date,Reckonable service date,Additional names,Known as,Previous last name,Pronouns,Legislation,Social security number,Date of birth,Date of birth verified,Gender,Legal gender,Marital status,Religion,Nationality,Country of citizenship,Sexual orientation,Ethnic origin / Race,Veteran status,Company phone number,Company phone number country code,Company cell/mobile number,Company cell/mobile number country code,Personal phone number,Personal phone number country code,Personal cell/mobile number,Personal cell/mobile number country code,Company email,Personal email,LinkedIn profile link,Twitter link,Skype,Address line 1,Address line 2,Address line 3,Address line 4,Address line 5,Address line 6,CountryF12345,Mr,Kenneth,Stannard,2024-04-01,,,Malcolm,Ken,,United Kingdom,JE987080A,1997-09-01,2024-04-01,Male,Male,Single,,,,,,,0115 9456 123,44,,,0115 9932419,44,07780 400500,44,,ken.stannard345@hdjfhdhjdshhd.co.uk,,https://twitter.com/kstannard345,kenstannard345,,1 Kimberley Road,Watnall,Nottingham,Notts,NG16 2JH,United Kingdom


Create a new import

Firstly, the person file content needs to be converted to base64 and loaded into the API request body as a stream.

For example, in Powershell you can use the following statement to read in the file content, and convert to base64 - $contents is then used as the fileData in the request body for the POST:

$contents = [Convert]::ToBase64String((Get-Content -Encoding Byte -Path $file))

Make the following API call to create the import:

POST PFBASEURI/api/v1/hrm/importsessions/importtemplates/Person?annotate=t


with sample body:

{
    "importsessions": {
        "fileData": "UGVyc29u…b20va3N0YW5uYXJkMzQ1LGtlbnN0YW5uYXJkMzQ1LZWQgS2luZ2RvbQ0K",
        "documentName": "PeopleImportTest.csv"
    }
}


From the response, get the data.importsessions.id property which is needed to check the status of the import.

Check import status – validation

Replace <importsessionId> in the following uri with the id from the previous step.

POST PFBASEURI/api/v1/hrm/importsessions/<importsessionId>


In the response, check property completionStatus. If this is ‘RecordValidationFailed‘, then there is something wrong with the file format or the data – this needs further investigation.

If the completionStatus is ReadyToImport, then we can proceed with importing the file.

If the completionStatus is PreValidating, then the import is file still being checked so wait a few seconds and repeat this GET request.

Importing the file

To import the file and create the data in People First, make API call:

POST PFBASEURI/api/v1/hrm/importsessions/importing?annotate=t


with sample body:

{
    "importsessions": {
        "id": "<importsessionId>"
    }
}


Replace <importsessionId> with the value from previous step.

Check import status – import

Replace <importsessionId> in the following uri with the id from the previous step.

GET PFBASEURI/api/v1/hrm/importsessions/<importsessionId>


In the response, check property completionStatus. If this is ‘Imported‘ then the file has been imported. Check importFailureCount to see if any errors occurred. Any errors can be investigated in the People First application, or there are further API errors to return the details of the errors.

If the response completionStatus is ‘Importing’ then wait a few seconds and repeat this GET request.


Further Imports

Further imports can be performed to import the rest of the data. There is a logical order to the imports as data for one import type may be dependent on the import of another type.

The import types and the order in which they should be done are:

  • Person
  • RightToWork
  • DriverDetail
  • RightToWorkDocumentationInfo
  • Job (if creating a job as part of this process)
  • Occupancy
  • OccupancyHoursAndBasis
  • OccupancySalary
  • OccupancySalaryGrade
  • WorkingPatternsAndShifts
  • SchemesAndBenefitsForPerson
  • User

The steps for importing a new person should be followed for the other import types, replacing Person in the POST importsession uri with the name of the import type. For User import, replace hrm with iam also

POST PFBASEURI/api/v1/hrm/importsessions/importtemplates/Person?annotate=t

Looking for something specific?