Send Tracking Updates

Push a status update for an initialized Parcel shipment.

The estimatedTimeOfArrival field will be honored ONLY when it is sent with an ETA event type. When estimatedTimeOfArrival is sent with other event types, it will be ignored.

Once a valid time is sent for estimatedTimeOfArrival, it is preserved until estimatedTimeOfArrival is sent as NULL. Project44 does not automatically clear the estimatedTimeOfArrival once it is set.

Send a Position Update, Out for Delivery, Arrived at Stop, or Departed Stop Event Update

Requirements

Have the following information:

Carrier Identifier (SCAC, DOT_NUMBER, or MC_NUMBER)
Shipment Identifier (TRACKING_NUMBER)
Location Information (city, state, postal code, and country)
Timestamp
Event Type (OUT_FOR_DELIVERY,ARRIVED_AT_STOP, DEPARTED_STOP, POSITION_UPDATE)

Workflow

Prepare POST request to api/v4/capacityproviders/parcel/shipments/statusupdates. For example,

{
    "carrierIdentifier": {
        "type": "SCAC",
        "value": "FXFE"
    },
    "shipmentIdentifier": [
        {
            "type": "TRACKING_NUMBER",
            "value": "1234567890"
        }
    ],
    "location": {
        "address": {
            "country": "US",
            "postalCode": "60654",
            "addressLines": [
                "222 W Merchandise Mart Plaza"
            ],
            "city": "Chicago",
            "state": "IL"
        },
        "geoCoordinates": {
            "latitude": 41.88837,
            "longitude": -87.63536
        }
    },
    "timestamp": "2020-07-10T01:30:00-0500",
    "eventType": "POSITION_UPDATE",
    "statusDescription": "XYZ"
}

Send the request.

Fields and Objects

Element	Description	Type	Notes
`carrierIdentifier.type`	The Carrier identifier type.	`string`	Required. Valid values are `SCAC`, `DOT_NUMBER`, `MC_NUMBER`.
`carrierIdentifier.value`	The value of the Carrier identifier.	`string`	Required.
`shipmentIdentifier.type`	The type of shipment identifier	`string`	Required. Valid value is `TRACKING_NUMBER`.
`shipmentIdentifier.value`	The value of the shipment identifier	`string`	Required.
`location.address.country`	The country of the current shipment location.	`string`	Required.
`location.address.postalCode`	The postal code of the current shipment location.	`string`	Required.
`location.address.address`	The street address of the current shipment location.	`string array`	Required.
`location.address.city`	The city of the current shipment location.	`string`	Required.
`location.address.state`	The state of the current shipment location.	`string`	Required.
`location.geoCoordinates.latitude`	The approximate geographic latitude of the current shipment location.	`number <float>`	Valid values are `[-90...90]`.
`location.geoCoordinates.longitude`	The approximate geographic longitude of the current shipment location.	`number <float>`	Valid values are `[-180...180]`.
`timestamp`	The at which the status update event occurred.	`string`	Required. The timezone format is ISO 8601. A timezone offset (`Z`) must be provided: `yyyy-MM-dd'T'HH:mm:ssZ`. For example, `2019-11-14T12:30:00-0500`.
`eventType`	The event for this status update.	`string`	Required. Valid values are `OUT_FOR_DELIVERY`,`ARRIVED_AT_STOP`, `DEPARTED_STOP`, `POSITION_UPDATE`. See the Appendix for event descriptions.
`statusDescription`	Additional details for the shipment status update.	`string`

Expected System Response

The request is successfully submitted and confirmed when a 202 ACCEPTED response is received.

{
    "carrierIdentifier": {
        "type": "SCAC",
        "value": "FXFE"
    },
    "shipmentIdentifier": [
        {
            "type": "TRACKING_NUMBER",
            "value": "1234567890"
        }
    ],
    "location": {
        "address": {
            "country": "US",
            "postalCode": "60654",
            "addressLines": [
            "222 W Merchandise Mart Plaza"
            ],
            "city": "Chicago",
            "state": "IL"
        },
        "geoCoordinates": {
            "latitude": 41.88837,
            "longitude": -87.63536
        }
    },
    "timestamp": "2020-07-10T01:30:00-0500",
    "eventType": "POSITION_UPDATE",
    "statusDescription": "XYZ"
}

Fields and Objects

