Purpose
This guide outlines how to integrate an Applicant Tracking System (ATS) to People First Onboarding, transferring successful candidates in readiness for enabling their onboarding journey. For organisations who do not use the People First Recruitment module, bringing these two systems together will streamline the hiring process for both HR and recruitment teams, ensure a seamless transition from candidate selection to employee onboarding, and accelerate time-to-productivity for new hires.
This document assumes the reader has knowledge of People First terminology and is familiar with API authentication methods, general API usage, and HTTP status codes.
References:
People First/ATS Setup
If possible, store the job title alongside the corresponding ID within the ATS, so that when the applicant gets appointed, we know which People First job they will be entering. Job IDs are preferred over job titles because the former will be unique whilst the latter may not be.
API basic guidelines
In the following sections, PFBASEURI refers to "People First Base URI" – see "Note:" under API Requests Section.
In the API calls, date values are specified in format YYYY-MM-DD and IDs follow the uuid convention (32 hexadecimal characters).
Error codes – successful requests will return status codes of 200 or 201. API calls which return 400 means the body of the request has something wrong with it. API calls which return 401 or 404 generally mean there is an authorisation issue.
Note: All example API calls in this document contain sample data.
Authentication
To make use of these API calls, the ATS will need to use a Personal Access Token (PAT) generated from People First.
When creating the new PAT token, we should select access to "Onboarding Integration" and "HRM Integration" as shown above to access the Onboarding API calls and the job search API calls respectively.
See: REST API Integration for generating PAT token.
This PAT should be included as the value of the "Authorization" HTTP header.
Finding a job in People First
In order to create a new person using the Onboarding API, there must be existing job vacancies in the system that have been created previously.
See: Creating a new job
Get People First jobid from job title
If the job ID is unknown to the ATS, an API call can first be made to fetch this by searching on Job Title as follows:
GET PFBASEURI/api/v1/hrm/org/orgId/search?t=position&effDate=YYYY-MM-DD&q=xxxThe 'YYYY-MM-DD' part corresponds with the start date of the onboarder.
This date is necessary in order to return the correct list of vacant job positions as of the given date.
The 'xxx' part of the API request corresponds with the search term for the title of the job.
- The result of this request will return a single result if there is only one job with title 'xxx' as of the given date.
- The result of this request will return list of results if there are multiple job positions which match the 'xxx' title as of the given date.
- The result of this request will return an empty list if there are no jobs that have a matching job title as of the input date.
Sample Response with 2 results:
{
"meta": {
"links": {
"self": {
"href": "/hrm/org/orgId/search?t=position&effDate=2026-04-23&q=Sales%20Executive"
}
},
"results.strucitem": {
"items": 2,
"total": 2
}
},
"data": {
"results": {
"_links": {},
"strucitem": [
{
"_links": {
"self": {
"href": "/hrm/structure/50986037-c1ee-4b44-bac3-b211008dfee5/effDate/2026-04-23"
},
"parent": {
"href": "/hrm/structure/ce1c4495-d6ea-43b3-80a5-b0d6010f286e/effDate/2026-04-23"
},
"ancestors": {
"href": "/hrm/jobs/50986037-c1ee-4b44-bac3-b211008dfee5/structuretree/effdate/2026-04-23"
}
},
"structureId": "50986037-c1ee-4b44-bac3-b211008dfee5",
"type": "",
"name": "Sales Executive",
"structureReference": "",
"parentName": "Sales Department",
"personId": "",
"occupantName": "",
"knownAs": "",
"personalReference": "",
"occupancyId": ""
},
{
"_links": {
"self": {
"href": "/hrm/structure/8c6cc566-cbaa-42fa-bfa9-b211008dfef7/effDate/2026-04-23"
},
"parent": {
"href": "/hrm/structure/ce1c4495-d6ea-43b3-80a5-b0d6010f286e/effDate/2026-04-23"
},
"ancestors": {
"href": "/hrm/jobs/8c6cc566-cbaa-42fa-bfa9-b211008dfef7/structuretree/effdate/2026-04-23"
}
},
"structureId": "8c6cc566-cbaa-42fa-bfa9-b211008dfef7",
"type": "",
"name": "Sales Executive",
"structureReference": "",
"parentName": "Sales Department",
"personId": "",
"occupantName": "",
"knownAs": "",
"personalReference": "",
"occupancyId": ""
}
]
}
}
}
The structureId is the jobId needed for future API calls, eg: "structureId": "8c6cc566-cbaa-42fa-bfa9-b211008dfef7",
this will be referred to as <jobId>.
Create an onboarder
Get new onboarder resource template
Before an onboarder can be created in People First, an API call is needed to retrieve the available reference data values, and check the request body format.
To get the onboarder resource template, make API call:
GET PFBASEURI/api/v1/onboarding/person/resourcetemplateSample response:
{
"data": {
"onboardingPerson": {
"titleId": "",
"firstName": "",
"lastName": "",
"employmentStartDate": "",
"jobId": "",
"_links": {
"jobs": {
"href": "hrm/org/orgId/search?t=position"
}
}
}
},
"meta": {
"onboardingPerson.employmentStartDate": {
"mandatory": "true"
},
"onboardingPerson.jobId": {
"mandatory": "true",
"links": {
"values": {
"href": "hrm/org/orgId/search?t=position"
}
}
},
"onboardingPerson.firstName": {
"mandatory": "true"
},
"onboardingPerson.titleId": {
"mandatory": "true",
"values": [
{
"id": "cf14f246-385f-4fb3-b90f-a1254ef5520e",
"value": "Dr"
},
{
"id": "5175ae20-63d7-48e3-824d-72d35d1e960c",
"value": "Miss"
},
{
"id": "9e188b9d-737b-4c9d-92bb-199d8a6fba5c",
"value": "Mr"
},
{
"id": "930fe73a-c2d5-446c-9819-75823d4fd7fe",
"value": "Mrs"
},
{
"id": "77165d3e-aebb-41fd-891e-5fc7ce169ace",
"value": "Ms"
},
{
"id": "1a564fa5-4de3-4a6a-bca3-2869c20414eb",
"value": "Professor"
}
]
},
"onboardingPerson.lastName": {
"mandatory": "true"
},
"links": {
"self": {
"href": "onboarding/person/resourcetemplate"
}
}
}
}In this response, the onboardingPerson.titleId field has a set of possible values in the "meta" section, each containing a value and an ID proprerty. These IDs should be used against the relevant title (Mr, Ms, etc.) when creating an onboarder.
Create a new onboarder person
Required fields:
- Title ID [uuid - 32 characters]
- First Name [text]
- Last Name [text]
- Employment Start Date [YYYY-MM-DD] - Can be edited at a later date
- Job ID [uuid - 32 characters] - Must already exist (Creating a new job)
To create the onboarder person, perform an api call of type POST.
POST PFBASEURI/api/v1/onboarding/person with sample body:
{
"onboardingPerson": {
"titleId": "9e188b9d-737b-4c9d-92bb-199d8a6fba5c",
"firstName": "Roderick",
"lastName": "Cline",
"employmentStartDate": "2026-12-07",
"jobId": "50986037-c1ee-4b44-bac3-b211008dfee5"
}
}
Sample response:
{
"data": {
"onboardingPerson": {
"correlationId": "f322065e-1df5-4b07-931b-c0a990ecc268",
"titleId": "9e188b9d-737b-4c9d-92bb-199d8a6fba5c",
"firstName": "Roderick",
"lastName": "Cline",
"employmentStartDate": "2026-12-07",
"jobId": "50986037-c1ee-4b44-bac3-b211008dfee5",
"onboardingStatusId": "7816fd7b-3c16-488f-9609-1944fecbc301",
"_links": {
"onboardingSetup": {
"href": "onboarding/occupancies/7816fd7b-3c16-488f-9609-1944fecbc301/setup"
},
"jobs": {
"href": "hrm/org/orgId/search?t=position"
}
}
}
},
"meta": {
"onboardingPerson.employmentStartDate": {
"mandatory": "true"
},
"onboardingPerson.jobId": {
"mandatory": "true"
},
"onboardingPerson.firstName": {
"mandatory": "true"
},
"onboardingPerson.titleId": {
"mandatory": "true"
},
"onboardingPerson.lastName": {
"mandatory": "true"
},
"links": {
"self": {
"href": "onboarding/person"
}
}
}
}
Additional onboarder details
If the ATS has collected additional information for the onboarder such as contact details, address, driver details, etc., these can be added after the person has been created by following this guide.
Person created
Upon successful creation of a person in onboarding, the new person can be viewed within People First when navigating to the Pending view within the Onboarding application as shown below.
Set up onboarding
To begin onboarding someone using the People First Onboarding module, click on the '+' icon beside their name, and a panel will appear on the side of the screen to fill out the necessary details for the newly appointed onboarder to get started.
