{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.6",
    "title": "LoadTrack - Create or Update Track",
    "termsOfService": "https://www.truckertools.com/terms/",
    "contact": {
      "email": "integrations@truckertools.com"
    },
    "license": {
      "name": "Private",
      "url": "https://www.truckertools.com"
    },
    "description": "Requests are authenticated by the `partnerId` and `accountId` attributes in the body.\nThese values will be provided by TruckerTools during onboarding, the latter already being encrypted.\n"
  },
  "security": [],
  "paths": {
    "/loadtrackservice/LTL": {
      "post": {
        "summary": "Create a new track",
        "operationId": "createLoadTrack",
        "responses": {
          "200": {
            "$ref": "#/components/responses/LoadTrackResponse"
          }
        },
        "requestBody": {
          "$ref": "#/components/requestBodies/LoadTrackRequest"
        }
      },
      "put": {
        "summary": "Update an existing track",
        "operationId": "updateLoadTrack",
        "responses": {
          "200": {
            "$ref": "#/components/responses/LoadTrackResponse"
          }
        },
        "requestBody": {
          "$ref": "#/components/requestBodies/LoadTrackRequest"
        }
      }
    }
  },
  "servers": [
    {
      "description": "Production Server",
      "url": "https://loadtracking.truckertools.com"
    }
  ],
  "components": {
    "schemas": {
      "LoadTrack": {
        "type": "object",
        "required": [
          "partnerId",
          "accountId",
          "loadTrackExternalId",
          "stops"
        ],
        "properties": {
          "partnerId": {
            "type": "integer",
            "minimum": 0,
            "example": 12345,
            "format": "int64",
            "description": "This is a unique integer id that is assigned to the Partner system to identify the Partner system by the Load Track system. This has to be sent on each webservice call.\n"
          },
          "accountId": {
            "type": "string",
            "example": "E++p1waC69ktJerPRkJHQg==",
            "description": "Unique identifier of the Agent in the Broker System that entered the Load Track. This accountId has to be encrypted with the shared secret of the partner. This shared secret will be shared during the integration process.\n"
          },
          "loadNumber": {
            "type": "string",
            "example": 12345,
            "minLength": 0,
            "maxLength": 50,
            "description": "Load Number that is specified by the Broker. This could be the pro number.\n"
          },
          "loadTrackExternalId": {
            "type": "string",
            "example": 54321,
            "description": "The unique identifier of the Load in the Partner system.\n"
          },
          "dispatcherId": {
            "type": "string",
            "example": 123,
            "minLength": 0,
            "maxLength": 200,
            "description": "Dispatcher id of the TMS software. Used to group the loads on Load Track website.\n"
          },
          "dispatcherEmail": {
            "type": "string",
            "format": "email",
            "minLength": 0,
            "maxLength": 200,
            "description": "Dispatcher email of the TMS software. Used to send the broker emails a CC.\n"
          },
          "dispatcherPhoneNumber": {
            "type": "string",
            "format": "phone",
            "minLength": 0,
            "maxLength": 200,
            "example": 7035551234,
            "description": "Dispatcher phone of the TMS software. Used to group the loads on Load Track website.\n"
          },
          "trackMethod": {
            "type": "string",
            "enum": [
              "APP",
              "ELD"
            ],
            "description": "Designate the type of tracking preferred. If \"APP\" is sent, the load will\n  automatically track via the mobile app and not try to track via ELD. If \n  the field is null or \"ELD\" is sent, the load will go through the standard\n  waterfall process trying ELD if the carrier is ELD integrated then app \n  tracking if ELD tracking is not successful. If the carrier is not ELD\n  integrated, it will automatically waterfall to app tracking.\n"
          },
          "scac": {
            "type": "string",
            "example": "ABCD",
            "description": "Broker's SCAC tied to the load. This field is only used to support 3rd party tracking provider integrations (e.g., 4Kites) when the broker has multiple carrier accounts that supply load updates to the 3rd party tracking provider.\n"
          },
          "textmessage": {
            "type": "string",
            "minLength": 0,
            "maxLength": 100,
            "description": "Text message that will be used as the text that is sent to the driver.\n"
          },
          "loadType": {
            "type": "string",
            "minLength": 0,
            "maxLength": 100,
            "example": "R",
            "description": "The type of load. This can be an equipment type as well, such as `R` for Reefer.\n"
          },
          "trailerType": {
            "type": "string",
            "minLength": 0,
            "maxLength": 100,
            "example": "R",
            "description": "Some customers use this for the type of load or DAT trailer type This can be equipment type as well such as `R` for Reefer.\n"
          },
          "revenueType": {
            "type": "string",
            "minLength": 0,
            "maxLength": 100,
            "default": null,
            "example": "TMS",
            "description": "Optional flag for the type of load.\n"
          },
          "driverCell": {
            "type": "string",
            "format": "phone",
            "example": 7035554321,
            "description": "Ten-digit or twelve-digit cell phone number of driver that will haul the load. This is an optional field and if omitted an email is sent to the Carrier Dispatcher to update the cell phone number. This number should be a valid cell phone number that is either an iPhone or an Android.\n"
          },
          "trailerNumber": {
            "type": "string",
            "minLength": 0,
            "maxLength": 45,
            "example": 67890,
            "description": "Number assigned to cargo trailer.\n"
          },
          "truckNumber": {
            "type": "string",
            "minLength": 0,
            "maxLength": 45,
            "example": 12345,
            "description": "Number assigned to truck or vehicle.\n"
          },
          "driverName": {
            "type": "string",
            "minLength": 0,
            "maxLength": 120,
            "example": "Jon Doe",
            "description": "Name of the driver tracking the Load.\n"
          },
          "driverType": {
            "type": "string",
            "enum": [
              "companyDriver",
              "ownerOperatorLeased",
              "ownerOperatorIndependent",
              "otherCarrierCompanyDriver"
            ],
            "description": "Type of the driver tracking the Load.\n"
          },
          "driverComments": {
            "type": "string",
            "minLength": 0,
            "maxLength": 2000,
            "example": "Driver comments.",
            "description": "Comment for the driver to see.\n"
          },
          "loadNotes": {
            "type": "string",
            "minLength": 0,
            "maxLength": 2000,
            "description": "Notes about the load. Driver will not see this.\n"
          },
          "isTeamLoad": {
            "type": "boolean",
            "default": false,
            "description": "Indicate if load is handled by multiple drivers.\n"
          },
          "minTemp": {
            "type": "number",
            "example": 30,
            "description": "Minimum temperature asset is supposed to reach."
          },
          "maxTemp": {
            "type": "number",
            "example": 40,
            "description": "Maximum temperature asset is supposed to reach."
          },
          "tempUoM": {
            "type": "string",
            "enum": [
              "fahrenheit",
              "celsius"
            ],
            "example": "fahrenheit",
            "description": "How temperature of asset is measured."
          },
          "carrierDispatcherEmail": {
            "type": "string",
            "minLength": 0,
            "maxLength": 100,
            "format": "email",
            "description": "Carrier dispatcher email address for carrier that will do the load track. It is important for this email to be a valid and functional email address. All communications are done to this email address by the TruckerTools system, including the email that is generated when a new load track is created in the system. This email will have the link for the carrier dispatcher to update the driver cell phone and also the map to show the status of the Load Track.\n"
          },
          "carrier": {
            "type": "object",
            "properties": {
              "companyName": {
                "type": "string",
                "minLength": 0,
                "maxLength": 100,
                "description": "Name of the carrier that will do the load track. This field is recommended but not required.\n"
              },
              "docketNumber": {
                "type": "string",
                "minLength": 0,
                "maxLength": 10,
                "example": 12345,
                "description": "MC number of the carrier hauling the load. This is required for ELD tracking. It also provides valuable insights for carrier scorecarding.\n"
              },
              "contactName": {
                "type": "string",
                "minLength": 0,
                "maxLength": 100,
                "description": "Legal name of carrier that will do the load track.\n"
              },
              "contactPhone": {
                "type": "string",
                "minLength": 0,
                "maxLength": 10,
                "description": "Ten-digit telephone number of carrier.\n",
                "format": "phone"
              },
              "contactPhoneExt": {
                "type": "string",
                "minLength": 0,
                "maxLength": 10,
                "description": "Telephone extension of carrier.\n"
              }
            }
          },
          "carriers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "companyName": {
                  "type": "string",
                  "minLength": 0,
                  "maxLength": 100,
                  "description": "Name of the carrier that will do the load track. This field is recommended but not required.\n"
                },
                "docketNumber": {
                  "type": "string",
                  "minLength": 0,
                  "maxLength": 10,
                  "example": 12345,
                  "description": "MC number of the carrier hauling the load. This is required for ELD tracking. It also provides valuable insights for carrier scorecarding.\n"
                },
                "contactName": {
                  "type": "string",
                  "minLength": 0,
                  "maxLength": 100,
                  "description": "Legal name of carrier that will do the load track.\n"
                },
                "contactPhone": {
                  "type": "string",
                  "minLength": 0,
                  "maxLength": 10,
                  "description": "Ten-digit telephone number of carrier.\n",
                  "format": "phone"
                },
                "contactPhoneExt": {
                  "type": "string",
                  "minLength": 0,
                  "maxLength": 10,
                  "description": "Telephone extension of carrier.\n"
                },
                "driverPhoneNumbers": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string",
                        "minLength": 0,
                        "maxLength": 120,
                        "example": "Jon Doe",
                        "description": "Name of the driver tracking the Load.\n"
                      },
                      "phone": {
                        "type": "string",
                        "format": "phone",
                        "example": 7035554321,
                        "description": "Ten-digit cell phone number of driver that will haul the load.\n"
                      }
                    }
                  }
                }
              }
            }
          },
          "broker": {
            "type": "object",
            "properties": {
              "companyName": {
                "type": "string",
                "minLength": 0,
                "maxLength": 120,
                "description": "Name of the broker that will do the load track. This field is recommended but not required.\n"
              },
              "docketNumber": {
                "type": "string",
                "minLength": 0,
                "maxLength": 10,
                "description": "Docket number of interstate broker that will do the load track. Docket numbers are usually 6 digits and are prefixed by a MC, FF or MX.\n",
                "example": "MC456123"
              },
              "contactName": {
                "type": "string",
                "minLength": 0,
                "maxLength": 120,
                "description": "Legal name of broker that will do the load track.\n"
              },
              "contactPhone": {
                "type": "string",
                "minLength": 0,
                "maxLength": 10,
                "description": "Ten-digit telephone number of broker.\n",
                "format": "phone"
              },
              "contactPhoneExt": {
                "type": "string",
                "minLength": 0,
                "maxLength": 10,
                "description": "Telephone extension of broker.\n"
              },
              "contactEmail": {
                "type": "string",
                "minLength": 0,
                "maxLength": 100,
                "description": "Email address of the broker.\n"
              }
            }
          },
          "shipper": {
            "type": "object",
            "properties": {
              "shipperId": {
                "type": "string",
                "minLength": 0,
                "maxLength": 200,
                "description": "Shipper Id / Bill To Id in the broker system.\n"
              },
              "loadNumber": {
                "type": "string",
                "minLength": 0,
                "maxLength": 50,
                "description": "Load Number used by the shipper. It is used to communicate with Shipper if shipper needs to be notified.\n"
              },
              "emails": {
                "type": "string",
                "minLength": 0,
                "maxLength": 250,
                "description": "Comma separated list of emails of the shippers who need to be notified about the load track.\n"
              },
              "emailInterval": {
                "type": "integer",
                "minimum": 0,
                "example": 1,
                "description": "The number represents the interval in hours when shipper needs an email notification for that particular load.\n"
              },
              "referenceNumber": {
                "type": "string",
                "description": "Optional Tracking Number used by the shipper. It is used to communicate with Shipper if shipper needs to be notified.\n"
              }
            }
          },
          "metadata": {
            "type": "array",
            "description": "List of metadata that can be added to Load. These are typically used to tag the load for searching.\n",
            "items": {
              "$ref": "#/components/schemas/Metadata"
            }
          },
          "stops": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Stop"
            }
          }
        }
      },
      "Stop": {
        "type": "object",
        "required": [
          "orderNumber",
          "address",
          "city",
          "state",
          "zipcode",
          "datetime"
        ],
        "properties": {
          "orderNumber": {
            "type": "integer",
            "minimum": 1,
            "description": "The order of the stop. The number shall start from 1.\n"
          },
          "locationName": {
            "type": "string",
            "description": "Name of the stop location or shipper/receiver, such as Walmart Danville. This name can be utilized to identify loads that have special requirements based on the shipper/receiver/location.\n"
          },
          "locationId": {
            "type": "string",
            "description": "ID of stop location or shipper/receiver, such as WAL133. This ID can be utilized to identify loads that have special requirements based on the shipper/receiver/location.\n"
          },
          "address": {
            "type": "string",
            "minLength": 0,
            "maxLength": 100,
            "description": "Street address for the stop. This field is recommended but not required.\n"
          },
          "city": {
            "type": "string",
            "minLength": 1,
            "maxLength": 50,
            "description": "City name of the stop.\n"
          },
          "state": {
            "type": "string",
            "minLength": 2,
            "maxLength": 4,
            "description": "State abbreviation or province abbreviation for the stop. Value will be 2 characters for state or province abbreviation, such as VA.\n",
            "example": "VA"
          },
          "zipcode": {
            "type": "string",
            "minLength": 1,
            "maxLength": 10,
            "example": 20148,
            "description": "Zip code or postal code for the load. Expected values should be 5 digit numeric zip code or 7 alphanumeric characters of Canadian postal code.\n"
          },
          "lat": {
            "type": "number",
            "minLength": 0,
            "description": "Latitude of the geo location of the stop\n"
          },
          "lon": {
            "type": "number",
            "minLength": 0,
            "description": "Longitude of the geo location of the stop\n"
          },
          "datetime": {
            "type": "string",
            "format": "date-time",
            "pattern": "m/d/Y H:i:s T",
            "example": "10/14/2021 12:14:45 EST"
          },
          "stopGMTDiff": {
            "type": "string",
            "description": "GMT offset of the stop.\n"
          },
          "datetimeExit": {
            "type": "string",
            "format": "data-time",
            "pattern": "m/d/Y H:i:s T",
            "example": "10/14/2021 12:14:45 EST"
          },
          "geofenceRadius": {
            "type": "integer",
            "description": "This value indicates the distance from the stop location at which the geofence alerts have to setup. The value is in miles.\n"
          },
          "notes": {
            "type": "string",
            "minLength": 0,
            "maxLength": 120,
            "description": "The comments for the driver to see for this load.\n"
          },
          "stopExternalId": {
            "type": "string",
            "minLength": 0,
            "maxLength": 120,
            "description": "A unique ID that is associated with this stop for this load in the external system. This will be sent back in the response of events that are associated with this.\n"
          },
          "actions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StopAction"
            }
          },
          "metadata": {
            "type": "array",
            "description": "List of metadata that can be added to each stop like the name, pickup number or delivery number.\n",
            "items": {
              "$ref": "#/components/schemas/Metadata"
            }
          }
        }
      },
      "StopAction": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "maxLength": 10,
            "description": "ID of the action.\n"
          },
          "name": {
            "type": "string",
            "maxLength": 255,
            "description": "Name of the action.\n"
          },
          "item": {
            "type": "string",
            "maxLength": 255,
            "description": "Action item.\n"
          },
          "required": {
            "type": "boolean",
            "description": "Option to mark an action as required. It is not actually required, but the driver will be prompted to complete the action before ending the track.\n"
          },
          "driverInput": {
            "type": "boolean",
            "description": "When true, the mobile app prompts the driver to enter a value to complete this action.\n"
          },
          "options": {
            "type": "array",
            "description": "Optional list of selectable options presented to the driver for this action.\n",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "maxLength": 255,
                  "description": "Display name of the option.      \n"
                }
              }
            }
          }
        },
        "description": "Actions driver can perform at the related stop.\n"
      },
      "Metadata": {
        "description": "Metadata that can be added to a Load.\n",
        "type": "object",
        "required": [
          "name",
          "value"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 0,
            "maxLength": 255,
            "description": "Name of the metadata item.\n"
          },
          "value": {
            "type": "string",
            "minLength": 0,
            "maxLength": 255,
            "description": "Value of the metadata item.\n"
          }
        }
      },
      "ELDAsset": {
        "type": "object",
        "properties": {
          "found": {
            "type": "boolean",
            "default": true,
            "description": "Checks carrier’s vehicle list for provided assetValue, if:\n- **true**: Load is set to ESET. The assetValue is correct and load is set to track via ELD. We will receive location updates 4 hours prior to scheduled pickup time.\n- **false**: Load is set to ESETIA. The assetValue is incorrect and cannot be found; this will return 10 best matched values to your TMS\n"
          }
        }
      },
      "ELDAssetFound": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ELDAsset"
          },
          {
            "type": "object",
            "properties": {
              "found": {
                "type": "boolean",
                "default": true
              },
              "assetValue": {
                "type": "string",
                "example": 321,
                "description": "The tractor or trailer number received from the customer that is assigned to the load based on the carrier’s asset tracking type.\n"
              }
            }
          }
        ]
      },
      "ELDAssetNotFound": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ELDAsset"
          },
          {
            "type": "object",
            "properties": {
              "found": {
                "type": "boolean",
                "default": false
              },
              "assetValue": {
                "type": "string",
                "example": "321-test",
                "description": "The tractor or trailer number received from the customer that is assigned to the load based on the carrier’s asset tracking type.\n"
              },
              "bestMatchAssetList": {
                "type": "array",
                "description": "List of 10 best matched values.\n",
                "items": {
                  "type": "object",
                  "properties": {
                    "value": {
                      "type": "string",
                      "example": 321,
                      "description": "Suggested values within carrier's vehicle list that best matches provided. assetValue\n"
                    },
                    "percentage": {
                      "type": "number",
                      "example": 99,
                      "description": "The rating or score of corresponding value matching assetValue.\n"
                    }
                  }
                }
              }
            }
          }
        ]
      }
    },
    "responses": {
      "LoadTrackResponse": {
        "description": "LoadTrack Response\n",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "status",
                "timeStamp"
              ],
              "properties": {
                "response": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "boolean",
                      "description": "Success indicator.\n"
                    },
                    "timeStamp": {
                      "type": "string",
                      "description": "Server timestamp.\n"
                    },
                    "loadId": {
                      "type": "integer",
                      "description": "Unique ID in LoadTrack. This is not provided in case of error.\n"
                    },
                    "trackingMethod": {
                      "type": "string",
                      "enum": [
                        "ELD",
                        "APP"
                      ]
                    },
                    "mapLink": {
                      "type": "string",
                      "example": "http://www.truckertools.com/us/f8ma90615f1dae80fbc",
                      "description": "Load track map URL. Provides a map route map of the Load Track that can be embedded in an iframe. This will not be provided in case of error.\n"
                    },
                    "statusPageLink": {
                      "type": "string",
                      "example": "http://www.truckertools.com/us/bcza73615f1daef3772",
                      "description": "Load track status URL. Provides an image representing the status of the Load Track. It can be embedded in client websites. This will not be provided in case of an error.\n"
                    },
                    "detailsLink": {
                      "type": "string",
                      "example": "http://www.truckertools.com/us/t28qnc615f1daca5ee3",
                      "description": "Load track details URL. Provides the full details of the Load Track including the status and the route map. This will not be provided in case of an error.\n"
                    },
                    "detailsLinkNoAuth": {
                      "type": "string",
                      "example": "http://www.truckertools.com/us/77100x615f1dad23281",
                      "description": "Load track details URL for unauthenticated users. Provides partial details of the Load Track including the status and the route map, but without editing capabilities. This will not be provided in case of an error.\n"
                    },
                    "carrierLink": {
                      "type": "string",
                      "example": "http://www.truckertools.com/us/8w3a3p615f1dad938fd",
                      "description": "Load track details URL for carriers.\n"
                    },
                    "shipperLink": {
                      "type": "string",
                      "example": "http://www.truckertools.com/us/59qf97615f1dae0fdda",
                      "description": "Load track details URL for shippers.\n"
                    },
                    "eldAsset": {
                      "description": "ELD asset to be tracked.\n",
                      "oneOf": [
                        {
                          "$ref": "#/components/schemas/ELDAssetFound"
                        },
                        {
                          "$ref": "#/components/schemas/ELDAssetNotFound"
                        }
                      ]
                    },
                    "errorCode": {
                      "type": "integer",
                      "description": "Error code. This will not be provided in case of successful creation or update of Load Track.\n",
                      "enum": [
                        101,
                        104,
                        105,
                        301,
                        401
                      ]
                    },
                    "errorMessage": {
                      "type": "string",
                      "description": "A short description of the error. This will not be provided in case of successful creation or update of Load Track.\n",
                      "enum": [
                        "Account not found",
                        "Partner not found",
                        "Load Track not found",
                        "Invalid parameters",
                        "Can't update Load Track as it is already started"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "requestBodies": {
      "LoadTrackRequest": {
        "description": "Load Track object that needs to be added to the load track system.\n",
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/LoadTrack"
            }
          }
        }
      }
    }
  }
}