Skip to content
/Customers

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

Carriers

Carrier management operations

Operations

Carrier Contacts

Carrier contact management operations

Operations

Carrier Factors

Carrier factor (factoring company) management operations

Operations

Carrier Payment Methods

Carrier payment method management operations

Operations

Companies

Company management operations

Operations

Credit Memos

AR credit memo management operations. Credit memos represent customer credits that can be applied to invoices.

Operations

Bills

AP bill management operations. Bills represent carrier and vendor invoices to be paid.

Operations

Bill Payments

AP bill payment management operations. Bill payments record payments made to carriers and vendors.

Operations

Customers

Customer management operations

Operations

Filter customers

Request

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 }).

Security
BearerAuth
Bodyapplication/jsonrequired
filterobject(CustomerFilter)

Filter criteria (optional - omit to return all customers). Note: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.

Example: {"and":[{"status":{"equalTo":"ACTIVE"}},{"industry":{"includes":"Manufacturing"}}]}
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/customers/filter \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": {
      "and": [
        {
          "status": {
            "equalTo": "ACTIVE"
          }
        },
        {
          "industry": {
            "includes": "Manufacturing"
          }
        }
      ]
    },
    "pageSize": 50
  }'

Responses

Successful response

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

Create customer

Request

Create a new customer in your organization

Security
BearerAuth
Bodyapplication/jsonrequired
namestringrequired

Customer company name (required)

Example: "Acme Manufacturing Corp"
statusstring(CustomerStatus)required

Customer account status (includes lead stages):

  • NEW: New lead, not yet contacted
  • CONTACTED: Initial contact made with lead
  • QUALIFIED: Lead has been qualified as potential customer
  • QUOTED: Quote has been provided to lead
  • NURTURING: Lead being nurtured for future opportunity
  • PENDING: Customer prospect pending activation
  • ACTIVE: Active customer account
  • INACTIVE: Deactivated customer account
  • BLOCKED: Customer account blocked from operations
  • CLOSED: Customer account permanently closed
Enum"NEW""CONTACTED""QUALIFIED""QUOTED""NURTURING""PENDING""ACTIVE""INACTIVE""BLOCKED""CLOSED"
serviceTierstring(CustomerServiceTier)

Service tier level for the customer

Enum"TIER_1""TIER_2""TIER_3"
websitestring

Customer website URL

Example: "https://acme-manufacturing.com"
phoneNumberstring

Primary phone number

Example: "+1-555-123-4567"
industrystring(CustomerIndustry)

Industry classification for the customer

Enum"AGRICULTURE_FORESTRY""CONSTRUCTION""CONSUMER_GOODS""EDUCATIONAL_SERVICES""ENTERTAINMENT""FOOD_SERVICES""HEALTHCARE""INDUSTRIAL_MACHINERY""MANUFACTURING""MINING"
annualRevenuestring(CustomerAnnualRevenue)

Annual revenue range

Enum"_0_TO_500K""_500K_TO_3M""_3M_TO_10M""_10M_TO_25M""_25M_TO_50M""_50M_TO_100M""_100M_TO_500M""_500M_PLUS"
annualSpendstring(CustomerAnnualSpend)

Annual freight spend estimate range

Enum"_0_TO_25K""_25_TO_150K""_150K_TO_300K""_300K_TO_1M""_1_TO_5M""_5M_TO_25M""_25M_TO_75M""_75M_PLUS"
spendTypestring(CustomerSpendType)

Customer spend type:

  • CONTRACT: Customer operates under contract pricing
  • SPOT: Customer operates on spot market pricing
Enum"CONTRACT""SPOT"
naicsstring

NAICS industry code

Example: "336411"
einstring

Employer Identification Number

Example: "12-3456789"
dunsstring

Dun & Bradstreet number

Example: "123456789"
leadSourcestring

How this customer was acquired

Example: "Referral"
dbaNamestring

Doing business as name

Example: "Acme Corp DBA"
numberOfEmployeesstring(CustomerNumberOfEmployees)

Number of employees in the company

Enum"_0_TO_1""_2_TO_5""_6_TO_9""_10_TO_24""_25_TO_99""_100_TO_249""_250_TO_499""_500_OR_MORE"
externalIdstring

External system identifier

Example: "EXT-12345"
currencystring(CustomerCurrency)

Preferred currency for transactions

Enum"USD""CAD""MXN""EUR""GBP""JPY""CNY""AUD""BRL""INR"
creditLimitnumber(float)

Maximum credit allowed

Example: 50000
creditUsageWarningnumber(float)

Credit usage warning threshold

Example: 40000
freeCreditReqnumber(float)

Free credit requirement

Example: 5000
defaultModestring(CustomerTransportationMode)

Transportation mode type

Enum"FTL""LTL""AIR""OCEAN""RAIL""INTERMODAL""DRAYAGE""EXPEDITED_GROUND""EXPEDITED_AIR""AUTO"
defaultMarginnumber(float)

Default margin percentage (0-1, e.g., 0.15 for 15%)

Example: 0.15
minMarginnumber(float)

Minimum margin threshold

Example: 0.1
maxMarginnumber(float)

Maximum margin threshold

Example: 0.25
defaultInternalNotesstring

Default internal notes template

Example: "Contact via email only"
defaultExternalNotesstring

Default external notes template

Example: "Please call 1 hour before delivery"
autoAcceptTenderboolean

Auto-accept tender flag

Example: false
groupIdstring(uuid)

Customer group reference

paymentTermobject(ResourceReferenceInput)
One of:

Reference to another resource by either ID or client key (used in create/update requests)

notesstring

Internal notes about this customer

Example: "Prefers email communication"
deactivationReasonstring(CustomerDeactivationReason)

Reason for customer deactivation:

  • NOT_PAYING_INVOICE: Customer is not paying invoices
  • ACQUIRED: Customer was acquired by another company
  • DUPLICATE: Duplicate customer record
  • NOT_IN_BUSINESS: Customer is no longer in business
  • OTHER: Other reason (see deactivationNotes for details)
Enum"NOT_PAYING_INVOICE""ACQUIRED""DUPLICATE""NOT_IN_BUSINESS""OTHER"
deactivationNotesstring

Additional details about deactivation

deactivationDatestring(date-time)

When the customer was deactivated

corporateAddressobject(AddressInput)

Corporate headquarters address (will create new location record)

billingAddressobject(AddressInput)

Billing address (will create new location record)

qboCustomerIdstring

QuickBooks Online customer ID

keystring<= 512 characters

Client-defined reference identifier

