Create a Shipment to track Vessel

Create a shipment to track vessel by using an API endpoint to add the shipment to project44's network and send tracking information about the shipment.

Requirements

Have the following information:

1. Shipment Identifier

Field: CUSTOMER_REFERENCE
Purpose: A reference identifier provided by the customer to track their shipment. If multiple shipments share the same CUSTOMER_REFERENCE, all matching shipments will be returned when filtered by this value.
Example: CUSTOMER_REFERENCE: "REF-123456"

"identifiers": [
  {
    "type": "CUSTOMER_REFERENCE",
    "value": "REF-123456"
  }
]

2. Shipment Attributes

Purpose: Additional information about the shipment, such as the type of cargo or special handling requirements. They are not used for any tracking purpose.
Fields:
- name: Name of the attribute.
- values: List of values for the attribute.
Example:

"attributes": [
  {
    "name": "Cargo Type",
    "values": [
      "Electronics"
    ]
  },
  {
    "name": "Special Handling",
    "values": [
      "Fragile"
    ]
  }
]

3. Shipment Plan

Fields:
- expectedTransportationModes: Defines the transportation mode of the shipmment. It can be OCEAN or BARGE.
- vesselTracking: Enables vessel-based tracking for the shipment.
Example:

"plan": {
  "expectedTransportationModes": [
    "OCEAN"
  ],
  "vesselTracking": {
    "enabled": "true"
  }
}

4. Stops Information

Purpose: Specifies the ports for vessel journey, including the Port of Loading and Port of Discharge.
Fields:
- type: Type of the port. It can be PORT_OF_LOADING, PORT_OF_DISCHARGE.
- id: Unique UUID of the port.
- PORT_UN_LOCODE: 5-character UN/LOCODE of the port.
Example:

"stops": [
  {
    "id": "f1246a3e-322f-492b-9b7f-d5dccad0d232",
    "type": "PORT_OF_LOADING",
    "location": {
      "identifiers": [
        {
          "type": "PORT_UN_LOCODE",
          "value": "USNYC"
        }
      ]
    }
  },
  {
    "id": "f7aab7ac-e3b0-4d21-b935-3a3ea64e0f4d",
    "type": "PORT_OF_DISCHARGE",
    "location": {
      "identifiers": [
        {
          "type": "PORT_UN_LOCODE",
          "value": "USLAX"
        }
      ]
    }
  }
]

5. Route Information

Purpose: Specifies the vessel journey between two port stops and includes vessel identifiers.
Fields:
- id: Unique UUID of the route segment.
- fromStopId: id of port of loading.
- toStopId: id of port of discharge.
- transportationMode: Defines the transportation mode of the route segment. It can be OCEAN or BARGE.
- identifiers: List of identifiers for the vessel assigned to the route segment.
This table describes the route segment identifiers for vessel tracking.

Vessel Identifiers	Description
`VESSEL_NAME`	The name of the vessel assigned to the route segment.
`VESSEL_IMO`	The IMO number of the vessel assigned to the route segment.
`VESSEL_MMSI`	The MMSI of the of the vessel assigned to the route segment.

Example:

"routeSegments": [
  {
    "id": "2e332c4b-1846-4e75-bfd2-cb7ac978b220",
    "fromStopId": "f1246a3e-322f-492b-9b7f-d5dccad0d232",
    "toStopId": "f7aab7ac-e3b0-4d21-b935-3a3ea64e0f4d",
    "transportationMode": "BARGE",
    "identifiers": [
      {
        "type": "VESSEL_NAME",
        "value": "MEKONG"
      }
    ]
  }
]

6. Events Information

Purpose: Specifies the planned events for the shipment.
Fields:
- plannedDateTime: Planned date and time for the event with time format (e.g., 2025-07-10T17:30:29+0000).
- plannedEndDateTime: Planned end date and time for the event (optional) with time format (e.g., 2025-07-11T12:30:29+0000).
- type: Type of the event. It can be DEPARTURE_FROM_STOP or ARRIVAL_AT_STOP.
- stopId: The id of the stop where the event occurs.
Example:

