Resources and prompts¶

Resources¶

Reference material any connection may read, and templates that serve your own data under exactly the same rules as the matching tool. Generated from the running server.

URI	What it is
`freightright://guides/pricing-and-booking`	Pricing, quoting and booking — reference material about how Freight Right answers. The same for every customer; needs no permission.
`freightright://guides/querying`	Finding shipments — reference material about how Freight Right answers. The same for every customer; needs no permission.
`freightright://reference/codes`	Codes and vocabulary — reference material about how Freight Right answers. The same for every customer; needs no permission.
`freightright://reference/milestones`	Shipment milestones and dates — reference material about how Freight Right answers. The same for every customer; needs no permission.

Template	What it is
`freightright://rate-requests/{rate_request_id}`	A quote request: its status, the offer once Freight Right has quoted it, and the booking once one was requested. Needs permission to read quote requests.
`freightright://shipments/{reference}`	Everything Freight Right records about one shipment: routing, containers, recorded milestones and estimated or actual dates. Needs permission to read shipments.

Prompts¶

Ready-made starting points. A prompt is text: it authorizes nothing, and the tools it names enforce what they always enforce.

Prompt	What it asks for	Arguments
Arrivals this week (`arrivals-this-week`)	What is due to arrive in the next seven days.	—
Book a price I have seen (`book-an-offer`)	Prepare a booking for me to confirm myself.	`which`
Compare instant prices (`compare-instant-rates`)	Price one lane now and compare the offers.	`lane`
Potentially overdue shipments (`delayed-shipments`)	Shipments whose estimated date has passed with nothing recorded.	—
My open quotes (`open-quotes`)	What is quoted, waiting or booked.	—
Price a container shipment (`price-a-container-shipment`)	Walk me through an FCL price check.	—
Price a pallet or crate shipment (`price-a-pallet-shipment`)	Walk me through an LTL or LCL price check.	—
Ask Freight Right to quote (`request-custom-quote`)	For what instant prices do not cover.	`what`
Track a shipment (`track-shipment`)	Where is one shipment, and what happens next.	`reference`

What the reference documents say¶

Shipment milestones and dates¶

freightright://reference/milestones

Shipment milestones and dates¶

Estimated vs actual. A date with actual happened. A date with only estimated has not: it is a plan that moves. Never tell a customer something has happened because an estimate has passed.

What each date means - departure: the vessel, aircraft or truck left the origin port or facility. - arrival: arrival at the final air or ocean port of the main leg — NOT delivery. - delivery: the goods reached the final destination address. appointment is a booked delivery slot.

Milestones are recorded events, newest last. They come from carriers, terminals and our own operations, so their wording is theirs, not ours — show it, do not interpret it. A shipment with no recent milestone is not necessarily late: not every carrier reports every step.

Times are local to the event's own location, as recorded.

"Potentially overdue" means only that an estimated arrival or delivery date has passed with no actual date recorded. It is not a confirmed delay: ask Freight Right before telling a customer their shipment is late.

Codes and vocabulary¶

freightright://reference/codes

Codes and vocabulary¶

Everything below is generated from the same table the tool schemas use, so it cannot fall behind them.

Places. A PORT is a UN/LOCODE (CNSHA Shanghai, USLAX Los Angeles) or, for air, an airport's IATA code (PVG, FRA). freightright_find_locations turns a place a customer NAMED into that code — use it rather than guessing, because a wrong code is location_not_found and nothing else. A DOOR is a postal code plus an ISO country code; the postal code is used exactly as sent, and needs no lookup.

Modes. FCL (full container load — ocean, priced by the container) · LCL (less than container load — ocean, priced by weight or volume, whichever is greater) · AIR (air freight, airport to airport or door to door) · LTL (less than truckload — road, door to door within the US, within Canada, and between them) · FTL (full truckload — road, door to door in the US, Canada and Mexico; quote requests only, never priced instantly).

A shipment’s transport_mode is not a pricing mode: SEA is the kind of move FCL and LCL price, AIR the kind AIR prices, and ROA or TRK the kind LTL and FTL price. A price check creates nothing and never becomes a shipment — a shipment exists once Freight Right books and operates it.

What each mode needs. FCL: needs containers, direction; refuses hazardous and temperature-controlled cargo — ask for a quote request instead · LCL: needs pieces OR totals, direction · AIR: needs pieces OR totals, direction · LTL: needs pieces, with the dimensions and weight of each handling unit, a DOOR at both ends; refuses direction, incoterm, port charges, customs and insurance — the API has no place for them on a truckload lane; ask for insurance in a quote request note · FTL: needs containers, a DOOR at both ends; refuses direction, incoterm, port charges, customs and insurance; and it is never priced instantly — it is a quote request.

FTL takes its equipment in the containers argument, as container sizes — the current API representation, and the same choices as the Shipment Manager trucking form. Anything else about the truck (trailer type, weight, loading) goes in the quote request note.

