Last updated

Get Tracking Updates

Get tracking information about a Full Truckload (FTL) shipment. A shipment must be created and added to project44's network before we can return tracking information. If you have not done so, please Create a Shipment.

project44 offers four targeted endpoints for returning shipment tracking information. This allows you to fetch the specific information you need, when you need it.

To have a shipment's tracking history PUSHed to you, set up a configuration wtih project44's webhook APIs. The PUSHed data will look like the response from the Get Tracking History endpoint.

Our Shipment Tracking APIs are designed to be used in an asynchronous manner. This means that a behavior or functionality may not be immediately available upon submission to our API because our system processes data asynchronously.

For more information about how to use the specific endpoints and features, please consult our user guide and API Reference documentation.

Get Event History

Get information about shipment milestones (events) that have occurred and are planned to occur.

Requirements

Have the following information available:

  • project44-generated Shipment ID (this is the id returned in the 200 OK response during Shipment Creation).

Workflow

Complete these steps:

  1. Prepare a GET request to /api/v4/shipments/{shipmentId}/eventhistory.

    To return stop and route information in the response, include the includeRouteInfo query parameter in your request. For example, GET /api/v4/shipments/ 758ff08b-2693-4308-bf22-b967623ffeea/eventhistory?includeRouteInfo=true

  2. Add the project44-generated Shipment ID.

  3. Submit the request.

Expected System Response

The request is successfully submitted and confirmed when a 200 OK response is received.

JSON
{
    "shipment": {
        "id": "758ff08b-2693-4308-bf22-b967623ffeea",
        "identifiers": [
            {
                "type": "BILL_OF_LADING",
                "value": "string"
            },
            {
                "type": "CARRIER_NMC_ID",
                "value": "string"
            }
        ],
        "attributes": [
            {
                "name":"Shipment Type",
                "values": [
                    "Drayage"
                ]
            }
        ]
        "shipmentShareLink": "https://na12.voc.project44.com/portal/v2/public/ma/tracking-details?shipmentShareToken=d2e5094c-0962-4f33-8553-4df015b6ffc6",
        "createdDateTime": "2023-02-07T16:12:29+0000",
        "routeInfo": {
            "stops": [
                {
                    "id": "0dcaf574-1183-45b2-ae9c-5529531af9c6",
                    "type": "ORIGIN",
                    "location": {
                        "id": "8669f02f-27b0-4b40-9a2f-38eddb4348ab",
                        "name": "Vancouver",
                        "identifiers": [
                            {
                                "type": "PORT_UN_LOCODE",
                                "value": "CNNGB"
                            }
                        ],
                        "address": {
                            "postalCode": "string",
                            "city": "Vancouver",
                            "state": "BC",
                            "country": "CA"
                        },
                        "coordinates": {
                            "latitude": 49.283333,
                            "longitude": -123.11667
                        }
                    }
                },
                {
                    "id": "6ab2c9dd-574c-4994-a14d-262a6313ab5d",
                    "type": "DESTINATION",
                    "location": {
                        "id": "72ec8d0b-3a29-4f5d-b116-ba8dcc83a124",
                        "name": "Minneapolis",
                        "address": {
                            "postalCode": "string",
                            "addressLines": [
                                "string"
                            ],
                            "city": "Minneapolis",
                            "state": "MN",
                            "country": "US"
                        },
                        "coordinates": {
                            "latitude": 44.97997,
                            "longitude": -93.26384
                        }
                    }
                }
            ],
            "routeSegments": [
                {
                    "id": "9810cab9-ab32-3871-b392-768aba8ea330",
                    "fromStopId": "0dcaf574-1183-45b2-ae9c-5529531af9c6",
                    "toStopId": "6ab2c9dd-574c-4994-a14d-262a6313ab5d",
                    "transportationMode": "TRUCKLOAD",
                    "identifiers": [
                        {
                            "type": "CARRIER_NMC_ID",
                            "value": "string"
                        }
                    ]
                }
            ]
        },
        "relatedShipments": [
            {
                "id": "d7e8af95-edf7-4f93-9377-f736220c9a2d",
                "identifiers": [
                    {
                        "type": "CONTAINER_ID",
                        "value": "string"
                    },
                    {
                        "type": "CARRIER_SCAC",
                        "value": "string"
                    }
                ],
                "attributes":[
                    {
                        "name": "Shipment Type",
                        "values": [
                            "Inland Drayage"
                        ]
                    },
                    {
                        "name": "Import Region",
                        "values": [
                            "NA"
                        ]
                    },
                    {
                        "name": "Export Region",
                        "values": [
                            "APAC"
                        ]
                    }
                ],
                "shipmentShareLink": "https://na12.voc.project44.com/portal/v2/public/ma/tracking-details?shipmentShareToken=6b3afee6-1f4d-4839-a453-11c01fa310fa",
                "createdDateTime": "2022-12-16T13:30:23+0000"
            }
        ]
    },
    "states": [
        {
            "type": "SCHEDULED",
            "startDateTime": "2023-02-07T16:29:54+0000",
            "endDateTime": "2023-02-07T22:05:02+0000",
        },
        {
            "type": "AT_STOP",
            "startDateTime": "2023-02-07T20:25:20+0000",
            "endDateTime": "2023-02-07T22:05:02+0000",
            "stopId": "0dcaf574-1183-45b2-ae9c-5529531af9c6",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330"
        },
        {
            "type": "IN_TRANSIT",
            "startDateTime": "2023-02-07T22:05:02+0000",
            "endDateTime": "2023-02-10T09:52:51+0000",
            "stopId": "0dcaf574-1183-45b2-ae9c-5529531af9c6",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330"
        }
    ],
    "events": [
        {
            "dateTime": "2023-02-07T16:12:30+0000",
            "receivedDateTime": "2023-02-07T16:12:30+0000",
            "type": "DISPATCH",
            "description": "The shipment has been dispatched."
        },
        {
            "dateTime": "2023-02-07T16:29:54+0000",
            "receivedDateTime": "2023-02-07T16:29:54+0000",
            "type": "TRACKING_START",
            "description": "Entered tracking update window."
        },
        {
            "dateTime": "2023-02-07T17:49:00+0000",
            "receivedDateTime": "2023-02-07T17:49:02+0000",
            "type": "IDLE",
            "description": "Shipment is stationary.",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330"
        },
        {
            "dateTime": "2023-02-07T20:25:20+0000",
            "receivedDateTime": "2023-02-07T20:25:20+0000",
            "type": "ARRIVAL_AT_STOP",
            "description": "Entered the inner location geofence.",
            "stopId": "0dcaf574-1183-45b2-ae9c-5529531af9c6",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "plannedDateTime": "2023-02-07T10:00:00-0800",
            "plannedEndDateTime": "2023-02-07T13:00:00-0800"
        },
        {
            "dateTime": "2023-02-07T22:05:02+0000",
            "receivedDateTime": "2023-02-07T22:05:03+0000",
            "type": "DEPARTURE_FROM_STOP",
            "description": "Exited the inner location geofence.",
            "stopId": "0dcaf574-1183-45b2-ae9c-5529531af9c6",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330"
        }
    ]
}

