Hire

Last updated: 11 Jul 2024

Automate recruitment record updates/creation in your HR tech system through our seamless Hire API


Contents

  1. Overview
  2. Requesting API Credentials
  3. Before you begin
  4. Common workflows
  5. URL format
  6. Postman Collection

Overview

The hire API enables HR tech systems to integrate with PageUp for the purposes of hiring, obtaining recruitment data and to support recruitment processes within PageUp.

A few common uses (but not limited to) of the hire API:

  • Exporting new starter data to external systems
  • Searching for applications and offer related data
  • Initiate onboarding of new starters in external systems

Requesting API Credentials

For information on how to obtain API credentials to begin integrating with the API, please visit the Getting started page.


Before you begin

To begin using any of the APIs, there are a few things that you will need:

  1. Authentication credentials for the particular PageUp Customer/Client
  2. You will need a valid (oAuth) JWT token to authorize yourself to access the end points in this API section. When requesting the bearer token with the authentication service please ensure you include the appropriate scope in the authentication request. Multiple scopes may be requested by specifying them as space separated list. The available scopes for the endpoints in this page are:
HTTP Method Endpoint Group Scope
HTTP-GET Offer Public.Offer.Read
HTTP-POST Offer Public.Offer.Write
HTTP-GET Job Public.Job.Read
HTTP-POST Job Public.Job.Write
HTTP-PUT Job Public.Job.Write
HTTP-GET SearchApplications Public.Application.Read
HTTP-POST SearchApplications Public.Application.Write

See the implementation notes under each endpoint below to see which scope it's needed for each of the endpoint.

Technical

  • API's are secured using oAuth (client credentials grant flow)
  • Integrators must handle common errors and support surfacing of error messages back to the user when a request is not successful
  • Integrators must log all relevant errors and be able to provide a copy to PageUp to assist with troubleshooting when required
Notes:
  • Client ID and Client secret will be different per environment (i.e. UAT and LIVE)
  • The oAuth token has an expiry period of 300 seconds.

Monitoring

  • Integrators must have in place monitoring processes to alert on failed requests, updates, retries or any other mechanisms.

Common workflows

1. Capture applicant and application form information

GET /jobs/{jobId}/applications endpoint under SearchApplications
Search applications by JobID (either sExternalJobID or lJobID. See the API endpoint documentation parameter below for further detail)
(Note: In the user interface, Job ID could be labelled something else depending on the instance's configuration)
GET /applicants/{applicantId} endpoint under SearchApplications
Get applicant details by PageUp Applicant ID.
{{applicantId}} = PUReferenceID under ApplicantInfo from the /jobs/{jobId}/applications response
GET /applications/{applicationId}/applicationForm endpoint under SearchApplications
Get the application form answers by PageUp Application ID.
{{applicationId}} = PUReferenceID under ApplicationInfo from the /jobs/{jobId}/applications response

2. Processing offer to your payroll/HRIS solution

Capture applicant details, application form answers, new starter form answers, and the offer details to process in your payroll/HRIS solution

GET /offers endpoint under Offer
Get the offers that are accepted, completed new starter form and has not yet been processed.
Where
   offerAccepted = true
   offerProcessed = false
   formComplete = true
GET /offers/{offerId} endpoint under Offer
Get offer details by PageUp Offer ID.
Where
   {{offerId}} = PUReferenceID under OfferInfo from the /offers response
GET /offers/{offerId}/onboardingform endpoint under Offer
Get the new starter form answers by PageUp Offer ID.
Where
   {{offerId}} = PUReferenceID under OfferInfo from the /offers response
GET /applications/{applicationId}/applicationForm endpoint under SearchApplications
Get the application form answers by PageUp Application ID.
Where
   {{applicationId}} = PUReferenceID under ApplicationInfo from the /offers response
POST /offers/{offerId}/process endpoint under Offer
Set the offer as processed, so the offer won't come up again on the next round of the call.
Ensure to set this process once all the responses and data have been processed successfully.
Where
   {{offerId}} = PUReferenceID under *OfferInfo* from the /offers response

3. Downloading Recruitment Document

Retrieving the recruitment documents/files (e.g. offer documents, application documents, job documents) to be downloaded our from PageUp

Depending on the type of documents, in the API endpoints such as (but not limited to):

  • /offers/
  • /applications//offer
  • /jobs/

will return Documents object for Job, Offer and/or Application:

"Documents": [
        {
          "PUReferenceID": 0,
          "Title": "string",
          "FileSizeKB": 0,
          "Extension": "string",
          "MimeType": "string",
          "DocumentCategory": "string",
          "CreatedDate": "2022-07-11T00:39:30.582Z",
          "FileName": "string"
        }
      ]
GET ***/document/

see https://developers.pageuppeople.com/Api/Recruitment/Document

Get the document download URL of the document
Where
   {{id}} = PUReferenceID under Document object

URL format

Root url:
https://<environment>.<dataCentreId>.pageuppeople.com/v3/<tenantId>/recruitment/hire/...
Where
  environment = specify 'api' for production or 'apiuat' for development or testing
  dataCentreId = the data centre to connect to (e.g. dc2)
  tenantId = the organisation's tenant Id (normally a 3-digit number. e.g. 218)
Region dataCentreId
AUS dc2
UK / EMEA dc3
US dc4
SEA dc5

Please contact PageUp representative to find out the data centre and organisation's tenant Id if not known.

Example - connect to the 218 production environment on dc2

https://api.dc2.pageuppeople.com/v3/218/recruitment/hire/jobs/1234

Example - connect to the 218 development or testing environment on dc2

https://apiuat.dc2.pageuppeople.com/v3/218/recruitment/hire/jobs/1234

Postman Collection

The access token request Postman collection is available publicly below (Recruitment API > Hire API):

https://postman.com/puptechsolution/workspace/pageup-public-workspace/documentation/421061-5f56c18e-2665-472e-be55-e9a338f60d13

Run in Postman