Winter '25 FourKites

Overview

FourKites provides GPS/Cell-based tracking of loads via the driver’s (smart) phone or in-cab ELD. The Revenova TMS integration with FourKites provides Carrier load tracking and status updates sent from FourKites and received in the TMS.

FourKites is a Load Tracking API service.

FourKites provides “push” status updates to the TMS via a sites-based web service. Inbound load status packets from FourKites are stored in the Queued Transaction table and processed by the QueuedTransactionJob. 

Setup

Enter Credentials

Enable the FourKites integration by completing the following steps.

1. Navigating to TMS Admin, 

2. Select Credentials. 

3. Select the Global Services tab,

4. Find FourKites in the list and open the card. 

5. Check the Enabled and  Receive Updates boxes.

6. Enter the   User ID and Password 1 into the text fields. 

7. Click the Save button when finished.

Valid credentials are required from a FourKites subscription. See examples in the table below.

Inbound Packet IP Ranges: Any load status post-backs from FourKites that do not originate from this IP mask are rejected as a security feature. Any changes to this range are provided by Revenova.

Remote Site Settings

Upgrading from previous versions of the TMS may have outdated information. Check that the Remote Site Settings for the FourKites integration URL are up to date.

1. Click the Setup gear icon in the top right corner.

2. From the drop-down, click Setup.

3. In the Quick Find Toolbar type Remote Site Settings and click the link.

4. From the list of remote sites find FourKites and click the Edit link.

5.  Update the Remote Site URL to match the Service URL below: 

Service URL: https://tracking-api.fourkites.com

Test Service URL: https://tracking-api-staging.fourkites.com 

Partner Community Setup

The FourKites integration requires a webhook to send tracking information to the TMS. Create an API Site to accept inbound API traffic.

1. Create a Salesforce Site for API Guest User Access.

2. Set the public access for the Site.

3. Activate and Publish the Site.

4. Enter the API URL into the field for Inbound API Community URL under TMS Admin, in the Configuration section. 

5. Add the following extension to the end of the URL to match the example below: /services/apexrest/rtms/tmslistener?org=[18-character org id]&source=FourKites&pwd=[credentials code field]  

6. Log in to the FourKites website.

   1. Go to Settings → 3rd Party Integration → Enter the URL.

   2. Enter the Authorization Scheme: No Authorization.

7. Contact FourKites and have them provision the following call-back events:

   1. Location Update

   2. Carrier ETA Update

   3. Stop Arrival

   4. Stop Departure

   5. User Note

{API Community URL} /services/apexrest/rtms/tmslistener?org= {18-character org id} &source=FourKites&pwd= {credentials code field} 

Example: https://revenova.my.site.com/api/services/apexrest/rtms/tmslistener?org=00D180000008oA9EAI&source=FourKites&pwd=4wGFDgnT950Ovg1

TMS Admin

Configuration

The following field may be set under TMS Admin, Configuration to use as default tracking settings when using FourKites.

Tracking Update frequency (Minutes): The number of minutes between inbound load location updates from FourKites. The TMS does not process load location updates less than the entered value since the last load location update.

Tracking Event Frequency

Location and Carrier ETA event frequency is updated:

• For pickup/delivery day: every 30 minutes

• Other updates: every 4 hours

Transportation Profile

It is possible to set a default Tracking Provider for each Carrier on their Transportation Profile.

Tracking Provider: The default selection in the Load Tracking Admin LWC of tracking information for a load. 

The FourKites integration supports multiple stops for the same Account location.

Carrier Load Tracking

Carrier load tracking is initiated on the Carrier Banner LWC. Click the antenna button to open the Load Tracking Administration LWC to begin tracking the load. 

Start and stop a tracking session by clicking the On and Off buttons. 

Start Load Tracking

Create Load API allows authorized users to create a new load for tracking. FourKites does not limit customers from creating more than one load with the same load number or PRO number. This means that multiple POST requests with the same data could generate duplicates if not handled carefully. 

The Tracking Number field is returned. 

This call is not processed by the QueuedTransactionJob batch process.

Sample Start Load Tracking JSON Request Payload

