Connecting to APIs to extract data

The API section in HP Insights gives administrators programmatic access to the data and workflows that power your print environment. Whether you're feeding data into Power BI, automating user provisioning, or integrating with a third-party card system, the APIs in HP Insights are built to connect securely with the tools your organization already uses.

What you can do with the APIs

HP Insights offers two methods for accessing data programmatically:

  • OAuth 2.0 client applications — For integrations that need scoped, credential-based access to specific APIs such as SCIM, Document Management, Device Scout, and Print Scout.

  • API Key access — A simpler, read-only method for extracting operational data, device meters, toner levels, status, and print activity into analytics platforms, SIEM tools, or custom dashboards.

There's also a preview feature for External Card Integration, which connects HP Insights with third-party card authentication systems.

Before you begin

  • You must be logged in as an Admin or System User.

  • A valid HP Insights license is required.

  • For OAuth integrations, save your Client Secret immediately after creation. It is shown only once and cannot be retrieved.

Manage OAuth client applications

OAuth 2.0 client applications are credentials you create for each system that needs programmatic access to HP Insights. Each application has its own Client ID and Client Secret, is restricted to a single API, and can be granted Full Access or Read Only permissions.

The Client Application tab is used to manage API integrations by allowing administrators to create, configure, and manage OAuth client applications. This tab provides a centralized interface for generating and controlling the credentials and permissions required for secure, programmatic access to HP Insights APIs.

Available APIs

Each client application targets one of the following APIs:

API Description API Documentation
SCIM v2.0 The SCIM v2.0 API (previously called Users) allows administrators to create, manage, and access user accounts, including guest accounts, programmatically. It provides endpoints to handle tasks such as creating new users (including guest users), updating user details, and deleting users SCIM v2.0 documentation
Document Management The Document Management (also called Secure Documents) API is designed to support organizations migrating from on-premises print management solution, Blueprint, to HP Insights Document Management API documentation

Note: Additional APIs may be available depending on your organisation's configuration.

Create a client application

Before you start, have the following ready:

  • The name of the system or tool you're connecting

  • Which API it needs to access (see Available APIs)

  • Whether it needs read-only or full access

Follow these steps to create a new OAuth client application and obtain credentials.

Step 1: Open the Create Application form

Navigate to Analysis > API > Client Application. The Create Application form appears at the top of the page.

Step 2: Enter an Application Name

Use a descriptive name that identifies the integration's purpose. Examples: Okta-SCIM-Production, PowerBI-Meter-Reporting

Avoid generic names like Test or API1, these become hard to manage when you have multiple integrations running.

Step 3: Select the target API

Choose the API this client will access from the API drop-down. Each client application can target only one API.

Step 4: Select the permission level

Choose from the Access drop-down:

  • Full — The client can read and write data. Use this only when the integration needs to create, update, or delete records (for example, provisioning users via SCIM).

  • Read Only — The client can retrieve data but cannot make changes. Use this for reporting tools, dashboards, or any integration that only needs to pull data.

Always grant the least privilege required. If your integration only reads data, choose Read Only even if you fully trust the system. This limits the potential impact if credentials are ever compromised.

Step 5: Click Create and save your credentials

Click Create. HP Insights generates a Client ID and Client Secret and displays them on screen.

Note: The Client Secret is shown only once. It cannot be retrieved later. Copy both values immediately and store them in your secrets manager before closing the dialog. If you lose the secret, you must revoke the application and create a new one.

The new application appears as a card in the Client Application section. The card shows:

  • Application name

  • Target API and assigned scopes

  • Issue date

  • A Revoke button

  • A link to the relevant API documentation.

Once you have your credentials, pass them to whoever is configuring the integration, a developer, a BI analyst, or your IdP administrator. They'll use the Client ID and Client Secret to obtain an OAuth 2.0 access token, which is then included in API requests to HP Insights.

For implementation details, refer to the documentation linked on the application card.

Revoke a client application

Revoke a client application when:

  • The integration is being decommissioned.

  • The Client Secret has been exposed or you suspect compromise.

  • You're rotating credentials as part of routine maintenance.

How to revoke

  1. In Analysis > API > Client Application, locate the application card you want to remove.

  2. Click Revoke on the card.

  3. Confirm the revocation when prompted.

Note: Revocation is immediate and cannot be undone. All active tokens issued under the revoked Client ID stop working straight away, and the integration will fail until you create new credentials and update its configuration.

Extract data using API Key access

The API Key method provides a straightforward read-only path for extracting operational data from HP Insights into analytics tools, Power BI, SIEM systems, or custom dashboards. A single static Authorization Key gives access to all five data APIs. There's no token exchange, you include the key in every request.

The system generates a new authorization key when you disable and then re-enable an API.

Enable the API Key

  1. Navigate to Analysis > API in the HP Insights web console.

  2. Check the Enable box. This activates the endpoint and creates an Authorization Key.

  3. Copy the Authorization Key. Include it in the Authorization header of every API Key request.

