Load Tracking API

Load Tracking API — Request/Response

Endpoint: POST /orders (example path — please provide us your tracking service’s URL)

Content-Type: application/json

Purpose

Webhook to receive a load for tracking.

Request Body (JSON)

The request body is a single JSON object with an Order object. Below is the schema and field descriptions.

Authentication

FMS will assign you a API Tracking ID for the tracking integration for the customer.  This will authenticate us to the customer’s account. GUID format is preferred. Must be under 255 characters.  The Webhook will listen for this ID in Order.Notifications.Notification.PartnerMPID  as definition below explains.  IP Address firewall inclusion is also a great idea when listening with the webhook.

Top-level schema

Path	Type	Required	Description
Order	object	Yes	Root object describing the order to track.
Order.TrackVia	object	Yes	Contact transport/driver methods.
Order.TrackVia.Number	array of object	Yes	List of phone numbers for the driver.
Order.TrackVia.Number[].Type	string	Yes	“Mobile” is the only acceptable value.
Order.TrackVia.Number[].Value	string	Yes	Phone number 10-digits, no dashes.
Order.TrackStartDateTime	string (DateTime)	Yes	Date/time to start tracking. Example: 2024-01-22 14:45 ET.
Order.Notifications.Notification	object	Yes	Notification & scheduling parameters.
Order.Notifications.Notification.PartnerMPID	string	Yes	Your assigned ID for the tracking integration for the customer. This will authenticate us to the customer’s account. GUID format is preferred but not required. Must be under 255 characters.
Order.Notifications.Notification.IDNumber	string	Yes	TMS load identifier.
Order.Notifications.Notification.TrackDurationInHours	string	Yes	How many hours to track the load.
Order.Notifications.Notification.TrackIntervalInMinutes	string	Yes	How frequently to poll the truck for location.
Order.Carrier	object	Yes	Carrier information.
Order.Carrier.Name	string	Yes	Carrier name (e.g. “XYZ TRUCKING LLC”).
Order.Carrier.CarrierID	string	Yes	FMS identifier for the carrier.
Order.TripSheet.Stops.Stop	array of object	Yes	Stops in the trip.
Order.TripSheet.Stops.Stop[].StopID	string	Yes	FMS ID for this stop (returned later with updates).
Order.TripSheet.Stops.Stop[].Name	string	Yes	Stop display name.
Order.TripSheet.Stops.Stop[].StopType	string	Yes	Either "PickUp" or "DropOff".
Order.TripSheet.Stops.Stop[].Address	object	No	Address object for the stop.
Order.TripSheet.Stops.Stop[].Address.Line1	string	Yes	Primary address line.
Order.TripSheet.Stops.Stop[].Address.Line2	string	No	Secondary address line.
Order.TripSheet.Stops.Stop[].Address.City	string	Yes	City.
Order.TripSheet.Stops.Stop[].Address.StateOrProvince	string	Yes	State or province code (e.g. “TN”).
Order.TripSheet.Stops.Stop[].Address.PostalCode	string	No	Postal / ZIP code.
Order.TripSheet.Stops.Stop[].StartDateTime	string (RFC3339 / ISO8601)	Yes	Earliest time of the arrival window (example: 2024-01-22T09:00:00-05:00).
Order.TripSheet.Stops.Stop[].EndDateTime	string (RFC3339 / ISO8601)	No	Latest time of the arrival window.
Order.Notes	string	No	Free text for additional load information; for example delivery instructions.

Example Request

{
  "Order": {
    "TrackVia": {
      "Number": [
        { "Type": "Mobile", "Value": "5551112222" },
        { "Type": "Mobile", "Value": "5552223333" }
      ]
    },
    "TrackStartDateTime": "2024-01-22 14:45 ET",
    "Notifications": {
      "Notification": {
        "PartnerMPID": "477c03ff-e0f4-4c36-9cb5-249fabe7e0d3",
        "IDNumber": "2-119859-0-1",
        "TrackDurationInHours": "102",
        "TrackIntervalInMinutes": "15"
      }
    },
    "Carrier": {
      "Name": "XYZ TRUCKING LLC",
      "CarrierID": "123-0"
    },
    "TripSheet": {
      "Stops": {
        "Stop": [
          {
            "StopID": "2-119859-0-1-1",
            "Name": "Stop 1: ACME PLUS DC",
            "StopType": "PickUp",
            "Address": {
              "Line1": "135 E 12TH STREET RD",
              "Line2": "",
              "City": "LENOIR CITY",
              "StateOrProvince": "TN",
              "PostalCode": "37771"
            },
            "StartDateTime": "2024-01-22T09:00:00-05:00",
            "EndDateTime": "2024-01-22T12:00:00-05:00"
          },
          {
            "StopID": "2-119859-0-1-2",
            "Name": "Stop 2: HARBOR TERMINAL",
            "StopType": "DropOff",
            "Address": {
              "Line1": "100 E MAIN ST",
              "Line2": "",
              "City": "PASCO",
              "StateOrProvince": "WA",
              "PostalCode": "99301"
            },
            "StartDateTime": "2024-01-24T09:00:00-08:00",
            "EndDateTime": "2024-01-24T15:00:00-08:00"
          }
        ]
      }
    },
    "Notes": "LENOIR CITY, TN - PASCO, WA"
  }
}
  

Successful Response

Return when order creation is successful.

{
  "OrderResult": {
    "Status": "Success",
    "OrderID": "TRACKING-67890"
  }
}
  

Failure Response

Return when order creation fails. Provide actionable error messages.

{
  "OrderResult": {
    "Status": "Failure",
    "Errors": [
      { "Message": "Missing required field: Order.TripSheet.Stops.Stop[0].StartDateTime" },
      { "Message": "Invalid phone number format for TrackVia.Number[0].Value" }
    ]
  }
}
  

Notes & Recommendations

• PartnerMPID will be a unique value assigned to each of our mutual customers using your service. GUID format is preferred but not required. Must be 255 characters or less.
• OrderID in the success response is the primary identifier for the load in your tracking service and must be used for all subsequent updates about this load.
• Return HTTP status codes appropriately: 201 Created for success (or 200 OK), 400 Bad Request for client validation errors, and 500 for server errors.

Validation checklist (recommended)

• Carrier, Partner and Load identifiers are validated against known customers when provided.
• Respond with clear error messages in the Errors array for easy troubleshooting.

---