Carrier management operations
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.
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.
Filter criteria (optional - omit to return all users). Note: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.
- Productionhttps://api.mvmnt.io/v1/users/filter
- Demo (non-production)https://api.demo.mvmnt.io/v1/users/filter
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
https://api.mvmnt.io/v1/users/filter \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"filter": {
"and": [
{
"status": {
"equalTo": "ACTIVE"
}
},
{
"roles": {
"contains": "CUSTOMER_REP"
}
},
{
"email": {
"includes": "@example.com"
}
}
]
},
"pageSize": 50
}'{ "data": [ { … } ], "pagination": { "pageSize": 50, "hasNextPage": true, "hasPreviousPage": false, "endCursor": "eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9" } }
User account status:
PENDING: User invited but has not completed onboardingACTIVE: User account is active and can access the systemINACTIVE: User account is deactivated
User's roles within the organization (required)
- Productionhttps://api.mvmnt.io/v1/users
- Demo (non-production)https://api.demo.mvmnt.io/v1/users
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
https://api.mvmnt.io/v1/users \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"email": "john.doe@example.com",
"name": "John Doe",
"phone": "+1-555-123-4567",
"phoneExt": "123",
"status": "PENDING",
"roles": [
"CUSTOMER_REP"
],
"key": "ERP-USER-12345",
"datUsername": "johndoe_dat",
"mcpUsername": "johndoe_mcp",
"avatarId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"teams": [
{
"id": "123e4567-e89b-12d3-a456-426614174000"
},
{
"key": "TEAM-WEST-COAST"
}
]
}'User created successfully
Unique user identifier
User account status:
PENDING: User invited but has not completed onboardingACTIVE: User account is active and can access the systemINACTIVE: User account is deactivated
User's roles within the organization
Client-defined reference identifier for this user
Profile avatar document ID
Timestamp when user was created
Timestamp when user was last updated
{ "object": "USER", "id": "550e8400-e29b-41d4-a716-446655440000", "email": "john.doe@example.com", "name": "John Doe", "phone": "+1-555-123-4567", "phoneExt": "123", "status": "PENDING", "roles": [ "CUSTOMER_REP", "ADMIN" ], "key": "ERP-USER-12345", "datUsername": "johndoe_dat", "mcpUsername": "johndoe_mcp", "avatarId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "teams": [ { … } ], "createdAt": "2025-01-15T10:00:00Z", "updatedAt": "2025-01-15T14:30:00Z", "deletedAt": null }
- Productionhttps://api.mvmnt.io/v1/users/{id}
- Demo (non-production)https://api.demo.mvmnt.io/v1/users/{id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://api.mvmnt.io/v1/users/550e8400-e29b-41d4-a716-446655440000?by=key' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'Successful response
Unique user identifier
User account status:
PENDING: User invited but has not completed onboardingACTIVE: User account is active and can access the systemINACTIVE: User account is deactivated
User's roles within the organization
Client-defined reference identifier for this user
Profile avatar document ID
Timestamp when user was created
Timestamp when user was last updated
{ "object": "USER", "id": "550e8400-e29b-41d4-a716-446655440000", "email": "john.doe@example.com", "name": "John Doe", "phone": "+1-555-123-4567", "phoneExt": "123", "status": "PENDING", "roles": [ "CUSTOMER_REP", "ADMIN" ], "key": "ERP-USER-12345", "datUsername": "johndoe_dat", "mcpUsername": "johndoe_mcp", "avatarId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "teams": [ { … } ], "createdAt": "2025-01-15T10:00:00Z", "updatedAt": "2025-01-15T14:30:00Z", "deletedAt": null }
User account status:
PENDING: User invited but has not completed onboardingACTIVE: User account is active and can access the systemINACTIVE: User account is deactivated
User's roles (replaces all existing roles)
Profile avatar document ID
- Productionhttps://api.mvmnt.io/v1/users/{id}
- Demo (non-production)https://api.demo.mvmnt.io/v1/users/{id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X PATCH \
'https://api.mvmnt.io/v1/users/550e8400-e29b-41d4-a716-446655440000?by=key' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"email": "john.doe@example.com",
"name": "John Doe",
"phone": "+1-555-123-4567",
"phoneExt": "123",
"status": "PENDING",
"roles": [
"CUSTOMER_REP",
"ADMIN"
],
"key": "ERP-USER-12345",
"datUsername": "johndoe_dat",
"mcpUsername": "johndoe_mcp",
"avatarId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"teams": [
{
"id": "123e4567-e89b-12d3-a456-426614174000"
},
{
"key": "TEAM-WEST-COAST"
}
]
}'User updated successfully
Unique user identifier
User account status:
PENDING: User invited but has not completed onboardingACTIVE: User account is active and can access the systemINACTIVE: User account is deactivated
User's roles within the organization
Client-defined reference identifier for this user
Profile avatar document ID
Timestamp when user was created
Timestamp when user was last updated
{ "object": "USER", "id": "550e8400-e29b-41d4-a716-446655440000", "email": "john.doe@example.com", "name": "John Doe", "phone": "+1-555-123-4567", "phoneExt": "123", "status": "PENDING", "roles": [ "CUSTOMER_REP", "ADMIN" ], "key": "ERP-USER-12345", "datUsername": "johndoe_dat", "mcpUsername": "johndoe_mcp", "avatarId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "teams": [ { … } ], "createdAt": "2025-01-15T10:00:00Z", "updatedAt": "2025-01-15T14:30:00Z", "deletedAt": null }
- Productionhttps://api.mvmnt.io/v1/users/{id}
- Demo (non-production)https://api.demo.mvmnt.io/v1/users/{id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X DELETE \
'https://api.mvmnt.io/v1/users/550e8400-e29b-41d4-a716-446655440000?by=key' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'Request
Search users using OpenSearch-powered full-text and field-specific search.
This endpoint provides fast, indexed search across user data with support for:
- Full-text search across multiple fields
- Field-specific filtering with various operators
- Sorting and pagination
- Saved search preferences
Note: Only active (non-deleted) users are searchable. Soft-deleted records are automatically excluded from all search results.
Response Formats:
flat(default): Returns indexed fields only for faster performancefull: Returns complete user objects with all relationships
Sort options for the search results
Optional saved search to load preferences from. When provided, the saved search criteria will be loaded and merged with any explicit criteria.
- Productionhttps://api.mvmnt.io/v1/users/search
- Demo (non-production)https://api.demo.mvmnt.io/v1/users/search
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
https://api.mvmnt.io/v1/users/search \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"criteria": {
"id": {
"operator": "EQUALS",
"values": [
"550e8400-e29b-41d4-a716-446655440000"
]
},
"name": {
"operator": "INCLUDES",
"values": [
"search term"
]
},
"email": {
"operator": "INCLUDES",
"values": [
"search term"
]
},
"emailVerified": {
"operator": "TRUE"
},
"phone": {
"operator": "INCLUDES",
"values": [
"search term"
]
},
"status": {
"operator": "ONE_OF",
"values": [
"ACTIVE",
"PENDING"
]
},
"roles": {
"operator": "ONE_OF",
"values": [
"ACTIVE",
"PENDING"
]
},
"visibility": {
"operator": "ONE_OF",
"values": [
"ACTIVE",
"PENDING"
]
},
"teamIds": {
"operator": "EQUALS",
"values": [
"550e8400-e29b-41d4-a716-446655440000"
]
},
"teamNames": {
"operator": "INCLUDES",
"values": [
"search term"
]
},
"customersCount": {
"operator": "BETWEEN",
"min": 10,
"max": 100
},
"quotesCount": {
"operator": "BETWEEN",
"min": 10,
"max": 100
},
"quotesWon": {
"operator": "BETWEEN",
"min": 10,
"max": 100
},
"quoteWinRate": {
"operator": "GREATER_THAN",
"value": 1000.5
},
"ordersCount": {
"operator": "BETWEEN",
"min": 10,
"max": 100
},
"ordersTotalRevenue": {
"operator": "GREATER_THAN",
"value": 1000.5
},
"ordersTotalTransportationCost": {
"operator": "GREATER_THAN",
"value": 1000.5
},
"ordersTotalGrossProfit": {
"operator": "GREATER_THAN",
"value": 1000.5
},
"averageGrossProfitPerOrder": {
"operator": "GREATER_THAN",
"value": 1000.5
},
"carriersCount": {
"operator": "BETWEEN",
"min": 10,
"max": 100
},
"createdAt": {
"operator": "AFTER",
"value": "2025-01-01T00:00:00Z"
},
"lastInvitedAt": {
"operator": "AFTER",
"value": "2025-01-01T00:00:00Z"
}
},
"pagination": {
"pageNumber": 1,
"pageSize": 50
},
"sort": [
{
"field": "createdAt",
"order": "desc"
}
],
"savedSearch": {
"id": "550e8400-e29b-41d4-a716-446655440000"
},
"format": "flat"
}'{ "data": [ { … } ], "pagination": { "pageNumber": 1, "pageSize": 50, "totalPages": 25 }, "totalResults": 0 }