Skip to content
API Reference/
/
Report TONU

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

Filter loads

Request

Search for loads using filter criteria.

Each row carries the fully nested load payload (stops with addresses, carriers with charges). With a large pageSize, responses can be sizable.

Common Filters

  • By shipment: { "filter": { "shipmentId": { "equalTo": "uuid" } } }
  • Active loads: { "filter": { "status": { "notIn": ["COMPLETE", "CANCELED"] } } }
  • FTL loads: { "filter": { "mode": { "equalTo": "FTL" } } }
Security
BearerAuth
Bodyapplication/jsonrequired
filterobject(LoadFilter)
pageSizeinteger[ 1 .. 100 ]
Default 50
cursorstring
curl -i -X POST \
  https://api.mvmnt.io/v1/loads/filter \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": {
      "shipmentId": {
        "equalTo": "550e8400-e29b-41d4-a716-446655440000"
      }
    }
  }'

Responses

Loads matching filter criteria

Bodyapplication/json
dataArray of objects(Load)required
idstring(uuid)required
Example: "550e8400-e29b-41d4-a716-446655440000"
friendlyIdstring

Human-readable load ID (e.g., "LD-12345")

Example: "LD-12345"
keystring or null

Client-defined reference identifier for this load

Example: "my-load-001"
shipmentIdstring(uuid)

Parent shipment

shipmentKeystring or null

Parent shipment human-readable ID (friendlyId)

modestring(TransportMode)

Transportation mode. Optional on write — a shipment or load created without one is stored with no mode, the same as one created in the TMS.

  • FTL: Full Truckload — the value the TMS stores and always returns
  • TL: legacy spelling of FTL, still accepted on write, never returned
  • LTL: Less than Truckload
  • PTL: Partial Truckload
  • RLTL: Retail LTL
  • AUTO: Auto transport
  • EXPEDITED_AIR: Expedited air
  • EXPEDITED_GROUND: Expedited ground
  • AIR: Air freight
  • OCEAN: Ocean freight
  • RAIL: Rail freight
  • INTERMODAL: Intermodal (multiple modes)
  • DRAYAGE: Drayage/cartage
Enum"FTL""TL""LTL""PTL""RLTL""AIR""OCEAN""RAIL""INTERMODAL""DRAYAGE"
statusstring(LoadStatus)required

Current status of the load.

Pre-transit:

  • SOURCING: Looking for carrier
  • SELECTED: Carrier selected
  • BOOKED: Carrier booked
  • DISPATCHED: Dispatched to carrier

In-transit:

  • LOADING: Loading at pickup
  • PICKED_UP: Picked up
  • IN_TRANSIT: In transit
  • UNLOADING: Unloading at delivery
  • ARRIVED_AT_DELIVERY_TERMINAL: Arrived at delivery terminal
  • OUT_FOR_DELIVERY: Out for delivery
  • RECOVERED: Recovered after a service issue

Delivered (accounts payable lifecycle):

  • DELIVERED_AWAITING_INVOICE: Delivered, awaiting carrier invoice
  • DELIVERED_INVOICE_IN_REVIEW: Carrier invoice in review
  • DELIVERED_APPROVED_TO_BE_PAID: Approved to be paid
  • DELIVERED_PAID: Paid

Final / exceptions:

  • COMPLETE: Complete
  • SERVICE_FAILURE: Service failure
  • ON_HOLD: On hold
  • CANCELED: Canceled
Enum"SOURCING""SELECTED""BOOKED""DISPATCHED""LOADING""PICKED_UP""IN_TRANSIT""UNLOADING""ARRIVED_AT_DELIVERY_TERMINAL""OUT_FOR_DELIVERY"
stopsArray of objects(LoadStop)

Load stops

carriersArray of objects(LoadCarrier)

Carrier assignments (flattened from LoadCarriersConnection)

totalCostnumber or null

Total carrier costs

createdAtstring(date-time)required
updatedAtstring or null(date-time)
pickedUpAtstring or null(date-time)
deliveredAtstring or null(date-time)
paginationobject(PaginationInfo)required
pageSizeintegerrequired

Number of items per page

Example: 50
hasNextPagebooleanrequired

Whether there are more pages

Example: true
hasPreviousPageboolean

Whether there are previous pages

