CHI-Cargo Business Partner API v1

Overview

The CHI-Cargo Business Partner API connects your systems to the CHI Cargo warehouse platform (the CHICARGO WMS) for Air Export and Air Import handling at Frankfurt and the connected stations. It lets you pre-advise cargo, create master and house air waybills, build consolidations, announce truck arrivals and pickups, request warehouse services, and receive operational status messages back from CHI.

The interface is intentionally message-oriented. Instead of many individual REST resources, a single business message can describe many objects and relationships at once — for example one export MAWB together with all of its HAWBs — and be submitted in a single call.

Why a single endpoint

Many enterprise customers integrate through message-based tooling — classic EDI, or no-code converters such as Lobster _data — where one incoming business message is transformed into one outgoing message. In that world, a classical REST API with many endpoints is hard to consume: pre-advising one export MAWB with 50, 100 or 1000 HAWBs would require a long, ordered sequence of individual calls (create master, create each shipment, attach each shipment, create arrivals, attach again, add services).

This API removes that friction. One message carries everything:

• a data area describing the business objects to create or update, and
• an actions area describing relationships and processing requests (attach, detach, work items, …).

Authentication & transport

The API accepts UTF-8 encoded JSON over HTTPS and supports the POST method only. The API version is part of the URL path.

API key

Authentication uses a per-customer API key transmitted in the x-chi-api-token request header. Keys are issued by CHI Cargo during onboarding. A staging key is provided first; a production key follows once testing on staging is complete. The staging key remains valid for future tests.

POST /v1 HTTP/1.1
Host: api.production.chi-deutschland.cloud 
Content-Type: application/json
x-chi-api-token: <YOUR_API_KEY>

Onboarding checklist

• Provide a technical contact email (and any addresses for update/action notifications).
• Receive your staging API key and complete integration testing on staging.
• (Optional) Provide an HTTPS endpoint to receive status messages.
• Receive your production key and go live.

Message structure

The request body is a single JSON object with two top-level areas, data and actions. Both are optional, and each contains arrays of objects. Unknown properties are rejected (the schema is strict).

{
  "data": {
    "inbound_masters": [],
    "outbound_masters": [],
    "inbound_shipments": [],
    "outbound_shipments": [],
    "inbound_pickups": [],
    "outbound_arrivals": [],
    "inbound_arrivals": []
  },
  "actions": {
    "attach_shipment": [],
    "detach_shipment": [],
    "attach_shipment_to_arrival": [],
    "add_work_item": [],
    "cancel": []
  }
}

Data vs. Actions

The split between data and actions is the core mental model of the API.

Every action must state whether it addresses inbound or outbound data via the process_type field.

Create-or-update behaviour

Objects are matched by their natural keys: mawb_number for masters, hawb_number for shipments, and manifest_number for arrivals and pickups. If an object does not yet exist, it is created on first transmission; on subsequent transmissions it is updated.

Only the fields you send are changed. Consider this outbound master:

{
  "data": {
    "outbound_masters": [
      { "mawb_number": "02012345675", "origin": "FRA", "destination": "JFK", "pieces": 10 }
    ]
  }
}

A later message updates only destination; origin and pieces stay unchanged:

{
  "data": {
    "outbound_masters": [
      { "mawb_number": "02012345675", "destination": "ORD" }
    ]
  }
}

Object model

The model has two object families — inbound (import) and outbound (export) — plus process-specific truck-manifest objects (arrivals and pickups). The table below summarises the data objects and their required keys. For full field-level constraints, see the schema and the interactive API reference.

Actions

Shared field reference

Carrying your own keys with additional_data

The four core data objects — outbound_masters, outbound_shipments, inbound_masters and inbound_shipments — accept an additional_data object: free-form JSON that CHI stores against the object and echoes back unchanged in every related status message (as additional_api_data). It is never interpreted by the warehouse.

