Last updated

Introduction

Send tracking updates about a Truckload shipment. A shipment must be created and added to project44's network before you can send tracking data. Our tracking window typically begins 90 minutes before the pickup window begins and ends when the shipment is marked as DELIVERED or when 14 days have passed since the delivery appointment time.

As you get started, here are some best practices to keep in mind:

  • Each API Request must be preceded by this line: Authorization:Bearer access_token
  • Build for future customers by not hard-coding the Customer ID.
  • Keep your client application continually authorized by having your client application’s receipt of the 401 Invalid or missing credentials HTTP status code in the API Response generate a Request for a new access token using its client credentials.
  • Send data as soon as it is available (e.g., Once a pickup has been scheduled). project44 can start receiving updates immediately.
  • For a customer to get tracking updates, the endpoint must be hit while the shipment is still actively in transit.
  • Send only one status event per API Request.
  • Only send a status event when the lifecycle stage changes. Repeatedly sending the same status event can confound the project44 system logic.
  • Send final status update once the delivery has been made. This status update is REQUIRED for project44’s logic to tell the customer the shipment has been successfully delivered.

Send Any Status Update

Send an update for each status event throughout the shipment's transit.

Requirements

Have the following information:

  • Customer Account ID
  • Carrier ID: SCAC
  • Shipment ID: PRO, BILL_OF_LADING, CUSTOMER_REFERENCE, PICKUP, or PURCHASE_ORDER
  • Status Code
  • Stop Type if the Status Code is DELIVERED, PICKED_UP, ARRIVED_AT_TERMINAL, or DEPARTED_TERMINAL.
  • Stop Number if the Status Code is DELIVERED, PICKED_UP, ARRIVED_AT_TERMINAL, or DEPARTED_TERMINAL.
  • OPTIONAL Stop Address if the Status Code is DELIVERED, PICKED_UP, ARRIVED_AT_TERMINAL, or DEPARTED_TERMINAL.
  • Timestamp for the Status Update

Workflow

  1. Prepare a POST request to /api/v4/capacityproviders/ltl/shipments/statusupdates.
  2. Complete all required information.
JSON
{
 "customerAccount": {
    "accountIdentifier": "string"
  },
  "carrierIdentifier": {
    "type": "SCAC",
    "value": "string"
  },
  "shipmentIdentifiers": [
    {
      "type": "PRO",
      "value": "string",
      "primaryForType": true
    }
  ],
  "statusCode": "PICKED_UP",
  "stopType": "ORIGIN",
  "stopNumber": 1,
  "location": {
    "address": {
      "postalCode": "string",
      "addressLines": [
        "string"
      ],
      "city": "Berlin",
      "state": "string",
      "country": "DE"
    }
  },
  "timestamp": "2021-03-01T16:30:00+0000"
}
  1. Send the request.
  2. Repeat this process for each subsequent event until the shipment has been delivered.

Expected Response

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

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.

Fields and Objects

The table below describes only the minimum relevant fields necessary for updating the tracking status of a LTL shipment. These are also the same fields returned in the API Response 202 Accepted.

