DocumentsAttach Documents to Events

Attaching Documents to Events

DocumentIds is an optional array of Document IDs returned when documents are uploaded with POST /Integration/Documents. It can be added to Commission, Receive, Ship, Transform, Aggregation, Disaggregation, Observe, and Decommission events. The event is created even if some document IDs cannot be found. DocumentIds is separate from ReferenceDocumentId, the traceability lot code (TLC) reference field.

curl -X POST "https://connect.wholechain.com/Integration/Events" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: example_string" \
  -d '{
  "Events": [
    {
      "$type": "commission",
      "Location": {
        "Id": "processing_001",
        "Details": {
          "TradePartner": {
            "Id": "processor_001",
            "Name": "Processor Name",
            "ConnectionType": "SELF",
            "Duns": "123456789"
          },
          "Name": "Processing Facility",
          "Gln": "9506000140445",
          "Extension": "SomeExtension",
          "DunsPlus4": "1234",
          "ContactInformation": {
            "Name": "Processing Contact",
            "Phone": "+1234567890",
            "Email": "processing@example.com"
          },
          "Address": {
            "City": "Cape Town",
            "State": "Western Cape",
            "Country": "South Africa",
            "AddressLine1": "123 Processing Street",
            "AddressLine2": "Building 2",
            "PostalCode": "8001",
            "GeoCoordinates": {
              "Latitude": -33.9249,
              "Longitude": 18.4241
            }
          }
        }
      },
      "ProductInstances": [
        {
          "Quantity": 190.75,
          "LotSerial": "lot_001",
          "Product": {
            "Id": "rawgoods_001",
            "Details": {
              "ProductIdentifierType": "Lot",
              "Name": "Raw Goods",
              "SimpleUnitOfMeasurement": "Kgm",
              "SharingPolicy": "Open",
              "UnitDescriptor": "Cases",
              "UnitQuantity": 10.5,
              "GTIN": "12345678912343",
              "PLU": "4001",
              "MasterData": [
                {
                  "name": "Gear Type",
                  "namespace": "custom",
                  "value": "GEAR TYPE_VALUE"
                }
              ]
            }
          }
        }
      ],
      "Id": "commission_001_doc_upload",
      "PurchaseOrder": "PO-450001",
      "InvoiceNumber": "INV-12345",
      "DocumentIds": [
        "PO-450001",
        "CERT-MSC-12345"
      ],
      "EventTime": "2026-09-28T13:00:00",
      "EventTimeZone": "-05:00",
      "CustomProperties": [
        {
          "Name": "quality_grade",
          "Namespace": "custom",
          "Value": "A"
        }
      ],
      "CertificationList": [
        {
          "Type": "urn:gdst:certType:harvestCoC",
          "Standard": "MSC Chain of Custody",
          "Agency": "MSC",
          "Value": "YES",
          "Identification": "MSC-C-12345"
        }
      ]
    }
  ]
}'

{
  "message": "Events processed successfully",
  "result": [
    {
      "id": "01a0e7ef-d59a-7edb-93b3-50609aee23c6",
      "externalEventId": "commission_001_doc_upload",
      "type": "Commission",
      "status": "Created",
      "eventDate": "2026-09-28T13:00:00+00:00",
      "productInstances": [],
      "documentsNotAttached": null
    }
  ]
}
POST
/Integration/Events
POST
Base URLstring

Target server for requests. Edit to use your own host.

Content-Typestring
Required

The media type of the request body

Options: application/json
header
X-API-KEYstring
Required

Your Wholechain API key.

Eventsarray
Required
Request Preview
Response
Response will appear here after sending the request


Responses


messagestring
resultarray


Introduction


To attach uploaded documents to an event, list their Document IDs in the event's DocumentIds array. The event is always created, even if some IDs can't be found.


The DocumentIds field


DocumentIds is an optional array of Document IDs, returned when you upload documents with POST /Integration/Documents. It can be added to any event type sent to POST /Integration/Events or POST /Integration/Events/async.


Supported event types: Commission, Receive, Ship, Transform, Aggregation, Disaggregation, Observe and Decommission.


DocumentIds valueResult
["PO-450001"]That document is attached to the event.
["PO-450001", "INV-12345"]Each document found in your account is attached.
Omitted, null or []No documents are attached. The event is processed as before.
"PO-450001" (a string, not an array)The request is rejected with 400. Always send an array, even for one ID.


