Skip to content
/
API Overview
Last updated

API Overview

Welcome to the MVMNT API documentation. The MVMNT API enables you to automate almost any part of your freight brokerage workflow by integrating directly with our Transportation Management System.

What is MVMNT?

MVMNT is a modern, cloud-native TMS platform built specifically for freight brokers seeking workflow automation and operational efficiency. We help you scale your business by streamlining operations and eliminating manual data entry.

Key Capabilities

  • Submit and Query Data: Create, read, update, and query orders, shipments, locations, carriers, and more via our REST API
  • Real-Time Notifications: Receive near real-time notifications about shipment status changes, document updates, and other events via webhooks
  • Workflow Automation: Automate quoting, load posting, carrier tendering, and more
  • Two-Way Integrations: Sync data bidirectionally with your existing systems

API Features

REST API

Our REST API follows industry best practices:

  • Resource-based URLs: Intuitive, predictable endpoints (e.g., /v1/orders, /v1/shipments)
  • HTTP verbs: Standard GET, POST, PATCH, DELETE operations
  • Standard HTTP status codes:
    • 201 Created for POST (create) operations
    • 200 OK for GET, PATCH (update), and POST /filter operations
    • 204 No Content for DELETE operations
  • JSON: All requests and responses use JSON format
  • Partial Updates: Use PATCH for efficient partial updates (full updates are discouraged)
  • Pagination: Cursor-based pagination for list endpoints
  • Error Handling: Consistent, detailed error responses

Authentication

OAuth 2.0 Machine-to-Machine (M2M) authentication using client credentials flow:

  1. You receive a client ID and client secret from MVMNT
  2. Exchange credentials for a Bearer token via /oauth2/token
  3. Include the token in the Authorization header for all API requests
  4. Request a new token when the current one expires (tokens are cached on your end)

Learn more about authentication →

Webhooks

Subscribe to real-time event notifications:

  • Event Types: order.*, shipment.*, document.*, and more
  • HMAC Security: Verify webhook authenticity with signature verification
  • Automatic Retries: We retry failed deliveries with exponential backoff
  • Testing Tools: Test webhook delivery in development

Learn more about webhooks →

Core Concepts

Resources

The API is organized around the following primary resources:

ResourceDescription
OrdersLoad orders with stops, freight details, and charges
ShipmentsActive shipments with real-time status tracking
LocationsPickup and delivery locations (warehouses, customer sites, etc.)
ContactsContact information for locations and organizations
CarriersCarrier profiles and capacity
ShippersYour customer profiles (shipper organizations)
DocumentsBOLs, PODs, rate confirmations, and invoices
VendorsService providers (not transport carriers)

Client Keys

Every entity includes a key field - a string identifier you control:

  • Your Reference: Store your system's ID in key (e.g., "ERP-ORDER-12345")
  • Bidirectional Lookup: Use key to find MVMNT entities by your system's IDs
  • Returned in Queries: key is always included in API responses
  • Webhooks: key is included in webhook payloads for easy correlation

Learn more about client keys →

Partial Updates

We strongly recommend using PATCH for updates:

PATCH /v1/orders/ORD-12345
Content-Type: application/json

{
  "status": "booked",
  "externalNotes": "Updated delivery instructions"
}

Only the fields you include will be updated. This approach:

  • Reduces payload size
  • Prevents unintentional overwrites
  • Improves performance
  • Simplifies concurrent updates

Learn more about partial updates →

Filtering

Query resources using flexible filter criteria with boolean logic:

POST /v1/vendors/filter
Content-Type: application/json

{
  "filter": {
    "and": [
      { "status": { "equalTo": "ACTIVE" } },
      { "currency": { "in": ["USD", "CAD"] } },
      { "createdAt": { "greaterThanOrEqualTo": "2025-01-01T00:00:00Z" } }
    ]
  },
  "pageSize": 50
}

Key features:

  • Flexible operators: equalTo, in, includes, greaterThan, lessThan, isNull, and more
  • Boolean logic: Combine filters with and, or, not operators
  • Type-specific filters: Different operations for strings, numbers, dates, UUIDs, etc.
  • Case-insensitive text search: Use includes, startsWith, endsWith for partial matching
  • Default soft-delete filtering: Deleted records excluded by default (override with explicit deletedAt filter)

Learn more about filtering →

Pagination

All filter endpoints use cursor-based pagination:

{
  "data": [
    { "id": "...", "name": "..." }
  ],
  "pageInfo": {
    "pageSize": 50,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "endCursor": "eyJpZCI6IjU1MGU4NDAwIn0="
  }
}

Key features:

  • Cursor-based: Efficient for large datasets, no performance degradation on deep pages
  • Configurable page size: 1-250 items per page (default: 50)
  • Consistent across resources: Same pagination format for all filter endpoints
  • Simple iteration: Use endCursor from response to fetch next page

Learn more about pagination →

Soft Deletes

MVMNT uses soft deletes for all resources - deleted entities are marked with deletedAt timestamp rather than being permanently removed:

{
  "id": "550e8400-...",
  "friendlyId": "ORD-12345",
  "deletedAt": "2025-01-20T15:30:00Z",
  ...
}

Key behaviors:

  • DELETE requests: Set deletedAt to current timestamp (entity still exists)
  • List queries: Soft-deleted entities are filtered out by default
  • Get by ID: Soft-deleted entities are still accessible (check deletedAt field)
  • Webhooks: Include entities with deletedAt set - your handlers must handle this
  • Restore: Contact support to restore soft-deleted entities (no API endpoint yet)

Learn more about soft deletes →

Getting Started

1. Obtain API Credentials

Contact your MVMNT account manager to request API access. You'll receive:

  • Client ID
  • Client Secret

Keep your secret secure! Never commit it to version control or expose it in client-side code.

2. Get an Access Token

curl -X POST https://api.mvmnt.io/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

3. Make Your First Request

curl https://api.mvmnt.io/v1/orders \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

View the quickstart guide →

API Endpoint

All API requests are made to:

https://api.mvmnt.io

The current API version is v1, and all endpoints are prefixed with /v1/:

https://api.mvmnt.io/v1/orders
https://api.mvmnt.io/v1/shipments
https://api.mvmnt.io/v1/locations

Rate Limits

API requests are rate limited based on your subscription tier:

TierRequests/Minute
Standard500
Enterprise2000

Rate limit headers are included in every response:

  • X-RateLimit-Limit: Your maximum requests per minute
  • X-RateLimit-Remaining: Requests remaining in current window
  • X-RateLimit-Reset: Unix timestamp when limit resets

Learn more about rate limits →

Support

Need help integrating with the MVMNT API?

  • Documentation: Browse this site for guides, examples, and reference
  • Email Support: support@mvmnt.io
  • Status Page: https://status.mvmnt.io
  • Account Manager: Contact your dedicated MVMNT account manager

Next Steps

Previous page
Next page