"events": [
  {
    "plannedDateTime": "2025-07-10T17:30:29+0000",
    "plannedEndDateTime": "2025-07-11T12:30:29+0000",
    "type": "DEPARTURE_FROM_STOP",
    "stopId": "f1246a3e-322f-492b-9b7f-d5dccad0d232",
    "routeSegmentId": "2e332c4b-1846-4e75-bfd2-cb7ac978b220"
  },
  {
    "plannedDateTime": "2025-07-13T15:30:29+0000",
    "plannedEndDateTime": "2025-07-15T10:30:29+0000",
    "type": "ARRIVAL_AT_STOP",
    "stopId": "f7aab7ac-e3b0-4d21-b935-3a3ea64e0f4d",
    "routeSegmentId": "2e332c4b-1846-4e75-bfd2-cb7ac978b220"
  }
]

Workflow

Complete these steps:

Prepare a POST request to /api/v4/shipments/tracking.
Add all the required details to the request schema. For example,

{
  "identifiers": [
    {
      "type": "CUSTOMER_REFERENCE",
      "value": "REF-123456"
    }
  ],
  "attributes": [
    {
      "name": "Cargo Type",
      "values": [
        "Electronics"
      ]
    },
    {
      "name": "Special Handling",
      "values": [
        "Fragile"
      ]
    }
  ],
  "plan": {
    "expectedTransportationModes": [
      "OCEAN"
    ],
    "vesselTracking": {
      "enabled": "true"
    }
  },
  "routeInfo": {
    "stops": [
      {
        "id": "f1246a3e-322f-492b-9b7f-d5dccad0d232",
        "type": "PORT_OF_LOADING",
        "location": {
          "identifiers": [
            {
              "type": "PORT_UN_LOCODE",
              "value": "USNYC"
            }
          ]
        }
      },
      {
        "id": "f7aab7ac-e3b0-4d21-b935-3a3ea64e0f4d",
        "type": "PORT_OF_DISCHARGE",
        "location": {
          "identifiers": [
            {
              "type": "PORT_UN_LOCODE",
              "value": "USLAX"
            }
          ]
        }
      }
    ],
    "routeSegments": [
      {
        "id": "2e332c4b-1846-4e75-bfd2-cb7ac978b220",
        "fromStopId": "f1246a3e-322f-492b-9b7f-d5dccad0d232",
        "toStopId": "f7aab7ac-e3b0-4d21-b935-3a3ea64e0f4d",
        "transportationMode": "BARGE",
        "identifiers": [
          {
            "type": "VESSEL_NAME",
            "value": "MEKONG"
          }
        ]
      }
    ]
  },
  "events": [
    {
      "plannedDateTime": "2025-07-10T17:30:29+0000",
      "plannedEndDateTime": "2025-07-11T12:30:29+0000",
      "type": "DEPARTURE_FROM_STOP",
      "stopId": "f1246a3e-322f-492b-9b7f-d5dccad0d232",
      "routeSegmentId": "2e332c4b-1846-4e75-bfd2-cb7ac978b220"
    },
    {
      "plannedDateTime": "2025-07-13T15:30:29+0000",
      "plannedEndDateTime": "2025-07-15T10:30:29+0000",
      "type": "ARRIVAL_AT_STOP",
      "stopId": "f7aab7ac-e3b0-4d21-b935-3a3ea64e0f4d",
      "routeSegmentId": "2e332c4b-1846-4e75-bfd2-cb7ac978b220"
    }
  ]
}

This only shows the minimum required request schema. For the full request schema and descriptions for all fields and objects, please see our reference documentation.

Send the request.

Expected System Response

You have successfully submitted the request when you receive a 200 OK response. Here is a sample of the minimum response schema:

