---
title: "Request a rate quote"
method: POST
path: "/rates/quote"
tags: ["Quote Management"]
---

# Request a rate quote

`POST /rates/quote`

## Request

- Base URL: `https://rates.example.com/v1`
- URL: `https://rates.example.com/v1/rates/quote`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/goaugment/apis/augment-api/docs/rates/quote/post.ts> (a function with typed inputs; its response is checked against the schema)

This endpoint is implemented by the rate provider and called by Augment. Every other endpoint in this reference operates in the opposite direction, so the distinction warrants emphasis: Augment acts as the HTTP client, and cannot retrieve quotes until the endpoint is available on the provider side. The path and base URL shown above are placeholders for the values the provider assigns.

Each request describes a single shipment and expects the rates that apply to it. `mode`, `rateType`, two stops carrying a city and a state, and `equipment.equipmentType` are always present. The remaining fields are included when Augment holds a value and omitted when it does not, so an omitted optional field should be read as unknown rather than as a default. An omitted `isHazmat`, for example, does not indicate that the freight is non-hazardous.

`dimensions` is optional, but Augment includes it whenever a value is available, so that the rate provider rather than Augment determines whether a shipment is legal or oversize. Where oversize freight falls outside the scope of an initial build, `dimensions` may be disregarded and the field reserved for later use.

Where a shipment cannot be priced, the response must be `200` with an empty `rates` array and a populated `noRateReason`. This condition must not be reported with an error status: an error prevents Augment from distinguishing between "no rate exists" and "the endpoint is unavailable", and the two require opposite handling. 4xx and 5xx responses are reserved for malformed requests, authentication failures, and genuine faults.

One request is sent per rep. When a customer email reaches several of your reps, Augment sends one request for each, with its own `augmentQuoteId` and that rep as `QUOTE_OWNER`. Create one quote per request and do not merge them.

A request that repeats an `augmentQuoteId` already sent is an update to that quote, not a new quote. Augment resends it when the customer replies on the same thread with changes. Treat the call as idempotent: apply the latest values and return the same `externalId`.

## Request body

