Skip to content
/Documents

MVMNT API (1.0.0)

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

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)
Download OpenAPI description
openapi.json
openapi.yaml
Overview
URL
https://docs.mvmnt.io
MVMNT Support
support@mvmnt.io
License
Proprietary
Languages
Servers
Mock server
https://docs.mvmnt.io/_mock/apis/openapi
Production
https://api.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

Filter documents

Request

Search for documents using filter criteria.

Usage

Documents are typically associated with other entities (orders, loads, services). Use filters to find documents by type, status, or date range.

Example Filters

  • Find all invoices: { "filter": { "type": { "equalTo": "INVOICE" } } }
  • Find uploaded documents: { "filter": { "status": { "equalTo": "UPLOADED" } } }
  • Find documents created today: { "filter": { "createdAt": { "greaterThanOrEqualTo": "2025-01-15T00:00:00Z" } } }
Security
BearerAuth
Bodyapplication/jsonrequired
filterobject(DocumentFilter)

Filter criteria for documents

pageSizeinteger[ 1 .. 100 ]

Number of results per page

Default 50
cursorstring

Pagination cursor from previous response

curl -i -X POST \
  https://docs.mvmnt.io/_mock/apis/openapi/documents/filter \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": {
      "type": {
        "equalTo": "INVOICE"
      }
    },
    "pageSize": 50
  }'

Responses

Documents matching filter criteria

Bodyapplication/json
dataArray of objects(Document)required
data[].​idstring(uuid)required

Unique identifier for the document

Example: "550e8400-e29b-41d4-a716-446655440000"
data[].​keystring or null<= 512 characters

Client-defined key for external reference

Example: "doc-inv-2025-001"
data[].​typestring(DocumentType)required

Type of document.

Common types:

  • INVOICE: Customer invoice
  • BILL_OF_LADING: Bill of lading document
  • RATE_CON: Rate confirmation
  • PROOF_OF_DELIVERY: Proof of delivery (POD)
  • CERTIFICATE_OF_INSURANCE: Certificate of insurance (COI)
  • W9: W-9 tax form
  • CARRIER_INVOICE: Carrier invoice/bill
  • LUMPER_RECEIPT: Lumper receipt
  • DETENTION: Detention documentation
  • DELIVERY_ORDER: Delivery order
  • LOAD_TENDER: Load tender
  • HOUSE_AIRWAY_BILL: House airway bill (HAWB)
  • MASTER_AIRWAY_BILL: Master airway bill (MAWB)
  • QUOTE: Quote document
  • OTHER: Other document type
Enum"INVOICE""BILL_OF_LADING""RATE_CON""PROOF_OF_DELIVERY""CERTIFICATE_OF_INSURANCE""W9""CARRIER_INVOICE""LUMPER_RECEIPT""DETENTION""DELIVERY_ORDER"
data[].​fileNamestringrequired

Original file name

Example: "invoice-2025-001.pdf"
data[].​extensionstring

File extension (without dot)

Example: "pdf"
data[].​contentTypestringrequired

MIME content type

Example: "application/pdf"
data[].​fileSizeinteger or null

File size in bytes

Example: 102400
data[].​statusstring(DocumentStatus)required

Upload status of the document.

  • PENDING_UPLOAD: Document record created, file not yet uploaded
  • UPLOADED: File has been uploaded to storage
Enum"PENDING_UPLOAD""UPLOADED"
data[].​uploadUrlstring or null(uri)

Pre-signed URL for uploading the file. Only present immediately after document creation. Expires after 15 minutes.

Example: "https://s3.amazonaws.com/bucket/key?signature=..."
data[].​downloadUrlstring or null(uri)

Pre-signed URL for downloading the file. Present when document status is UPLOADED. Expires after 1 hour.

Example: "https://s3.amazonaws.com/bucket/key?signature=..."
data[].​tagsobject or null

Arbitrary key-value tags for the document

Example: {"invoiceNumber":"INV-2025-001","customerPO":"PO-12345"}
data[].​createdAtstring(date-time)required

When the document was created

Example: "2025-01-15T10:30:00Z"
data[].​updatedAtstring or null(date-time)

When the document was last updated

Example: "2025-01-15T10:35:00Z"
paginationobject(PaginationInfo)required
pagination.​pageSizeintegerrequired

Number of items per page

Example: 50
pagination.​hasNextPagebooleanrequired

Whether there are more pages

Example: true
pagination.​hasPreviousPageboolean

Whether there are previous pages

Example: false
pagination.​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"
  }
}

Create a document

Request

Create a new document record and receive a pre-signed URL for uploading the file.

Workflow

  1. Call this endpoint with document metadata (type, fileName, contentType)
  2. Receive the created document with an uploadUrl
  3. Upload the file directly to S3 using the uploadUrl (PUT request)
  4. Document status changes from PENDING_UPLOAD to UPLOADED automatically