Example: false
endCursorstring or null

Cursor for the next page (null if no next page)

Example: "eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9"
Response
application/json
{
  "data": [
    { … }
  ],
  "pagination": {
    "pageSize": 50,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "endCursor": "eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9"
  }
}

Add an additional load

Request

Add an additional load to an existing shipment. This endpoint requires a shipment — it cannot create one. Creating a shipment already creates its first load structure; use this endpoint only for multi-load scenarios (extra legs, split moves).

What happens

  • Load is created for the specified shipment
  • Optionally assigns an initial carrier

To book a carrier on a load afterwards, use the load-carrier endpoints — that is the primary booking flow.

Security
BearerAuth
Bodyapplication/jsonrequired
shipmentIdstring(uuid)required

Parent shipment ID

loadobject(LoadInput)required
modestring(TransportMode)

Transportation mode. Optional on write — a shipment or load created without one is stored with no mode, the same as one created in the TMS.

  • FTL: Full Truckload — the value the TMS stores and always returns
  • TL: legacy spelling of FTL, still accepted on write, never returned
  • LTL: Less than Truckload
  • PTL: Partial Truckload
  • RLTL: Retail LTL
  • AUTO: Auto transport
  • EXPEDITED_AIR: Expedited air
  • EXPEDITED_GROUND: Expedited ground
  • AIR: Air freight
  • OCEAN: Ocean freight
  • RAIL: Rail freight
  • INTERMODAL: Intermodal (multiple modes)
  • DRAYAGE: Drayage/cartage
Enum"FTL""TL""LTL""PTL""RLTL""AIR""OCEAN""RAIL""INTERMODAL""DRAYAGE"
orderStopIdsArray of strings(uuid)

Order stop IDs to include in this load

carrierobject(LoadCarrierInput)

Initial carrier assignment

curl -i -X POST \
  https://api.mvmnt.io/v1/loads \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "shipmentId": "550e8400-e29b-41d4-a716-446655440000",
    "load": {
      "mode": "FTL"
    }
  }'

Responses

Load created successfully

Bodyapplication/json
idstring(uuid)required
Example: "550e8400-e29b-41d4-a716-446655440000"
friendlyIdstring

Human-readable load ID (e.g., "LD-12345")

Example: "LD-12345"
keystring or null

Client-defined reference identifier for this load

Example: "my-load-001"
shipmentIdstring(uuid)

Parent shipment

shipmentKeystring or null

Parent shipment human-readable ID (friendlyId)

modestring(TransportMode)

Transportation mode. Optional on write — a shipment or load created without one is stored with no mode, the same as one created in the TMS.

  • FTL: Full Truckload — the value the TMS stores and always returns
  • TL: legacy spelling of FTL, still accepted on write, never returned
  • LTL: Less than Truckload
  • PTL: Partial Truckload
  • RLTL: Retail LTL
  • AUTO: Auto transport
  • EXPEDITED_AIR: Expedited air
  • EXPEDITED_GROUND: Expedited ground
  • AIR: Air freight
  • OCEAN: Ocean freight
  • RAIL: Rail freight
  • INTERMODAL: Intermodal (multiple modes)
  • DRAYAGE: Drayage/cartage
Enum"FTL""TL""LTL""PTL""RLTL""AIR""OCEAN""RAIL""INTERMODAL""DRAYAGE"
statusstring(LoadStatus)required

Current status of the load.

Pre-transit:

  • SOURCING: Looking for carrier
  • SELECTED: Carrier selected
  • BOOKED: Carrier booked
  • DISPATCHED: Dispatched to carrier

In-transit:

  • LOADING: Loading at pickup
  • PICKED_UP: Picked up
  • IN_TRANSIT: In transit
  • UNLOADING: Unloading at delivery
  • ARRIVED_AT_DELIVERY_TERMINAL: Arrived at delivery terminal
  • OUT_FOR_DELIVERY: Out for delivery
  • RECOVERED: Recovered after a service issue

Delivered (accounts payable lifecycle):

  • DELIVERED_AWAITING_INVOICE: Delivered, awaiting carrier invoice
  • DELIVERED_INVOICE_IN_REVIEW: Carrier invoice in review
  • DELIVERED_APPROVED_TO_BE_PAID: Approved to be paid
  • DELIVERED_PAID: Paid

