Quotes API

The Quotes API allows you to get real-time shipping rates from multiple carriers with a single request. This is typically the first API call you'll make when integrating Flash Americas into your application.

Overview

The Quotes API provides:

Real-time rates from 7+ carriers
Multiple service levels (ground, air, expedited)
Transit time estimates and delivery dates
Cost breakdowns with fuel surcharges and accessorials
Quote caching to reduce repeated API calls

Endpoints

Method	Endpoint	Description
POST	`/quote`	Create a new rate quote
POST	`/quote-crossborder`	Create cross-border rate quote (V2 API)

Note: The ezship API focuses on real-time quote generation. Quote retrieval and booking are handled through external systems.

Create Quote

Get shipping rates for cargo between two addresses.

Request

POST /quotehttp

POST https://ship.flashamericas.com/api/v1/quote
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

Request Body

Quote requestjson

{
"originAddress": {
  "address1": "123 Main Street",
  "address2": "Suite 100",
  "city": "Dallas",
  "state": "TX",
  "postalCode": "75201",
  "country": "US",
  "companyName": "Acme Corp",
  "contactName": "John Smith",
  "phone": "214-555-0123",
  "email": "john@acme.com"
},
"destinationAddress": {
  "address1": "456 Oak Avenue",
  "city": "Houston", 
  "state": "TX",
  "postalCode": "77001",
  "country": "US",
  "companyName": "Customer Corp",
  "contactName": "Jane Doe",
  "phone": "713-555-0456",
  "email": "jane@customer.com"
},
"cargo": [
  {
    "weight": 25.5,
    "length": 18,
    "width": 12,
    "height": 10,
    "quantity": 1,
    "description": "Electronics",
    "value": 1500.00,
    "currency": "USD",
    "hazmat": false,
    "nmfcCode": "50",
    "freightClass": "65"
  }
],
"shipDate": "2025-02-20",
"accessorials": ["LIFTGATE_PICKUP", "LIFTGATE_DELIVERY"],
"insuranceAmount": 1500.00,
"returnJson": true
}

Address Object

Field	Type	Required	Description
`address1`	string	Yes	Street address
`address2`	string	No	Apartment, suite, etc.
`city`	string	Yes	City name
`state`	string	Yes	State/province code
`postalCode`	string	Yes	ZIP/postal code
`country`	string	Yes	ISO 3166-1 alpha-2 country code
`companyName`	string	No	Company name
`contactName`	string	No	Contact person name
`phone`	string	No	Phone number
`email`	string	No	Email address

Cargo Object

Field	Type	Required	Description
`weight`	number	Yes	Weight in pounds
`length`	number	Yes	Length in inches
`width`	number	Yes	Width in inches
`height`	number	Yes	Height in inches
`quantity`	integer	Yes	Number of pieces
`description`	string	Yes	Cargo description
`value`	number	No	Declared value
`currency`	string	No	Currency code (default: USD)
`hazmat`	boolean	No	Hazardous materials flag
`nmfcCode`	string	No	NMFC code for LTL
`freightClass`	string	No	Freight class for LTL

Response

Quote responsejson

{
"success": true,
"data": {
  "quoteId": "550e8400-e29b-41d4-a716-446655440000",
  "rates": [
    {
      "provider": "FEDEX",
      "service": "FEDEX_GROUND",
      "totalCost": 12.45,
      "currency": "USD",
      "transitDays": 1,
      "deliveryDate": "2025-02-21T17:00:00Z",
      "isGuaranteed": false,
      "breakdown": {
        "baseCost": 10.95,
        "fuelSurcharge": 1.50,
        "accessorials": {
          "LIFTGATE_PICKUP": 35.00,
          "LIFTGATE_DELIVERY": 35.00
        }
      },
      "metadata": {
        "carrierCode": "FDXG",
        "serviceCode": "92",
        "rateId": "rate_abc123"
      }
    },
    {
      "provider": "UPS",
      "service": "UPS_GROUND",
      "totalCost": 13.20,
      "currency": "USD",
      "transitDays": 1,
      "deliveryDate": "2025-02-21T17:00:00Z",
      "isGuaranteed": false,
      "breakdown": {
        "baseCost": 11.75,
        "fuelSurcharge": 1.45,
        "accessorials": {}
      },
      "metadata": {
        "carrierCode": "UPS",
        "serviceCode": "03",
        "rateId": "rate_def456"
      }
    }
  ],
  "expiresAt": "2025-01-15T11:30:00Z",
  "warnings": [
    "Address validation suggests '75201-4567' for postal code"
  ]
},
"meta": {
  "requestId": "req_550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-01-15T10:30:00Z",
  "version": "1.0.0"
}
}

Rate Object

