# Create a new vendor

Create a new vendor within an organization.

Vendors represent service providers (warehousing, storage, etc.) that are not carriers.

Endpoint: POST /vendors
Version: 1.0.0
Security: BearerAuth

## Request fields (application/json):

  - `name` (string, required)
    Vendor legal name
    Example: "ABC Warehouse Services"

  - `key` (string)
    Client-defined reference identifier
    Example: "ERP-VENDOR-ABC-001"

  - `email` (string)
    Primary email address
    Example: "billing@abcwarehouse.com"

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

  - `status` (string)
    Vendor status
    Example: "ACTIVE"

  - `notes` (string)
    Internal notes about the vendor
    Example: "Preferred vendor for warehouse services"

  - `taxId` (string)
    Tax identification number
    Example: "12-3456789"

  - `currency` (string)
    Preferred currency for transactions
    Enum: "USD", "CAD", "MXN", "EUR", "GBP"

  - `corporateAddress` (object)
    Corporate headquarters address

  - `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 for invoices

  - `paymentTermId` (string)
    Payment term ID
    Example: "550e8400-e29b-41d4-a716-446655440001"

  - `isMvmnt` (boolean)
    Whether this vendor is MVMNT itself

  - `requiredDocuments` (array)
    List of required document types
    Example: ["W9","INSURANCE_CERTIFICATE"]

## Response 201 fields (application/json):

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

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

  - `friendlyId` (string, required)
    Human-readable vendor identifier
    Example: "V123456"

  - `name` (string, required)
    Vendor legal name
    Example: "ABC Warehouse Services"

  - `key` (string,null)
    Client-defined reference identifier
    Example: "ERP-VENDOR-ABC-001"

  - `email` (string,null)
    Primary email address
    Example: "billing@abcwarehouse.com"

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

  - `status` (string,null)
    Vendor status
    Example: "ACTIVE"

  - `notes` (string,null)
    Internal notes about the vendor
    Example: "Preferred vendor for warehouse services"

  - `taxId` (string,null)
    Tax identification number
    Example: "12-3456789"

  - `currency` (any)
    Preferred currency for transactions

  - `corporateAddress` (any)
    Corporate headquarters address

  - `billingAddress` (any)
    Billing address for invoices

  - `paymentTerm` (any)
    Payment terms for this vendor

  - `isMvmnt` (boolean,null)
    Whether this vendor is MVMNT itself

  - `requiredDocuments` (array,null)
    List of required document types
    Example: ["W9","INSURANCE_CERTIFICATE"]

  - `paymentMethods` (array)
    Payment methods configured for this vendor

  - `paymentMethods.id` (string, required)
    Unique vendor payment method identifier
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `paymentMethods.paymentMethodType` (string, required)
    How payment is made
    Enum: "ACH_WIRE", "ZELLE", "VENMO", "ACH", "CHECK", "WIRE", "CAD_EFT", "TRIUMPH_PAY", "COMCHECK", "EFS", "ECHECK"

  - `paymentMethods.status` (string,null)
    Payment method status
    Example: "ACTIVE"

  - `paymentMethods.isPreferred` (boolean,null)
    Whether this is the preferred payment method
    Example: true

  - `paymentMethods.email` (string,null)
    Email address for payment notifications
    Example: "payments@vendor.com"

  - `paymentMethods.phone` (string,null)
    Phone number for payment contact
    Example: "+1-555-123-4567"

  - `paymentMethods.companyName` (string,null)
    Company name for this payment method
    Example: "Vendor Payments LLC"

  - `paymentMethods.username` (string,null)
    Username for payment platforms
    Example: "vendor_payments"

  - `paymentMethods.bankName` (string,null)
    Bank name
    Example: "Chase Bank"

  - `paymentMethods.bankAddress` (string,null)
    Bank address
    Example: "123 Bank Street, Dallas, TX 75201"

  - `paymentMethods.accountName` (string,null)
    Bank account holder name
    Example: "Vendor Services Inc"

  - `paymentMethods.accountNumber` (string,null)
    Bank account number (masked in responses)
    Example: "****1234"

  - `paymentMethods.abaAch` (string,null)
    ABA/ACH routing number
    Example: "021000021"

  - `paymentMethods.wire` (string,null)
    Wire transfer routing number
    Example: "026009593"

  - `paymentMethods.swiftCode` (string,null)
    SWIFT/BIC code
    Example: "CHASUS33"

  - `paymentMethods.eftInstitution` (string,null)
    EFT institution number (Canadian banking)
    Example: "001"

  - `paymentMethods.eftTransit` (string,null)
    EFT transit number (Canadian banking)
    Example: "00010"

  - `paymentMethods.clabe` (string,null)
    CLABE number (Mexican banking)
    Example: "012180001234567897"

  - `paymentMethods.currency` (string,null)
    Preferred currency code
    Example: "USD"

  - `paymentMethods.paymentTerm` (any)
    Payment terms

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

  - `paymentMethods.updatedAt` (string, required)
    When the payment method was last updated
    Example: "2025-01-15T14:30:00Z"

  - `paymentMethods.deletedAt` (string,null)
    When the payment method was soft deleted

  - `paymentMethods.deletedBy` (any)
    User who deleted this payment method

  - `contacts` (array)
    Contacts for this vendor

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

  - `contacts.email` (string,null)
    Contact email address
    Example: "john.smith@abcwarehouse.com"

  - `contacts.phone` (string,null)
    Contact phone number
    Example: "+1-555-123-4567"

  - `contacts.role` (string,null)
    Contact role or title (deprecated - use roles array)
    Example: "Billing Manager"

  - `contacts.roles` (array,null)
    Types/roles this contact serves
    Enum: "AGENT", "BILLING", "OPERATION", "OWNER"

  - `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

  - `deletedBy` (any)
    User who deleted this vendor (full user details)

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

  - `updatedAt` (string, required)
    When the vendor was last updated
    Example: "2025-01-15T14:30:00Z"

  - `deletedAt` (string,null)
    When the vendor was soft deleted (null if active)

## 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 409 fields (application/json):

  - `error` (string, required)
    Error code

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

## Response 500 fields (application/json):

  - `error` (string, required)
    Error code

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