Insights API

The Transparent Supply Insights API allows authorized users (human and system) to retrieve supply chain and cold chain data for registered products.

You can use the Transparent Supply Insights API to view aggregated data to gain an understanding of your supply chain. The data provided by Insights API is curated, with out of order data, data corrections, and containment inheritance for sensor readings managed and applied by Insights. This allows you to easily start performing your own analytics and build metric from the provided raw data. Along with the curated raw data, Insights provides you with a set of basic metrics, including inventory, product inflow and outflow, product age or shelf life, and sensor reading exceptions such as date, time, duration and locations in which they occur.
Note: Insights API requires an extra license beyond the base Transparent Supply license.
You can use Insights API to retrieve data and metrics in the following categories for your supply chain:
Table 1. Examples of data and metrics retrieved by Insights API.
Category Data and metrics
Inventory
  • Inventory for all products at a single location.
  • Inventory for a single product at all locations.
  • Inventory for a single product that is in transit (based on entry and exit).
  • Inventory for all products that are in transit to (inbound) or from (outbound) a single location.
  • Quantities of products, including at-risk inventory.
Inflow and Outflow
  • Inflows of all products to a single location.
  • Inflows of a single product to all locations.
  • Outflows of all products from a single location.
  • Outflows of a single product from all locations.
Freshness
  • Dwell time of a single product.
  • Age or shelf life of a single product.
  • Time until expiration of a single product.
Cold Chain
  • Raw ambient temperature readings for specified time ranges.
  • Rule configuration for temperature exceptions.
  • Instances over or under a user-defined temperature and time threshold.
  • Temperature readings for in transit containers.

Prerequisites

To use the Transparent Supply Insights API, you must meet the following prerequisites:

  1. Your organization has subscribed to Insights.
  2. Your data integration experts are familiar with using REST APIs to send data programmatically. Automation of data upload is an ultimate goal to facilitate data sharing.
  3. For Transparent Supply organizations to share supply chain data, each organization must have defined the appropriate level of data access control. For details on restricting and sharing your data, see Data entitlement mode and Data access control.

Getting started

Take the following steps to get started with the Transparent Supply Insights API:

  1. Obtain an Authentication Token, as described in Authentication.
  2. Submit an Insights API request, with the authentication token in the authorization header.

Swagger

To use the Insights API manually, use the Swagger interface for the following environments:

You must first provide a valid Transparent Supply authorization token (human user token) on Swagger, using the Authorize button.

Products endpoints

The products endpoints retrieve product, inventory and dwell time data for the specified product identifier (product ID).

Product parameters

The Product ID (query string) identifies the specific product instance for which to retrieve data. The supported formats are:

Table 2. Supported Product ID formats
Type Example and syntax
EPC LGTIN urn:epc:class:lgtin:0614141.107346.101 urn:epc:class:lgtin:<CompanyPrefix>.<ItemRefAndIndicator>.<Lot> (13 digits + Lot #)
EPC SGTIN urn:epc:id:sgtin:0614141.107346.2017 urn:epc:id:sgtin:<CompanyPrefix>.<ItemRefAndIndicator>.<SerialNumber> (13 Digits + Serial Number)
Transparent Supply Product ID with Lot # urn:ibm:ift:product:lot:class:1234567890123.product-123.lot4 urn:ibm:ift:product:lot:class:<Company Prefix>.<Item Reference>.<Lot Number>
Transparent Supply Product ID with Serial # urn:ibm:ift:product:serial:obj:1234567890123.product-123.serial-number-4567 urn:ibm:ift:product:serial:obj:<Company Prefix>.<Item Reference>.<Serial Number>

Locations endpoints

The locations endpoints retrieve product, inventory and dwell time data for the specified location identifier (facility ID).

Location parameters

The facility ID (query string) identifies the specific facility (location) for which to retrieve insights data. The supported formats are:

Table 3. Supported facility ID formats.
Type Example and syntax
EPC-SGLN urn:epc:id:sgln:0614141.00777.0 urn:epc:id:sgln:'<CompanyPrefix>.<LocationReference>.<Extension>(12 Digits + Extension)
GS1-GLN 4098765000010 <CompanyPrefix><LocationReference><CheckDigit>(13 Digits)
Location urn:ibm:ift:location:loc:1234567890123.store_123 urn:ibm:ift:location:loc:<Company Prefix>.<Location Reference>
Location with Extension urn:ibm:ift:location:extension:loc:1234567890123.store_123.toydepartment urn:ibm:ift:location:extension:loc:<Company Prefix>.<Location Reference>.<Extension>

At-risk configurations endpoints

The at-risk configurations endpoints retrieve insights data for the specified organization, product or facility type.

Parameters for at-risk items

The product ID (query string) or facility type (party role code) identifies the specific product or facility type for which to retrieve insights data. The supported formats are:

Table 4. Supported at-risk configuration product ID formats.
Type Example and syntax
EPC LGTIN urn:epc:class:lgtin:0614141.107346.101 urn:epc:class:lgtin:<CompanyPrefix>.<ItemRefAndIndicator>.<Lot>(13 digits + Lot #)
EPC SGTIN urn:epc:id:sgtin:0614141.107346.2017 urn:epc:id:sgtin:<CompanyPrefix>.<ItemRefAndIndicator>.<SerialNumber> (13 Digits + Serial Number)
Transparent Supply product ID with Lot # urn:ibm:ift:product:lot:class:1234567890123.product-123.lot4 urn:ibm:ift:product:lot:class:<Company Prefix>.<Item Reference>.<Lot Number>
Transparent Supply product ID with Serial # urn:ibm:ift:product:serial:obj:1234567890123.product-123.serial-number-4567 urn:ibm:ift:product:serial:obj:<Company Prefix>.<Item Reference>.<Serial Number>

The facility type (party role code) identifies the specific facility type for which to retrieve data. The supported formats are:

Table 5. Supported at-risk configuration facility type formats.
Transparent Supply Party Role Code Name
DISTRIBUTION_CENTER Distribution Center
PROCESSING_FACILITY Processing Facility
PROCESSING_PLANT Processing Plant