FTL Trips overview
The FTL Trips API lets you create FTLs (full truck loads), read and change the trips that carry them, and run them with your own drivers. Some steps are done in the Mile web app: creating a trip, optimizing it, and assigning or offering it to transporters. Transporters use their own endpoints to answer offers and assign their drivers.
Need to create trips, optimize them or assign them to transporters through the API? Contact Mile support and we will enable it for your account.
How it works
Two accounts
The API has two kinds of account. Each has its own login and token, and a token works only on its own endpoints.
Transporter accounts exist once you approve the transporter in the Mile web app. Read authentication and errors before your first call.
Glossary
FTL (full truck load)
A cargo booking that fills one truck: FTL number, bill of lading (BL) number, customer, consignee and one or more containers. created_on is the pickup day and expected_on the delivery day.
The API calls an FTL a shipment in endpoint paths and field names: /shipments, /shipment-trips, shipment_id, shipment_no, stops[].shipment. These names are real and stay as they are. Wherever you see “shipment” in a path, field or API message, read it as FTL.
Customer and consignee
The customer (shown as consigner in responses) is the shipper. By default the container is picked up at the customer’s address. The consignee is the receiver, where the container is delivered.
Container
One container on an FTL: number, seal number, size (20ft, 40ft, 40ft HC, 45ft HC), product, quantity and weight.
Trip
The work for one truck: a list of stops, the order to do them in, and an ETA plan. A trip is run by one driver, either yours or a transporter’s.
Stop
One FTL on a trip: where and when it is picked up, and where and when it is delivered. A stop is identified by its order_id.
Outbound and return leg
Every stop is on the outbound leg (the default) or the return leg. Return stops are done after the outbound deliveries, for example taking empty containers back to the port.
Round trip
A trip with at least one return stop. Its type is round_trip. A trip with only outbound stops has type outbound.
Transporter (partner)
An outside trucking company that works for you. Company endpoints and the web app call it a partner (partner, partner_id). Transporter endpoints call it a transporter. They are the same thing. The /api/v1/partners prefix is shared by all endpoints and does not mean transporter.
Outsource
Give a trip to a transporter, in the Mile web app. You can do it directly, or through offers that the transporter accepts or rejects.
Offer
An offer asks one transporter to take one trip before a deadline. You send offers from the web app, for one or more trips, each with an ordered list of transporters to try.
Own driver and transporter driver
Your own drivers work for your company and go on trips you keep. Transporter drivers belong to a transporter. Through the API, only that transporter can put them on a trip, and only on trips outsourced to it.
ETA plan
Mile’s estimate of the truck’s day: when it leaves, reaches each stop, waits, rests and gets back. See ETA plan.