{
    "load": {
        "carrier": "cc79",
        "haulType": [
            "inbound_load"
        ],
        "loadNumber": "601E5D3C",
        "priority": "high",
        "proNumber": "4638",
        "products": [
            {
                "lowerTemperatureThreshold": "20",
                "name": "Produce",
                "productId": "0123456",
                "setTemperature": "28",
                "timeToleranceInMinutes": "30",
                "upperTemperatureThreshold": "34"
            }
        ],
        "referenceNumbers": [
            "TU-2945",
            "80982",
            "94BC8"
        ],
        "relayLoad": false,
        "stops": [
            {
                "addressLine1": "500 West Madison Street",
                "addressLine2": "Suite 3300",
                "city": "Chicago",
                "country": "US",
                "customer": {
                    "id": "789789",
                    "poNumbers": [
                        "00210123OF-203503"
                    ]
                },
                "earliestAppointmentTime": "2021-03-09T15:25:00.203Z",
                "latestAppointmentTime": "2021-03-09T15:25:00.203Z",
                "name": "FourKites HQ",
                "pallets": [
                    {
                        "number": "123444444",
                        "parts": [
                            {
                                "customerPartNumber": "123-FCOSS",
                                "quantity": "1",
                                "shipperPartNumber": "1259924",
                                "weight": "41.92 LB"
                            },
                            {
                                "customerPartNumber": "65-2333SS",
                                "quantity": "21",
                                "shipperPartNumber": "59924",
                                "weight": "880.32 LB"
                            },
                            {
                                "customerPartNumber": "65-24DGOSS",
                                "quantity": "22",
                                "shipperPartNumber": "1924",
                                "weight": "922.24 LB"
                            },
                            {
                                "customerPartNumber": "65-24S",
                                "quantity": "15",
                                "shipperPartNumber": "1255524",
                                "weight": "628.8 LB"
                            }
                        ]
                    }
                ],
                "postalCode": "60611",
                "referenceNumbers": [
                    "1234567",
                    "2412422222",
                    "PalletNumber:54831396"
                ],
                "shipTo": "1234",
                "state": "IL",
                "sequence": "1",
                "stopReferenceId": "123",
                "stopType": "pickup"
            },
            {
                "addressLine1": "425 South Palos Verdes Street",
                "addressLine2": "",
                "city": "Los Angeles",
                "country": "US",
                "customer": {
                    "id": "789789",
                    "poNumbers": [
                        "00210123OF-203503"
                    ]
                },
                "earliestAppointmentTime": "2021-04-01T16:17:40.288Z",
                "latestAppointmentTime": "2021-04-02T16:17:40.288Z",
                "name": "Port of Longbeach",
                "pallets": [
                    {
                        "number": "123444444",
                        "parts": [
                            {
                                "customerPartNumber": "123-FCOSS",
                                "quantity": "1",
                                "shipperPartNumber": "1259924",
                                "weight": "41.92 LB"
                            },
                            {
                                "customerPartNumber": "65-2333SS",
                                "quantity": "21",
                                "shipperPartNumber": "59924",
                                "weight": "880.32 LB"
                            },
                            {
                                "customerPartNumber": "65-24DGOSS",
                                "quantity": "22",
                                "shipperPartNumber": "1924",
                                "weight": "922.24 LB"
                            },
                            {
                                "customerPartNumber": "65-24S",
                                "quantity": "15",
                                "shipperPartNumber": "1255524",
                                "weight": "628.8 LB"
                            }
                        ]
                    }
                ],
                "postalCode": "90731",
                "referenceNumbers": [
                    "1234567",
                    "2412422222",
                    "PalletNumber:54831396"
                ],
                "state": "CA",
                "sequence": "2",
                "stopReferenceId": "9876",
                "stopType": "delivery",
                "wantTime": "2021-04-02T16:17:40.288Z"
            }
        ],
        "tags": [
            "temp",
            "field2",
            "Inbound"
        ]
    },
    "trackingInfo": {
        "trailerNumber": "643",
        "truckNumber": "1085"
    },
    "additionalData": {
        "modeDetails": {
            "shipperModes": "TL"
        }
    }
}

The Stop Appointment Time fields are sent as part of the start tracking call, if they are available. If not available, the Shipping/Receiving Hours are sent.

Sample Start Load Tracking JSON Response Payload

{
  "statusCode": 200,
  "message": "Load creation request has been submitted successfully",
  "loadId": 174824552
}

TMS Field Updates

See FourKites Create Load documentation here.

Stop Load Tracking

The stop load tracking call sends a request to FourKites to end the current tracking session. When the cancel request is received, the Load Track system cancels the Load Track if the driver has not started the session. 

This call is not processed by the QueuedTransactionJob batch process. 

Sample JSON Stop Tracking Session Request Payload.

{
    "trackingIds": [
        "165589369"
    ]
}

Sample JSON Response Payload.