DocumentIds is separate from ReferenceDocumentId, the traceability lot code (TLC) reference field on events.


Example: commission event with documents


This commission event attaches two documents uploaded earlier: a purchase order (PO-450001) and an MSC certificate (CERT-MSC-12345).


curl -X POST "https://connect.wholechain.com/Integration/Events" \
  -H "X-API-KEY: <api-key>" \
  -H "Content-Type: application/json" \
  -d @commission-event.json



commission-event.json:


{
  "Events": [
    {
      "$type": "commission",
      "Location": {
        "Id": "processing_001",
        "Details": {
          "TradePartner": {
            "Id": "processor_001",
            "Name": "Processor Name",
            "ConnectionType": "SELF",
            "Duns": "123456789"
          },
          "Name": "Processing Facility",
          "Gln": "9506000140445",
          "Extension": "SomeExtension",
          "DunsPlus4": "1234",
          "ContactInformation": {
            "Name": "Processing Contact",
            "Phone": "+1234567890",
            "Email": "processing@example.com"
          },
          "Address": {
            "City": "Cape Town",
            "State": "Western Cape",
            "Country": "South Africa",
            "AddressLine1": "123 Processing Street",
            "AddressLine2": "Building 2",
            "PostalCode": "8001",
            "GeoCoordinates": {
              "Latitude": -33.9249,
              "Longitude": 18.4241
            }
          }
        }
      },
      "ProductInstances": [
        {
          "Quantity": 190.75,
          "LotSerial": "lot_001",
          "Product": {
            "Id": "rawgoods_001",
            "Details": {
              "ProductIdentifierType": "Lot",
              "Name": "Raw Goods",
              "SimpleUnitOfMeasurement": "Kgm",
              "SharingPolicy": "Open",
              "UnitDescriptor": "Cases",
              "UnitQuantity": 10.5,
              "GTIN": "12345678912343",
              "PLU": "4001",
              "MasterData": [
                {
                  "name": "Gear Type",
                  "namespace": "custom",
                  "value": "GEAR TYPE_VALUE"
                }
              ]
            }
          }
        }
      ],
      "Id": "commission_001",
      "PurchaseOrder": "PO-450001",
      "InvoiceNumber": "INV-12345",
      "DocumentIds": [
        "PO-450001",
        "CERT-MSC-12345"
      ],
      "EventTime": "2026-09-28T13:00:00",
      "EventTimeZone": "-05:00",
      "CustomProperties": [
        {
          "Name": "quality_grade",
          "Namespace": "custom",
          "Value": "A"
        }
      ],
      "CertificationList": [
        {
          "Type": "urn:gdst:certType:harvestCoC",
          "Standard": "MSC Chain of Custody",
          "Agency": "MSC",
          "Value": "YES",
          "Identification": "MSC-C-12345"
        }
      ]
    }
  ]
}



Response


Each event result includes documentsNotAttached, which lists any Document IDs that were not attached. It is null when every ID was attached or none was sent.


Some documents not found


If CERT-MSC-12345 had not been uploaded, the event is still created and PO-450001 is still attached. The missing ID is reported:


{
  "message": "Events processed successfully",
  "result": [
    {
      "id": "01a0e7ef-d59a-7edb-93b3-50609aee23c6",
      "externalEventId": "commission_001",
      "type": "Commission",
      "status": "Created",
      "eventDate": "2026-09-28T13:00:00+00:00",
      "productInstances": [ ... ],
      "documentsNotAttached": [
        {
          "documentId": "CERT-MSC-12345",
          "reason": "DocumentNotFound"
        }
      ]
    }
  ]
}



documentsNotAttached fieldDescription
documentIdThe ID from DocumentIds that was not attached.
reasonWhy it was not attached. DocumentNotFound means no document with that ID exists in your account.


When a batch contains several events, each event's result carries its own documentsNotAttached.


Good to know


    

  • Upload each document first and wait for status: Uploaded. Its Document ID can be used in an event immediately after that. See Documents API — Upload.
    • 

  • One document can be attached to any number of events, such as an invoice on both a Ship and a Receive event.
    • 

  • Document IDs are not case-sensitive.
    • 

  • Only documents from the same account as the API key can be attached.
    • 

  • Adding DocumentIds does not change any other required fields or validation for an event.
    • 

Was this page helpful?