The IBM Food Trust™ Insights API allows authorized users (human and system) to retrieve data for supply chain and cold chain products.

To use the IBM Food Trust Insights API, you must meet the following prerequisites:

1. Your Organization has subscribed to the Insights Module.

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 IBM Food Trust 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 and Access Control.

Take the following steps to get started with the IBM Food Trust Insights API:

1. Obtain an Authentication Token, as described in Authenticate Human Users and Authenticate System Users.

2. Submit a Fresh Insights API request, with the authentication token in the Authorization header.

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

• Sandbox Fresh Insights API
• Production Fresh Insights API

You must first provide a valid IBM Food Trust Authorization Token (human user token) on Swagger, using the Authorize button on the top right of the page.

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

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

Table 1. 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)
IBM Food Trust 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>
IBM Food Trust 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 locations endpoints retrieve product, inventory, dwell time and freshness data for the specified location identifier (Facility ID).

The Facility ID (query string) identifies the specific facility (location) for which to retrieve freshness data. The supported formats are shown in Table 2:

Table 2. 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>

The At Risk Configurations endpoints retrieve freshness data for the specified organization, product or facility type.

The Product ID (query string) or Facility Type (party role code) identifies the specific product or facility type for which to retrieve freshness data. The supported formats are shown in Table 3:

Table 3. 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)
IBM Food Trust 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>
IBM Food Trust 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 freshness data. The supported formats are shown in Table 4:

Table 4. Supported At Risk Configuration Facility Type Formats

IBM Food Trust Party Role Code	Name
DISTRIBUTION_CENTER	Distribution Center
PROCESSING_FACILITY	Processing Facility
PROCESSING_PLANT	Processing Plant

• Insights API usage
• Insights Data
• Swagger Insights API