This is an example of what could be returned in the response. Null fields will not show up in the response. Please refer to the reference data for more information on required and potential null fields.

See the Appendix for descriptions of the FTL Shipment Event Types, FTL Shipment State Types, and FTL Shipment Stop Types returned by this endpoint.

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
  • 404 Shipment not found

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

Field and Objects

The table below describes only the minimum relevant fields returned in the 200 OK response from the GET: Fetch the event history for a shipment endpoint including the includeRouteInfo query parameter.

FieldDescription
routeInfoAn overview of the shipment route includes all the necessary IDs for mapping each event to the correct stop, vessel, and segment of the journey.
routeInfo.stopsA stop is a set point of the journey that can be an inland location or a port. Several data fields are used to describe an array of stops as defined in the API.
routeInfo.stops.idproject44 ID of the stop the event is related to (referenced to as stopId in events payload).
routeInfo.stops.typeThe type of the stop. For descriptions of specific stop types, see FTL Shipment Stop Types.
routeInfo.stops.locationAn object that consists of the location name, identifiers, and coordinates.
routeInfo.stops.location.nameThe name of the location - received by shipping line (no input from customer required).
routeInfo.stops.location.identifiersA type:value pair.
routeInfo.stops.location.coordinatesThe latitude and longitude of the location.
routeInfo.routeSegmentsAn array that describes the journey between two stops.
routeInfo.routeSegments.idproject44 ID of the route segment the event is related to (referenced to as routeSegmentId in events and positions payload)
routeInfo.routeSegments.fromStopIdproject44 ID of where the route segment originates.
routeInfo.routeSegments.toStopIdproject44 ID of where the route segment terminates.
routeInfo.routeSegments.transportatioinModeThe mode of transport used for the route segment.
routeInfo.routeSegments.identifiersAn array that consists of type:value pairs. See Route Segment Identifiers for valid IDs and descriptions.
relatedShipmentsA BOL/BN can consist of multiple containers. An array of all containers tracked under the overall shipment (as created by the user) is returned in the relatedShipments object. Each object uses an unique ID (id) to retrieve or identify (for PUSH) updates related to the designated container.
statesAn array of all states the shipment was or currently is in.
states.typeThe specific type of state the shipment was in. See FTL Shipment State Types for a full list of the supported state types and their descriptions.
states.startDateTimeThe time this state began.
states.endDateTimeThe time that this state ended. May not be populated if the shipment is still in this state.
states.stopIdThe ID of the related stop.routeSegmentId: the route segment ID this state occurred along.
eventsAn array of all events related to the shipment.
events.dateTimeThe time at which the event took place (actual).
events.estimateDateTimeproject44's latest estimated time for the event.
events.plannedDateTimeThe carrier's latest scheduled time for the event. NOTE: Timestamps related to an event do not currently include contracted time or initial planned time by carrier.
events.typeThe type of event that occurs. See FTL Shipment Event Types for a full list of supported event types and descriptions.
events.descriptionA description of the event that occurs (not available for all events)
events.stopIdThe project44 ID of the stop the event is related to.
events.routeSegmentsIdThe project44 ID of the route segment the stop is related to. See Route Segment Identifierss for more information on the specific identifier types.
events.receivedDateTimeThe last time information about event was modified.
events.estimatedLastCalculatedDateTimeThe last time the estimate date time was modified.

