MVMNT Customer Contacts API
Customer contact management operations
OpenAPI Specification
openapi: 3.1.0
info:
title: MVMNT Bill Payments Customer Contacts 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: Customer Contacts
description: Customer contact management operations
paths:
/customer-contacts/filter:
post:
tags:
- Customer Contacts
summary: Filter customer contacts
description: 'Query customer contacts using flexible filter criteria with AND/OR logic.
By default, only non-deleted customer contacts are returned (deletedAt: { isNull: true }).
Override this by explicitly setting deletedAt filter criteria.
'
operationId: filterCustomerContacts
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerContactFilterRequest'
responses:
'200':
description: Filtered customer contacts with pagination
content:
application/json:
schema:
type: object
required:
- data
- pageInfo
properties:
data:
type: array
items:
$ref: '#/components/schemas/CustomerContact'
pageInfo:
$ref: '#/components/schemas/PaginationInfo'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'500':
$ref: '#/components/responses/InternalServerError'
/customer-contacts:
post:
tags:
- Customer Contacts
summary: Create customer contact
description: 'Create a new customer contact. The contactInfo will create a new Contact record,
and the CustomerContact will reference it via parentContactId (managed internally).
'
operationId: createCustomerContact
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerContactInput'
responses:
'201':
description: Customer contact created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerContact'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'409':
$ref: '#/components/responses/ConflictError'
'500':
$ref: '#/components/responses/InternalServerError'
/customer-contacts/{id}:
get:
tags:
- Customer Contacts
summary: Get customer contact
description: Retrieve a single customer contact by its unique identifier
operationId: getCustomerContactById
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
responses:
'200':
description: Customer contact found
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerContact'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/InternalServerError'
patch:
tags:
- Customer Contacts
summary: Update customer contact
description: 'Partially update a customer contact. Only provided fields will be updated.
- **Omitted fields**: Not modified (current value preserved)
- **Provided fields**: Updated to the new value
- **Null values**: Clear the field (set to null) where applicable
When updating contactInfo, the underlying Contact record is updated.
'
operationId: updateCustomerContact
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerContactPatch'
responses:
'200':
description: Customer contact updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerContact'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'409':
$ref: '#/components/responses/ConflictError'
'500':
$ref: '#/components/responses/InternalServerError'
delete:
tags:
- Customer Contacts
summary: Delete customer contact
description: 'Soft delete a customer contact (sets deletedAt timestamp).
The contact will no longer appear in default queries but can be retrieved
by explicitly filtering for deleted records.
'
operationId: deleteCustomerContact
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
responses:
'204':
description: Customer contact deleted successfully
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
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
CustomerContactPatch:
type: object
description: 'Partial contact 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
Note: customerId cannot be updated after creation.
'
properties:
name:
type: string
description: Contact person's name (should match contactInfo.name if updating both)
example: John Smith
contactInfo:
anyOf:
- $ref: '#/components/schemas/ContactInfoPatch'
- type: 'null'
description: 'Contact information update. Provide partial or full contact data to update the parent Contact record.
Cannot be set to null (contact info is required).
'
phoneExtension:
type:
- string
- 'null'
description: Phone extension
example: '1234'
isPrimary:
type: boolean
description: Whether this is the primary contact
example: true
contactTypes:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/CustomerContactType'
description: Types/roles this contact serves (replaces entire array)
example:
- BILLING
- ACCOUNT_MANAGER
notifications:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/CustomerContactNotificationType'
description: Notification types (replaces entire array)
example:
- SHIPMENT_PICKED_UP
- SHIPMENT_DELIVERED
key:
type:
- string
- 'null'
maxLength: 512
description: Client-defined reference identifier
example: ERP-CONTACT-JOHN-001
ContactInfoInput:
type: object
description: Contact information for creating a new contact record
required:
- name
properties:
name:
type: string
description: Contact person's full name
example: John Smith
email:
type: string
format: email
description: Email address
example: john.smith@example.com
phoneNumber:
type: string
description: Phone number
example: +1-555-0100
title:
type: string
description: Job title or position
example: Operations Manager
BooleanFilter:
type: object
description: Filter options for boolean fields
properties:
equalTo:
type: boolean
description: Exact match
notEqualTo:
type: boolean
description: Not equal to
isNull:
type: boolean
description: Field is null (true) or not null (false)
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)
PaginationInfo:
type: object
required:
- pageSize
- hasNextPage
properties:
pageSize:
type: integer
description: Number of items per page
example: 50
hasNextPage:
type: boolean
description: Whether there are more pages
example: true
hasPreviousPage:
type: boolean
description: Whether there are previous pages
example: false
endCursor:
type:
- string
- 'null'
description: Cursor for the next page (null if no next page)
example: eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9
CustomerContactFilter:
type: object
description: Filter criteria for contacts with AND/OR logic support
properties:
and:
type: array
description: All conditions must match (recursive)
items:
$ref: '#/components/schemas/CustomerContactFilter'
or:
type: array
description: At least one condition must match (recursive)
items:
$ref: '#/components/schemas/CustomerContactFilter'
not:
$ref: '#/components/schemas/CustomerContactFilter'
description: Negates the filter
id:
$ref: '#/components/schemas/IDFilter'
customerId:
$ref: '#/components/schemas/UUIDFilter'
name:
$ref: '#/components/schemas/StringFilter'
email:
$ref: '#/components/schemas/StringFilter'
phoneNumber:
$ref: '#/components/schemas/StringFilter'
phoneExtension:
$ref: '#/components/schemas/StringFilter'
isPrimary:
$ref: '#/components/schemas/BooleanFilter'
contactTypes:
$ref: '#/components/schemas/CustomerContactTypeFilter'
notifications:
$ref: '#/components/schemas/CustomerContactNotificationTypeFilter'
invitedUserId:
$ref: '#/components/schemas/UUIDFilter'
deletedById:
$ref: '#/components/schemas/UUIDFilter'
key:
$ref: '#/components/schemas/ClientKeyFilter'
createdAt:
$ref: '#/components/schemas/DatetimeFilter'
deletedAt:
$ref: '#/components/schemas/DatetimeFilter'
CustomerContactType:
type: string
description: Type of customer contact role
enum:
- ACCOUNT_MANAGER
- BILLING
- DOCK_SHIPPING
- EMERGENCY
- LOCATION_MANAGER
- OWNER
- PROCUREMENT
- PURCHASING
- RATES_PRICING
- RECEIVING
- SHIPPING
UUIDFilter:
type: object
description: Filter options for UUID fields (all operations)
properties:
equalTo:
type: string
format: uuid
description: Exact match
notEqualTo:
type: string
format: uuid
description: Not equal to
in:
type: array
items:
type: string
format: uuid
description: Matches any UUID in the array
notIn:
type: array
items:
type: string
format: uuid
description: Does not match any UUID in the array
isNull:
type: boolean
description: Field is null (true) or not null (false)
CustomerContactFilterRequest:
type: object
description: Request body for filtering contacts
properties:
filter:
$ref: '#/components/schemas/CustomerContactFilter'
description: 'Filter criteria (optional - omit to return all contacts).
Note: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.
'
pageSize:
type: integer
minimum: 1
maximum: 250
default: 50
description: Number of results per page
cursor:
type: string
description: Pagination cursor for next page
example:
filter:
and:
- isPrimary:
equalTo: true
- contactTypes:
includes: BILLING
pageSize: 50
CustomerReference:
type: object
description: 'Enhanced reference to a customer resource (returned in responses).
Includes full customer details in addition to id/key.
Note: Does NOT include nested references (paymentTerm, contacts, etc.) to prevent recursion.
Maximum nesting depth: 1 level.
'
required:
- id
- name
- friendlyId
- status
- createdAt
- updatedAt
properties:
id:
type: string
format: uuid
description: Customer UUID
example: 550e8400-e29b-41d4-a716-446655440000
key:
type:
- string
- 'null'
maxLength: 512
description: Client-defined reference ID if set
example: ERP-CUSTOMER-ACME
name:
type: string
description: Customer company name
example: Acme Manufacturing Corp
friendlyId:
type: string
description: Human-readable customer identifier
example: A123456
status:
type: string
description: Customer status
enum:
- PROSPECT
- ACTIVE
- INACTIVE
- CHURNED
example: ACTIVE
phoneNumber:
type:
- string
- 'null'
description: Primary phone number
example: +1-555-123-4567
website:
type:
- string
- 'null'
description: Customer website URL
example: https://acme-manufacturing.com
createdAt:
type: string
format: date-time
description: When the customer was created
example: '2025-01-15T10:00:00Z'
updatedAt:
type: string
format: date-time
description: When the customer was last updated
example: '2025-01-15T14:30:00Z'
deletedAt:
type:
- string
- 'null'
format: date-time
description: When the customer was soft deleted (null if active)
example: null
ContactInfoPatch:
type: object
description: 'Partial contact information 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:
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
CustomerContactInput:
type: object
required:
- customerId
- name
- contactInfo
properties:
customerId:
type: string
format: uuid
description: Customer this contact belongs to
example: 550e8400-e29b-41d4-a716-446655440001
name:
type: string
description: Contact person's name (should match contactInfo.name)
example: John Smith
contactInfo:
$ref: '#/components/schemas/ContactInfoInput'
description: Contact information details (will create new Contact record)
phoneExtension:
type: string
description: Phone extension specific to this contact role
example: '1234'
isPrimary:
type: boolean
default: false
description: Whether this is the primary contact for the customer
example: true
contactTypes:
type: array
items:
$ref: '#/components/schemas/CustomerContactType'
description: Types/roles this contact serves
example:
- BILLING
- ACCOUNT_MANAGER
notifications:
type: array
items:
$ref: '#/components/schemas/CustomerContactNotificationType'
description: Shipment notification types to send to this contact
example:
- SHIPMENT_PICKED_UP
- SHIPMENT_DELIVERED
key:
type: string
maxLength: 512
description: Client-defined reference identifier
example: ERP-CONTACT-JOHN-001
UserReference:
type: object
description: 'Enhanced reference to a user resource (returned in responses).
Includes full user details in addition to id/key.
Note: Does NOT include nested references (teams, etc.) to prevent recursion.
Maximum nesting depth: 1 level.
'
required:
- id
- email
- status
- createdAt
- updatedAt
properties:
id:
type: string
format: uuid
description: User UUID
example: 550e8400-e29b-41d4-a716-446655440000
key:
type:
- string
- 'null'
maxLength: 512
description: Client-defined reference ID if set
example: ERP-USER-12345
email:
type: string
format: email
description: User's email address
example: john.doe@example.com
name:
type:
- string
- 'null'
description: User's full name
example: John Doe
phone:
type:
- string
- 'null'
description: User's phone number
example: +1-555-123-4567
phoneExt:
type:
- string
- 'null'
description: Phone extension
example: '123'
status:
type: string
description: User account status
enum:
- PENDING
- ACTIVE
- INACTIVE
example: ACTIVE
avatarId:
type:
- string
- 'null'
format: uuid
description: Profile avatar document ID
example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
createdAt:
type: string
format: date-time
description: When the user was created
example: '2025-01-15T10:00:00Z'
updatedAt:
type: string
format: date-time
description: When the user was last updated
example: '2025-01-15T14:30:00Z'
deletedAt:
type:
- string
- 'null'
format: date-time
description: When the user was soft deleted (null if active)
example: null
DatetimeFilter:
type: object
description: Filter options for datetime fields
properties:
equalTo:
type: string
format: date-time
description: Exact match
notEqualTo:
type: string
format: date-time
description: Not equal to
lessThan:
type: string
format: date-time
description: Before this datetime
lessThanOrEqualTo:
type: string
format: date-time
description: On or before this datetime
greaterThan:
type: string
format: date-time
description: After this datetime
greaterThanOrEqualTo:
type: string
format: date-time
description: On or after this datetime
isNull:
type: boolean
description: Field is null (true) or not null (false)
IDFilter:
type: object
description: Filter options for ID fields (limited operations - exact match only)
properties:
equalTo:
type: string
format: uuid
description: Exact match
in:
type: array
description: Matches any UUID in the array
items:
type: string
format: uuid
StringFilter:
type: object
description: Filter options for string fields
properties:
equalTo:
type: string
description: Exact match
notEqualTo:
type: string
description: Not equal to
in:
type: array
items:
type: string
description: Matches any value in the array
notIn:
type: array
items:
type: string
description: Does not match any value in the array
includes:
type: string
description: Contains substring (case-insensitive)
notIncludes:
type: string
description: Does not contain substring (case-insensitive)
startsWith:
type: string
description: Starts with prefix (case-insensitive)
notStartsWith:
type: string
description: Does not start with prefix (case-insensitive)
endsWith:
type: string
description: Ends with suffix (case-insensitive)
notEndsWith:
type: string
description: Does not end with suffix (case-insensitive)
isNull:
type: boolean
description: Field is null (true) or not null (false)
CustomerContact:
type: object
required:
- id
- customer
- name
- isPrimary
- contactInfo
- createdAt
properties:
object:
type: string
enum:
- CUSTOMER_CONTACT
readOnly: true
description: Object type identifier
example: CUSTOMER_CONTACT
id:
type: string
format: uuid
readOnly: true
description: Unique contact identifier
example: 550e8400-e29b-41d4-a716-446655440000
customer:
$ref: '#/components/schemas/CustomerReference'
description: Customer this contact belongs to (full customer details)
name:
type: string
description: Contact person's name (denormalized from ContactInfo for convenience)
example: John Smith
contactInfo:
allOf:
- $ref: '#/components/schemas/ContactInfo'
description: Contact information details (email, phone, title) - nested from parent Contact record
phoneExtension:
type:
- string
- 'null'
description: Phone extension specific to this contact role
example: '1234'
isPrimary:
type: boolean
description: Whether this is the primary contact for the customer
example: true
contactTypes:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/CustomerContactType'
description: Types/roles this contact serves
example:
- BILLING
- ACCOUNT_MANAGER
notifications:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/CustomerContactNotificationType'
description: Shipment notification types to send to this contact
example:
- SHIPMENT_PICKED_UP
- SHIPMENT_DELIVERED
invitedUser:
anyOf:
- $ref: '#/components/schemas/UserReference'
- type: 'null'
readOnly: true
description: User account invited/created for this contact (full user details)
deletedBy:
anyOf:
- $ref: '#/components/schemas/UserReference'
- type: 'null'
readOnly: true
description: User who deleted this contact (full user details)
key:
type:
- string
- 'null'
maxLength: 512
description: Client-defined reference identifier
example: ERP-CONTACT-JOHN-001
createdAt:
type: string
format: date-time
readOnly: true
description: When the contact was created
example: '2025-01-15T10:00:00Z'
deletedAt:
type:
- string
- 'null'
format: date-time
readOnly: true
description: When the contact was soft deleted (null if active)
example: null
CustomerContactNotificationTypeFilter:
type: object
description: Filter for notification type enum array field
properties:
includes:
$ref: '#/components/schemas/CustomerContactNotificationType'
description: Array contains this notification type
notIncludes:
$ref: '#/components/schemas/CustomerContactNotificationType'
description: Array does not contain this notification type
isNull:
type: boolean
description: Field is null (true) or not null (false)
CustomerContactTypeFilter:
type: object
description: Filter for contact type enum array field
properties:
includes:
$ref: '#/components/schemas/CustomerContactType'
description: Array contains
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mvmnt/refs/heads/main/openapi/mvmnt-customer-contacts-api-openapi.yml