Observe

Endpoint URL

https://connect.wholechain.com/Integration/Events

Sandbox URL

https://connect-sandbox.wholechain.com/Integration/Events

Method:

POST

Observe Event

Introduction

An Observe event represents the capture of information about a product, lot, or process at a specific point in time — without changing its state or creating a new product. It is typically used to record conditions, quality checks, measurements, or any other relevant observations during the supply chain journey.

How it works

A Wholechain user can initiate an Observe event directly from the product’s current inventory page or via the Wholechain API, allowing them to add observations such as temperature readings, quality assessments, or audit results.
The observation is stored in the Wholechain database and written to the blockchain, preserving an immutable record of the condition or context of the product at that moment.

Practical Examples

Apple Quality Check:
A quality control technician records an observation after inspecting a lot of apples, logging the number of damaged crates and their condition.
Temperature Monitoring:
A fishing vessel logs a temperature observation for a catch stored in the hold to verify that it remains within required cold-chain parameters.
Moisture Content Reading:
A grain producer records a moisture reading for wheat after harvest, documenting that it meets storage specifications.
Observed Quantity Change:
During a mid-shift audit, a warehouse operator observes that 10 cases are missing from a pallet of produce and logs an observe event with the updated quantity and reason for the loss, without changing product state.

Use Case

This API is typically used when a company needs to capture data about a product’s status at a given point without affecting inventory levels or product state. Observe events are crucial for traceability because they provide a continuous record of product conditions, compliance checks, and other critical data points throughout the supply chain.

Authentication

The API uses an API key (X-API-KEY) to authenticate requests. Each user has a unique API key that controls access to observation event details tied to their company. To understand where this can be found, please visit the Authentication page.

Request Headers for existing master data:

Header	Description	Example Value
`X-API-KEY`	Your API key	`08a3b47b-fc51-4eed-ae7e-a96fe4f49c64`
`Content-Type`	Content type of the request	`application/json`
`accept`	Response content type	`/`

Request Body Parameters:

This document outlines the database schema for storing JSON event data. Each table corresponds to a distinct data object in the JSON structure.

Location Object

Column Name	Data Type	Description	Identifier	Required
`Location ID`	STRING	Unique identifier for the location.	Primary	Yes

Product Instance Object

Column Name	Data Type	Description	Identifier	Required
`Quantity`	DECIMAL	Quantity of the product in the instance.	Not Primary	Yes
`LotSerial`	STRING	Lot or serial number of the product instance.	Not Primary	Yes
`Product ID`	STRING	Unique identifier for the product.	Primary	Yes

Event Object

Column Name	Data Type	Description	Identifier	Required
`Id`	STRING	Unique identifier for the event.	Not Primary	Yes
`PurchaseOrder`	STRING	Purchase order associated with the event.	Not Primary	No
`InvoiceNumber`	STRING	Invoice number linked to the event.	Not Primary	No
`BizStep`	STRING	Business step defining the event type. Learn more	Not Primary	No
`Disposition`	STRING	Status or condition of the item at the event time. Learn more	Not Primary	No
`EventTime`	DATETIME	Timestamp of when the event occurred.	Not Primary	Yes
`EventTimeZone`	STRING	Timezone of the event timestamp.	Not Primary	Yes

Minimum Payload Examples

ℹ️ Note: The minimum data payload contains required fields.
⚠️ Warning: All fields in the minimum data payload must be provided, or the request will fail.

PythonC#Curl

import requests

url = 'https://connect.wholechain.com/Integration/Events'

headers = {
    'accept': '*/*',
    'X-API-KEY': '0193d105-03f6-7829-8de1-d55c166a35f6',
    'Content-Type': 'application/json'
}

data = {
    "Events": [
        {
            "$type": "observe",
            "Location": {
                "Id": "4567"
            },
            "ProductInstances": [
                {
                    "Quantity": 190.75,
                    "LotSerial": "123",
                    "Product": {
                        "Id": "raw_goods_000"
                    }
                }
            ],
            "Id": "0002",
            "EventTime": "2024-03-30T13:00:00+00:00",
            "EventTimeZone": "-05:00"
        }
    ]
}

response = requests.post(url, headers=headers, json=data)

print(response.status_code)
print(response.json())

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

