Developer Portal

Overview

Access export files you have configured in PageUp's system for integrations

Requesting API credentials
Before you begin
URL Format
Prerequisites
Common workflow
Redownloading files

Requesting API Credentials

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

Before you begin

To begin using the Exports API, 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. When requesting the bearer token with the authentication service please ensure you include the scopes required in the authentication request.

The scopes needed for the endpoints in this page are as follows:

HTTP	Endpoint	Scope
GET	Exporter	Public.Exporter.Read
POST	Exporter	Public.Exporter.Write

This information will be provided to you when you register for API credentials.

URL Format

Root URL:
https://{environment}.{dataCentreId}.pageuppeople.com/v3/{tenantId}/platform/

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/platform/...
UAT 6784 environment for dc5: https://apiuat.dc5.pageuppeople.com/v3/6784/platform/...

Prerequisites

One or more flat file exports must be already configured in PageUp
Each export that is intended to be retrieved via the Exports API must have a unique alphanumeric reference configured against it (e.g. 'NewHire')
Your PageUp contact will be able to configure these for you

Common Workflow

1. Retrieve the list of unprocessed files to download

GET [endpoint_url]/Exporter/{exportReference}/ExportFiles
Where:

{exportReference} = the unique reference for a given export (e.g. 'NewHire') - see Prerequisites above if you are not sure what this should be

2. Download file/s

The response returned in Step 1 will contain an array of files that have not yet been marked as processed:

[
  {
    "id": 0,
    "fileName": "string",
    "downloadUrl": "string",
    "urlExpiration": "string"
  }
]

For each file in the array:

Use the pre-authenticated S3 URL found in the downloadUrl attribute to retrieve each file.
If the expiration date listed in urlExpiration has passed before the URL is accessed, you may generate a new URL by returning to Step 1.
Once the file has been successfully downloaded, take the id attribute for that file and proceed to Step 3.

3. Mark file as processed/downloaded

POST [endpoint_url]/Exporter/{exportReference}/ExportFiles/{id}/MarkReceived
Where:

{exportReference} = the unique reference used in Step 1
{id} = the id attribute of the file from Step 2

Redownloading files

Once a given file has been marked as processed, it will no longer appear in the GET [endpoint_url]/Exporter/{exportReference}/ExportFiles endpoint.
If for any reason a file needs to be downloaded after being marked as processed, this can be done provided the id of the file is retained.

GET [endpoint_url]/Exporter/{exportReference}/ExportFiles/{id}
Where:

{exportReference} = the unique reference for the export
{id} = the id attribute of the file

This will return a single-object array of the specified file, in the same format as seen in Step 2 of the Common workflow including the pre-authenticated S3 URL for download.

Exports