Get Position History

Get information about an FTL shipment's position history.

Requirements

Have the following information available:

  • project44-generated Shipment ID (this is the id returned in the 200 OK response during Shipment Creation).

Workflow

Complete the following steps.

  1. Prepare a GET request to /api/v4/shipments/{shipmentId}/positionhistory using the project44-generated Shipment ID. For example, GET /api/v4/shipments/758ff08b-2693-4308-bf22-b967623ffeea/positionhistory.

    To return stop information in the response, include the includeRouteInfo query parameter in your request. For example, GET /api/v4/shipments/758ff08b-2693-4308-bf22-b967623ffeea/positionhistory?includeRouteInfo=true

  2. Submit the request.

Expected System Response

The request is successfully submitted and confirmed when a 200 OK response is received.

JSON
{
    "shipment": {
        "id": "758ff08b-2693-4308-bf22-b967623ffeea",
        "identifiers": [
            {
                "type": "BILL_OF_LADING",
                "value": "string"
            },
            {
                "type": "CARRIER_NMC_ID",
                "value": "string"
            }
        ],
        "attributes": [
            {
                "name":"Shipment Type",
                "values": [
                    "Drayage"
                ]
            }
        ]
        "shipmentShareLink": "https://na12.voc.project44.com/portal/v2/public/ma/tracking-details?shipmentShareToken=d2e5094c-0962-4f33-8553-4df015b6ffc6",
        "createdDateTime": "2023-02-07T16:12:29+0000",
        "routeInfo": {
            "stops": [
                {
                    "id": "0dcaf574-1183-45b2-ae9c-5529531af9c6",
                    "type": "ORIGIN",
                    "location": {
                        "id": "8669f02f-27b0-4b40-9a2f-38eddb4348ab",
                        "name": "Vancouver",
                        "identifiers": [
                            {
                                "type": "PORT_UN_LOCODE",
                                "value": "CNNGB"
                            }
                        ],
                        "address": {
                            "postalCode": "V6C 3T3",
                            "city": "Vancouver",
                            "state": "BC",
                            "country": "CA"
                        },
                        "coordinates": {
                            "latitude": 49.283333,
                            "longitude": -123.11667
                        }
                    }
                },
                {
                    "id": "6ab2c9dd-574c-4994-a14d-262a6313ab5d",
                    "type": "DESTINATION",
                    "location": {
                        "id": "72ec8d0b-3a29-4f5d-b116-ba8dcc83a124",
                        "name": "Minneapolis",
                        "address": {
                            "postalCode": "55415",
                            "addressLines": [
                                "string"
                            ],
                            "city": "Minneapolis",
                            "state": "MN",
                            "country": "US"
                        },
                        "coordinates": {
                            "latitude": 44.97997,
                            "longitude": -93.26384
                        }
                    }
                }
            ],
            "routeSegments": [
                {
                    "id": "9810cab9-ab32-3871-b392-768aba8ea330",
                    "fromStopId": "0dcaf574-1183-45b2-ae9c-5529531af9c6",
                    "toStopId": "6ab2c9dd-574c-4994-a14d-262a6313ab5d",
                    "transportationMode": "TRUCKLOAD",
                    "identifiers": [
                        {
                            "type": "CARRIER_NMC_ID",
                            "value": "string"
                        }
                    ]
                }
            ]
        },
        "relatedShipments": [
            {
                "id": "d7e8af95-edf7-4f93-9377-f736220c9a2d",
                "identifiers": [
                    {
                        "type": "CONTAINER_ID",
                        "value": "string"
                    },
                    {
                        "type": "CARRIER_SCAC",
                        "value": "string"
                    }
                ],
                "attributes":[
                    {
                        "name": "Shipment Type",
                        "values": [
                            "Inland Drayage"
                        ]
                    },
                    {
                        "name": "Import Region",
                        "values": [
                            "NA"
                        ]
                    },
                    {
                        "name": "Export Region",
                        "values": [
                            "APAC"
                        ]
                    }
                ],
                "shipmentShareLink": "https://na12.voc.project44.com/portal/v2/public/ma/tracking-details?shipmentShareToken=6b3afee6-1f4d-4839-a453-11c01fa310fa",
                "createdDateTime": "2022-12-16T13:30:23+0000"
            }
        ]
    },
    "positions": [
        {
            "dateTime": "2023-02-07T17:00:18+0000",
            "receivedDateTime": "2023-02-07T17:00:19+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 48.88333,
            "longitude": -123.11667
        },
        {
            "dateTime": "2023-02-07T17:09:55+0000",
            "receivedDateTime": "2023-02-07T17:09:55+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 48.798283,
            "longitude": -123.17604
        },
        {
            "dateTime": "2023-02-07T17:19:41+0000",
            "receivedDateTime": "2023-02-07T17:19:42+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 48.79268,
            "longitude": -123.16987
        },
        {
            "dateTime": "2023-02-07T17:29:27+0000",
            "receivedDateTime": "2023-02-07T17:29:34+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 48.793232,
            "longitude": -123.177986
        },
        {
            "dateTime": "2023-02-07T17:39:14+0000",
            "receivedDateTime": "2023-02-07T17:39:27+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 48.795376,
            "longitude": -123.19365
        },
        {
            "dateTime": "2023-02-07T17:49:00+0000",
            "receivedDateTime": "2023-02-07T17:49:02+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 48.797813,
            "longitude": -123.20121
        },
        {
            "dateTime": "2023-02-07T17:58:46+0000",
            "receivedDateTime": "2023-02-07T17:58:54+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.006584,
            "longitude": -123.12925
        },
        {
            "dateTime": "2023-02-07T18:08:32+0000",
            "receivedDateTime": "2023-02-07T18:08:51+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.01115,
            "longitude": -123.12313
        },
        {
            "dateTime": "2023-02-07T18:18:18+0000",
            "receivedDateTime": "2023-02-07T18:18:19+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.0369,
            "longitude": -123.080864
        },
        {
            "dateTime": "2023-02-07T18:28:05+0000",
            "receivedDateTime": "2023-02-07T18:28:09+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.05388,
            "longitude": -123.05711
        },
        {
            "dateTime": "2023-02-07T18:37:51+0000",
            "receivedDateTime": "2023-02-07T18:37:51+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 9.08813,
            "longitude": -123.056885
        },
        {
            "dateTime": "2023-02-07T18:47:37+0000",
            "receivedDateTime": "2023-02-07T18:48:04+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.108738,
            "longitude": -123.054214
        },
        {
            "dateTime": "2023-02-07T18:57:23+0000",
            "receivedDateTime": "2023-02-07T18:57:42+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.110863,
            "longitude": -123.06193
        },
        {
            "dateTime": "2023-02-07T19:07:09+0000",
            "receivedDateTime": "2023-02-07T19:07:10+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.15712,
            "longitude": -123.08654
        },
        {
            "dateTime": "2023-02-07T19:16:56+0000",
            "receivedDateTime": "2023-02-07T19:16:56+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.191326,
            "longitude": -123.117645
        },
        {
            "dateTime": "2023-02-07T19:26:42+0000",
            "receivedDateTime": "2023-02-07T19:26:42+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.206993,
            "longitude": -123.1245
        },
        {
            "dateTime": "2023-02-07T19:36:28+0000",
            "receivedDateTime": "2023-02-07T19:36:29+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.21587,
            "longitude": -123.11674
        },
        {
            "dateTime": "2023-02-07T19:46:15+0000",
            "receivedDateTime": "2023-02-07T19:46:15+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.233353,
            "longitude": -123.11609
        },
        {
            "dateTime": "2023-02-07T19:56:01+0000",
            "receivedDateTime": "2023-02-07T19:56:02+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.24108,
            "longitude": -123.11829
        },
        {
            "dateTime": "2023-02-07T20:05:47+0000",
            "receivedDateTime": "2023-02-07T20:06:56+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.25121,
            "longitude": -123.11531
        },
        {
            "dateTime": "2023-02-07T20:15:34+0000",
            "receivedDateTime": "2023-02-07T20:15:34+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.262188,
            "longitude": -123.11484
        },
        {
            "dateTime": "2023-02-07T20:25:20+0000",
            "receivedDateTime": "2023-02-07T20:25:20+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.276264,
            "longitude": -123.11521
        },
        {
            "dateTime": "2023-02-07T20:35:06+0000",
            "receivedDateTime": "2023-02-07T20:35:07+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.283333,
            "longitude": -123.11667
        },
        {
            "dateTime": "2023-02-07T22:05:02+0000",
            "receivedDateTime": "2023-02-07T22:05:03+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.251926,
            "longitude": -123.13901
        }
    ]
}