Example: "ERP-CUSTOMER-12345"
curl -i -X POST \
  https://docs.mvmnt.io/_mock/apis/openapi/customers \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Acme Manufacturing Corp",
    "status": "NEW",
    "serviceTier": "TIER_1",
    "website": "https://acme-manufacturing.com",
    "phoneNumber": "+1-555-123-4567",
    "industry": "AGRICULTURE_FORESTRY",
    "annualRevenue": "_0_TO_500K",
    "annualSpend": "_0_TO_25K",
    "spendType": "CONTRACT",
    "naics": "336411",
    "ein": "12-3456789",
    "duns": "123456789",
    "leadSource": "Referral",
    "dbaName": "Acme Corp DBA",
    "numberOfEmployees": "_0_TO_1",
    "externalId": "EXT-12345",
    "currency": "USD",
    "creditLimit": 50000,
    "creditUsageWarning": 40000,
    "freeCreditReq": 5000,
    "defaultMode": "FTL",
    "defaultMargin": 0.15,
    "minMargin": 0.1,
    "maxMargin": 0.25,
    "defaultInternalNotes": "Contact via email only",
    "defaultExternalNotes": "Please call 1 hour before delivery",
    "autoAcceptTender": false,
    "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
    "paymentTerm": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    },
    "notes": "Prefers email communication",
    "deactivationReason": "NOT_PAYING_INVOICE",
    "deactivationNotes": "string",
    "deactivationDate": "2019-08-24T14:15:22Z",
    "corporateAddress": {
      "line1": "123 Main St",
      "line2": "Suite 400",
      "city": "Chicago",
      "country": "USA",
      "market": "CHI",
      "latitude": "41.8781",
      "longitude": "-87.6298",
      "isAirportOrAirbase": false,
      "isConstructionOrUtilitySite": false,
      "isSmartyValidated": true,
      "obeysDst": true,
      "cityId": "c903c051-7337-48de-bbe0-bca96fcde3f4"
    },
    "billingAddress": {
      "line1": "123 Main St",
      "line2": "Suite 400",
      "city": "Chicago",
      "country": "USA",
      "market": "CHI",
      "latitude": "41.8781",
      "longitude": "-87.6298",
      "isAirportOrAirbase": false,
      "isConstructionOrUtilitySite": false,
      "isSmartyValidated": true,
      "obeysDst": true,
      "cityId": "c903c051-7337-48de-bbe0-bca96fcde3f4"
    },
    "qboCustomerId": "string",
    "key": "ERP-CUSTOMER-12345"
  }'

Responses

Customer created successfully

Bodyapplication/json
objectstringread-only

Object type identifier

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

Unique customer identifier

Example: "550e8400-e29b-41d4-a716-446655440000"
namestringrequired

Customer company name

Example: "Acme Manufacturing Corp"
friendlyIdstringread-onlyrequired

Human-readable customer identifier, starts with "A"

Example: "A123456"
statusstring(CustomerStatus)required

Customer account status (includes lead stages):

  • NEW: New lead, not yet contacted
  • CONTACTED: Initial contact made with lead
  • QUALIFIED: Lead has been qualified as potential customer
  • QUOTED: Quote has been provided to lead
  • NURTURING: Lead being nurtured for future opportunity
  • PENDING: Customer prospect pending activation
  • ACTIVE: Active customer account
  • INACTIVE: Deactivated customer account
  • BLOCKED: Customer account blocked from operations
  • CLOSED: Customer account permanently closed
Enum"NEW""CONTACTED""QUALIFIED""QUOTED""NURTURING""PENDING""ACTIVE""INACTIVE""BLOCKED""CLOSED"
serviceTierCustomerServiceTier (string) or null

Service tier level

Any of:

Service tier level for the customer

string(CustomerServiceTier)
Enum"TIER_1""TIER_2""TIER_3"
websitestring or null

Customer website URL

Example: "https://acme-manufacturing.com"
phoneNumberstring or null

Primary phone number

Example: "+1-555-123-4567"
industryCustomerIndustry (string) or null

Industry classification

Any of:

Industry classification for the customer

string(CustomerIndustry)
Enum"AGRICULTURE_FORESTRY""CONSTRUCTION""CONSUMER_GOODS""EDUCATIONAL_SERVICES""ENTERTAINMENT""FOOD_SERVICES""HEALTHCARE""INDUSTRIAL_MACHINERY""MANUFACTURING""MINING"
annualRevenueCustomerAnnualRevenue (string) or null

Annual revenue range

Any of:

Annual revenue range

string(CustomerAnnualRevenue)
Enum"_0_TO_500K""_500K_TO_3M""_3M_TO_10M""_10M_TO_25M""_25M_TO_50M""_50M_TO_100M""_100M_TO_500M""_500M_PLUS"
annualSpendCustomerAnnualSpend (string) or null

Annual freight spend estimate

Any of:

Annual freight spend estimate range

string(CustomerAnnualSpend)
Enum"_0_TO_25K""_25_TO_150K""_150K_TO_300K""_300K_TO_1M""_1_TO_5M""_5M_TO_25M""_25M_TO_75M""_75M_PLUS"
spendTypeCustomerSpendType (string) or null

Customer spend type (contract vs spot pricing)

Any of:

Customer spend type:

  • CONTRACT: Customer operates under contract pricing
  • SPOT: Customer operates on spot market pricing
string(CustomerSpendType)
Enum"CONTRACT""SPOT"
naicsstring or null

NAICS industry code

Example: "336411"
einstring or null

Employer Identification Number

Example: "12-3456789"
dunsstring or null

Dun & Bradstreet number

Example: "123456789"
leadSourcestring or null

How this customer was acquired

Example: "Referral"
dbaNamestring or null

Doing business as name

Example: "Acme Corp DBA"
numberOfEmployeesCustomerNumberOfEmployees (string) or null

Company size by number of employees

Any of:

Number of employees in the company

string(CustomerNumberOfEmployees)
Enum"_0_TO_1""_2_TO_5""_6_TO_9""_10_TO_24""_25_TO_99""_100_TO_249""_250_TO_499""_500_OR_MORE"
externalIdstring or null

External system identifier

Example: "EXT-12345"
currencyCustomerCurrency (string) or null

Preferred currency for transactions

Any of:

Preferred currency for transactions

string(CustomerCurrency)
Enum"USD""CAD""MXN""EUR""GBP""JPY""CNY""AUD""BRL""INR"
creditLimitnumber or null(float)

Maximum credit allowed

Example: 50000
creditUsageWarningnumber or null(float)

Credit usage warning threshold

Example: 40000
freeCreditReqnumber or null(float)

Free credit requirement

Example: 5000
defaultModeCustomerTransportationMode (string) or null

Default transportation mode

Any of:

Transportation mode type

string(CustomerTransportationMode)
Enum"FTL""LTL""AIR""OCEAN""RAIL""INTERMODAL""DRAYAGE""EXPEDITED_GROUND""EXPEDITED_AIR""AUTO"
defaultMarginnumber or null(float)

Default margin percentage (0-1, e.g., 0.15 for 15%)

Example: 0.15
minMarginnumber or null(float)

Minimum margin threshold

Example: 0.1
maxMarginnumber or null(float)

Maximum margin threshold

Example: 0.25
defaultInternalNotesstring or null

Default internal notes template

Example: "Contact via email only"
defaultExternalNotesstring or null

Default external notes template

Example: "Please call 1 hour before delivery"
autoAcceptTenderboolean or null

Auto-accept tender flag

Example: false
groupResourceReference (object) or null

Customer group reference (minimal - id and key only)

Any of:

Reference to another resource (returned in responses)

paymentTermPaymentTermReference (object) or null

Payment term configuration reference with full details

Any of:

Enhanced reference to a payment term resource (returned in responses). Includes full payment term details in addition to id/key.

notesstring or null

Internal notes about this customer

Example: "Prefers email communication"
deactivationReasonCustomerDeactivationReason (string) or null

Reason for deactivation if status is INACTIVE

Any of:

Reason for customer deactivation:

  • NOT_PAYING_INVOICE: Customer is not paying invoices
  • ACQUIRED: Customer was acquired by another company
  • DUPLICATE: Duplicate customer record
  • NOT_IN_BUSINESS: Customer is no longer in business
  • OTHER: Other reason (see deactivationNotes for details)
