# 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 →](/getting-started/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 →](/webhooks/overview)

## Core Concepts

### Resources

The API is organized around the following primary resources:

| Resource | Description |
|  --- | --- |
| **Orders** | Load orders with stops, freight details, and charges |
| **Shipments** | Active shipments with real-time status tracking |
| **Locations** | Pickup and delivery locations (warehouses, customer sites, etc.) |
| **Contacts** | Contact information for locations and organizations |
| **Carriers** | Carrier profiles and capacity |
| **Shippers** | Your customer profiles (shipper organizations) |
| **Documents** | BOLs, PODs, rate confirmations, and invoices |
| **Vendors** | Service 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 →](/getting-started/client-keys)

### Partial Updates

We strongly recommend using **PATCH** for updates:


```http
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 →](/getting-started/partial-updates)

### Filtering

Query resources using flexible filter criteria with boolean logic:


```bash
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 →](/getting-started/filtering)

### Pagination

All filter endpoints use cursor-based pagination:


```json
{
  "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 →](/getting-started/pagination)

### Soft Deletes

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


```json
{
  "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/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


```bash
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:**


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

### 3. Make Your First Request


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

[View the quickstart guide →](/getting-started/quickstart)

## 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:

| Tier | Requests/Minute |
|  --- | --- |
| **Standard** | 500 |
| **Enterprise** | 2000 |


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 →](/getting-started/rate-limits)

## Support

Need help integrating with the MVMNT API?

- **Documentation**: Browse this site for guides, examples, and reference
- **Email Support**: [support@mvmnt.io](mailto:support@mvmnt.io)
- **Status Page**: [https://status.mvmnt.io](https://status.mvmnt.io)
- **Account Manager**: Contact your dedicated MVMNT account manager


## Next Steps

- [Authentication Guide](/getting-started/authentication) - Set up OAuth credentials
- [Quickstart](/getting-started/quickstart) - Make your first API call in 5 minutes
- [Filtering](/getting-started/filtering) - Query resources with flexible filter criteria
- [Pagination](/getting-started/pagination) - Efficiently iterate through large result sets
- [Client Keys](/getting-started/client-keys) - Use your own identifiers for bidirectional lookups
- [API Reference](/apis/openapi) - Explore all available endpoints
- [Webhooks](/webhooks/overview) - Set up real-time event notifications