Final / exceptions:

  • COMPLETE: Complete
  • SERVICE_FAILURE: Service failure
  • ON_HOLD: On hold
  • CANCELED: Canceled
Enum"SOURCING""SELECTED""BOOKED""DISPATCHED""LOADING""PICKED_UP""IN_TRANSIT""UNLOADING""ARRIVED_AT_DELIVERY_TERMINAL""OUT_FOR_DELIVERY"
stopsArray of objects(LoadStop)

Load stops

carriersArray of objects(LoadCarrier)

Carrier assignments (flattened from LoadCarriersConnection)

totalCostnumber or null

Total carrier costs

createdAtstring(date-time)required
updatedAtstring or null(date-time)
pickedUpAtstring or null(date-time)
deliveredAtstring or null(date-time)
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "friendlyId": "LD-12345",
  "key": "my-load-001",
  "shipmentId": "47efd5a2-af91-4417-950a-7f546cd1b5cf",
  "shipmentKey": "string",
  "mode": "FTL",
  "status": "SOURCING",
  "stops": [
    { … }
  ],
  "carriers": [
    { … }
  ],
  "totalCost": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "pickedUpAt": "2019-08-24T14:15:22Z",
  "deliveredAt": "2019-08-24T14:15:22Z"
}

Get a load

Request

Retrieve a load by ID.

The response includes embedded carriers and stops.

Security
BearerAuth
Path
idstringrequired

Resource ID (UUID) or client key

Example: 550e8400-e29b-41d4-a716-446655440000
Query
bystring

Specify lookup type for faster retrieval. If omitted, defaults to looking up by ID first, then falls back to client key if not found. Use by=key when you know you're providing a client key for best performance.

Enum"id""key"
Example: by=key
curl -i -X GET \
  'https://api.mvmnt.io/v1/loads/550e8400-e29b-41d4-a716-446655440000?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Load retrieved successfully

Bodyapplication/json
idstring(uuid)required
Example: "550e8400-e29b-41d4-a716-446655440000"
friendlyIdstring

Human-readable load ID (e.g., "LD-12345")

Example: "LD-12345"
keystring or null

Client-defined reference identifier for this load

Example: "my-load-001"
shipmentIdstring(uuid)

Parent shipment

shipmentKeystring or null

Parent shipment human-readable ID (friendlyId)

modestring(TransportMode)

Transportation mode. Optional on write — a shipment or load created without one is stored with no mode, the same as one created in the TMS.

  • FTL: Full Truckload — the value the TMS stores and always returns
  • TL: legacy spelling of FTL, still accepted on write, never returned
  • LTL: Less than Truckload
  • PTL: Partial Truckload
  • RLTL: Retail LTL
  • AUTO: Auto transport
  • EXPEDITED_AIR: Expedited air
  • EXPEDITED_GROUND: Expedited ground
  • AIR: Air freight
  • OCEAN: Ocean freight
  • RAIL: Rail freight
  • INTERMODAL: Intermodal (multiple modes)
  • DRAYAGE: Drayage/cartage
Enum"FTL""TL""LTL""PTL""RLTL""AIR""OCEAN""RAIL""INTERMODAL""DRAYAGE"
statusstring(LoadStatus)required

Current status of the load.

Pre-transit:

  • SOURCING: Looking for carrier
  • SELECTED: Carrier selected
  • BOOKED: Carrier booked
  • DISPATCHED: Dispatched to carrier

In-transit:

  • LOADING: Loading at pickup
  • PICKED_UP: Picked up
  • IN_TRANSIT: In transit
  • UNLOADING: Unloading at delivery
  • ARRIVED_AT_DELIVERY_TERMINAL: Arrived at delivery terminal
  • OUT_FOR_DELIVERY: Out for delivery
  • RECOVERED: Recovered after a service issue

Delivered (accounts payable lifecycle):

  • DELIVERED_AWAITING_INVOICE: Delivered, awaiting carrier invoice
  • DELIVERED_INVOICE_IN_REVIEW: Carrier invoice in review
  • DELIVERED_APPROVED_TO_BE_PAID: Approved to be paid
  • DELIVERED_PAID: Paid