string(CustomerDeactivationReason)
Enum"NOT_PAYING_INVOICE""ACQUIRED""DUPLICATE""NOT_IN_BUSINESS""OTHER"
deactivationNotesstring or null

Additional details about deactivation

deactivationDatestring or null(date-time)

When the customer was deactivated

Example: null
closedAtstring or null(date-time)

When the customer account was closed

Example: null
closedByUserReference (object) or nullread-only

User who closed the account (full user details)

Any of:

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.

closedNotesstring or null

Notes about account closure

corporateAddressAddress (object) or null

Corporate headquarters address (nested location data)

Any of:

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.

billingAddressAddress (object) or null

Billing address (nested location data)

Any of:

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.

qboCustomerIdstring or null

QuickBooks Online customer ID

Example: null
keystring or null<= 512 characters

Client-defined reference identifier for this customer

Example: "ERP-CUSTOMER-12345"
contactsArray of objects(CustomerContactReference)

Contacts for this customer

createdAtstring(date-time)read-onlyrequired

Timestamp when customer was created

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

Timestamp when customer was last updated

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

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

Example: null
deletedByUserReference (object) or nullread-only

User who deleted the customer (full user details)

Any of:

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.

Response
application/json
{
  "object": "CUSTOMER",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Manufacturing Corp",
  "friendlyId": "A123456",
  "status": "NEW",
  "serviceTier": "TIER_1",
  "website": "https://acme-manufacturing.com",
  "phoneNumber": "+1-555-123-4567",
  "industry": "AGRICULTURE_FORESTRY",
  "annualRevenue": "_0_TO_500K",
  "annualSpend": "_0_TO_25K",
  "spendType": "CONTRACT",
  "naics": "336411",
  "ein": "12-3456789",
  "duns": "123456789",
  "leadSource": "Referral",
  "dbaName": "Acme Corp DBA",
  "numberOfEmployees": "_0_TO_1",
  "externalId": "EXT-12345",
  "currency": "USD",
  "creditLimit": 50000,
  "creditUsageWarning": 40000,
  "freeCreditReq": 5000,
  "defaultMode": "FTL",
  "defaultMargin": 0.15,
  "minMargin": 0.1,
  "maxMargin": 0.25,
  "defaultInternalNotes": "Contact via email only",
  "defaultExternalNotes": "Please call 1 hour before delivery",
  "autoAcceptTender": false,
  "group": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-USER-12345"
  },
  "paymentTerm": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-PAYTERM-NET30",
    "name": "Net 30",
    "description": "Payment due 30 days from invoice date",
    "days": 30,
    "quickPayFee": 0.05,
    "apOnly": false,
    "doNotUse": false,
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z",
    "deletedAt": null
  },
  "notes": "Prefers email communication",
  "deactivationReason": "NOT_PAYING_INVOICE",
  "deactivationNotes": "string",
  "deactivationDate": null,
  "closedAt": null,
  "closedBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-USER-12345",
    "email": "john.doe@example.com",
    "name": "John Doe",
    "phone": "+1-555-123-4567",
    "phoneExt": "123",
    "status": "ACTIVE",
    "avatarId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z",
    "deletedAt": null
  },
  "closedNotes": "string",
  "corporateAddress": {
    "line1": "123 Main St",
    "line2": "Suite 400",
    "city": "Chicago",
    "country": "USA",
    "market": "CHI",
    "latitude": "41.8781",
    "longitude": "-87.6298",
    "isAirportOrAirbase": false,
    "isConstructionOrUtilitySite": false,
    "isSmartyValidated": true,
    "obeysDst": true,
    "cityId": null
  },
  "billingAddress": {
    "line1": "123 Main St",
    "line2": "Suite 400",
    "city": "Chicago",
    "country": "USA",
    "market": "CHI",
    "latitude": "41.8781",
    "longitude": "-87.6298",
    "isAirportOrAirbase": false,
    "isConstructionOrUtilitySite": false,
    "isSmartyValidated": true,
    "obeysDst": true,
    "cityId": null
  },
  "qboCustomerId": null,
  "key": "ERP-CUSTOMER-12345",
  "contacts": [
    { … }
  ],
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T14:30:00Z",
  "deletedAt": null,
  "deletedBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-USER-12345",
    "email": "john.doe@example.com",
    "name": "John Doe",
    "phone": "+1-555-123-4567",
    "phoneExt": "123",
    "status": "ACTIVE",
    "avatarId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z",
    "deletedAt": null
  }
}

Get customer

Request

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

Responses

Successful response

Bodyapplication/json
objectstringread-only

Object type identifier

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

Unique customer identifier

Example: "550e8400-e29b-41d4-a716-446655440000"
namestringrequired

Customer company name

Example: "Acme Manufacturing Corp"
friendlyIdstringread-onlyrequired

Human-readable customer identifier, starts with "A"

Example: "A123456"
statusstring(CustomerStatus)required

Customer account status (includes lead stages):

  • NEW: New lead, not yet contacted
  • CONTACTED: Initial contact made with lead
  • QUALIFIED: Lead has been qualified as potential customer
  • QUOTED: Quote has been provided to lead
  • NURTURING: Lead being nurtured for future opportunity
  • PENDING: Customer prospect pending activation
  • ACTIVE: Active customer account
  • INACTIVE: Deactivated customer account
  • BLOCKED: Customer account blocked from operations
  • CLOSED: Customer account permanently closed
Enum"NEW""CONTACTED""QUALIFIED""QUOTED""NURTURING""PENDING""ACTIVE""INACTIVE""BLOCKED""CLOSED"
serviceTierCustomerServiceTier (string) or null

Service tier level

Any of:

Service tier level for the customer

string(CustomerServiceTier)
Enum"TIER_1""TIER_2""TIER_3"
websitestring or null

Customer website URL

Example: "https://acme-manufacturing.com"
phoneNumberstring or null

Primary phone number

Example: "+1-555-123-4567"
industryCustomerIndustry (string) or null

Industry classification

Any of:

Industry classification for the customer

string(CustomerIndustry)
Enum"AGRICULTURE_FORESTRY""CONSTRUCTION""CONSUMER_GOODS""EDUCATIONAL_SERVICES""ENTERTAINMENT""FOOD_SERVICES""HEALTHCARE""INDUSTRIAL_MACHINERY""MANUFACTURING""MINING"
annualRevenueCustomerAnnualRevenue (string) or null

Annual revenue range

Any of:

Annual revenue range

string(CustomerAnnualRevenue)
Enum"_0_TO_500K""_500K_TO_3M""_3M_TO_10M""_10M_TO_25M""_25M_TO_50M""_50M_TO_100M""_100M_TO_500M""_500M_PLUS"
annualSpendCustomerAnnualSpend (string) or null

Annual freight spend estimate

Any of:

Annual freight spend estimate range

string(CustomerAnnualSpend)
Enum"_0_TO_25K""_25_TO_150K""_150K_TO_300K""_300K_TO_1M""_1_TO_5M""_5M_TO_25M""_25M_TO_75M""_75M_PLUS"
spendTypeCustomerSpendType (string) or null

Customer spend type (contract vs spot pricing)

Any of:

Customer spend type:

  • CONTRACT: Customer operates under contract pricing
  • SPOT: Customer operates on spot market pricing
