Provider List API

Retrieve available shipping providers based on shipment details

POST/api/shipments/provider-listSmall Parcel & LTL

Description

This endpoint analyzes your shipment requirements and returns a filtered list of shipping providers that can handle your specific shipment type, route, and package specifications.

The response includes provider details, capabilities, and a unique key for subsequent rate fetching operations.

Authentication

JSON

headers: {
  "Authorization": "Bearer {YOUR_API_KEY}",
  "Content-Type": "application/json"
}

Request Parameters

Core Parameters

Parameter	Type	Required	Description
shipment_from	object	Yes	Origin address details
shipment_to	object	Yes	Destination address and recipient details
from_details	object	Yes	Shipper contact information and pickup preferences
to_details	object	Yes	Consignee contact information
packages	array	Yes	Array of package specifications
pickup_date	string	Yes	Pickup date in YYYY-MM-DD format
options	array	No	Additional shipping service options
type	string	No	Shipment type ("ltl" for LTL shipments, omit for Small Parcel)

Shipment From Object

Parameter	Type	Required	Description
address_line1	string	Yes	Primary address line
address_line2	string	No	Secondary address line
city	string	Yes	City name
stateCode	string	Yes	State/province code (e.g., 'OH', 'FL')
postalCode	string	Yes	Postal/ZIP code
countryCode	string	Yes	ISO country code (e.g., 'US')

Shipment To Object

Parameter	Type	Required	Description
destination	string	Yes	Complete destination address string
company	string	No	Recipient company name
name	string	Yes	Recipient contact name
email	string	Yes	Recipient email address
phone	string	No	Recipient phone number
address_line1	string	Yes	Primary address line
address_line2	string	No	Secondary address line
city	string	Yes	City name
state	string	Yes	Full state/province name
country	string	Yes	Full country name
postalCode	string	Yes	Postal/ZIP code
countryCode	string	Yes	ISO country code
stateCode	string	Yes	State/province code
weight	number	Yes	Total shipment weight
weight_unit	string	Yes	Weight unit ("pound", "kg")
description	string	Yes	Shipment description

Shipper Details (from_details)

Parameter	Type	Required	Description
pickup_window.start_at	string	Yes	Pickup window start time (HH:MM:SS format)
pickup_window.end_at	string	Yes	Pickup window end time (HH:MM:SS format)
pickup_window.closing_at	string	Yes	Facility closing time (HH:MM:SS format)
company_name	string	Yes	Shipper company name
contact_name	string	Yes	Shipper contact person name
contact_no	string	Yes	Shipper contact phone number
contact_email	string	Yes	Shipper contact email address
is_residential	boolean	Yes	Whether the pickup location is residential

Consignee Details (to_details)

Parameter	Type	Required	Description
destination_window.start_at	string	Yes	Pickup window start time (HH:MM:SS format)
destination_window.end_at	string	Yes	Pickup window end time (HH:MM:SS format)
destination_window.closing_at	string	Yes	Facility closing time (HH:MM:SS format)
company_name	string	Yes	Consignee company name
contact_name	string	Yes	Consignee contact person name
contact_no	string	Yes	Consignee contact phone number
contact_email	string	Yes	Consignee contact email address
is_residential	boolean	Yes	Whether the delivery location is residential

Package Object

Parameter	Type	Required	Description
weight	number	Yes	Package weight
quantity	number	Yes	Number of packages
width	string/number	Yes	Package width
length	string/number	Yes	Package length
height	string/number	Yes	Package height
weight_unit	string	Yes	Weight unit ("pound", "kg")
dimension_unit	string	Yes	Dimension unit ("inch", "cm")
description	string	Yes	Package description
class	string	Yes	Freight class (e.g., "175", "250")
type	string	Yes	Package type ("Box", "Pallet", etc.)
stackable	boolean	Yes	Whether package can be stacked
hazardous_materials	boolean	Yes	Whether contains hazardous materials
hazardous_materials_un_na	string	No	UN/NA identification number for hazardous materials (e.g., 'UN1203', 'NA1993')
hazardous_materials_shipping_name	string	No	Official shipping name of the hazardous material (e.g., 'Gasoline', 'Combustible liquid, n.o.s.')
hazardous_materials_hazard_class	string	No	Hazard class classification (e.g., '3', '8', '9' for flammable liquids, corrosive, misc dangerous goods)
hazardous_materials_packaging_group	string	No	Packaging group level indicating danger level ('I', 'II', 'III' - I being most dangerous)
hazardous_materials_emergncy_name	string	No	Emergency contact person's name responsible for hazardous materials handling and incident response
hazardous_materials_emergncy_phone	string	No	24/7 emergency contact phone number for hazardous materials incidents, spills, or transportation emergencies