FieldDescription
customerAccountAn array of the account information for the customer of the shipment.
customerAccount.accountIdentifierThe account identifier for the customer of the shipment. This is used to identify the customer in project44's system.
carrierIdentifierAn array that includes your capacity provider identifier information.
carrierIdentifier.typeThe type of your capacity identifier. SCAC is the only type accepted in this API.
carrierIdentifier.valueThe value of your identifier.
shipmentIdentifiersThis array includes the list if shipment IDs that are used to track the shipment.
shipmentIdentifiers.typeThe type of the shipment ID. At least one identifier in this array must be a PRO Number (shipmentIdentifiers.type = PRO). Other valid values include: BILL_OF_LADING, CUSTOMER_REFERENCE, PICKUP, PURCHASE_ORDER, or EXTERNAL.
shipmentIdentifiers.valueThe value of the shipment ID.
shipmentIdentifiers.primaryForTypeThis field indicates if the shipment ID is the primary shipment ID. The primary shipment ID will always be attempted before other identifiers.
statusCodeThe project44 status code for this status update. This field must always be populated. Valid values include READY_FOR_PICKUP, UPDATED_PICKUP_APPT, EXCEPTION, PICKED_UP, ARRIVED_AT_TERMINAL, REWEIGHT_RECLASS, INFO, UPDATED_DELIVERY_APPT, DEPARTED_TERMINAL, OUT_FOR_DELIVERY, DELIVERED.
stopType*The type of stop. User-defined stops will always have the customer locations ORIGIN and DESTINATION. TERMINAL stops types are capacity provider redistribution centers and will be inserted dynamically as you return them.
stopNumber*The stop number, where the ORIGIN is 1 and the DESTINATION has the largest number. Any stops in between are numbered in order of appointment time. You can leave this field empty during shipment creation. The DESTINATION stop number will change dynamically as terminals are discovered along the shipment route from ORIGIN to DESTINATION. The stopType is the most useful field for easily and reliably identifying the ORIGIN and DESTINATION.
location*OPTIONAL. This object contains data about the stop's location, including address and contact information. Full address and contact information should be included during shipment creation. Terminals may or may not have complete address and contact information.
location.address*OPTIONAL. This object contains the stop's address information.
location.address.postalCode*OPTIONAL. The ZIP or postal code of the stop location.
location.address.addressLines*OPTIONAL. An array of strings with address information that includes the street name, number, direction, PO Box, etc. for the stop location. NOTE: Currently, only three address lines are permitted.
location.address.city*OPTIONAL. The name of the city or town of the stop location.
location.address.state*OPTIONAL. The abbreviation of the state, province, district, etc. of the stop location. This is only applicable to locations in North America. For locations outside of North America, leave this blank.
location.address.country*OPTIONAL. The abbreviation of the country (using ISO 3166 standards) of the stop location. The default is US.
timestampThe timestamp of the status update. If provided in UTC, add +0000 at the end of the string. If provided in local time, add the applicable UTC offset (for example, add +0100 if the time was given in CET) at the end of the string.

*Only include if the statusCode is DELIVERED, PICKED_UP, ARRIVED_AT_TERMINAL, or DEPARTED_TERMINAL.

Send Only Pickup and Delivery Status Updates

Send status updates only for Pickup and Delivery events.

Requirements

Have the following information:

  • Customer Account ID
  • Carrier ID: SCAC
  • Shipment ID: PRO, BILL_OF_LADING, CUSTOMER_REFERENCE, PICKUP, or PURCHASE_ORDER
  • Status Code: PICKED_UP (for a pick-up event) or DELIVERED (for a delivery event)
  • Stop Types for the Pickup and Delivery Events
  • Stop Numbers for the Pickup and Delivery Events
  • OPTIONAL Stop Locations for the Pickup and Delivery Events
  • Timestamps for the Pickup and Delivery Events

Workflow

Complete these steps:

  1. Prepare a POST request to /api/v4/capacityproviders/ltl/shipments/statusupdates.
  2. Complete all required information for the PICKUP update.
JSON
{ 
 "customerAccount": {
    "accountIdentifier": "string"
  },
  "carrierIdentifier": {
    "type": "SCAC",
    "value": "string"
  },
  "shipmentIdentifiers": [
    {
      "type": "PRO",
      "value": "string",
      "primaryForType": true
    }
  ],
  "statusCode": "PICKED_UP",
  "stopType": "ORIGIN",
  "stopNumber": 1,
  "timestamp": "2021-08-01T12:07:34+0000"
}
  1. Send the request.
  2. Repeat this process to send the Delivery update once the shipment has been delivered.

Expected System Response

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

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.

Fields and Objects

The table below describes only the minimum relevant fields necessary for updating the tracking status of a LTL shipment. These are also the same fields returned in the API Response 202 Accepted.

