# Create a quote

Create a new quote with order details.

## How it works

Creating a quote also creates an associated Order containing the route and freight details.
The Order is embedded in the Quote and cannot be managed separately.

## Required fields

- customer: Reference to the customer (shipper profile)
- order: Order details including stops and mode

## Example workflow

1. Create quote with customer and order details
2. Add pricing (amount) via PATCH
3. Send to customer (status changes to QUOTED)
4. Convert to shipment when accepted (POST /quotes/{id}/convert-to-shipment)

Endpoint: POST /quotes
Version: 1.0.0
Security: BearerAuth

## Request fields (application/json):

  - `customer` (any, required)

  - `carrier` (any)

  - `order` (object, required)
    Order details (route, freight)

  - `order.mode` (string, required)
    Transportation mode.
- TL: Full Truckload
- LTL: Less than Truckload
- AIR: Air freight
- OCEAN: Ocean freight
- RAIL: Rail freight
- INTERMODAL: Intermodal (multiple modes)
- DRAYAGE: Drayage/cartage
    Enum: "TL", "LTL", "AIR", "OCEAN", "RAIL", "INTERMODAL", "DRAYAGE"

  - `order.stops` (array, required)
    At least origin and destination stops

  - `order.stops.type` (string, required)
    Type of stop
    Enum: "PICKUP", "DELIVERY", "CROSS_DOCK"

  - `order.stops.location` (any)

  - `order.stops.address` (object)
    Address for ad-hoc stop (if no location reference)

  - `order.stops.address.line1` (string, required)
    Primary street address line
    Example: "123 Main St"

  - `order.stops.address.line2` (string)
    Secondary address line (suite, floor, etc.)
    Example: "Suite 400"

  - `order.stops.address.city` (string, required)
    City name
    Example: "Chicago"

  - `order.stops.address.country` (string, required)
    Country name or code
    Example: "USA"

  - `order.stops.address.market` (string, required)
    Market or region identifier
    Example: "CHI"

  - `order.stops.address.latitude` (string)
    Latitude coordinate
    Example: "41.8781"

  - `order.stops.address.longitude` (string)
    Longitude coordinate
    Example: "-87.6298"

  - `order.stops.address.isAirportOrAirbase` (boolean)
    Whether this location is an airport or airbase

  - `order.stops.address.isConstructionOrUtilitySite` (boolean)
    Whether this location is a construction or utility site

  - `order.stops.address.isSmartyValidated` (boolean)
    Whether address has been validated by SmartyStreets
    Example: true

  - `order.stops.address.obeysDst` (boolean)
    Whether this location observes daylight saving time
    Example: true

  - `order.stops.address.cityId` (string)
    Reference to standardized city record (internal use)

  - `order.stops.requestedStartDate` (string)
    Requested start date for the stop

  - `order.stops.requestedEndDate` (string)
    Requested end date for the stop

  - `order.stops.requestedStartTime` (string)
    Requested start time (HH:MM format)

  - `order.stops.requestedEndTime` (string)
    Requested end time (HH:MM format)

  - `order.stops.appointmentRequired` (boolean)
    Whether an appointment is required

  - `order.stops.notes` (string)
    Special instructions for the stop

  - `order.freight` (object)
    Freight details for an order

  - `order.freight.handlingUnitQuantity` (integer)
    Number of handling units

  - `order.freight.handlingUnitType` (string)
    Type of handling unit
    Enum: "PALLET", "SKID", "CARTON", "CRATE", "DRUM", "BUNDLE", "ROLL", "BAG", "TOTE", "OTHER"

  - `order.freight.weight` (number)
    Total weight in pounds

  - `order.freight.volume` (number)
    Total volume in cubic feet

  - `order.freight.length` (number)
    Length in inches

  - `order.freight.width` (number)
    Width in inches

  - `order.freight.height` (number)
    Height in inches

  - `order.freight.commodityDescription` (string)
    Description of the commodity

  - `order.freight.hazmat` (boolean)
    Whether freight is hazardous materials

  - `order.freight.stackable` (boolean)
    Whether freight is stackable

  - `order.equipment` (array)
    Equipment types required

  - `order.references` (array)
    Reference numbers for the order

  - `order.references.type` (string, required)
    Reference type (e.g., BOL_NUMBER, PO_NUMBER)

  - `order.references.value` (string, required)
    Reference value

  - `order.specialRequirements` (array)
    Special requirements (e.g., liftgate, team drivers)

  - `amount` (number)
    Quoted price

  - `expiresAt` (string)
    Quote expiration

  - `assignee` (any)

## Response 201 fields (application/json):

  - `id` (string, required)
    Unique identifier
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `key` (string, required)
    Human-readable quote ID (e.g., "Q003602")
    Example: "Q003602"

  - `side` (string, required)
    Quote direction.
- SELL: Selling to shipper (customer quote)
- BUY: Buying from carrier (carrier quote)
    Enum: "SELL", "BUY"

  - `status` (string, required)
    Current status in the quote lifecycle.

Initial states:
- DRAFT: Quote being drafted
- REQUESTED: Customer requested a quote (needs pricing)

Active states:
- QUOTED: Price sent to customer
- RECEIVED_REPLY: Received reply from customer
- SENT_REPLY: Sent reply to customer
- RECEIVED_COUNTER: Received counter-offer
- SENT_COUNTER: Sent counter-offer

