---
title: "Batch Locations"
method: POST
path: "/v2/tms-api/batch/locations"
tags: ["TMS API", "TMS API - Batch Operations"]
---

# Batch Locations

`POST /v2/tms-api/batch/locations`

## Request

- Base URL: `https://api.mentium.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.mentium.io/v2/tms-api/batch/locations`
- Auth: none declared

Process batch location operations (create, update, upsert, delete).

- For 'create' or 'upsert': all required fields must be provided
- For 'update': only fields to update need to be provided
- For 'delete': no data needed

## Headers

- `X-API-Key` string, nullable: API key for authentication

## Request body

- BatchLocationRequest: Request schema for batch location operations.
  - `items` BatchLocationItem[], required: Batch items (max 100)
    - `operation` 'create' | 'update' | 'upsert' | 'delete', required: Batch operation types.
    - `external_reference_id` string, required: External reference ID of the location
    - `data` union: Location data
      - LocationCreate: Schema for creating a location. Required: country defaults to US when omitted. State is required unless it can be inferred from coordinates. Geocoding Requirement: Must additionally provide EITHER: - (latitude + longitude) for direct coordinates (state can be inferred), OR - (postal_code) for address-based geocoding (with state + country) Without geocoding data, the location cannot be used for lane matching and carrier recommendations.
        - `external_reference_id` string, required: Unique identifier from your system
        - `name` string, nullable: Location name
        - `address_line1` string, nullable: Street address line 1
        - `address_line2` string, nullable: Street address line 2
        - `city` string, nullable: City
        - `state` string, nullable: State/Province
        - `postal_code` string, nullable: Postal/ZIP code
        - `country` string, nullable: Country
        - `latitude` number, nullable: Latitude
        - `longitude` number, nullable: Longitude
        - `iana_timezone` string, nullable: IANA timezone for the facility (e.g., 'America/Chicago'). Used to render stop times in the facility's local TZ.
        - `email` string, nullable: Contact email
        - `phone_number` string, nullable: Contact phone number
        - `weekday_open_hours` string, nullable: Weekday opening hours (HH:MM)
        - `weekday_close_hours` string, nullable: Weekday closing hours (HH:MM)
        - `weekend_open_hours` string, nullable: Weekend opening hours (HH:MM)
        - `weekend_close_hours` string, nullable: Weekend closing hours (HH:MM)
        - `internal_notes` string, nullable: Internal notes about the location
      - LocationUpdate: Schema for updating a location. All fields are optional.
        - `name` string, nullable: Location name
        - `address_line1` string, nullable: Street address line 1
        - `address_line2` string, nullable: Street address line 2
        - `city` string, nullable: City
        - `state` string, nullable: State/Province
        - `postal_code` string, nullable: Postal/ZIP code
        - `country` string, nullable: Country
        - `latitude` number, nullable: Latitude
        - `longitude` number, nullable: Longitude
        - `iana_timezone` string, nullable: IANA timezone for the facility (e.g., 'America/Chicago').
        - `email` string, nullable: Contact email
        - `phone_number` string, nullable: Contact phone number
        - `weekday_open_hours` string, nullable: Weekday opening hours (HH:MM)
        - `weekday_close_hours` string, nullable: Weekday closing hours (HH:MM)
        - `weekend_open_hours` string, nullable: Weekend opening hours (HH:MM)
        - `weekend_close_hours` string, nullable: Weekend closing hours (HH:MM)
        - `internal_notes` string, nullable: Internal notes
    - `location` LocationCreate: Schema for creating a location. Required: country defaults to US when omitted. State is required unless it can be inferred from coordinates. Geocoding Requirement: Must additionally provide EITHER: - (latitude + longitude) for direct coordinates (state can be inferred), OR - (postal_code) for address-based geocoding (with state + country) Without geocoding data, the location cannot be used for lane matching and carrier recommendations.
      - `external_reference_id` string, required: Unique identifier from your system
      - `name` string, nullable: Location name
      - `address_line1` string, nullable: Street address line 1
      - `address_line2` string, nullable: Street address line 2
      - `city` string, nullable: City
      - `state` string, nullable: State/Province
      - `postal_code` string, nullable: Postal/ZIP code
      - `country` string, nullable: Country
      - `latitude` number, nullable: Latitude
      - `longitude` number, nullable: Longitude
      - `iana_timezone` string, nullable: IANA timezone for the facility (e.g., 'America/Chicago'). Used to render stop times in the facility's local TZ.
      - `email` string, nullable: Contact email
      - `phone_number` string, nullable: Contact phone number
      - `weekday_open_hours` string, nullable: Weekday opening hours (HH:MM)
      - `weekday_close_hours` string, nullable: Weekday closing hours (HH:MM)
      - `weekend_open_hours` string, nullable: Weekend opening hours (HH:MM)
      - `weekend_close_hours` string, nullable: Weekend closing hours (HH:MM)
      - `internal_notes` string, nullable: Internal notes about the location

## Response `200`

Successful Response

- BatchResponse: Response for batch operations.
  - `success_count` integer, required: Number of successful operations
  - `error_count` integer, required: Number of failed operations
  - `results` BatchResultItem[], required: Results for each item
    - `external_reference_id` string, required: External reference ID of the item
    - `operation` 'create' | 'update' | 'upsert' | 'delete', required: Batch operation types.
    - `success` boolean, required: Whether the operation succeeded
    - `id` string, nullable: ID of created/updated entity
    - `error` string, nullable: Error message if failed
    - `error_code` string, nullable: Error code (e.g., DUPLICATE, NOT_FOUND)

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/mentium/apis/mentium-api.md) - [All operations](https://skmtc.dev/mentium/apis/mentium-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mentium/apis/mentium-api/revisions/b4ed8e59432e?raw)