This is an example of what could be returned in the response. Null fields will not show up in the response. Please refer to the reference data for more information on required and potential null fields.

See the Appendix for descriptions of the FTL Shipment Stop Types and Route Segment Identifiers.

Error

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
  • 404 Shipment not found

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

Fields and Objects

The table below describes fields returned in the response 200 OK from the GET: Fetch the position history for a shipment endpoint.

FieldDescription
routeInfoAn overview of the shipment route includes all the necessary IDs for mapping each event to the correct stop, vessel, and segment of the journey.
routeInfo.stopsA stop is a set point of the journey that can be an inland location or a port. Several data fields are used to describe an array of stops as defined in the API.
routeInfo.stops.idproject44 ID of the stop the event is related to (referenced to as stopId in events payload).
routeInfo.stops.typeThe type of the stop. For descriptions of specific stop types, see FTL Shipment Stop Types.
routeInfo.stops.locationAn object that consists of the location name, identifiers, and coordinates.
routeInfo.stops.location.nameThe name of the location – received by shipping line (no input from customer required).
routeInfo.stops.location.identifiersA type:value pair.
routeInfo.stops.location.coordinatesThe latitude and longitude of the location.
routeInfo.routeSegmentsAn array that describes the journey between two stops.
routeInfo.routeSegments.idproject44 ID of the route segment the event is related to (referenced to as routeSegmentId in events and positions payload)
routeInfo.routeSegments.fromStopIdproject44 ID of where the route segment originates.
routeInfo.routeSegments.toStopIdproject44 ID of where the route segment terminates.
routeInfo.routeSegments.transportatioinModeThe mode of transport used for the route segment.
routeInfo.routeSegments.identifiersAn array that consists of type:value pairs. See Route Segment Identifiers for valid IDs and descriptions.
relatedShipmentsA BOL/BN can consist of multiple containers. An array of all containers tracked under the overall shipment (as created by the user) is returned in the relatedShipments object. Each object uses an unique ID (id) to retrieve or identify (for PUSH) updates related to the designated container.
positionsAn array of all geo-positions related to the shipment.
positions.dateTimeThe time the recorded position.
positions.receivedDateTimeThe time the position was received by project44.
positions.routeSegmentIdThe ID of the route segment the stop is related to.

