FourKites

 

 

We offer two integrations with FourKites:

• Pull Integration: Allows FourKites data to be retrieved and displayed in Tai TMS.
• Push Integration: Used to send tracking location data to FourKites for specific customers.

FourKites PULL Integration

This is a RESTful API integration that works with Tai's existing Shipment Location History functionality. FourKites is listed as an available Shipment Tracker in Tai. Through this integration, Tai can Create, Update, and Delete loads within FourKites. Relevant information is pulled back via callbacks and displayed in the Shipment Location History modal.

API Authentication
Basic authentication is used for both POSTS and callbacks.

Setup Instructions

To configure the integration:

1. Obtain Credentials: Request a username and password from FourKites.
2. Add a New Integration Source:
   • Navigate to LSP > Integration Sources.
   • Click Add New Integration Source.
   • Enter a name for the integration.
   • Set Source Group to "Other" and Source Type to "FourKites".
   • Enter the username and password, then click Save.
3. Link Your Organization:
   • After saving the integration, click the Add Organization Link button.
   • Enter your organization's name in the Organization field and click Create to link the integration to the desired organization.
     
4. Create an Authentication Key:
   • Generate an API Key and link it to an LSP Staff account:
     • Create an LSP Staff account using "broker.fourkites" as the login.
     • Navigate to LSP > Public Authentication Keys and click the Add Public Authentication Key button.
   • Configure the API Key:
     • In the Organization field, enter your organization's name.
     • In the Staff field, select the newly created "broker.fourkites" account.
     • Click Save to generate the API Key.
   • Share the API Key:
     • Provide the API Key to the FourKites onboarding representative to establish connectivity for callbacks within the FourKites system.

If you need assistance generating the API Key or creating the LSP Staff account, you can contact Tai Support for help. This article also serves as a step-by-step guide for generating an API Key.

Supported Methods

1. Create Load (POST)

• This API creates a load in FourKites and requests the carrier to accept the tender for the load.
• The process is triggered by the Start Tracking UI.
• The response includes a FourKites loadid, which must be saved and used for subsequent API calls.
• Tai sends the shipment ID and generates a stop reference ID for tracking.

2. Update Load

• This API allows users to update an existing load.
• Use this when the carrier assigned to the load changes.

3. Delete Load

• This API allows users to delete previously created loads in FourKites.
• Use this when a shipment is canceled or terminated.

CALLBACKS
Tai Software registers a callback URL to receive notifications from FourKites via HTTPS POST. Notifications provide updates on load statuses and related events.

Callback Workflow:

1. Create Load (POST)
   • FourKites returns a loadid (their reference number).
2. Load Create Notification
   • Includes a URL to open the public tracking page.
3. Tracking Info Assignment
   • Returns driver name, phone number, truck number, and trailer number.
4. New Location Update
   • Provides updated GPS coordinates.
   • Sent multiple times during transit.
5. Stop ETA Update – Pickup
   • Uses the stop reference ID to identify the stop.
   • Use this to log potential exceptions for late or missed pickups.
6. Stop ETA Update – Delivery
   • Similar to the pickup ETA update, but for delivery.
   • Call is triggered when the ETA changes by more than 15 minutes.
7. Stop Arrival – Pickup Location
   • Triggered when the driver enters the geofence.
   • Use this to log the actual pickup date and time.
8. Stop Departure – Pickup Location
   • Triggered when the driver exits the geofence.
   • Log this as the actual stop departure time.
9. Stop ETA Update
   • Uses the stop reference ID to identify the stop.
   • Only called when the ETA is changed.
10. Stop Arrival – Delivery Location
    • Triggered when the driver enters the delivery geofence.
    • Use this to log the actual delivery date and time.
11. Stop Departure – Delivery Location
    • Triggered when the driver exits the delivery geofence.
    • Log this as the actual stop departure time.
12. Stop File Upload
    • Includes uploaded files (e.g., PODs or Return Receipts)

Webhooks

Below are the webhook endpoints and their corresponding functionalities:

1. Tracking Notifications

   • https://www.taicloud.net/publicapi/fourkites/notification
   • Includes a URL to open the public tracking page.

2. ETA Updates

   • https://www.taicloud.net/publicapi/fourkites/etaupdate
   • Used to log exceptions for late or missed pickups.
   • Triggered when the ETA changes by more than 15 minutes.

3. Stop Arrival

   • https://www.taicloud.net/publicapi/fourkites/arrival
   • Triggered when the driver enters a geofence (pickup or delivery).

4. Stop Departure

   • https://www.taicloud.net/publicapi/fourkites/departure
   • Triggered when the driver exits a geofence (pickup or delivery).

5. File Upload

   • https://www.taicloud.net/publicapi/fourkites/fileupload
   • Used to retrieve documents such as PODs and Return Receipts.

6. Location Updates

   • https://www.taicloud.net/publicapi/fourkites/locationupdate
   • Provides location updates with geolocation data.

7. Tracking Info Assignment

   • https://www.taicloud.net/publicapi/fourkites/trackingInfoAssignment
   • Returns driver details: name, phone number, truck number, and trailer number.

FourKites PUSH Integration

The FourKites PUSH integration allows location information to be transmitted to the FourKites platform via API integration.

Setup Instructions

To configure the integration:

1. Obtain Credentials: Request a username and password from FourKites.
2. Add a New Integration Source:
   • Navigate to LSP > Integration Sources.
   • Click Add New Integration Source.
   • Enter a name for the integration.
   • Set Source Group to "Other" and Source Type to "FourKites".
   • Enter the username and password, then click Save.
3. Add Customer ID Setting:
   • Click Edit on the newly created integration.
   • In the Source Settings section, add a new setting:
     • Name: CustomerId
     • Value: The customer’s ID, which can be found in the customer profile.
   • After entering these details, click Save to complete the setup.

Important Notes

If FourKites provides credentials in an encoded format (e.g., clientID and clientSecret), request the username and password instead. The TMS will automatically encode these credentials during payload transmission.

Endpoint Details

The following endpoint is used to transmit location data (latitude and longitude):

https://tracking-api.fourkites.com/api/v1/tracking/locations

Example Request:

{
  "shipper": "123456",
  "billOfLading": "789012",
  "trailerNumber": "+11234567890",
  "driverPhone": "+11234567890",
  "latitude": "34.052235",
  "longitude": "-118.243683",
  "locatedAt": "2025-01-23T14:16:42.0000000",
  "delivered": true,
  "deliveredAt": "2025-01-23T14:19:23.9167736Z"
}

Data Transmission

To begin sending tracking data to FourKites, a supported tracking integration must first be used to initiate tracking in Tai. Once Tai receives tracking information via the integration, it will trigger the data to be pushed to FourKites, provided the shipment status is "In Transit" or "Delivered."

Required Data

• Secondary BOL Number: This reference number must be configured within the shipment in Tai and corresponds to the shipment ID in FourKites. It establishes the link between tracking updates and your customer's load in FourKites.

• LAT/LONG Data: This information is pulled from the TMS through a supported tracking integration.