Data Warehousing Integration Setup

Edited

HirePOS provides secure, read-only access to your data exports through Microsoft Azure Blob Storage. You can retrieve these CSV files for reporting, business intelligence, data warehousing and other integrations.

HirePOS hosts and manages the exported data. You can access it from your own systems without needing to host your integration in Microsoft Azure.

To connect, you need:

  • Microsoft Entra ID app registration: Provides your application's identity and authentication credentials.

  • Approved public outbound IP address: Restricts access to your nominated network connection.

  • Compatible integration software: Authenticates and retrieves the CSV files using HTTPS requests.

Your application must meet both the authentication and IP address requirements.

1. Register your application in Microsoft Entra ID

You will need access to a Microsoft Entra ID tenant with permission to manage app registrations.

  1. Open the Microsoft Entra admin centre.

  2. Navigate to Microsoft Entra ID > App registrations > New registration.

  3. Enter a descriptive name, such as HirePOS Data Warehouse Integration.

  4. Under Supported account types, select Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant). Do not select the option that includes personal Microsoft accounts.

  5. Leave the Redirect URI blank.

  6. Register the application.

  7. Under Certificates & secrets, configure a client secret or supported application credential.

Record the following values:

  • Application (Client) ID

  • Directory (Tenant) ID

Keep your client credentials secure. You manage these credentials yourself and can rotate or replace them as required.

Do not send your client secret or private credentials to HirePOS.

2. Request access from HirePOS

Provide HirePOS Support with:

  • Your Application (Client) ID.

  • Your Directory (Tenant) ID.

  • The public outbound IP address(es) your integration will use.

HirePOS will configure read-only access to your designated exports, restricted to your approved application and public IP addresses.

The IP address must be the public address from which your integration connects to HirePOS's storage. This may differ from the internal IP address of your computer or server.

Important: Connections from unapproved IP addresses will be blocked, even when valid authentication credentials are provided.

If you do not have a fixed outbound IP address, see What if my integration doesn't have a static IP address? below.

Once access is configured, HirePOS will provide your authorised export URLs and the HirePOS Directory ID required for authentication.

3. Authenticate using OAuth 2.0

Use the OAuth 2.0 Client Credentials flow to obtain an access token.

Setting

Value

Grant type

client_credentials

Token URL

https://login.microsoftonline.com/{HirePOS-Directory-ID}/oauth2/v2.0/token

Client ID

Your Application (Client) ID

Client credential

Your configured client secret or supported credential

Scope

https://storage.azure.com/.default

Replace {HirePOS-Directory-ID} with the Directory ID provided by HirePOS.

Note: This is the HirePOS Directory ID, not your own Directory (Tenant) ID.

Use the resulting access token to make authenticated HTTPS GET requests to your authorised Azure Blob Storage URLs.

Include both of the following request headers:

Authorization: Bearer {access_token}
x-ms-version: 2023-11-03

Both headers are required. Use the specified x-ms-version value.

4. Retrieve your CSV files

Once authenticated, your application can list available exports and download the CSV files.

List available files

GET https://hireposdwexports.blob.core.windows.net/hirepos-{HirePOS-Subscription-Number}?restype=container&comp=list

A successful request returns HTTP 200 OK with an XML listing of the available files.

Download a CSV file

GET https://hireposdwexports.blob.core.windows.net/hirepos-{HirePOS-Subscription-Number}/{ExportFolder}/{FileName}.csv

A successful request returns HTTP 200 OK with the CSV content.

Replace {HirePOS-Subscription-Number} with your HirePOS subscription number. HirePOS will provide the applicable export paths and file naming details.

You can use any compatible HTTP client or integration platform that supports the required OAuth authentication, HTTPS requests and approved outbound IP address.

5. Data availability and refresh schedules

HirePOS provides approved reporting datasets as monthly CSV files.

Each CSV contains the complete dataset for its reporting month, rather than only new or changed records.

When an export is refreshed, the existing file for that month is replaced with its latest contents. Your integration should account for these full-file replacements to avoid duplicate records.

Current and previous calendar months can be refreshed automatically each night. Availability of older historical periods should be confirmed with HirePOS.

When nightly updates are enabled, HirePOS schedules exports from approximately 12:05am Australian Eastern Standard Time (AEST, UTC+10).

Processing time can vary depending on data volume, so allow sufficient time for exports to complete before retrieving the files.

For available datasets and instructions on enabling, managing and refreshing exports, see the Data Warehousing guide.

Frequently asked questions

Do I need Microsoft Azure to use Data Warehousing?

You need a Microsoft Entra ID app registration for authentication, but you do not need to host your integration in Azure or purchase Azure hosting services.

HirePOS stores and manages your exported data in its own Azure Blob Storage environment.

