Document

Last updated: 23 Dec 2024

This document describes the endpoints, data contracts and operations that can be used to upload and retrieve documents in the PageUp system.

Contents

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

Overview

The document API enables systems to integrate with PageUp for the common purpose of obtaining recruitment documents (files) from PageUp or uploading recruitment documents (files) to PageUp.

Requesting API Credentials

For information on how to obtain API credentials and to start 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:
  • Public.Document.Read
  • Public.Document.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. Upload a recruitment document to PageUp

GET /document/prepareTempDirectUpload
This endpoint will return metadata for an Amazon S3 presigned URL.
See the API endpoint documentation parameter below for further detail)
Required parameter = fileName
Where
fileName = the filename intended to be uploaded
PUT the file to the url property in the response from the prepareTempDirectUpload call above
Ensure the request HTTP headers include the `headers` property from the response `prepareTempDirectUpload` call above
POST /document/moveFromTemp
Where:
id (optional) = PageUp reference ID (lDocumentID). If this PageUp reference ID is passed, then existing document with this ID will be replaced.
title = Document title.
providerID (optional) = PageUp reference ID (lProviderID). This is PageUp reference ID for the user/employee who uploads the file (i.e. employee/user uploaded file).
fileName = The document file name.
physicalFile = This has to be exact fileName as what's being passed in the `prepareTempDirectUpload` above.
documentCategoryId =  This is the system document category ID (lLKP_SystemDocumentCategoryID). See the tables below on the supported IDs.
documentCategoryName` = This is the document category title as setup in the PageUp system
Only one of *either* documentCategoryId or documentCategoryName can be passed. Not both.
applicationId = PageUp reference ID (lApplicationID). Populate this if this is an *application* or *offer* document.
applicantId = PageUp reference ID (lApplicantID). Populate this if this is an *applicant*, *application*, or *offer* document.
jobId` = PageUp reference ID (lJobID). Populate this if this is a *job* document.
offerId` = PageUp reference ID (lOfferID). Populate this if this is an *offer* document.
System Document Category documentCategoryId
Resume 7
Agency 10
MailMatcherEmail 13
PositionDescription 14
ReportBuilderTemplate 17
EmployeeDocument 18
JobNote 19

2. Download recruitment document from PageUp

GET ***/document/
This endpoint will return limited time URL of the document for download.
Where
   {{id}} = PageUp reference document ID (lDocumentID).
   expiresInSeconds = Default is 60 seconds if not specified. Can be specified in the parameters between 10 to 300 seconds

URL format

Root url:
https://<environment>.<dataCentreId>.pageuppeople.com/v3/<tenantId>/recruitment/document/...

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/document/1234

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

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