{
  "statusCode": 200,
  "message": "Tracking records marked as delivered"
}

TMS Field Updates

See FourKites Delete Load(s) documentation here.

Tracking Updates from FourKites (PUSH into Revenova)

The FourKitesLoadId is sent with each push to verify the load Tracking Number. The Tracking Number field is not updated.

Stop ETA Update

The Stop ETA Update callback is sent as soon as FourKites generates a new ETA for the given stop. FourKites will calculate a new ETA as soon as new information about the load has been received (new GPS location, new status event, etc.).

Sample JSON Stop ETA Update Payload

{
  "EncryptedAccessToken": "VjN8Y3l0Yy1jb21wYW55LW5ld3wwNzQyZjZkMS0wMmUwLTRhZmEtYjI2Yy01ZjdlNGQzYjMwYzR8Y3l0Yy1jb21wYW55LW5ldw",
  "FourKitesLoadId": 123654314,
  "LoadNumber": "2DB85AEB",
  "MessageType": "STOP_ETA_UPDATED",
  "ProNumber": "4638",
  "ReferenceNumbers": [
    "TU-2945",
    "80982",
    "94BC8"
  ],
  "Scac": "CC79",
  "Shipper": "cytc-company-new",
  "StopName": "Port of Longbeach",
  "StopReferenceId": "9876",
  "StopSequence": 2,
  "StopType": "delivery",
  "Tags": [
    "Inbound",
    "field2",
    "temp"
  ],
  "Timestamp": "2021-06-06T07:32:29-07:00",
  "Timezone": "America/Los_Angeles",
  "TimezoneOffset": -25200,
  "TimezoneShortName": "PDT"
}

TMS Field Updates

See FourKites Stop ETA Update documentation here.

Location Update

The Location Update callback is sent as soon as FourKites logs a new GPS location has been received. Loads are updated if the load status is Tendered, Assigned, Dispatched, In Transit, or if the event is the Last Stop Departure. 

Tracking updates received within the period set by the Tracking Update frequency (Minutes) field in TMS Admin are stored in the Queued Transaction table. These updates are processed during the next tracking session update.

Sample JSON Location Update Payload

{
    "City": "Chicago",
    "Country": "US",
    "FourKitesLoadId": 130650373,
    "Latitude": "41.8333925",
    "LoadNumber": "520126804",
    "Location": "Chicago Loop",
    "Longitude": "-88.0121478",
    "MessageType": "LOCATION_UPDATE",
    "OdometerReading": null,
    "ProNumber": null,
    "ReferenceNumbers": [
        "9571274"
    ],
    "Scac": "CC79",
    "Shipper": "cytc-company-new",
    "State": "IL",
    "Tags": [
        "2CT9",
        "Export",
        "2810938"
    ],
    "Timestamp": "2021-07-01T10:19:49-04:00",
    "Timezone": "America/Chicago",
    "TimezoneOffset": -18000,
    "TimezoneShortName": "EDT"
}

TMS Field Updates

See FourKites Location Update documentation here.

Stop Arrival

The Stop Arrival callback is sent as soon as FourKites receives a GPS ping inside the geofence of the stop. 

Sample JSON Stop Arrival Payload

{
    ...
    "StopName": "FourKites HQ",
    "StopReferenceId": "123",
    "StopSequence": 1,
    "StopType": "pickup"
    ...
}

TMS Field Updates

See FourKites Stop Arrival documentation here.

Stop Departure

The Stop Departure callback is sent as soon as FourKites receives a GPS ping outside the geofence of the stop which was previously arrived.

Sample JSON Stop Departure Payload

{
    ...
    "StopName": "FourKites HQ",
    "StopReferenceId": "123",
    "StopSequence": 1,
    "StopType": "pickup"
    ...
}

TMS Field Updates

See FourKites Stop Departure documentation here.

User Note

The User Note callback is sent when FourKites receives a driver comment or event. 

When the event is marked by FourKites as from the Driver, the note is inserted into the Driver Comments field. If not marked as from the Driver, the note is inserted into the Load Status Comments field.

TMS Field Updates

API Field Reference

The following table relates TMS data fields with the equivalent FourKites fields used in API calls.

To successfully create a Start Tracking Operation with FourKites: (at least one of) a Bill of Lading Number, PRO Number, MC Number, or SCAC Number is required. The TMS will search for values in any of these fields.

* Fields marked with an asterisk are required.

FourKites Codes

The following table contains the codes sent by FourKites that can appear in the TMS user interface.