Purpose
To provide an integrator with a guide for which People First API calls are needed to integrate an Applicant Tracking System (ATS) with People First Onboarding, so that appointed applicants can automatically be created within the People First Onboarding module (with all of their relevant data from the ATS carried over) ready to have their onboarding set up.
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.
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.
This PAT should be included as the value of the "Authorization" HTTP header.
Finding a job in People First
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]
- Job ID [uuid - 32 characters]
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"
}
}
}
}
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.