This is the recommended way to carry your own business keys alongside CHI's. CHI identifies cargo by mawb_number (master) and hawb_number (house); many platforms key on something else. For example, CargoWise One (WiseTech Global) identifies consolidations and shipments by its Consol ID and Shipment ID rather than by MAWB/HAWB. By placing those IDs in additional_data on the way in, your system receives them back on every status message and can match CHI's updates to its own records automatically — without maintaining a separate MAWB/HAWB cross-reference.

{
  "data": {
    "outbound_masters": [
      { "mawb_number": "02012345675", "additional_data": { "cw1_consol_id": "C00045678" } }
    ],
    "outbound_shipments": [
      { "hawb_number": "FRA10099001", "additional_data": { "cw1_shipment_id": "S00012345" } }
    ]
  }
}

{
  "type": "outbound_shipment_secured",
  "client_slug": "acme-forwarding",
  "shipment": {
    "hawb_number": "FRA10099001",
    "number": "8MY65FN9",
    "additional_api_data": { "cw1_shipment_id": "S00012345" }
  }
}

Air Export · 1 — Transport pre-advice

Announce a truck or delivery arriving at the CHI warehouse, optionally together with the outbound shipments it carries. Use the outbound_arrivals object for the truck manifest and attach shipments with attach_shipment_to_arrival.

{
  "data": {
    "outbound_arrivals": [
      {
        "manifest_number": "FRAT900123",
        "announced_for": "2026-06-14T08:30:00+02:00",
        "station": "FRA",
        "license_plate": "F-CC 4210",
        "trucker": "J. Becker",
        "hauler": "Placeholder Trucking GmbH"
      }
    ],
    "outbound_shipments": [
      { "hawb_number": "FRA10099001", "origin": "FRA", "destination": "JFK", "pieces": 4, "weight": 612.0 },
      { "hawb_number": "FRA10099002", "origin": "FRA", "destination": "ORD", "pieces": 7, "weight": 568.5 }
    ]
  },
  "actions": {
    "attach_shipment_to_arrival": [
      { "process_type": "outbound", "hawb_number": "FRA10099001", "manifest_number": "FRAT900123" },
      { "process_type": "outbound", "hawb_number": "FRA10099002", "manifest_number": "FRAT900123" }
    ]
  }
}

Air Export · 2 — Shipment pre-advice

Announce outbound shipments expected at the warehouse, independently of a truck manifest. This is the most common building block — send the HAWB-level detail and let later messages add the MAWB and attachments.

{
  "data": {
    "outbound_shipments": [
      {
        "hawb_number": "FRA10099001",
        "origin": "FRA",
        "destination": "JFK",
        "pieces": 4,
        "weight": 612.0,
        "consigner": "ACME INSTRUMENTS GMBH",
        "consignee": "ACME US INC",
        "content": "Measuring instruments",
        "hazard_class": "nonhazardous",
        "prior_party_secured": false,
        "measurements": [
          { "length": 120, "width": 80, "height": 95, "weight": 153.0 }
        ],
        "additional_data": { "cargowise_shipment_id": "S00012345" }
      }
    ]
  }
}

Air Export · 3 — MAWB / consolidation creation

When the export MAWB is known, create or update an outbound_master. A master can carry many HAWBs (outbound shipments). Create the master and the shipments in the same message, then attach them (see the next use case).

{
  "data": {
    "outbound_masters": [
      {
        "mawb_number": "02012345675",
        "consolidation_type": "consol",
        "origin": "FRA",
        "destination": "JFK",
        "pieces": 11,
        "weight": 1180.5,
        "lat": "2026-06-14T18:00:00+02:00",
        "alt_refs": "CONSOL-JFK-0614"
      }
    ]
  }
}

Air Export · 4 — Attach HAWBs to a MAWB

Link outbound shipments to an outbound master with the attach_shipment action. Provide process_type: "outbound", the hawb_number, and the target mawb_number. One message can attach hundreds of HAWBs.

