Integrations - Applicant Tracking System

Creating a department

Finding a parent department / organisation

Creating a department requires a parent department or organisation.

If the parent is a department then make api call to find department matching reference number xxx:

GET PFBASEURI/api/v1/hrm/odata/Units?$filter=StructureReference eq 'xxx'

From the response get the Id which is the department id

          {
            "value": [{
              "Id": "1506be34-3cd7-46ba-ac67-acd100fde2ce",
              "StructureReference": "xxx",
              "Name": "Top Department",
              "FinanceReferenceNumber": "AUTO001",
              "StartDate": "1990-01-01T00:00:00Z",
              "EndDate": null
            }]
          }
        

If the parent is the organization, then People First only has one organization per environment so make this odata query to get the organization id to use as the parent. The id of the organization is different per People First environment.

GET PFBASEURI/api/v1/hrm/odata/Organisations

Sample Response:

          {
            "value": [{
              "Id": "7d4ff72f-6681-41f1-9e18-acd100e57c8d",
              "Name": "Wid",
              "StartDate": "1900-01-01T00:00:00Z",
              "EndDate": null
            }]
          }
        

Creating a new department

To create the department firstly get resource template for the parent:

GET PFBASEURI/api/v1/hrm/structure/<ParentDeptIdOrOrgId>/resourcetemplate?type=Unit&annotate=t

<ParentDeptIdOrOrgId> is id of parent org or department obtained earlier:

To create the new department make post request with sample body:

Mandatory fields - name, startDate, parentStructureId, quantity (default to 1), type. If department reference numbers are set to Manual, then structureReference is mandatory and must adhere to correct format.

Quantity can be used to create more than one department if department reference numbers are set to Autogenerate.

Start date of the department has to be on or after the parent's start date.

POST PFBASEURI/api/v1/hrm/structure/<ParentDeptIdOrOrgId>?type=Unit&annotate=t

          {
            "structureitem": {
              "name": "Special Projects Assistant",
              "startDate": "2024-05-22",
              "endDate": "",
              "parentStructureId": "a34d6b57-c65d-4898-8ba1-ad74007d1600",
              "quantity": 1,
              "structureReference": "S60006",
              "companyRegistrationNumber": "",
              "type": "Unit",
              "reportingUnit": "Special Projects"
            }
          }
        

In the POST response, the id of the new department can be obtained and used to create a job.

Creating attachments

Adding attachment data

Many of the data areas in People First allow attachments to be added against that data area. The APIs work in a similar way whichever area they are in so we will cover these APIs in one section.

An attachment is a file attachment. People First only supports ‘whitelisted’ types and currently only supports files up to 10Mb. To add an attachment using the APIs, the attachment 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))

Get the new attachment resource template

Get resource template for a new attachment by making one of the followjng API calls – the uri differs depending on which area is being used – the id in the chevrons should be replaced with the Id from the PUT/POST request for the appropriate area.

Person attachment

GET PFBASEURI/api/v1/hrm/people/<personid>/attachments/resourcetemplate?annotate=t

Sensitive information attachment

GET PFBASEURI/api/v1/hrm/sensitiveinformation/<personid>/attachments/resourcetemplate?annotate=t

Right to work attachment

GET PFBASEURI/api/v1/hrm/people/<personid>/righttowork/attachments/resourcetemplate?annotate=t

Certificate of sponsorship attachment

GET PFBASEURI/api/v1/hrm/sponsorshipcertificates/<sponsorshipCertificateId>/attachments/resourcetemplate?annotate=t

Settlement status attachment

GET PFBASEURI/api/v1/hrm/settlementstatuses/<settlementstatusId>/attachments/resourcetemplate?annotate=t

Passport attachment

GET PFBASEURI/api/v1/hrm/passports/<passportId>/attachments/resourcetemplate?annotate=t

Residency permit attachment

GET PFBASEURI/api/v1/hrm/residencypermits/<residencypermitId>/attachments/resourcetemplate?annotate=t

Visa attachment

GET PFBASEURI/api/v1/hrm/visas/<visaId>/attachments/resourcetemplate?annotate=t

Work permit attachment

GET PFBASEURI/api/v1/hrm/workpermits/<workpermitId>/attachments/resourcetemplate?annotate=t

Driver details attachment

GET PFBASEURI/api/v1/hrm/occupancies/<occupancyid>/attachments/resourcetemplate?annotate=t

Occupancy attachment

GET PFBASEURI/api/v1/hrm/occupancies/<occupancyid>/attachments/resourcetemplate?annotate=t

Occupancy salary attachment

GET PFBASEURI/api/v1/hrm/occupancies/<occupancyid>/salary/attachments/resourcetemplate?annotate=t

Occupancy scheme and benefit attachment

GET PFBASEURI/api/v1/hrm/occupancies/<occupancyid>/schemesbenefits/item//<itemid>/attachments/resourcetemplate?annotate=t

Create an attachment record

Mandatory fields – documentName, filename, fileData, visibleInSelfService.

The attachment uri is depending on the area:

Person

POST PFBASEURI/api/v1/hrm/people/<personid>/attachments/resourcetemplate?annotate=t

Sensitive information

POST PFBASEURI/api/v1/hrm/people/<personid>/sensitiveinformation/attachments?annotate=t

Right to work attachment

POST PFBASEURI/api/v1/hrm/people/<personid>/righttowork/attachments?annotate=t

Certificate of sponsorship attachment

POST PFBASEURI/api/v1/hrm/sponsorshipcertificates/<sponsorshipCertificateId>/attachments?annotate=t

Settlement status attachment

POST PFBASEURI/api/v1/hrm/settlementstatuses/<settlementstatusId>/attachments?annotate=t

Passport attachment

POST PFBASEURI/api/v1/hrm/passports/<passportId>/attachments?annotate=t

Residency permit attachment

POST PFBASEURI/api/v1/hrm/residencypermits/<residencypermitId>/attachments?annotate=t

Visa attachment

POST PFBASEURI/api/v1/hrm/visas/<visaId>/attachments?annotate=t

Work permit attachment

POST PFBASEURI/api/v1/hrm/workpermits/<workpermitId>/attachments?annotate=t

Driver details attachment

POST PFBASEURI/api/v1/hrm/persondrivers/<driverdetailsid>/attachments?annotate=t

Occupancy attachment

POST PFBASEURI/api/v1/hrm/occupancies/<occupancyid>/attachments?annotate=t

Occupancy attachment

POST PFBASEURI/api/v1/hrm/occupancies/<occupancyid>/salary/attachments?annotate=t

Occupancy scheme and benefit attachment

POST PFBASEURI/api/v1/hrm/occupancies/<occupancyid>/schemesbenefits/item/<itemid>/attachments/resourcetemplate?annotate=t

For example, creating a person attachment – make the following request:

POST PFBASEURI/api/v1/hrm/people/<personid>/drivers?annotate=t with sample body (the fileData has been shortened in this example!):

          {
            "attachments": {
              "visibleInSelfService": true,
              "fileData": "JVBERi0xEJBNTNBMUY0MjRGQzk2RkUzPjw1NDY4N0MxMzBBNTA4MjRCQTUzQTFGNDI0RkM5NkZFMz5dIC9QcmV2IDU5NDIvWFJlZlN0bSA1NjQ3Pj4NCnN0YXJ0eHJlZg0KNjYzNw0KJSVFT0Y=",
              "documentName": "TestForm.pdf",
              "filename": "TestForm.pdf",
              "authorId": ""
            }
          }