About this Guide  

 This user guide document is designed and intended for users interested in visualizing and consuming tracking information about Parcel shipments. This includes guidance for visualizing shipments in project44’s User Interface - the Visibility Operations Center (VOC) - and on the phases and processes underlying the implementation of project44 APIs for Full Truckload in the United States and Europe.   

  

This guide contains links to the developer portal for API documents. Please reach out to your implementation team for access if you do not already have this.   

  

This guide will cover:    

• How to Initialize Shipment Tracking  
• How to Check Shipment Status  

 In the VOC, you can add, track, and update shipments as well as access analytics for shipment and carrier performance. Find API resources in the VOC’s Developer Portal.   

  

Using API tracking, project44's Parcel Tracking endpoints give you or your customers visibility into your parcel shipments. Use these endpoints to initialize (POST), track (GET), or delete (DELETE) parcel shipments. You can return shipment information by either unique system ID.  

  
Parcel Tracking in the VOC  

 You can login to the project44 Visibility Operations Center (VOC) at https://cloud-v2.p-44.com/portal/v2/login. Please use the credentials provided by your project44 onboarding consultant or solutions engineer.   

   

After logging into the VOC, you will be directed to the landing page. There are three primary features available on the landing page:   

• Search: search for a unique shipment, or a group of shipments that meet specified criteria. For example, you can search by a carrier that is handling the freight, or a customer that the freight is being delivered to. You can also search using reference numbers for line items that a load is carrying (i.e. PO number or SKU).   

 

• Quick Views: a pre-configured report that enables you to quickly find shipments that are of frequent interest. For example, you can create a quick view that retrieves all shipments that are in transit to a specified location. After clicking on a quick view tile, the user will be directed to the Shipment List Page.     

 

You will be directed to the Shipment List page after selecting a quick view or executing a search on the portal landing page. This page will display a list of all shipments that meet the criteria specified within the quick view or search. Once you are in the list page, you can update the filters to narrow your search to more precise criteria.   

Each shipment tile displayed within the search page will show the tracking number, carrier, shipment status, origin and delivery details, and delivery forecast. Clicking on the shipment tile will direct you to the Shipment Detail page.   

  

Check Shipment Status  

 A parcel shipment will be added to the VOC once it has been initiated through project44’s POST API (see below). Alternatively, you can send a flatfile with the shipment’s information to your project44 Implementation Team.  

  

The Parcel Shipment Details page displays the status of the shipment, a timeline detailing events along the route, and a map showing the route of the shipment. With the buttons at the top-right of the pages, you can perform the following actions:  

• Notes: Click the “NOTES” button to see all notes that are visible to everyone. To add a note, type your note in the “Type your comment” field under your name. Indicate whether it is private or visible to everyone with the checkbox next to VISIBLE TO EVERYONE. Then click POST. 
• Alerts: This will take you to the Notifications section of the VOC and show you all notifications set up for this shipment.  
• Share: Click the “Share” button to share the shipment. project44 provides a shareable link. Click on the copy icon next to the link to copy it, then click DONE.  

  

 

Just below that, you can find a timeline of the route details for the shipment. This will include timestamps for shipment events, scheduled arrival/departure times, and ETA or actual arrival if the truck has already arrived at the stop.   

 

 

Beneath the route information, you can find a map of stops made throughout transportation of the shipment. The map includes a marker for the shipment origin, shipment destination, and current shipment location  

 

   

Add Reference Data Keys  

You can create a set of custom keys that can be used to “tag” shipments and place them into appropriate groups and categories. These keys and corresponding tags can be completely unique to your business. Some examples of reference keys could be “Business Unit,” “Customer ID,” or “High Priority.” The reference keys and associated tags provide an additional level of flexibility when creating custom views of in transit shipments or analyzing historical trends and performance data for critical load groups.    

  

In order to create a new reference key, you will navigate to the SETTINGS page within the upper right-hand menu of the landing page.   

Once on the settings page, make sure to select REFERENCE DATA KEYS from the list of options on the left-hand side of the screen.   

 

To create a new key, type the name of your key into the KEYS search bar. Please note that the CREATE button on the right side of the search bar will not be accessible until text is entered. After you’ve finished typing the name of your key, simply click the CREATE button.   

 

The tags themselves can be applied either through the project44 API during the tracking initialization process. The reference keys that you have created will now be available as filter options when you create quick views on the VOC landing page. The reference keys can be found at the bottom of the quick view configuration panel.     

 

    

   

Notification Engine   

 Notifications can be configured by clicking on the menu icon in the upper right-hand corner of the landing page and selecting NOTIFICATIONS.   

You can then edit an existing notification or create a new notification by selecting NEW NOTIFICATION in the upper right-hand corner of the page.   

 

   

The notification is a proactive email or text message that is triggered by a specified event type. Within the notification itself, you can assign a name, select the relevant mode, define the event type, create the shipment criteria, and assign recipients. Supported event types differ by mode of transportation. For parcel shipments, supported event types include: Out for Delivery, Missed Delivery Window, and Running late.  