Upload Instructions

The uploadUrl is a pre-signed S3 URL. Upload your file with:

curl -X PUT -H "Content-Type: application/pdf" \
  --data-binary @your-file.pdf \
  "https://s3.amazonaws.com/bucket/key?signature=..."

Important:

  • The uploadUrl expires after 15 minutes
  • Use the exact contentType specified in the request
  • Maximum file size: 100MB
Security
BearerAuth
Bodyapplication/jsonrequired
keystring<= 512 characters

Optional client-defined key for external reference

Example: "doc-inv-2025-001"
typestring(DocumentType)required

Type of document.

Common types:

  • INVOICE: Customer invoice
  • BILL_OF_LADING: Bill of lading document
  • RATE_CON: Rate confirmation
  • PROOF_OF_DELIVERY: Proof of delivery (POD)
  • CERTIFICATE_OF_INSURANCE: Certificate of insurance (COI)
  • W9: W-9 tax form
  • CARRIER_INVOICE: Carrier invoice/bill
  • LUMPER_RECEIPT: Lumper receipt
  • DETENTION: Detention documentation
  • DELIVERY_ORDER: Delivery order
  • LOAD_TENDER: Load tender
  • HOUSE_AIRWAY_BILL: House airway bill (HAWB)
  • MASTER_AIRWAY_BILL: Master airway bill (MAWB)
  • QUOTE: Quote document
  • OTHER: Other document type
Enum"INVOICE""BILL_OF_LADING""RATE_CON""PROOF_OF_DELIVERY""CERTIFICATE_OF_INSURANCE""W9""CARRIER_INVOICE""LUMPER_RECEIPT""DETENTION""DELIVERY_ORDER"
fileNamestring[ 1 .. 255 ] charactersrequired

File name (including extension)

Example: "invoice-2025-001.pdf"
contentTypestringrequired

MIME content type of the file

Example: "application/pdf"
fileSizeinteger>= 1

File size in bytes (optional, for validation)

Example: 102400
tagsobject

Optional key-value tags

Example: {"invoiceNumber":"INV-2025-001"}
curl -i -X POST \
  https://docs.mvmnt.io/_mock/apis/openapi/documents \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "INVOICE",
    "fileName": "invoice-2025-001.pdf",
    "contentType": "application/pdf",
    "fileSize": 102400,
    "tags": {
      "invoiceNumber": "INV-2025-001"
    }
  }'

Responses

Document created successfully

Bodyapplication/json
idstring(uuid)required

Unique identifier for the document

Example: "550e8400-e29b-41d4-a716-446655440000"
keystring or null<= 512 characters

Client-defined key for external reference

Example: "doc-inv-2025-001"
typestring(DocumentType)required

Type of document.

Common types:

  • INVOICE: Customer invoice
  • BILL_OF_LADING: Bill of lading document
  • RATE_CON: Rate confirmation
  • PROOF_OF_DELIVERY: Proof of delivery (POD)
  • CERTIFICATE_OF_INSURANCE: Certificate of insurance (COI)
  • W9: W-9 tax form
  • CARRIER_INVOICE: Carrier invoice/bill
  • LUMPER_RECEIPT: Lumper receipt
  • DETENTION: Detention documentation
  • DELIVERY_ORDER: Delivery order
  • LOAD_TENDER: Load tender
  • HOUSE_AIRWAY_BILL: House airway bill (HAWB)
  • MASTER_AIRWAY_BILL: Master airway bill (MAWB)
  • QUOTE: Quote document
  • OTHER: Other document type
Enum"INVOICE""BILL_OF_LADING""RATE_CON""PROOF_OF_DELIVERY""CERTIFICATE_OF_INSURANCE""W9""CARRIER_INVOICE""LUMPER_RECEIPT""DETENTION""DELIVERY_ORDER"
fileNamestringrequired

Original file name

Example: "invoice-2025-001.pdf"
extensionstring

File extension (without dot)

Example: "pdf"
contentTypestringrequired

MIME content type

Example: "application/pdf"
fileSizeinteger or null

File size in bytes

Example: 102400
statusstring(DocumentStatus)required

Upload status of the document.

  • PENDING_UPLOAD: Document record created, file not yet uploaded
  • UPLOADED: File has been uploaded to storage
Enum"PENDING_UPLOAD""UPLOADED"
uploadUrlstring or null(uri)

Pre-signed URL for uploading the file. Only present immediately after document creation. Expires after 15 minutes.

Example: "https://s3.amazonaws.com/bucket/key?signature=..."
downloadUrlstring or null(uri)

Pre-signed URL for downloading the file. Present when document status is UPLOADED. Expires after 1 hour.

Example: "https://s3.amazonaws.com/bucket/key?signature=..."
tagsobject or null

