Skip to content
API Reference/
/
Filter 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/

Companies

Operations

Carrier Contacts

Operations

Carriers

Operations

Carrier Factors

Operations

Carrier Payment Methods

Operations

Customer Contacts

Operations

Customers

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)
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
Enum"NEW""CONTACTED""QUALIFIED""QUOTED""NURTURING""PENDING""ACTIVE""INACTIVE""BLOCKED""CLOSED"
serviceTierstring(CustomerServiceTier)
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)
Enum"AGRICULTURE_FORESTRY""CONSTRUCTION""CONSUMER_GOODS""EDUCATIONAL_SERVICES""ENTERTAINMENT""FOOD_SERVICES""HEALTHCARE""INDUSTRIAL_MACHINERY""MANUFACTURING""MINING"
annualRevenuestring(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"
annualSpendstring(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"
spendTypestring(CustomerSpendType)
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)
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)
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)
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)
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)
billingAddressobject(AddressInput)
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
Enum"NEW""CONTACTED""QUALIFIED""QUOTED""NURTURING""PENDING""ACTIVE""INACTIVE""BLOCKED""CLOSED"
serviceTierCustomerServiceTier (string) or null
Any of:

Service tier level for the customer

string CustomerServiceTier Recursive
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
Any of:

Industry classification for the customer

string CustomerIndustry Recursive
annualRevenueCustomerAnnualRevenue (string) or null
Any of:

Annual revenue range

string CustomerAnnualRevenue Recursive
annualSpendCustomerAnnualSpend (string) or null
Any of:

Annual freight spend estimate range

string CustomerAnnualSpend Recursive
spendTypeCustomerSpendType (string) or null
Any of:

Customer spend type:

  • CONTRACT: Customer operates under contract pricing
  • SPOT: Customer operates on spot market pricing
string CustomerSpendType Recursive
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
Any of:

Number of employees in the company

string CustomerNumberOfEmployees Recursive
externalIdstring or null

External system identifier

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

Preferred currency for transactions

string CustomerCurrency Recursive
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
Any of:

Transportation mode type

string CustomerTransportationMode Recursive
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
Any of:

Reference to another resource (returned in responses)

object ResourceReference Recursive
paymentTermPaymentTermReference (object) or null
Any of:

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

object PaymentTermReference Recursive
notesstring or null

Internal notes about this customer

Example: "Prefers email communication"
deactivationReasonCustomerDeactivationReason (string) or null
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 Recursive
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
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.

object UserReference Recursive
closedNotesstring or null

Notes about account closure

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

object Address Recursive
billingAddressAddress (object) or null
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.

object Address Recursive
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
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.

object UserReference Recursive
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
Enum"NEW""CONTACTED""QUALIFIED""QUOTED""NURTURING""PENDING""ACTIVE""INACTIVE""BLOCKED""CLOSED"
serviceTierCustomerServiceTier (string) or null
Any of:

Service tier level for the customer

string CustomerServiceTier Recursive
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
Any of:

Industry classification for the customer

string CustomerIndustry Recursive
annualRevenueCustomerAnnualRevenue (string) or null
Any of:

Annual revenue range

string CustomerAnnualRevenue Recursive
annualSpendCustomerAnnualSpend (string) or null
Any of:

Annual freight spend estimate range

string CustomerAnnualSpend Recursive
spendTypeCustomerSpendType (string) or null
Any of:

Customer spend type:

  • CONTRACT: Customer operates under contract pricing
  • SPOT: Customer operates on spot market pricing
string CustomerSpendType Recursive
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
Any of:

Number of employees in the company

string CustomerNumberOfEmployees Recursive
externalIdstring or null

External system identifier

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

Preferred currency for transactions

string CustomerCurrency Recursive
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
Any of:

Transportation mode type

string CustomerTransportationMode Recursive
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
Any of:

Reference to another resource (returned in responses)

object ResourceReference Recursive
paymentTermPaymentTermReference (object) or null
Any of:

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

object PaymentTermReference Recursive
notesstring or null

Internal notes about this customer

Example: "Prefers email communication"
deactivationReasonCustomerDeactivationReason (string) or null
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 Recursive
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
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.