Final / exceptions:

  • COMPLETE: Complete
  • SERVICE_FAILURE: Service failure
  • ON_HOLD: On hold
  • CANCELED: Canceled
Enum"SOURCING""SELECTED""BOOKED""DISPATCHED""LOADING""PICKED_UP""IN_TRANSIT""UNLOADING""ARRIVED_AT_DELIVERY_TERMINAL""OUT_FOR_DELIVERY"
stopsArray of objects(LoadStop)

Load stops

carriersArray of objects(LoadCarrier)

Carrier assignments (flattened from LoadCarriersConnection)

totalCostnumber or null

Total carrier costs

createdAtstring(date-time)required
updatedAtstring or null(date-time)
pickedUpAtstring or null(date-time)
deliveredAtstring or null(date-time)
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "friendlyId": "LD-12345",
  "key": "my-load-001",
  "shipmentId": "47efd5a2-af91-4417-950a-7f546cd1b5cf",
  "shipmentKey": "string",
  "mode": "FTL",
  "status": "SOURCING",
  "stops": [
    { … }
  ],
  "carriers": [
    { … }
  ],
  "totalCost": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "pickedUpAt": "2019-08-24T14:15:22Z",
  "deliveredAt": "2019-08-24T14:15:22Z"
}

Update a load

Request

Update load fields.

Note: To manage carriers, use the carrier-specific endpoints.

Security
BearerAuth
Path
idstringrequired

Resource ID (UUID) or client key

Example: 550e8400-e29b-41d4-a716-446655440000
Query
bystring

Specify lookup type for faster retrieval. If omitted, defaults to looking up by ID first, then falls back to client key if not found. Use by=key when you know you're providing a client key for best performance.

Enum"id""key"
Example: by=key
Bodyapplication/jsonrequired
modestring(TransportMode)

Transportation mode. Optional on write — a shipment or load created without one is stored with no mode, the same as one created in the TMS.

  • FTL: Full Truckload — the value the TMS stores and always returns
  • TL: legacy spelling of FTL, still accepted on write, never returned
  • LTL: Less than Truckload
  • PTL: Partial Truckload
  • RLTL: Retail LTL
  • AUTO: Auto transport
  • EXPEDITED_AIR: Expedited air
  • EXPEDITED_GROUND: Expedited ground
  • AIR: Air freight
  • OCEAN: Ocean freight
  • RAIL: Rail freight
  • INTERMODAL: Intermodal (multiple modes)
  • DRAYAGE: Drayage/cartage
Enum"FTL""TL""LTL""PTL""RLTL""AIR""OCEAN""RAIL""INTERMODAL""DRAYAGE"
curl -i -X PATCH \
  'https://api.mvmnt.io/v1/loads/550e8400-e29b-41d4-a716-446655440000?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "mode": "FTL"
  }'

Responses

Load updated successfully

Bodyapplication/json
idstring(uuid)required
Example: "550e8400-e29b-41d4-a716-446655440000"
friendlyIdstring

Human-readable load ID (e.g., "LD-12345")

Example: "LD-12345"
keystring or null

Client-defined reference identifier for this load

Example: "my-load-001"
shipmentIdstring(uuid)

Parent shipment

shipmentKeystring or null

Parent shipment human-readable ID (friendlyId)

modestring(TransportMode)

Transportation mode. Optional on write — a shipment or load created without one is stored with no mode, the same as one created in the TMS.

  • FTL: Full Truckload — the value the TMS stores and always returns
  • TL: legacy spelling of FTL, still accepted on write, never returned
  • LTL: Less than Truckload
  • PTL: Partial Truckload
  • RLTL: Retail LTL
  • AUTO: Auto transport
  • EXPEDITED_AIR: Expedited air
  • EXPEDITED_GROUND: Expedited ground
  • AIR: Air freight
  • OCEAN: Ocean freight
  • RAIL: Rail freight
  • INTERMODAL: Intermodal (multiple modes)
  • DRAYAGE: Drayage/cartage
Enum"FTL""TL""LTL""PTL""RLTL""AIR""OCEAN""RAIL""INTERMODAL""DRAYAGE"
statusstring(LoadStatus)required

Current status of the load.

Pre-transit:

  • SOURCING: Looking for carrier
  • SELECTED: Carrier selected
  • BOOKED: Carrier booked
  • DISPATCHED: Dispatched to carrier

