Skip to content
/Event Notifications

MVMNT API (1.0.0)

The MVMNT API enables you to automate freight brokerage workflows by integrating directly with our Transportation Management System.

Postman setup guide: API Clients.

Authentication

OAuth 2.0 client credentials flow. See Authentication Guide for details.

Token Endpoint

POST https://api.mvmnt.io/oauth2/token

Request

Headers:

Content-Type: application/x-www-form-urlencoded

Body Parameters:

grant_type=client_credentials
client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET

Example Request

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"

Success Response

Status: 200 OK

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

Response Fields:

  • access_token: JWT Bearer token to use for API requests
  • token_type: Always Bearer
  • expires_in: Token lifetime in seconds (3600 = 1 hour)

Idempotency

Mutating requests (POST, PATCH, DELETE) accept an optional Idempotency-Key header (up to 255 characters). Retrying a request with the same key and the same body returns the original result instead of repeating the operation; reusing a key with a different body fails. Keys are scoped to your organization — keys chosen by other tenants can never collide with yours. Use a stable identifier from your system (for example your own record id plus the action) rather than a random value per attempt.

Download OpenAPI description
openapi.json
openapi.yaml
openapi-3.0.yaml (legacy tooling)
Postman Collection
Postman Environment — Demo
Postman Environment — Production
Overview
URL
https://docs.mvmnt.io
MVMNT Support
support@mvmnt.io
License
Proprietary
Languages
Servers
Production
https://api.mvmnt.io/v1
Demo (non-production)
https://api.demo.mvmnt.io/v1

Carriers

Carrier management operations

Operations

Carrier Contacts

Carrier contact management operations

Operations

Carrier Factors

Carrier factor (factoring company) management operations

Operations

Carrier Payment Methods

Carrier payment method management operations

Operations

Companies

Company management operations

Operations

Credit Memos

AR credit memo management operations. Credit memos represent customer credits that can be applied to invoices.

Operations

Bills

AP bill management operations. Bills represent carrier and vendor invoices to be paid.

Operations

Bill Payments

AP bill payment management operations. Bill payments record payments made to carriers and vendors.

Operations

Customers

Customer management operations

Operations

Customer Contacts

Customer contact management operations

Operations

Documents

Document management operations. Documents are files (PDFs, images) that can be attached to orders, loads, or services.

Operations

Invoices

AR invoice management operations. Invoices represent customer billing for shipment services.

Operations

Loads

Load management operations. Loads represent carrier execution - which carrier is moving the freight.

Operations

Locations

Location management operations

Operations

Location Contacts

Location contact management operations

Operations

Payment Terms

Payment term management operations

Operations

Reference Data

Read-only catalogs (equipment, charge codes, special requirements) referenced by id from other resources.