Field	Type	Description
`provider`	string	Carrier name (FEDEX, UPS, USPS, etc.)
`service`	string	Service level (FEDEX_GROUND, UPS_NEXT_DAY, etc.)
`totalCost`	number	Total shipping cost
`currency`	string	Currency code
`transitDays`	integer	Estimated transit time in business days
`deliveryDate`	string	Estimated delivery date (ISO 8601)
`isGuaranteed`	boolean	Whether delivery is guaranteed
`breakdown`	object	Cost breakdown details
`metadata`	object	Additional carrier-specific information

Using Quote Results

The quote response provides all rates available for your shipment. Each rate includes:

Total cost with all fees and surcharges
Transit time in business days
Delivery date estimates
Carrier-specific service details
Breakdown of base cost, fuel, and accessorials

Use this information to:

Display options to your customers
Compare rates across carriers
Select optimal service levels
Integrate with your booking system

Note: Shipment booking is handled through separate business processes. Contact support for booking integration options.

Accessorials

Common accessorial services that can be added to quotes:

Code	Description	Typical Cost
`LIFTGATE_PICKUP`	Liftgate service at pickup	$35-50
`LIFTGATE_DELIVERY`	Liftgate service at delivery	$35-50
`INSIDE_PICKUP`	Inside pickup service	$25-40
`INSIDE_DELIVERY`	Inside delivery service	$25-40
`RESIDENTIAL_PICKUP`	Residential pickup	$15-25
`RESIDENTIAL_DELIVERY`	Residential delivery	$15-25
`APPOINTMENT_DELIVERY`	Appointment delivery	$20-35
`WHITE_GLOVE`	White glove service	$150-300

Examples

Basic Quote Request

Simple quote examplejavascript

const response = await fetch('https://ship.flashamericas.com/api/v1/quote', {
method: 'POST',
headers: {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json',
  'Accept': 'application/json'
},
body: JSON.stringify({
  originAddress: {
    address1: "123 Main St",
    city: "Dallas",
    state: "TX", 
    postalCode: "75201",
    country: "US"
  },
  destinationAddress: {
    address1: "456 Oak Ave",
    city: "Houston",
    state: "TX",
    postalCode: "77001", 
    country: "US"
  },
  cargo: [{
    weight: 25,
    length: 18,
    width: 12,
    height: 10,
    quantity: 1,
    description: "Electronics"
  }],
  shipDate: "2025-02-20",
  returnJson: true
})
});

const data = await response.json();
console.log(`Found ${data.data.rates.length} rates`);

With Accessorials

Quote with accessorialsjavascript

const quoteRequest = {
originAddress: {
  address1: "1000 Industrial Blvd",
  city: "Dallas",
  state: "TX",
  postalCode: "75201",
  country: "US"
},
destinationAddress: {
  address1: "500 Residential St",
  city: "Austin", 
  state: "TX",
  postalCode: "78701",
  country: "US"
},
cargo: [{
  weight: 250,
  length: 48,
  width: 40,
  height: 36,
  quantity: 1,
  description: "Machinery"
}],
shipDate: "2025-02-20",
accessorials: [
  "LIFTGATE_PICKUP",
  "LIFTGATE_DELIVERY", 
  "RESIDENTIAL_DELIVERY"
],
returnJson: true
};

Cross-Border Quote API

Create quotes for international shipments between the US and Mexico using the V2 crossborder API.

Request

POST /quote-crossborderhttp

POST https://ship.flashamericas.com/api/v1/quote-crossborder
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

Request Body (V2 Format)

Cross-border quote requestjavascript