Options Array (LTL Services)

Parameter	Type	Required	Description
cnstp	string	No	Construction Site Pickup
ltdap	string	No	Limited Access Pickup
rep	string	No	Residential Pickup
lftp	string	No	Liftgate Pickup
ipu	string	No	Inside Pickup
lftd	string	No	Liftgate Delivery
psc	string	No	Protective Service Coverage
ovr	string	No	Over Dimensional
ltdad	string	No	Limited Access Delivery
cnstd	string	No	Construction Site Delivery
mnc	string	No	Marking/Counting
aptd	string	No	Appointment Delivery
res	string	No	Residential Delivery
haz	string	No	Hazardous Materials
ins	string	No	Additional Insurance
excessive_length	string	No	Excessive Length

API Configuration

REST API URL

API Token

Request Examples

JSON

{
  "shipment_from": {
    "address_line1": "285 Northeast Avenue",
    "city": "Tallmadge",
    "stateCode": "OH",
    "postalCode": "44278",
    "countryCode": "US"
  },
  "shipment_to": {
    "destination": "8800 Dorchester Road, North Charleston, South Carolina, United States - 29420",
    "company": "D4W-Solutions",
    "name": "consignee",
    "email": "[email protected]",
    "phone": "+1 330-931-5863",
    "address_line1": "8800 Dorchester Road",
    "city": "North Charleston",
    "state": "South Carolina",
    "country": "United States",
    "postalCode": "29420",
    "countryCode": "US",
    "stateCode": "SC",
    "weight": 160,
    "weight_unit": "pound",
    "description": "Product : New321"
  },
  "from_details": {
    "pickup_window": {
      "start_at": "02:00:00",
      "end_at": "04:30:00",
      "closing_at": "10:30:00"
    },
    "company_name": "shipper",
    "contact_name": "shipper",
    "contact_no": "+1 330-899-5862",
    "contact_email": "[email protected]",
    "is_residential": false
  },
  "to_details": {
    "destination_window": {
      "start_at": "02:00:00",
      "end_at": "04:30:00",
      "closing_at": "10:30:00"
    },
    "company_name": "D4W-Solutions",
    "contact_name": "Nick",
    "contact_no": "+1 330-931-5863",
    "contact_email": "[email protected]",
    "is_residential": false
  },
  "packages": [
    {
      "weight": 1,
      "quantity": 1,
      "width": "6",
      "length": "3",
      "height": "1",
      "weight_unit": "pound",
      "dimension_unit": "inch",
      "description": "Test",
      "class": "175",
      "type": "Box",
      "stackable": false,
      "hazardous_materials": true,
      "hazardous_materials_un_na": "UN1203",
      "hazardous_materials_shipping_name": "Gasoline",
      "hazardous_materials_hazard_class": "3",
      "hazardous_materials_packaging_group": "I",
      "hazardous_materials_emergncy_name": "Test",
      "hazardous_materials_emergncy_phone": "+1 330-899-5862"
    }
  ],
  "type": "small_parcel",
  "pickup_date": "",
  "options": []
}

Code Examples

JAVASCRIPT

100

101

102

103

104

105

106

107

108

109

import fetch from "node-fetch";

async function getProviders() {
  try {
    const response = await fetch("https://api.shipduo.com/api/shipments/provider-list", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": "Bearer ",
      },
      body: JSON.stringify({
        // Your request body here
        {
  "shipment_from": {
    "address_line1": "285 Northeast Avenue",
    "city": "Tallmadge",
    "stateCode": "OH",
    "postalCode": "44278",
    "countryCode": "US"
  },
  "shipment_to": {
    "destination": "8800 Dorchester Road, North Charleston, South Carolina, United States - 29420",
    "company": "D4W-Solutions",
    "name": "consignee",
    "email": "[email protected]",
    "phone": "+1 330-931-5863",
    "address_line1": "8800 Dorchester Road",
    "city": "North Charleston",
    "state": "South Carolina",
    "country": "United States",
    "postalCode": "29420",
    "countryCode": "US",
    "stateCode": "SC",
    "weight": 160,
    "weight_unit": "pound",
    "description": "Product : New321"
  },
  "from_details": {
    "pickup_window": {
      "start_at": "02:00:00",
      "end_at": "04:30:00",
      "closing_at": "10:30:00"
    },
    "company_name": "shipper",
    "contact_name": "shipper",
    "contact_no": "+1 330-899-5862",
    "contact_email": "[email protected]",
    "is_residential": false
  },
  "to_details": {
    "destination_window": {
      "start_at": "02:00:00",
      "end_at": "04:30:00",
      "closing_at": "10:30:00"
    },
    "company_name": "D4W-Solutions",
    "contact_name": "Nick",
    "contact_no": "+1 330-931-5863",
    "contact_email": "[email protected]",
    "is_residential": false
  },
  "packages": [
    {
      "weight": 1,
      "quantity": 1,
      "width": "6",
      "length": "3",
      "height": "1",
      "weight_unit": "pound",
      "dimension_unit": "inch",
      "description": "Test",
      "class": "175",
      "type": "Box",
      "stackable": false,
      "hazardous_materials": true,
      "hazardous_materials_un_na": "UN1203",
      "hazardous_materials_shipping_name": "Gasoline",
      "hazardous_materials_hazard_class": "3",
      "hazardous_materials_packaging_group": "I",
      "hazardous_materials_emergncy_name": "Test",
      "hazardous_materials_emergncy_phone": "+1 330-899-5862"
    }
  ],
  "type": "small_parcel",
  "pickup_date": "",
  "options": []
}
      }),
    });

    if (!response.ok) {
      const errorData = await response.json();
      console.error("API Error:", {
        status: response.status,
        error: errorData.error || "Unknown error",
        message: errorData.message || "No error message provided",
        details: errorData.details || errorData.data || "No details available"
      });
      return;
    }

    const data = await response.json();
    console.log("Success:", data);
  } catch (error) {
    console.error("Network Error:", error);
  }
}

