API reference

Get rates

Overview

The Get Rates API provides instant freight rate predictions and quotes for both Full Truckload (FTL) and Less Than Truckload (LTL) shipments. This endpoint returns rates synchronously and automatically triggers document creation in your organization's workflow system.

Base URL: https://v2.cartage.ai (Production)

Endpoint: POST /p/getRates

Authentication: API Key (Header)

Authentication

All requests must include your organization's API key in the x-api-key header.

curl -X POST https://app.cartage.ai/p/getRates \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{...}'

Request

HTTP Method

POST /p/getRates

Headers

Header	Type	Required	Description
`Content-Type`	string	Yes	Must be `application/json`
`x-api-key`	string	Yes	Your organization API key

Request Body

Core Fields

Field	Type	Required	Description
`orgId`	string	Yes	Your organization ID
`serviceType`	enum	Yes	Type of service: `"ltl"` or `"ftl"`
`equipmentType`	enum	Yes	Equipment type: `"VAN"`, `"REEFER"`, `"FLATBED"`, `"SUPER_B"`
`pickupLocation`	object	Yes	Pickup location details (see Location Object)
`dropoffLocation`	object	Yes	Dropoff location details (see Location Object)
`vendors`	array	Conditional	Required for LTL. Array of vendor platforms: `["echo"]`
`commodities`	array	Conditional	Required for LTL. Array of commodity objects (see Commodity Object)
`shipDate`	string	No	Ship date in `YYYY-MM-DD` format. Defaults to tomorrow
`referenceNumber`	string	No	Existing shipment reference number. If provided, updates existing shipment instead of creating new one
`isStackable`	boolean	No	Whether freight is stackable (LTL only)

Location Object

Both pickupLocation and dropoffLocation use this structure:

Field	Type	Required	Description
`city`	string	Yes	City name
`state`	string	Yes	Two-letter state/province code (e.g., "IL", "CA")
`country`	enum	Yes	Country code: `"US"`, `"USA"`, `"CA"`, or `"CAN"`
`name`	string	No	Location name or business name
`address1`	string	No	Street address
`address2`	string	No	Address line 2 (suite, unit, etc.)
`zip`	string	No	Postal/ZIP code (recommended for accuracy)
`accessorials`	array	No	Array of accessorial services (see Accessorials)
`contactName`	string	No	Contact person name
`email`	string	No	Contact email address
`phone`	string	No	Contact phone number
`businessHoursStart`	string	No	Business hours start in `HH:MM` format (e.g., "08:00")
`businessHoursEnd`	string	No	Business hours end in `HH:MM` format (e.g., "17:00")
`specialInstructions`	string	No	Special pickup/delivery instructions

Accessorials

Pickup Accessorials:

"liftGate" - Lift gate required at pickup
"inside" - Inside pickup required
"appointmentRequired" - Appointment required for pickup
"residential" - Residential pickup location

Dropoff Accessorials:

"liftGate" - Lift gate required at delivery
"inside" - Inside delivery required
"appointmentRequired" - Appointment required for delivery
"residential" - Residential delivery location
"limitedAccess" - Limited access location
"callBeforeDelivery" - Call before delivery required

Commodity Object

Required for LTL shipments. Each commodity represents a freight item:

Field	Type	Required	Description
`description`	string	Yes	Description of the commodity
`quantity`	number	Yes	Number of pieces/units
`weight`	number	Yes	Weight in pounds (lbs)
`length`	number	Yes	Length in inches
`width`	number	Yes	Width in inches
`height`	number	Yes	Height in inches
`freightType`	enum	Yes	Type: `"pallet"`, `"box"`, or `"carton"`

Response

Success Response (200 OK)

The API returns different response structures depending on the service type.

FTL Response

{
    "distance": 750,
    "targetBuyRate": 2850.5,
    "confidenceLevel": 0.85,
    "highBuyRate": 3200.0,
    "startBuyRate": 2850.5,
    "lowBuyRate": 2500.0,
    "referenceNumber": "SHIP-2024-001"
}

Field	Type	Description
`distance`	number	Distance in miles
`targetBuyRate`	number	Predicted target buy rate in USD
`confidenceLevel`	number	Confidence level (0-1 scale)
`highBuyRate`	number	High end of rate range
`startBuyRate`	number	Starting rate recommendation
`lowBuyRate`	number	Low end of rate range
`referenceNumber`	string	Shipment reference number (provided or auto-generated)

