MVMNT Location Contacts API
Location contact management operations
OpenAPI Specification
openapi: 3.1.0
info:
title: MVMNT Bill Payments Location 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: Location Contacts
description: Location contact management operations
paths:
/location-contacts/filter:
post:
tags:
- Location Contacts
summary: Filter location contacts
description: 'Query location contacts using flexible filter criteria with AND/OR logic.
By default, only non-deleted location contacts are returned (deletedAt: { isNull: true }).
Override this by explicitly setting deletedAt filter criteria.
'
operationId: filterLocationContacts
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LocationContactFilterRequest'
responses:
'200':
description: Filtered location contacts with pagination
content:
application/json:
schema:
type: object
required:
- data
- pageInfo
properties:
data:
type: array
items:
$ref: '#/components/schemas/LocationContact'
pageInfo:
$ref: '#/components/schemas/PaginationInfo'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'500':
$ref: '#/components/responses/InternalServerError'
/location-contacts:
post:
tags:
- Location Contacts
summary: Create a new location contact
description: 'Link a customer contact to a location with specific contact types/roles.
Location contacts represent the relationship between a customer contact
and a specific location, defining what role the contact has at that location.
'
operationId: createLocationContact
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LocationContactInput'
examples:
primary_manager:
summary: Primary location manager
value:
locationId: 770e8400-e29b-41d4-a716-446655440000
customerContactId: 660e8400-e29b-41d4-a716-446655440000
isPrimary: true
contactTypes:
- LOCATION_MANAGER
- SHIPPING
key: ERP-LOC-CONTACT-001
billing_contact:
summary: Billing contact
value:
locationId: 770e8400-e29b-41d4-a716-446655440000
customerContactId: 660e8400-e29b-41d4-a716-446655440001
isPrimary: false
contactTypes:
- BILLING
responses:
'201':
description: Location contact created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/LocationContact'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'409':
$ref: '#/components/responses/ConflictError'
'500':
$ref: '#/components/responses/InternalServerError'
/location-contacts/{id}:
get:
tags:
- Location Contacts
summary: Get a location contact by ID
description: 'Retrieve a single location contact by its unique identifier.
'
operationId: getLocationContactById
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
responses:
'200':
description: Location contact found
content:
application/json:
schema:
$ref: '#/components/schemas/LocationContact'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/InternalServerError'
patch:
tags:
- Location Contacts
summary: Update a location contact
description: 'Partially update a location 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
'
operationId: updateLocationContact
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LocationContactPatch'
examples:
updateContactTypes:
summary: Update contact types
value:
contactTypes:
- LOCATION_MANAGER
- SHIPPING
- RECEIVING
updatePrimary:
summary: Set as primary
value:
isPrimary: true
responses:
'200':
description: Location contact updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/LocationContact'
'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:
- Location Contacts
summary: Delete a location contact
description: 'Soft delete a location contact (sets deletedAt timestamp).
The location contact will no longer appear in default queries but can be retrieved
by explicitly filtering for deleted records.
'
operationId: deleteLocationContact
parameters:
- $ref: '#/components/parameters/IdOrClientKey'
responses:
'204':
description: Location 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:
CustomerTransportationMode:
type: string
enum:
- FTL
- LTL
- AIR
- OCEAN
- RAIL
- INTERMODAL
- DRAYAGE
- EXPEDITED_GROUND
- EXPEDITED_AIR
- AUTO
- PTL
description: Transportation mode type
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
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
'
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
CustomerServiceTier:
type: string
enum:
- TIER_1
- TIER_2
- TIER_3
description: Service tier level for the customer
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)
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
CustomerCurrency:
type: string
enum:
- USD
- CAD
- MXN
- EUR
- GBP
- JPY
- CNY
- AUD
- BRL
- INR
- KRW
- RUB
- SAR
- TRY
- IDR
- ARS
- ZAR
description: Preferred currency for transactions
LocationContactPatch:
type: object
description: 'Partial location 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
'
properties:
locationId:
type: string
format: uuid
description: Location this contact is associated with
example: 770e8400-e29b-41d4-a716-446655440000
customerContactId:
type: string
format: uuid
description: Customer contact linked to this location
example: 660e8400-e29b-41d4-a716-446655440000
isPrimary:
type: boolean
description: Whether this is the primary contact for the location
example: true
contactTypes:
type: array
items:
$ref: '#/components/schemas/LocationContactType'
description: Roles/types for this location contact
example:
- LOCATION_MANAGER
- SHIPPING
key:
type:
- string
- 'null'
maxLength: 512
description: Client-defined reference identifier
example: ERP-LOC-CONTACT-001
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
LocationContactInput:
type: object
required:
- locationId
- customerContactId
- isPrimary
properties:
locationId:
type: string
format: uuid
description: Location this contact is associated with (required)
example: 770e8400-e29b-41d4-a716-446655440000
customerContactId:
type: string
format: uuid
description: Customer contact to link to this location (required)
example: 660e8400-e29b-41d4-a716-446655440000
isPrimary:
type: boolean
description: Whether this is the primary contact for the location (required)
example: true
contactTypes:
type: array
items:
$ref: '#/components/schemas/LocationContactType'
description: Roles/types for this location contact
example:
- LOCATION_MANAGER
- SHIPPING
key:
type: string
maxLength: 512
description: Client-defined reference identifier
example: ERP-LOC-CONTACT-001
CustomerAnnualRevenue:
type: string
enum:
- _0_TO_500K
- _500K_TO_3M
- _3M_TO_10M
- _10M_TO_25M
- _25M_TO_50M
- _50M_TO_100M
- _100M_TO_500M
- _500M_PLUS
description: Annual revenue range
Location:
type: object
required:
- id
- customerId
- name
- isAppointmentRequired
- createdAt
- updatedAt
properties:
object:
type: string
enum:
- LOCATION
readOnly: true
description: Object type identifier
example: LOCATION
id:
type: string
format: uuid
readOnly: true
description: Unique location identifier
example: 770e8400-e29b-41d4-a716-446655440000
customerId:
type: string
format: uuid
description: Customer (shipper profile) this location belongs to
example: 550e8400-e29b-41d4-a716-446655440000
customer:
$ref: '#/components/schemas/Customer'
readOnly: true
description: The customer this location belongs to
name:
type: string
description: Location name
example: ABC Warehouse - Dallas
key:
type:
- string
- 'null'
maxLength: 512
description: Client-defined reference identifier for this location
example: ERP-LOC-DALLAS-01
type:
$ref: '#/components/schemas/LocationType'
description: Type of location (SHIPPER, RECEIVER, or BOTH)
example: SHIPPER
isAppointmentRequired:
type: boolean
description: Whether appointments are required for this location
example: true
notes:
type:
- string
- 'null'
description: External notes visible to carriers
example: Call 24 hours ahead for appointment
internalNotes:
type:
- string
- 'null'
description: Internal notes (not visible to carriers)
example: Use dock door 5 for expedited shipments
contacts:
type: array
description: Contacts for this location
items:
$ref: '#/components/schemas/LocationContactReference'
createdAt:
type: string
format: date-time
readOnly: true
description: Timestamp when location was created
example: '2025-01-15T10:00:00Z'
updatedAt:
type: string
format: date-time
readOnly: true
description: Timestamp when location was last updated
example: '2025-01-15T14:30:00Z'
deletedAt:
type:
- string
- 'null'
format: date-time
readOnly: true
description: Timestamp when location was soft-deleted (null if active)
example: null
Customer:
type: object
required:
- id
- name
- status
- friendlyId
- createdAt
- updatedAt
properties:
object:
type: string
enum:
- CUSTOMER
readOnly: true
description: Object type identifier
example: CUSTOMER
id:
type: string
format: uuid
readOnly: true
description: Unique customer identifier
example: 550e8400-e29b-41d4-a716-446655440000
name:
type: string
description: Customer company name
example: Acme Manufacturing Corp
friendlyId:
type: string
readOnly: true
description: Human-readable customer identifier, starts with "A"
example: A123456
status:
$ref: '#/components/schemas/CustomerStatus'
serviceTier:
anyOf:
- $ref: '#/components/schemas/CustomerServiceTier'
- type: 'null'
description: Service tier level
website:
type:
- string
- 'null'
description: Customer website URL
example: https://acme-manufacturing.com
phoneNumber:
type:
- string
- 'null'
description: Primary phone number
example: +1-555-123-4567
industry:
anyOf:
- $ref: '#/components/schemas/CustomerIndustry'
- type: 'null'
description: Industry classification
annualRevenue:
anyOf:
- $ref: '#/components/schemas/CustomerAnnualRevenue'
- type: 'null'
description: Annual revenue range
annualSpend:
anyOf:
- $ref: '#/components/schemas/CustomerAnnualSpend'
- type: 'null'
description: Annual freight spend estimate
spendType:
anyOf:
- $ref: '#/components/schemas/CustomerSpendType'
- type: 'null'
description: Customer spend type (contract vs spot pricing)
naics:
type:
- string
- 'null'
description: NAICS industry code
example: '336411'
ein:
type:
- string
- 'null'
description: Employer Identification Number
example: 12-3456789
duns:
type:
- string
- 'null'
description: Dun & Bradstreet number
example: '123456789'
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: Dun & Bradstreet number
children: []
type: text
annotations: []
slots: {}
type: inline
annotations: []
slots: {}
type: paragraph
annotations: []
slots: {}
leadSource:
type:
- string
- 'null'
description: How this customer was acquired
example: Referral
dbaName:
type:
- string
- 'null'
description: Doing business as name
example: Acme Corp DBA
numberOfEmployees:
anyOf:
- $ref: '#/components/schemas/CustomerNumberOfEmployees'
- type: 'null'
description: Company size by number of employees
externalId:
type:
- string
- 'null'
description: External system identifier
example: EXT-12345
currency:
anyOf:
- $ref: '#/components/schemas/CustomerCurrency'
- type: 'null'
description: Preferred currency for transactions
creditLimit:
type:
- number
- 'null'
format: float
description: Maximum credit allowed
example: 50000
creditUsageWarning:
type:
- number
- 'null'
format: float
description: Credit usage warning threshold
example: 40000
freeCreditReq:
type:
- number
- 'null'
format: float
description: Free credit requirement
example: 5000
defaultMode:
anyOf:
- $ref: '#/components/schemas/CustomerTransportationMode'
- type: 'null'
description: Default transportation mode
defaultMargin:
type:
- number
- 'null'
format: float
description: Default margin percentage (0-1, e.g., 0.15 for 15%)
example: 0.15
minMargin:
type:
- number
- 'null'
format: float
description: Minimum margin threshold
example: 0.1
maxMargin:
type:
- number
- 'null'
format: float
description: Maximum margin threshold
example: 0.25
defaultInternalNotes:
type:
- string
- 'null'
description: Default internal notes template
example: Contact via email only
defaultCarrierNotes:
type:
- string
- 'null'
description: Default carrier-facing notes template used when note splitting is enabled
example: Call pickup contact before arrival
defaultExternalNotes:
type:
- string
- 'null'
description: Default external notes template
example: Please call 1 hour before delivery
defaultShowNotes:
anyOf:
- $ref: '#/components/schemas/ShowNotes'
- type: 'null'
description: Controls whether default external notes are reused on carrier docs or split from default carrier notes
autoAcceptTender:
type:
- boolean
- 'null'
description: Auto-accept tender flag
example: false
group:
anyOf:
- $ref: '#/components/schemas/ResourceReference'
- type: 'null'
description: Customer group reference (minimal - id and key only)
paymentTerm:
anyOf:
- $ref: '#/components/schemas/PaymentTermReference'
- type: 'null'
description: Payment term configuration reference with full details
notes:
type:
- string
- 'null'
description: Internal notes about this customer
example: Prefers email communication
deactivationReason:
anyOf:
- $ref: '#/components/schemas/CustomerDeactivationReason'
- type: 'null'
description: Reason for deactivation if status is INACTIVE
deactivationNotes:
type:
- string
- 'null'
description: Additional details about deactivation
deactivationDate:
type:
- string
- 'null'
format: date-time
description: When the customer was deactivated
example: null
closedAt:
type:
- string
- 'null'
format: date-time
description: When the customer account was closed
example: null
closedBy:
anyOf:
- $ref: '#/components/schemas/UserReference'
- type: 'null'
readOnly: true
description: User who closed the account (full user details)
closedNotes:
type:
- string
- 'null'
description: Notes about account closure
corporateAddress:
anyOf:
- $ref: '#/components/schemas/Address'
- type: 'null'
description: Corporate headquarters address (nested location data)
billingAddress:
anyOf:
- $ref: '#/components/schemas/Address'
- type: 'null'
description: Billing address (nested location data)
qboCustomerId:
type:
- string
- 'null'
description: QuickBooks Online customer ID
example: null
key:
type:
- string
- 'null'
maxLength: 512
description: Client-defined reference identifier for this customer
example: ERP-CUSTOMER-12345
contacts:
type: array
description: Contacts for this customer
items:
$ref: '#/components/schemas/CustomerContactReference'
createdAt:
type: string
format: date-time
readOnly: true
description: Timestamp when customer was created
example: '2025-01-15T10:00:00Z'
updatedAt:
# --- truncated at 32 KB (84 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mvmnt/refs/heads/main/openapi/mvmnt-location-contacts-api-openapi.yml