After the event type is selected, you can assign a threshold to the event. For example, if the notification should only be triggered after a shipment is running more than four hours late, you would assign a threshold of 240 minutes.   

   

You can also configure the group of shipments that this notification will monitor. For example, if you would like to create notifications that are related to a particular customer, you can define this setting within the INCLUDE SHIPMENTS section. You can group shipments by Customer, Location, and Carrier.   

   

Finally, you can enter the recipients of the notification. Please be sure to enter a valid email address for each recipient that you would like to receive this notification.   

  

Managing Capacity Providers in the VOC  

 To connect your project44 account to a capacity provider via API, you will need to enter a set of API credentials into the project44 system. project44 will store these credentials on your behalf in the Carrier Portal and use them to authenticate against the capacity provider’s API. You can navigate to the Carrier Portal by going to the menu icon in the upper right-hand corner of the VOC landing page and selecting CARRIERS.  

 

This will direct you to the Capacity Providers page of the Carrier Portal where you can see all capacity providers for which credentials have already been entered. Each capacity provider has its own Capacity Provider ID and Account Code associated with it. On this page you can also see the Account Groups each capacity provider has been categorized into.  

  

  

Add Capacity Providers  

 To enter credentials for a new capacity provider, select ADD ACCOUNT in the upper right-hand corner of the Capacity Providers page. You can then search for the relevant capacity provider by typing in their name or Capacity Provider ID.  

After you find and select the correct capacity provider, click NEXT. This will direct you to a page where you can enter in the required credentials for that capacity provider. Different capacity providers require different types of credential information, so do not be alarmed if you do not see the same field names for different capacity providers.  

  

To enter a batch of credentials for multiple capacity providers, go to IMPORT at the top right-hand corner of the Capacity Providers page. This will bring up a window where you can import a CSV file of capacity provider credentials. You can also download the template file and the reference file to view the fields accepted by each capacity provider.  

  

 

Create and Add to Capacity Provider Account Groups  

 You can organize capacity providers into Account Groups to quickly access a select group of capacity provider accounts against which an operation is to be performed. To do this, go to ACCOUNT GROUPS at the top, right corner of the Capacity Providers page. Then select ADD ACCOUNT GROUP at the top, right corner of the Vendor Account Groups page. Create a name and code for the Account Group you want to create in the Add Account Group window – these can be anything you want, but you cannot duplicate account codes. Save the new Account Group information.  

  

Manage Capacity Provider Contact Information  

You can add and make changes to capacity provider contact information in the Address Book that can be found under Settings and Providers in the menu at the top left-hand corner of the page. To add information, select ADD ADDRESS at the top right-hand corner of the Address Book page and enter all required information. You can also edit existing entry information by selecting the EDIT button next to each capacity provider entry. Be sure to click SAVE so that adjustments are applied.  

  

  

Parcel Tracking with project44 API  

 project44's Parcel Tracking endpoints give you or your customers visibility into your parcel shipments, including such features as predictive ETAs and temperature tracking. Use these endpoints to initialize (POST), track (GET), or delete (DELETE) parcel shipments. You can return shipment information by either unique system ID or by identifier.  

  

Add Shipment to Initialize Parcel Tracking  

 Tracking for a shipment is initialized when all necessary shipment information is entered into an API POST request. Initiating tracking with project44’s API requires the following shipment information, otherwise the shipment will not be created, and tracking will not be initialized:   

• Capacity provider account group code  
• Shipment tracking number  

For more details on the required fields and valid values for these fields, see the POST: Initialize parcel shipment for tracking section in the VOC Developer Portal.   

  

Table 1. Example of valid JSON input for a POST request to create a shipment and initialize shipment tracking.

{     "capacityProviderAccountGroup": {       "code": “{{CAPACITY_PROVIDER_ACCOUNT_GROUP_CODE}}”,       "accounts": [         {           "code": “{{CAPACITY_PROVIDER_ACCOUNT_GROUP_ACCOUNTS_CODE}}”         }       ]     },     "shipmentIdentifiers": [       {         "type": “{{SHIPMENT_IDENTIFIERS_TYPE = “TRACKING_NUMBER”}}”,         "value": “{{SHIPMENT_IDENTIFIERS_VALUE}}”       }     ],   }

  

Table 2. Sample Responses for a POST request to create a shipment and initialize shipment tracking.
Code	Description	Example Value
201	Created	{     "shipment": {       "capacityProviderAccountGroup": {…},       "shipmentIdentifiers": […],       "shipmentAttributes": […],       "shipmentStops": […],       "apiConfiguration": {…},       "id": 0,       "masterShipmentId": "string",       "parcelLegId": "string"     },     "shipments": [       {…}     ],     "infoMessages": […]   }
400	Invalid request	{     "httpStatusCode": 0,     "httpMessage": "string",     "errorMessage": "string",     "errors": [       {...}     ],     "supportReferenceId": "string"   }
401	Invalid or missing credentials	{     "httpStatusCode": 0,     "httpMessage": "string",     "errorMessage": "string",     "errors": [       {...}     ],     "supportReferenceId": "string"   }
403	User not authorized to perform this operation	{     "httpStatusCode": 0,     "httpMessage": "string",     "errorMessage": "string",     "errors": [       {...}     ],     "supportReferenceId": "string"   }

  

