Skip to main content

Register a tracking request

Currently, our legacy API allows you to register a tracking request and also sync the current "state" of a load by submitting a payload to the same end-point.

This will be replaced by our new event-based end-point in the future.

This API is for Chaine customers to sync load information from their TMS to the Chaine Platform.

Note: The TMS-Sync API is for Chaine's customers that have a Chaine Platform account. If you're a trading partner of a Chaine customer looking to provide tracking updates, please refer to the Visibility section.

This endpoint can be triggered when a new load is created or for any load status changes, load activity update, or any other updates to load data in TMS.

Note, this end-point is designed to take the current state of the load. It is most effective when the current state of a load is provided in all variables.

Base URL​

The base URL used for the TMS-Sync API is formatted as shown below:

http://api{.env}.track.loadtap.com/api/v1/external/tms/loads
  • For Production, remove the {}
  • For Staging, replace {.env} with .uat

Headers​

A typical HTTP request to the TMS-Sync API includes the following headers:

Content-Type: application/json; charset=utf8
  • Content-Type: "application/json". If you need to send another type, please reach out to your Chaine rep.

Query Params​

x-lt-tms-api-key: {master_api_token or secondary_api_token}
x-lt-tms-account-id: {unique Chaine account_sid}
x-lt-tms-type: {use "external" for custom, or see below for others}
  • x-lt-tms-api-key: Either the Main API token or a secondary API token is required for Chaine server to authenticate your API requests. An exception occurs when you attempt to perform certain actions outside the scope of the current application such as creating a new load, or retrieving a list of messages, in which case you should provide Basic Authentication.
  • x-lt-tms-account-id: Every request must contain an account-sid header with your unique Chaine account-sid.
  • x-lt-tms-type: For all custom integrations, use "external". For 3rd-party TMS, use the appropriate value based on the TMS:
    • MercuryGate: "mercuryGate"
    • Revenova: "revenova"
    • 3GTMS: "3gtms"

Register and Update Load

Use this end-point to both register a new load for tracking and also to update an existing registered load with the current state.

POST http://api{.env}.track.loadtap.com/api/v1/external/tms/loads

How to use the API​

The most simpliest way to use this API is to hit send a request on any change, and let our ingestion engine handle it on our end. The API is extremely scalable with very high rate-limits, so API volume is not a concern.

The easiest way to sync a load is to call our API for any state change on the load. We will process the changes.

If you are concerened with any performance issues, you can also choose to send it only on required field changes. This will require more fine grained effort on your end. The required scenarios are when changes occur to:

  1. Shipment tracking status: ETA, arrival or departure times are updated.
  2. Carrier: When changes occur to the carrier name, driver name, driver cell, dispatcher name and dispatcher email.
  3. Load status: Changes to the load status (i.e. if load is cancelled, load goes from "Booked" to "In Transit", etc..)
  4. Stop info changes: if stops are added or removed, or if any of the important pickup information changes such as appointment times, addresses, special instructions and PU#s.
  5. User: If a user on a load changes (for example, the carrier rep changes)

Example Value Module​