{
  "data": {
    "outbound_masters": [
      { "mawb_number": "02012345675", "consolidation_type": "consol", "origin": "FRA", "destination": "JFK", "pieces": 11, "weight": 1180.5 }
    ],
    "outbound_shipments": [
      { "hawb_number": "FRA10099001", "pieces": 4, "weight": 612.0 },
      { "hawb_number": "FRA10099002", "pieces": 7, "weight": 568.5 }
    ]
  },
  "actions": {
    "attach_shipment": [
      { "process_type": "outbound", "hawb_number": "FRA10099001", "mawb_number": "02012345675" },
      { "process_type": "outbound", "hawb_number": "FRA10099002", "mawb_number": "02012345675" }
    ]
  }
}

Air Export · 5 — Update shipment or master data

Because the API is create-or-update, revised data is sent the same way as the original. Re-transmit the object with its key and only the changed fields. This is ideal for corrected pre-advices.

{
  "data": {
    "outbound_masters": [
      { "mawb_number": "02012345675", "destination": "ORD" }
    ],
    "outbound_shipments": [
      { "hawb_number": "FRA10099002", "weight": 575.0 }
    ]
  }
}

Air Export · 6 — Special service / work item

Request a warehouse service on a shipment or master with add_work_item. For outbound HAWB work items the allowed workable values are secure, palletize, measure, neutralize, label_hawb, shrink, weigh, photograph, other. For masters (and inbound), secure and label_hawb are not available.

{
  "actions": {
    "add_work_item": [
      {
        "process_type": "outbound",
        "hawb_number": "FRA10099001",
        "workable": "photograph",
        "instructions": "Please take photos of all sides and from the top.",
        "client_reference": "JOB-2026-0614-07"
      }
    ]
  }
}

Air Export · 7 — Local Frankfurt export without HAWB

In local Frankfurt export, outbound records sometimes exist before a HAWB number is known. The API allows creating an outbound_shipment with only alt_refs (no hawb_number). Later, when the HAWB exists, a label_hawb work item links the pre-records to the HAWB using their alt_refs.

{
  "data": {
    "outbound_shipments": [
      { "alt_refs": "WH-REF-77001", "origin": "FRA", "destination": "ORD", "pieces": 2, "weight": 95.0 }
    ]
  }
}

{
  "actions": {
    "add_work_item": [
      {
        "process_type": "outbound",
        "hawb_number": "FRA10099050",
        "workable": "label_hawb",
        "instructions": "Label and link the warehouse pre-record(s) to this HAWB.",
        "attach_shipments": [
          { "alt_refs": "WH-REF-77001" }
        ]
      }
    ]
  }
}

Air Import · 1 — MAWB / shipment pre-advice

For import, the expected MAWBs are usually known in advance. Pre-advise an inbound_master and its inbound_shipments. The master can carry total_amount_of_parts (number of ULDs) and an eta.

{
  "data": {
    "inbound_masters": [
      {
        "mawb_number": "02012345675",
        "consolidation_type": "consol",
        "origin": "JFK",
        "destination": "FRA",
        "pieces": 11,
        "weight": 1180.5,
        "total_amount_of_parts": 2,
        "eta": "2026-06-14T06:30:00+02:00"
      }
    ],
    "inbound_shipments": [
      { "hawb_number": "FRA10088001", "pieces": 4, "weight": 612.0, "consignee": "ACME EUROPE GMBH" },
      { "hawb_number": "FRA10088002", "pieces": 7, "weight": 568.5, "consignee": "ACME EUROPE GMBH" }
    ]
  }
}

Air Import · 2 — Attach shipments to a master

Attach inbound house shipments to an inbound master with attach_shipment and process_type: "inbound".

{
  "actions": {
    "attach_shipment": [
      { "process_type": "inbound", "hawb_number": "FRA10088001", "mawb_number": "02012345675" },
      { "process_type": "inbound", "hawb_number": "FRA10088002", "mawb_number": "02012345675" }
    ]
  }
}