class Program
{
    static async Task Main(string[] args)
    {
        var url = "https://connect.wholechain.com/Integration/Events";
        var apiKey = "0193d105-03f6-7829-8de1-d55c166a35f6";

        var data = new
        {
            Events = new[]
            {
                new
                {
                    $type = "observe",
                    Location = new { Id = "4567" },
                    ProductInstances = new[]
                    {
                        new
                        {
                            Quantity = 190.75,
                            LotSerial = "123",
                            Product = new { Id = "raw_goods_000" }
                        }
                    },
                    Id = "0002",
                    EventTime = "2024-03-30T13:00:00+00:00",
                    EventTimeZone = "-05:00"
                }
            }
        };

        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("accept", "*/*");
            client.DefaultRequestHeaders.Add("X-API-KEY", apiKey);

            var json = JsonConvert.SerializeObject(data);
            var content = new StringContent(json, Encoding.UTF8, "application/json");

            var response = await client.PostAsync(url, content);

            Console.WriteLine($"Status Code: {response.StatusCode}");
            var responseContent = await response.Content.ReadAsStringAsync();
            Console.WriteLine(responseContent);
        }
    }
}

curl -X POST https://connect.wholechain.com/Integration/Events \
-H "accept: */*" \
-H "X-API-KEY: 0193d105-03f6-7829-8de1-d55c166a35f6" \
-H "Content-Type: application/json" \
-d '{
  "Events": [
    {
      "$type": "observe",
      "Location": { "Id": "4567" },
      "ProductInstances": [
        {
          "Quantity": 190.75,
          "LotSerial": "123",
          "Product": { "Id": "raw_goods_000" }
        }
      ],
      "Id": "0002",
      "EventTime": "2024-03-30T13:00:00+00:00",
      "EventTimeZone": "-05:00"
    }
  ]
}'

Additional Fields

In addition to the minimum required data payloads, you may include a range of optional fields, shown in the full payload example below. Refernce to them is made in the tables above where required = "No".

We also support several specialized objects:

Custom Properties Object – Allows you to attach custom properties to a specific event. See the reference table below for details.
Certificate Object – Enables you to include certification details related to an event. See the reference table below.
TLC Object (for FSMA compliance) – Used only when changing the vendor lot code upon receiving a product. In that case, include the vendor lot in the TLC object and also record the TLC lot code.

All of these fields are optional, but they provide flexibility to capture additional, event-specific information when needed.

Custom Properties Object

Column Name	Data Type	Description	Identifier	Required
`Name`	STRING	The name of the custom property.	Not Primary	Yes
`Namespace`	STRING	The namespace associated with the property.	Not Primary	No
`Value`	STRING	The value assigned to the custom property.	Not Primary	Yes
`PropertyLocation`	STRING	Location where the property is applied, such as ILMD.	Not Primary	No

Certification List Object

Column Name	Data Type	Description	Identifier	Required
`Type`	STRING	The type of certification (e.g., harvest CoC).	Not Primary	No
`Standard`	STRING	The certification standard being referenced.	Not Primary	No
`Agency`	STRING	The agency issuing the certification.	Not Primary	No
`Value`	STRING	The value of the certification (e.g., Yes/No).	Not Primary	No
`Identification`	STRING	Identifier for the certification, if applicable.	Not Primary	No

Important Information About TLC Source

TLC Source offers two ways to identify a location in your data:

Using a TLC Source Reference: Provide a reference, such as a GLN number, to identify a location.
Using TLC Location Details: Provide the full location address information (e.g., country, street address, city, etc.) to specify the location.

Below are two example payload formats, each demonstrating one of these options, along with tables for reference.

TLC Object (Using Reference Details)

Field Name	Data Type	Description	Primary Key	Required
`TlcSource`	OBJECT	Source information for the traceability lot code (TLC).	Not Primary	Yes
`Type`	STRING	Default to "Identifier"	Primary	Yes
`Reference`	STRING	What is the identifier (eg, DUNS, GLN, MSC Etc)	Primary	Yes
`Identifier`	STRING	Actual value of the identification	Primary	Yes

TLC Object (Using Location Details)

