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.

Geocoding Requirement

Locations must be geocodable for lane matching and carrier recommendations. Provide either:

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

Request Body

Required Fields

external_reference_idstringrequired

Your unique identifier for this location (must be unique within your organization)

Optional Fields

namestring

Location name (e.g., "Chicago Distribution Center")

address_line1string

Street address line 1

address_line2string

Street address line 2

citystring

City name

statestring

State/Province code (e.g., "IL", "TX", "CA")

postal_codestring

Postal/ZIP code (required for auto-geocoding if latitude/longitude not provided)

countrystring

Country code (e.g., "US", "CA", "MX") - required for auto-geocoding if latitude/longitude not provided

latitudenumber

Latitude (-90 to 90) - provide this OR postal_code+state+country for geocoding

longitudenumber

Longitude (-180 to 180) - provide this OR postal_code+state+country for geocoding

emailstring

Contact email address

phone_numberstring

Contact phone number

weekday_open_hoursstring

Weekday opening hours in HH:MM format (e.g., "08:00")

weekday_close_hoursstring

Weekday closing hours in HH:MM format (e.g., "17:00")

internal_notesstring

Internal notes about the location (max 2000 characters)

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": "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": "IL",
        "postal_code": "60601",
        "country": "US"
    }
)
print(response.json())

Response

201 Created

{
  "id": "loc_abc123def456",
  "external_reference_id": "LOC-CHICAGO-001",
  "name": "Chicago Distribution Center",
  "address_line1": "123 Industrial Blvd",
  "address_line2": null,
  "city": "Chicago",
  "state": "IL",
  "postal_code": "60601",
  "country": "US",
  "latitude": 41.8781,
  "longitude": -87.6298,
  "email": "warehouse@example.com",
  "phone_number": "312-555-0100",
  "weekday_open_hours": "08:00",
  "weekday_close_hours": "17:00",
  "weekend_open_hours": null,
  "weekend_close_hours": null,
  "internal_notes": null,
  "created_at": "2026-01-29T10:30:00Z",
  "updated_at": "2026-01-29T10:30:00Z"
}

422 Validation Error

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "external_reference_id"],
      "msg": "Location must be geocodable. Provide either: (latitude + longitude) OR (postal_code + state + country)"
    }
  ]
}

409 Conflict

{
  "detail": "Location with external_reference_id 'LOC-CHICAGO-001' already exists"
}

Validation Rules

• Geocoding: Must provide either (latitude + longitude) OR (postal_code + state + country)
• 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 already have coordinates, you can provide latitude and longitude directly.
• 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).