The shipment’s project44-generated ID (shipment.id) will be returned in the response to the succesful POST request to initialize tracking. Save this ID because you will need it to PULL status updates and/or delete the shipment. See the Check Shipment Status section below for more information on PULLing a status and deleting parcel shipments.  

  

The project44 parcel tracking relies on live tracking data. A shipment that is submitted after the initial pickup, will only be tracked from the moment it gets submitted into the project44 systems. Any activities prior to that moment (e.g., arrival or departure from a stop, position updates etc.) cannot be retrieved or restored.   

  

Tracking begins as soon as a successful POST request is submitted for the shipment, and it will be tracked until the shipment is delivered. Updates will be provided for each change in events.  

  

Add Custom Attributes  

 Customers have the ability to tag shipments with a customized key:value pair during tracking initialization and updates. These key:value pairs, which can be referred to as custom attributes or custom reference keys, can be used to group and categorize shipments, which allows VOC users to create more relevant dashboards and reports.  

  

You can create custom attributes to group and categorize shipments, which allows you to create more relevant dashboards and reports in the VOC. Create these attributes, aka custom reference keys, either in the VOC (see the above subsection Reference Data Keys) or through project44’s endpoint: Create a predefined attribute. Only organization administrators can perform create predefined attributes for shipments. Each attribute created must be unique. To see existing attributes, use the Get all shipment attributes endpoint.  

  

To assign attributes to a parcel shipment during initialization, you can add up to five attributes to the shipmentAttributes parameter of the POST endpoint.  

  

Webhook Configuration  

A webhook can be used to PUSH shipment updates to a customer once those updates become available. One or multiple webhooks must be registered (each with a unique name). You will use the PUT: Add or update webhook where shipment tracking updates are posted to set up the webhook. The URL to which a POST request will be made with the content of the status update for a specific parcel shipment is required. For more details, see PUT: Add or update webhook where shipment tracking updates are posted section in the project44 API Documentation.  

  

Table 3. Example of valid JSON input for a POST request to create a shipment and initialize shipment tracking.

{     "url": "string",     "username": "string",     "password": "string",     "showLatestUpdate": {{showLatestUpdate = TRUE or FALSE}},     "includeFullHistory": {{includeFullHistory = TRUE or FALSE}}   }

 To PUSH a shipment’s entire history, set the includeFullHistory parameter to “true.”  

  

Check Parcel Shipment Status  

You can PULL the status of a parcel shipment by using the GET: Get the status of a parcel shipment using the unique system ID API request with the project44-generated ID for the shipment.  

 

Customers have the option to have parcel status events pushed to them in lieu of running a GET status request every time. In the background, once tracking has been initialized through a POST, project44 will ping the carrier approximately every 15 minutes for an update. project44 will then store these statuses in our system and push out a status update every time there is a change in the status reason. For example, if we get 50 "IN_TRANSIT" statuses in a row, we would push out an update the first time we receive this status but then would not push another update until we receive a new status such as "AT_STOP". Even though we are not pushing out a status on a regular cadence, those statuses are still stored in our system and available to obtain through a GET request.  

   

PUSH Tracking Updates   

The shipment tracking updates PUSHed to the webhook are formatted identically to the updates received when querying for a status at the GET: Get the webhook URL where shipment tracking updates are posted endpoint.   

Should your webhook fail to receive the push update, e.g. in case of system maintenance, the project44 system will not try and re-transmit the PUSH update. However, in every push update, there is the current update (in the latestStatusUpdate object) as well as the three previous updates in the statusUpdates object, in case a couple were missed. Should you miss an update of a shipment completing (latestStatusUpdate.statusCode = “COMPLETED”) we recommend implementing a local timer that triggers a query for a status update at the timeout, to check if that shipment may have completed normally (e.g. by the vehicle departing last stop). In case of scheduled down-time in your systems, consider starting by querying for an update on all shipments that were non-completed before the shut-down to synchronize status between your and the project44 systems.  

Once tracking has been initialized through a POST, p44 will ping the carrier every ~15 minutes for an update. p44 will then store these statuses in our system and push out a status update every time there is a delta in the status reason. For example, if we get 50 "IN_TRANSIT" statuses in a row, we would push out an update the first time we receive this status but then wouldn't push another update until we receive a new status such as "AT_STOP". Even though we are not pushing out a status on a regular cadence, those statuses are still stored in our system and available to obtain through a GET request.  

  

Delete Parcel Shipments  

Use the DELETE: Delete an existing parcel shipment using the unique system id API request to delete a parcel shipment.  

 

 

Nothing contained herein constitutes an offer to sell or solicits an offer to purchase any of the products and services described herein. Any such purchase or sale shall be made only upon execution of a definitive agreement, which shall be the sole and exclusive embodiment of the terms and conditions of sale as well as the representations and warranties, if any, related thereto.