OpenAPI Specification
openapi: 3.1.0
info:
title: MVMNT Bill Payments Customers 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: Customers
description: Customer management operations
paths:
/customers/filter:
post:
summary: Filter customers
description: 'Filter customers using comprehensive query criteria with AND/OR logic and multiple operators.
Supports complex filtering similar to GraphQL capabilities.
Note: Soft-deleted customers are excluded by default (deletedAt defaults to { isNull: true }).
'
operationId: filterCustomers
tags:
- Customers
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerFilterRequest'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Customer'
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 customers 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 customers are excluded by default (deletedAt defaults to { isNull: true }).'
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: paragraph
annotations: []
slots: {}
/customers:
post:
summary: Create customer
description: Create a new customer in your organization
operationId: createCustomer
tags:
- Customers
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerInput'
responses:
'201':
description: Customer created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'422':
$ref: '#/components/responses/ValidationError'
'429':
$ref: '#/components/responses/RateLimitExceeded'
/customers/{id}:
get:
summary: Get customer
description: Retrieve a customer by ID or client key
operationId: getCustomer
tags:
- Customers
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
- $ref: '#/components/parameters/LookupBy'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'429':
$ref: '#/components/responses/RateLimitExceeded'
patch:
summary: Update customer
description: Partially update a customer. Only provided fields will be updated.
operationId: updateCustomer
tags:
- Customers
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
- $ref: '#/components/parameters/LookupBy'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerPatch'
responses:
'200':
description: Customer updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
'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 customer
description: Soft delete a customer (sets deletedAt timestamp)
operationId: deleteCustomer
tags:
- Customers
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
- $ref: '#/components/parameters/LookupBy'
responses:
'204':
description: Customer deleted successfully
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'429':
$ref: '#/components/responses/RateLimitExceeded'
/customers/search:
post:
summary: Search customers
description: 'Search customers using OpenSearch-powered full-text and field-specific search.
This endpoint provides fast, indexed search across customer 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) customers 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 customer objects with all relationships
'
operationId: searchCustomers
tags:
- Customers
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerSearchRequest'
responses:
'200':
description: Successful search results
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerSearchResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'422':
$ref: '#/components/responses/ValidationError'
'429':
$ref: '#/components/responses/RateLimitExceeded'
/customers/{id}/payments:
get:
summary: Get customer payments
description: List all payments from a specific customer.
operationId: getCustomerPayments
tags:
- Customers
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
- $ref: '#/components/parameters/LookupBy'
- name: pageSize
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 50
- name: cursor
in: query
schema:
type: string
responses:
'200':
description: Payments retrieved successfully
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Payment'
pagination:
$ref: '#/components/schemas/PaginationInfo'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
/customers/{id}/outstanding-invoices:
get:
summary: Get outstanding invoices
description: 'List invoices available for payment from a customer.
Returns invoices with status `AWAITING_PAYMENT` or `PARTIALLY_PAID`.
'
operationId: getCustomerOutstandingInvoices
tags:
- Customers
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
- $ref: '#/components/parameters/LookupBy'
responses:
'200':
description: Outstanding invoices retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/OutstandingInvoicesResponse'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
components:
schemas:
CustomerTransportationMode:
type: string
enum:
- FTL
- LTL
- AIR
- OCEAN
- RAIL
- INTERMODAL
- DRAYAGE
- EXPEDITED_GROUND
- EXPEDITED_AIR
- AUTO
- PTL
description: Transportation mode type
AddressPatch:
type: object
description: 'Partial address update. All fields are optional.
- **Omitted fields**: Not modified (current value preserved)
- **Provided fields**: Updated to the new value
- **Null values**: Clear the field (set to null) where applicable
'
properties:
line1:
type: string
description: Primary street address line
example: 123 Main St
line2:
type:
- string
- 'null'
description: Secondary address line
example: Suite 400
city:
type: string
description: City name
example: Chicago
country:
type: string
description: Country name or code
example: USA
market:
type: string
description: Market or region identifier
example: CHI
latitude:
type:
- string
- 'null'
description: Latitude coordinate
example: '41.8781'
longitude:
type:
- string
- 'null'
description: Longitude coordinate
example: '-87.6298'
isAirportOrAirbase:
type: boolean
description: Whether this location is an airport or airbase
example: false
isConstructionOrUtilitySite:
type: boolean
description: Whether this location is a construction or utility site
example: false
isSmartyValidated:
type: boolean
description: Whether address has been validated by SmartyStreets
example: true
obeysDst:
type: boolean
description: Whether this location observes daylight saving time
example: true
cityId:
type:
- string
- 'null'
format: uuid
description: Reference to standardized city record
example: null
CustomerAnnualRevenueFilter:
type: object
description: Filter options for CustomerAnnualRevenue enum
properties:
equalTo:
$ref: '#/components/schemas/CustomerAnnualRevenue'
description: Exact match
notEqualTo:
$ref: '#/components/schemas/CustomerAnnualRevenue'
description: Not equal to
in:
type: array
items:
$ref: '#/components/schemas/CustomerAnnualRevenue'
description: Matches any value in the array
notIn:
type: array
items:
$ref: '#/components/schemas/CustomerAnnualRevenue'
description: Does not match any value in the array
isNull:
type: boolean
description: Field is null (true) or not null (false)
ContactInfo:
type: object
description: 'Contact information details (nested, without id).
This is an embedded object representing a Contact record. The id is managed
internally and not exposed in the API.
'
required:
- name
properties:
name:
type: string
description: Contact person's full name
example: John Smith
email:
type:
- string
- 'null'
format: email
description: Email address
example: john.smith@example.com
phoneNumber:
type:
- string
- 'null'
description: Phone number
example: +1-555-0100
title:
type:
- string
- 'null'
description: Job title or position
example: Operations Manager
CustomerSearchResponse:
type: object
description: 'Response for customer search requests.
Note: Only active (non-deleted) customers are included in results.
'
required:
- data
- pagination
- totalResults
properties:
data:
type: array
description: Search results - either flat rows or full customer objects based on format parameter
items:
oneOf:
- $ref: '#/components/schemas/CustomerSearchRow'
- $ref: '#/components/schemas/Customer'
discriminator:
propertyName: object
mapping:
CUSTOMER_SEARCH_ROW: '#/components/schemas/CustomerSearchRow'
CUSTOMER: '#/components/schemas/Customer'
pagination:
$ref: '#/components/schemas/SearchPaginationInfo'
totalResults:
type: integer
description: Total number of matching results (excluding soft-deleted records)
minimum: 0
CustomerServiceTier:
type: string
enum:
- TIER_1
- TIER_2
- TIER_3
description: Service tier level for the customer
CustomerAnnualSpend:
type: string
enum:
- _0_TO_25K
- _25_TO_150K
- _150K_TO_300K
- _300K_TO_1M
- _1_TO_5M
- _5M_TO_25M
- _25M_TO_75M
- _75M_PLUS
description: Annual freight spend estimate range
ShowNotes:
type: string
enum:
- ALL
- SPLIT
description: 'Controls whether external notes are shown on all documents or split from carrier-facing notes.
- `ALL`: Use external notes on customer-facing and carrier-facing documents
- `SPLIT`: Use external notes on customer-facing documents and carrier notes on carrier-facing documents
'
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'
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
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
Address:
type: object
description: 'Physical address/location details (nested, without id).
This is an embedded object representing a Location record. The id is managed
internally and not exposed in the API.
'
required:
- line1
- city
- country
- market
- isAirportOrAirbase
- isConstructionOrUtilitySite
- isSmartyValidated
- obeysDst
properties:
line1:
type: string
description: Primary street address line
example: 123 Main St
line2:
type:
- string
- 'null'
description: Secondary address line (suite, floor, etc.)
example: Suite 400
city:
type: string
description: City name
example: Chicago
country:
type: string
description: Country name or code
example: USA
market:
type: string
description: Market or region identifier
example: CHI
latitude:
type:
- string
- 'null'
description: Latitude coordinate
example: '41.8781'
longitude:
type:
- string
- 'null'
description: Longitude coordinate
example: '-87.6298'
isAirportOrAirbase:
type: boolean
description: Whether this location is an airport or airbase
example: false
isConstructionOrUtilitySite:
type: boolean
description: Whether this location is a construction or utility site
example: false
isSmartyValidated:
type: boolean
description: Whether address has been validated by SmartyStreets
example: true
obeysDst:
type: boolean
description: Whether this location observes daylight saving time
example: true
cityId:
type:
- string
- 'null'
format: uuid
description: Reference to standardized city record (internal use)
example: null
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
example:
operator: ONE_OF
values:
- ACTIVE
- PENDING
PaymentCreditApplication:
type: object
properties:
id:
type: string
format: uuid
creditMemoId:
type: string
format: uuid
creditMemoReference:
type:
- string
- 'null'
amount:
type: number
description: Credit amount applied in this payment
SearchPaginationInput:
type: object
description: Pagination options for search requests
properties:
pageNumber:
type: integer
minimum: 1
default: 1
description: Page number (1-based)
example: 1
pageSize:
type: integer
minimum: 1
maximum: 250
default: 50
description: Number of results per page (max 250)
example: 50
example:
pageNumber: 1
pageSize: 50
CustomerSearchRow:
type: object
description: 'Flattened customer data from search index.
Note: This represents only active customers. Soft-deleted records are never returned.
'
properties:
object:
type: string
enum:
- CUSTOMER_SEARCH_ROW
description: Object type identifier for discriminating between flat and full response formats
id:
type: string
format: uuid
friendlyId:
type: string
example: CUST-0001
name:
type: string
dbaName:
type:
- string
- 'null'
status:
type: string
enum:
- ACTIVE
- INACTIVE
- PENDING
- SUSPENDED
- ARCHIVED
city:
type:
- string
- 'null'
state:
type:
- string
- 'null'
description: State/Province code (uppercase)
location:
type:
- string
- 'null'
description: Computed as "city, state"
zip:
type:
- string
- 'null'
country:
type:
- string
- 'null'
description: Country code (uppercase)
teamId:
type:
- string
- 'null'
format: uuid
description: Team ID (maps from groupId)
teamName:
type:
- string
- 'null'
description: Team name (maps from groupName)
userIds:
type: array
items:
type: string
format: uuid
description: IDs of users associated with this customer
userNames:
type: array
items:
type: string
description: Names of users associated with this customer (may be hidden in some contexts)
accountOwnerId:
type:
- string
- 'null'
format: uuid
accountOwnerName:
type:
- string
- 'null'
operatedById:
type:
- string
- 'null'
format: uuid
operatedByName:
type:
- string
- 'null'
primaryContactName:
type:
- string
- 'null'
primaryContactEmail:
type:
- string
- 'null'
format: email
primaryContactPhone:
type:
- string
- 'nu
# --- truncated at 32 KB (142 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mvmnt/refs/heads/main/openapi/mvmnt-customers-api-openapi.yml