Your application authenticates using Microsoft Entra ID and retrieves the files through standard HTTPS requests.

The software retrieving the files can run in your own environment, provided it meets the authentication and approved outbound IP requirements.

Does creating a Microsoft Entra app registration cost anything?

Creating and using an app registration is generally free through Microsoft Entra ID Free.

You do not need to purchase Azure hosting, databases or storage services simply to register an application and authenticate with HirePOS.

You do need access to a suitable Microsoft Entra tenant. If you do not already have one, additional Microsoft account or tenant setup requirements may apply.

Other costs may arise from your own hosting, integration software or network configuration, including obtaining a fixed outbound IP address.

Any HirePOS charges for Data Warehousing access or additional datasets are separate from these third-party costs.

Can I run my integration outside Azure?

Yes. You can retrieve the data from any compatible environment that satisfies the authentication and IP address requirements.

For example:

  • Office computer or server: Run a scheduled script to download your CSV exports.

  • AWS, Google Cloud or another hosting provider: Retrieve and process the data using an application hosted outside Azure.

  • Reporting or business intelligence platform: Import the CSV files into your preferred reporting or data analysis tools.

  • AI assistant or internal application: Use a scheduled process to retrieve the data for analysis or automated monitoring.

The integration does not require your application to run on the same cloud platform used by HirePOS.

Why does HirePOS require an approved IP address?

The approved public IP address provides an additional restriction alongside your application credentials.

Even if someone obtains valid authentication credentials, requests from an unapproved public IP address will be blocked.

Your integration must therefore connect from one of the public outbound IP addresses nominated to and approved by HirePOS.

What if my integration doesn't have a static IP address?

You may be able to establish a predictable outbound connection without changing where your application is hosted.

Depending on your environment, options include:

  • Business internet connection: Use an existing static public IP address or request one from your internet provider.

  • Cloud networking: Configure a fixed outbound IP through your hosting provider, such as a NAT gateway or dedicated outbound address.

  • VPN or network gateway: Route your integration traffic through a trusted gateway with a fixed public IP address.

  • Managed integration service: Use a provider that supports dedicated or fixed outbound IP addresses.

These are networking options, not alternative authentication methods.

The important requirement is that the public IP address presented to HirePOS's Azure storage matches an address approved by HirePOS.

If your cloud provider uses changing outbound addresses, consult your provider or IT administrator about establishing a fixed outbound connection.

Some of these options may involve additional third-party costs.

Can I connect using only my app credentials or a SAS token?

For the current HirePOS Data Warehousing integration, application authentication and approved public IP addresses are both required.

Using valid OAuth credentials does not remove the IP address restriction.

The documented integration uses Microsoft Entra authentication. SAS token-only access is not offered as an alternative connection method.

Can I use an AI assistant, Power BI or another reporting tool?

Yes, provided your chosen tool or supporting integration process can authenticate, retrieve the files and connect through an approved public IP address.

Some platforms may need an intermediate script, connector or integration service to handle authentication and download the files.

Once downloaded, the CSV files can be processed using your preferred compatible software.

Troubleshooting

Testing with Postman

Postman can be used to test OAuth authentication and file retrieval.

Use Postman Desktop or a local Desktop Agent so that requests originate from your own network connection.

Postman Cloud may use changing outbound IP addresses that are not approved for access.

When configuring OAuth 2.0 in Postman, set:

Client Authentication: Send client credentials in body

Common connection errors

Result

Likely cause

OAuth token request fails

Incorrect tenant, client credentials or application configuration

403 AuthorizationFailure

Network restrictions, including an unapproved IP address

403 AuthorizationPermissionMismatch

Application lacks permission for the requested resource

401 AuthenticationFailed

Invalid or unsuitable access token, or authentication/header issue

200 OK

Request successful

Authentication succeeds, but I cannot download the CSV files

Successfully obtaining an OAuth access token does not necessarily mean your application can retrieve the data.

Authentication and network access are separate requirements.

Check the following:

  1. Confirm that your request originates from an approved public outbound IP address.

  2. Check whether your hosting provider, VPN or network configuration uses a different outbound address than expected.

  3. Confirm that your application is requesting the correct authorised export URL.

  4. Confirm that both required HTTP headers are included.

  5. Review the HTTP status and Azure Storage error code.

If your public outbound IP address has changed, contact HirePOS Support to update your approved addresses.

Still unable to connect?

Contact HirePOS Support with the HTTP status, Azure Storage error code and a description of your integration environment.

Do not share your client secrets, access tokens or other private credentials.

Was this article helpful?

Sorry about that! Care to tell us more?

Thanks for the feedback!

There was an issue submitting your feedback
Please check your connection and try again.