object UserReference Recursive
closedNotesstring or null

Notes about account closure

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

object Address Recursive
billingAddressAddress (object) or null
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.

object Address Recursive
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
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.

object UserReference Recursive
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)
Enum"NEW""CONTACTED""QUALIFIED""QUOTED""NURTURING""PENDING""ACTIVE""INACTIVE""BLOCKED""CLOSED"
serviceTierCustomerServiceTier (string) or null
Any of:

Service tier level for the customer

string CustomerServiceTier Recursive
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
Any of:

Industry classification for the customer

string CustomerIndustry Recursive
annualRevenueCustomerAnnualRevenue (string) or null
Any of:

Annual revenue range

string CustomerAnnualRevenue Recursive
annualSpendCustomerAnnualSpend (string) or null
Any of:

Annual freight spend estimate range

string CustomerAnnualSpend Recursive
spendTypeCustomerSpendType (string) or null
Any of:

Customer spend type:

  • CONTRACT: Customer operates under contract pricing
  • SPOT: Customer operates on spot market pricing
string CustomerSpendType Recursive
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
Any of:

Number of employees in the company

string CustomerNumberOfEmployees Recursive
externalIdstring or null

External system identifier

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

Preferred currency for transactions

string CustomerCurrency Recursive
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
Any of:

Transportation mode type

string CustomerTransportationMode Recursive
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
Any of:
One of:
One of:

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

object ResourceReferenceInput Recursive
notesstring or null

Internal notes

Example: "Prefers email communication"
deactivationReasonCustomerDeactivationReason (string) or null
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 Recursive
deactivationNotesstring or null

Additional deactivation details

deactivationDatestring or null(date-time)

Deactivation date

corporateAddressAddressPatch (object) or null
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
object AddressPatch Recursive
billingAddressAddressPatch (object) or null
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
object AddressPatch Recursive
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
Enum"NEW""CONTACTED""QUALIFIED""QUOTED""NURTURING""PENDING""ACTIVE""INACTIVE""BLOCKED""CLOSED"
serviceTierCustomerServiceTier (string) or null
Any of:

Service tier level for the customer

string CustomerServiceTier Recursive
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
Any of:

Industry classification for the customer

string CustomerIndustry Recursive
annualRevenueCustomerAnnualRevenue (string) or null
Any of:

Annual revenue range

string CustomerAnnualRevenue Recursive
annualSpendCustomerAnnualSpend (string) or null
Any of:

Annual freight spend estimate range

string CustomerAnnualSpend Recursive
spendTypeCustomerSpendType (string) or null
Any of:

Customer spend type:

  • CONTRACT: Customer operates under contract pricing
  • SPOT: Customer operates on spot market pricing
string CustomerSpendType Recursive
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
Any of:

Number of employees in the company

string CustomerNumberOfEmployees Recursive
externalIdstring or null

External system identifier

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

Preferred currency for transactions

string CustomerCurrency Recursive
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
Any of:

Transportation mode type

string CustomerTransportationMode Recursive
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
Any of:

Reference to another resource (returned in responses)

object ResourceReference Recursive
paymentTermPaymentTermReference (object) or null
Any of:

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

object PaymentTermReference Recursive
notesstring or null

Internal notes about this customer

Example: "Prefers email communication"
deactivationReasonCustomerDeactivationReason (string) or null
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 Recursive
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
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.

object UserReference Recursive
closedNotesstring or null

Notes about account closure

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

object Address Recursive
billingAddressAddress (object) or null
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.

object Address Recursive
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
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.

object UserReference Recursive
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)
paginationobject(SearchPaginationInput)
sortArray of objects(SearchSortOption)<= 3 items

Sort options for the search results

Example: [{"field":"createdAt","order":"desc"}]
savedSearchobject(SavedSearchLookup)
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.​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
}

Locations

Operations

Location Contacts

Operations

Payment Terms

Operations

Teams

Operations

Users

Operations

Vendors

Operations

Vendor Contacts

Operations

Vendor Payment Methods

Operations

Saved Searches

Operations

Event Notifications

Webhooks