FourKites

Prev Next

FourKits provides GPS/Cell-based tracking of loads via the driver’s (smart) phone or in-cab ELD. The Revenova TMS integration with FourKits 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. Navigate 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.

User ID

Password 1

Password 2

Customer Number

Username in email address format

Required

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

The Salesforce-generated API Community URL is case sensitive.

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.

TMS Operation

FourKites Endpoint

Request Type

Response

Start new load tracking session

Create Load

POST

200: Success

400: Bad Request

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

Object

Field

Type

Value

FourKites Field

Load

Tracking Number

Text(40)

FourKites provided tracking number.

FourKitesLoadId

Load

Tracking Provider

Text(40)

"FourKites"

Not sent by FourKites

Stop

Carrier Status Comments

Text(255)

Load Tracking Started.

Stop

Carrier Status as of

Date/Time

Date/Time now

Not sent by FourKites

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.

TMS Operation

FourKites Endpoint

Request Type

Response

Stop Tracking session

Delete Load(s)

POST

200: Success

Sample JSON Stop Tracking Session Request Payload.

{
    "trackingIds": [
        "165589369"
    ]
}

Sample JSON Response Payload.

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

TMS Field Updates

Object

Field

Type

FourKites Field

Load

Tracking Number

Text(40) (no value)

FourKitesLoadId

Load

Tracking Provider

Date/Time (no value)

Not sent by FourKites

Stop

Carrier Status Comments

Text(255) ("Load Tracking Stopped")

Not sent by FourKites

Stop

Carrier Status as of

Date/Time

Not sent by FourKites

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.).

TMS Operation

FourKites Endpoint

Message Type

Response

Stop ETA Update

Stop ETA Update Webhook

STOP_ETA_UPDATED

none

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

Object

TMS Field

Type

FourKites Field

Load

Driver Comments

Text(255)

User_Note

Load

Last Tracking Update Source

Text(50) (“FourKites”)

Not sent by FourKites

Load

Load Status Comments

Text(255) “Location Update”

User_Note

Stop

Carrier ETA Date

Date

Timestamp

Stop

Carrier ETA Time

Text(5)

Timestamp

Stop

Carrier Status as of

Date/Time

Timestamp and TimezoneOffset

Stop

Carrier Status Comments

Text(255)

Set by TMS when Stop ETA push received.

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.

TMS Operation

FourKites Endpoint

Message Type

Response

Location Update

Location Update Webhook

LOCATION_UPDATE

none

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

Object

Field

TMS Type

FourKites Field

Load

Driver Comments

Text(255)

User_Note

Load

Last Reported City

Text(40)

City

Load

Last Reported State

Picklist

State

Load

Last Reported Geolocation

Geolocation

latitude

Load

Last Reported Geolocation

Geolocation

longitude

Load

Last Tracking Update

Date/Time

Timestamp and TimezoneOffset

Load

Last Tracking Update Source

Text(50) ("Four Kites")

Not sent by FourKites

Load

Load Status Comments

Text(255) "Location Update"

User_Note

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.

TMS Operation

FourKites Endpoint

Message Type

Response

Stop Arrival Update

Stop Arrival Webhook

STOP_ARRIVAL

none

Sample JSON Stop Arrival Payload

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

TMS Field Updates

Object

TMS Field

Type

FourKites Field

Load

Driver Comments

Text(255)

User_Note

Load

Last Reported City

Text(40)

City

Load

Last Reported State

Picklist

State

Load

Last Tracking Update

Date/Time

Timestamp and TimezoneOffset

Load

Last Tracking Update Source

Text(50) ("Four Kites")

Not sent by FourKites

Load

Load Status Comments

Text(255) "Arrived at..."

User_Note

Stop

Carrier Status as of

Date/Time

Timestamp and TimezoneOffset

Stop

Carrier Status Comments

Text(255)

Set by TMS when Arrival push received.

Stop

Arrival Date

Date

Timestamp and TimezoneOffset

Stop

Arrival Time

Text(5)

Timestamp and TimezoneOffset

Stop

Stop Status

Picklist (Arrived/Departed)

Set by TMS when Arrival push received.

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.

TMS Operation

FourKites Endpoint

Message Type

Response

Stop Departure Update

Stop Departure Webhook

STOP_DEPARTURE

none

Sample JSON Stop Departure Payload

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

TMS Field Updates

Object

TMS Field

Type

FourKites Field

Load

Driver Comments

Text(255)

User_Note

Load

Last Reported City

Text(40)

Not sent by FourKites

Load

Last Reported State

Picklist

Not sent by FourKites

Load

Last Tracking Update

Date/Time

Timestamp and TimezoneOffset

Load

Last Tracking Update Source

Text(50) (“FourKites”)

Not sent by FourKites

Load

Load Status Comments

Text(255) “Departed…”

User_Note

Stop

Carrier Status as of

Date/Time

Timestamp and TimezoneOffset

Stop

Carrier Status Comments

Text(255)

Set by TMS when Departure push received.

Stop

Departure Date

Date

Timestamp and TimezoneOffset

Stop

Departure Time

Text(5)

Timestamp and TimezoneOffset

Stop

Stop Status

Picklist (Arrived/Departed)

Set by TMS when Departure push received.

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 Operation

FourKites Endpoint

Message Type

Response

Note Update Received

User Note

USER_NOTE

none

TMS Field Updates

Object

TMS Field

Type

FourKites Field

Load

Driver Comments

Text(255)

User_Note

Load

Last Tracking Update Source

Text(50) (“FourKites”)

Not sent by FourKites

Load

Load Status Comments

Text(255)

Use_Note

API Field Mapping

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

