# Lookup for shipments

This endpoint looks up shipments. The result should be limit by using search criterias in the request body. For a complete list of search criteria see the ShipmentIdentifier enumeration below. Depending on the search criteria you will receive zero up to n shipments.

Endpoint: POST /cargosoft/shipment/lookup
Version: 2025.1
Security: JavaWebToken

## Query parameters:

  - `page_no` (integer)
    The page number for pagination.

  - `page_size` (integer)
    The page size for pagination.

  - `order_by` (array)
    The order by for ordering API results sending back as response.
    Enum: "ID", "HBL", "MBL", "FILENUMBER", "SHIPMENT_ID", "ADDRESS_REFERENCE", "DIRECTION", "MODE_OF_TRANSPORT", "MONTH_OF_SERVICE", "CLIENT", "CREATION_DATE", "RUNNING_SEQUENCE_NUMBER", "SHIPMENT_NUMBER", "CUSTOMER_ADDRESS_TYPE", "CUSTOMER_ADDRESS_NUMBER", "SHIPMENT_CLOSED", "LAST_MODIFIED_DATE", "LAST_MODIFIED_TIME"

  - `order_mode` (array)
    The order mode for ordering API results sending back as response.
    Enum: "ASC", "DESC"

## Request fields (application/json):

  - `key` (string)
    Identifier key. For instance a ShipmentIdentifier
    Enum: "ID", "HBL", "MBL", "FILENUMBER", "SHIPMENT_ID", "ADDRESS_REFERENCE", "DIRECTION", "MODE_OF_TRANSPORT", "MONTH_OF_SERVICE", "CLIENT", "CREATION_DATE", "RUNNING_SEQUENCE_NUMBER", "SHIPMENT_NUMBER", "CUSTOMER_ADDRESS_TYPE", "CUSTOMER_ADDRESS_NUMBER", "SHIPMENT_CLOSED", "LAST_MODIFIED_DATE", "LAST_MODIFIED_TIME"

  - `match_mode` (string)
    The match mode.
    Enum: "EQUALS", "CONTAINS", "IN", "OR", "GT", "LT", "GE", "LE"

