# Create customer

Create a new customer in your organization

Endpoint: POST /customers
Version: 1.0.0
Security: BearerAuth

## Request fields (application/json):

  - `name` (string, required)
    Customer company name (required)
    Example: "Acme Manufacturing Corp"

  - `status` (string, 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"

  - `serviceTier` (string)
    Service tier level for the customer
    Enum: "TIER_1", "TIER_2", "TIER_3"

  - `website` (string)
    Customer website URL
    Example: "https://acme-manufacturing.com"

  - `phoneNumber` (string)
    Primary phone number
    Example: "+1-555-123-4567"

  - `industry` (string)
    Industry classification for the customer
    Enum: "AGRICULTURE_FORESTRY", "CONSTRUCTION", "CONSUMER_GOODS", "EDUCATIONAL_SERVICES", "ENTERTAINMENT", "FOOD_SERVICES", "HEALTHCARE", "INDUSTRIAL_MACHINERY", "MANUFACTURING", "MINING", "RETAIL_TRADE", "TRANSPORTATION_WAREHOUSING", "UTILITIES", "WHOLESALE_TRADE"

  - `annualRevenue` (string)
    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"

  - `annualSpend` (string)
    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"

  - `spendType` (string)
    Customer spend type:
- CONTRACT: Customer operates under contract pricing
- SPOT: Customer operates on spot market pricing
    Enum: "CONTRACT", "SPOT"

  - `naics` (string)
    NAICS industry code
    Example: "336411"

  - `ein` (string)
    Employer Identification Number
    Example: "12-3456789"

  - `duns` (string)
    Dun & Bradstreet number
    Example: "123456789"

  - `leadSource` (string)
    How this customer was acquired
    Example: "Referral"

  - `dbaName` (string)
    Doing business as name
    Example: "Acme Corp DBA"

  - `numberOfEmployees` (string)
    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"

  - `externalId` (string)
    External system identifier
    Example: "EXT-12345"

  - `currency` (string)
    Preferred currency for transactions
    Enum: "USD", "CAD", "MXN", "EUR", "GBP", "JPY", "CNY", "AUD", "BRL", "INR", "KRW", "RUB", "SAR", "TRY", "IDR", "ARS", "ZAR"

  - `creditLimit` (number)
    Maximum credit allowed
    Example: 50000

  - `creditUsageWarning` (number)
    Credit usage warning threshold
    Example: 40000

  - `freeCreditReq` (number)
    Free credit requirement
    Example: 5000

  - `defaultMode` (string)
    Transportation mode type
    Enum: "FTL", "LTL", "AIR", "OCEAN", "RAIL", "INTERMODAL", "DRAYAGE", "EXPEDITED_GROUND", "EXPEDITED_AIR", "AUTO", "PTL"

  - `defaultMargin` (number)
    Default margin percentage (0-1, e.g., 0.15 for 15%)
    Example: 0.15

  - `minMargin` (number)
    Minimum margin threshold
    Example: 0.1

  - `maxMargin` (number)
    Maximum margin threshold
    Example: 0.25

  - `defaultInternalNotes` (string)
    Default internal notes template
    Example: "Contact via email only"

  - `defaultExternalNotes` (string)
    Default external notes template
    Example: "Please call 1 hour before delivery"

  - `autoAcceptTender` (boolean)
    Auto-accept tender flag

  - `groupId` (string)
    Customer group reference

  - `paymentTerm` (any)

  - `notes` (string)
    Internal notes about this customer
    Example: "Prefers email communication"

  - `deactivationReason` (string)
    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"

  - `deactivationNotes` (string)
    Additional details about deactivation

  - `deactivationDate` (string)
    When the customer was deactivated

  - `corporateAddress` (object)
    Corporate headquarters address (will create new location record)

  - `corporateAddress.line1` (string, required)
    Primary street address line
    Example: "123 Main St"

  - `corporateAddress.line2` (string)
    Secondary address line (suite, floor, etc.)
    Example: "Suite 400"

  - `corporateAddress.city` (string, required)
    City name
    Example: "Chicago"

  - `corporateAddress.country` (string, required)
    Country name or code
    Example: "USA"

  - `corporateAddress.market` (string, required)
    Market or region identifier
    Example: "CHI"

  - `corporateAddress.latitude` (string)
    Latitude coordinate
    Example: "41.8781"

  - `corporateAddress.longitude` (string)
    Longitude coordinate
    Example: "-87.6298"

  - `corporateAddress.isAirportOrAirbase` (boolean)
    Whether this location is an airport or airbase

  - `corporateAddress.isConstructionOrUtilitySite` (boolean)
    Whether this location is a construction or utility site

  - `corporateAddress.isSmartyValidated` (boolean)
    Whether address has been validated by SmartyStreets
    Example: true

  - `corporateAddress.obeysDst` (boolean)
    Whether this location observes daylight saving time
    Example: true

  - `corporateAddress.cityId` (string)
    Reference to standardized city record (internal use)

  - `billingAddress` (object)
    Billing address (will create new location record)

  - `qboCustomerId` (string)
    QuickBooks Online customer ID

  - `key` (string)
    Client-defined reference identifier
    Example: "ERP-CUSTOMER-12345"

## Response 201 fields (application/json):

  - `object` (string)
    Object type identifier
    Enum: "CUSTOMER"

  - `id` (string, required)
    Unique customer identifier
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `name` (string, required)
    Customer company name
    Example: "Acme Manufacturing Corp"

  - `friendlyId` (string, required)
    Human-readable customer identifier, starts with "A"
    Example: "A123456"

  - `status` (string, 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"

  - `serviceTier` (any)
    Service tier level

  - `website` (string,null)
    Customer website URL
    Example: "https://acme-manufacturing.com"

  - `phoneNumber` (string,null)
    Primary phone number
    Example: "+1-555-123-4567"

  - `industry` (any)
    Industry classification

  - `annualRevenue` (any)
    Annual revenue range

  - `annualSpend` (any)
    Annual freight spend estimate

  - `spendType` (any)
    Customer spend type (contract vs spot pricing)

  - `naics` (string,null)
    NAICS industry code
    Example: "336411"

  - `ein` (string,null)
    Employer Identification Number
    Example: "12-3456789"

  - `duns` (string,null)
    Dun & Bradstreet number
    Example: "123456789"

  - `leadSource` (string,null)
    How this customer was acquired
    Example: "Referral"

  - `dbaName` (string,null)
    Doing business as name
    Example: "Acme Corp DBA"

  - `numberOfEmployees` (any)
    Company size by number of employees

  - `externalId` (string,null)
    External system identifier
    Example: "EXT-12345"

  - `currency` (any)
    Preferred currency for transactions

  - `creditLimit` (number,null)
    Maximum credit allowed
    Example: 50000

  - `creditUsageWarning` (number,null)
    Credit usage warning threshold
    Example: 40000

  - `freeCreditReq` (number,null)
    Free credit requirement
    Example: 5000

  - `defaultMode` (any)
    Default transportation mode

  - `defaultMargin` (number,null)
    Default margin percentage (0-1, e.g., 0.15 for 15%)
    Example: 0.15

  - `minMargin` (number,null)
    Minimum margin threshold
    Example: 0.1

  - `maxMargin` (number,null)
    Maximum margin threshold
    Example: 0.25

  - `defaultInternalNotes` (string,null)
    Default internal notes template
    Example: "Contact via email only"

  - `defaultExternalNotes` (string,null)
    Default external notes template
    Example: "Please call 1 hour before delivery"

  - `autoAcceptTender` (boolean,null)
    Auto-accept tender flag

  - `group` (any)
    Customer group reference (minimal - id and key only)

  - `paymentTerm` (any)
    Payment term configuration reference with full details

  - `notes` (string,null)
    Internal notes about this customer
    Example: "Prefers email communication"

  - `deactivationReason` (any)
    Reason for deactivation if status is INACTIVE

  - `deactivationNotes` (string,null)
    Additional details about deactivation

  - `deactivationDate` (string,null)
    When the customer was deactivated

  - `closedAt` (string,null)
    When the customer account was closed

  - `closedBy` (any)
    User who closed the account (full user details)

  - `closedNotes` (string,null)
    Notes about account closure

  - `corporateAddress` (any)
    Corporate headquarters address (nested location data)

  - `billingAddress` (any)
    Billing address (nested location data)

  - `qboCustomerId` (string,null)
    QuickBooks Online customer ID

  - `key` (string,null)
    Client-defined reference identifier for this customer
    Example: "ERP-CUSTOMER-12345"

  - `contacts` (array)
    Contacts for this customer

  - `contacts.id` (string, required)
    Unique contact identifier
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `contacts.key` (string,null)
    Client-defined reference identifier
    Example: "ERP-CONTACT-JOHN-001"

  - `contacts.name` (string, required)
    Contact person's name
    Example: "John Smith"

  - `contacts.contactInfo` (object, required)
    Contact information details (email, phone, title)

  - `contacts.contactInfo.name` (string, required)
    Contact person's full name
    Example: "John Smith"

  - `contacts.contactInfo.email` (string,null)
    Email address
    Example: "john.smith@example.com"

  - `contacts.contactInfo.phoneNumber` (string,null)
    Phone number
    Example: "+1-555-0100"

  - `contacts.contactInfo.title` (string,null)
    Job title or position
    Example: "Operations Manager"

  - `contacts.phoneExtension` (string,null)
    Phone extension specific to this contact role
    Example: "1234"

  - `contacts.isPrimary` (boolean, required)
    Whether this is the primary contact
    Example: true

  - `contacts.contactTypes` (array,null)
    Types/roles this contact serves
    Enum: "ACCOUNT_MANAGER", "BILLING", "DOCK_SHIPPING", "EMERGENCY", "LOCATION_MANAGER", "OWNER", "PROCUREMENT", "PURCHASING", "RATES_PRICING", "RECEIVING", "SHIPPING"

  - `contacts.notifications` (array,null)
    Shipment notification types
    Enum: "SHIPMENT_DELIVERED", "SHIPMENT_IN_TRANSIT", "SHIPMENT_LOADING", "SHIPMENT_OUT_FOR_DELIVERY", "SHIPMENT_PICKED_UP", "SHIPMENT_TENDER_REJECTED", "SHIPMENT_UNLOADING"

  - `contacts.invitedUser` (any)
    User account invited/created for this contact

  - `contacts.deletedBy` (any)
    User who deleted this contact

  - `contacts.createdAt` (string, required)
    When the contact was created
    Example: "2025-01-15T10:00:00Z"

  - `contacts.deletedAt` (string,null)
    When the contact was soft deleted

  - `createdAt` (string, required)
    Timestamp when customer was created
    Example: "2025-01-15T10:00:00Z"

  - `updatedAt` (string, required)
    Timestamp when customer was last updated
    Example: "2025-01-15T14:30:00Z"

  - `deletedAt` (string,null)
    Timestamp when customer was soft-deleted (null if active)

  - `deletedBy` (any)
    User who deleted the customer (full user details)

## Response 400 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 401 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 422 fields (application/json):

  - `error` (string, required)
    Error code
    Example: "validation_error"

  - `message` (string, required)
    Human-readable error message

  - `details` (array, required)
    Validation error details

  - `details.field` (string, required)
    Field name that failed validation

  - `details.message` (string, required)
    Validation error message

## Response 429 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message