OpenAPI Specification
openapi: 3.1.0
info:
title: MVMNT Bill Payments Users API
version: 1.0.0
description: "The MVMNT API enables you to automate freight brokerage workflows by integrating\ndirectly with our Transportation Management System.\n\n## Authentication\n\nOAuth 2.0 client credentials flow. See [Authentication Guide](/getting-started/authentication)\nfor details.\n\n### Token Endpoint\n\n```\nPOST https://api.mvmnt.io/oauth2/token\n```\n\n#### Request\n\n**Headers:**\n```http\nContent-Type: application/x-www-form-urlencoded\n```\n\n**Body Parameters:**\n```\ngrant_type=client_credentials\nclient_id=YOUR_CLIENT_ID\nclient_secret=YOUR_CLIENT_SECRET\n```\n\n#### Example Request\n\n```bash\ncurl -X POST https://api.mvmnt.io/oauth2/token \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"grant_type=client_credentials\" \\\n -d \"client_id=YOUR_CLIENT_ID\" \\\n -d \"client_secret=YOUR_CLIENT_SECRET\"\n```\n\n#### Success Response\n\n**Status:** `200 OK`\n\n```json\n{\n \"access_token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 3600\n}\n```\n\n**Response Fields:**\n- `access_token`: JWT Bearer token to use for API requests\n- `token_type`: Always `Bearer`\n- `expires_in`: Token lifetime in seconds (3600 = 1 hour)\n"
contact:
name: MVMNT Support
email: support@mvmnt.io
url: https://docs.mvmnt.io
license:
name: Proprietary
url: https://mvmnt.io/legal/terms
x-parsed-md-description:
result:
- $$mdtype: Node
errors: []
lines:
- 0
- 2
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 0
- 2
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 0
- 2
inline: true
attributes:
content: The MVMNT API enables you to automate freight brokerage workflows by integrating
children: []
type: text
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 0
- 2
inline: true
attributes: {}
children: []
type: softbreak
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 0
- 2
inline: true
attributes:
content: directly with our Transportation Management System.
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: paragraph
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 3
- 4
inline: false
attributes:
level: 2
children:
- $$mdtype: Node
errors: []
lines:
- 3
- 4
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 3
- 4
inline: true
attributes:
content: Authentication
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: heading
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: true
attributes:
content: 'OAuth 2.0 client credentials flow. See '
children: []
type: text
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: true
attributes:
href: /getting-started/authentication
children:
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: true
attributes:
content: Authentication Guide
children: []
type: text
annotations: []
slots: {}
type: link
annotations: []
slots: {}
redocly:::linkOriginal:href: /getting-started/authentication
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: true
attributes:
content: ' for details.'
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: paragraph
annotations: []
slots: {}
servers:
- url: https://api.mvmnt.io/v1
description: Production
security:
- BearerAuth: []
tags:
- name: Users
description: User management operations
paths:
/users/filter:
post:
summary: Filter users
description: '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 }).
'
operationId: filterUsers
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserFilterRequest'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
pagination:
$ref: '#/components/schemas/PaginationInfo'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'422':
$ref: '#/components/responses/ValidationError'
'429':
$ref: '#/components/responses/RateLimitExceeded'
x-parsed-md-description:
result:
- $$mdtype: Node
errors: []
lines:
- 0
- 3
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 0
- 3
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 0
- 3
inline: true
attributes:
content: Filter users using comprehensive query criteria with AND/OR logic and multiple operators.
children: []
type: text
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 0
- 3
inline: true
attributes: {}
children: []
type: softbreak
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 0
- 3
inline: true
attributes:
content: Supports complex filtering similar to GraphQL capabilities.
children: []
type: text
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 0
- 3
inline: true
attributes: {}
children: []
type: softbreak
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 0
- 3
inline: true
attributes:
content: 'Note: Soft-deleted users are excluded by default (deletedAt defaults to { isNull: true }).'
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: paragraph
annotations: []
slots: {}
/users:
post:
summary: Create user
description: Create a new user in your organization
operationId: createUser
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserInput'
responses:
'201':
description: User created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'422':
$ref: '#/components/responses/ValidationError'
'429':
$ref: '#/components/responses/RateLimitExceeded'
/users/{id}:
get:
summary: Get user
description: Retrieve a user by ID or client key
operationId: getUser
tags:
- Users
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
- $ref: '#/components/parameters/LookupBy'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'429':
$ref: '#/components/responses/RateLimitExceeded'
patch:
summary: Update user
description: Partially update a user. Only provided fields will be updated.
operationId: updateUser
tags:
- Users
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
- $ref: '#/components/parameters/LookupBy'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserPatch'
responses:
'200':
description: User updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'422':
$ref: '#/components/responses/ValidationError'
'429':
$ref: '#/components/responses/RateLimitExceeded'
delete:
summary: Delete user
description: Soft delete a user (sets deletedAt timestamp)
operationId: deleteUser
tags:
- Users
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
- $ref: '#/components/parameters/LookupBy'
responses:
'204':
description: User deleted successfully
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'429':
$ref: '#/components/responses/RateLimitExceeded'
/users/search:
post:
summary: Search users
description: '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
'
operationId: searchUsers
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserSearchRequest'
responses:
'200':
description: Successful search results
content:
application/json:
schema:
$ref: '#/components/schemas/UserSearchResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'422':
$ref: '#/components/responses/ValidationError'
'429':
$ref: '#/components/responses/RateLimitExceeded'
components:
schemas:
UserStatus:
type: string
enum:
- PENDING
- ACTIVE
- INACTIVE
description: 'User account status:
- `PENDING`: User invited but has not completed onboarding
- `ACTIVE`: User account is active and can access the system
- `INACTIVE`: User account is deactivated
'
x-parsed-md-description:
result:
- $$mdtype: Node
errors: []
lines:
- 0
- 1
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 0
- 1
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 0
- 1
inline: true
attributes:
content: 'User account status:'
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: paragraph
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 1
- 4
inline: false
attributes:
ordered: false
marker: '-'
children:
- $$mdtype: Node
errors: []
lines:
- 1
- 2
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 1
- 2
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 1
- 2
inline: true
attributes:
content: PENDING
children: []
type: code
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 1
- 2
inline: true
attributes:
content: ': User invited but has not completed onboarding'
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: item
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 2
- 3
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 2
- 3
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 2
- 3
inline: true
attributes:
content: ACTIVE
children: []
type: code
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 2
- 3
inline: true
attributes:
content: ': User account is active and can access the system'
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: item
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 3
- 4
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 3
- 4
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 3
- 4
inline: true
attributes:
content: INACTIVE
children: []
type: code
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 3
- 4
inline: true
attributes:
content: ': User account is deactivated'
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: item
annotations: []
slots: {}
type: list
annotations: []
slots: {}
ValidationError:
type: object
required:
- error
- message
- details
properties:
error:
type: string
description: Error code
example: validation_error
message:
type: string
description: Human-readable error message
details:
type: array
description: Validation error details
items:
type: object
required:
- field
- message
properties:
field:
type: string
description: Field name that failed validation
message:
type: string
description: Validation error message
UserRole:
type: string
enum:
- CUSTOMER_REP
- CARRIER_REP
- AR_AP
- COMPLIANCE
- ADMIN
description: 'User role within the organization:
- `CUSTOMER_REP`: Customer service representative
- `CARRIER_REP`: Carrier service representative
- `AR_AP`: Accounts receivable/payable
- `COMPLIANCE`: Compliance officer
- `ADMIN`: System administrator
'
x-parsed-md-description:
result:
- $$mdtype: Node
errors: []
lines:
- 0
- 1
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 0
- 1
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 0
- 1
inline: true
attributes:
content: 'User role within the organization:'
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: paragraph
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 1
- 6
inline: false
attributes:
ordered: false
marker: '-'
children:
- $$mdtype: Node
errors: []
lines:
- 1
- 2
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 1
- 2
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 1
- 2
inline: true
attributes:
content: CUSTOMER_REP
children: []
type: code
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 1
- 2
inline: true
attributes:
content: ': Customer service representative'
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: item
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 2
- 3
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 2
- 3
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 2
- 3
inline: true
attributes:
content: CARRIER_REP
children: []
type: code
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 2
- 3
inline: true
attributes:
content: ': Carrier service representative'
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: item
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 3
- 4
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 3
- 4
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 3
- 4
inline: true
attributes:
content: AR_AP
children: []
type: code
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 3
- 4
inline: true
attributes:
content: ': Accounts receivable/payable'
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: item
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 4
- 5
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 4
- 5
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 4
- 5
inline: true
attributes:
content: COMPLIANCE
children: []
type: code
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 4
- 5
inline: true
attributes:
content: ': Compliance officer'
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: item
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: false
attributes: {}
children:
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: true
attributes:
content: ADMIN
children: []
type: code
annotations: []
slots: {}
- $$mdtype: Node
errors: []
lines:
- 5
- 6
inline: true
attributes:
content: ': System administrator'
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: item
annotations: []
slots: {}
type: list
annotations: []
slots: {}
UserSearchResponse:
type: object
description: 'Response for user search requests.
Note: Only active (non-deleted) users are included in results.
'
required:
- data
- pagination
- totalResults
properties:
data:
type: array
description: Search results - either flat rows or full user objects based on format parameter
items:
oneOf:
- $ref: '#/components/schemas/UserSearchRow'
- $ref: '#/components/schemas/User'
discriminator:
propertyName: object
mapping:
USER_SEARCH_ROW: '#/components/schemas/UserSearchRow'
USER: '#/components/schemas/User'
pagination:
$ref: '#/components/schemas/SearchPaginationInfo'
totalResults:
type: integer
description: Total number of matching results (excluding soft-deleted records)
minimum: 0
TextSearchCriteria:
type: object
required:
- operator
description: Search criteria for text fields (supports wildcards and partial matching)
properties:
operator:
type: string
enum:
- EQUALS
- NOT_EQUALS
- STARTS_WITH
- ENDS_WITH
- INCLUDES
- ONE_OF
- NOT_ONE_OF
- EXISTS
- DOES_NOT_EXIST
description: 'Search operator:
- `EQUALS`: Exact match
- `NOT_EQUALS`: Not equal to
- `STARTS_WITH`: Begins with prefix
- `ENDS_WITH`: Ends with suffix
- `INCLUDES`: Contains substring
- `ONE_OF`: Matches any value in array
- `NOT_ONE_OF`: Does not match any value in array
- `EXISTS`: Field has a value (not null)
- `DOES_NOT_EXIST`: Field is null
'
values:
type: array
items:
type: string
description: Array of values for ONE_OF or NOT_ONE_OF operators
example:
- value1
- value2
example:
operator: INCLUDES
values:
- search term
DatetimeSearchCriteria:
type: object
required:
- operator
description: 'Search criteria for datetime fields.
Supports both absolute datetime values and relative time expressions.
'
properties:
operator:
type: string
enum:
- EQUALS
- NOT_EQUALS
- BEFORE
- AFTER
- BETWEEN
- NOT_BETWEEN
- EXISTS
- DOES_NOT_EXIST
description: 'Search operator:
- `EQUALS`: Exact match
- `NOT_EQUALS`: Not equal to
- `BEFORE`: Before datetime
- `AFTER`: After datetime
- `BETWEEN`: Between min and max (inclusive)
- `NOT_BETWEEN`: Not between min and max
- `EXISTS`: Field has a value (not null)
- `DOES_NOT_EXIST`: Field is null
'
value:
type: string
format: date-time
description: Absolute datetime for EQUALS, NOT_EQUALS
example: '2025-01-15T10:00:00Z'
min:
type: string
format: date-time
description: Minimum datetime for BETWEEN or NOT_BETWEEN
example: '2025-01-01T00:00:00Z'
max:
type: string
format: date-time
description: Maximum datetime for BETWEEN or NOT_BETWEEN
example: '2025-12-31T23:59:59Z'
valueRelative:
type: integer
description: 'Relative time from now (negative for past, positive for future).
Example: -7 with WEEK unit means 7 weeks ago.
'
valueRelativeUnit:
$ref: '#/components/schemas/RelativeTimeUnit'
minRelative:
type: integer
description: Relative time for min boundary
minRelativeUnit:
$ref: '#/components/schemas/RelativeTimeUnit'
maxRelative:
type: integer
description: Relative time for max boundary
maxRelativeUnit:
$ref: '#/components/schemas/RelativeTimeUnit'
example:
operator: AFTER
value: '2025-01-01T00:00:00Z'
Error:
type: object
required:
- error
- message
properties:
error:
type: string
description: Error code
message:
type: string
description: Human-readable error message
ClientKeyFilter:
type: object
description: Filter options for client key fields (limited operations - exact match only)
properties:
equalTo:
type: string
description: Exact match
in:
type: array
description: Matches any value in the array
items:
type: string
isNull:
type: boolean
description: Field is null (true) or not null (false)
KeywordSearchCriteria:
type: object
required:
- operator
description: Search criteria for keyword fields (exact match, no partial matching)
properties:
operator:
type: string
enum:
- EQUALS
- NOT_EQUALS
- ONE_OF
- NOT_ONE_OF
- EXISTS
- DOES_NOT_EXIST
description: 'Search operator:
- `EQUALS`: Exact match
- `NOT_EQUALS`: Not equal to
- `ONE_OF`: Matches any value in array
- `NOT_ONE_OF`: Does not match any value in array
- `EXISTS`: Field has a value (not null)
- `DOES_NOT_EXIST`: Field is null
'
values:
type: array
items:
type: string
description: Array of values for ONE_OF or NOT_ONE_OF operators
example:
- ACTIVE
- PENDING
ex
# --- truncated at 32 KB (74 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mvmnt/refs/heads/main/openapi/mvmnt-users-api-openapi.yml