In-transit:

  • LOADING: Loading at pickup
  • PICKED_UP: Picked up
  • IN_TRANSIT: In transit
  • UNLOADING: Unloading at delivery
  • ARRIVED_AT_DELIVERY_TERMINAL: Arrived at delivery terminal
  • OUT_FOR_DELIVERY: Out for delivery
  • RECOVERED: Recovered after a service issue

Delivered (accounts payable lifecycle):

  • DELIVERED_AWAITING_INVOICE: Delivered, awaiting carrier invoice
  • DELIVERED_INVOICE_IN_REVIEW: Carrier invoice in review
  • DELIVERED_APPROVED_TO_BE_PAID: Approved to be paid
  • DELIVERED_PAID: Paid

Final / exceptions:

  • COMPLETE: Complete
  • SERVICE_FAILURE: Service failure
  • ON_HOLD: On hold
  • CANCELED: Canceled
Enum"SOURCING""SELECTED""BOOKED""DISPATCHED""LOADING""PICKED_UP""IN_TRANSIT""UNLOADING""ARRIVED_AT_DELIVERY_TERMINAL""OUT_FOR_DELIVERY"
stopsArray of objects(LoadStop)

Load stops

carriersArray of objects(LoadCarrier)

Carrier assignments (flattened from LoadCarriersConnection)

totalCostnumber or null

Total carrier costs

createdAtstring(date-time)required
updatedAtstring or null(date-time)
pickedUpAtstring or null(date-time)
deliveredAtstring or null(date-time)
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "friendlyId": "LD-12345",
  "key": "my-load-001",
  "shipmentId": "47efd5a2-af91-4417-950a-7f546cd1b5cf",
  "shipmentKey": "string",
  "mode": "FTL",
  "status": "SOURCING",
  "stops": [
    { … }
  ],
  "carriers": [
    { … }
  ],
  "totalCost": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "pickedUpAt": "2019-08-24T14:15:22Z",
  "deliveredAt": "2019-08-24T14:15:22Z"
}

Delete a load

Request

Soft delete a load.

Prerequisites

  • Load must not have any active carriers
Security
BearerAuth
Path
idstringrequired

Resource ID (UUID) or client key

Example: 550e8400-e29b-41d4-a716-446655440000
Query
bystring

Specify lookup type for faster retrieval. If omitted, defaults to looking up by ID first, then falls back to client key if not found. Use by=key when you know you're providing a client key for best performance.

Enum"id""key"
Example: by=key
curl -i -X DELETE \
  'https://api.mvmnt.io/v1/loads/550e8400-e29b-41d4-a716-446655440000?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Load deleted successfully

Response
No content

Add carrier to load

Request

Add an additional carrier to a load.

Use cases

  • Split loads (multiple carriers for same load)
  • Adding backup carrier
  • Re-assigning after TONU/bounce

What happens

  • New LoadCarrier record is created
  • Carrier is notified (if configured)
Security
BearerAuth
Path
idstringrequired

Resource ID (UUID) or client key

Example: 550e8400-e29b-41d4-a716-446655440000
Query
bystring

Specify lookup type for faster retrieval. If omitted, defaults to looking up by ID first, then falls back to client key if not found. Use by=key when you know you're providing a client key for best performance.

Enum"id""key"
Example: by=key
Bodyapplication/jsonrequired
carrierobject(ResourceReferenceInput)required
One of:

Carrier reference

idstring(uuid)required

Resource UUID

keystring

Client-defined reference ID

contactobject(ResourceReferenceInput)
One of:

Carrier contact

chargesArray of objects
driverNamestring
driverPhonestring
truckNumberstring
trailerNumberstring
curl -i -X POST \
  'https://api.mvmnt.io/v1/loads/550e8400-e29b-41d4-a716-446655440000/add-carrier?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "carrier": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    },
    "contact": {
      "id": "660e8400-e29b-41d4-a716-446655440001"
    },
    "charges": [
      {
        "chargeCode": {
          "key": "LINEHAUL"
        },
        "amount": 2000
      }
    ],
    "driverName": "John Smith",
    "driverPhone": "+15551234567"
  }'

Responses

Carrier added successfully