string(CustomerSpendType)
Enum"CONTRACT""SPOT"
naicsstring or null

NAICS industry code

Example: "336411"
einstring or null

Employer Identification Number

Example: "12-3456789"
dunsstring or null

Dun & Bradstreet number

Example: "123456789"
leadSourcestring or null

How this customer was acquired

Example: "Referral"
dbaNamestring or null

Doing business as name

Example: "Acme Corp DBA"
numberOfEmployeesCustomerNumberOfEmployees (string) or null

Company size by number of employees

Any of:

Number of employees in the company

string(CustomerNumberOfEmployees)
Enum"_0_TO_1""_2_TO_5""_6_TO_9""_10_TO_24""_25_TO_99""_100_TO_249""_250_TO_499""_500_OR_MORE"
externalIdstring or null

External system identifier

Example: "EXT-12345"
currencyCustomerCurrency (string) or null

Preferred currency for transactions

Any of:

Preferred currency for transactions

string(CustomerCurrency)
Enum"USD""CAD""MXN""EUR""GBP""JPY""CNY""AUD""BRL""INR"
creditLimitnumber or null(float)

Maximum credit allowed

Example: 50000
creditUsageWarningnumber or null(float)

Credit usage warning threshold

Example: 40000
freeCreditReqnumber or null(float)

Free credit requirement

Example: 5000
defaultModeCustomerTransportationMode (string) or null

Default transportation mode

Any of:

Transportation mode type

string(CustomerTransportationMode)
Enum"FTL""LTL""AIR""OCEAN""RAIL""INTERMODAL""DRAYAGE""EXPEDITED_GROUND""EXPEDITED_AIR""AUTO"
defaultMarginnumber or null(float)

Default margin percentage (0-1, e.g., 0.15 for 15%)

Example: 0.15
minMarginnumber or null(float)

Minimum margin threshold

Example: 0.1
maxMarginnumber or null(float)

Maximum margin threshold

Example: 0.25
defaultInternalNotesstring or null

Default internal notes template

Example: "Contact via email only"
defaultExternalNotesstring or null

Default external notes template

Example: "Please call 1 hour before delivery"
autoAcceptTenderboolean or null

Auto-accept tender flag

Example: false
groupResourceReference (object) or null

Customer group reference (minimal - id and key only)

Any of:

Reference to another resource (returned in responses)

paymentTermPaymentTermReference (object) or null

Payment term configuration reference with full details

Any of:

Enhanced reference to a payment term resource (returned in responses). Includes full payment term details in addition to id/key.

notesstring or null

Internal notes about this customer

Example: "Prefers email communication"
deactivationReasonCustomerDeactivationReason (string) or null

Reason for deactivation if status is INACTIVE

Any of:

Reason for customer deactivation:

  • NOT_PAYING_INVOICE: Customer is not paying invoices
  • ACQUIRED: Customer was acquired by another company
  • DUPLICATE: Duplicate customer record
  • NOT_IN_BUSINESS: Customer is no longer in business
  • OTHER: Other reason (see deactivationNotes for details)
string(CustomerDeactivationReason)
Enum"NOT_PAYING_INVOICE""ACQUIRED""DUPLICATE""NOT_IN_BUSINESS""OTHER"
deactivationNotesstring or null

Additional details about deactivation

deactivationDatestring or null(date-time)

When the customer was deactivated

Example: null
closedAtstring or null(date-time)

When the customer account was closed

Example: null
closedByUserReference (object) or nullread-only

User who closed the account (full user details)

Any of:

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.

closedNotesstring or null

Notes about account closure

corporateAddressAddress (object) or null

Corporate headquarters address (nested location data)

Any of:

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.

billingAddressAddress (object) or null

Billing address (nested location data)

Any of:

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.

qboCustomerIdstring or null

QuickBooks Online customer ID

Example: null
keystring or null<= 512 characters

Client-defined reference identifier for this customer

Example: "ERP-CUSTOMER-12345"
contactsArray of objects(CustomerContactReference)

Contacts for this customer

createdAtstring(date-time)read-onlyrequired

Timestamp when customer was created

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

Timestamp when customer was last updated

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

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

Example: null
deletedByUserReference (object) or nullread-only

User who deleted the customer (full user details)

Any of:

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.

Response
application/json
{
  "object": "CUSTOMER",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Manufacturing Corp",
  "friendlyId": "A123456",
  "status": "NEW",
  "serviceTier": "TIER_1",
  "website": "https://acme-manufacturing.com",
  "phoneNumber": "+1-555-123-4567",
  "industry": "AGRICULTURE_FORESTRY",
  "annualRevenue": "_0_TO_500K",
  "annualSpend": "_0_TO_25K",
  "spendType": "CONTRACT",
  "naics": "336411",
  "ein": "12-3456789",
  "duns": "123456789",
  "leadSource": "Referral",
  "dbaName": "Acme Corp DBA",
  "numberOfEmployees": "_0_TO_1",
  "externalId": "EXT-12345",
  "currency": "USD",
  "creditLimit": 50000,
  "creditUsageWarning": 40000,
  "freeCreditReq": 5000,
  "defaultMode": "FTL",
  "defaultMargin": 0.15,
  "minMargin": 0.1,
  "maxMargin": 0.25,
  "defaultInternalNotes": "Contact via email only",
  "defaultExternalNotes": "Please call 1 hour before delivery",
  "autoAcceptTender": false,
  "group": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-USER-12345"
  },
  "paymentTerm": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-PAYTERM-NET30",
    "name": "Net 30",
    "description": "Payment due 30 days from invoice date",
    "days": 30,
    "quickPayFee": 0.05,
    "apOnly": false,
    "doNotUse": false,
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z",
    "deletedAt": null
  },
  "notes": "Prefers email communication",
  "deactivationReason": "NOT_PAYING_INVOICE",
  "deactivationNotes": "string",
  "deactivationDate": null,
  "closedAt": null,
  "closedBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-USER-12345",
    "email": "john.doe@example.com",
    "name": "John Doe",
    "phone": "+1-555-123-4567",
    "phoneExt": "123",
    "status": "ACTIVE",
    "avatarId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z",
    "deletedAt": null
  },
  "closedNotes": "string",
  "corporateAddress": {
    "line1": "123 Main St",
    "line2": "Suite 400",
    "city": "Chicago",
    "country": "USA",
    "market": "CHI",
    "latitude": "41.8781",
    "longitude": "-87.6298",
    "isAirportOrAirbase": false,
    "isConstructionOrUtilitySite": false,
    "isSmartyValidated": true,
    "obeysDst": true,
    "cityId": null
  },
  "billingAddress": {
    "line1": "123 Main St",
    "line2": "Suite 400",
    "city": "Chicago",
    "country": "USA",
    "market": "CHI",
    "latitude": "41.8781",
    "longitude": "-87.6298",
    "isAirportOrAirbase": false,
    "isConstructionOrUtilitySite": false,
    "isSmartyValidated": true,
    "obeysDst": true,
    "cityId": null
  },
  "qboCustomerId": null,
  "key": "ERP-CUSTOMER-12345",
  "contacts": [
    { … }
  ],
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T14:30:00Z",
  "deletedAt": null,
  "deletedBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-USER-12345",
    "email": "john.doe@example.com",
    "name": "John Doe",
    "phone": "+1-555-123-4567",
    "phoneExt": "123",
    "status": "ACTIVE",
    "avatarId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z",
    "deletedAt": null
  }
}

