Exports

Last updated: 29 Jul 2025

Overview

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


Contents

  1. Scopes
  2. URL Format
  3. Prerequisites
  4. Common workflow
  5. Redownloading files

Scopes

All scopes for endpoints on this page are listed below. The authentication page has further scope usage information.

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

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.