Element	Description	Type	Notes
`carrierIdentifier.type`	The Carrier identifier type.	`string`	Valid values are `SCAC`, `DOT_NUMBER`, `MC_NUMBER`.
`carrierIdentifier.value`	The value of the Carrier identifier.	`string`
`shipmentIdentifier.type`	The type of shipment identifier	`string`	Valid value is `TRACKING_NUMBER`.
`shipmentIdentifier.value`	The value of the shipment identifier	`string`
`location.address.country`	The country of the current shipment location.	`string`
`location.address.postalCode`	The postal code of the current shipment location.	`string`
`location.address.address`	The street address of the current shipment location.	`string array`
`location.address.city`	The city of the current shipment location.	`string`
`location.address.state`	The state of the current shipment location.	`string`
`location.geoCoordinates.latitude`	The approximate geographic latitude of the current shipment location.	`number <float>`	Valid values are `[-90...90]`.
`location.geoCoordinates.longitude`	The approximate geographic longitude of the current shipment location.	`number <float>`	Valid values are `[-180...180]`.
`timestamp`	The at which the status update event occurred.	`string`	The timezone format is ISO 8601: `yyyy-MM-dd'T'HH:mm:ssZ`. `Z` is the timezone offset. For example, `2019-11-14T12:30:00-0500`.
`eventType`	The event for this status update.	`string`	Valid values are `OUT_FOR_DELIVERY`,`ARRIVED_AT_STOP`, `DEPARTED_STOP`, or `POSITION_UPDATE`. See the Appendix event descriptions
`statusDescription`	Additional details for the shipment status update.	`string`

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.

Send an ETA Event Update

Requirements

Have the following information:

Carrier Identifier (SCAC, DOT_NUMBER, or MC_NUMBER)
Shipment Identifier (TRACKING_NUMBER)
Timestamp
Estimated Time of Arrival
Event Type (ETA)

Workflow

Prepare POST request to api/v4/capacityproviders/parcel/shipments/statusupdates. For example,

{
    "carrierIdentifier": {
        "type": "SCAC",
        "value": "FXFE"
    },
    "shipmentIdentifier": [
        {
            "type": "TRACKING_NUMBER",
            "value": "1234567890"
        }
    ],
    "timestamp": "2020-07-10T01:30:00-0500",
    "eventType": "ETA",
    "estimatedTimeOfArrival": "2020-07-10T01:30:00-0500"
}

Send the request.

Fields and Objects

Element	Description	Type	Notes
`carrierIdentifier.type`	The Carrier identifier type.	`string`	Required. Valid values are `SCAC`, `DOT_NUMBER`, `MC_NUMBER`.
`carrierIdentifier.value`	The value of the Carrier identifier.	`string`	Required.
`shipmentIdentifier.type`	The type of shipment identifier	`string`	Required. Valid value is `TRACKING_NUMBER`.
`shipmentIdentifier.value`	The value of the shipment identifier	`string`	Required.
`timestamp`	The at which the status update event occurred.	`string`	Required. The timezone format is ISO 8601. A timezone offset (`Z`) must be provided: `yyyy-MM-dd'T'HH:mm:ssZ`. For example, `2019-11-14T12:30:00-0500`.
`estimatedTimeOfArrival`	The estimated time of shipment delivery at the destination stop.	`string` (Accepts `NULL`)	Required. The timezone format is ISO 8601. A timezone offset (`Z`) must be provided: `yyyy-MM-dd'T'HH:mm:ssZ`. For example, `2019-11-14T12:30:00-0500`. Use `NULL` to clear the value that is set.
`eventType`	The event for this status update.	`string`	Required. Valid value is `ETA`. See the Appendix for the event description.

Expected System Response

The request is successfully submitted and confirmed when a 202 ACCEPTED response is received.

{
    "carrierIdentifier": {
        "type": "SCAC",
        "value": "FXFE"
    },
    "shipmentIdentifier": {
        "type": "TRACKING_NUMBER",
        "value": "1234567890"
    },
    "timestamp": "2020-07-10T01:30:00-0500",
    "eventType": "ETA",
    "estimatedTimeOfArrival": "2020-07-10T01:30:00-0500"
}

Fields and Objects

Element	Description	Type	Notes
`carrierIdentifier.type`	The Carrier identifier type.	`string`	Valid values are `SCAC`, `DOT_NUMBER`, `MC_NUMBER`.
`carrierIdentifier.value`	The value of the Carrier identifier.	`string`
`shipmentIdentifier.type`	The type of shipment identifier	`string`	Valid value is `TRACKING_NUMBER`.
`shipmentIdentifier.value`	The value of the shipment identifier	`string`
`timestamp`	The at which the status update event occurred.	`string`	The timezone format is ISO 8601: `yyyy-MM-dd'T'HH:mm:ssZ`. `Z` is the timezone offset. For example, `2019-11-14T12:30:00-0500`.
`estimatedTimeOfArrival`	The estimated time of shipment delivery at the destination stop.	`string`	The timezone format is ISO 8601: `yyyy-MM-dd'T'HH:mm:ssZ`. `Z` is the timezone offset. For example, `2019-11-14T12:30:00-0500`.
`eventType`	The event for this status update.	`string`	Valid value is `ETA`. See the Appendix for the event description.

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.

Send Any Other Event Update

Requirements

Have the following information:

Carrier Identifier (SCAC, DOT_NUMBER, or MC_NUMBER)
Shipment Identifier (TRACKING_NUMBER)
Timestamp
Event Type (DELAYED, HELD, EXCEPTION, DELIVERY_MISSED, LOADED_FOR_DELIVERY, RETURN_TO_SENDER, SHIPMENT_RECEIVED, SHIPMENT_CREATED, AVAILABLE_FOR_PICKUP, PICKED_UP, DELIVERED, CANCELLED)

Workflow

Prepare POST request to api/v4/capacityproviders/parcel/shipments/statusupdates. For example,

{
    "carrierIdentifier": {
        "type": "SCAC",
        "value": "FXFE"
    },
    "shipmentIdentifier": [
        {
            "type": "TRACKING_NUMBER",
            "value": "1234567890"
        }
    ],
    "timestamp": "2020-07-10T01:30:00-0500",
    "eventType": "POSITION_UPDATE"
}

Send the request.

Fields and Objects

Element	Description	Type	Notes
`carrierIdentifier.type`	The Carrier identifier type.	`string`	Required. Valid values are `SCAC`, `DOT_NUMBER`, `MC_NUMBER`.
`carrierIdentifier.value`	The value of the Carrier identifier.	`string`	Required.
`shipmentIdentifier.type`	The type of shipment identifier	`string`	Required. Valid value is `TRACKING_NUMBER`.
`shipmentIdentifier.value`	The value of the shipment identifier	`string`	Required.
`location.address.country`	The country of the current shipment location.	`string`	Suggested for `EXCEPTION`, `LOADED_FOR_DELIVERY`, `AVAILABLE_FOR_PICKUP`, and `PICKED_UP` event types.
`location.address.postalCode`	The postal code of the current shipment location.	`string`	Suggested for `EXCEPTION`, `LOADED_FOR_DELIVERY`, `AVAILABLE_FOR_PICKUP`, and `PICKED_UP` event types.
`location.address.address`	The street address of the current shipment location.	`string array`	Suggested for `EXCEPTION`, `LOADED_FOR_DELIVERY`, `AVAILABLE_FOR_PICKUP`, and `PICKED_UP` event types.
`location.address.city`	The city of the current shipment location.	`string`	Suggested for `EXCEPTION`, `LOADED_FOR_DELIVERY`, `AVAILABLE_FOR_PICKUP`, and `PICKED_UP` event types.
`location.address.state`	The state of the current shipment location.	`string`	Suggested for `EXCEPTION`, `LOADED_FOR_DELIVERY`, `AVAILABLE_FOR_PICKUP`, and `PICKED_UP` event types.
`timestamp`	The at which the status update event occurred.	`string`	Required. The timezone format is ISO 8601. A timezone offset (`Z`) must be provided: `yyyy-MM-dd'T'HH:mm:ssZ`. For example, `2019-11-14T12:30:00-0500`.
`eventType`	The event for this status update.	`string`	Required. Valid values are `EXCEPTION`, `LOADED_FOR_DELIVERY`, `AVAILABLE_FOR_PICKUP`, and `PICKED_UP`. See the Appendix for event descriptions.
`statusDescription`	Additional details for the shipment status update.	`string`

Expected System Response

The request is successfully submitted and confirmed when a 202 ACCEPTED response is received.

{
    "carrierIdentifier": {
        "type": "SCAC",
        "value": "FXFE"
    },
    "shipmentIdentifier": [
        {
            "type": "TRACKING_NUMBER",
            "value": "1234567890"
        }
    ],
    "timestamp": "2020-07-10T01:30:00-0500",
    "eventType": "POSITION_UPDATE"
}

Fields and Objects

Element	Description	Type	Notes
`carrierIdentifier.type`	The Carrier identifier type.	`string`
`carrierIdentifier.value`	The value of the Carrier identifier.	`string`
`shipmentIdentifier.type`	The type of shipment identifier	`string`
`shipmentIdentifier.value`	The value of the shipment identifier	`string`
`timestamp`	The at which the status update event occurred.	`string`	The timezone format is ISO 8601: `yyyy-MM-dd'T'HH:mm:ssZ`. `Z` is the timezone offset. For example, `2019-11-14T12:30:00-0500`.
`eventType`	The event for this status update.	`string`	Valid values are `EXCEPTION`, `LOADED_FOR_DELIVERY`, `AVAILABLE_FOR_PICKUP`, and `PICKED_UP`. See the Appendix for event descriptions.
`statusDescription`	Additional details for the shipment status update.	`string`

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.

Send Tracking Updates

Send a Position Update, Out for Delivery, Arrived at Stop, or Departed Stop Event Update

Requirements

Workflow

Expected System Response

Errors

Send an ETA Event Update

Requirements

Workflow

Expected System Response

Errors

Send Any Other Event Update

Requirements

Workflow

Expected System Response

Errors

Was this helpful?