Air Import · 3 — Inbound master AWB broken-down status

When cargo is physically checked and broken down in the warehouse, CHI sends an inbound_master_awb_brokendown status message to your endpoint. It reports what was actually checked in per HAWB, any damage, and links to break-down photos and the report PDF.

{
  "id": "f19bb8a3-d64b-49b0-8df8-76b6cc2fe69b",
  "type": "inbound_master_awb_brokendown",
  "client_slug": "acme-forwarding",
  "brokendown_at": "2026-06-12T18:12:31+02:00",
  "master": { "number": "02012345675", "consolidation_type": "consol" },
  "shipments": [
    {
      "number": "NPPUCEY5",
      "hawb_number": "FRA10088001",
      "pieces": 4,
      "pieces_checkedin": 4,
      "weight": "612.0",
      "damaged_count": 1,
      "damage_types": ["dented"],
      "shipment_image": [
        { "image_url": "https://files.chi-cargo.example/inbound/shipment/NPPUCEY5/01.jpg" }
      ]
    }
  ],
  "breakdown_pdf_url": "https://files.chi-cargo.example/inbound/masters/02012345675/breakdown_report.pdf"
}

Air Import · 4 — Create an inbound pickup

When cargo is planned for onward transport to local stations, create an inbound_pickup. The manifest_number is the primary identifier and should match the value used in later pickup status messages.

{
  "data": {
    "inbound_pickups": [
      {
        "manifest_number": "FRAT900777",
        "announced_for": "2026-06-15T14:00:00+02:00",
        "station": "MUC",
        "license_plate": "F-CC 4210",
        "trucker": "J. Becker",
        "hauler": "Placeholder Trucking GmbH"
      }
    ]
  }
}

Air Import · 5 — Attach shipments to a pickup

Attach the inbound shipments to be collected to the pickup manifest with attach_shipment, providing the manifest_number instead of a mawb_number.

{
  "data": {
    "inbound_pickups": [
      { "manifest_number": "FRAT900777", "announced_for": "2026-06-15T14:00:00+02:00", "station": "MUC", "hauler": "Placeholder Trucking GmbH" }
    ]
  },
  "actions": {
    "attach_shipment": [
      { "process_type": "inbound", "hawb_number": "FRA10088001", "manifest_number": "FRAT900777" },
      { "process_type": "inbound", "hawb_number": "FRA10088002", "manifest_number": "FRAT900777" }
    ]
  }
}

Air Import · 6 — Update pickup or shipment data

As with export, send revised pickup or shipment data using the same objects and keys. Only changed fields are applied.

{
  "data": {
    "inbound_pickups": [
      { "manifest_number": "FRAT900777", "announced_for": "2026-06-15T16:30:00+02:00", "trucker": "M. Schulz" }
    ]
  }
}

Status messages

Beyond accepting requests, CHI can push status messages to a customer HTTPS endpoint as cargo moves through the warehouse. If you want to receive them, provide your endpoint during onboarding.

Common envelope

Every status message shares a common envelope:

Export status messages

{
  "id": "8c4f0b02-aaa2-4324-88c1-1416c241f88a",
  "type": "outbound_shipment_secured",
  "client_slug": "acme-forwarding",
  "shipment": { "number": "8MY65FN9", "hawb_number": "FRA10099001", "origin": "FRA", "pieces": 4, "pieces_secured": 4 },
  "secured": [
    { "secured_at": "2026-06-12T17:32:59+02:00", "secured_by": "Placeholder Agent", "securing_method": "SPX by EDD", "amount": 4, "rac_number": "DE/RA/00000-01" }
  ],
  "spx_pdf_url": "https://files.chi-cargo.example/outbound/shipments/8MY65FN9/spx_report.pdf"
}

