Skip to content
/Users

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/

Companies

Operations

Carrier Contacts

Operations

Carriers

Operations

Carrier Factors

Operations

Carrier Payment Methods

Operations

Customer Contacts

Operations

Customers

Operations

Locations

Operations

Location Contacts

Operations

Payment Terms

Operations

Teams

Operations

Users

Operations

Filter users

Request

Filter users using comprehensive query criteria with AND/OR logic and multiple operators. Supports complex filtering similar to GraphQL capabilities. Note: Soft-deleted users are excluded by default (deletedAt defaults to { isNull: true }).

Security
BearerAuth
Bodyapplication/jsonrequired
filterobject(UserFilter)
Example: {"and":[{"status":{"equalTo":"ACTIVE"}},{"roles":{"contains":"CUSTOMER_REP"}},{"email":{"includes":"@example.com"}}]}
pageSizeinteger[ 1 .. 250 ]

Number of results per page

Default 50
Example: 50
cursorstring

Pagination cursor for next page

curl -i -X POST \
  https://docs.mvmnt.io/_mock/apis/openapi/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
  }'

Responses

Successful response

Bodyapplication/json
dataArray of objects(User)
paginationobject(PaginationInfo)
Response
application/json
{
  "data": [
    { … }
  ],
  "pagination": {
    "pageSize": 50,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "endCursor": "eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9"
  }
}

Create user

Request

Create a new user in your organization

Security
BearerAuth
Bodyapplication/jsonrequired
emailstring(email)required

User's email address (required)

Example: "john.doe@example.com"
namestring

User's full name

Example: "John Doe"
phonestring

User's phone number

Example: "+1-555-123-4567"
phoneExtstring

Phone extension

Example: "123"
statusstring(UserStatus)required
Enum"PENDING""ACTIVE""INACTIVE"
rolesArray of strings(UserRole)non-emptyrequired

User's roles within the organization (required)

Items Enum"CUSTOMER_REP""CARRIER_REP""AR_AP""COMPLIANCE""ADMIN"
Example: ["CUSTOMER_REP"]
keystring<= 512 characters

Client-defined reference identifier

Example: "ERP-USER-12345"
datUsernamestring

DAT (Load Board) integration username

Example: "johndoe_dat"
mcpUsernamestring

MyCarrierPortal integration username

Example: "johndoe_mcp"
avatarIdstring(uuid)

Profile avatar document ID

Example: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
teamsArray of objects(ResourceReferenceInput)

Teams to add this user to

Example: [{"id":"123e4567-e89b-12d3-a456-426614174000"},{"key":"TEAM-WEST-COAST"}]
curl -i -X POST \
  https://docs.mvmnt.io/_mock/apis/openapi/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"
      }
    ]
  }'

Responses

User created successfully

Bodyapplication/json
objectstringread-only

Object type identifier

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

Unique user identifier

Example: "550e8400-e29b-41d4-a716-446655440000"
emailstring(email)required

User's email address

Example: "john.doe@example.com"
namestring or null

User's full name

Example: "John Doe"
phonestring or null

User's phone number

Example: "+1-555-123-4567"
phoneExtstring or null

Phone extension

Example: "123"
statusstring(UserStatus)required
Enum"PENDING""ACTIVE""INACTIVE"
rolesArray of strings(UserRole)required

User's roles within the organization

Items Enum"CUSTOMER_REP""CARRIER_REP""AR_AP""COMPLIANCE""ADMIN"
Example: ["CUSTOMER_REP","ADMIN"]
keystring or null<= 512 characters

Client-defined reference identifier for this user

Example: "ERP-USER-12345"
datUsernamestring or null

DAT (Load Board) integration username

Example: "johndoe_dat"
mcpUsernamestring or null

MyCarrierPortal integration username

Example: "johndoe_mcp"
avatarIdstring or null(uuid)

Profile avatar document ID

Example: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
teamsArray of objects(TeamReference)

Teams this user belongs to

createdAtstring(date-time)read-onlyrequired

Timestamp when user was created

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

Timestamp when user was last updated

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

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

Example: null
Response
application/json
{
  "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
}

Get user

Request

Retrieve a user by ID or client key

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/users/550e8400-e29b-41d4-a716-446655440000?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Successful response

Bodyapplication/json
objectstringread-only

Object type identifier

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

Unique user identifier

Example: "550e8400-e29b-41d4-a716-446655440000"
emailstring(email)required

User's email address

Example: "john.doe@example.com"
namestring or null

User's full name

Example: "John Doe"
phonestring or null

User's phone number

Example: "+1-555-123-4567"
phoneExtstring or null

Phone extension

Example: "123"
statusstring(UserStatus)required
Enum"PENDING""ACTIVE""INACTIVE"
rolesArray of strings(UserRole)required

User's roles within the organization

Items Enum"CUSTOMER_REP""CARRIER_REP""AR_AP""COMPLIANCE""ADMIN"
Example: ["CUSTOMER_REP","ADMIN"]
keystring or null<= 512 characters

Client-defined reference identifier for this user

Example: "ERP-USER-12345"
datUsernamestring or null

DAT (Load Board) integration username

Example: "johndoe_dat"
mcpUsernamestring or null

MyCarrierPortal integration username

Example: "johndoe_mcp"
avatarIdstring or null(uuid)

Profile avatar document ID

Example: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
teamsArray of objects(TeamReference)

Teams this user belongs to

createdAtstring(date-time)read-onlyrequired

Timestamp when user was created

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

Timestamp when user was last updated

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

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

Example: null
Response
application/json
{
  "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
}

Update user

Request

Partially update a user. Only provided fields will be updated.

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
emailstring(email)

User's email address

Example: "john.doe@example.com"
namestring or null