Final states:
- WON: Customer accepted the quote
- LOST: Quote not accepted
- PASS: Broker declined to quote
- CANCELED: Quote canceled
    Enum: "DRAFT", "REQUESTED", "QUOTED", "RECEIVED_REPLY", "SENT_REPLY", "RECEIVED_COUNTER", "SENT_COUNTER", "WON", "LOST", "PASS", "CANCELED"

  - `amount` (number,null)
    Quoted price
    Example: 2500

  - `target` (number,null)
    Target price for margin calculation
    Example: 2200

  - `margin` (number,null)
    Calculated margin percentage
    Example: 12

  - `expiresAt` (string,null)
    Quote expiration timestamp

  - `customer` (object)
    Customer (for SELL quotes)

  - `customer.id` (string, required)
    Customer UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `customer.key` (string,null)
    Client-defined reference ID if set
    Example: "ERP-CUSTOMER-ACME"

  - `customer.name` (string, required)
    Customer company name
    Example: "Acme Manufacturing Corp"

  - `customer.friendlyId` (string, required)
    Human-readable customer identifier
    Example: "A123456"

  - `customer.status` (string, required)
    Customer status
    Enum: "PROSPECT", "ACTIVE", "INACTIVE", "CHURNED"

  - `customer.phoneNumber` (string,null)
    Primary phone number
    Example: "+1-555-123-4567"

  - `customer.website` (string,null)
    Customer website URL
    Example: "https://acme-manufacturing.com"

  - `customer.createdAt` (string, required)
    When the customer was created
    Example: "2025-01-15T10:00:00Z"

  - `customer.updatedAt` (string, required)
    When the customer was last updated
    Example: "2025-01-15T14:30:00Z"

  - `customer.deletedAt` (string,null)
    When the customer was soft deleted (null if active)

  - `carrier` (object)
    Carrier (for BUY quotes)

  - `carrier.id` (string, required)
    Carrier UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `carrier.name` (string, required)
    Carrier company name
    Example: "Swift Transportation"

  - `carrier.email` (string,null)
    Primary email address
    Example: "dispatch@swifttrans.com"

  - `carrier.createdAt` (string, required)
    When the carrier was created
    Example: "2025-01-15T10:00:00Z"

  - `carrier.updatedAt` (string, required)
    When the carrier was last updated
    Example: "2025-01-15T14:30:00Z"

  - `carrier.deletedAt` (string,null)
    When the carrier was soft deleted (null if active)

  - `order` (object)
    Order details (route, freight)

  - `order.id` (string)

  - `order.key` (string,null)

  - `order.mode` (string)
    Transportation mode.
- TL: Full Truckload
- LTL: Less than Truckload
- AIR: Air freight
- OCEAN: Ocean freight
- RAIL: Rail freight
- INTERMODAL: Intermodal (multiple modes)
- DRAYAGE: Drayage/cartage
    Enum: "TL", "LTL", "AIR", "OCEAN", "RAIL", "INTERMODAL", "DRAYAGE"

  - `order.origin` (object)

  - `order.origin.city` (string)

  - `order.origin.stateProvince` (string)

  - `order.origin.postalCode` (string,null)

  - `order.destination` (object)

  - `order.pickUpDate` (string,null)

  - `order.deliveryDate` (string,null)

  - `order.equipment` (array)

  - `order.weight` (number,null)

  - `order.mileage` (number,null)

  - `lostReason` (any)
    Why the quote was lost

  - `lostReasonText` (string,null)
    Additional text for lost reason

  - `closedTime` (string,null)
    When the quote was closed (won/lost)

  - `assignee` (object)
    Assigned sales rep

  - `assignee.id` (string, required)
    User UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `assignee.email` (string, required)
    User's email address
    Example: "john.doe@example.com"

  - `assignee.name` (string,null)
    User's full name
    Example: "John Doe"

  - `assignee.phone` (string,null)
    User's phone number
    Example: "+1-555-123-4567"

  - `assignee.phoneExt` (string,null)
    Phone extension
    Example: "123"

  - `assignee.status` (string, required)
    User account status
    Enum: "PENDING", "ACTIVE", "INACTIVE"

  - `assignee.avatarId` (string,null)
    Profile avatar document ID
    Example: "7c9e6679-7425-40de-944b-e07fc1f90ae7"

  - `assignee.createdAt` (string, required)
    When the user was created
    Example: "2025-01-15T10:00:00Z"

  - `assignee.updatedAt` (string, required)
    When the user was last updated
    Example: "2025-01-15T14:30:00Z"

  - `assignee.deletedAt` (string,null)
    When the user was soft deleted (null if active)

  - `shipmentId` (string,null)
    Shipment ID if converted

  - `shipmentKey` (string,null)
    Shipment friendly ID if converted

  - `createdAt` (string, required)

  - `updatedAt` (string,null)

## Response 400 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 401 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 422 fields (application/json):

  - `error` (string, required)
    Error code
    Example: "validation_error"

  - `message` (string, required)
    Human-readable error message

  - `details` (array, required)
    Validation error details

  - `details.field` (string, required)
    Field name that failed validation

  - `details.message` (string, required)
    Validation error message