{
  "user": {
    "loginId": "string",
    "firstName": "string",
    "lastName": "string",
    "phoneNumber": "string",
    "email": "user@example.com"
  },
  "activity": {
    "type": "string",
    "activityUpdateDateTime": "2020-05-27T19:57:39.566Z",
    "activityUpdateBy": "string"
  },
  "load": {
    "loadDescription": "string",
    "uniqueRefId": {
      "key": "string",
      "value": "string"
    },
    "equipmentType": "string",
    "modeType": "string",
    "tractorNumber": "string",
    "commodity": "string",
    "geoTrackingOnOff": true,
    "maxPayAmount": "string",
    "hazMat": true,
    "origin": "string",
    "destination": "string",
    "temperatureControlled": true,
    "maintainTemperatureDegrees(F)": "string",
    "weight": "string",
    "distance": "string",
    "instructions": "string",
    "checkCallComments": "string",
    "nextCheckCall": "2020-05-27T19:57:39.567Z",
    "loadStatus": {
      "status": "string",
      "statusCode": "string",
      "statusTime": "2020-05-27T19:57:39.567Z",
      "updatedBy": "string"
    },
    "contacts": [
      {
        "contactType": "string",
        "contactTypeDescription": "string",
        "phoneNr": 0,
        "name": "string",
        "lastName": "string",
        "firstName": "string",
        "email": "user@example.com",
        "isPrimary": true
      }
    ],
    "customer": {
      "name": "string"
    },
    "carrier": {
      "name": "string",
      "MC": 0,
      "DOT": 0,
      "drivers": [
        {
          "isPrimary": true,
          "contact": {
            "firstName": "string",
            "lastName": "string",
            "phoneNr": 0,
            "email": "user@example.com"
          }
        }
      ],
      "dispatchers": [
        {
          "isPrimary": true,
          "contact": {
            "firstName": "string",
            "lastName": "string",
            "phoneNr": 0,
            "email": "user@example.com"
          }
        }
      ]
    },
    "pickAndDrops": [
      {
        "type": "string",
        "uniqueRefId": "string",
        "stopNumber": "string",
        "stopName": "string",
        "pickUpDeliveryNumber": "string",
        "locationName": "string",
        "instructions": "string",
        "comments": "string",
        "shippingReceivingHours": "string",
        "appointmentRequired": true,
        "references": "string",
        "arrivalStatus": "string",
        "carrierStatus": "string",
        "carrierStatusComments": "string",
        "carrierStatusDateTime": "2020-05-27T19:57:39.567Z",
        "address": {
          "street": "string",
          "suite": "string",
          "city": "string",
          "state": "string",
          "country": "string",
          "postalCode": 0
        },
        "stopStatus": {
          "updatedBy": "string",
          "statusTime": "2020-05-27T19:57:39.567Z",
          "statusCode": "string",
          "status": "string"
        },
        "dateTimes": {
          "earliest": "2020-05-27T19:57:39.567Z",
          "appointment": "2020-05-27T19:57:39.567Z",
          "latest": "2020-05-27T19:57:39.567Z",
          "eta": "2020-05-27T19:57:39.567Z",
          "etaComments": "string"
        },
        "warehouse": [
          {
            "isPrimary": true,
            "contact": {
              "firstName": "string",
              "lastName": "string",
              "phoneNr": "string",
              "email": "user@example.com"
            }
          }
        ]
      }
    ]
  }
}

Sample Request​

