Carrier management operations
- Create a document
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.
OAuth 2.0 client credentials flow. See Authentication Guide for details.
Headers:
Content-Type: application/x-www-form-urlencodedBody Parameters:
grant_type=client_credentials
client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRETcurl -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"Status: 200 OK
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600
}Response Fields:
access_token: JWT Bearer token to use for API requeststoken_type: AlwaysBearerexpires_in: Token lifetime in seconds (3600 = 1 hour)
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.
Request
Search for documents using filter criteria.
Documents are typically associated with other entities (orders, loads, services). Use filters to find documents by type, status, or date range.
- 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" } } }
- Productionhttps://api.mvmnt.io/v1/documents/filter
- Demo (non-production)https://api.demo.mvmnt.io/v1/documents/filter
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
https://api.mvmnt.io/v1/documents/filter \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"filter": {
"type": {
"equalTo": "INVOICE"
}
},
"pageSize": 50
}'Documents matching filter criteria
Unique identifier for the document
Client-defined key for external reference
Type of document.
Common types:
INVOICE: Customer invoiceBILL_OF_LADING: Bill of lading documentRATE_CON: Rate confirmationPROOF_OF_DELIVERY: Proof of delivery (POD)CERTIFICATE_OF_INSURANCE: Certificate of insurance (COI)W9: W-9 tax formCARRIER_INVOICE: Carrier invoice/billLUMPER_RECEIPT: Lumper receiptDETENTION: Detention documentationDELIVERY_ORDER: Delivery orderLOAD_TENDER: Load tenderHOUSE_AIRWAY_BILL: House airway bill (HAWB)MASTER_AIRWAY_BILL: Master airway bill (MAWB)QUOTE: Quote documentOTHER: Other document type
The remaining values mirror the document types available in the MVMNT TMS UI (carrier compliance, air freight, customer agreements, receipts, alerts, and branding assets).
Values outside this list are rejected with 400. Documents created internally with other types are returned as OTHER.
Upload status of the document.
PENDING_UPLOAD: Document record created, file not yet uploadedUPLOADED: File has been uploaded to storage
Pre-signed URL for uploading the file. Only present immediately after document creation. Expires after 15 minutes.
Pre-signed URL for downloading the file. Present when document status is UPLOADED. Expires after 1 hour.
Arbitrary key-value tags for the document
{ "data": [ { … } ], "pagination": { "pageSize": 50, "hasNextPage": true, "hasPreviousPage": false, "endCursor": "eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9" } }
Request
Create a new document record and receive a pre-signed URL for uploading the file.
- Call this endpoint with document metadata (type, fileName, contentType)
- Receive the created document with an
uploadUrl - Upload the file directly to S3 using the
uploadUrl(PUT request) - Document status changes from
PENDING_UPLOADtoUPLOADEDautomatically
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
uploadUrlexpires after 15 minutes - Use the exact
contentTypespecified in the request - Maximum file size: 100MB
Optional client-defined key for external reference
Type of document.
Common types:
INVOICE: Customer invoiceBILL_OF_LADING: Bill of lading documentRATE_CON: Rate confirmationPROOF_OF_DELIVERY: Proof of delivery (POD)CERTIFICATE_OF_INSURANCE: Certificate of insurance (COI)W9: W-9 tax formCARRIER_INVOICE: Carrier invoice/billLUMPER_RECEIPT: Lumper receiptDETENTION: Detention documentationDELIVERY_ORDER: Delivery orderLOAD_TENDER: Load tenderHOUSE_AIRWAY_BILL: House airway bill (HAWB)MASTER_AIRWAY_BILL: Master airway bill (MAWB)QUOTE: Quote documentOTHER: Other document type
The remaining values mirror the document types available in the MVMNT TMS UI (carrier compliance, air freight, customer agreements, receipts, alerts, and branding assets).
Values outside this list are rejected with 400. Documents created internally with other types are returned as OTHER.
File name (including extension)
- Productionhttps://api.mvmnt.io/v1/documents
- Demo (non-production)https://api.demo.mvmnt.io/v1/documents
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
https://api.mvmnt.io/v1/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"
}
}'Document created successfully
Unique identifier for the document
Client-defined key for external reference
Type of document.
Common types:
INVOICE: Customer invoiceBILL_OF_LADING: Bill of lading documentRATE_CON: Rate confirmationPROOF_OF_DELIVERY: Proof of delivery (POD)CERTIFICATE_OF_INSURANCE: Certificate of insurance (COI)W9: W-9 tax formCARRIER_INVOICE: Carrier invoice/billLUMPER_RECEIPT: Lumper receiptDETENTION: Detention documentationDELIVERY_ORDER: Delivery orderLOAD_TENDER: Load tenderHOUSE_AIRWAY_BILL: House airway bill (HAWB)MASTER_AIRWAY_BILL: Master airway bill (MAWB)QUOTE: Quote documentOTHER: Other document type
The remaining values mirror the document types available in the MVMNT TMS UI (carrier compliance, air freight, customer agreements, receipts, alerts, and branding assets).
Values outside this list are rejected with 400. Documents created internally with other types are returned as OTHER.
Upload status of the document.
PENDING_UPLOAD: Document record created, file not yet uploadedUPLOADED: File has been uploaded to storage
Pre-signed URL for uploading the file. Only present immediately after document creation. Expires after 15 minutes.
Pre-signed URL for downloading the file. Present when document status is UPLOADED. Expires after 1 hour.
Arbitrary key-value tags for the document
{ "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 }
- Productionhttps://api.mvmnt.io/v1/documents/{id}
- Demo (non-production)https://api.demo.mvmnt.io/v1/documents/{id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://api.mvmnt.io/v1/documents/550e8400-e29b-41d4-a716-446655440000?by=key' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'Document retrieved successfully
Unique identifier for the document
Client-defined key for external reference
Type of document.
Common types:
INVOICE: Customer invoiceBILL_OF_LADING: Bill of lading documentRATE_CON: Rate confirmationPROOF_OF_DELIVERY: Proof of delivery (POD)CERTIFICATE_OF_INSURANCE: Certificate of insurance (COI)W9: W-9 tax formCARRIER_INVOICE: Carrier invoice/billLUMPER_RECEIPT: Lumper receiptDETENTION: Detention documentationDELIVERY_ORDER: Delivery orderLOAD_TENDER: Load tenderHOUSE_AIRWAY_BILL: House airway bill (HAWB)MASTER_AIRWAY_BILL: Master airway bill (MAWB)QUOTE: Quote documentOTHER: Other document type
The remaining values mirror the document types available in the MVMNT TMS UI (carrier compliance, air freight, customer agreements, receipts, alerts, and branding assets).
Values outside this list are rejected with 400. Documents created internally with other types are returned as OTHER.
Upload status of the document.
PENDING_UPLOAD: Document record created, file not yet uploadedUPLOADED: File has been uploaded to storage
Pre-signed URL for uploading the file. Only present immediately after document creation. Expires after 15 minutes.
Pre-signed URL for downloading the file. Present when document status is UPLOADED. Expires after 1 hour.
Arbitrary key-value tags for the document
{ "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" }
Type of document.
Common types:
INVOICE: Customer invoiceBILL_OF_LADING: Bill of lading documentRATE_CON: Rate confirmationPROOF_OF_DELIVERY: Proof of delivery (POD)CERTIFICATE_OF_INSURANCE: Certificate of insurance (COI)W9: W-9 tax formCARRIER_INVOICE: Carrier invoice/billLUMPER_RECEIPT: Lumper receiptDETENTION: Detention documentationDELIVERY_ORDER: Delivery orderLOAD_TENDER: Load tenderHOUSE_AIRWAY_BILL: House airway bill (HAWB)MASTER_AIRWAY_BILL: Master airway bill (MAWB)QUOTE: Quote documentOTHER: Other document type
The remaining values mirror the document types available in the MVMNT TMS UI (carrier compliance, air freight, customer agreements, receipts, alerts, and branding assets).
Values outside this list are rejected with 400. Documents created internally with other types are returned as OTHER.
- Productionhttps://api.mvmnt.io/v1/documents/{id}
- Demo (non-production)https://api.demo.mvmnt.io/v1/documents/{id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X PATCH \
'https://api.mvmnt.io/v1/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
}
}'Document updated successfully
Unique identifier for the document
Client-defined key for external reference
Type of document.
Common types:
INVOICE: Customer invoiceBILL_OF_LADING: Bill of lading documentRATE_CON: Rate confirmationPROOF_OF_DELIVERY: Proof of delivery (POD)CERTIFICATE_OF_INSURANCE: Certificate of insurance (COI)W9: W-9 tax formCARRIER_INVOICE: Carrier invoice/billLUMPER_RECEIPT: Lumper receiptDETENTION: Detention documentationDELIVERY_ORDER: Delivery orderLOAD_TENDER: Load tenderHOUSE_AIRWAY_BILL: House airway bill (HAWB)MASTER_AIRWAY_BILL: Master airway bill (MAWB)QUOTE: Quote documentOTHER: Other document type
The remaining values mirror the document types available in the MVMNT TMS UI (carrier compliance, air freight, customer agreements, receipts, alerts, and branding assets).
Values outside this list are rejected with 400. Documents created internally with other types are returned as OTHER.
Upload status of the document.
PENDING_UPLOAD: Document record created, file not yet uploadedUPLOADED: File has been uploaded to storage
Pre-signed URL for uploading the file. Only present immediately after document creation. Expires after 15 minutes.
Pre-signed URL for downloading the file. Present when document status is UPLOADED. Expires after 1 hour.
Arbitrary key-value tags for the document
{ "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" }
- Productionhttps://api.mvmnt.io/v1/documents/{id}
- Demo (non-production)https://api.demo.mvmnt.io/v1/documents/{id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X DELETE \
'https://api.mvmnt.io/v1/documents/550e8400-e29b-41d4-a716-446655440000?by=key' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'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.