{
  "id": "99cf8cbb-4a19-4baa-b046-88e19ace4c75",
  "type": "outbound_arrival_checkedin",
  "client_slug": "acme-forwarding",
  "arrival": {
    "number": "33530099",
    "manifest_number": "FRAT900123",
    "warehouse": "557",
    "arrival_time": "2026-06-12 15:41:15 +0200",
    "license_plate": "F-CC 4210",
    "securing_status": "SECURE (RegB (RA))",
    "pieces_total": 4,
    "pieces_checkedin_total": 4
  },
  "shipments": [
    {
      "number": "JK3QXHE2", "hawb_number": "FRA10099001", "destination": "JFK",
      "pieces": 4, "pieces_checkedin": 4, "pieces_damaged": 0, "weight": "612.0",
      "damage_severity": "undamaged", "checkedin_at": "2026-06-12 16:06:20 +0200", "images_of_damages": []
    }
  ],
  "arrival_confirmation_pdf": "https://files.chi-cargo.example/outbound/arrivals/33530099/arrival_confirmation_report.pdf"
}

{
  "id": "6f079c53-5553-4481-8683-26d727c1f04d",
  "type": "darc_alert",
  "client_slug": "acme-forwarding",
  "darc_alert": "dark",
  "previous_darc_alert": "no_lock",
  "shipment": { "hawb_number": "FRA10099001", "pieces": 3 }
}

Import status messages

{
  "id": "5e699bc0-9d24-4d42-8a43-d2a9b9a0b08e",
  "type": "inbound_pickup_completed",
  "client_slug": "acme-forwarding",
  "completed_at": "2026-06-12T18:20:30+02:00",
  "pickup": { "number": "58924209", "manifest_number": "FRAT900777" },
  "shipments": [
    {
      "number": "1W4YDYT2", "hawb_number": "FRA10088001",
      "pieces": 4, "pieces_checkedin": 4, "pieces_checkedout": 4, "weight": "612.0",
      "master": { "number": "02012345675", "consolidation_type": "consol" }
    }
  ]
}

Universal status messages

{
  "id": "0a0014dd-9205-4fe9-ba28-05be3f325231",
  "type": "work_item_done",
  "client_slug": "acme-forwarding",
  "completed_at": "2026-06-12T02:15:00+02:00",
  "work_item": {
    "number": "60240047",
    "parent_type": "Outbound::Shipment",
    "workable": "label_hawb",
    "client_reference": "JOB-2026-0614-01"
  },
  "outbound_shipment": { "hawb_number": "FRA10099050" }
}

Sequence diagrams

The diagrams below show the main end-to-end flows. Actors: Customer System, EDI / Converter, Business Partner API v1, CHICARGO WMS, CHI Operations, and the Customer Notification Endpoint.

Export — transport pre-advice

Export — MAWB with HAWB attach flow

Export — local shipment without HAWB, later labeling

Import — MAWB pre-advice and broken-down status

Import — pickup creation and attach flow

Customer request + CHI status lifecycle

Errors & validation

A syntactically valid, schema-conformant message is accepted with 202 and a process id. The id can be used to correlate the request with later status messages.

{
  "message": "Unprocessable Entity",
  "error": "JSON validation failed:\n'mawb_number' is a required property",
  "id": "9519adbe-cd08-411b-a1b5-754c92aa1cbd"
}

Schema & OpenAPI 3.1

The API is defined canonically as a JSON Schema (draft-07). An OpenAPI 3.1 document is also provided as an additional artifact — OpenAPI 3.1 aligns with modern JSON Schema, so the full model (including anyOf/oneOf/allOf composition) is represented faithfully while keeping the single POST /v1 endpoint.

Support & contact

For onboarding, API keys, status-message endpoints, or integration questions, contact Enterprise Integration. Please include your client_slug and, where relevant, the process id from the API response.

Changelog & versioning

The API version is part of the URL path (/v1). Backwards-compatible additions (new optional fields, new status types) are made within v1. Breaking changes would be introduced under a new path version.