Create Location

POST /v2/tms-api/locations

Create a new location in your organization. Locations are automatically geocoded if you provide postal code, state, and country.

Required Fields

country defaults to US when omitted.

Additionally, locations must be geocodable for carrier recommendations. Provide either:

• (latitude + longitude + country) for direct coordinates (state is auto-filled when possible), OR
• (postal_code + state + country) for auto-geocoding

Request Body

Country/State format (ISO)

• country: ISO 3166-1 alpha-2 (e.g., US, CA, MX)
• state: ISO 3166-2 subdivision code (e.g., US-IL, CA-ON, MX-CMX)

API Reference

Request Examples

cURL - 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": "US-IL",
    "postal_code": "60601",
    "country": "US",
    "email": "warehouse@example.com",
    "phone_number": "312-555-0100",
    "weekday_open_hours": "08:00",
    "weekday_close_hours": "17:00"
  }'

Python

import requests

# Create pickup location
response = requests.post(
    "https://api.mentium.io/v2/tms-api/locations",
    headers={
        "X-API-Key": "your_api_key_here",
        "Content-Type": "application/json"
    },
    json={
        "external_reference_id": "LOC-CHICAGO-001",
        "name": "Chicago Distribution Center",
        "address_line1": "123 Industrial Blvd",
        "city": "Chicago",
        "state": "US-IL",
        "postal_code": "60601",
        "country": "US"
    }
)
print(response.json())

Validation Rules

• country: Defaults to US when omitted
• state: Required for address-only requests (postal_code path), optional for coordinate requests
• Geocoding: Must provide either (latitude + longitude) OR (postal_code + state)
• external_reference_id: Must be unique within your organization

Notes

• Auto-geocoding: If you provide postal_code, state, and country, the system will automatically geocode the location and populate latitude and longitude.
• Direct coordinates: If you provide latitude and longitude, the system can auto-fill postal_code and state (when resolvable from coordinates + country dataset).
• Default country: If country is omitted, Mentium uses US.
• Location hours: The weekday_*_hours and weekend_*_hours fields are displayed in the UI for scheduling purposes.

TIP

Create both locations before creating loads. The Load example uses LOC-CHICAGO-001 (pickup) and LOC-DETROIT-001 (delivery).