Hire

Last updated: 15 Nov 2024

Overview

The HIRE API enables integration with PageUp for the purposes of processing new employees and activating jobs within PageUp.

Contents

  1. Scopes
  2. URL Format
  3. Requirements of Use
  4. Common workflows
  5. Postman Collection

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

Processing Offers to Your Payroll or HRIS Solution

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

1. GET `

Retrieve the list of offers that are accepted, have a completed new starter form, and have not yet been processed. Conditions:

  • offerAccepted = true
  • offerProcessed = false
  • formComplete = true

2. GET `

Retrieve the complete list of offer details by PageUp Offer ID. Where:

  • {{offerId}} = PUReferenceID

3. GET `

Retrieve the new starter form answers by PageUp Offer ID. Where:

  • {{offerId}} = PUReferenceID

4. GET `

Retrieve the application form answers by PageUp Application ID. Where:

  • {{applicationId}} = PUReferenceID (under Applications object from the /offers response)

5. POST `

Mark the offer as processed. This will ensure that the offer will not appear again on the next round of the call. Ensure:

  • Set this process only after all the responses and data have been processed successfully. Where:
  • {{offerId}} = PUReferenceID

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}/offer
  • /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:

  1. Use the PUReferenceID from the document object.
  2. Make a request to the /document/{id}/downloadurl endpoint (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):

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

Run in Postman