Arbitrary key-value tags for the document

Example: {"invoiceNumber":"INV-2025-001","customerPO":"PO-12345"}
createdAtstring(date-time)required

When the document was created

Example: "2025-01-15T10:30:00Z"
updatedAtstring or null(date-time)

When the document was last updated

Example: "2025-01-15T10:35:00Z"
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "INVOICE",
  "fileName": "invoice-2025-001.pdf",
  "extension": "pdf",
  "contentType": "application/pdf",
  "fileSize": 102400,
  "status": "PENDING_UPLOAD",
  "uploadUrl": "https://s3.amazonaws.com/bucket/key?X-Amz-Signature=...",
  "downloadUrl": null,
  "tags": {
    "invoiceNumber": "INV-2025-001"
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": null
}

Get a document

Request

Retrieve a document by ID or key.

Returns the document metadata including a fresh downloadUrl if the file is uploaded.

Note: The downloadUrl is a pre-signed S3 URL that expires after 1 hour. Each GET request generates a fresh URL.

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://docs.mvmnt.io/_mock/apis/openapi/documents/550e8400-e29b-41d4-a716-446655440000?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Document retrieved successfully

Bodyapplication/json
idstring(uuid)required

Unique identifier for the document

Example: "550e8400-e29b-41d4-a716-446655440000"
keystring or null<= 512 characters

Client-defined key for external reference

Example: "doc-inv-2025-001"
typestring(DocumentType)required

Type of document.

Common types:

  • INVOICE: Customer invoice
  • BILL_OF_LADING: Bill of lading document
  • RATE_CON: Rate confirmation
  • PROOF_OF_DELIVERY: Proof of delivery (POD)
  • CERTIFICATE_OF_INSURANCE: Certificate of insurance (COI)
  • W9: W-9 tax form
  • CARRIER_INVOICE: Carrier invoice/bill
  • LUMPER_RECEIPT: Lumper receipt
  • DETENTION: Detention documentation
  • DELIVERY_ORDER: Delivery order
  • LOAD_TENDER: Load tender
  • HOUSE_AIRWAY_BILL: House airway bill (HAWB)
  • MASTER_AIRWAY_BILL: Master airway bill (MAWB)
  • QUOTE: Quote document
  • OTHER: Other document type
Enum"INVOICE""BILL_OF_LADING""RATE_CON""PROOF_OF_DELIVERY""CERTIFICATE_OF_INSURANCE""W9""CARRIER_INVOICE""LUMPER_RECEIPT""DETENTION""DELIVERY_ORDER"
fileNamestringrequired

Original file name

Example: "invoice-2025-001.pdf"
extensionstring

File extension (without dot)

Example: "pdf"
contentTypestringrequired

MIME content type

Example: "application/pdf"
fileSizeinteger or null

File size in bytes

Example: 102400
statusstring(DocumentStatus)required

Upload status of the document.

  • PENDING_UPLOAD: Document record created, file not yet uploaded
  • UPLOADED: File has been uploaded to storage
Enum"PENDING_UPLOAD""UPLOADED"
uploadUrlstring or null(uri)

Pre-signed URL for uploading the file. Only present immediately after document creation. Expires after 15 minutes.

Example: "https://s3.amazonaws.com/bucket/key?signature=..."
downloadUrlstring or null(uri)

Pre-signed URL for downloading the file. Present when document status is UPLOADED. Expires after 1 hour.

Example: "https://s3.amazonaws.com/bucket/key?signature=..."
tagsobject or null

Arbitrary key-value tags for the document

Example: {"invoiceNumber":"INV-2025-001","customerPO":"PO-12345"}
createdAtstring(date-time)required

When the document was created

Example: "2025-01-15T10:30:00Z"
updatedAtstring or null(date-time)

When the document was last updated

Example: "2025-01-15T10:35:00Z"
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "key": "doc-inv-2025-001",
  "type": "INVOICE",
  "fileName": "invoice-2025-001.pdf",
  "extension": "pdf",
  "contentType": "application/pdf",
  "fileSize": 102400,
  "status": "UPLOADED",
  "uploadUrl": null,
  "downloadUrl": "https://s3.amazonaws.com/bucket/key?X-Amz-Signature=...",
  "tags": {
    "invoiceNumber": "INV-2025-001"
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:35:00Z"
}

Update a document

Request

Update document metadata.

Note: File content cannot be changed after upload. To replace a file, create a new document.

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
keystring or null<= 512 characters

Update client-defined key

typestring(DocumentType)

Type of document.

