Quickstart

This guide will walk you through creating a complete ecosystem of connected entities. By following these steps, you'll have locations, customers, carriers, and loads that work together for analytics and carrier recommendations.

Prerequisites

• An API key (get one from Settings → API Keys in your Mentium dashboard)
• curl or your preferred HTTP client

Step 1: Create Locations

First, create the pickup and delivery locations. These will be referenced by loads.

# Create Chicago pickup location
curl -X POST "https://api.mentium.io/v2/tms-api/locations" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "external_reference_id": "LOC-CHICAGO-001",
    "name": "Chicago Distribution Center",
    "address_line1": "123 Industrial Blvd",
    "city": "Chicago",
    "state": "IL",
    "postal_code": "60601",
    "country": "US"
  }'

# Create Detroit delivery location
curl -X POST "https://api.mentium.io/v2/tms-api/locations" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "external_reference_id": "LOC-DETROIT-001",
    "name": "Detroit Receiving Facility",
    "address_line1": "456 Woodward Ave",
    "city": "Detroit",
    "state": "MI",
    "postal_code": "48201",
    "country": "US"
  }'

TIP

Locations are automatically geocoded for lane matching and carrier recommendations.

Step 2: Create a Customer

Create the customer who will be associated with loads.

curl -X POST "https://api.mentium.io/v2/tms-api/customers" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "external_reference_id": "CUST-ACME-001",
    "name": "Acme Corporation",
    "phone": "312-555-0100",
    "domain": "acme.com"
  }'

Step 3: Create a Carrier

Create carriers that can be assigned to loads or recommended by the system.

curl -X POST "https://api.mentium.io/v2/tms-api/carriers" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "external_reference_id": "CARRIER-MIDWEST-001",
    "name": "Midwest Express Trucking",
    "mc_number": "MC123456",
    "dot_number": "DOT789012",
    "phone_number": "800-555-0101",
    "email": "dispatch@midwestexpress.com",
    "contacts": [
      {
        "first_name": "John",
        "last_name": "Driver",
        "primary_email": "john@midwestexpress.com",
        "primary_phone": "800-555-0102",
        "is_primary_contact": true
      }
    ]
  }'

Step 4: Create a Load

Now create a load that references the locations, customer, and optionally the carrier.

curl -X POST "https://api.mentium.io/v2/tms-api/loads" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "external_reference_id": "LOAD-001",
    "status": "ACTIVE",
    "equipment_type": "DRY_VAN",
    "customer_external_reference_id": "CUST-ACME-001",
    "description": "Electronics shipment - handle with care",
    "weight": 42000,
    "weight_uom": "lbs",
    "total_distance": 285,
    "max_buy_rate": 2200,
    "stops": [
      {
        "stop_number": 1,
        "stop_type": "Pickup",
        "location_external_reference_id": "LOC-CHICAGO-001",
        "early_arrival": "2026-02-01T08:00:00Z",
        "late_arrival": "2026-02-01T16:00:00Z",
        "appointment_datetime": "2026-02-01T10:00:00Z"
      },
      {
        "stop_number": 2,
        "stop_type": "Delivery",
        "location_external_reference_id": "LOC-DETROIT-001",
        "early_arrival": "2026-02-02T08:00:00Z",
        "late_arrival": "2026-02-02T16:00:00Z",
        "appointment_datetime": "2026-02-02T14:00:00Z"
      }
    ],
    "financial_rates": [
      {
        "rate_entity": "CUSTOMER",
        "amount": 3500
      }
    ]
  }'

Success!

Your load is now visible in the Mentium dashboard with:

• Origin: Chicago, IL
• Destination: Detroit, MI
• Customer: Acme Corporation
• Status: Active (ready for offers)

Step 5: Create Historical Loads (For Recommendations)

To enable carrier recommendations, create historical loads with carriers assigned. This builds the lane history data.

curl -X POST "https://api.mentium.io/v2/tms-api/loads" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "external_reference_id": "HIST-LOAD-001",
    "status": "DELIVERED",
    "equipment_type": "DRY_VAN",
    "customer_external_reference_id": "CUST-ACME-001",
    "carrier_external_reference_id": "CARRIER-MIDWEST-001",
    "description": "Historical shipment - Auto Parts",
    "weight": 35000,
    "total_distance": 285,
    "stops": [
      {
        "stop_number": 1,
        "stop_type": "Pickup",
        "location_external_reference_id": "LOC-CHICAGO-001",
        "early_arrival": "2026-01-15T08:00:00Z",
        "late_arrival": "2026-01-15T16:00:00Z"
      },
      {
        "stop_number": 2,
        "stop_type": "Delivery",
        "location_external_reference_id": "LOC-DETROIT-001",
        "early_arrival": "2026-01-16T08:00:00Z",
        "late_arrival": "2026-01-16T16:00:00Z"
      }
    ],
    "financial_rates": [
      {"rate_entity": "CUSTOMER", "amount": 2800},
      {"rate_entity": "CARRIER", "amount": 2200}
    ]
  }'

INFO

Historical loads with status: "DELIVERED" and a carrier assigned build the lane history that powers carrier recommendations. The more historical data, the better the recommendations.

What's Next?

• View in Dashboard: Go to app.mentium.io → Loads to see your load
• Send Offers: Click on LOAD-001 to send offers to carriers
• Carrier Recommendations: With historical data, you'll see recommended carriers ranked by match score
• Batch Operations: Use batch endpoints to sync multiple loads at once

Recommended Order of Operations

For the best results when syncing data:

1. Locations → Create pickup/delivery locations first
2. Customers → Create customers
3. Carriers → Create carriers (with contacts for communication)
4. Historical Loads → Import DELIVERED loads with carriers to build recommendation data
5. Active Loads → Create ACTIVE loads ready for offers

TIP

You can use batch endpoints to sync all your data in a few API calls instead of one at a time.