LTL Response

{
    "ltlRates": [
        {
            "vendor": "rocketShipping",
            "carrierName": "XPO Logistics",
            "price": 485.5,
            "serviceName": "Standard",
            "transitDays": 3,
            "rocketLoadId": 12345,
            "rocketClientLoadId": 67890,
            "rocketRateId": 111213,
            "rocketRateCarrierId": 98765
        },
        {
            "vendor": "echo",
            "carrierName": "Old Dominion",
            "price": 520.0,
            "serviceName": "Guaranteed",
            "transitDays": 2
        },
        {
            "vendor": "freightcom",
            "response": "This shipment requires a spot quote. I've submitted a spot quote request in Freightcom and will let you know when we receive the response."
        }
    ],
    "referenceNumber": "SHIP-2024-002"
}

LTL Rate Object:

Field	Type	Description
`vendor`	enum	Vendor platform: `"tql"`, `"rocketShipping"`, `"freightcom"`, `"echo"`
`carrierName`	string	Carrier company name (if available)
`price`	number	Total rate in USD (if available)
`serviceName`	string	Service type or name (if available)
`transitDays`	number	Estimated transit time in days (if available)
`response`	string	Human-readable message (used for errors or spot quotes)
`rocketLoadId`	number	Rocket Shipping load ID (Rocket only)
`rocketClientLoadId`	number	Rocket Shipping client load ID (Rocket only)
`rocketRateId`	number	Rocket Shipping rate ID (Rocket only)
`rocketRateCarrierId`	number	Rocket Shipping carrier ID (Rocket only)

Error Responses

400 Bad Request

{
    "error": "Validation error",
    "message": "Invalid request parameters",
    "details": [
        {
            "field": "pickupLocation.city",
            "message": "Required field missing"
        }
    ]
}

401 Unauthorized

{
    "error": "Unauthorized",
    "message": "Invalid or missing API key"
}

500 Internal Server Error

{
    "error": "Internal server error",
    "message": "An unexpected error occurred while processing your request"
}

Request Examples

FTL Shipment Example

curl -X POST https://app.cartage.ai/p/getRates \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "orgId": "org_abc123",
    "serviceType": "ftl",
    "equipmentType": "VAN",
    "shipDate": "2024-02-01",
    "pickupLocation": {
      "city": "Chicago",
      "state": "IL",
      "country": "US",
      "zip": "60601"
    },
    "dropoffLocation": {
      "city": "Atlanta",
      "state": "GA",
      "country": "US",
      "zip": "30301"
    }
  }'

LTL Shipment Example with Lift Gate

 curl -X POST https://v2.cartage.ai/p/getRates \
    -H 'Content-Type: application/json' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -d '{
      "orgId": "yourOrgId",
      "serviceType": "ltl",
      "equipmentType": "VAN",
      "vendors": ["echo"],
      "pickupLocation": {
        "zip": "10001",
        "city": "New York",
        "state": "NY",
        "country": "US",
        "accessorials": ["liftGate"]
      },
      "dropoffLocation": {
        "zip": "90001",
        "city": "Los Angeles",
        "state": "CA",
        "country": "US",
        "accessorials": ["liftGate"]
      },
      "commodities": [{
        "description": "General Freight",
        "quantity": 2,
        "weight": 1000,
        "length": 48,
        "width": 40,
        "height": 48,
        "freightType": "pallet"
      }]
    }'

Update Existing Shipment Example

curl -X POST https://v2.cartage.ai/p/getRates \
    -H 'Content-Type: application/json' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -d '{
      "orgId": "yourOrgId",
      "serviceType": "ltl",
      "equipmentType": "VAN",
      "vendors": ["echo"],
      "pickupLocation": {
        "zip": "10001",
        "city": "New York",
        "state": "NY",
        "country": "US",
        "accessorials": ["liftGate"]
      },
      "dropoffLocation": {
        "zip": "94115",
        "city": "San Francisco",
        "state": "CA",
        "country": "US",
        "accessorials": ["liftGate"]
      },
      "commodities": [{
        "description": "General Freight",
        "quantity": 2,
        "weight": 1000,
        "length": 48,
        "width": 40,
        "height": 48,
        "freightType": "pallet"
      }],
      "referenceNumber": "SHP-034"
    }'