{
  "user": {
    "phone": null,
    "loginId": "collin@greatbrokerage.com",
    "lastName": "Fasthands",
    "firstName": "Collin",
    "email": "collin@greatbrokerage.com"
  },
  "load": {
    "weight": "19000(lbs)",
    "uniqueRefId": {
      "value": "a0j2E00000Cg3wlQAB",
      "key": "Load Id"
    },
    "tractorNumber": "355/19915",
    "temperatureControlled": false,
    "pickAndDrops": [
      {
        "warehouseInfo": [
          {
            "shippingReceivingHours": "00:00-00:00",
            "isPrimary": true,
            "contact": {
              "phoneNr": "404-322-1943",
              "name": "Debbie Williams",
              "lastName": "Williams",
              "firstName": "Debbie",
              "email": "debbie@supercoolwarehouse.com"
            }
          }
        ],
        "uniqueRefId": "a0t2E000009Ctv9QAC",
        "type": "pick",
        "stopStatus": {
          "updatedBy": "",
          "statusTime": "2020-06-26 00:00:00",
          "statusCode": "Departed",
          "status": "Departed"
        },
        "stopNumber": "Stop 1",
        "stopName": "Super Cool Warehouse",
        "shippingReceivingHours": "00:00-00:00",
        "references": "READY NOON FRIDAY",
        "pickUpDeliveryNumber": "3178",
        "locationName": "Super Cool Warehouse",
        "instructions": "*VAN OR REEFER WORKS*\r\n\r\n*PLEASE ARRIVE AS CLOSE TO THE LOAD READY TIME AS POSSIBLE TO ENSURE A QUICK LOADING PROCESS*",
        "dateTimes": {
          "latest": "2020-06-26 00:00:00",
          "earliest": "2020-06-26 00:00:00",
          "appointment": null
        },
        "carrierStatusComments": "per dispat",
        "carrierStatusAsOf": "2020-06-26 14:42:53",
        "carrierStatus": "Loaded Clean",
        "arrivalStatus": "On Time",
        "appointmentRequired": false,
        "address": {
          "city": "PERRYVILLE",
          "country": "United States",
          "countryCode": "US",
          "geocodeAccuracy": "Block",
          "latitude": 37.739967,
          "longitude": -89.860951,
          "postalCode": "63775",
          "state": "Missouri",
          "stateCode": "MO",
          "street": "444 Wicnchester Road"
        }
      },
      {
        "warehouseInfo": [
          {
            "shippingReceivingHours": "00:45-01:45",
            "isPrimary": true,
            "contact": {
              "phoneNr": "",
              "name": "",
              "lastName": "",
              "firstName": "",
              "email": ""
            }
          }
        ],
        "uniqueRefId": "a0t2E000009CtvAQAS",
        "type": "drop",
        "stopStatus": {
          "updatedBy": "",
          "statusTime": "",
          "statusCode": null,
          "status": null
        },
        "stopNumber": "Stop 2",
        "stopName": "Super Easy Drop Warehouse",
        "shippingReceivingHours": "00:45-01:45",
        "references": "145AM APPT MONDAY",
        "pickUpDeliveryNumber": "143-6996154",
        "locationName": "Super Cool Warehouse",
        "instructions": "***DELIVERY CANNOT BE LATE***",
        "dateTimes": {
          "latest": "2020-06-29 01:45:00",
          "earliest": "2020-06-29 00:45:00",
          "appointment": "2020-06-29 01:45:00"
        },
        "carrierStatusComments": null,
        "carrierStatusAsOf": null,
        "carrierStatus": null,
        "arrivalStatus": "1388mi / 2233km away",
        "appointmentRequired": true,
        "address": {
          "city": "FARR WEST",
          "country": "United States",
          "countryCode": "US",
          "geocodeAccuracy": "Block",
          "latitude": 41.304621,
          "longitude": -112.024901,
          "postalCode": "84404",
          "state": "Utah",
          "stateCode": "UT",
          "street": "2530 N 1850 W"
        }
      }
    ],
    "otherInstructions": null,
    "otherCarrierCapabilities": null,
    "origin": "PERRYVILLE, Missouri",
    "offerRateType": "Fixed Cost",
    "offerRateText": "We are looking to source a carrier for this load and are willing to pay $ 2000 Fixed Cost. If you are interested in this load, please Submit a Quote in this amount by clicking the SUBMIT link below",
    "offerRate": "2000.00",
    "nextCheckCall": null,
    "maxPayAmount": null,
    "maintainTemperatureDegreesF": null,
    "loadStatus": {
      "updatedBy": "",
      "statusTime": "",
      "statusCode": "In Transit",
      "status": "In Transit"
    },
    "loadDescription": "662920",
    "internalCoordinationComments": "VAN OR REEFER WORKS",
    "hazMat": false,
    "geoTrackingOnOff": true,
    "equipmentType": "a0V2E00000CuLbhUAF",
    "equipmentCategory": "Van",
    "distanceMiles": "1392.53",
    "destination": "FARR WEST, Utah",
    "customer": {
      "name": "Best Customer Ever"
    },
    "contacts": [
      {
        "phoneNr": "(855) 999-0666",
        "name": "Cal Moneymaker",
        "lastName": "Moneymaker",
        "isPrimary": true,
        "firstName": "Cal",
        "email": "cal@greatbrokerage.com",
        "contactTypeDescription": "Carrier Sales Rep",
        "contactType": "carrierSalesRep"
      },
      {
        "phoneNr": null,
        "name": "Bradley Poland",
        "lastName": "Polands",
        "isPrimary": true,
        "firstName": "Bradley",
        "email": "bradley@greatbrokerage.com",
        "contactTypeDescription": "Customer Sales Rep",
        "contactType": "customerSalesRep"
      }
    ],
    "commodity": "DRY FOOD PRODUCT",
    "checkCallComments": "Per Wesley the dispatcher, 1pm ETA",
    "carrier": {
      "scheduleStatus": null,
      "salesStatus": "Won",
      "name": "SUPER TRUCKING LLC",
      "marginQuoted": "1050.00",
      "drivers": [
        {
          "isPrimary": true,
          "contact": {
            "phoneNr": "226-444-8777",
            "name": "tony",
            "lastName": "tony",
            "firstName": "tony",
            "email": ""
          },
          "comments": "mc 860800"
        }
      ],
      "dispatchers": [
        {
          "isPrimary": true,
          "contact": {
            "phoneNr": "222-240-0000",
            "name": "jane",
            "lastName": "jane",
            "firstName": "jane",
            "email": "dispatch@supertrucking.com"
          }
        }
      ],
      "costQuoted": ""
    }
  },
  "lastModifiedBy": {
    "phone": "(855) 999-0666",
    "loginId": "cal@greatbrokerage.com",
    "lastName": "Moneymaker",
    "firstName": "Cal",
    "email": "cal@greatbrokerage.com"
  }
}