getProviders();

Response Examples

Small Parcel Response

JSON

{
  "status": true,
  "message": "Operation succeeded.",
  "data": {
    "type": "small_parcel",
    "total_providers": 2,
    "providers": [
      {
        "id": 7,
        "name": "UPS",
        "short_name": "UPS",
        "logo": "https://api.shipduo.com/asset/shipping/ups.png",
        "type": "small_parcel",
        "status": 1,
      },
      {
        "id": 8,
        "name": "USPS",
        "short_name": "USPS",
        "logo": "https://api.shipduo.com/asset/shipping/usps.png",
        "type": "small_parcel",
        "status": 1,
      }
    ],
    "fetch_rates_random_key": "af53da99-d8f1-4321-9099-74400b68f058"
  }
}

Response Format

Success Response Structure

Parameter	Type	Description
status	boolean	Response status (true for success)
message	string	Response message
data	object	Provider list data

Response Data Object

Parameter	Type	Description
type	string/null	Shipment type ("ltl" for LTL, null for Small Parcel)
total_providers	number	Total number of available providers
providers	array	Array of provider objects
fetch_rates_random_key	string	Unique key for subsequent rate fetching

Provider Object

Parameter	Type	Description
id	number	Provider unique identifier
name	string	Full provider company name
short_name	string	Provider short name/abbreviation
logo	string	URL to provider logo image
type	string	Provider type ("small_parcel" or "ltl")
status	number	Provider status (1 = active)
custom_own_credential	number	Custom credentials flag
created_at	string/null	Creation timestamp
updated_at	string/null	Last update timestamp

Error Response

JSON

{
  "status": false,
  "message": "Error description here",
  "data": null
}

HTTP Status Codes

200OK - Successful provider list retrieval

400Bad Request - Invalid request parameters

401Unauthorized - Authentication failed

422Unprocessable Entity - Validation errors

500Internal Server Error - Server error

Common Providers

Small Parcel Providers

UPSUnited Parcel Service
USPSUnited States Postal Service
FedExFederal Express (when available)
DHLDHL Express (when available)

LTL Providers

SAIASAIA Motor Freight Lines Inc.
ABFABF Freight Systems Inc.
WARDWard Transport
OLD DominionOld Dominion Freight Lines Inc.
XPOXPO Logistics
ESTESEstes Express Lines

Important Notes

Shipment Type Detection: The system automatically determines available providers based on package weight, dimensions, and shipment characteristics.
Route Coverage: Providers are filtered based on their service coverage for the origin-destination route.
Fetch Rates Key: The fetch_rates_random_key in the response is required for subsequent rate fetching operations. Store this key for the next API call.
Provider Status: Only active providers (status = 1) are returned in the response.
Logo URLs: Provider logos are provided for UI display purposes and are hosted on the platform's CDN.
LTL Options: For LTL shipments, various service options can be specified to get providers that support specific requirements (liftgate, residential, hazmat, etc.).
Weight Thresholds:
- Small Parcel: Typically for packages under 150 lbs
- LTL: For freight over 150 lbs

Workflow

Prepare complete shipment details including origin, destination, and package specifications
Include any required service options for LTL shipments
Call the provider list endpoint
Review available providers and their capabilities
Store the fetch_rates_random_key for the next step
Use the provider information to fetch rates from selected carriers

Next Steps

After receiving the provider list, use the fetch_rates_random_key and selected provider IDs to call the rates API for specific pricing information.