Get Route Information

Get route information (stops and route segments) for an FTL shipment.

Requirements

Have the following information available:

  • project44-generated Shipment ID (this is the id returned in the 200 OK response during Shipment Creation).

Workflow

Complete the following steps.

  1. Prepate a GET request to /api/v4/shipments/{shipmentId}/tracking and use the project44-generated Shipment ID. For example, GET /api/v4/shipments/758ff08b-2693-4308-bf22-b967623ffeea/tracking.
  2. Submit the request.

Expected System Response

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

JSON
{
    "shipment": {
        "id": "758ff08b-2693-4308-bf22-b967623ffeea",
        "identifiers": [
            {
                "type": "BILL_OF_LADING",
                "value": "string"
            },
            {
                "type": "CARRIER_NMC_ID",
                "value": "string"
            }
        ],
        "attributes": [
            {
                "name":"Shipment Type",
                "values": [
                    "Drayage"
                ]
            }
        ]
        "shipmentShareLink": "https://na12.voc.project44.com/portal/v2/public/ma/tracking-details?shipmentShareToken=d2e5094c-0962-4f33-8553-4df015b6ffc6",
        "createdDateTime": "2023-02-07T16:12:29+0000",
        "routeInfo": {
            "stops": [
                {
                    "id": "0dcaf574-1183-45b2-ae9c-5529531af9c6",
                    "type": "ORIGIN",
                    "location": {
                        "id": "8669f02f-27b0-4b40-9a2f-38eddb4348ab",
                        "name": "Vancouver",
                        "identifiers": [
                            {
                                "type": "PORT_UN_LOCODE",
                                "value": "CNNGB"
                            }
                        ],
                        "address": {
                            "postalCode": "V6C 3T3",
                            "city": "Vancouver",
                            "state": "BC",
                            "country": "CA"
                        },
                        "coordinates": {
                            "latitude": 49.283333,
                            "longitude": -123.11667
                        }
                    }
                },
                {
                    "id": "6ab2c9dd-574c-4994-a14d-262a6313ab5d",
                    "type": "DESTINATION",
                    "location": {
                        "id": "72ec8d0b-3a29-4f5d-b116-ba8dcc83a124",
                        "name": "Minneapolis",
                        "address": {
                            "postalCode": "55415",
                            "addressLines": [
                                "string"
                            ],
                            "city": "Minneapolis",
                            "state": "MN",
                            "country": "US"
                        },
                        "coordinates": {
                            "latitude": 44.97997,
                            "longitude": -93.26384
                        }
                    }
                }
            ],
            "routeSegments": [
                {
                    "id": "9810cab9-ab32-3871-b392-768aba8ea330",
                    "fromStopId": "0dcaf574-1183-45b2-ae9c-5529531af9c6",
                    "toStopId": "6ab2c9dd-574c-4994-a14d-262a6313ab5d",
                    "transportationMode": "TRUCKLOAD",
                    "identifiers": [
                        {
                            "type": "CARRIER_NMC_ID",
                            "value": "string"
                        }
                    ]
                }
            ]
        },
        "relatedShipments": [
            {
                "id": "d7e8af95-edf7-4f93-9377-f736220c9a2d",
                "identifiers": [
                    {
                        "type": "CONTAINER_ID",
                        "value": "string"
                    },
                    {
                        "type": "CARRIER_SCAC",
                        "value": "string"
                    }
                ],
                "attributes":[
                    {
                        "name": "Shipment Type",
                        "values": [
                            "Inland Drayage"
                        ]
                    },
                    {
                        "name": "Import Region",
                        "values": [
                            "NA"
                        ]
                    },
                    {
                        "name": "Export Region",
                        "values": [
                            "APAC"
                        ]
                    }
                ],
                "shipmentShareLink": "https://na12.voc.project44.com/portal/v2/public/ma/tracking-details?shipmentShareToken=6b3afee6-1f4d-4839-a453-11c01fa310fa",
                "createdDateTime": "2022-12-16T13:30:23+0000"
            }
        ]
    }
}

This is an example of what could be returned in the response. Null fields will not show up in the response. Please refer to the reference data for more information on required and potential null fields.

See the Appendix for descriptions FTL Shipment Stop Types and Route Segment Identifiers returned by this endpoint.

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
  • 404 Shipment not found

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

Fields and Objects

The table below describes fields returned in the response 200 OK from the GET: Fetch the route information for a shipment including the stops and route segments endpoint.