{
  "id": "eb0edc03-8078-48bf-bc0c-d2b6ceb7e631",
  "createdDateTime": "2025-07-31T10:06:46+0000",
  "identifiers": [
    {
      "type": "CUSTOMER_REFERENCE",
      "value": "REF-123456"
    }
  ],
  "shipmentShareLink": "https://movement.project44.com/share/976758b4-1185-4c8b-b55d-cb88dac8591b",
  "lastModifiedDateTime": "2025-07-31T10:06:46+0000",
  "plan": {
    "expectedTransportationModes": [
      "OCEAN"
    ],
    "vesselTracking": {
      "enabled": true
    }
  },
  "routeInfo": {
    "stops": [
      {
        "id": "f1246a3e-322f-492b-9b7f-d5dccad0d232",
        "type": "PORT_OF_LOADING",
        "location": {
          "identifiers": [
            {
              "type": "PORT_UN_LOCODE",
              "value": "USNYC"
            }
          ]
        }
      },
      {
        "id": "f7aab7ac-e3b0-4d21-b935-3a3ea64e0f4d",
        "type": "PORT_OF_DISCHARGE",
        "location": {
          "identifiers": [
            {
              "type": "PORT_UN_LOCODE",
              "value": "USLAX"
            }
          ]
        }
      }
    ],
    "routeSegments": [
      {
        "id": "2e332c4b-1846-4e75-bfd2-cb7ac978b220",
        "fromStopId": "f1246a3e-322f-492b-9b7f-d5dccad0d232",
        "toStopId": "f7aab7ac-e3b0-4d21-b935-3a3ea64e0f4d",
        "transportationMode": "BARGE",
        "identifiers": [
          {
            "type": "VESSEL_NAME",
            "value": "MEKONG"
          }
        ]
      }
    ]
  },
  "events": [
    {
      "receivedDateTime": "2025-07-31T10:06:46+0000",
      "type": "DEPARTURE_FROM_STOP",
      "stopId": "f1246a3e-322f-492b-9b7f-d5dccad0d232",
      "routeSegmentId": "2e332c4b-1846-4e75-bfd2-cb7ac978b220",
      "plannedDateTime": "2025-07-10T17:30:29+0000",
      "plannedEndDateTime": "2025-07-11T12:30:29+0000"
    },
    {
      "receivedDateTime": "2025-07-31T10:06:46+0000",
      "type": "ARRIVAL_AT_STOP",
      "stopId": "f7aab7ac-e3b0-4d21-b935-3a3ea64e0f4d",
      "routeSegmentId": "2e332c4b-1846-4e75-bfd2-cb7ac978b220",
      "plannedDateTime": "2025-07-13T15:30:29+0000",
      "plannedEndDateTime": "2025-07-15T10:30:29+0000"
    }
  ]
}

In this response you receive the identifiers used in the request (CUSTOMER_REFERENCE) plus the UUID (id) along with shipment link.

Store the id. Use the id to get shipment tracking updates.

Errors

If there was a problem with your request, you will receive one of the following error codes:

400 Invalid request
401 Invalid or missing credentials
403 User not authorized to perform this operation

See Error Response Codes in the Appendix for more information on the meaning of these error codes.

Validations on request payload

The following validations are applied to the request payload:

Field	Validation
`identifiers`	Each shipment must include at least one identifier of type `CUSTOMER_REFERENCE`.
`plan.expectedTransportationModes`	This field should specify the transportation mode for the shipment. Allowed values are `BARGE` or `VESSEL`.
`plan.vesselTracking`	Must be set to `true` to enable tracking for a vessel shipment. If set to `False`, vessel tracking will not initiate.
`routeInfo.stops`	Both `PORT_OF_LOADING` and `PORT_OF_DISCHARGE` stops are required, and each must include a `PORT_UN_LOCODE` identifier. Shipments missing this information will fail creation.
`routeInfo.routeSegments`	Each route segment must include `fromStopId` and `toStopId`, corresponding to the `PORT_OF_LOADING` and `PORT_OF_DISCHARGE` respectively. The `transportationMode` must indicate the shipment's mode. At least one vessel identifier is required.
`events`	Must contain at least one `DEPARTURE_FROM_STOP` event and one `ARRIVAL_AT_STOP` event, each with appropriate `stopId`. `DEPARTURE_FROM_STOP` should reference the `PORT_OF_LOADING`, and `ARRIVAL_AT_STOP` should reference the `PORT_OF_DISCHARGE`. The `plannedDateTime` must be valid. `plannedEndDateTime` is optional but should also be valid if provided. `plannedEndDateTime` should always be greater than `plannedDateTime`.