FieldDescription
customerAccountAn array of the account information for the customer of the shipment.
customerAccount.accountIdentifierThe account identifier for the customer of the shipment. This is used to identify the customer in project44's system.
carrierIdentifierAn array that includes your capacity provider identifier information.
carrierIdentifier.typeThe type of your capacity identifier. SCAC is the only type accepted in this API.
carrierIdentifier.valueThe value of your identifier.
shipmentIdentifiersThis array includes the list if shipment IDs that are used to track the shipment.
shipmentIdentifiers.typeThe type of the shipment ID. At least one identifier in this array must be a PRO Number (shipmentIdentifiers.type = PRO). Other valid values include: BILL_OF_LADING, CUSTOMER_REFERENCE, PICKUP, PURCHASE_ORDER, or EXTERNAL.
shipmentIdentifiers.valueThe value of the shipment ID.
shipmentIdentifiers.primaryForTypeThis field indicates if the shipment ID is the primary shipment ID. The primary shipment ID will always be attempted before other identifiers.
statusCodeThe project44 status code for this status update. This field must always be populated. Valid values include PICKED_UP or DELIVERED.
stopTypeThe type of stop. User-defined stops will always have the customer locations ORIGIN and DESTINATION.
stopNumberThe stop number, where the ORIGIN is 1 and the DESTINATION has the largest number. Any stops in between are numbered in order of appointment time. You can leave this field empty during shipment creation. The DESTINATION stop number will change dynamically as terminals are discovered along the shipment route from ORIGIN to DESTINATION. The stopType is the most useful field for easily and reliably identifying the ORIGIN and DESTINATION.
locationOPTIONAL. This object contains data about the stop's location, including address and contact information. Full address and contact information should be included during shipment creation. Terminals may or may not have complete address and contact information.
location.addressOPTIONAL. This object contains the stop's address information.
location.address.postalCodeOPTIONAL. The ZIP or postal code of the stop location.
location.address.addressLinesOPTIONAL. An array of strings with address information that includes the street name, number, direction, PO Box, etc. for the stop location. NOTE: Currently, only three address lines are permitted.
location.address.cityOPTIONAL. The name of the city or town of the stop location.
location.address.stateOPTIONAL. The abbreviation of the state, province, district, etc. of the stop location. This is only applicable to locations in North America. For locations outside of North America, leave this blank.
location.address.countryOPTIONAL. The abbreviation of the country (using ISO 3166 standards) of the stop location. The default is US.
timestampThe timestamp of the status update. If provided in UTC, add +0000 at the end of the string. If provided in local time, add the applicable UTC offset (for example, add +0100 if the time was given in CET) at the end of the string.

Send a Status Update with a project44 Exception Code

project44’s API accepts additional information from Carriers when there are unexpected events causing delays or issues within the shipment lifecycle. Those unexpected events are called exception codes and can be provided in the statusReason section of the request body in the predefined API fields:

  • reasonSummaryCode
  • reasonDetailCode
  • reasonDescription

There are hard dependencies for providing exception codes that can be accepted and processed by project44’s API. Map project44’s exception codes as accurately as possible. See the exception codes in the Appendix for samples of mapping rules and a mapping table with all available exception codes. If you are not entirely sure how to map your codes against project44 codes, please contact project44 Integration Manager accountable for your project.

The reasonDetailCode is related to and has impact on the reasonSummaryCode. This relationship should be taken into consideration during mapping.

Requirements

Have the following information

  • Customer Account ID
  • Carrier ID: SCAC
  • Shipment ID: PRO, BILL_OF_LADING, CUSTOMER_REFERENCE, PICKUP, or PURCHASE_ORDER
  • Status Code
  • Stop Type if the Status Code is DELIVERED, PICKED_UP, ARRIVED_AT_TERMINAL, or DEPARTED_TERMINAL.
  • Stop Number if the Status Code is DELIVERED, PICKED_UP, ARRIVED_AT_TERMINAL, or DEPARTED_TERMINAL.
  • OPTIONAL Stop Location if the Status Code is DELIVERED, PICKED_UP, ARRIVED_AT_TERMINAL, or DEPARTED_TERMINAL.
  • Timestamp for the Status Update
  • Status Reason Summary and Detail Codes (See Appendix for a list of project44 exception codes)

Workflow

Complete these steps:

  1. Prepare a POST request to /api/v4/capacityproviders/ltl/shipments/statusupdates.
  2. Complete all required information. For example,
 { 
  "customerAccount": {
    "accountIdentifier": "string"
  },
  "carrierIdentifier": {
    "type": "SCAC",
    "value": "string"
  },
  "shipmentIdentifiers": [
    {
      "type": "PRO",
      "value": "string",
      "primaryForType": true
    }
  ],
  "statusCode": "EXCEPTION",
  "statusReason": {
    "reasonSummaryCode": "APPOINTMENT_ISSUE",
    "reasonDetailCode": "DELIVERY_ATTEMPTED_APPOINTMENT",
    "description": "string"
  },
  "stopType": "DESTINATION",
  "stopNumber": 2,
  "timestamp": "2021-08-04T12:07:34+0000"
}
  1. Send the request.

See additional Exception Code Payload Examples in the Appendix for more samples of using project44 and non-project44 exception codes.

Expected System Response

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

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.

Fields and Objects

The table below describes only the minimum relevant fields necessary for updating the tracking status of a LTL shipment with a project44 exception code. These are also the same fields returned in the API Response 202 Accepted.