Containers. 20GP (20-foot general-purpose container) · 40GP (40-foot general-purpose container) · 40HC (40-foot high-cube container — taller than a 40GP) · 45HC (45-foot high-cube container). A container entry is a type and a quantity; at most 4 entries, so combine quantities of the same type.

Loose cargo. A piece group is any number of IDENTICAL pieces, with the dimensions and weight of ONE of them. At most 30 groups for LTL and 50 for LCL and AIR — a group can be hundreds of pallets, so that is rarely a limit in practice. LCL and AIR accept totals instead when the dimensions are unknown.

Packaging. PALLET (goods on a pallet) · SKID (goods on a skid — a pallet with no bottom deck) · BOX (a box) · CARTON (a cardboard carton) · CASE (a case) · CRATE (a wooden crate) · DRUM (a drum) · BUNDLE (items bundled together) · ROLL (a roll) · BAG (a bag or sack) · BALE (a bale) · COIL (a coil) · TUBE (a tube) · PIECE (a single unpackaged item) · PACKAGE (a package, when nothing more specific fits).

Freight class (LTL). A freight class is classified from the density, handling, stowability and liability of the goods — it is not a price setting. Give dimensions and weight and let it be estimated, or use the class on the customer’s own NMFC paperwork. Never choose a lower class to get a cheaper price: the carrier reweighs and rebills. Values: 50 · 55 · 60 · 65 · 70 · 77.5 · 85 · 92.5 · 100 · 110 · 125 · 150 · 175 · 200 · 250 · 300 · 400 · 500.

Units. Weight KG · LB · dimensions CM · IN · volume CBM · CFT. Decimals accepted: dimensions 2 places, weight 3, volume 4, money 2. More than that is refused rather than rounded — a rounded weight is a different shipment.

Accessorials. LIFTGATE (the truck needs a lift at that end — no loading dock or forklift there) · RESIDENTIAL (a home or a residential street rather than a commercial address) · LIMITED_ACCESS (a site a truck reaches with difficulty — a school, a farm, a construction site, a military base) · INSIDE (the driver carries the goods inside, past the threshold) · APPOINTMENT (the carrier must book a time slot before arriving). Each side needs a DOOR at that end; FCL accepts RESIDENTIAL only.

Insurance. Give the commercial value of the goods as insured_value_usd, in USD. Ocean and air only — LTL and FTL cannot be insured through this API; ask for insurance in a quote request note instead.

Customs. customs_brokerage adds clearance at the destination. SINGLE (a bond for this one entry — quoted separately, not in the offer) · ANNUAL (a continuous bond covering a year of entries — adds a charge to the offer) — US imports only.

Direction. IMPORT (the customer is BUYING the goods and bringing them in) · EXPORT (the customer is SELLING the goods and sending them out). Required for FCL, LCL and AIR; not accepted for LTL or FTL.

Incoterms decide which port charges are included by default; omitted means FOB for an import, EXW for an export. EXW (Ex Works — the buyer takes over at the seller’s premises) · FCA (Free Carrier — the seller hands the goods to the buyer’s carrier) · FAS (Free Alongside Ship — the seller delivers beside the vessel) · FOB (Free On Board — the seller delivers on board at the origin port) · CFR (Cost and Freight — the seller pays carriage to the destination port) · CIF (Cost, Insurance and Freight — CFR plus the seller’s insurance) · CPT (Carriage Paid To — the seller pays carriage to the named place) · CIP (Carriage and Insurance Paid To — CPT plus the seller’s insurance) · DAP (Delivered At Place — the seller delivers, the buyer clears customs) · DPU (Delivered At Place Unloaded — the seller delivers and unloads) · DDP (Delivered Duty Paid — the seller delivers cleared, duties paid).

Service scope (on an offer, never sent): PORT_TO_PORT (port to port — nothing inland at either end) · DOOR_TO_PORT (collected at the origin address, delivered to the destination port) · PORT_TO_DOOR (collected at the origin port, delivered to the destination address) · DOOR_TO_DOOR (collected and delivered at addresses). It follows from choosing a PORT or a DOOR at each end — there is nothing to ask for.

Charges. Every charge has a category (ORIGIN · FREIGHT · DESTINATION · CUSTOMS · INSURANCE) and a basis (per container, per kg, per shipment, …). An offer's total is the sum of its charges. All amounts are sell prices for the customer.

Quote statuses. PENDING (with Freight Right’s pricing team) · QUOTED (there is an offer that can be booked) · DECLINED (Freight Right cannot quote it) · EXPIRED (the offer is no longer valid) · BOOKING_REQUESTED (a booking was asked for and Freight Right is reviewing it) · BOOKED (Freight Right confirmed the booking).

Where a quote came from. PORTAL (created in Shipment Manager by the customer or by Freight Right) · RATE_REQUEST (created from a quote request) · INSTANT_BOOKING (created by booking an instant offer).

Identifiers. rc_… a price check · pj_… a running price check, the pricing_id collected with freightright_get_rate_offers · of_… an offer · rev_… the fingerprint of an offer exactly as shown · rfq_… a quote request · a quote number is an integer in Shipment Manager and is NOT a quote request id · a forwarder reference identifies a shipment.