FieldDescription
routeInfoAn overview of the shipment route includes all the necessary IDs for mapping each event to the correct stop, vessel, and segment of the journey.
routeInfo.stopsA stop is a set point of the journey that can be an inland location or a port. Several data fields are used to describe an array of stops as defined in the API.
routeInfo.stops.idproject44 ID of the stop the event is related to (referenced to as stopId in events payload).
routeInfo.stops.typeThe type of the stop. For descriptions of specific stop types, see FTL Shipment Stop Types.
routeInfo.stops.locationAn object that consists of the location name, identifiers, and coordinates.
routeInfo.stops.location.nameThe name of the location – received by shipping line (no input from customer required).
routeInfo.stops.location.identifiersA type:value pair.
routeInfo.stops.location.coordinatesThe latitude and longitude of the location.
routeInfo.routeSegmentsAn array that describes the journey between two stops.
routeInfo.routeSegments.idproject44 ID of the route segment the event is related to (referenced to as routeSegmentId in events and positions payload)
routeInfo.routeSegments.fromStopIdproject44 ID of where the route segment originates.
routeInfo.routeSegments.toStopIdproject44 ID of where the route segment terminates.
routeInfo.routeSegments.transportatioinModeThe mode of transport used for the route segment.
routeInfo.routeSegments.identifiersAn array that consists of type:value pairs. See Route Segment Identifiers for valid IDs and descriptions.
relatedShipmentsA BOL/BN can consist of multiple containers. An array of all containers tracked under the overall shipment (as created by the user) is returned in the relatedShipments object. Each object uses an unique ID (id) to retrieve or identify (for PUSH) updates related to the designated container.

Get Full Tracking History

Get an FTL shipment's full tracking history including route information and stops, states, events, and positions. To have the shipment's full tracking history PUSHed to you, set up a configuration wtih project44's webhook APIs.

Requirements

Have the following information available:

  • project44-generated Shipment ID (this is the id returned in the 200 OK response during Shipment Creation).

Workflow

Complete the following steps.

  1. Prepare a GET request to /api/v4/shipments/{shipmentId}/tracking/history endpoint and use the project44-generated Shipment ID. For example, GET /api/v4/shipments/758ff08b-2693-4308-bf22-b967623ffeea/tracking/history.
  2. Submit the request.

Expected System Response

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