Common types:

  • INVOICE: Customer invoice
  • BILL_OF_LADING: Bill of lading document
  • RATE_CON: Rate confirmation
  • PROOF_OF_DELIVERY: Proof of delivery (POD)
  • CERTIFICATE_OF_INSURANCE: Certificate of insurance (COI)
  • W9: W-9 tax form
  • CARRIER_INVOICE: Carrier invoice/bill
  • LUMPER_RECEIPT: Lumper receipt
  • DETENTION: Detention documentation
  • DELIVERY_ORDER: Delivery order
  • LOAD_TENDER: Load tender
  • HOUSE_AIRWAY_BILL: House airway bill (HAWB)
  • MASTER_AIRWAY_BILL: Master airway bill (MAWB)
  • QUOTE: Quote document
  • OTHER: Other document type
Enum"INVOICE""BILL_OF_LADING""RATE_CON""PROOF_OF_DELIVERY""CERTIFICATE_OF_INSURANCE""W9""CARRIER_INVOICE""LUMPER_RECEIPT""DETENTION""DELIVERY_ORDER"
fileNamestring[ 1 .. 255 ] characters

Update file name

tagsobject or null

Update or clear tags (null to clear)

curl -i -X PATCH \
  'https://docs.mvmnt.io/_mock/apis/openapi/documents/550e8400-e29b-41d4-a716-446655440000?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "tags": {
      "invoiceNumber": "INV-2025-001-REVISED",
      "approved": true
    }
  }'

Responses

Document updated successfully

Bodyapplication/json
idstring(uuid)required

Unique identifier for the document

Example: "550e8400-e29b-41d4-a716-446655440000"
keystring or null<= 512 characters

Client-defined key for external reference

Example: "doc-inv-2025-001"
typestring(DocumentType)required

Type of document.

Common types:

  • INVOICE: Customer invoice
  • BILL_OF_LADING: Bill of lading document
  • RATE_CON: Rate confirmation
  • PROOF_OF_DELIVERY: Proof of delivery (POD)
  • CERTIFICATE_OF_INSURANCE: Certificate of insurance (COI)
  • W9: W-9 tax form
  • CARRIER_INVOICE: Carrier invoice/bill
  • LUMPER_RECEIPT: Lumper receipt
  • DETENTION: Detention documentation
  • DELIVERY_ORDER: Delivery order
  • LOAD_TENDER: Load tender
  • HOUSE_AIRWAY_BILL: House airway bill (HAWB)
  • MASTER_AIRWAY_BILL: Master airway bill (MAWB)
  • QUOTE: Quote document
  • OTHER: Other document type
Enum"INVOICE""BILL_OF_LADING""RATE_CON""PROOF_OF_DELIVERY""CERTIFICATE_OF_INSURANCE""W9""CARRIER_INVOICE""LUMPER_RECEIPT""DETENTION""DELIVERY_ORDER"
fileNamestringrequired

Original file name

Example: "invoice-2025-001.pdf"
extensionstring

File extension (without dot)

Example: "pdf"
contentTypestringrequired

MIME content type

Example: "application/pdf"
fileSizeinteger or null

File size in bytes

Example: 102400
statusstring(DocumentStatus)required

Upload status of the document.

  • PENDING_UPLOAD: Document record created, file not yet uploaded
  • UPLOADED: File has been uploaded to storage
Enum"PENDING_UPLOAD""UPLOADED"
uploadUrlstring or null(uri)

Pre-signed URL for uploading the file. Only present immediately after document creation. Expires after 15 minutes.

Example: "https://s3.amazonaws.com/bucket/key?signature=..."
downloadUrlstring or null(uri)

Pre-signed URL for downloading the file. Present when document status is UPLOADED. Expires after 1 hour.

Example: "https://s3.amazonaws.com/bucket/key?signature=..."
tagsobject or null

Arbitrary key-value tags for the document

Example: {"invoiceNumber":"INV-2025-001","customerPO":"PO-12345"}
createdAtstring(date-time)required

When the document was created

Example: "2025-01-15T10:30:00Z"
updatedAtstring or null(date-time)

When the document was last updated

Example: "2025-01-15T10:35:00Z"
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "key": "doc-inv-2025-001",
  "type": "INVOICE",
  "fileName": "invoice-2025-001.pdf",
  "extension": "pdf",
  "contentType": "application/pdf",
  "fileSize": 102400,
  "status": "PENDING_UPLOAD",
  "uploadUrl": "https://s3.amazonaws.com/bucket/key?signature=...",
  "downloadUrl": "https://s3.amazonaws.com/bucket/key?signature=...",
  "tags": {
    "invoiceNumber": "INV-2025-001",
    "customerPO": "PO-12345"
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:35:00Z"
}

Delete a document

Request

Soft delete a document.

The document record is marked as deleted but not permanently removed. Associated files in S3 may be cleaned up asynchronously.

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://docs.mvmnt.io/_mock/apis/openapi/documents/550e8400-e29b-41d4-a716-446655440000?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Document deleted successfully

Response
No content

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

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