Quick Start

Get up and running with the Flash Americas API in just 5 minutes. This guide will walk you through testing the API immediately and then making authenticated calls for shipping quotes.

Prerequisites

Before you begin, you'll need:

A tool to make HTTP requests (we'll use cURL in examples)
An API key for quote generation (contact support@flashamericas.com)

Note: Many endpoints work without authentication, perfect for immediate testing!

Step 1: Test API Connectivity (No Auth Required)

Let's start by testing endpoints that don't require authentication:

Check API Status

curl -X GET "https://ship.flashamericas.com/api/v1/help"

This returns HTML documentation confirming the API is accessible.

Location Search

Search for ZIP codes and cities without authentication:

# Search for Dallas, TX ZIP codes
curl -X GET "https://ship.flashamericas.com/api/v1/location/search/US/DALLAS" \
-H "Accept: application/json"

# ZIP code autocomplete (e.g., all starting with 752)
curl -X GET "https://ship.flashamericas.com/api/v1/location/search/US/752" \
-H "Accept: application/json"

# Search across all countries
curl -X GET "https://ship.flashamericas.com/api/v1/location/search/MIAMI" \
-H "Accept: application/json"

Example Response:

{
"success": true,
"data": [
  {
    "zip": "75201",
    "city": "DALLAS",
    "state": "TX",
    "full_state": "Texas",
    "country": "US",
    "county": "Dallas",
    "lat": 32.7767,
    "lng": -96.7970
  }
],
"total": 38,
"search_type": "city"
}

SAT Code Lookup

Find Mexican tax classification codes for cross-border shipping:

# Search in English
curl -X GET "https://ship.flashamericas.com/api/v1/sat-code/lookup/en/electronics" \
-H "Accept: application/json"

# Search in Spanish
curl -X GET "https://ship.flashamericas.com/api/v1/sat-code/lookup/es/plastico" \
-H "Accept: application/json"

Example Response:

{
"data": [
  {
    "code": "25201706",
    "description_en": "Aircraft interface electronics",
    "description_es": "Electrónica de interfaz del avión"
  }
]
}

Step 2: Get Your First Quote (Auth Required)

Once you have an API key, you can get shipping rates:

curl -X POST "https://ship.flashamericas.com/api/v1/quote" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
  "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
}'

⚠️ Note: The above request structure follows the API reference documentation. However, the actual API may require additional fields like auth object with account details and shipmentDetails with complete shipper/consignee information. Contact support@flashamericas.com for the complete working request structure.

Quote Response

The API returns available shipping rates:

{
"success": true,
"loadId": "3a614a6a-6221-427f-9d83-21536290eb10",
"bolNumber": "3a614a6a-6221-427f-9d83-21536290eb10",
"data": {
  "quotes": [...],
  "loadId": "3a614a6a-6221-427f-9d83-21536290eb10",
  "bolNumber": "3a614a6a-6221-427f-9d83-21536290eb10"
},
"quotes": [
  {
    "quoteId": "d3e14567-0527-4871-bbc9-77cd77a711fd",
    "carrierName": "ABF",
    "scac": "ABFS",
    "customerPrice": {
      "miscCharges": [],
      "netPrice": 391.76,
      "grossCharge": 391.76
    },
    "rawPrice": [
      {
        "id": "49553882-d907-4d12-ab13-1fa881b02517",
        "chargeType": "ltl_base_freight_charge",
        "description": "Base Freight Charge",
        "chargeAmount": 391.76
      }
    ],
    "fromTransitTime": 1,
    "toTransitTime": 1,
    "service": "LTL",
    "serviceType": "LTL",
    "currency": "usd",
    "provider": "FPG",
    "preferred": false,
    "purchasable": false
  },
  {
    "quoteId": "8f2c1a94-3b6e-4d5c-9e7f-12345abcdef0",
    "carrierName": "SOUTHEASTERN",
    "scac": "SEFL",
    "customerPrice": {
      "miscCharges": [],
      "netPrice": 294.06,
      "grossCharge": 294.06
    },
    "fromTransitTime": 2,
    "toTransitTime": 3,
    "service": "LTL",
    "serviceType": "LTL",
    "currency": "usd",
    "provider": "FPG"
  }
]
}

Step 3: Cross-Border Quote (Auth Required)

For international shipments between the US and Mexico, use the V2 crossborder API:

curl -X POST "https://ship.flashamericas.com/api/v1/quote-crossborder" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
  "borderCrossingLocation": "LLB",
  "shipperLocation": {
    "accessorials": [],
    "address1": "Av. Javier Rojo Gómez No. 278",
    "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": []
  },
  "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": []
  },
  "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",
      "density": 11.25,
      "uid": "tfbejh1ii"
    }]
  }],
  "insuranceInfo": {
    "insuredValue": 0
  },
  "customs": {
    "borderCrossingLocation": "LLB",
    "origin": {
      "firstName": "Carlos",
      "lastName": "Rodriguez",
      "email": "customs.mx@flashamericas.com",
      "phone": "5551234567"
    },
    "destination": {
      "firstName": "Sarah",
      "lastName": "Johnson",
      "email": "customs.us@flashamericas.com",
      "phone": "5551234567"
    }
  },
  "parcelOptions": {
    "appointment": "no"
  },
  "usePublicApi": true
}'

Cross-Border Response

Cross-border quotes include multi-leg routing and customs handling:

{
"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"
        }
      ]
    }
  ],
  "loadId": "LOAD123456",
  "bolNumber": "BOL789012"
}
}

Border Crossing Locations

Choose the optimal crossing based on your route:

Code	US City	Mexican City	Best For
`LLB`	Laredo, TX	Nuevo Laredo, TAM	Central/eastern Mexico
`PDN`	El Paso, TX	Ciudad Juarez, CHH	Western Mexico

💡 Cross-Border Tip: Always include a valid SAT code for Mexican customs compliance. Use the SAT code lookup endpoint (Step 1) to find the correct classification for your products.

Step 4: Address Validation (Auth Required)

Validate and correct shipping addresses:

curl -X POST "https://ship.flashamericas.com/api/v1/address/validate" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
  "street1": "123 Main Street",
  "city": "Dallas",
  "state": "TX",
  "zip": "75201",
  "country": "US"
}'

⚠️ Note: Address validation service may be temporarily unavailable and return "Address validation service unavailable" errors.

What's Next?

Congratulations! You've successfully: ✅ Tested API connectivity without authentication
✅ Used location search and SAT code lookup
✅ Learned how to get domestic shipping quotes (with API key)
✅ Created cross-border quotes for US ↔ Mexico shipments
✅ Explored address validation services

API Summary

Endpoint	Authentication	Status	Use Case
`/help`	None	✅ Working	API documentation
`/location/search/*`	None	✅ Working	ZIP/city search
`/sat-code/lookup/*`	None	✅ Working	Mexican tax codes
`/quote`	Required	✅ Working	Domestic shipping rates
`/quote-crossborder`	Required	✅ Working	Cross-border US ↔ Mexico shipping
`/address/validate`	Required	⚠️ Unavailable	Address validation

Explore More Features

Now that you have the basics working, explore these advanced features:

Quotes API - Detailed quote generation and cross-border API
Cross-Border Shipping - Complete guide for US ↔ Mexico shipments
Locations API - Address validation and ZIP lookup
SAT Codes API - Mexican tax codes for customs compliance
Integration Examples - Complete code examples including cross-border

API Capabilities

The Flash Americas ezship API provides:

Real-time shipping quotes from 25+ carriers
Cross-border shipping between US and Mexico
Address validation and location search
SAT code lookup for customs compliance
Rate comparison across multiple service levels

Business Integration

For shipment booking, document generation, and tracking:

Contact our sales team for complete logistics platform access
Integrate quotes into your existing booking workflows
Use our carrier partnerships for actual shipping

Integration Examples

See real-world integration examples:

Node.js TypeScript Client - Full API client with retries and caching
React Component - Shipping calculator widget
Express Webhook Handler - Handle shipment notifications

Common Issues

Invalid API Key

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Invalid API key"
  }
}

Solution: Double-check your API key and ensure it's included in the Authorization header.

Invalid Address

{
  "success": false,
  "error": {
    "code": "INVALID_ADDRESS",
    "message": "The destination address could not be validated",
    "details": {
      "field": "destinationAddress.postalCode"
    }
  }
}

Solution: Verify the postal code format and ensure all required address fields are included.

Rate Limit Exceeded

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_ERROR",
    "message": "Rate limit exceeded"
  }
}

Solution: Implement exponential backoff in your requests. Check the Retry-After header for guidance.

Need Help?

Documentation: Continue reading our comprehensive guides
Examples: Check out our code examples repository
Support: Contact our developer support team

Rate Limits

Remember these limits for the API:

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

Check the response headers for your current usage:

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