Object

Field

Type

FourKites Field

TMS sends during Create Load

Geofence Radius

radius in meters

geofenceRadius

Load

*Bill of Lading Number

Text(55)

loadNumber, referenceNumbers

Load

*Load Number

Text(80)

loadNumber

Load

Container/Trailer Number

Text(40)

trailerNumber

Load

Driver Phone

Phone

driverPhone

Load

Last Reported Geolocation

Geolocation

Location

Load

Last Reported Geolocation

Geolocation

Location

Load

Last Reported City

Text(40)

City

Load

Last Reported State/Province

Picklist

State

Load

Last Tracking Update

Date/Time

Timestamp and TimezoneOffset

Load

Last Tracking Update Source

Text(50) ("FourKites")

Not sent by FourKites

Load

Load Status Comments

Text(255)

Location

Load

Order Number

Text(50)

referenceNumbers

Load

PO Number

Text(100)

customer.poNumbers

Load

*PRO Number

Text(40)

loadNumber, referenceNumbers

Load

Tracking Number

Text(40)

FourKitesLoadId

Load

Tracking Provider

Text(40) "Four Kites"

Not sent by FourKites

Load

Tractor Number

Text(40)

truckNumber

Stop

*Address (Shipping Street)

Text(255)

addressLine1

Stop

*Address (Shipping City)

Text(255)

city

Stop

*Address (Shipping State)

Text(255)

state

Stop

*Address (Shipping Postal Code)

Text(255)

postalCode

Stop

Country (Shipping Country)

Picklist

country

Stop

*Appointment Time

Text(11)

earliestAppointmentTime, latestAppointmentTime

Stop

Arrival Date

Date

Timestamp and TimezoneOffset

Stop

Arrival Time

Text(5)

Timestamp and TimezoneOffset

Stop

Carrier ETA Date

Date

Timestamp

Stop

Carrier ETA Time

Text(5)

Timestamp

Stop

Carrier Status as of

Date/Time

Timestamp and TimezoneOffset

Stop

Carrier Status Comments

Text(255)

Carrier ETA Update, ETA Date/Time

Stop

Departure Date

Date

Timestamp and TimezoneOffset

Stop

Departure Time

Text(5)

Timestamp and TimezoneOffset

Stop

Expected Date

Date

earlistAppointmentTime, latestAppointmentTime

Stop

Geolocation

Geolocation

latitude

Stop

Geolocation

Geolocation

longitude

Stop

*Is Dropoff

Checkbox

stopType

Stop

*Is Pickup

Checkbox

stopType

Stop

Location Name

Text(80)

shipTo

Stop

Number

Number(3,0)

sequence

Stop

References

Text(255)

stopReferenceId

Stop

*Shipping/Receiving Hours

Text(11)

earliestAppointmentTime, latestAppointmentTime

Stop

Stop

Text(80)

name

Stop

Stop Status

Picklist (Arrived/Departed)

Set by TMS during Stop Arrival/Departure push

Transportation Profile

*MC/MX/FF Number

Text(20)

carrier

Transportation Profile

*Name

Text(80)

Shipper

Transportation Profile

*SCAC

Text(6)

carrier

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.

Code

API Call

Error Message

200

Create Load/Delete Load(s)

OK - response has a successful REST API action.

400

Create Load/Delete Load(s)

Bad Request (Invalid syntax, format, or input - see table below)

401

Create Load/Delete Load(s)

Unauthorized (Invalid API Key)

403

Create Load/Delete Load(s)

Forbidden (Authenticated user doesn’t have permission)

404

Create Load/Delete Load(s)

Not Found (Entity does not exist)

429

Create Load/Delete Load(s)

Too Many Requests (Request rate is too high)

500

Create Load/Delete Load(s)

Internal Server Error (Issue processing the request)

502

Create Load/Delete Load(s)

Bad Gateway (Invalid response from the upstream server)

504

Create Load/Delete Load(s)

Gateway Timeout (Server cannot get a response in time)

400: Error Message

Resolution

State 'ABCD' is not valid.

Provide a valid 2-character state code for US and Canada and a 3-character state code for Mexico.

Example: CA, NY, ON, BCN, CAM.

Postal 'EFGH' is not a valid US postal code.

Provide a valid US postal code.

Example: 87901

Postal 'EFGH' is not a valid Canada postal code.

Provide a valid Canada postal code.

Example: V3J

Postal 'EFGH' is not a valid Mexico postal code.

Provide a valid Mexico postal code.

Example: 46958

Stops should contain at least one pickup and one delivery.

Ensure that you create a load with at least one pickup and one delivery stop.

Stops Earliest Appointment Time should not be greater than Latest Appointment Time.

Ensure that the stop's earliest appointment time is not greater than the latest appointment time.

Stops cannot have appointment time earlier than 4 days.

Ensure that the stop's appointment time is not earlier than 4 days from the current time.

Address should contain Address line 1 or city, state and country or Latitude and Longitude.

While creating a load, ensure that stop address contains at least one of the following: Address Line 1, City, State, Country, Latitude/Longitude.

Load information is empty.

Ensure that the "load" object is included in your API request: { "load": { ... } }

Carrier is not specified.

Specify the SCAC of the Carrier.

Stops stop should contain both earliest and latest want times.

If you want to create a load with want time as time ranges (earliest and latest want time), ensure that you provide the values for both these fields.

Stops stop should contain both earliest and latest want times.

If you want to create a load with want time as time ranges (earliest and latest want time), ensure that you provide the values for both these fields.

Stops stop Earliest Want Time should not be greater than Latest Want Time.

Ensure that the stop's earliest want time is not greater than the latest want time.