Bodyapplication/json
loadIdstring(uuid)required
loadCarrierIdstring(uuid)required

The new load carrier ID

loadCarrierobject(LoadCarrier)
Response
application/json
{
  "loadId": "9fa4c9ea-0db7-4bb2-8f50-086d18a90403",
  "loadCarrierId": "29f9f87f-f417-4003-80d8-b9d49851fa35",
  "loadCarrier": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "carrier": { … },
    "contact": { … },
    "status": "ACTIVE",
    "billingStatus": "AWAITING_INVOICE",
    "bookedAt": "2019-08-24T14:15:22Z",
    "dispatchedAt": "2019-08-24T14:15:22Z",
    "removedAt": "2019-08-24T14:15:22Z",
    "charges": [ … ],
    "totalCost": 0,
    "driverName": "string",
    "driverPhone": "string",
    "truckNumber": "string",
    "trailerNumber": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}

Rebook a TONU load

Request

Create a new load to replace a TONU'd load.

Use case

After a carrier reports TONU, use this to create a replacement load that can be assigned to a new carrier.

What happens

  • New Load is created with same stops
  • Original load remains in TONU status
  • New load is ready for carrier assignment
Security
BearerAuth
Path
idstringrequired

Resource ID (UUID) or client key

Example: 550e8400-e29b-41d4-a716-446655440000
Query
bystring

Specify lookup type for faster retrieval. If omitted, defaults to looking up by ID first, then falls back to client key if not found. Use by=key when you know you're providing a client key for best performance.

Enum"id""key"
Example: by=key
curl -i -X POST \
  'https://api.mvmnt.io/v1/loads/550e8400-e29b-41d4-a716-446655440000/rebook?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Load rebooked successfully

Bodyapplication/json
originalLoadIdstring(uuid)required
newLoadIdstring(uuid)required
newLoadKeystring or null
Response
application/json
{
  "originalLoadId": "550e8400-e29b-41d4-a716-446655440000",
  "newLoadId": "660e8400-e29b-41d4-a716-446655440001",
  "newLoadKey": "LD-12346"
}

Get load carrier

Request

Retrieve a specific carrier assignment for a load.

Security
BearerAuth
Path
loadIdstringrequired

Load ID

carrierIdstringrequired

LoadCarrier ID

curl -i -X GET \
  'https://api.mvmnt.io/v1/loads/{loadId}/carriers/{carrierId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Load carrier retrieved

Bodyapplication/json
idstring(uuid)
carrierobject(CarrierReference)

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

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

contactobject
statusstring(LoadCarrierStatus)

Status of the carrier assignment.

  • ACTIVE: Carrier is actively assigned
  • TONU: Truck Ordered Not Used (carrier dispatched but cancelled)
  • BOUNCED: Carrier bounced/rejected load
Enum"ACTIVE""TONU""BOUNCED"
billingStatusstring(LoadBillingStatus)

Billing status for the load (AP side).

  • AWAITING_INVOICE: Waiting for carrier invoice
  • INVOICE_IN_REVIEW: Invoice received, under review
  • APPROVED_TO_PAY: Approved for payment
  • PAID: Paid to carrier
Enum"AWAITING_INVOICE""INVOICE_IN_REVIEW""APPROVED_TO_PAY""PAID"
bookedAtstring or null(date-time)
dispatchedAtstring or null(date-time)
removedAtstring or null(date-time)

When this assignment was removed from the load (bounce, TONU, rebook). Removed assignments stay in carriers as history but their charges are excluded from the load totalCost.

chargesArray of objects(LoadCarrierCharge)

Flattened charges array

totalCostnumber or null

Sum of all charges

driverNamestring or null
driverPhonestring or null
truckNumberstring or null
trailerNumberstring or null
createdAtstring(date-time)
updatedAtstring or null(date-time)
Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "carrier": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-CARRIER-SWIFT",
    "name": "Swift Transportation",
    "phoneNumber": "+1-555-987-6543",
    "email": "dispatch@swifttrans.com",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z",
    "deletedAt": null
  },
  "contact": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "phone": "string",
    "email": "string"
  },
  "status": "ACTIVE",
  "billingStatus": "AWAITING_INVOICE",
  "bookedAt": "2019-08-24T14:15:22Z",
  "dispatchedAt": "2019-08-24T14:15:22Z",
  "removedAt": "2019-08-24T14:15:22Z",
  "charges": [
    { … }
  ],
  "totalCost": 0,
  "driverName": "string",
  "driverPhone": "string",
  "truckNumber": "string",
  "trailerNumber": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Update load carrier