User's full name

Example: "John Doe"
phonestring or null

User's phone number

Example: "+1-555-123-4567"
phoneExtstring or null

Phone extension

Example: "123"
statusstring(UserStatus)
Enum"PENDING""ACTIVE""INACTIVE"
rolesArray of strings(UserRole)non-empty

User's roles (replaces all existing roles)

Items Enum"CUSTOMER_REP""CARRIER_REP""AR_AP""COMPLIANCE""ADMIN"
Example: ["CUSTOMER_REP","ADMIN"]
keystring or null<= 512 characters

Client-defined reference identifier

Example: "ERP-USER-12345"
datUsernamestring or null

DAT integration username

Example: "johndoe_dat"
mcpUsernamestring or null

MyCarrierPortal integration username

Example: "johndoe_mcp"
avatarIdstring or null(uuid)

Profile avatar document ID

Example: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
teamsArray of objects(ResourceReferenceInput)

Teams this user belongs to (replaces all existing team memberships)

Example: [{"id":"123e4567-e89b-12d3-a456-426614174000"},{"key":"TEAM-WEST-COAST"}]
curl -i -X PATCH \
  'https://docs.mvmnt.io/_mock/apis/openapi/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"
      }
    ]
  }'

Responses

User updated successfully

Bodyapplication/json
objectstringread-only

Object type identifier

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

Unique user identifier

Example: "550e8400-e29b-41d4-a716-446655440000"
emailstring(email)required

User's email address

Example: "john.doe@example.com"
namestring or null

User's full name

Example: "John Doe"
phonestring or null

User's phone number

Example: "+1-555-123-4567"
phoneExtstring or null

Phone extension

Example: "123"
statusstring(UserStatus)required
Enum"PENDING""ACTIVE""INACTIVE"
rolesArray of strings(UserRole)required

User's roles within the organization

Items Enum"CUSTOMER_REP""CARRIER_REP""AR_AP""COMPLIANCE""ADMIN"
Example: ["CUSTOMER_REP","ADMIN"]
keystring or null<= 512 characters

Client-defined reference identifier for this user

Example: "ERP-USER-12345"
datUsernamestring or null

DAT (Load Board) integration username

Example: "johndoe_dat"
mcpUsernamestring or null

MyCarrierPortal integration username

Example: "johndoe_mcp"
avatarIdstring or null(uuid)

Profile avatar document ID

Example: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
teamsArray of objects(TeamReference)

Teams this user belongs to

createdAtstring(date-time)read-onlyrequired

Timestamp when user was created

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

Timestamp when user was last updated

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

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

Example: null
Response
application/json
{
  "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
}

Delete user

Request

Soft delete a user (sets deletedAt timestamp)

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/users/550e8400-e29b-41d4-a716-446655440000?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

User deleted successfully

Response
No content

Search users

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 performance
  • full: Returns complete user objects with all relationships
Security
BearerAuth
Bodyapplication/jsonrequired
criteriaobject(UserSearchCriteria)
paginationobject(SearchPaginationInput)
sortArray of objects(SearchSortOption)<= 3 items

Sort options for the search results

Example: [{"field":"createdAt","order":"desc"}]
savedSearchobject(SavedSearchLookup)
formatstring

Response format:

  • flat: Returns only indexed fields (default, faster)
  • full: Returns complete user objects
Default "flat"
Enum"flat""full"
curl -i -X POST \
  https://docs.mvmnt.io/_mock/apis/openapi/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"
  }'

Responses

Successful search results

Bodyapplication/json
dataArray of objectsrequired

Search results - either flat rows or full user objects based on format parameter

data[].​objectstringrequired

Object type identifier for discriminating between flat and full response formats

Value"USER_SEARCH_ROW"
Discriminator
data[].​idstring(uuid)required
data[].​namestringrequired
data[].​emailstring(email)required
data[].​emailVerifiedbooleanrequired

Whether email is verified

data[].​phonestring or null
data[].​statusstringrequired
Enum"pending""active""inactive"
data[].​rolesArray of strings

User roles

data[].​visibilitystring or null
Enum"ALL""LIMITED"
data[].​teamIdsArray of strings(uuid)

Team IDs (maps from groupIds)

data[].​teamNamesArray of strings

Team names (maps from groupNames)

data[].​customersCountintegerrequired

Number of customers (maps from shippersCount)

data[].​quotesCountinteger or null
data[].​quotesWoninteger or null
data[].​quoteWinRatenumber or null(float)

Win rate percentage

data[].​ordersCountintegerrequired

Number of shipments

data[].​ordersTotalRevenuenumber(float)required

Total shipment revenue

data[].​ordersTotalTransportationCostnumber(float)required

Total transportation cost

data[].​ordersTotalGrossProfitnumber(float)required

Total gross profit

data[].​averageGrossProfitPerOrdernumber or null(float)

Average gross profit per shipment

data[].​carriersCountintegerrequired

Number of carriers

data[].​createdAtstring(date-time)required
data[].​lastInvitedAtstring or null(date-time)
paginationobject(SearchPaginationInfo)required
pagination.​pageNumberintegerrequired

Current page number

Example: 1
pagination.​pageSizeintegerrequired

Number of results returned on this page

Example: 50
pagination.​totalPagesintegerrequired

Total number of pages available

Example: 25
totalResultsinteger>= 0required

Total number of matching results (excluding soft-deleted records)

Response
application/json
{
  "data": [
    { … }
  ],
  "pagination": {
    "pageNumber": 1,
    "pageSize": 50,
    "totalPages": 25
  },
  "totalResults": 0
}

Vendors

Operations

Vendor Contacts

Operations

Vendor Payment Methods

Operations

Saved Searches

Operations

Event Notifications

Webhooks