Field Name	Data Type	Description	Primary Key	Required
`TlcSource`	OBJECT	Source information for the traceability lot code (TLC).	Not Primary	Yes
`TlcSource.LocationName`	STRING	Name of the TLC location.	Not Primary	Yes
`TlcSource.CompanyName`	STRING	Name of the company associated with the TLC.	Not Primary	Yes
`TlcSource.City`	STRING	City of the source.	Not Primary	No
`TlcSource.State`	STRING	State of the source.	Not Primary	No
`TlcSource.Country`	STRING	Country of the source.	Not Primary	Yes
`TlcSource.Line1`	STRING	Primary address line of the source.	Not Primary	Yes
`TlcSource.Line2`	STRING	Secondary address line of the source.	Not Primary	No
`TlcSource.PostalCode`	STRING	Postal code of the source.	Not Primary	No
`TlcSource.Phone`	STRING	Contact phone number for the source.	Not Primary	Yes
`TlcSource.Type`	STRING	Type of TLC source (e.g., MasterData).	Not Primary	Yes
`TlcSource.GeoCoordinates`	OBJECT	Geographical coordinates of the source.	Not Primary	NO
`GeoCoordinates.Latitude`	DECIMAL	Latitude of the source.	Not Primary	No
`GeoCoordinates.Longitude`	DECIMAL	Longitude of the source.	Not Primary	No

Example Payload All Fields Included

TLC Source RefTLC Location Ref

    {
    "Events": [
        {
            "$type": "observe",
            "Location": {
                "Id": "4567"
            },
            "ProductInstances": [
                {
                    "Quantity": 190.75,
                    "LotSerial": "1990091",
                    "Product": {
                        "Id": "prod_000"
                    },
                    "TraceabilityLotCode": "1234567989",
                    "TlcSource": {
                        "Type": "Identifier",
                        "Reference": "Eg: BAP",
                        "Identifier": "BAP01283"
                    }
                }
            ],
            "Id": "0082932",
            "PurchaseOrder": "1990091",
            "InvoiceNumber": "12314154",
            "BizStep": "urn:epcglobal:cbv:bizstep:commissioning",
            "Disposition": "urn:epcglobal:cbv:disp:active",
            "EventTime": "2024-03-30T13:00:00+00:00",
            "EventTimeZone": "-05:00",
            "CustomProperties": [
                {
                    "Name": "expiry_date",
                    "Namespace": "",
                    "Value": "2024-03-30",
                    "PropertyLocation": ""
                }
            ],
            "CertificationList": [
                {
                    "Type": "urn:gdst:certType:harvestCoC",
                    "Standard": "MSC Chain of Custody",
                    "Agency": "MSC",
                    "Value": "NO",
                    "Identification": "NA"
                }
            ]
        }
    ]
}

    {
    "Events": [
        {
            "$type": "observe",
            "Location": {
                "Id": "4567"
            },
            "ProductInstances": [
                {
                    "Quantity": 190.75,
                    "LotSerial": "1990091",
                    "Product": {
                        "Id": "prod_000"
                    },
                    "TraceabilityLotCode": "1234567989",
                    "TlcSource": {
                        "LocationName": "Test TLC Location",
                        "CompanyName": "Test TLC Company",
                        "City": "Test City",
                        "Country": "Test Country",
                        "Line1": "Address Line 1",
                        "Line2": "Address Line 2",
                        "PostalCode": "987654",
                        "Phone": "+55951254875",
                        "Type": "MasterData",
                        "GeoCoordinates": {
                            "Latitude": 12.345678,
                            "Longitude": 98.765432
                        }
                    }
                }
            ],
            "Id": "0082932",
            "PurchaseOrder": "1990091",
            "InvoiceNumber": "12314154",
            "BizStep": "urn:epcglobal:cbv:bizstep:commissioning",
            "Disposition": "urn:epcglobal:cbv:disp:active",
            "EventTime": "2024-03-30T13:00:00+00:00",
            "EventTimeZone": "-05:00",
            "CustomProperties": [
                {
                    "Name": "expiry_date",
                    "Namespace": "",
                    "Value": "2024-03-30",
                    "PropertyLocation": ""
                }
            ],
            "CertificationList": [
                {
                    "Type": "urn:gdst:certType:harvestCoC",
                    "Standard": "MSC Chain of Custody",
                    "Agency": "MSC",
                    "Value": "NO",
                    "Identification": "NA"
                }
            ]
        }
    ]
}