Hire
Overview
The HIRE API enables integration with PageUp for the purposes of processing new employees and activating jobs within PageUp.
Contents
Scopes
All scopes for endpoints on this page are listed below. The authentication page has further scope usage information.
| HTTP | Endpoint | Scope |
|---|---|---|
| GET | Offer | Public.Offer.Read |
| POST | Offer | Public.Offer.Write |
| GET | Job | Public.Job.Read |
| POST | Job | Public.Job.Write |
| PUT | Job | Public.Job.Write |
| GET | SearchApplications | Public.Application.Read |
| POST | SearchApplications | Public.Application.Write |
URL Format
Root URL:
https://<environment>.<dataCentreId>.pageuppeople.com/v3/<tenantId>/recruitment/hire/...
environment = 'api' for LIVE or 'apiuat' for UAT
dataCentreId = the data centre to connect to (e.g. dc2)
tenantId = the organisation's tenant Id
Examples:
LIVE 6784 environment for dc2: https://api.dc2.pageuppeople.com/v3/6784/recruitment/hire/...
UAT 6784 environment for dc5: https://apiuat.dc5.pageuppeople.com/v3/6784/recruitment/hire/...
Requirements of Use
- 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
- Integrators must have in place monitoring processes to alert on failed requests, updates, retries or any other mechanisms.
Common Workflows
Integrating to your Payroll or HRIS systems
Capture applicant details, application form answers, new starter form answers, and offer details to process in your payroll or HRIS solution.
The main consideration would be the number of integrations you need to accomplish; have a discussion as to how many integrations you will require (e.g., if you only need to integrate to one external HRIS system).
For single integrations, the process will typically be:
However, if there are multiple integrations, the same endpoint should be called with the offerActionTypeId querystring to differentiate as to which integration (e.g., you have separate HRIS and Payroll processing providers) is being marked as processed:
It is important to note that these two mechanisms do not work together. If you have been using bTransmitFull in the past and want to shift to offer actions, you will need to backfill old offers with the new offer actions. This needs to be done so that older offers will not re-appear when you retrieve the list of offers that are not yet marked as processed for a specific offer action.
The above illustration is only an example for two integrations. More can be accommodated if needed.
1. GET [endpoint_url]/offers
Retrieve the list of offers that are accepted, have a completed new starter form, and have not yet been processed.
Common filters (Querystring):
offerActionTypeId = {{offerActionTypeId}}offerAccepted = trueofferProcessed = falseformComplete = true
NOTE: If offerActionTypeId is not included as a querystring, bTransmitFull will be checked but not any offer actions. On the other hand, if offerActionTypeId is used, the value of bTransmitFull will be ignored.
Special filters:
offersAcceptedAfterProcessingAsUnprocessed = trueto find candidates that accepted an offer after you have already marked an offer as processed with eitherbTransmitFullorofferActionTypeId. This typically happens if offers are left unaccepted for a longer period than normal.
2. GET [endpoint_url]/offers/[offerId]
Retrieve the complete list of offer details by PageUp Offer ID.
Where:
{{offerId}} = PUReferenceID
3. GET [endpoint_url]/offers/[offerId]/onboardingform
Retrieve the new starter form answers by PageUp Offer ID.
Where:
{{offerId}} = PUReferenceID
4. GET [endpoint_url]/applications/[applicationId]/applicationForm
Retrieve the application form answers by PageUp Application ID.
Where:
{{applicationId}} = PUReferenceID(under Applications object from the/offersresponse)
5. GET [endpoint_url]/applications/[applicationId]/forms/[formtype]
Retrieve other form answers by PageUp Application ID.
Where:
{{applicationId}} = PUReferenceID(under Applications object from the/offersresponse){{formtype}} = additionalinfoThe type of form to retrieve.
Available form types:
- additionalInfo - Additional information forms
- genericInternal - Generic internal forms
6. POST [endpoint_url]/offers/[offerId]/process
A. Mark offers as processed for a single integration (bTransmitFull)
URL: POST [endpoint_url]/offers/[offerId]/process
Mark the offer as processed using the bTransmitFull flag. This is the scenario applicable to most users, and will ensure that the offer will not appear again on the next round of the API call.
However, proceed to the next section if you have multiple applications that access application data (e.g., an HRIS or ERP other than PageUp). You can only use bTransmitFull if you are not using Offer Actions, which was designed to accommodate multiple integrations. Consult your contact in PageUp for more details.
Ensure:
- Set this process only after all the responses and data have been processed successfully.
Where:
{{offerId}} = PUReferenceID
B. Mark offers as processed for multiple integrations (Offer Actions)
URL: POST [endpoint_url]/offers/[offerId]/process?offerActionTypeId={{offerActionTypeId}}
Mark the offer as processed for the specified offerActionTypeId. This will ensure that the offer will not appear again on the next round of the API call, for that particular offer action. This will, however, ignore bTransmitFull. If you had previously used bTransmitFull, all offers not previously marked as processed with offer actions will need to be backfilled so they don't appear in offer search operations. Consult your contact in PageUp if you wish to use offer actions but you have existing workflows using the bTransmitFull field.
Ensure:
- Set this process only after all the responses and data have been processed successfully.
Where:
{{offerId}} = PUReferenceID{{offerActionTypeId}} = string- The name of the specific offer action. This can be arbitrarily assigned, and the consistency of its use is in the discretion of the caller.
Downloading Recruitment Documents
To download recruitment-related documents (e.g., offer documents, application documents, job documents) from PageUp, you can use specific API endpoints based on the type of document you need:
/offers/{offerId}/applications/{applicationId}/jobs/{jobId}
These endpoints return a Documents object for the respective Job, Offer, or Application, which looks like this:
"Documents": [
{
"PUReferenceID": 0,
"Title": "string",
"FileSizeKB": 0,
"Extension": "string",
"MimeType": "string",
"DocumentCategory": "string",
"CreatedDate": "2022-07-11T00:39:30.582Z",
"FileName": "string"
}
]
To download the file:
- Use the PUReferenceID from the document object.
- Make a request to the
/document/{id}/downloadurlendpoint (from the Document API) using the PUReferenceID as the{id}. Refer to the PageUp API documentation for more details on the Document API.
Postman Collection
The access token request Postman collection is available publicly below (Recruitment API > Hire API):