FieldDescription
customerAccountAn array of the account information for the customer of the shipment.
customerAccount.accountIdentifierThe account identifier for the customer of the shipment. This is used to identify the customer in project44's system.
carrierIdentifierAn array that includes your capacity provider identifier information.
carrierIdentifier.typeThe type of your capacity identifier. SCAC is the only type accepted in this API.
carrierIdentifier.valueThe value of your identifier.
shipmentIdentifiersThis array includes the list if shipment IDs that are used to track the shipment.
shipmentIdentifiers.typeThe type of the shipment ID. At least one identifier in this array must be a PRO Number (shipmentIdentifiers.type = PRO). Other valid values include: BILL_OF_LADING, CUSTOMER_REFERENCE, PICKUP, PURCHASE_ORDER, or EXTERNAL.
shipmentIdentifiers.valueThe value of the shipment ID.
shipmentIdentifiers.primaryForTypeThis field indicates if the shipment ID is the primary shipment ID. The primary shipment ID will always be attempted before other identifiers.
statusCodeThe project44 status code for this status update. This field must always be populated. Valid values include READY_FOR_PICKUP, UPDATED_PICKUP_APPT, EXCEPTION, PICKED_UP, ARRIVED_AT_TERMINAL, REWEIGHT_RECLASS, INFO, UPDATED_DELIVERY_APPT, DEPARTED_TERMINAL, OUT_FOR_DELIVERY, DELIVERED.
statusReasonThe reason for the status. This is an opportunity to provide additional details for the status update.
statusReason.reasonSummaryCodeThe reason summary code for the status of the status update. See project44 Exception Codes for valid values.
statusReason.reasonDetailCodeThe reason detail code for the status of the status update. The reasonDetailCode is related to and has impact on the reasonSummaryCode. This relationship should be taken into consideration during mapping. See project44 Exception Codes for valid values.
stopType*The type of stop. User-defined stops will always have the customer locations ORIGIN and DESTINATION. TERMINAL stops types are capacity provider redistribution centers and will be inserted dynamically as you return them.
stopNumber*The stop number, where the ORIGIN is 1 and the DESTINATION has the largest number. Any stops in between are numbered in order of appointment time. You can leave this field empty during shipment creation. The DESTINATION stop number will change dynamically as terminals are discovered along the shipment route from ORIGIN to DESTINATION. The stopType is the most useful field for easily and reliably identifying the ORIGIN and DESTINATION.
location*OPTIONAL. This object contains data about the stop's location, including address and contact information. Full address and contact information should be included during shipment creation. Terminals may or may not have complete address and contact information.
location.address*OPTIONAL. This object contains the stop's address information.
location.address.postalCode*OPTIONAL. The ZIP or postal code of the stop location.
location.address.addressLines*OPTIONAL. An array of strings with address information that includes the street name, number, direction, PO Box, etc. for the stop location. NOTE: Currently, only three address lines are permitted.
location.address.city*OPTIONAL. The name of the city or town of the stop location.
location.address.state*OPTIONAL. The abbreviation of the state, province, district, etc. of the stop location. This is only applicable to locations in North America. For locations outside of North America, leave this blank.
location.address.country*OPTIONAL. The abbreviation of the country (using ISO 3166 standards) of the stop location. The default is US.
timestampThe timestamp of the status update. If provided in UTC, add +0000 at the end of the string. If provided in local time, add the applicable UTC offset (for example, add +0100 if the time was given in CET) at the end of the string.

*Only include if the statusCode is DELIVERED, PICKED_UP, ARRIVED_AT_TERMINAL, or DEPARTED_TERMINAL.

Send a Status Update with a non-project44 Exception Code

Send a non-project44 exception code in the status update when an unexpected event causes delays or issues within the shipment lifecycle.

Requirements

Have the following information:

  • Customer Account ID
  • Carrier ID: SCAC
  • Shipment ID: PRO, BILL_OF_LADING, CUSTOMER_REFERENCE, PICKUP, or PURCHASE_ORDER
  • Status Code
  • Stop Type if the Status Code is DELIVERED, PICKED_UP, ARRIVED_AT_TERMINAL, or DEPARTED_TERMINAL.
  • Stop Number if the Status Code is DELIVERED, PICKED_UP, ARRIVED_AT_TERMINAL, or DEPARTED_TERMINAL.
  • OPTIONAL Stop Location if the Status Code is DELIVERED, PICKED_UP, ARRIVED_AT_TERMINAL, or DEPARTED_TERMINAL.
  • Timestamp for the Status Update
  • Status Reason Summary Code: INFO_MESSAGE
  • Status Reason Description

Workflow