Every catalog also answers on its short top-level path, so GET /v1/charge-codes and GET /v1/reference-data/charge-codes are the same endpoint. The documented /reference-data/* form is canonical — it keeps the catalogs grouped here as more are added (port codes, cities, zip codes) — and the short form is a convenience alias.

Operations

Payments

AR payment management operations. Payments represent received customer payments applied to invoices.

Operations

Quotes

Quote management operations. Quotes are pricing requests/responses that can be converted to shipments.

Operations

Saved Searches

Saved search management operations

Operations

Services

Service (vended service) management operations. Services represent non-carrier vendor work (drayage, customs, warehousing).

Operations

Shipments

Shipment tracking and management operations. Shipments contain orders, loads, and services.

Operations

Teams

Team management operations

Operations

Users

User management operations

Operations

Vendors

Vendor management operations

Operations

Vendor Contacts

Vendor contact management operations

Operations

Vendor Payment Methods

Vendor payment method management operations

Operations

Event Notifications

Webhooks

Webhook EventWebhook

Request

All webhook events are delivered to your configured endpoint URL.

The event field in the payload determines which type of webhook was triggered. Your endpoint should handle all event types or gracefully ignore unknown events.

Event Types:

  • Entity changes: CUSTOMER_*, COMPANY_*, CARRIER_*, CUSTOMER_CONTACT_*
  • Shipment events: SHIPMENT_DELIVERED, SHIPMENT_BOOKED, SHIPMENT_DISPATCHED, etc.
  • Financial events: CARRIER_INVOICE_CREATED, CUSTOMER_PAYMENT_CREATED, etc.

Security: All webhook requests include an x-api-key header containing your webhook token configured in the MVMNT UI.

Best Practices:

  • Return 200 OK quickly and process asynchronously
  • Implement idempotency using event ID and timestamp
  • Handle unknown event types gracefully for forward compatibility
Security
BearerAuth
Bodyapplication/jsonrequired
sentAtstring(date-time)required

ISO 8601 timestamp when the webhook was sent from MVMNT

Example: "2025-01-15T14:30:00Z"
eventsArray of objects(WebhookPayload)non-emptyrequired

Array of webhook events (typically contains a single event)

eventstringrequired

The type of webhook event

Enum"CUSTOMER_CREATED""CUSTOMER_UPDATED""CUSTOMER_DELETED""CARRIER_ACTIVATED""CARRIER_CONTACT_CREATED""CARRIER_CONTACT_UPDATED""CARRIER_CONTACT_DELETED""CARRIER_CREATED""CARRIER_DEACTIVATED""CARRIER_DELETED"
Discriminator
timestampstring(date-time)required

ISO 8601 timestamp when the event occurred

Example: "2025-01-15T14:30:00Z"
dataobjectrequired

Event-specific data. Structure varies by event type.

objectstringread-only

Object type identifier

Value"CUSTOMER"
Example: "CUSTOMER"
idstring(uuid)read-onlyrequired

Unique customer identifier

Example: "550e8400-e29b-41d4-a716-446655440000"
namestringrequired

Customer company name

Example: "Acme Manufacturing Corp"
friendlyIdstringread-onlyrequired

Human-readable customer identifier, starts with "A"

Example: "A123456"
statusstring(CustomerStatus)required

Customer account status (includes lead stages):

  • NEW: New lead, not yet contacted
  • CONTACTED: Initial contact made with lead
  • QUALIFIED: Lead has been qualified as potential customer
  • QUOTED: Quote has been provided to lead
  • NURTURING: Lead being nurtured for future opportunity
  • PENDING: Customer prospect pending activation
  • ACTIVE: Active customer account
  • INACTIVE: Deactivated customer account
  • BLOCKED: Customer account blocked from operations
  • CLOSED: Customer account permanently closed
Enum"NEW""CONTACTED""QUALIFIED""QUOTED""NURTURING""PENDING""ACTIVE""INACTIVE""BLOCKED""CLOSED"
serviceTierCustomerServiceTier (string) or null

Service tier level

Any of:

Service tier level for the customer

string(CustomerServiceTier)
Enum"TIER_1""TIER_2""TIER_3"
websitestring or null

Customer website URL

Example: "https://acme-manufacturing.com"
phoneNumberstring or null

Primary phone number

Example: "+1-555-123-4567"
industryCustomerIndustry (string) or null

Industry classification

Any of:

Industry classification for the customer

string(CustomerIndustry)
Enum"AGRICULTURE_FORESTRY""CONSTRUCTION""CONSUMER_GOODS""EDUCATIONAL_SERVICES""ENTERTAINMENT""FOOD_SERVICES""HEALTHCARE""INDUSTRIAL_MACHINERY""MANUFACTURING""MINING"
annualRevenueCustomerAnnualRevenue (string) or null

Annual revenue range

Any of:

Annual revenue range

string(CustomerAnnualRevenue)
Enum"_0_TO_500K""_500K_TO_3M""_3M_TO_10M""_10M_TO_25M""_25M_TO_50M""_50M_TO_100M""_100M_TO_500M""_500M_PLUS"
annualSpendCustomerAnnualSpend (string) or null

Annual freight spend estimate

Any of:

Annual freight spend estimate range

string(CustomerAnnualSpend)
Enum"_0_TO_25K""_25_TO_150K""_150K_TO_300K""_300K_TO_1M""_1_TO_5M""_5M_TO_25M""_25M_TO_75M""_75M_PLUS"
spendTypeCustomerSpendType (string) or null

Customer spend type (contract vs spot pricing)

Any of:

Customer spend type:

  • CONTRACT: Customer operates under contract pricing
  • SPOT: Customer operates on spot market pricing
string(CustomerSpendType)
Enum"CONTRACT""SPOT"
naicsstring or null

NAICS industry code

Example: "336411"
einstring or null

Employer Identification Number

Example: "12-3456789"
dunsstring or null

Dun & Bradstreet number

Example: "123456789"
leadSourcestring or null

How this customer was acquired

Example: "Referral"
dbaNamestring or null

Doing business as name

Example: "Acme Corp DBA"
numberOfEmployeesCustomerNumberOfEmployees (string) or null

Company size by number of employees

Any of:

Number of employees in the company

string(CustomerNumberOfEmployees)
Enum"_0_TO_1""_2_TO_5""_6_TO_9""_10_TO_24""_25_TO_99""_100_TO_249""_250_TO_499""_500_OR_MORE"
externalIdstring or null

External system identifier

Example: "EXT-12345"
currencyCustomerCurrency (string) or null

Preferred currency for transactions

Any of:

Preferred currency for transactions

string(CustomerCurrency)
Enum"USD""CAD""MXN""EUR""GBP""JPY""CNY""AUD""BRL""INR"
creditLimitnumber or null(float)

Maximum credit allowed

Example: 50000
creditUsageWarningnumber or null(float)

Credit usage warning threshold

Example: 40000
freeCreditReqnumber or null(float)

Free credit requirement

Example: 5000
defaultModeCustomerTransportationMode (string) or null

Default transportation mode. Values outside the enum are rejected with 400; customers whose internal mode isn't in the public enum return the field omitted.

Any of:

Transportation mode type

string(CustomerTransportationMode)
Enum"FTL""LTL""AIR""OCEAN""RAIL""INTERMODAL""DRAYAGE""EXPEDITED_GROUND""EXPEDITED_AIR""AUTO"
defaultMarginnumber or null(float)

Default margin percentage (0-1, e.g., 0.15 for 15%)

Example: 0.15
minMarginnumber or null(float)

Minimum margin threshold

Example: 0.1
maxMarginnumber or null(float)

Maximum margin threshold

Example: 0.25
defaultInternalNotesstring or null

Default internal notes template

Example: "Contact via email only"
defaultCarrierNotesstring or null

Default carrier-facing notes template used when note splitting is enabled

Example: "Call pickup contact before arrival"
defaultExternalNotesstring or null

Default external notes template

Example: "Please call 1 hour before delivery"
defaultShowNotesShowNotes (string) or null

Controls whether default external notes are reused on carrier docs or split from default carrier notes

Any of:

Controls whether external notes are shown on all documents or split from carrier-facing notes.

  • ALL: Use external notes on customer-facing and carrier-facing documents
  • SPLIT: Use external notes on customer-facing documents and carrier notes on carrier-facing documents
string(ShowNotes)
Enum"ALL""SPLIT"
autoAcceptTenderboolean or null

Auto-accept tender flag

Example: false
groupResourceReference (object) or null

Customer group reference (minimal - id and key only)

Any of:

Reference to another resource (returned in responses)

paymentTermPaymentTermReference (object) or null

Payment term configuration reference with full details

Any of:

Enhanced reference to a payment term resource (returned in responses). Includes full payment term details in addition to id/key.

notesstring or null

Internal notes about this customer

Example: "Prefers email communication"
deactivationReasonCustomerDeactivationReason (string) or null

Reason for deactivation if status is INACTIVE

Any of:

Reason for customer deactivation:

  • NOT_PAYING_INVOICE: Customer is not paying invoices
  • ACQUIRED: Customer was acquired by another company
  • DUPLICATE: Duplicate customer record
  • NOT_IN_BUSINESS: Customer is no longer in business
  • OTHER: Other reason (see deactivationNotes for details)
string(CustomerDeactivationReason)
Enum"NOT_PAYING_INVOICE""ACQUIRED""DUPLICATE""NOT_IN_BUSINESS""OTHER"
deactivationNotesstring or null

Additional details about deactivation

deactivationDatestring or null(date-time)

When the customer was deactivated

Example: null
closedAtstring or null(date-time)

When the customer account was closed

Example: null
closedByUserReference (object) or nullread-only

User who closed the account (full user details)

Any of:

Enhanced reference to a user resource (returned in responses). Includes full user details in addition to id/key.

Note: Does NOT include nested references (teams, etc.) to prevent recursion. Maximum nesting depth: 1 level.

closedNotesstring or null

Notes about account closure

corporateAddressAddress (object) or null

Corporate headquarters address (nested location data)

Any of:

Physical address/location details (nested, without id).

This is an embedded object representing a Location record. The id is managed internally and not exposed in the API.

billingAddressAddress (object) or null

Billing address (nested location data)

Any of:

Physical address/location details (nested, without id).

This is an embedded object representing a Location record. The id is managed internally and not exposed in the API.

qboCustomerIdstring or null

QuickBooks Online customer ID

Example: null
keystring or null<= 512 characters

Client-defined reference identifier for this customer

Example: "ERP-CUSTOMER-12345"
contactsArray of objects(CustomerContactReference)

Contacts for this customer

createdAtstring(date-time)read-onlyrequired

Timestamp when customer was created

Example: "2025-01-15T10:00:00Z"
updatedAtstring(date-time)read-onlyrequired

Timestamp when customer was last updated

Example: "2025-01-15T14:30:00Z"
deletedAtstring or null(date-time)read-only

Timestamp when customer was soft-deleted (null if active)

Example: null
deletedByUserReference (object) or nullread-only

User who deleted the customer (full user details)

Any of:

Enhanced reference to a user resource (returned in responses). Includes full user details in addition to id/key.

Note: Does NOT include nested references (teams, etc.) to prevent recursion. Maximum nesting depth: 1 level.

property name*anyadditional property
diffArray of objects or null(DiffChange)

Array of changes made during an UPDATE operation using json-diff-ts. Only present for UPDATE events. Null for CREATE and DELETE events. Each change follows the IChange interface from json-diff-ts library.

application/json
{
  "sentAt": "2025-01-15T14:30:05Z",
  "events": [
    { … }
  ]
}

Responses

Webhook received and processed successfully