Request

Update carrier assignment details.

Use this to update driver info, truck/trailer numbers, or contact.

Security
BearerAuth
Path
loadIdstringrequired
carrierIdstringrequired
Bodyapplication/jsonrequired
contactobject(ResourceReferenceInput)
One of:

Reference to another resource by either ID or client key (used in create/update requests)

driverNamestring or null
driverPhonestring or null
truckNumberstring or null
trailerNumberstring or null
curl -i -X PATCH \
  'https://api.mvmnt.io/v1/loads/{loadId}/carriers/{carrierId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "driverName": "Jane Doe",
    "driverPhone": "+15559876543",
    "truckNumber": "TRK-123",
    "trailerNumber": "TRL-456"
  }'

Responses

Load carrier updated

Bodyapplication/json
idstring(uuid)
carrierobject(CarrierReference)

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

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

contactobject
statusstring(LoadCarrierStatus)

Status of the carrier assignment.

  • ACTIVE: Carrier is actively assigned
  • TONU: Truck Ordered Not Used (carrier dispatched but cancelled)
  • BOUNCED: Carrier bounced/rejected load
Enum"ACTIVE""TONU""BOUNCED"
billingStatusstring(LoadBillingStatus)

Billing status for the load (AP side).

  • AWAITING_INVOICE: Waiting for carrier invoice
  • INVOICE_IN_REVIEW: Invoice received, under review
  • APPROVED_TO_PAY: Approved for payment
  • PAID: Paid to carrier
Enum"AWAITING_INVOICE""INVOICE_IN_REVIEW""APPROVED_TO_PAY""PAID"
bookedAtstring or null(date-time)
dispatchedAtstring or null(date-time)
removedAtstring or null(date-time)

When this assignment was removed from the load (bounce, TONU, rebook). Removed assignments stay in carriers as history but their charges are excluded from the load totalCost.

chargesArray of objects(LoadCarrierCharge)

Flattened charges array

totalCostnumber or null

Sum of all charges

driverNamestring or null
driverPhonestring or null
truckNumberstring or null
trailerNumberstring or null
createdAtstring(date-time)
updatedAtstring or null(date-time)
Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "carrier": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-CARRIER-SWIFT",
    "name": "Swift Transportation",
    "phoneNumber": "+1-555-987-6543",
    "email": "dispatch@swifttrans.com",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z",
    "deletedAt": null
  },
  "contact": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "phone": "string",
    "email": "string"
  },
  "status": "ACTIVE",
  "billingStatus": "AWAITING_INVOICE",
  "bookedAt": "2019-08-24T14:15:22Z",
  "dispatchedAt": "2019-08-24T14:15:22Z",
  "removedAt": "2019-08-24T14:15:22Z",
  "charges": [
    { … }
  ],
  "totalCost": 0,
  "driverName": "string",
  "driverPhone": "string",
  "truckNumber": "string",
  "trailerNumber": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Bounce carrier

Request

Mark carrier as bounced (rejected load without payment).

What happens

  • LoadCarrier status changes to BOUNCED
  • Carrier is removed from active execution
  • No payment is recorded

When to use

Use bounce when carrier rejects the load before dispatch, or fails to show up without prior notice.

For carriers who were dispatched but cancelled, use TONU instead.

Security
BearerAuth
Path
loadIdstringrequired
carrierIdstringrequired
Bodyapplication/json
reasonstring(LoadCarrierRemovalReason)

Reason for removing a carrier from a load. Whether the removal counts as a bounce or a TONU is the removal type, tracked separately.

Enum"CAN_NO_LONGER_TAKE_LOAD""LOAD_GIVEN_BACK""RATE_CON_REJECTED""CUSTOMER_NOT_READY_FOR_PU""CONSIGNEE_NOT_READY_FOR_DEL""FORGOT_TO_BOUNCE_CARRIER""OTHER"
reasonTextstring<= 1000 characters

Additional reason details