## Response 200 fields (application/json):

  - `id` (integer)
    Unique identifier of this shipment.

  - `client` (string)
    The CargoSoft client.

  - `direction` (string)
    The shipment direction. Possible values are [I, E]. I = import shipments, E = export shipments.

  - `office` (string)
    The shipment office.

  - `employees` (object)
    Employee login names, who are working on this shipment.

  - `employees.closed_employee_matchcode` (string)
    Employee login, who closed the shipment.

  - `employees.last_modified_employee_matchcode` (string)
    Employee login, who last modified the shipment.

  - `employees.created_employee_matchcode` (string)
    Employee login, who created the shipment.

  - `employees.responsible_employee_matchcode` (string)
    Employee login, who is responsible for the shipment

  - `memos` (array)
    Memos associated with this shipment.

  - `memos.id` (integer)

  - `memos.client` (string)

  - `memos.memo` (string)

  - `memos.shipment_number` (string)

  - `memos.running_number` (integer)

  - `aes` (array)
    Automated Export System (AES) proposals.

  - `aes.mrn` (string)
    The Movement Reference Number assigned to this customs declaration.

  - `aes.shipment_number` (string)
    The CargoSoft shipment number of the shipment.

  - `aes.running_number` (integer)
    Proposal counter

  - `shipment_number` (string)
    The CargoSoft shipment number of this shipment.

  - `master_reference` (string)
    The shipment master bl number.

  - `house_reference` (string)
    The shipment house bl number.

  - `bl_type` (string)
    Bl type of the shipment.

  - `mode_of_transport` (string)
    Transport mode of the shipment. Possible values are [SEA, AIR, RD, RL]

  - `month_of_service` (string)
    The month in which freight services are provided, used for billing and reporting.

  - `total_packages` (integer)
    The total number of packages of the shipment.

  - `total_gross_weight` (number)
    The gross weight of the shipment.

  - `self_pickup` (string)
    Indicates whether the recipient will pick up the goods directly from the warehouse or terminal.

  - `self_delivery` (string)
    Indicates whether the sender will deliver the goods to the carrier or warehouse by themselves.

  - `goods` (array)
    The description of the transported goods.

  - `goods.measurements` (array)
    A list of measurements related to the goods, such as dimensions or additional weights.

  - `goods.measurements.weight` (number)

  - `goods.measurements.length` (integer)

  - `goods.measurements.width` (integer)

  - `goods.measurements.height` (integer)

  - `goods.measurements.quantity` (integer)

  - `goods.measurements.goods_id` (integer)

  - `goods.measurements.shipment_number` (string)
    The CargoSoft shipment number of the shipment. This number may unique in combination of the client property.

  - `goods.measurements.weight_unit` (string)

  - `goods.measurements.volume` (number)

  - `goods.measurements.volume_unit` (string)

  - `goods.measurements.measurement_unit` (string)

  - `goods.customs` (array)
    Customs-related information for processing the goods.

  - `goods.customs.invoice_number` (string)

  - `goods.customs.invoice_date_time` (string)

  - `goods.customs.amount` (number)

  - `goods.customs.currency_matchcode` (string)

  - `goods.customs.delivery_note` (string)

  - `goods.customs.delivery_date_time` (string)

  - `goods.mrns` (array)
    Movement Reference Numbers (MRNs) associated with customs declarations for the goods.

  - `goods.mrns.mrn` (string)

  - `goods.subgoods` (array)
    Sub-goods or components that form part of the overall goods in the shipment.

  - `goods.dangerousGoods` (array)
    Details of dangerous goods information of this good.

  - `goods.dangerousGoods.id` (integer)
    The id of this dangerous goods.

  - `goods.dangerousGoods.dangerous_good_legislation` (string)
    The dangerous goods legislation. Possible values are IMDG, ADR, or RID.

  - `goods.dangerousGoods.classification_code` (string)
    Classification code of this dangerous goods. For instance the imdg code.

  - `goods.dangerousGoods.un_number` (string)
    Dangerous goods UN-Number.

  - `goods.dangerousGoods.release` (string)
    Dangerous goods release.

  - `goods.dangerousGoods.label_1` (string)
    Dangerous goods label.

  - `goods.dangerousGoods.label_2` (string)
    Dangerous goods label.

  - `goods.dangerousGoods.label_3` (string)
    Dangerous goods label.

  - `goods.dangerousGoods.label_4` (string)
    Dangerous goods label.

  - `goods.dangerousGoods.site` (string)
    Dangerous goods site.

  - `goods.dangerousGoods.flashpoint` (string)
    Flashpoint of this dangerous goods.

  - `goods.dangerousGoods.flashpoint_unit` (string)
    The unit of the flashpoint. Possible values are C or F.

  - `goods.dangerousGoods.ems_number_1` (string)
    EMS number.

  - `goods.dangerousGoods.ems_number_2` (string)
    EMS number.

  - `goods.dangerousGoods.mfag_number_1` (string)
    MFAG number.

  - `goods.dangerousGoods.mfag_number_2` (string)
    MFAG number.

  - `goods.dangerousGoods.remarks` (array)
    Dangerous goods remarks.

  - `goods.dangerousGoods.authorisation_number` (string)
    Dangerous goods authorisation number.

  - `goods.dangerousGoods.packaging_group` (string)
    Packaging group of this dangerous goods.

  - `goods.dangerousGoods.technical_name_1` (string)
    Technical name of this dangerous goods.

  - `goods.dangerousGoods.technical_name_2` (string)
    Technical name of this dangerous goods.

  - `goods.dangerousGoods.causing_substance_1` (string)
    Causing substance of this dangerous goods.

  - `goods.dangerousGoods.causing_substance_2` (string)
    Causing substance of this dangerous goods.

  - `goods.dangerousGoods.issuer` (string)
    Issuer of this dangerous goods.

  - `goods.dangerousGoods.net_weight` (number)
    Net weight of this dangerous goods.

  - `goods.dangerousGoods.weight_unit` (string)
    Weight unit of the net and gross weight.

  - `goods.dangerousGoods.gross_weight` (number)
    Gross weight of this dangerous goods.

  - `goods.dangerousGoods.contact` (object)
    Contact information of this dangerous goods.

  - `goods.dangerousGoods.contact.name` (string)

  - `goods.dangerousGoods.contact.phone_number` (string)

  - `goods.dangerousGoods.contact.fax_number` (string)

  - `goods.dangerousGoods.contact.email` (string)

  - `goods.id` (integer)
    Unique identifier for the goods description in the shipment.

  - `goods.identifier` (string)

  - `goods.counter` (integer)
    Counter used to track and number individual goods description lines.

  - `goods.level` (integer)
    The hierarchical level of the goods within the goods description.

  - `goods.level_number` (integer)
    Internal technical number, to order the goods description lines within the CargoSoft TMS.

  - `goods.marks` (array)
    Marks or labels associated with the goods for identification purposes.

  - `goods.quantity` (integer)
    The quantity of goods described in this entry.

  - `goods.packaging_matchcode` (string)
    The matchcode representing the type of packaging used for this good.

  - `goods.commodity_matchcode` (string)
    The matchcode representing the type of commodity being shipped.

  - `goods.description` (array)
    A list providing detailed descriptions of the goods.

  - `goods.weight` (number)
    The total weight of the goods in this shipment.

  - `goods.colli` (boolean)
    Indicates whether this goods description line is a colli line.

  - `goods.colli_number` (integer)

  - `goods.volume` (number)
    The total volume.

  - `goods.volume_unit` (string)
    The unit of measurement used for the volume of the goods.

  - `goods.additional_mark` (boolean)

  - `goods.net_weight` (number)
    The net weight of the goods, excluding packaging.

  - `goods.weight_unit` (string)
    The unit of measurement for the weight of the goods.

  - `goods.chargable_weight` (number)
    The chargeable weight used for calculating shipping costs, either based on actual or volumetric weight.

  - `goods.container_number` (string)
    The container number in which the goods are stored for shipment.

  - `goods.hs_codes` (array)
    List of Harmonized System (HS) codes for the goods in the shipment.

  - `goods.hs_codes.goodId` (integer)

  - `goods.hs_codes.hsCode` (string)

  - `addresses` (array)
    The contact details of involved parties.

  - `addresses.qualifier` (string)
    Enum: "AGT", "CAR", "CNE", "CUS", "DEL", "DEP", "DL1", "DL2", "INV", "MIS", "NFY", "PUP", "SHP", "TRA", "FACILIATOR", "AGENT", "CARRIER"

  - `addresses.address_type` (string)
    The CargoSoft address type.

  - `addresses.address_number` (integer)
    The CargoSoft address number.

  - `addresses.printed_address` (object)
    The address exactly as entered in the shipment record.

  - `addresses.printed_address.line_1` (string)

  - `addresses.printed_address.line_2` (string)

  - `addresses.printed_address.line_3` (string)

  - `addresses.printed_address.line_4` (string)

  - `addresses.printed_address.line_5` (string)

  - `addresses.street` (string)
    The street address of the party involved in the shipment.

  - `addresses.postal_code` (string)
    The postal code of the address.

  - `addresses.city` (string)
    The city of the address.

  - `addresses.state` (string)
    The state or region of the address.

  - `addresses.country_matchcode` (string)
    The CargoSoft matchcode for the country of the address.

  - `addresses.un_location_code` (string)
    The UN location code for the address.

  - `addresses.contact` (object)
    The contact details of the person or entity at the specified address.

  - `addresses.references` (array)
    Optional references related to the address, such as additional identifiers or notes.

  - `addresses.references.matchcode` (string, required)

  - `addresses.references.value` (string, required)

  - `addresses.references.date_and_time` (object)

  - `addresses.references.date_and_time.date` (string)
    The date.

  - `addresses.references.date_and_time.time` (object)
    The time.

  - `addresses.references.date_and_time.time.hour` (integer)

  - `addresses.references.date_and_time.time.minute` (integer)

  - `addresses.references.date_and_time.time.second` (integer)

  - `addresses.references.date_and_time.time.nano` (integer)

  - `addresses.references.date_and_time.zone_offset` (object)
    The UTC time zone of this date and time.

  - `addresses.references.date_and_time.zone_offset.totalSeconds` (integer)

  - `addresses.references.date_and_time.zone_offset.rules` (object)

  - `addresses.references.date_and_time.zone_offset.rules.fixedOffset` (boolean)

  - `addresses.references.date_and_time.zone_offset.rules.transitions` (array)

  - `addresses.references.date_and_time.zone_offset.rules.transitions.offsetBefore` (object)

  - `addresses.references.date_and_time.zone_offset.rules.transitions.offsetAfter` (object)

  - `addresses.references.date_and_time.zone_offset.rules.transitions.overlap` (boolean)

  - `addresses.references.date_and_time.zone_offset.rules.transitions.instant` (string)

  - `addresses.references.date_and_time.zone_offset.rules.transitions.duration` (object)

  - `addresses.references.date_and_time.zone_offset.rules.transitions.duration.seconds` (integer)

  - `addresses.references.date_and_time.zone_offset.rules.transitions.duration.zero` (boolean)

  - `addresses.references.date_and_time.zone_offset.rules.transitions.duration.negative` (boolean)

  - `addresses.references.date_and_time.zone_offset.rules.transitions.duration.positive` (boolean)

  - `addresses.references.date_and_time.zone_offset.rules.transitions.duration.units` (array)

  - `addresses.references.date_and_time.zone_offset.rules.transitions.duration.units.durationEstimated` (boolean)

  - `addresses.references.date_and_time.zone_offset.rules.transitions.duration.units.timeBased` (boolean)

  - `addresses.references.date_and_time.zone_offset.rules.transitions.duration.units.dateBased` (boolean)

  - `addresses.references.date_and_time.zone_offset.rules.transitions.gap` (boolean)

  - `addresses.references.date_and_time.zone_offset.rules.transitions.dateTimeAfter` (string)

  - `addresses.references.date_and_time.zone_offset.rules.transitions.dateTimeBefore` (string)

  - `addresses.references.date_and_time.zone_offset.rules.transitionRules` (array)

  - `addresses.references.date_and_time.zone_offset.rules.transitionRules.month` (string)
    Enum: "JANUARY", "FEBRUARY", "MARCH", "APRIL", "MAY", "JUNE", "JULY", "AUGUST", "SEPTEMBER", "OCTOBER", "NOVEMBER", "DECEMBER"

  - `addresses.references.date_and_time.zone_offset.rules.transitionRules.timeDefinition` (string)
    Enum: "UTC", "WALL", "STANDARD"

  - `addresses.references.date_and_time.zone_offset.rules.transitionRules.standardOffset` (object)

  - `addresses.references.date_and_time.zone_offset.rules.transitionRules.dayOfWeek` (string)
    Enum: "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY"

  - `addresses.references.date_and_time.zone_offset.rules.transitionRules.dayOfMonthIndicator` (integer)

  - `addresses.references.date_and_time.zone_offset.rules.transitionRules.localTime` (object)

  - `addresses.references.date_and_time.zone_offset.rules.transitionRules.midnightEndOfDay` (boolean)

  - `pre_carriage` (object)
    The transport of goods from the origin to the main carrier, preceding the main shipment.

  - `pre_carriage.carriage_legs` (array)
    A specific segment of the overall transport journey

  - `pre_carriage.carriage_legs.origin` (object)
    The origin of this leg. This object contains several information about the location and its dates and times.

  - `pre_carriage.carriage_legs.origin.location` (object)
    The location of this leg.

  - `pre_carriage.carriage_legs.origin.location.codes` (array)
    A list of all location codes and their types of this location.

  - `pre_carriage.carriage_legs.origin.location.codes.type` (string, required)
    The type of this location code.
    Enum: "CARGOSOFT", "UNLOC", "IATA", "FOREIGN", "POSTAL_CODE", "UN_COUNTRY"

  - `pre_carriage.carriage_legs.origin.location.codes.code` (string, required)
    The code of this location.

  - `pre_carriage.carriage_legs.origin.location.name` (string)
    The written name of this location.

  - `pre_carriage.carriage_legs.origin.location.latitude` (number)
    The latitude of this location.

  - `pre_carriage.carriage_legs.origin.location.longitude` (number)
    The longitude of this location.

  - `pre_carriage.carriage_legs.origin.estimated_datetime` (object)
    The local estimated date and time related to the location.

  - `pre_carriage.carriage_legs.origin.actual_datetime` (object)
    The local actual date and time related to the location.

  - `pre_carriage.carriage_legs.origin.revised_datetime` (object)
    The local revised date and time related to the location.

  - `pre_carriage.carriage_legs.origin.estimated_datetime_until` (object)

  - `pre_carriage.carriage_legs.destination` (object)
    The destination of this leg. This object contains several information about the location and its dates and times.

  - `pre_carriage.carriage_legs.leg_no` (integer)
    The number for the correct order of the transport legs. Important if more than one leg is entered for the shipment.

  - `pre_carriage.carriage_legs.mot` (string, required)

  - `main_carriage` (object)
    The primary transportation stage of the shipment

  - `post_carriage` (object)
    The transportation of goods from the main carrier to the final destination after the main shipment.

  - `events` (array)
    Shipment events with location, date and time.

  - `events.event` (string)
    The event code of this shipment event. The code describes the functional meaning of the event date and time.
    Enum: "DISPATCH", "PICKUP", "WAREHOUSE", "POL_ARRIVAL", "LOADING_START", "LOADING_END", "POL_DEPARTURE", "POD_ARRIVAL", "CLEARANCE_START", "CLEARANCE_END", "CUSTOMS_CLEARANCE", "AVAILABLE", "ACCEPTANCE", "FINAL_DESTINATION", "TRANSSHIPMENT", "GATE_OUT", "POD_DEPARTURE", "CUSTOMS_RELEASE", "DELIVERY_DATE", "POL_DEPARTURE_REVISED", "POD_ARRIVAL_REVISED", "TRANSSHIPMENT_ARRIVAL", "TRANSSHIPMENT_DEPARTURE", "DIFF_BL_DATE", "VGM_CLOSING"

  - `events.type` (string)
    The event type of this shipment event. The event type describes if the event date and time is estimated or actual.
    Enum: "ACTUAL", "ESTIMATED"

  - `events.shipment_id` (integer)
    The id of the Shipment.

  - `events.date_time` (object)
    The date and time of this event.

  - `events.date_time.until` (object)
    Optional time range. Only for Event types: PICKUP and FINAL_DESTINATION

  - `events.location` (object)
    The location of this event.

  - `terms_of_delivery_matchcode` (string)
    The agreed conditions under which goods are delivered (matchcode).

  - `terms_of_delivery_name` (string)
    The agreed conditions under which goods are delivered (full condition).

  - `total_volume` (number)
    The combined physical space occupied by the goods, measured in cubic meters.

  - `chargeableWeight` (number)
    The weight used to calculate shipping costs, based on either the actual weight or the volumetric weight, whichever is higher.

  - `original_shipment_number` (string)

  - `foreign_id` (string)
    Shipment number used by a foreign system.

  - `movement_matchcode` (string)

  - `insurance` (object)
    Informations related to the shipment insurance

  - `insurance.waiver_customer` (boolean)

  - `insurance.insurable_value` (number)

  - `insurance.insurable_value_currency_matchcode` (string)

  - `insurance.value_of_goods` (number)

  - `insurance.value_of_goods_currency_matchcode` (string)

  - `insurance.insurance_text` (string)

  - `insurance.transport_insurance` (boolean)

  - `insurance.insurance_type` (string)

  - `insurance.insurer` (object)

  - `credit_data` (object)
    Information related to payment terms

  - `credit_data.lc_number` (string)
    The reference number for a Letter of Credit.

  - `credit_data.latest_shipment_date` (string)

  - `credit_data.lc_expiry` (string)
    The date when a Letter of Credit becomes invalid.

  - `customs_data` (object)
    Informations related to customs processing

  - `customs_data.custom_clearance_date` (string)
    The date when goods are officially cleared by customs

  - `customs_data.clearance` (string)

  - `customs_data.book` (string)
    The customs ledger used to record the official clearance of goods

  - `containers` (array)
    Containers on this shipment.

  - `containers.containerAddresses` (array)
    List of container addresses. This list contains the three fixed addresses on the container. In addition, further dynamic addresses can be defined and entered on the container.

  - `containers.containerAddresses.id` (integer)
    The id of the dynamic container address. The three fixed container addresses have no id.

  - `containers.containerAddresses.qualifier` (string)
    The role of this address. For the three fixed addresses are the following roles dedined [DELIVERER, PICKUP, REDILIVERY]. The roles of the dynamic addresses do not have a fixed qualifier.

  - `containers.containerAddresses.street` (string)
    The street of this address.

  - `containers.containerAddresses.city` (string)
    The city name of this address.

  - `containers.containerAddresses.order` (integer)
    Sequential numbering of the addresses. This is important for the order of the addresses.

  - `containers.containerAddresses.references` (array)
    References of this address.

  - `containers.containerAddresses.postal_code` (string)
    The postal code of this address.

  - `containers.containerAddresses.country_matchcode` (string)
    The country code of this address.

  - `containers.containerAddresses.un_location_code` (string)
    The city un location code of this address.

  - `containers.containerAddresses.from_date_and_time` (object)
    From date and time for an appointment.

  - `containers.containerAddresses.to_date_and_time` (object)
    To date and time for an appointment.

  - `containers.containerAddresses.contact` (object)
    Additional contact information.

  - `containers.id` (integer)
    The unique identifier of this Container.

  - `containers.good_id` (integer)
    The goods id references the associated good element.

  - `containers.client` (string)
    The CargoSoft client

  - `containers.shipment_number` (string)
    The CargoSoft shipment number, this container belongs to.

  - `containers.container_number` (string)
    The container number

  - `containers.seal_number1` (string)
    The first seal number.

  - `containers.seal_number2` (string)
    The second seal number

  - `containers.seal_number3` (string)
    The third seal number

  - `containers.container_iso_code` (string)
    The ISO code representing the type and size of this container.

  - `containers.shippers_own` (boolean)
    Indicates whether the container is owned by the shipper rather than the carrier.

  - `custom_fields` (array)
    Various customer specific values.

  - `custom_fields.id` (integer)
    Unique identifier for this custom field.

  - `custom_fields.value` (string)
    The value for this custom field.

  - `custom_fields.shipment_number` (string)
    The CargoSoft shipment number

  - `custom_fields.running_number` (integer)
    Internal counter.

  - `last_modified_date_time` (string)
    Timestamp of the last modification of the shipment.

  - `created_date_time` (string)
    Timestamp of the creation of the shipment.

  - `order_date_time` (string)
    The order date.

  - `project_matchcode` (string)
    Customizable field used to classify or categorize the order based on business-specific criteria.

  - `depot_matchcode` (string)

  - `shipment_closed` (boolean)

  - `booking_party_address_qualifier` (string)
    The address qualifier of the booking party of the shipment.