Get tracking information about a Less than Truckload (LTL) 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.

The Get Event History endpoint returns shipment events, or milestones.
The Get Position History endpoint returns shipment positions.
The Get Route Information endpoint returns only route segment and stop information for a shipment.
The Get Tracking History endpoint returns all shipment tracking information including events, positions, and stops and route segments.

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:

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
Add the project44-generated Shipment ID.
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": "CAPACITY_PROVIDER_ACCOUNT_GROUP",
                "value": "string"
            }
        ],
        "shipmentShareLink": "string",
        "createdDateTime": "2022-09-09T18:13:43+0000",
        "relatedShipments": [
            {
                "id": "a2adac91-18ba-4fc5-b939-93a10f9a7406",
                "identifiers": [
                    {
                        "type": "BILL_OF_LADING",
                        "value": "string"
                    }
                ],
                "shipmentShareLink": "string",
                "createdDateTime": "2022-09-09T18:13:43+0000"
            }
        ]
    },
    "states": [
        {
            "type": "IN_TRANSIT",
            "startDateTime": "2022-08-22T15:37:00+0000",
            "endDateTime": "2022-08-25T23:53:00+0000",
            "stopId": "133703df-3ce5-3a8f-9531-27fb23798139",
            "routeSegmentId": "914e66af-46c6-3d90-889a-422940d0a68a"
        },
        {
            "type": "AT_STOP",
            "startDateTime": "2022-08-25T23:53:00+0000",
            "endDateTime": "2022-09-01T21:36:00+0000",
            "stopId": "f2f7b4c5-125f-338b-8f8f-3a92745b57dd",
            "routeSegmentId": "914e66af-46c6-3d90-889a-422940d0a68a"
        }
    ],
    "events": [
        {
            "dateTime": "2022-08-22T15:37:00+0000",
            "receivedDateTime": "2022-10-11T21:26:00+0000",
            "type": "DEPARTURE_FROM_STOP",
            "stopId": "133703df-3ce5-3a8f-9531-27fb23798139",
            "routeSegmentId": "914e66af-46c6-3d90-889a-422940d0a68a"
        },
        {
            "dateTime": "2022-08-25T23:53:00+0000",
            "receivedDateTime": "2022-10-11T21:26:00+0000",
            "type": "ARRIVAL_AT_STOP",
            "stopId": "f2f7b4c5-125f-338b-8f8f-3a92745b57dd",
            "routeSegmentId": "914e66af-46c6-3d90-889a-422940d0a68a",
            "plannedDateTime": "2022-09-01T22:00:00+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 API Reference Documentation for more information on required and potential null fields.

See the Appendix for descriptions of the LTL Shipment Event Types, LTL Shipment State Types, and LTL 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.

Field	Description
`routeInfo`	An 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.stops`	A 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.id`	project44 ID of the stop the event is related to (referenced to as stopId in events payload).
`routeInfo.stops.type`	The type of the stop. For descriptions of specific stop types, see LTL Shipment Stop Types.
`routeInfo.stops.location`	An object that consists of the location name, identifiers, and coordinates.
`routeInfo.stops.location.name`	The name of the location - received by shipping line (no input from customer required).
`routeInfo.stops.location.identifiers`	A type:value pair.
`routeInfo.stops.location.coordinates`	The latitude and longitude of the location.
`routeInfo.routeSegments`	An array that describes the journey between two stops.
`routeInfo.routeSegments.id`	project44 ID of the route segment the event is related to (referenced to as `routeSegmentId` in events and positions payload)
`routeInfo.routeSegments.fromStopId`	project44 ID of where the route segment originates.
`routeInfo.routeSegments.toStopId`	project44 ID of where the route segment terminates.
`routeInfo.routeSegments.transportatioinMode`	The mode of transport used for the route segment.
`relatedShipments`	A BOL 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.
`states`	An array of all states the shipment was or currently is in.
`states.type`	The specific type of state the shipment was in. Valid values include `"UNKNOWN"`, `"AT_STOP"`, `"IN_TRANSIT"`, `"COMPLETED"`, `"SCHEDULED"`. See LTL Shipment State Types for a full list of the supported state types and their descriptions.
`states.startDateTime`	The time this state began.
`states.endDateTime`	The time that this state ended. May not be populated if the shipment is still in this state.
`states.stopId`	The ID of the related stop.routeSegmentId: the route segment ID this state occurred along.
`events`	An array of all events related to the shipment.
`events.dateTime`	The time at which the event took place (actual).
`events.estimateDateTime`	project44's latest estimated time for the event.
`events.plannedDateTime`	The 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.type`	The type of event that occurs. See LTL Shipment Event Types for a full list of supported event types and descriptions.
`events.description`	A description of the event that occurs (not available for all events)
`events.stopId`	The project44 ID of the stop the event is related to.
`events.receivedDateTime`	The last time information about event was modified.
`events.estimatedLastCalculatedDateTime`	The last time the estimate date time was modified.

Get Position History

Get information about an LTL 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.

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
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": "CAPACITY_PROVIDER_ACCOUNT_GROUP",
                "value": "string"
            }
        ],
        "shipmentShareLink": "string",
        "createdDateTime": "2022-09-09T18:13:43+0000",
        "relatedShipments": [
            {
                "id": "a2adac91-18ba-4fc5-b939-93a10f9a7406",
                "identifiers": [
                    {
                        "type": "BILL_OF_LADING",
                        "value": "string"
                    }
                ],
                "shipmentShareLink": "string",
                "createdDateTime": "2022-09-09T18:13:43+0000"
            }
        ]
    },
    "positions": [
        {
            "dateTime": "2022-09-01T22:30:00+0000",
            "routeSegmentId": "41d77999-5804-329a-92ca-090564639740",
            "latitude": -32.884075,
            "longitude": -71.67896
        }
    ]
}

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 API Reference documentation for more information on required and potential null fields.

See the Appendix for descriptions of the LTL Shipment Stop Types.

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.

Field	Description
`routeInfo`	An 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.stops`	A 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.id`	project44 ID of the stop the event is related to (referenced to as stopId in events payload).
`routeInfo.stops.type`	The type of the stop. For descriptions of specific stop types, see LTL Shipment Stop Types.
`routeInfo.stops.location`	An object that consists of the location name, identifiers, and coordinates.
`routeInfo.stops.location.name`	The name of the location – received by shipping line (no input from customer required).
`routeInfo.stops.location.identifiers`	A type:value pair.
`routeInfo.stops.location.coordinates`	The latitude and longitude of the location.
`routeInfo.routeSegments`	An array that describes the journey between two stops.
`routeInfo.routeSegments.id`	project44 ID of the route segment the event is related to (referenced to as `routeSegmentId` in events and positions payload)
`routeInfo.routeSegments.fromStopId`	project44 ID of where the route segment originates.
`routeInfo.routeSegments.toStopId`	project44 ID of where the route segment terminates.
`routeInfo.routeSegments.transportatioinMode`	The mode of transport used for the route segment.
`relatedShipments`	A BOL 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.
`positions`	An array of all geo-positions related to the shipment.
`positions.dateTime`	The time the recorded position.
`positions.receivedDateTime`	The time the position was received by project44.
`positions.routeSegmentId`	The ID of the route segment the stop is related to.

Get Route Information

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

Requirements

Have the following information available:

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

Worfklow

Complete the following steps.

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.
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": "CAPACITY_PROVIDER_ACCOUNT_GROUP",
                "value": "string"
            }
        ],
        "routeInfo": {
            "stops": [
                {
                    "id": "0f92db12-496c-4712-b3f1-42d87132aff1",
                    "type": "ORIGIN",
                    "location": {
                        "name": "Stop",
                        "identifiers": [
                            {
                                "type": "string",
                                "value": "string"
                            }
                        ],
                        "address": {
                            "addressLines": [
                                "string"
                            ],
                            "city": "string",
                            "country": "US"
                        },
                        "coordinates": {
                            "latitude": 32.8968,
                            "longitude": -97.038
                        }
                    }
                }
            ] 
        },       
        "shipmentShareLink": "string",
        "createdDateTime": "2022-09-09T18:13:43+0000",
        "relatedShipments": [
            {
                "id": "a2adac91-18ba-4fc5-b939-93a10f9a7406",
                "identifiers": [
                    {
                        "type": "BILL_OF_LADING",
                        "value": "string"
                    }
                ],
                "shipmentShareLink": "string",
                "createdDateTime": "2022-09-09T18:13:43+0000"
            }
        ]
    } 
}

See the Appendix for descriptions LTL Shipment Stop Types.

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.

Field	Description
`routeInfo`	An 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.stops`	A 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.id`	project44 ID of the stop the event is related to (referenced to as stopId in events payload).
`routeInfo.stops.type`	The type of the stop. For descriptions of specific stop types, see LTL Shipment Stop Types.
`routeInfo.stops.location`	An object that consists of the location name, identifiers, and coordinates.
`routeInfo.stops.location.name`	The name of the location – received by shipping line (no input from customer required).
`routeInfo.stops.location.identifiers`	A type:value pair.
`routeInfo.stops.location.coordinates`	The latitude and longitude of the location.
`routeInfo.routeSegments`	An array that describes the journey between two stops.
`routeInfo.routeSegments.id`	project44 ID of the route segment the event is related to (referenced to as `routeSegmentId` in events and positions payload)
`routeInfo.routeSegments.fromStopId`	project44 ID of where the route segment originates.
`routeInfo.routeSegments.toStopId`	project44 ID of where the route segment terminates.
`routeInfo.routeSegments.transportatioinMode`	The mode of transport used for the route segment.
`relatedShipments`	A BOL 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 LTL 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.

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.
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": "CAPACITY_PROVIDER_ACCOUNT_GROUP",
                "value": "string"
            }
        ],
        "shipmentShareLink": "string",
        "createdDateTime": "2022-09-09T18:13:43+0000",
        "relatedShipments": [
            {
                "id": "a2adac91-18ba-4fc5-b939-93a10f9a7406",
                "identifiers": [
                    {
                        "type": "BILL_OF_LADING",
                        "value": "string"
                    }
                ],
                "shipmentShareLink": "string",
                "createdDateTime": "2022-09-09T18:13:43+0000"
            }
        ]
    },
    "states": [
        {
            "type": "IN_TRANSIT",
            "startDateTime": "2022-08-22T15:37:00+0000",
            "endDateTime": "2022-08-25T23:53:00+0000",
            "stopId": "133703df-3ce5-3a8f-9531-27fb23798139",
            "routeSegmentId": "914e66af-46c6-3d90-889a-422940d0a68a"
        },
        {
            "type": "AT_STOP",
            "startDateTime": "2022-08-25T23:53:00+0000",
            "endDateTime": "2022-09-01T21:36:00+0000",
            "stopId": "f2f7b4c5-125f-338b-8f8f-3a92745b57dd",
            "routeSegmentId": "914e66af-46c6-3d90-889a-422940d0a68a"
        }
    ],
    "events": [
        {
            "dateTime": "2022-08-22T15:37:00+0000",
            "receivedDateTime": "2022-10-11T21:26:00+0000",
            "type": "DEPARTURE_FROM_STOP",
            "stopId": "133703df-3ce5-3a8f-9531-27fb23798139",
            "routeSegmentId": "914e66af-46c6-3d90-889a-422940d0a68a"
        },
        {
            "dateTime": "2022-08-25T23:53:00+0000",
            "receivedDateTime": "2022-10-11T21:26:00+0000",
            "type": "ARRIVAL_AT_STOP",
            "stopId": "f2f7b4c5-125f-338b-8f8f-3a92745b57dd",
            "routeSegmentId": "914e66af-46c6-3d90-889a-422940d0a68a",
            "plannedDateTime": "2022-09-01T22:00:00+0000"
        }
    ],
    "positions": [
        {
            "dateTime": "2022-09-01T22:30:00+0000",
            "routeSegmentId": "41d77999-5804-329a-92ca-090564639740",
            "latitude": -32.884075,
            "longitude": -71.67896
        }
    ]
}

See the Appendix for descriptions LTL Shipment Event Types, LTL Shipment State Types, and LTL 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

Field	Description
`routeInfo`	An 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.stops`	A 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.id`	project44 ID of the stop the event is related to (referenced to as stopId in events payload).
`routeInfo.stops.type`	The type of the stop. For descriptions of specific stop types, see LTL Shipment Stop Types returned by this endpoint.
`routeInfo.stops.location`	An object that consists of the location name, identifiers, and coordinates.
`routeInfo.stops.location.name`	The name of the location – received by shipping line (no input from customer required).
`routeInfo.stops.location.identifiers`	A type:value pair.
`routeInfo.stops.location.coordinates`	The latitude and longitude of the location.
`routeInfo.routeSegments`	An array that describes the journey between two stops.
`routeInfo.routeSegments.id`	project44 ID of the route segment the event is related to (referenced to as `routeSegmentId` in events and positions payload)
`routeInfo.routeSegments.fromStopId`	project44 ID of where the route segment originates.
`routeInfo.routeSegments.toStopId`	project44 ID of where the route segment terminates.
`routeInfo.routeSegments.transportatioinMode`	The mode of transport used for the route segment.
`relatedShipments`	A BOL 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.
`states`	An array of all states the shipment was or currently is in.
`states.type`	The specific type of state the shipment was in. Valid values include `"UNKNOWN"`, `"AT_STOP"`, `"IN_TRANSIT"`, `"COMPLETED"`, `"SCHEDULED"`. See LTL Shipment State Types for a full list of the supported state types and their descriptions.
`states.startDateTime`	The time this state began.
`states.endDateTime`	The time that this state ended. May not be populated if the shipment is still in this state.
`states.stopId`	The ID of the related stop.routeSegmentId: the route segment ID this state occurred along.
`events`	An array of all events related to the shipment.
`events.dateTime`	The time at which the event took place (actual).
`events.estimateDateTime`	project44’s latest estimated time for the event.
`events.plannedDateTime`	The 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.type`	The type of event that occurs. See LTL Shipment Event Types for a full list of supported event types and descriptions.
`events.description`	A description of the event that occurs (not available for all events)
`events.stopId`	The project44 ID of the stop the event is related to.
`events.routeSegmentsId`	The project44 ID of the route segment the stop is related to. See Route Segment Identifiers for more information on the specific identifier types.
`events.receivedDateTime`	The last time information about event was modified.
`events.estimatedLastCalculatedDateTime`	The last time the estimate date time was modified.
`positions`	An array of all geo-positions related to the shipment.
`positions.dateTime`	The time the recorded position.
`positions.receivedDateTime`	The time the position was received by project44.
`positions.routeSegmentId`	The ID of the route segment the stop is related to.

Get Event History

Requirements

Workflow

Expected System Response

Errors

Field and Objects

Get Position History

Requirements

Workflow

Expected System Response

Error

Fields and Objects

Get Route Information

Requirements

Worfklow

Expected System Response

Errors

Fields and Objects

Get Full Tracking History

Requirements

Workflow

Expected System Response

Errors

Fields and Objects

Was this helpful?