curl -i -X POST \
  'https://api.mvmnt.io/v1/loads/{loadId}/carriers/{carrierId}/bounce' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "reason": "CAN_NO_LONGER_TAKE_LOAD",
    "reasonText": "Driver did not show up at scheduled time"
  }'

Responses

Carrier bounced successfully

Bodyapplication/json
idstring(uuid)
carrierobject(CarrierReference)

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

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

contactobject
statusstring(LoadCarrierStatus)

Status of the carrier assignment.

  • ACTIVE: Carrier is actively assigned
  • TONU: Truck Ordered Not Used (carrier dispatched but cancelled)
  • BOUNCED: Carrier bounced/rejected load
Enum"ACTIVE""TONU""BOUNCED"
billingStatusstring(LoadBillingStatus)

Billing status for the load (AP side).

  • AWAITING_INVOICE: Waiting for carrier invoice
  • INVOICE_IN_REVIEW: Invoice received, under review
  • APPROVED_TO_PAY: Approved for payment
  • PAID: Paid to carrier
Enum"AWAITING_INVOICE""INVOICE_IN_REVIEW""APPROVED_TO_PAY""PAID"
bookedAtstring or null(date-time)
dispatchedAtstring or null(date-time)
removedAtstring or null(date-time)

When this assignment was removed from the load (bounce, TONU, rebook). Removed assignments stay in carriers as history but their charges are excluded from the load totalCost.

chargesArray of objects(LoadCarrierCharge)

Flattened charges array

totalCostnumber or null

Sum of all charges

driverNamestring or null
driverPhonestring or null
truckNumberstring or null
trailerNumberstring or null
createdAtstring(date-time)
updatedAtstring or null(date-time)
Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "carrier": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-CARRIER-SWIFT",
    "name": "Swift Transportation",
    "phoneNumber": "+1-555-987-6543",
    "email": "dispatch@swifttrans.com",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z",
    "deletedAt": null
  },
  "contact": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "phone": "string",
    "email": "string"
  },
  "status": "ACTIVE",
  "billingStatus": "AWAITING_INVOICE",
  "bookedAt": "2019-08-24T14:15:22Z",
  "dispatchedAt": "2019-08-24T14:15:22Z",
  "removedAt": "2019-08-24T14:15:22Z",
  "charges": [
    { … }
  ],
  "totalCost": 0,
  "driverName": "string",
  "driverPhone": "string",
  "truckNumber": "string",
  "trailerNumber": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Report TONU

Request

Report Truck Ordered Not Used (TONU).

What happens

  • LoadCarrier status changes to TONU
  • TONU costs are recorded if provided
  • Optionally creates a replacement load

When to use

Use TONU when:

  • Carrier was dispatched but load was cancelled
  • Carrier arrived but freight wasn't ready
  • Carrier was turned away at shipper

TONU typically involves some payment to the carrier.

Security
BearerAuth
Path
loadIdstringrequired
carrierIdstringrequired
Bodyapplication/json
reasonstring<= 1000 characters

Reason for TONU

costsArray of objects

TONU costs to record

createReplacementLoadboolean

Whether to create a replacement load

Default false
curl -i -X POST \
  'https://api.mvmnt.io/v1/loads/{loadId}/carriers/{carrierId}/tonu' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "reason": "Freight not ready at shipper",
    "costs": [
      {
        "chargeCode": {
          "key": "TONU"
        },
        "amount": 250,
        "description": "TONU fee"
      }
    ],
    "createReplacementLoad": true
  }'

Responses

TONU reported successfully

Bodyapplication/json
loadCarrierobject(LoadCarrier)
replacementLoadIdstring or null(uuid)

New load ID if replacement was requested

Response
application/json
{
  "loadCarrier": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "carrier": { … },
    "contact": { … },
    "status": "ACTIVE",
    "billingStatus": "AWAITING_INVOICE",
    "bookedAt": "2019-08-24T14:15:22Z",
    "dispatchedAt": "2019-08-24T14:15:22Z",
    "removedAt": "2019-08-24T14:15:22Z",
    "charges": [ … ],
    "totalCost": 0,
    "driverName": "string",
    "driverPhone": "string",
    "truckNumber": "string",
    "trailerNumber": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  },
  "replacementLoadId": "08109b74-00a2-4d00-91a7-576db2a57194"
}

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