Appearance

Batch Operations ​

Batch operations allow you to create or update multiple records in a single API request, reducing the number of API calls and improving performance.

Benefits ​

  • Fewer API calls: Create 100 locations in 1 request instead of 100 requests
  • Optimized analytics: Load batches trigger analytics once for the entire batch, not per item
  • Better performance: Reduced network overhead and faster processing
  • Rate limit friendly: One batch counts as one request for rate limiting

Supported Resources ​

ResourceEndpoint
LocationsPOST /v2/tms-api/batch/locations
CustomersPOST /v2/tms-api/batch/customers
CarriersPOST /v2/tms-api/batch/carriers
LoadsPOST /v2/tms-api/batch/loads

Operations ​

OperationDescription
createCreate a new record (fails if exists)
updateUpdate an existing record by external_reference_id
upsertCreate if doesn't exist, update if it does

Complete Example: Sync an Entire Ecosystem ​

This example shows how to batch create interconnected entities. Run these in order:

1. Batch Create Locations ​

bash
curl -X POST "https://api.mentium.io/v2/tms-api/batch/locations" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "operation": "create",
        "external_reference_id": "LOC-CHICAGO-001",
        "location": {
          "external_reference_id": "LOC-CHICAGO-001",
          "name": "Chicago Distribution Center",
          "address_line1": "123 Industrial Blvd",
          "city": "Chicago",
          "state": "IL",
          "postal_code": "60601",
          "country": "US"
        }
      },
      {
        "operation": "create",
        "external_reference_id": "LOC-DETROIT-001",
        "location": {
          "external_reference_id": "LOC-DETROIT-001",
          "name": "Detroit Receiving Facility",
          "address_line1": "456 Woodward Ave",
          "city": "Detroit",
          "state": "MI",
          "postal_code": "48201",
          "country": "US"
        }
      }
    ]
  }'

2. Batch Create Customers ​

bash
curl -X POST "https://api.mentium.io/v2/tms-api/batch/customers" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "operation": "create",
        "external_reference_id": "CUST-ACME-001",
        "customer": {
          "external_reference_id": "CUST-ACME-001",
          "name": "Acme Corporation",
          "phone": "312-555-0100"
        }
      }
    ]
  }'

3. Batch Create Carriers ​

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

4. Batch Create Loads (Historical + Active) ​

Important

Include historical DELIVERED loads with carriers to build lane history for recommendations. Active loads on the same lane will then show carrier recommendations.

bash
curl -X POST "https://api.mentium.io/v2/tms-api/batch/loads" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "operation": "create",
        "external_reference_id": "HIST-BATCH-001",
        "load": {
          "external_reference_id": "HIST-BATCH-001",
          "status": "DELIVERED",
          "equipment_type": "DRY_VAN",
          "customer_external_reference_id": "CUST-ACME-001",
          "carrier_external_reference_id": "CARRIER-MIDWEST-001",
          "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}
          ]
        }
      },
      {
        "operation": "create",
        "external_reference_id": "BATCH-LOAD-001",
        "load": {
          "external_reference_id": "BATCH-LOAD-001",
          "status": "ACTIVE",
          "equipment_type": "DRY_VAN",
          "customer_external_reference_id": "CUST-ACME-001",
          "total_distance": 285,
          "max_buy_rate": 2500,
          "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"
            },
            {
              "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"
            }
          ],
          "financial_rates": [
            {"rate_entity": "CUSTOMER", "amount": 3500}
          ]
        }
      }
    ]
  }'

Success!

After running these 4 batch commands, you'll have:

  • 2 locations (Chicago, Detroit)
  • 1 customer (Acme)
  • 1 carrier (Midwest Express)
  • 1 historical load (builds recommendation data)
  • 1 active load (with carrier recommendations available!)

Response Format ​

json
{
  "success_count": 2,
  "error_count": 0,
  "results": [
    {
      "external_reference_id": "HIST-BATCH-001",
      "operation": "create",
      "success": true,
      "id": "load_hist123",
      "error": null,
      "error_code": null
    },
    {
      "external_reference_id": "BATCH-LOAD-001",
      "operation": "create",
      "success": true,
      "id": "load_abc123",
      "error": null,
      "error_code": null
    }
  ]
}

Limits ​

LimitValue
Maximum items per batch100
Request timeout60 seconds

Partial Success ​

Unlike some APIs, batch operations allow partial success. If one item fails validation, other items can still succeed:

json
{
  "success_count": 1,
  "error_count": 1,
  "results": [
    {
      "external_reference_id": "HIST-BATCH-001",
      "operation": "create",
      "success": true,
      "id": "load_hist123"
    },
    {
      "external_reference_id": "LOAD-INVALID",
      "operation": "create",
      "success": false,
      "error": "Load must have at least one Pickup/Shipper stop",
      "error_code": "VALIDATION_ERROR"
    }
  ]
}

TIP

Check the results array to see which items succeeded or failed, and handle errors accordingly.

Mentium TMS API Documentation

Copyright © 2024-present Mentium