Update customer

Request

Partially update a customer. 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
namestring

Customer company name

Example: "Acme Manufacturing Corp"
statusstring(CustomerStatus)

Customer account status (includes lead stages):

  • NEW: New lead, not yet contacted
  • CONTACTED: Initial contact made with lead
  • QUALIFIED: Lead has been qualified as potential customer
  • QUOTED: Quote has been provided to lead
  • NURTURING: Lead being nurtured for future opportunity
  • PENDING: Customer prospect pending activation
  • ACTIVE: Active customer account
  • INACTIVE: Deactivated customer account
  • BLOCKED: Customer account blocked from operations
  • CLOSED: Customer account permanently closed
Enum"NEW""CONTACTED""QUALIFIED""QUOTED""NURTURING""PENDING""ACTIVE""INACTIVE""BLOCKED""CLOSED"
serviceTierCustomerServiceTier (string) or null

Service tier level

Any of:

Service tier level for the customer

string(CustomerServiceTier)
Enum"TIER_1""TIER_2""TIER_3"
websitestring or null

Customer website URL

Example: "https://acme-manufacturing.com"
phoneNumberstring or null

Primary phone number

Example: "+1-555-123-4567"
industryCustomerIndustry (string) or null

Industry classification

Any of:

Industry classification for the customer

string(CustomerIndustry)
Enum"AGRICULTURE_FORESTRY""CONSTRUCTION""CONSUMER_GOODS""EDUCATIONAL_SERVICES""ENTERTAINMENT""FOOD_SERVICES""HEALTHCARE""INDUSTRIAL_MACHINERY""MANUFACTURING""MINING"
annualRevenueCustomerAnnualRevenue (string) or null

Annual revenue range

Any of:

Annual revenue range

string(CustomerAnnualRevenue)
Enum"_0_TO_500K""_500K_TO_3M""_3M_TO_10M""_10M_TO_25M""_25M_TO_50M""_50M_TO_100M""_100M_TO_500M""_500M_PLUS"
annualSpendCustomerAnnualSpend (string) or null

Annual freight spend estimate

Any of:

Annual freight spend estimate range

string(CustomerAnnualSpend)
Enum"_0_TO_25K""_25_TO_150K""_150K_TO_300K""_300K_TO_1M""_1_TO_5M""_5M_TO_25M""_25M_TO_75M""_75M_PLUS"
spendTypeCustomerSpendType (string) or null

Customer spend type (contract vs spot pricing)

Any of:

Customer spend type:

  • CONTRACT: Customer operates under contract pricing
  • SPOT: Customer operates on spot market pricing
string(CustomerSpendType)
Enum"CONTRACT""SPOT"
naicsstring or null

NAICS industry code

Example: "336411"
einstring or null

Employer Identification Number

Example: "12-3456789"
dunsstring or null

Dun & Bradstreet number

Example: "123456789"
leadSourcestring or null

How this customer was acquired

Example: "Referral"
dbaNamestring or null

Doing business as name

Example: "Acme Corp DBA"
numberOfEmployeesCustomerNumberOfEmployees (string) or null

Company size by number of employees

Any of:

Number of employees in the company

string(CustomerNumberOfEmployees)
Enum"_0_TO_1""_2_TO_5""_6_TO_9""_10_TO_24""_25_TO_99""_100_TO_249""_250_TO_499""_500_OR_MORE"
externalIdstring or null

External system identifier

Example: "EXT-12345"
currencyCustomerCurrency (string) or null

Preferred currency for transactions

Any of:

Preferred currency for transactions

string(CustomerCurrency)
Enum"USD""CAD""MXN""EUR""GBP""JPY""CNY""AUD""BRL""INR"
creditLimitnumber or null(float)

Maximum credit allowed

Example: 50000
creditUsageWarningnumber or null(float)

Credit usage warning threshold

Example: 40000
freeCreditReqnumber or null(float)

Free credit requirement

Example: 5000
defaultModeCustomerTransportationMode (string) or null

Default transportation mode

Any of:

Transportation mode type

string(CustomerTransportationMode)
Enum"FTL""LTL""AIR""OCEAN""RAIL""INTERMODAL""DRAYAGE""EXPEDITED_GROUND""EXPEDITED_AIR""AUTO"
defaultMarginnumber or null(float)

Default margin percentage (0-1, e.g., 0.15 for 15%)

Example: 0.15
minMarginnumber or null(float)

Minimum margin threshold

Example: 0.1
maxMarginnumber or null(float)

Maximum margin threshold

Example: 0.25
defaultInternalNotesstring or null

Default internal notes template

Example: "Contact via email only"
defaultExternalNotesstring or null

Default external notes template

Example: "Please call 1 hour before delivery"
autoAcceptTenderboolean or null

Auto-accept tender flag

Example: false
groupIdstring or null(uuid)

Customer group reference

Example: null
paymentTermResourceReferenceInput (ResourceReferenceInput (object)) or null

Payment term configuration reference

Any of:

Reference to another resource by either ID or client key (used in create/update requests)

One of:

Reference to another resource by either ID or client key (used in create/update requests)

notesstring or null

Internal notes

Example: "Prefers email communication"
deactivationReasonCustomerDeactivationReason (string) or null

Reason for deactivation

Any of:

Reason for customer deactivation:

  • NOT_PAYING_INVOICE: Customer is not paying invoices
  • ACQUIRED: Customer was acquired by another company
  • DUPLICATE: Duplicate customer record
  • NOT_IN_BUSINESS: Customer is no longer in business
  • OTHER: Other reason (see deactivationNotes for details)
string(CustomerDeactivationReason)
Enum"NOT_PAYING_INVOICE""ACQUIRED""DUPLICATE""NOT_IN_BUSINESS""OTHER"
deactivationNotesstring or null

Additional deactivation details

deactivationDatestring or null(date-time)

Deactivation date

corporateAddressAddressPatch (object) or null

Corporate address update. Provide partial or full address data to update the existing location. Set to null to clear the address reference.

Any of:

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
billingAddressAddressPatch (object) or null

Billing address update. Provide partial or full address data to update the existing location. Set to null to clear the address reference.

Any of:

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
qboCustomerIdstring or null

QuickBooks Online customer ID

keystring or null<= 512 characters

Client-defined reference identifier