JSON
{
    "shipment": {
        "id": "758ff08b-2693-4308-bf22-b967623ffeea",
        "identifiers": [
            {
                "type": "BILL_OF_LADING",
                "value": "string"
            },
            {
                "type": "CARRIER_NMC_ID",
                "value": "string"
            }
        ],
        "attributes": [
            {
                "name":"Shipment Type",
                "values": [
                    "Drayage"
                ]
            }
        ]
        "shipmentShareLink": "https://na12.voc.project44.com/portal/v2/public/ma/tracking-details?shipmentShareToken=d2e5094c-0962-4f33-8553-4df015b6ffc6",
        "createdDateTime": "2023-02-07T16:12:29+0000",
        "routeInfo": {
            "stops": [
                {
                    "id": "0dcaf574-1183-45b2-ae9c-5529531af9c6",
                    "type": "ORIGIN",
                    "location": {
                        "id": "8669f02f-27b0-4b40-9a2f-38eddb4348ab",
                        "name": "Vancouver",
                        "identifiers": [
                            {
                                "type": "PORT_UN_LOCODE",
                                "value": "CNNGB"
                            }
                        ],
                        "address": {
                            "postalCode": "V6C 3T3",
                            "city": "Vancouver",
                            "state": "BC",
                            "country": "CA"
                        },
                        "coordinates": {
                            "latitude": 49.283333,
                            "longitude": -123.11667
                        }
                    }
                },
                {
                    "id": "6ab2c9dd-574c-4994-a14d-262a6313ab5d",
                    "type": "DESTINATION",
                    "location": {
                        "id": "72ec8d0b-3a29-4f5d-b116-ba8dcc83a124",
                        "name": "Minneapolis",
                        "address": {
                            "postalCode": "55415",
                            "addressLines": [
                                "string"
                            ],
                            "city": "Minneapolis",
                            "state": "MN",
                            "country": "US"
                        },
                        "coordinates": {
                            "latitude": 44.97997,
                            "longitude": -93.26384
                        }
                    }
                }
            ],
            "routeSegments": [
                {
                    "id": "9810cab9-ab32-3871-b392-768aba8ea330",
                    "fromStopId": "0dcaf574-1183-45b2-ae9c-5529531af9c6",
                    "toStopId": "6ab2c9dd-574c-4994-a14d-262a6313ab5d",
                    "transportationMode": "TRUCKLOAD",
                    "identifiers": [
                        {
                            "type": "CARRIER_NMC_ID",
                            "value": "string"
                        }
                    ]
                }
            ]
        },
        "relatedShipments": [
            {
                "id": "d7e8af95-edf7-4f93-9377-f736220c9a2d",
                "identifiers": [
                    {
                        "type": "CONTAINER_ID",
                        "value": "string"
                    },
                    {
                        "type": "CARRIER_SCAC",
                        "value": "string"
                    }
                ],
                "attributes":[
                    {
                        "name": "Shipment Type",
                        "values": [
                            "Inland Drayage"
                        ]
                    },
                    {
                        "name": "Import Region",
                        "values": [
                            "NA"
                        ]
                    },
                    {
                        "name": "Export Region",
                        "values": [
                            "APAC"
                        ]
                    }
                ],
                "shipmentShareLink": "https://na12.voc.project44.com/portal/v2/public/ma/tracking-details?shipmentShareToken=6b3afee6-1f4d-4839-a453-11c01fa310fa",
                "createdDateTime": "2022-12-16T13:30:23+0000"
            }
        ]
    },
    "states": [
        {
            "type": "SCHEDULED",
            "startDateTime": "2023-02-07T16:29:54+0000",
            "endDateTime": "2023-02-07T22:05:02+0000",
        },
        {
            "type": "AT_STOP",
            "startDateTime": "2023-02-07T20:25:20+0000",
            "endDateTime": "2023-02-07T22:05:02+0000",
            "stopId": "0dcaf574-1183-45b2-ae9c-5529531af9c6",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330"
        },
        {
            "type": "IN_TRANSIT",
            "startDateTime": "2023-02-07T22:05:02+0000",
            "endDateTime": "2023-02-10T09:52:51+0000",
            "stopId": "0dcaf574-1183-45b2-ae9c-5529531af9c6",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330"
        }
    ],
    "events": [
        {
            "dateTime": "2023-02-07T16:12:30+0000",
            "receivedDateTime": "2023-02-07T16:12:30+0000",
            "type": "DISPATCH",
            "description": "The shipment has been dispatched."
        },
        {
            "dateTime": "2023-02-07T16:29:54+0000",
            "receivedDateTime": "2023-02-07T16:29:54+0000",
            "type": "TRACKING_START",
            "description": "Entered tracking update window."
        },
        {
            "dateTime": "2023-02-07T17:49:00+0000",
            "receivedDateTime": "2023-02-07T17:49:02+0000",
            "type": "IDLE",
            "description": "Shipment is stationary.",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330"
        },
        {
            "dateTime": "2023-02-07T20:25:20+0000",
            "receivedDateTime": "2023-02-07T20:25:20+0000",
            "type": "ARRIVAL_AT_STOP",
            "description": "Entered the inner location geofence.",
            "stopId": "0dcaf574-1183-45b2-ae9c-5529531af9c6",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "plannedDateTime": "2023-02-07T10:00:00-0800",
            "plannedEndDateTime": "2023-02-07T13:00:00-0800"
        },
        {
            "dateTime": "2023-02-07T22:05:02+0000",
            "receivedDateTime": "2023-02-07T22:05:03+0000",
            "type": "DEPARTURE_FROM_STOP",
            "description": "Exited the inner location geofence.",
            "stopId": "0dcaf574-1183-45b2-ae9c-5529531af9c6",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330"
        }
    ],
    "positions": [
        {
            "dateTime": "2023-02-07T17:00:18+0000",
            "receivedDateTime": "2023-02-07T17:00:19+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 48.88333,
            "longitude": -123.11667
        },
        {
            "dateTime": "2023-02-07T17:09:55+0000",
            "receivedDateTime": "2023-02-07T17:09:55+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 48.798283,
            "longitude": -123.17604
        },
        {
            "dateTime": "2023-02-07T17:19:41+0000",
            "receivedDateTime": "2023-02-07T17:19:42+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 48.79268,
            "longitude": -123.16987
        },
        {
            "dateTime": "2023-02-07T17:29:27+0000",
            "receivedDateTime": "2023-02-07T17:29:34+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 48.793232,
            "longitude": -123.177986
        },
        {
            "dateTime": "2023-02-07T17:39:14+0000",
            "receivedDateTime": "2023-02-07T17:39:27+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 48.795376,
            "longitude": -123.19365
        },
        {
            "dateTime": "2023-02-07T17:49:00+0000",
            "receivedDateTime": "2023-02-07T17:49:02+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 48.797813,
            "longitude": -123.20121
        },
        {
            "dateTime": "2023-02-07T17:58:46+0000",
            "receivedDateTime": "2023-02-07T17:58:54+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.006584,
            "longitude": -123.12925
        },
        {
            "dateTime": "2023-02-07T18:08:32+0000",
            "receivedDateTime": "2023-02-07T18:08:51+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.01115,
            "longitude": -123.12313
        },
        {
            "dateTime": "2023-02-07T18:18:18+0000",
            "receivedDateTime": "2023-02-07T18:18:19+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.0369,
            "longitude": -123.080864
        },
        {
            "dateTime": "2023-02-07T18:28:05+0000",
            "receivedDateTime": "2023-02-07T18:28:09+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.05388,
            "longitude": -123.05711
        },
        {
            "dateTime": "2023-02-07T18:37:51+0000",
            "receivedDateTime": "2023-02-07T18:37:51+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 9.08813,
            "longitude": -123.056885
        },
        {
            "dateTime": "2023-02-07T18:47:37+0000",
            "receivedDateTime": "2023-02-07T18:48:04+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.108738,
            "longitude": -123.054214
        },
        {
            "dateTime": "2023-02-07T18:57:23+0000",
            "receivedDateTime": "2023-02-07T18:57:42+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.110863,
            "longitude": -123.06193
        },
        {
            "dateTime": "2023-02-07T19:07:09+0000",
            "receivedDateTime": "2023-02-07T19:07:10+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.15712,
            "longitude": -123.08654
        },
        {
            "dateTime": "2023-02-07T19:16:56+0000",
            "receivedDateTime": "2023-02-07T19:16:56+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.191326,
            "longitude": -123.117645
        },
        {
            "dateTime": "2023-02-07T19:26:42+0000",
            "receivedDateTime": "2023-02-07T19:26:42+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.206993,
            "longitude": -123.1245
        },
        {
            "dateTime": "2023-02-07T19:36:28+0000",
            "receivedDateTime": "2023-02-07T19:36:29+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.21587,
            "longitude": -123.11674
        },
        {
            "dateTime": "2023-02-07T19:46:15+0000",
            "receivedDateTime": "2023-02-07T19:46:15+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.233353,
            "longitude": -123.11609
        },
        {
            "dateTime": "2023-02-07T19:56:01+0000",
            "receivedDateTime": "2023-02-07T19:56:02+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.24108,
            "longitude": -123.11829
        },
        {
            "dateTime": "2023-02-07T20:05:47+0000",
            "receivedDateTime": "2023-02-07T20:06:56+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.25121,
            "longitude": -123.11531
        },
        {
            "dateTime": "2023-02-07T20:15:34+0000",
            "receivedDateTime": "2023-02-07T20:15:34+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.262188,
            "longitude": -123.11484
        },
        {
            "dateTime": "2023-02-07T20:25:20+0000",
            "receivedDateTime": "2023-02-07T20:25:20+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.276264,
            "longitude": -123.11521
        },
        {
            "dateTime": "2023-02-07T20:35:06+0000",
            "receivedDateTime": "2023-02-07T20:35:07+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.283333,
            "longitude": -123.11667
        },
        {
            "dateTime": "2023-02-07T22:05:02+0000",
            "receivedDateTime": "2023-02-07T22:05:03+0000",
            "routeSegmentId": "9810cab9-ab32-3871-b392-768aba8ea330",
            "latitude": 49.251926,
            "longitude": -123.13901
        }
    ]
}