Complete these steps:

  1. Prepare a POST request to /api/v4/capacityproviders/ltl/shipments/statusupdates.
  2. Complete all required information. Set the statusReason.reasonSummaryCode to INFO_MESSAGE, and add a description of the exception to statusReason.description.
JSON
 { 
  "customerAccount": {
    "accountIdentifier": "string"
  },
  "carrierIdentifier": {
    "type": "SCAC",
    "value": "string"
  },
  "shipmentIdentifiers": [
    {
      "type": "PRO",
      "value": "string",
      "primaryForType": true
    }
  ],
  "statusCode": "INFO",
  "statusReason": {
    "reasonSummaryCode": "INFO_MESSAGE",
    "description": "string"
  },
  "stopType": "DESTINATION",
  "stopNumber": 2,
  "timestamp": "2021-08-04T12:07:34+0000"
}
  1. Send the request.

See additional Exception Code Payload Examples in the Appendix for more samples of using project44 and non-project44 exception codes.

Expected System Response

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

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.

Fields and Objects

The table below describes only the minimum relevant fields necessary for updating the tracking status of a LTL shipment with a non-project44 exception code. These are also the same fields returned in the API Response 202 Accepted.

FieldDescription
customerAccountAn array of the account information for the customer of the shipment.
customerAccount.accountIdentifierThe account identifier for the customer of the shipment. This is used to identify the customer in project44's system.
carrierIdentifierAn array that includes your capacity provider identifier information.
carrierIdentifier.typeThe type of your capacity identifier. SCAC is the only type accepted in this API.
carrierIdentifier.valueThe value of your identifier.
shipmentIdentifiersThis array includes the list if shipment IDs that are used to track the shipment.
shipmentIdentifiers.typeThe type of the shipment ID. At least one identifier in this array must be a PRO Number (shipmentIdentifiers.type = PRO). Other valid values include: BILL_OF_LADING, CUSTOMER_REFERENCE, PICKUP, PURCHASE_ORDER, or EXTERNAL.
shipmentIdentifiers.valueThe value of the shipment ID.
shipmentIdentifiers.primaryForTypeThis field indicates if the shipment ID is the primary shipment ID. The primary shipment ID will always be attempted before other identifiers.
statusCodeThe project44 status code for this status update. This field must always be populated. Valid values include READY_FOR_PICKUP, UPDATED_PICKUP_APPT, EXCEPTION, PICKED_UP, ARRIVED_AT_TERMINAL, REWEIGHT_RECLASS, INFO, UPDATED_DELIVERY_APPT, DEPARTED_TERMINAL, OUT_FOR_DELIVERY, DELIVERED.
statusReasonThe reason for the status. This is an opportunity to provide additional details for the status update.
statusReason.reasonSummaryCodeThe reason summary code for the status of the status update. The valid value here is INFO_MESSAGE.
statusReason.descriptionExplain the reason for the status update
stopType*The type of stop. User-defined stops will always have the customer locations ORIGIN and DESTINATION. TERMINAL stops types are capacity provider redistribution centers and will be inserted dynamically as you return them.
stopNumber*The stop number, where the ORIGIN is 1 and the DESTINATION has the largest number. Any stops in between are numbered in order of appointment time. You can leave this field empty during shipment creation. The DESTINATION stop number will change dynamically as terminals are discovered along the shipment route from ORIGIN to DESTINATION. The stopType is the most useful field for easily and reliably identifying the ORIGIN and DESTINATION.
location*OPTIONAL. This object contains data about the stop's location, including address and contact information. Full address and contact information should be included during shipment creation. Terminals may or may not have complete address and contact information.
location.address*OPTIONAL. This object contains the stop's address information.
location.address.postalCode*OPTIONAL. The ZIP or postal code of the stop location.
location.address.addressLines*OPTIONAL. An array of strings with address information that includes the street name, number, direction, PO Box, etc. for the stop location. NOTE: Currently, only three address lines are permitted.
location.address.city*OPTIONAL. The name of the city or town of the stop location.
location.address.state*OPTIONAL. The abbreviation of the state, province, district, etc. of the stop location. This is only applicable to locations in North America. For locations outside of North America, leave this blank.
location.address.country*OPTIONAL. The abbreviation of the country (using ISO 3166 standards) of the stop location. The default is US.
timestampThe timestamp of the status update. If provided in UTC, add +0000 at the end of the string. If provided in local time, add the applicable UTC offset (for example, add +0100 if the time was given in CET) at the end of the string.

*Only include if the statusCode is DELIVERED, PICKED_UP, ARRIVED_AT_TERMINAL, or DEPARTED_TERMINAL.

Previous page
Next page