Example: "ERP-CUSTOMER-12345"
curl -i -X PATCH \
  'https://docs.mvmnt.io/_mock/apis/openapi/customers/550e8400-e29b-41d4-a716-446655440000?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Acme Manufacturing Corp",
    "status": "NEW",
    "serviceTier": "TIER_1",
    "website": "https://acme-manufacturing.com",
    "phoneNumber": "+1-555-123-4567",
    "industry": "AGRICULTURE_FORESTRY",
    "annualRevenue": "_0_TO_500K",
    "annualSpend": "_0_TO_25K",
    "spendType": "CONTRACT",
    "naics": "336411",
    "ein": "12-3456789",
    "duns": "123456789",
    "leadSource": "Referral",
    "dbaName": "Acme Corp DBA",
    "numberOfEmployees": "_0_TO_1",
    "externalId": "EXT-12345",
    "currency": "USD",
    "creditLimit": 50000,
    "creditUsageWarning": 40000,
    "freeCreditReq": 5000,
    "defaultMode": "FTL",
    "defaultMargin": 0.15,
    "minMargin": 0.1,
    "maxMargin": 0.25,
    "defaultInternalNotes": "Contact via email only",
    "defaultExternalNotes": "Please call 1 hour before delivery",
    "autoAcceptTender": false,
    "groupId": null,
    "paymentTerm": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    },
    "notes": "Prefers email communication",
    "deactivationReason": "NOT_PAYING_INVOICE",
    "deactivationNotes": "string",
    "deactivationDate": "2019-08-24T14:15:22Z",
    "corporateAddress": {
      "line1": "123 Main St",
      "line2": "Suite 400",
      "city": "Chicago",
      "country": "USA",
      "market": "CHI",
      "latitude": "41.8781",
      "longitude": "-87.6298",
      "isAirportOrAirbase": false,
      "isConstructionOrUtilitySite": false,
      "isSmartyValidated": true,
      "obeysDst": true,
      "cityId": null
    },
    "billingAddress": {
      "line1": "123 Main St",
      "line2": "Suite 400",
      "city": "Chicago",
      "country": "USA",
      "market": "CHI",
      "latitude": "41.8781",
      "longitude": "-87.6298",
      "isAirportOrAirbase": false,
      "isConstructionOrUtilitySite": false,
      "isSmartyValidated": true,
      "obeysDst": true,
      "cityId": null
    },
    "qboCustomerId": "string",
    "key": "ERP-CUSTOMER-12345"
  }'

Responses

Customer updated successfully

Bodyapplication/json
objectstringread-only

Object type identifier

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

Unique customer identifier

Example: "550e8400-e29b-41d4-a716-446655440000"
namestringrequired

Customer company name

Example: "Acme Manufacturing Corp"
friendlyIdstringread-onlyrequired

Human-readable customer identifier, starts with "A"

Example: "A123456"
statusstring(CustomerStatus)required

Customer account status (includes lead stages):

  • NEW: New lead, not yet contacted
  • CONTACTED: Initial contact made with lead
  • QUALIFIED: Lead has been qualified as potential customer
  • QUOTED: Quote has been provided to lead
  • NURTURING: Lead being nurtured for future opportunity
  • PENDING: Customer prospect pending activation
  • ACTIVE: Active customer account
  • INACTIVE: Deactivated customer account
  • BLOCKED: Customer account blocked from operations
  • CLOSED: Customer account permanently closed
Enum"NEW""CONTACTED""QUALIFIED""QUOTED""NURTURING""PENDING""ACTIVE""INACTIVE""BLOCKED""CLOSED"
serviceTierCustomerServiceTier (string) or null

Service tier level

Any of:

Service tier level for the customer

string(CustomerServiceTier)
Enum"TIER_1""TIER_2""TIER_3"
websitestring or null

Customer website URL

Example: "https://acme-manufacturing.com"
phoneNumberstring or null

Primary phone number

Example: "+1-555-123-4567"
industryCustomerIndustry (string) or null

Industry classification

Any of:

Industry classification for the customer

string(CustomerIndustry)
Enum"AGRICULTURE_FORESTRY""CONSTRUCTION""CONSUMER_GOODS""EDUCATIONAL_SERVICES""ENTERTAINMENT""FOOD_SERVICES""HEALTHCARE""INDUSTRIAL_MACHINERY""MANUFACTURING""MINING"
annualRevenueCustomerAnnualRevenue (string) or null

Annual revenue range

Any of:

Annual revenue range

string(CustomerAnnualRevenue)
Enum"_0_TO_500K""_500K_TO_3M""_3M_TO_10M""_10M_TO_25M""_25M_TO_50M""_50M_TO_100M""_100M_TO_500M""_500M_PLUS"
annualSpendCustomerAnnualSpend (string) or null

Annual freight spend estimate

Any of:

Annual freight spend estimate range

string(CustomerAnnualSpend)
Enum"_0_TO_25K""_25_TO_150K""_150K_TO_300K""_300K_TO_1M""_1_TO_5M""_5M_TO_25M""_25M_TO_75M""_75M_PLUS"
spendTypeCustomerSpendType (string) or null

Customer spend type (contract vs spot pricing)

Any of:

Customer spend type:

  • CONTRACT: Customer operates under contract pricing
  • SPOT: Customer operates on spot market pricing
string(CustomerSpendType)
Enum"CONTRACT""SPOT"
naicsstring or null

NAICS industry code

Example: "336411"
einstring or null

Employer Identification Number

Example: "12-3456789"
dunsstring or null

Dun & Bradstreet number

Example: "123456789"
leadSourcestring or null

How this customer was acquired

Example: "Referral"
dbaNamestring or null

Doing business as name

Example: "Acme Corp DBA"
numberOfEmployeesCustomerNumberOfEmployees (string) or null

Company size by number of employees

Any of:

Number of employees in the company

string(CustomerNumberOfEmployees)
Enum"_0_TO_1""_2_TO_5""_6_TO_9""_10_TO_24""_25_TO_99""_100_TO_249""_250_TO_499""_500_OR_MORE"
externalIdstring or null

External system identifier

Example: "EXT-12345"
currencyCustomerCurrency (string) or null

Preferred currency for transactions

Any of:

Preferred currency for transactions

string(CustomerCurrency)
Enum"USD""CAD""MXN""EUR""GBP""JPY""CNY""AUD""BRL""INR"
creditLimitnumber or null(float)

Maximum credit allowed

Example: 50000
creditUsageWarningnumber or null(float)

Credit usage warning threshold

Example: 40000
freeCreditReqnumber or null(float)

Free credit requirement

Example: 5000
defaultModeCustomerTransportationMode (string) or null

Default transportation mode

Any of:

Transportation mode type

string(CustomerTransportationMode)
Enum"FTL""LTL""AIR""OCEAN""RAIL""INTERMODAL""DRAYAGE""EXPEDITED_GROUND""EXPEDITED_AIR""AUTO"
defaultMarginnumber or null(float)

Default margin percentage (0-1, e.g., 0.15 for 15%)

Example: 0.15
minMarginnumber or null(float)

Minimum margin threshold

Example: 0.1
maxMarginnumber or null(float)

Maximum margin threshold

Example: 0.25
defaultInternalNotesstring or null

Default internal notes template

Example: "Contact via email only"
defaultExternalNotesstring or null

Default external notes template

Example: "Please call 1 hour before delivery"
autoAcceptTenderboolean or null

Auto-accept tender flag

Example: false
groupResourceReference (object) or null

Customer group reference (minimal - id and key only)

Any of:

Reference to another resource (returned in responses)

paymentTermPaymentTermReference (object) or null

Payment term configuration reference with full details

Any of:

Enhanced reference to a payment term resource (returned in responses). Includes full payment term details in addition to id/key.

notesstring or null

Internal notes about this customer

Example: "Prefers email communication"
deactivationReasonCustomerDeactivationReason (string) or null

Reason for deactivation if status is INACTIVE

Any of:

Reason for customer deactivation:

  • NOT_PAYING_INVOICE: Customer is not paying invoices
  • ACQUIRED: Customer was acquired by another company
  • DUPLICATE: Duplicate customer record
  • NOT_IN_BUSINESS: Customer is no longer in business
  • OTHER: Other reason (see deactivationNotes for details)
string(CustomerDeactivationReason)
Enum"NOT_PAYING_INVOICE""ACQUIRED""DUPLICATE""NOT_IN_BUSINESS""OTHER"
deactivationNotesstring or null