const crossBorderRequest = {
borderCrossingLocation: "LLB",  // Laredo/Nuevo Laredo (use "PDN" for El Paso/Ciudad Juarez)

// Shipper location
shipperLocation: {
accessorials: [],
address1: "Av. Javier Rojo Gómez No. 278",
address4: "Guadalupe del Moral",
city: "Iztapalapa",
stateOrProvince: "CMX",
zipCode: "09300",
country: "MX",
contactFirstName: "Marc",
contactLastName: "Held",
phone: "+52 55 1234 5678",
email: "plasticos@moldplas.com.mx",
name: "Moldeados Plásticos, S.A. de C.V.",
type: "business",
limitedAccess: false,
scheduledDate: "2025-06-27T12:00",
openTime: "06/27/2025 08:00:00 -5",
closeTime: "06/27/2025 17:00:00 -5",
readyTime: "06/27/2025 08:00:00 -5",
references: []
},

// Consignee location
consigneeLocation: {
accessorials: [],
address1: "3300 NE 192nd St",
city: "MIAMI",
stateOrProvince: "FL",
zipCode: "33180",
country: "US",
contactFirstName: "Marc",
contactLastName: "Held",
phone: "305-555-0100",
email: "hq@flashamericas.com",
name: "HQ",
type: "business",
limitedAccess: false,
firstComeFirstServe: true,
openTime: "06/27/2025 08:00 -5",
closeTime: "06/27/2025 17:00 -5",
references: []
},

// Handling units with products
handlingUnits: [{
quantity: 1,
uuid: "ea4xxicv9",
transform: true,
products: [{
selectedPackage: {
id: 22,
key: "Pallets",
name: "Pallets"
},
packageType: "Pallets",
description: "Plastic",
quantity: 1,
weight: 501,
length: 48,
width: 40,
height: 40,
class: 92.5,
condition: "used",
isHazmat: false,
stackable: false,
additionalHandling: false,
satCode: "24121807", // Required for Mexico
density: 11.25,
uid: "tfbejh1ii"
}]
}],

// Insurance info
insuranceInfo: {
insuredValue: 0
},

// Customs information for cross-border
customs: {
borderCrossingLocation: "LLB", // Must match main borderCrossingLocation
origin: {
firstName: "Carlos",
lastName: "Rodriguez",
email: "customs.mx@flashamericas.com",
phone: "5551234567"
},
destination: {
firstName: "Sarah",
lastName: "Johnson",
email: "customs.us@flashamericas.com",
phone: "5551234567"
}
},

// Additional options
parcelOptions: {
appointment: "no"
},

usePublicApi: true
};

Border Crossing Locations

Flash Americas supports multiple border crossing facilities:

Code	US City	Mexican City	Description
`LLB`	Laredo, TX	Nuevo Laredo, TAM	Primary crossing for central/eastern routes
`PDN`	El Paso, TX	Ciudad Juarez, CHH	Primary crossing for western routes

Choose the optimal crossing based on your origin/destination:

LLB - Best for shipments to/from central and eastern Mexico
PDN - Best for shipments to/from western Mexico and Pacific coast

Cross-Border Response

Cross-border quote responsejson

{
"success": true,
"quotes": {
  "quotes": [
    {
      "quoteId": "cb_550e8400-e29b-41d4-a716-446655440000",
      "total": 450.75,
      "currency": "USD",
      "fromTransitTime": 3,
      "toTransitTime": 5,
      "serviceType": "standard",
      "moves": [
        {
          "carrierName": "Flash Cross-Border",
          "scac": "FLSH",
          "pickupDate": "2025-06-27",
          "deliveryDate": "2025-07-02"
        }
      ]
    },
    {
      "quoteId": "cb_550e8400-e29b-41d4-a716-446655440001",
      "total": 525.00,
      "currency": "USD",
      "fromTransitTime": 2,
      "toTransitTime": 3,
      "serviceType": "expedited",
      "moves": [
        {
          "carrierName": "Express Border Services",
          "scac": "EXPR",
          "pickupDate": "2025-06-27",
          "deliveryDate": "2025-06-30"
        }
      ]
    }
  ],
  "loadId": "LOAD123456",
  "bolNumber": "BOL789012"
}
}

Error Handling

Common Errors

Invalid address errorjson

{
"success": false,
"error": {
  "code": "INVALID_ADDRESS",
  "message": "The destination address could not be validated",
  "details": {
    "field": "destinationAddress.postalCode",
    "suggestions": ["77001-4567", "77002"]
  }
}
}

No rates availablejson

{
"success": false,
"error": {
  "code": "NO_RATES_AVAILABLE",
  "message": "No shipping rates available for this route",
  "details": {
    "reason": "Destination not serviced by available carriers"
  }
}
}

Best Practices

Cache quotes - Quotes are valid for 1 hour, cache them to avoid repeated API calls
Handle no rates - Always check if rates array is empty
Validate addresses - Use the address validation API before getting quotes
Set timeouts - API calls should timeout after 30 seconds
Retry logic - Implement exponential backoff for transient errors

Rate Limiting

The Quotes API is subject to rate limiting:

Production: 1000 requests per minute
Sandbox: 100 requests per minute

Rate limit headers are included in responses:

Rate limit headershttp

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200
X-RateLimit-Window: 60

Testing

Use our production environment for testing:

Base URL: https://ship.flashamericas.com/api/v1
API Key: Contact support for credentials
Test Data: Use real addresses for accurate quote results

Next Steps

Book shipments using quote results
Track packages after booking
Handle webhooks for real-time updates
See examples for complete integration code

Quotes API

Overview

Endpoints

Create Quote

Request

Request Body

Address Object

Cargo Object

Response

Rate Object

Using Quote Results

Accessorials

Examples

Basic Quote Request

With Accessorials

Cross-Border Quote API

Request

Request Body (V2 Format)

Border Crossing Locations

Cross-Border Response

Error Handling

Common Errors

Best Practices

Rate Limiting

Testing

Next Steps

On this page