- RateQuoteRequest: One shipment to be priced. `mode`, `rateType`, `stops`, `equipment` and `augmentQuoteId` are always sent. The rest is sent when Augment has it, so treat a missing field as unknown rather than as a default.
  - `mode` 'DRAYAGE' | 'EXPEDITE' | 'FTL' | 'LTL' | 'PARTIAL', required: Transportation mode. Same values as `Load.mode`.
  - `rateType` 'CONTRACT' | 'DEDICATED' | 'PROJECT' | 'SPOT', required: The commercial basis of the rate being asked for. Same values as `Load.rateType`.
  - `stops` QuoteStop[], required: The route in sequence. One `PICKUP` and one `DELIVERY` is the floor and is enough to return a rate. This is an array rather than an origin and destination pair so a third or later stop is visible in the request. You cannot charge a stop-off fee against a lane that doesn't show the stop.
    - `sequence` integer, required: Position of the stop in the route. Starts at 1 and goes up by 1 for each stop after it.
    - `stopActivity` 'PICKUP' | 'DELIVERY', required
    - `address` object, required: A geographic point. The field names match `LoadRouteStop.address`, but only `city`, `stateOrProvince` and `country` are required. Quote requests routinely arrive with no ZIP, and street lines are never sent.
      - `city` string, required: City name
      - `stateOrProvince` string, required: State or province code
      - `postalCode` string, nullable: Postal or ZIP code, when the source document had one
      - `country` 'US' | 'CA' | 'MX', required: Two-letter ISO country code
  - `equipment` object, required: Equipment needed to move the shipment
    - `equipmentType` 'DRY_VAN' | 'REEFER' | 'FLATBED' | 'FLATBED_WITH_TARPS' | 'FLATBED_OVERDIMENSION' | 'FLATBED_STRETCH' | 'STEP_DECK' | 'STEP_DECK_OR_REM_GOOSENECK_RGN' | 'DOUBLE_DROP' | 'LOWBOY' | 'LOWBOY_OR_REM_GOOSENECK_RGN' | 'LOWBOY_OVERDIMENSION' | 'REMOVABLE_GOOSENECK' | 'CONESTOGA' | 'STRETCH_TRAILER' | 'WALKING_FLOOR' | 'OTHER', required: A subset of the platform equipment enum, weighted toward specialized and oversize trailers. Closed set for this endpoint. The full platform enum runs to over a hundred values and carries aliases for the same trailer, so provider trailer codes should be mapped onto these values, with `OTHER` sent where nothing fits, rather than a synonym Augment may not map back.
  - `weight` object, nullable: Total shipment weight. An object rather than a bare number, matching the load contract, so the unit is never guessed.
    - `value` number: Weight amount
    - `unit` 'LB' | 'KG': Unit of measure for the weight
  - `dimensions` object, nullable: Overall shipment dimensions in whole inches. Legal width runs to roughly 12 feet; wider than that generally needs escorts.
    - `lengthInches` integer: Overall length in whole inches
    - `widthInches` integer: Overall width in whole inches
    - `heightInches` integer: Overall height in whole inches
  - `commodity` string, nullable: Free-text description of the freight
  - `pickupDate` string, date, nullable: Requested pickup day
  - `totalMiles` number, nullable: Augment's mileage estimate, when it has one. Advisory only: rating should use the provider's own mileage, which is then returned on the response.
  - `tarpSize` string, nullable: Tarp size requirement, when the freight needs tarping
  - `isHazmat` boolean, nullable: Whether the shipment carries hazardous materials. Missing means unknown, not false.
  - `hazmatUnNumber` string, nullable: UN number for the hazardous material, `UN` followed by four digits. Sent only when `isHazmat` is true and the source document carried the number.
  - `accessorials` AccessorialsEnum[], nullable: Accessorial codes Augment already knows the shipment needs, such as `TARPS` or `TWIC`. Advisory only. You return the priced accessorials on each rate and are not limited to what's listed here.
  - `customerName` string, nullable: The shipper the quote is for, when a customer rate applies
  - `augmentQuoteId` string, required: Augment's id for this quote. Echo it back unchanged. Treat it as an opaque string.
  - `numberTruckloads` integer, nullable: Number of truckloads on this lane. Missing means 1. One request covers one lane; several truckloads on the same lane are counted here rather than sent as separate requests.
  - `wellspaceInches` integer, nullable: Well space needed, in whole inches, for drop-deck freight. A separate field rather than part of `dimensions`, because it describes the trailer requirement, not the freight.
  - `referenceNumbers` object[], nullable: Reference numbers the customer put on the request, such as a tender or spot-bid number. Use them to recognize a follow-up on the same request.
    - `name` 'TENDER_NUMBER' | 'PO_NUMBER' | 'BOL_NUMBER' | 'OTHER', required: Kind of reference number on a quote request
    - `value` string, required
  - `contacts` QuoteContact[]: People on the quote. Exactly one `QUOTE_OWNER` is always sent: the rep whose mailbox received the request. `QUOTE_REQUESTER` is the customer contact who asked, when known.
    - `role` 'QUOTE_OWNER' | 'QUOTE_REQUESTER', required: `QUOTE_OWNER` is the provider's rep who owns the quote. `QUOTE_REQUESTER` is the customer contact who asked for it.
    - `name` string, nullable: Contact name, when known
    - `email` string, email, nullable: Contact email address, when known
  - `email` QuoteEmail, nullable: The email that triggered this quote. When one thread carries several quote requests, this is the message that produced this quote, not the first message in the thread.
    - `direction` 'INBOUND': Direction of the email relative to the provider's rep
    - `messageId` string, nullable: Internet Message-ID of the triggering email (the RFC 5322 `Message-ID` header). It stays the same across folders and mailboxes. To open the email in Microsoft 365, look it up with Microsoft Graph: `GET /users/{rep}/messages?$filter=internetMessageId eq '{messageId}'`, which returns the message `id` and `webLink`.
    - `sentAt` string, date-time, nullable: When the triggering email was sent, in UTC
    - `subject` string, nullable: Subject line of the triggering email
    - `participants` object: Sender and recipients of the triggering email
      - `from` QuoteEmailAddress
        - `name` string, nullable: Display name, when present
        - `address` string, email, required: Email address
      - `to` QuoteEmailAddress[]
        - `name` string, nullable: Display name, when present
        - `address` string, email, required: Email address
      - `cc` QuoteEmailAddress[]
        - `name` string, nullable: Display name, when present
        - `address` string, email, required: Email address
    - `body` string, nullable: Plain-text body of the triggering email, as received. A reply or forward includes the quoted history it carried.
    - `summary` string, nullable: Short summary of the request, written by Augment. A convenience for the rep; `body` stays the source of truth.
    - `classification` string, nullable: How Augment classified the email, for example `QUOTE_REQUEST`.
    - `attachmentCount` integer, nullable: Number of attachments on the triggering email, when known
  - `customData` object, nullable: Additional fields Augment can reliably parse from the email, agreed with each provider during setup, such as a customer-specific code. Keys and values are defined per provider. Ignore any key you do not use.

## Response `200`

The applicable rates. Also the response for a shipment that cannot be priced: an empty `rates` array plus a `noRateReason`.