This is an example of what could be returned in the response. Null fields will not show up in the response. Please refer to the reference data for more information on required and potential null fields.

See the Appendix for descriptions FTL Shipment Event Types, Route Segment Identifiers, FTL Shipment State Types, and FTL Shipment Stop Types returned by this endpoint.

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
  • 404 Shipment not found

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

Fields and Objects

FieldDescription
routeInfoAn overview of the shipment route includes all the necessary IDs for mapping each event to the correct stop, vessel, and segment of the journey.
routeInfo.stopsA stop is a set point of the journey that can be an inland location or a port. Several data fields are used to describe an array of stops as defined in the API.
routeInfo.stops.idproject44 ID of the stop the event is related to (referenced to as stopId in events payload).
routeInfo.stops.typeThe type of the stop. For descriptions of specific stop types, see FTL Shipment Stop Types returned by this endpoint.
routeInfo.stops.locationAn object that consists of the location name, identifiers, and coordinates.
routeInfo.stops.location.nameThe name of the location – received by shipping line (no input from customer required).
routeInfo.stops.location.identifiersA type:value pair.
routeInfo.stops.location.coordinatesThe latitude and longitude of the location.
routeInfo.routeSegmentsAn array that describes the journey between two stops.
routeInfo.routeSegments.idproject44 ID of the route segment the event is related to (referenced to as routeSegmentId in events and positions payload)
routeInfo.routeSegments.fromStopIdproject44 ID of where the route segment originates.
routeInfo.routeSegments.toStopIdproject44 ID of where the route segment terminates.
routeInfo.routeSegments.transportatioinModeThe mode of transport used for the route segment.
routeInfo.routeSegments.identifiersAn array that consists of type:value pairs. See Route Segment Identifiers for valid IDs and descriptions.
relatedShipmentsA BOL/BN can consist of multiple containers. An array of all containers tracked under the overall shipment (as created by the user) is returned in the relatedShipments object. Each object uses an unique ID (id) to retrieve or identify (for PUSH) updates related to the designated container.
statesAn array of all states the shipment was or currently is in.
states.typeThe specific type of state the shipment was in. See FTL Shipment State Types for a full list of the supported state types and their descriptions.
states.startDateTimeThe time this state began.
states.endDateTimeThe time that this state ended. May not be populated if the shipment is still in this state.
states.stopIdThe ID of the related stop.routeSegmentId: the route segment ID this state occurred along.
eventsAn array of all events related to the shipment.
events.dateTimeThe time at which the event took place (actual).
events.estimateDateTimeproject44’s latest estimated time for the event.
events.plannedDateTimeThe carrier’s latest scheduled time for the event. NOTE: Timestamps related to an event do not currently include contracted time or initial planned time by carrier.
events.typeThe type of event that occurs. See FTL Shipment Event Types for a full list of supported event types and descriptions.
events.descriptionA description of the event that occurs (not available for all events)
events.stopIdThe project44 ID of the stop the event is related to.
events.routeSegmentsIdThe project44 ID of the route segment the stop is related to. See Route Segment Identifiers for more information on the specific identifier types.
events.receivedDateTimeThe last time information about event was modified.
events.estimatedLastCalculatedDateTimeThe last time the estimate date time was modified.
positionsAn array of all geo-positions related to the shipment.
positions.dateTimeThe time the recorded position.
positions.receivedDateTimeThe time the position was received by project44.
positions.routeSegmentIdThe ID of the route segment the stop is related to.
Previous page
Next page