Tracking
      Back to home
      1. Knowledge Base
      2. Integrations
      3. Tracking

      FourKites

      We have two integrations available with FourKites. One is used to push tracking location data to FourKites for a specific customer. The other uses the FourKites integration to pull data down from FourKites into the TMS. 

      FourKites PULL

      This is a RESTful API integration that will work with Tai TMS’s existing Shipment Location History functionality. Four Kites will be listed as an available Shipment Tracker. Tai TMS will be able to Create, Update, and Delete loads within Four Kites application. Callbacks will pull back relevant information for display in the Shipment Location History modal.

      API AUTHENTICATION
      We will use basic authentication for both POSTS and callbacks.

      Supported Methods

      CREATE LOAD - POST
      This API is called to request the carrier to accepted the tender for the load. This is triggered by the Start Tracking UI.
      The response from this post is a FourKites loadid. This loadid must be saved and used for other calls.

      We send in our shipmentID and create a stop reference id that we will use for tracking. The stop reference ID is similar to the way we create stop reference numbers for the Tai mobile integration.

      UPDATE LOAD
      This allows authorized users to update a load. This should be used when the carrier is changed.

      DELETE LOAD
      Allows authorized users to delete loads already created in FourKites. This should be used when a shipment has been terminated.

      CALLBACKS
      Tai Software will register a callback URL to which FourKites will send notifications (via HTTPS POST method) related to the loads they have created for tracking.

      Callback workflow is triggered after a create load is posted to Fourkites
      1. Create load - POST
      - gets back loadid (4kites reference number)
      2. Load Create Notification
      - includes URL to open public tracking page. We should make this available to the users
      3. tracking Info Assignment
      - driver name / phone / truck number / trailer number is returned
      4. New Location Update
      5. Stop ETA Update – pickup
      - stopreferenceid is our key to identify each stop
      - this call should be used to add exceptions for potential late / missed pickups
      6. Stop ETA Update - delivery
      - ETA update is only sent when the ETA is changed by more than 15 minutes
      7. New location Update
      - this contains GPS locations
      8. Stop Arrival – Pickup location
      - Triggered when the driver enters geo-fence
      - Use this to trigger actual pickup/delivery date/time
      9. Stop departure – Pickup Location
      - Triggered when the driver leaves the geo-fence
      - We should log this as the actual stop departure time
      10. New Location Update
      - This will happen multiple times
      11. Stop ETA update
      - Only called when the ETA is changed
      12. Stop Arrival – delivery
      13. Stop Departure - delivery
      14. Stop File Upload
      - images come back - we download the images

      Webhooks

      https://www.taicloud.net/publicapi/fourkites/notification
      - includes URL to open public tracking page

      https://www.taicloud.net/publicapi/fourkites/etaupdate
      - used to add exceptions for potential late/missed pickups
      - sent when ETA is changed by more than 15 mins

      https://www.taicloud.net/publicapi/fourkites/arrival
      - triggered when the driver enters the geofence

      https://www.taicloud.net/publicapi/fourkites/departure
      - triggered when the driver leaves the geofence

      https://www.taicloud.net/publicapi/fourkites/fileupload
      - potential to pull back POD and ReturnReceipt

      https://www.taicloud.net/publicapi/fourkites/locationupdate
      - location updates w/ geolocation

      https://www.taicloud.net/publicapi/fourkites/trackingInfoAssignment
      - the following is returned: driver name, phone number, trucker number, and trailer number

      FourKites PUSH

      The Fourkites integration will transmit location information to the Fourkites platform via API Integration. 

      To set this up: 

      1. Obtain credentials from Fourkites. Username/Password are required.
      2. Go to Rates --> Integration Sources
      3. Click Add New Integration Source
      4. Enter a name for the integration
      5. Source Group = Other / Source Type = FourKites
      6. Enter Username/Password and click Save
      7. Click Edit and in the Source Settings section add a new setting
      8. Name = "CustomerId" (without the quotes)
      9. Value = The customer's id which can be viewed in the customer profile

      When setting up the integration, Fourkites may provide a clientID and clientSecret that are in encoded format. If so, ask them to provide the username/password. The TMS will encode the credentials when the payload is transmitted. 

      The endpoint that we transmit LAT/LONG to is:

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

      After the integration source is saved, any active (In Transit or Delivered) shipments for this customer will transmit data to Fourkites. The shipment data requires a Secondary BOL Number which would be the corresponding ID in Fourkites and also requires LAT/LONG data which is saved in the TMS.

      **Note: the LAT/LONG data will only be pull from one of our tracking integration or by the Request driver location feature**