Additional details about deactivation

deactivationDatestring or null(date-time)

When the customer was deactivated

Example: null
closedAtstring or null(date-time)

When the customer account was closed

Example: null
closedByUserReference (object) or nullread-only

User who closed the account (full user details)

Any of:

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.

closedNotesstring or null

Notes about account closure

corporateAddressAddress (object) or null

Corporate headquarters address (nested location data)

Any of:

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.

billingAddressAddress (object) or null

Billing address (nested location data)

Any of:

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.

qboCustomerIdstring or null

QuickBooks Online customer ID

Example: null
keystring or null<= 512 characters

Client-defined reference identifier for this customer

Example: "ERP-CUSTOMER-12345"
contactsArray of objects(CustomerContactReference)

Contacts for this customer

createdAtstring(date-time)read-onlyrequired

Timestamp when customer was created

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

Timestamp when customer was last updated

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

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

Example: null
deletedByUserReference (object) or nullread-only

User who deleted the customer (full user details)

Any of:

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.

Response
application/json
{
  "object": "CUSTOMER",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Manufacturing Corp",
  "friendlyId": "A123456",
  "status": "NEW",
  "serviceTier": "TIER_1",
  "website": "https://acme-manufacturing.com",
  "phoneNumber": "+1-555-123-4567",
  "industry": "AGRICULTURE_FORESTRY",
  "annualRevenue": "_0_TO_500K",
  "annualSpend": "_0_TO_25K",
  "spendType": "CONTRACT",
  "naics": "336411",
  "ein": "12-3456789",
  "duns": "123456789",
  "leadSource": "Referral",
  "dbaName": "Acme Corp DBA",
  "numberOfEmployees": "_0_TO_1",
  "externalId": "EXT-12345",
  "currency": "USD",
  "creditLimit": 50000,
  "creditUsageWarning": 40000,
  "freeCreditReq": 5000,
  "defaultMode": "FTL",
  "defaultMargin": 0.15,
  "minMargin": 0.1,
  "maxMargin": 0.25,
  "defaultInternalNotes": "Contact via email only",
  "defaultExternalNotes": "Please call 1 hour before delivery",
  "autoAcceptTender": false,
  "group": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-USER-12345"
  },
  "paymentTerm": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-PAYTERM-NET30",
    "name": "Net 30",
    "description": "Payment due 30 days from invoice date",
    "days": 30,
    "quickPayFee": 0.05,
    "apOnly": false,
    "doNotUse": false,
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z",
    "deletedAt": null
  },
  "notes": "Prefers email communication",
  "deactivationReason": "NOT_PAYING_INVOICE",
  "deactivationNotes": "string",
  "deactivationDate": null,
  "closedAt": null,
  "closedBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-USER-12345",
    "email": "john.doe@example.com",
    "name": "John Doe",
    "phone": "+1-555-123-4567",
    "phoneExt": "123",
    "status": "ACTIVE",
    "avatarId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z",
    "deletedAt": null
  },
  "closedNotes": "string",
  "corporateAddress": {
    "line1": "123 Main St",
    "line2": "Suite 400",
    "city": "Chicago",
    "country": "USA",
    "market": "CHI",
    "latitude": "41.8781",
    "longitude": "-87.6298",
    "isAirportOrAirbase": false,
    "isConstructionOrUtilitySite": false,
    "isSmartyValidated": true,
    "obeysDst": true,
    "cityId": null
  },
  "billingAddress": {
    "line1": "123 Main St",
    "line2": "Suite 400",
    "city": "Chicago",
    "country": "USA",
    "market": "CHI",
    "latitude": "41.8781",
    "longitude": "-87.6298",
    "isAirportOrAirbase": false,
    "isConstructionOrUtilitySite": false,
    "isSmartyValidated": true,
    "obeysDst": true,
    "cityId": null
  },
  "qboCustomerId": null,
  "key": "ERP-CUSTOMER-12345",
  "contacts": [
    { … }
  ],
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T14:30:00Z",
  "deletedAt": null,
  "deletedBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-USER-12345",
    "email": "john.doe@example.com",
    "name": "John Doe",
    "phone": "+1-555-123-4567",
    "phoneExt": "123",
    "status": "ACTIVE",
    "avatarId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z",
    "deletedAt": null
  }
}

Delete customer

Request