Finding shipments¶

freightright://guides/querying

Finding shipments¶

Start from what the customer says, not from a list:

A reference of any kind — forwarder reference, house or master bill, container number, purchase order — freightright_find_shipments searches all of them at once and says which one matched.
"What is arriving this week", "what is still on the water": freightright_list_shipments with an arrival window, newest first.
One shipment in full: freightright_get_shipment with its forwarder reference.

Filters are applied by Freight Right, never by you: every answer says which filters it applied (applied_filters). If a filter is missing there, the results were withheld rather than shown unfiltered — say so, do not filter by hand.

Pages: when has_more is true, call again with cursor set to next_cursor and the SAME filters. Never invent a cursor.

The filters, and what they mean. traffic international (sea or air, crossing a border) or domestic (road inside one country) · transport_mode SEA, AIR, ROA, RAI, TRK — how it moves, not a pricing mode · shipment_status FREE TEXT matched exactly, often empty, so never invent one · archived false by default · updated_since an RFC 3339 timestamp, for syncing · arriving_from/arriving_to the estimated arrival at the FINAL port · delivering_from/delivering_to the estimated FINAL delivery to the address — a different event, often days later · departing_* the estimated departure · arrival_recorded/delivery_recorded whether an ACTUAL timestamp exists, so arriving_to=yesterday with arrival_recorded=false is what "possibly overdue" means.

A shipment nobody can see is not an error: a customer's account sees the shipments of its own organizations. A Freight Right administrator's connection sees every organization's; organization narrows a list to one of them.

Pricing, quoting and booking¶

freightright://guides/pricing-and-booking

Pricing, quoting and booking¶

Instant prices (freightright_get_instant_rates) ask carriers live. A NEW price check spends one unit of the customer's monthly allowance, so price once per lane and cargo, when the customer wants prices — never to explore. A slow answer comes back as status: PRICING with a pricing_id: collect it with freightright_get_rate_offers, do not price again.

Repeating a price check does not always cost a unit. An identical request for the same billing account — the same normalized request, not merely the same lane and cargo — joins the running check, or is served the retained one, and spends nothing; served_from says EXISTING_CHECK and the original priced_at is kept. A result is retained until bookable_until (at least a minute, at most four hours; fifteen minutes when an answer is complete without one, two minutes when it is not) and can be dropped sooner, because only the five most recent results per customer are kept. NEW_CHECK means this call started a check and spent a unit; it is not a promise that the carriers were asked again, since the API may answer a repeated request from its own cache.

An offer is a price, not a booking. Nothing is reserved. complete: false means a source did not answer; no offers with complete: true means there is no instant price for that lane.

Quote requests (freightright_submit_rate_request) ask Freight Right's team to price something instantly prices cannot: full truckload, Mexico trucking, unusual cargo — or simply a second opinion. Show the customer freightright_preview_rate_request first: it sends nothing. Sending the identical request twice within 30 days returns the first one.

Bookings are the customer's decision, always. freightright_prepare_instant_booking and freightright_prepare_rate_request_booking prepare one and give you a link; only the customer, signed in to Freight Right, can submit it there. Give them the link and say what it will book. Then freightright_get_booking_operation says what they decided. BOOKING_REQUESTED means our team is reviewing it; BOOKED means Freight Right confirmed it.

Billing. A price, a quote request and a booking are made for a billing account: an organization id (freightright_list_billing_organizations) or, for an account with no billable organization, the company name the customer gives. If several organizations exist and none is the default, ask the customer which. A Freight Right administrator names the client organization on every request — search it by name with query, confirm the match with them, and never guess an id — or a company name for a customer who has none.

Whose booking. Booking a quote request takes the account that created it, or a current member of the organization it is billed to; the request says may_book. An administrator reads every organization's requests but books only the ones their own account created — do not offer to book what the user cannot.

Money. Amounts are sell prices for this customer, in the currency of the offer. Never compare or add totals in different currencies. Never present a price as final after its valid_until.

Insurance is insured_value_usd: the commercial value of the goods, in USD, on FCL, LCL and AIR. LTL and FTL have no insurance field at all — for those, submit a quote request and ask for insurance in the note, with the value.

What each mode needs, in one line. Resolve the place first with freightright_find_locations, then:

FCL — containers (type and quantity) and direction. No hazardous or temperature-controlled cargo: that is a quote request.
LCL and AIR — direction, and either pieces (groups of identical pieces with the dimensions and weight of ONE) or totals (pieces, gross weight, volume). Never both.
LTL — pieces with dimensions and weight, a DOOR at both ends, inside the US and Canada. No direction, no incoterm, no insurance. freight_class is optional and estimated from density when omitted.
FTL — a quote request only. Equipment goes in containers as container sizes; everything else about the truck goes in the note.

Ask the customer for what is missing rather than assuming a value: a guessed weight is a wrong price.