Note: Disabling and re-enabling the API generates a new Authorization Key. Any existing integrations using the old key will stop working.

Connecting to the API to extract Device Meter Data

Note: The Device Meter API accesses only the columns on the Meter grid.

  1. In the Analysis > API screen, check the Enable box to connect to the API endpoint. This also creates an Authorization Key, which will give you access to the API.
  2. Select Device Meter Data. This opens the Device Meter Data dialog box. Take note of the HTTP request URL.
  3. You can manipulate meter data using a range of tools. Refer to the following examples:
  • Powershell

    (Invoke-WebRequest -Headers @{Authorization = "bearer <Authorization Key>"}https://api.insights.hpondemand.com/ReportApi/Reports/Meters).Content

  • curl

    -curl -H 'Authorization: bearer <Authorization Key>' https://api.insights.hpondemand.com/ReportApi/Reports/Meters

  • Power BI Desktop - See Importing data via Power BI Importing data via PowerBI

Connecting to the API to extract Device Status Data

This API enables administrators to retrieve status data for exporting and manipulation.

  1. In the Analysis > API screen, check the Enable box to connect to the API endpoint. This also creates an Authorization Key, which will give you access to the API.
  2. Select Device Status Data. This opens the Device Status Data dialog box. Take note of the HTTP request URL.
  3. You can manipulate meter data using a range of tools. Refer to the following examples:

  • Powershell 

(Invoke-WebRequest -Headers @{Authorization = "bearer <Authorization Key>"} https://api.insights.hpondemand.com/ReportApi/Reports/Status).Content

Connecting to the API to extract Device Toner Data

This API enables administrators to retrieve toner data for exporting and manipulation.

  1. In the Analysis > API screen, check the Enable box to connect to the API endpoint. This also creates an Authorization Key, which will give you access to the API.
  2. Select Device Toner Data. This opens the Device Toner Data dialog box. Take note of the HTTP request URL.
  3. You can manipulate meter data using a range of tools. Refer to the following examples:

  • Powershell 

(Invoke-WebRequest -Headers @{Authorization = "bearer <Authorization Key>"} https://api.insights.hpondemand.com/ReportApi/Reports/Toner).Content

Connecting to the Print Analytics API to extract Print Transactions Data

For print transactions, you’ll need to specify a date range to pull a summary of all user data for the specified period.

  1. Navigate to the Analysis > API screen.
  2. Select Enable to connect to the API endpoint. This creates an Authorization Key, which will give you access to the API.
  3. Click on Print Transactions Data. It opens a dialog box which includes the information you need to extract print transactions data.
  • HTTP request
  • HTTP request header
  • Instructions on how to extract data using different tools
  1. You can manipulate print data using a range of tools. Refer to the following examples.
  • Powershell

(Invoke-WebRequest -Headers @{Authorization = "bearer <Authorization Key>"} https://api.insights.hpondemand.com/ReportApi/Reports/PrintJobs/<YYYY-MM-DD>/<YYYY-MM-DD>).Content

  • curl

curl -H 'Authorization: bearer <Authorization Key>' https://api.insights.hpondemand.com/ReportApi/Reports/PrintJobs/<YYYY-MM-DD>/<YYYY-MM-DD> Example: curl -H 'Authorization: bearer 873fe108995e37b81e0c64b44e895de045c9dcc71408c03d1e70b4e8ca47649f' https://api.insights.hpondemand.com/ReportApi/Reports/PrintJobs/2017-04-01/2017-05-01

Connecting to the Print Analytics API to extract Monthly Print Data

For monthly print data, you’ll need to specify a date range to pull a summary of all user data for the specified period.

  1. Navigate to the Analysis > API screen.
  2. Select Enable to connect to the API endpoint. This creates an Authorization Key, which will give you access to the API.
  3. Click on Monthly Print Data. It opens a dialog box which includes the information you need to extract monthly print data.
  • HTTP request
  • HTTP request header
  • Instructions on how to extract data using different tools
  1. You can manipulate print data using a range of tools. Refer to the following examples.
  • Powershell

(Invoke-WebRequest -Headers @{Authorization = "bearer <Authorization Key>"} https://api.insights.hpondemand.com/ReportApi/Reports/MonthlyPrintJobs/<YYYY-MM>/<YYYY-MM>).Content

  • curl

curl -H 'Authorization: bearer <Authorization Key>' https://api.insights.hpondemand.com/ReportApi/Reports/MonthlyPrintJobs/<YYYY-MM>/<YYYY-MM>

Example: curl -H 'Authorization: bearer 873fe108995e37b81e0c64b44e895de045c9dcc71408c03d1e70b4e8ca47649f' https://api.insights.hpondemand.com/ReportApi/Reports/PrintJobs/2017-04/2017-05

Configuring External Card Integration (Preview Mode)

For information on connecting HP Insights with third-party card systems, see External Card Integration.