- RateQuoteResponse: The rates that apply to the shipment. `rates` is empty and `noRateReason` is set where the shipment cannot be priced.
  - `augmentQuoteId` string, required: The `augmentQuoteId` from the request, echoed back unchanged
  - `externalId` string, nullable: Your id for the quote this request created, such as the TMS quote number. Augment stores it against `augmentQuoteId`.
  - `quotedAt` string, date-time, required: When the rate was produced, in UTC
  - `currency` 'USD' | 'CAD', required: Currency for every money field in the response. Cross-border lanes are in scope, so CAD is supported.
  - `totalMiles` number, nullable: The mileage the rates were actually priced against. Augment prefers this over the estimate it sent, and extends `PER_MILE` accessorials with it.
  - `rates` Rate[], required: One entry per rating source. Empty where the shipment cannot be priced. A list keyed by `source` rather than a fixed field per rater means adding a source later is additive instead of a breaking change.
    - `source` string, required: The system or model that produced the rate. Not a closed set. New rating sources are added over time and Augment tolerates a value it has not seen, so the examples below are not exhaustive. Values should use UPPER_SNAKE_CASE, and a given source's value should remain stable between responses. The values are vendor-neutral on purpose: the same field carries a specialized in-house rate, a market rate, or a model added later, without either side reserving vendor-specific names.
    - `linehaul` number, required: Linehaul amount, before fuel and accessorials
    - `fuelSurcharge` number, required: Fuel surcharge in dollars, not a percent. Send 0 rather than leaving it out when a rate carries no fuel surcharge.
    - `fuelSurchargePct` number, nullable: The fuel surcharge as a whole percent, where the provider holds it in that form. Sent alongside `fuelSurcharge`, never instead of it.
    - `allInTotal` number, required: Total rate including linehaul, fuel and any accessorials already rolled in.
    - `costPerMile` number, nullable: Cost per mile for this rate, where the provider calculates it
    - `marginPct` number, nullable: Margin as a whole percent: 17, not 0.17. When a rate carries a margin, Augment seeds its margin selector with it and does not stack a second margin on top; a rep override is still tracked. Send null when the source has no margin of its own, as with a raw market rate.
    - `accessorials` RateAccessorial[]: The accessorials that apply to this shipment on this rate, with amounts. Send an empty array when none do. Augment asks for these per rate instead of keeping its own table, because a table cannot represent a route-dependent charge such as metro tolls, bridge and island fees, or county and city permits, and goes stale silently whenever a charge changes on the provider side.
      - `code` string, required: Accessorial code representing an additional service or requirement for a load. This is not a closed set — new accessorial codes may be added at any time. Values are normalized to UPPER_SNAKE_CASE (e.g., `inside delivery` → `INSIDE_DELIVERY`).
      - `label` string, nullable: The charge as the provider words it, shown to the rep
      - `amount` number, required: The amount, read according to `basis`. A `PER_MILE` amount is the rate per mile, not the extended total.
      - `basis` 'FLAT' | 'PER_MILE' | 'PER_STOP', required: How `amount` applies. `FLAT` is charged once for the shipment, `PER_MILE` is multiplied by the route mileage, and `PER_STOP` is charged for each stop beyond the first pickup and last delivery.
  - `noRateReason` 'LANE_NOT_SERVICED' | 'NO_CAPACITY' | 'EQUIPMENT_NOT_SUPPORTED' | 'HAZMAT_NOT_SUPPORTED' | 'OVERSIZE_OUT_OF_SCOPE' | 'COMMODITY_RESTRICTED' | 'CUSTOMER_NOT_FOUND' | 'MISSING_REQUIRED_INPUT' | 'RATE_UNAVAILABLE' | 'OTHER' | 'null', nullable: Why there is no rate. Required when `rates` is empty, and null whenever `rates` has at least one entry. An enum rather than free text so Augment can route the quote without parsing a message. `MISSING_REQUIRED_INPUT` is the only value Augment can act on automatically: the request was well formed but did not carry a value the provider requires, so Augment can obtain it from the customer and retry. Every other value is final for that shipment and routes the quote to a rep.
  - `noRateDetail` string, nullable: Optional free text expanding on `noRateReason`, shown to the rep working the quote. Augment does not parse it.

## Other responses

- `400`: Malformed request body
- `401`: Unauthorized
- `422`: Validation errors
- `500`: Rating failed. Reserved for genuine faults. A shipment that simply cannot be priced is a 200 with a `noRateReason`.

---

[API](https://skmtc.dev/goaugment/apis/augment-api.md) - [All operations](https://skmtc.dev/goaugment/apis/augment-api/llms.txt) - [OpenAPI document](https://skmtc.dev/goaugment/apis/augment-api/revisions/b61097634d79?raw)