Hire
Automate recruitment record updates/creation in your HR tech system through our seamless Hire API
Contents
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:
- Authentication credentials for the particular PageUp Customer/Client
- 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):