Soft delete a customer (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/customers/550e8400-e29b-41d4-a716-446655440000?by=key' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Customer deleted successfully

Response
No content

Search customers

Request

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
Security
BearerAuth
Bodyapplication/jsonrequired
criteriaobject(CustomerSearchCriteria)

Search criteria to filter customers

paginationobject(SearchPaginationInput)

Pagination options for search requests

sortArray of objects(SearchSortOption)<= 3 items

Sort options for the search results

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

Optional saved search to load preferences from. When provided, the saved search criteria will be loaded and merged with any explicit criteria.

formatstring

Response format:

  • flat: Returns only indexed fields (default, faster)
  • full: Returns complete customer objects
Default "flat"
Enum"flat""full"
curl -i -X POST \
  https://docs.mvmnt.io/_mock/apis/openapi/customers/search \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "criteria": {
      "id": {
        "operator": "EQUALS",
        "values": [
          "550e8400-e29b-41d4-a716-446655440000"
        ]
      },
      "friendlyId": {
        "operator": "ONE_OF",
        "values": [
          "ACTIVE",
          "PENDING"
        ]
      },
      "name": {
        "operator": "INCLUDES",
        "values": [
          "search term"
        ]
      },
      "dbaName": {
        "operator": "INCLUDES",
        "values": [
          "search term"
        ]
      },
      "status": {
        "operator": "ONE_OF",
        "values": [
          "ACTIVE",
          "PENDING"
        ]
      },
      "city": {
        "operator": "INCLUDES",
        "values": [
          "search term"
        ]
      },
      "state": {
        "operator": "ONE_OF",
        "values": [
          "ACTIVE",
          "PENDING"
        ]
      },
      "location": {
        "operator": "INCLUDES",
        "values": [
          "search term"
        ]
      },
      "zip": {
        "operator": "ONE_OF",
        "values": [
          "ACTIVE",
          "PENDING"
        ]
      },
      "country": {
        "operator": "ONE_OF",
        "values": [
          "ACTIVE",
          "PENDING"
        ]
      },
      "teamId": {
        "operator": "EQUALS",
        "values": [
          "550e8400-e29b-41d4-a716-446655440000"
        ]
      },
      "teamName": {
        "operator": "INCLUDES",
        "values": [
          "search term"
        ]
      },
      "userIds": {
        "operator": "EQUALS",
        "values": [
          "550e8400-e29b-41d4-a716-446655440000"
        ]
      },
      "userNames": {
        "operator": "INCLUDES",
        "values": [
          "search term"
        ]
      },
      "accountOwnerId": {
        "operator": "EQUALS",
        "values": [
          "550e8400-e29b-41d4-a716-446655440000"
        ]
      },
      "accountOwnerName": {
        "operator": "INCLUDES",
        "values": [
          "search term"
        ]
      },
      "operatedById": {
        "operator": "EQUALS",
        "values": [
          "550e8400-e29b-41d4-a716-446655440000"
        ]
      },
      "operatedByName": {
        "operator": "INCLUDES",
        "values": [
          "search term"
        ]
      },
      "primaryContactName": {
        "operator": "INCLUDES",
        "values": [
          "search term"
        ]
      },
      "primaryContactEmail": {
        "operator": "INCLUDES",
        "values": [
          "search term"
        ]
      },
      "primaryContactPhone": {
        "operator": "INCLUDES",
        "values": [
          "search term"
        ]
      },
      "serviceTier": {
        "operator": "ONE_OF",
        "values": [
          "ACTIVE",
          "PENDING"
        ]
      },
      "yearsInBusiness": {
        "operator": "ONE_OF",
        "values": [
          "ACTIVE",
          "PENDING"
        ]
      },
      "numberOfEmployees": {
        "operator": "ONE_OF",
        "values": [
          "ACTIVE",
          "PENDING"
        ]
      },
      "industry": {
        "operator": "ONE_OF",
        "values": [
          "ACTIVE",
          "PENDING"
        ]
      },
      "sic": {
        "operator": "ONE_OF",
        "values": [
          "ACTIVE",
          "PENDING"
        ]
      },
      "naics": {
        "operator": "ONE_OF",
        "values": [
          "ACTIVE",
          "PENDING"
        ]
      },
      "paymentTermName": {
        "operator": "ONE_OF",
        "values": [
          "ACTIVE",
          "PENDING"
        ]
      },
      "creditLimit": {
        "operator": "GREATER_THAN",
        "value": 1000.5
      },
      "outstandingBalance": {
        "operator": "GREATER_THAN",
        "value": 1000.5
      },
      "totalRevenue": {
        "operator": "GREATER_THAN",
        "value": 1000.5
      },
      "totalTransportationCost": {
        "operator": "GREATER_THAN",
        "value": 1000.5
      },
      "totalGrossProfit": {
        "operator": "GREATER_THAN",
        "value": 1000.5
      },
      "ordersCount": {
        "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
      },
      "mostRecentOrderCreationAt": {
        "operator": "AFTER",
        "value": "2025-01-01T00:00:00Z"
      },
      "nextFollowUp": {
        "operator": "BETWEEN",
        "min": "2025-01-01",
        "max": "2025-01-31"
      },
      "lastOutreach": {
        "operator": "AFTER",
        "value": "2025-01-01T00:00:00Z"
      },
      "quickbooksCustomerId": {
        "operator": "ONE_OF",
        "values": [
          "ACTIVE",
          "PENDING"
        ]
      },
      "tags": {
        "operator": "INCLUDES",
        "values": [
          "search term"
        ]
      },
      "createdAt": {
        "operator": "AFTER",
        "value": "2025-01-01T00:00:00Z"
      },
      "updatedAt": {
        "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 customer objects based on format parameter

data[].​objectstringrequired

Object type identifier for discriminating between flat and full response formats

Value"CUSTOMER_SEARCH_ROW"
Discriminator
data[].​idstring(uuid)required
data[].​friendlyIdstringrequired
Example: "CUST-0001"
data[].​namestringrequired
data[].​dbaNamestring or null
data[].​statusstringrequired
Enum"ACTIVE""INACTIVE""PENDING""SUSPENDED""ARCHIVED"
data[].​citystring or null
data[].​statestring or null

State/Province code (uppercase)

data[].​locationstring or null

Computed as "city, state"

data[].​zipstring or null
data[].​countrystring or null

Country code (uppercase)

data[].​teamIdstring or null(uuid)

Team ID (maps from groupId)

data[].​teamNamestring or null

Team name (maps from groupName)

data[].​userIdsArray of strings(uuid)

IDs of users associated with this customer

data[].​userNamesArray of strings

Names of users associated with this customer (may be hidden in some contexts)

data[].​accountOwnerIdstring or null(uuid)
data[].​accountOwnerNamestring or null
data[].​operatedByIdstring or null(uuid)
data[].​operatedByNamestring or null
data[].​primaryContactNamestring or null
data[].​primaryContactEmailstring or null(email)
data[].​primaryContactPhonestring or null
data[].​serviceTierstring or null
data[].​yearsInBusinessstring or null
data[].​numberOfEmployeesstring or null
data[].​industrystring or null
data[].​sicstring or null

Standard Industrial Classification code

data[].​naicsstring or null

North American Industry Classification System code

data[].​paymentTermNamestring or null
data[].​creditLimitnumber or null(float)
data[].​outstandingBalancenumber or null(float)
data[].​totalRevenuenumber or null(float)
data[].​totalTransportationCostnumber or null(float)
data[].​totalGrossProfitnumber or null(float)

Computed as totalRevenue - totalTransportationCost

data[].​ordersCountinteger or null

Number of non-canceled/rejected shipments

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

Win rate percentage (0-100)

data[].​mostRecentOrderCreationAtstring or null(date-time)
data[].​nextFollowUpstring or null(date)
data[].​lastOutreachstring or null(date-time)
data[].​quickbooksCustomerIdstring or null

QuickBooks Online customer ID (maps from qboCustomerId)

data[].​tagsArray of strings

Tag labels

data[].​createdAtstring(date-time)required
data[].​updatedAtstring(date-time)required
paginationobject(SearchPaginationInfo)required

Pagination information for search results

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
}

Get customer payments

Request

List all payments from a specific customer.

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
pageSizeinteger[ 1 .. 100 ]
Default 50
cursorstring
curl -i -X GET \
  'https://docs.mvmnt.io/_mock/apis/openapi/customers/550e8400-e29b-41d4-a716-446655440000/payments?by=key&pageSize=50&cursor=string' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Payments retrieved successfully

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

Get outstanding invoices

Request

List invoices available for payment from a customer.

Returns invoices with status AWAITING_PAYMENT or PARTIALLY_PAID.

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

Responses

Outstanding invoices retrieved

Bodyapplication/json
invoicesArray of objectsrequired
invoices[].​idstring(uuid)
invoices[].​friendlyIdstring
invoices[].​amountnumber
invoices[].​invoiceDatestring(date)
invoices[].​dueDatestring or null(date)
invoices[].​openBalancenumber
invoices[].​isOverdueboolean
invoices[].​paymentsArray of objects
totalOutstandingnumberrequired

Total outstanding balance for customer

Response
application/json
{
  "invoices": [
    { … }
  ],
  "totalOutstanding": 0
}

Customer Contacts

Customer contact management operations

Operations

Documents

Document management operations. Documents are files (PDFs, images) that can be attached to orders, loads, or services.

Operations

Invoices

AR invoice management operations. Invoices represent customer billing for shipment services.

Operations

Loads

Load management operations. Loads represent carrier execution - which carrier is moving the freight.

Operations

Locations

Location management operations

Operations

Location Contacts

Location contact management operations

Operations

Payment Terms

Payment term management operations

Operations

Payments

AR payment management operations. Payments represent received customer payments applied to invoices.

Operations

Quotes

Quote management operations. Quotes are pricing requests/responses that can be converted to shipments.

Operations

Saved Searches

Saved search management operations

Operations

Services

Service (vended service) management operations. Services represent non-carrier vendor work (drayage, customs, warehousing).

Operations

Shipments

Shipment tracking and management operations. Shipments contain orders, loads, and services.

Operations

Teams

Team management operations

Operations

Users

User management operations

Operations

Vendors

Vendor management operations

Operations

Vendor Contacts

Vendor contact management operations

Operations

Vendor Payment Methods

Vendor payment method management operations

Operations

Event Notifications

Webhooks