openapi: 3.1.0
info:
  title: MVMNT API
  version: 1.0.0
  description: >
    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](/getting-started/authentication)

    for details.


    ### Token Endpoint


    ```

    POST https://api.mvmnt.io/oauth2/token

    ```


    #### Request


    **Headers:**

    ```http

    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


    ```bash

    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`


    ```json

    {
      "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)
  contact:
    name: MVMNT Support
    email: support@mvmnt.io
    url: https://docs.mvmnt.io
  license:
    name: Proprietary
    url: https://mvmnt.io/legal/terms
  x-parsed-md-description:
    result:
      - $$mdtype: Node
        errors: []
        lines:
          - 0
          - 2
        inline: false
        attributes: {}
        children:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 2
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 2
                inline: true
                attributes:
                  content: >-
                    The MVMNT API enables you to automate freight brokerage
                    workflows by integrating
                children: []
                type: text
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 2
                inline: true
                attributes: {}
                children: []
                type: softbreak
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 2
                inline: true
                attributes:
                  content: directly with our Transportation Management System.
                children: []
                type: text
                annotations: []
                slots: {}
            type: inline
            annotations: []
            slots: {}
        type: paragraph
        annotations: []
        slots: {}
      - $$mdtype: Node
        errors: []
        lines:
          - 3
          - 4
        inline: false
        attributes:
          level: 2
        children:
          - $$mdtype: Node
            errors: []
            lines:
              - 3
              - 4
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 3
                  - 4
                inline: true
                attributes:
                  content: Authentication
                children: []
                type: text
                annotations: []
                slots: {}
            type: inline
            annotations: []
            slots: {}
        type: heading
        annotations: []
        slots: {}
      - $$mdtype: Node
        errors: []
        lines:
          - 5
          - 6
        inline: false
        attributes: {}
        children:
          - $$mdtype: Node
            errors: []
            lines:
              - 5
              - 6
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 5
                  - 6
                inline: true
                attributes:
                  content: 'OAuth 2.0 client credentials flow. See '
                children: []
                type: text
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 5
                  - 6
                inline: true
                attributes:
                  href: /getting-started/authentication
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 5
                      - 6
                    inline: true
                    attributes:
                      content: Authentication Guide
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: link
                annotations: []
                slots: {}
                redocly:::linkOriginal:href: /getting-started/authentication
              - $$mdtype: Node
                errors: []
                lines:
                  - 5
                  - 6
                inline: true
                attributes:
                  content: ' for details.'
                children: []
                type: text
                annotations: []
                slots: {}
            type: inline
            annotations: []
            slots: {}
        type: paragraph
        annotations: []
        slots: {}
servers:
  - url: https://api.mvmnt.io/v1
    description: Production
webhooks:
  your-endpoint:
    post:
      summary: Webhook Event
      description: >
        All webhook events are delivered to your configured endpoint URL.


        The `event` field in the payload determines which type of webhook was
        triggered.

        Your endpoint should handle all event types or gracefully ignore unknown
        events.


        **Event Types:**

        - Entity changes: `CUSTOMER_*`, `COMPANY_*`, `CARRIER_*`,
        `CUSTOMER_CONTACT_*`

        - Shipment events: `SHIPMENT_DELIVERED`, `SHIPMENT_BOOKED`,
        `SHIPMENT_DISPATCHED`, etc.

        - Financial events: `CARRIER_INVOICE_CREATED`,
        `CUSTOMER_PAYMENT_CREATED`, etc.


        **Security:** All webhook requests include an `x-api-key` header
        containing your webhook token configured in the MVMNT UI.


        **Best Practices:**

        - Return 200 OK quickly and process asynchronously

        - Implement idempotency using event ID and timestamp

        - Handle unknown event types gracefully for forward compatibility
      operationId: webhookCallback
      tags:
        - Event Notifications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookDelivery'
            examples:
              customer_created:
                summary: Customer created
                value:
                  sentAt: '2025-01-15T14:30:05Z'
                  events:
                    - event: CUSTOMER_CREATED
                      timestamp: '2025-01-15T14:30:00Z'
                      data:
                        id: 660e8400-e29b-41d4-a716-446655440000
                        name: Acme Corporation
                        friendlyId: A123456
                        status: ACTIVE
                        serviceTier: PLATINUM
                        website: https://acme-manufacturing.com
                        phoneNumber: +1-555-123-4567
                        industry: MANUFACTURING
                        annualRevenue: OVER_100M
                        annualSpend: 10M_TO_50M
                        spendType: CONTRACT
                        naics: '336411'
                        ein: 12-3456789
                        duns: '123456789'
                        leadSource: Referral
                        dbaName: Acme Corp DBA
                        numberOfEmployees: 1000_TO_5000
                        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: null
                        paymentTerm:
                          id: 123e4567-e89b-12d3-a456-426614174000
                          name: Net 30
                          key: null
                        notes: Prefers email communication
                        deactivationReason: null
                        deactivationNotes: null
                        deactivationDate: null
                        closedAt: null
                        closedBy: null
                        closedNotes: null
                        corporateAddress:
                          addressLine1: 123 Corporate Blvd
                          addressLine2: Suite 100
                          city: Chicago
                          state: IL
                          postalCode: '60601'
                          country: USA
                          latitude: 41.8781
                          longitude: -87.6298
                        billingAddress:
                          addressLine1: 456 Billing Ave
                          addressLine2: null
                          city: Chicago
                          state: IL
                          postalCode: '60602'
                          country: USA
                          latitude: 41.8827
                          longitude: -87.6233
                        qboCustomerId: null
                        key: ERP-CUSTOMER-12345
                        createdAt: '2025-01-15T14:30:00Z'
                        updatedAt: '2025-01-15T14:30:00Z'
                        deletedAt: null
                      diff: null
              customer_updated:
                summary: Customer updated with diff
                value:
                  sentAt: '2025-01-15T15:45:05Z'
                  events:
                    - event: CUSTOMER_UPDATED
                      timestamp: '2025-01-15T15:45:00Z'
                      data:
                        id: 660e8400-e29b-41d4-a716-446655440000
                        name: Acme Corporation
                        friendlyId: A123456
                        status: INACTIVE
                        serviceTier: GOLD
                        website: https://acme-manufacturing.com
                        phoneNumber: +1-555-999-8888
                        industry: MANUFACTURING
                        annualRevenue: OVER_100M
                        annualSpend: 50M_TO_100M
                        spendType: CONTRACT
                        naics: '336411'
                        ein: 12-3456789
                        duns: '123456789'
                        leadSource: Referral
                        dbaName: Acme Corp DBA
                        numberOfEmployees: 1000_TO_5000
                        externalId: EXT-12345
                        currency: USD
                        creditLimit: 75000
                        creditUsageWarning: 60000
                        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: null
                        paymentTerm:
                          id: 123e4567-e89b-12d3-a456-426614174000
                          name: Net 30
                          key: null
                        notes: Prefers email communication. Account under review.
                        deactivationReason: PAYMENT_ISSUES
                        deactivationNotes: Multiple late payments
                        deactivationDate: '2025-01-15T15:45:00Z'
                        closedAt: null
                        closedBy: null
                        closedNotes: null
                        corporateAddress:
                          addressLine1: 123 Corporate Blvd
                          addressLine2: Suite 100
                          city: Chicago
                          state: IL
                          postalCode: '60601'
                          country: USA
                          latitude: 41.8781
                          longitude: -87.6298
                        billingAddress:
                          addressLine1: 456 Billing Ave
                          addressLine2: null
                          city: Chicago
                          state: IL
                          postalCode: '60602'
                          country: USA
                          latitude: 41.8827
                          longitude: -87.6233
                        qboCustomerId: null
                        key: ERP-CUSTOMER-12345
                        createdAt: '2025-01-15T14:30:00Z'
                        updatedAt: '2025-01-15T15:45:00Z'
                        deletedAt: null
                      diff:
                        - type: UPDATE
                          key: status
                          value: INACTIVE
                          oldValue: ACTIVE
                        - type: UPDATE
                          key: serviceTier
                          value: GOLD
                          oldValue: PLATINUM
                        - type: UPDATE
                          key: phoneNumber
                          value: +1-555-999-8888
                          oldValue: +1-555-123-4567
                        - type: UPDATE
                          key: annualSpend
                          value: 50M_TO_100M
                          oldValue: 10M_TO_50M
                        - type: UPDATE
                          key: creditLimit
                          value: 75000
                          oldValue: 50000
                        - type: UPDATE
                          key: creditUsageWarning
                          value: 60000
                          oldValue: 40000
                        - type: UPDATE
                          key: notes
                          value: Prefers email communication. Account under review.
                          oldValue: Prefers email communication
                        - type: ADD
                          key: deactivationReason
                          value: PAYMENT_ISSUES
                        - type: ADD
                          key: deactivationNotes
                          value: Multiple late payments
                        - type: ADD
                          key: deactivationDate
                          value: '2025-01-15T15:45:00Z'
              customer_deleted:
                summary: Customer deleted
                value:
                  sentAt: '2025-01-15T16:00:05Z'
                  events:
                    - event: CUSTOMER_DELETED
                      timestamp: '2025-01-15T16:00:00Z'
                      data:
                        id: 660e8400-e29b-41d4-a716-446655440000
                      diff: null
              company_created:
                summary: Company created
                value:
                  sentAt: '2025-01-15T09:00:05Z'
                  events:
                    - event: COMPANY_CREATED
                      timestamp: '2025-01-15T09:00:00Z'
                      data:
                        id: 550e8400-e29b-41d4-a716-446655440000
                        name: Acme Logistics Inc
                        addressLine1: 123 Main St
                        addressLine2: Suite 400
                        city: Chicago
                        country: USA
                        fax: +1-555-0123
                        invoiceOnly: false
                        invoiceVerbiage: Please remit payment within 30 days
                        primaryContactName: John Smith
                        primaryContactEmail: john.smith@acmelogistics.com
                        primaryContactPhone: +1-555-0100
                        createdBy:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          email: admin@example.com
                          name: Admin User
                        key: ERP-COMPANY-ACME-001
                        createdAt: '2025-01-15T09:00:00Z'
                        updatedAt: '2025-01-15T09:00:00Z'
                        deletedAt: null
                      diff: null
              company_updated:
                summary: Company updated with diff
                value:
                  sentAt: '2025-01-15T11:00:05Z'
                  events:
                    - event: COMPANY_UPDATED
                      timestamp: '2025-01-15T11:00:00Z'
                      data:
                        id: 550e8400-e29b-41d4-a716-446655440000
                        name: Acme Logistics Corporation
                        addressLine1: 456 New Ave
                        addressLine2: Suite 200
                        city: New York
                        country: USA
                        fax: +1-555-0124
                        invoiceOnly: true
                        invoiceVerbiage: Payment due upon receipt
                        primaryContactName: Jane Doe
                        primaryContactEmail: jane.doe@acmelogistics.com
                        primaryContactPhone: +1-555-0101
                        createdBy:
                          id: 550e8400-e29b-41d4-a716-446655440009
                          email: admin@example.com
                          name: Admin User
                        key: ERP-COMPANY-ACME-001
                        createdAt: '2025-01-15T09:00:00Z'
                        updatedAt: '2025-01-15T11:00:00Z'
                        deletedAt: null
                      diff:
                        - type: UPDATE
                          key: name
                          value: Acme Logistics Corporation
                          oldValue: Acme Logistics Inc
                        - type: UPDATE
                          key: addressLine1
                          value: 456 New Ave
                          oldValue: 123 Main St
                        - type: UPDATE
                          key: addressLine2
                          value: Suite 200
                          oldValue: Suite 400
                        - type: UPDATE
                          key: city
                          value: New York
                          oldValue: Chicago
                        - type: UPDATE
                          key: fax
                          value: +1-555-0124
                          oldValue: +1-555-0123
                        - type: UPDATE
                          key: invoiceOnly
                          value: true
                          oldValue: false
                        - type: UPDATE
                          key: invoiceVerbiage
                          value: Payment due upon receipt
                          oldValue: Please remit payment within 30 days
                        - type: UPDATE
                          key: primaryContactName
                          value: Jane Doe
                          oldValue: John Smith
                        - type: UPDATE
                          key: primaryContactEmail
                          value: jane.doe@acmelogistics.com
                          oldValue: john.smith@acmelogistics.com
                        - type: UPDATE
                          key: primaryContactPhone
                          value: +1-555-0101
                          oldValue: +1-555-0100
              company_deleted:
                summary: Company deleted
                value:
                  sentAt: '2025-01-15T12:00:05Z'
                  events:
                    - event: COMPANY_DELETED
                      timestamp: '2025-01-15T12:00:00Z'
                      data:
                        id: 550e8400-e29b-41d4-a716-446655440000
                      diff: null
              customer_contact_created:
                summary: Customer contact created
                value:
                  sentAt: '2025-01-15T13:00:05Z'
                  events:
                    - event: CUSTOMER_CONTACT_CREATED
                      timestamp: '2025-01-15T13:00:00Z'
                      data:
                        id: 990e8400-e29b-41d4-a716-446655440002
                        customer:
                          id: 660e8400-e29b-41d4-a716-446655440000
                          name: Acme Corporation
                          friendlyId: A123456
                        name: Sarah Johnson
                        contactInfo:
                          name: Sarah Johnson
                          email: sarah.johnson@example.com
                          phone: +1-555-0123
                          title: Logistics Manager
                        phoneExtension: '1234'
                        isPrimary: true
                        contactTypes:
                          - BILLING
                          - ACCOUNT_MANAGER
                        notifications:
                          - SHIPMENT_PICKED_UP
                          - SHIPMENT_DELIVERED
                        invitedUser: null
                        deletedBy: null
                        key: ERP-CONTACT-SARAH-001
                        createdAt: '2025-01-15T13:00:00Z'
                        deletedAt: null
                      diff: null
              customer_contact_updated:
                summary: Customer contact updated with diff
                value:
                  sentAt: '2025-01-15T13:30:05Z'
                  events:
                    - event: CUSTOMER_CONTACT_UPDATED
                      timestamp: '2025-01-15T13:30:00Z'
                      data:
                        id: 990e8400-e29b-41d4-a716-446655440002
                        customer:
                          id: 660e8400-e29b-41d4-a716-446655440000
                          name: Acme Corporation
                          friendlyId: A123456
                        name: Sarah Johnson-Smith
                        contactInfo:
                          name: Sarah Johnson-Smith
                          email: sarah.js@example.com
                          phone: +1-555-9999
                          title: Senior Logistics Manager
                        phoneExtension: '5678'
                        isPrimary: false
                        contactTypes:
                          - BILLING
                          - PROCUREMENT
                          - RATES_PRICING
                        notifications:
                          - SHIPMENT_IN_TRANSIT
                          - SHIPMENT_DELIVERED
                          - SHIPMENT_TENDER_REJECTED
                        invitedUser:
                          id: 880e8400-e29b-41d4-a716-446655440003
                          email: sarah.js@example.com
                          name: Sarah Johnson-Smith
                        deletedBy: null
                        key: ERP-CONTACT-SARAH-001
                        createdAt: '2025-01-15T13:00:00Z'
                        deletedAt: null
                      diff:
                        - type: UPDATE
                          key: name
                          value: Sarah Johnson-Smith
                          oldValue: Sarah Johnson
                        - type: UPDATE
                          key: contactInfo
                          changes:
                            - type: UPDATE
                              key: name
                              value: Sarah Johnson-Smith
                              oldValue: Sarah Johnson
                            - type: UPDATE
                              key: email
                              value: sarah.js@example.com
                              oldValue: sarah.johnson@example.com
                            - type: UPDATE
                              key: phone
                              value: +1-555-9999
                              oldValue: +1-555-0123
                            - type: UPDATE
                              key: title
                              value: Senior Logistics Manager
                              oldValue: Logistics Manager
                        - type: UPDATE
                          key: phoneExtension
                          value: '5678'
                          oldValue: '1234'
                        - type: UPDATE
                          key: isPrimary
                          value: false
                          oldValue: true
                        - type: UPDATE
                          key: contactTypes
                          changes:
                            - type: REMOVE
                              key: '1'
                              oldValue: ACCOUNT_MANAGER
                            - type: ADD
                              key: '1'
                              value: PROCUREMENT
                            - type: ADD
                              key: '2'
                              value: RATES_PRICING
                        - type: UPDATE
                          key: notifications
                          changes:
                            - type: UPDATE
                              key: '0'
                              value: SHIPMENT_IN_TRANSIT
                              oldValue: SHIPMENT_PICKED_UP
                            - type: ADD
                              key: '2'
                              value: SHIPMENT_TENDER_REJECTED
                        - type: ADD
                          key: invitedUser
                          value:
                            id: 880e8400-e29b-41d4-a716-446655440003
                            email: sarah.js@example.com
                            name: Sarah Johnson-Smith
              customer_contact_deleted:
                summary: Customer contact deleted
                value:
                  sentAt: '2025-01-15T14:00:05Z'
                  events:
                    - event: CUSTOMER_CONTACT_DELETED
                      timestamp: '2025-01-15T14:00:00Z'
                      data:
                        id: 990e8400-e29b-41d4-a716-446655440002
                      diff: null
              carrier_created:
                summary: Carrier created (truckload)
                value:
                  sentAt: '2025-01-15T08:00:05Z'
                  events:
                    - event: CARRIER_CREATED
                      timestamp: '2025-01-15T08:00:00Z'
                      data:
                        id: 770e8400-e29b-41d4-a716-446655440000
                        friendlyId: C123456
                        type: TRUCKLOAD
                        name: Fast Transport LLC
                        dbaName: Fast Logistics
                        key: ERP-CARRIER-FAST-001
                        email: dispatch@fasttransport.com
                        phone: +1-555-0200
                        website: https://fasttransport.com
                        status: ACTIVE
                        statusReason: null
                        notes: Preferred carrier for midwest routes
                        corporateAddress:
                          addressLine1: 789 Transport Way
                          addressLine2: null
                          city: Dallas
                          state: TX
                          postalCode: '75201'
                          country: USA
                          latitude: 32.7767
                          longitude: -96.797
                        billingAddress:
                          addressLine1: PO Box 12345
                          addressLine2: null
                          city: Dallas
                          state: TX
                          postalCode: '75202'
                          country: USA
                          latitude: null
                          longitude: null
                        mcNumber: MC-123456
                        dotNumber: '1234567'
                        scac: FAST
                        einNumber: 12-3456789
                        ffNumber: null
                        mxNumber: null
                        rfcNumber: null
                        iataCode: null
                        equipments:
                          - VAN
                          - REEFER
                          - FLATBED
                        isHazmat: false
                        tsaApproved: true
                        trucks: 50
                        trailers: 100
                        drivers: 75
                        powerUnits: 50
                        currency: USD
                        paymentTerm:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Net 30
                          key: null
                        isFactoringPreferred: false
                        goldenCarrierId: null
                        insuranceCompany: State Farm Insurance
                        insuranceAgent: John Smith
                        insuranceAgentPhone: +1-555-123-4567
                        insuranceAuthorityDate: '2025-01-01T00:00:00Z'
                        insuranceExpirationDate: '2025-12-31T23:59:59Z'
                        insuranceAutoLiabilityLimit: 1000000
                        insuranceCargoLiabilityLimit: 100000
                        insuranceGeneralLiabilityLimit: 1000000
                        rating: SATISFACTORY
                        ratingDate: '2025-01-15'
                        reviewType: COMPLIANCE_REVIEW
                        reviewDate: '2025-01-15'
                        operatingAbility: AUTHORIZED
                        inFmcsa: true
                        usDriverInspections: 100
                        usDriverInspectionsOos: 5
                        usDriverInspectionsOosPct: 5
                        usVehicleInspections: 150
                        usVehicleInspectionsOos: 8
                        usVehicleInspectionsOosPct: 5.33
                        createdAt: '2025-01-15T08:00:00Z'
                        updatedAt: '2025-01-15T08:00:00Z'
                        deletedAt: null
                      diff: null
              carrier_updated:
                summary: Carrier updated with diff
                value:
                  sentAt: '2025-01-15T10:30:05Z'
                  events:
                    - event: CARRIER_UPDATED
                      timestamp: '2025-01-15T10:30:00Z'
                      data:
                        id: 770e8400-e29b-41d4-a716-446655440000
                        friendlyId: C123456
                        type: TRUCKLOAD
                        name: Fast Transport LLC
                        dbaName: Fast Logistics Express
                        key: ERP-CARRIER-FAST-001
                        email: newdispatch@fasttransport.com
                        phone: +1-555-0201
                        website: https://fasttransport.com
                        status: INACTIVE
                        statusReason: Contract expired
                        notes: Contract renewal pending. Good safety record.
                        corporateAddress:
                          addressLine1: 789 Transport Way
                          addressLine2: Building B
                          city: Dallas
                          state: TX
                          postalCode: '75201'
                          country: USA
                          latitude: 32.7767
                          longitude: -96.797
                        billingAddress:
                          addressLine1: PO Box 12345
                          addressLine2: null
                          city: Dallas
                          state: TX
                          postalCode: '75202'
                          country: USA
                          latitude: null
                          longitude: null
                        mcNumber: MC-123456
                        dotNumber: '1234567'
                        scac: FAST
                        einNumber: 12-3456789
                        ffNumber: null
                        mxNumber: null
                        rfcNumber: null
                        iataCode: null
                        equipments:
                          - VAN
                          - REEFER
                          - FLATBED
                          - POWER_ONLY
                        isHazmat: true
                        tsaApproved: true
                        trucks: 60
                        trailers: 120
                        drivers: 85
                        powerUnits: 60
                        currency: USD
                        paymentTerm:
                          id: 550e8400-e29b-41d4-a716-446655440002
                          name: Net 30
                          key: null
                        isFactoringPreferred: false
                        goldenCarrierId: null
                        insuranceCompany: State Farm Insurance
                        insuranceAgent: Jane Doe
                        insuranceAgentPhone: +1-555-123-4568
                        insuranceAuthorityDate: '2025-01-01T00:00:00Z'
                        insuranceExpirationDate: '2026-12-31T23:59:59Z'
                        insuranceAutoLiabilityLimit: 2000000
                        insuranceCargoLiabilityLimit: 250000
                        insuranceGeneralLiabilityLimit: 2000000
                        rating: SATISFACTORY
                        ratingDate: '2025-01-15'
                        reviewType: COMPLIANCE_REVIEW
                        reviewDate: '2025-01-15'
                        operatingAbility: AUTHORIZED
                        inFmcsa: true
                        usDriverInspections: 110
                        usDriverInspectionsOos: 4
                        usDriverInspectionsOosPct: 3.64
                        usVehicleInspections: 165
                        usVehicleInspectionsOos: 7
                        usVehicleInspectionsOosPct: 4.24
                        createdAt: '2025-01-15T08:00:00Z'
                        updatedAt: '2025-01-15T10:30:00Z'
                        deletedAt: null
                      diff:
                        - type: UPDATE
                          key: dbaName
                          value: Fast Logistics Express
                          oldValue: Fast Logistics
                        - type: UPDATE
                          key: email
                          value: newdispatch@fasttransport.com
                          oldValue: dispatch@fasttransport.com
                        - type: UPDATE
                          key: phone
                          value: +1-555-0201
                          oldValue: +1-555-0200
                        - type: UPDATE
                          key: status
                          value: INACTIVE
                          oldValue: ACTIVE
                        - type: ADD
                          key: statusReason
                          value: Contract expired
                        - type: UPDATE
                          key: notes
                          value: Contract renewal pending. Good safety record.
                          oldValue: Preferred carrier for midwest routes
                        - type: UPDATE
                          key: corporateAddress
                          changes:
                            - type: ADD
                              key: addressLine2
                              value: Building B
                        - type: UPDATE
                          key: equipments
                          changes:
                            - type: ADD
                              key: '3'
                              value: POWER_ONLY
                        - type: UPDATE
                          key: isHazmat
                          value: true
                          oldValue: false
                        - type: UPDATE
                          key: trucks
                          value: 60
                          oldValue: 50
                        - type: UPDATE
                          key: trailers
                          value: 120
                          oldValue: 100
                        - type: UPDATE
                          key: drivers
                          value: 85
                          oldValue: 75
                        - type: UPDATE
                          key: powerUnits
                          value: 60
                          oldValue: 50
                        - type: UPDATE
                          key: insuranceAgent
                          value: Jane Doe
                          oldValue: John Smith
                        - type: UPDATE
                          key: insuranceAgentPhone
                          value: +1-555-123-4568
                          oldValue: +1-555-123-4567
                        - type: UPDATE
                          key: insuranceExpirationDate
                          value: '2026-12-31T23:59:59Z'
                          oldValue: '2025-12-31T23:59:59Z'
                        - type: UPDATE
                          key: insuranceAutoLiabilityLimit
                          value: 2000000
                          oldValue: 1000000
                        - type: UPDATE
                          key: insuranceCargoLiabilityLimit
                          value: 250000
                          oldValue: 100000
                        - type: UPDATE
                          key: insuranceGeneralLiabilityLimit
                          value: 2000000
                          oldValue: 1000000
                        - type: UPDATE
                          key: usDriverInspections
                          value: 110
                          oldValue: 100
                        - type: UPDATE
                          key: usDriverInspectionsOos
                          value: 4
                          oldValue: 5
                        - type: UPDATE
                          key: usDriverInspectionsOosPct
                          value: 3.64
                          oldValue: 5
                        - type: UPDATE
                          key: usVehicleInspections
                          value: 165
                          oldValue: 150
                        - type: UPDATE
                          key: usVehicleInspectionsOos
                          value: 7
                          oldValue: 8
                        - type: UPDATE
                          key: usVehicleInspectionsOosPct
                          value: 4.24
                          oldValue: 5.33
              carrier_deleted:
                summary: Carrier deleted
                value:
                  sentAt: '2025-01-15T11:00:05Z'
                  events:
                    - event: CARRIER_DELETED
                      timestamp: '2025-01-15T11:00:00Z'
                      data:
                        id: 770e8400-e29b-41d4-a716-446655440000
                      diff: null
              carrier_contact_created:
                summary: Carrier contact created
                value:
                  sentAt: '2025-01-15T12:00:05Z'
                  events:
                    - event: CARRIER_CONTACT_CREATED
                      timestamp: '2025-01-15T12:00:00Z'
                      data:
                        id: 880e8400-e29b-41d4-a716-446655440001
                        carrier:
                          id: 770e8400-e29b-41d4-a716-446655440000
                          name: Fast Transport LLC
                          friendlyId: C123456
                        name: Mike Johnson
                        contactInfo:
                          name: Mike Johnson
                          email: mike@fasttransport.com
                          phone: +1-555-0300
                          title: Dispatch Manager
                        contactType: DISPATCH
                        key: ERP-CARRIER-CONTACT-001
                        createdAt: '2025-01-15T12:00:00Z'
                        deletedAt: null
                      diff: null
              carrier_factor_created:
                summary: Carrier factor created
                value:
                  sentAt: '2025-01-15T13:00:05Z'
                  events:
                    - event: CARRIER_FACTOR_CREATED
                      timestamp: '2025-01-15T13:00:00Z'
                      data:
                        id: 550e8400-e29b-41d4-a716-446655440010
                        companyName: Capital Factoring Services Inc
                        key: ERP-FACTOR-001
                        email: accounting@capitalfactoring.com
                        phoneNumber: +1-555-234-5678
                        addressLine1: 789 Finance Ave
                        city: Dallas
                        state: TX
                        country: USA
                        zipCode: '75201'
                        bankName: Chase Bank
                        accountName: Capital Factoring Services Inc
                        currency: USD
                        createdAt: '2025-01-15T13:00:00Z'
                        updatedAt: '2025-01-15T13:00:00Z'
                        deletedAt: null
                      diff: null
              carrier_payment_method_created:
                summary: Carrier payment method created
                value:
                  sentAt: '2025-01-15T14:00:05Z'
                  events:
                    - event: CARRIER_PAYMENT_METHOD_CREATED
                      timestamp: '2025-01-15T14:00:00Z'
                      data:
                        id: 990e8400-e29b-41d4-a716-446655440020
                        carrierId: 770e8400-e29b-41d4-a716-446655440000
                        carrier:
                          id: 770e8400-e29b-41d4-a716-446655440000
                          name: Fast Transport LLC
                          friendlyId: C123456
                        paymentRecipientType: DIRECT
                        paymentMethodType: ACH
                        isPreferred: true
                        bankName: Chase Bank
                        accountName: Fast Transport LLC
                        accountNumber: '****1234'
                        abaAch: '021000021'
                        currency: USD
                        carrierFactor: null
                        createdAt: '2025-01-15T14:00:00Z'
                        updatedAt: '2025-01-15T14:00:00Z'
                        deletedAt: null
                      diff: null
              carrier_payment_method_updated:
                summary: Carrier payment method updated
                value:
                  sentAt: '2025-01-15T15:00:05Z'
                  events:
                    - event: CARRIER_PAYMENT_METHOD_UPDATED
                      timestamp: '2025-01-15T15:00:00Z'
                      data:
                        id: 990e8400-e29b-41d4-a716-446655440020
                        carrierId: 770e8400-e29b-41d4-a716-446655440000
                        carrier:
                          id: 770e8400-e29b-41d4-a716-446655440000
                          name: Fast Transport LLC
                          friendlyId: C123456
                        paymentRecipientType: FACTOR
                        paymentMethodType: ACH_WIRE
                        isPreferred: false
                        bankName: null
                        accountName: null
                        accountNumber: null
                        abaAch: null
                        currency: USD
                        carrierFactor:
                          id: 550e8400-e29b-41d4-a716-446655440010
                          key: ERP-FACTOR-001
                          companyName: Capital Factoring Services Inc
                          email: accounting@capitalfactoring.com
                          phoneNumber: +1-555-234-5678
                          currency: USD
                          createdAt: '2025-01-15T13:00:00Z'
                          updatedAt: '2025-01-15T13:00:00Z'
                        createdAt: '2025-01-15T14:00:00Z'
                        updatedAt: '2025-01-15T15:00:00Z'
                        deletedAt: null
                      diff:
                        - type: UPDATE
                          key: paymentRecipientType
                          value: FACTOR
                          oldValue: DIRECT
                        - type: UPDATE
                          key: paymentMethodType
                          value: ACH_WIRE
                          oldValue: ACH
                        - type: UPDATE
                          key: isPreferred
                          value: false
                          oldValue: true
                        - type: ADD
                          key: carrierFactor
                          value:
                            id: 550e8400-e29b-41d4-a716-446655440010
                            companyName: Capital Factoring Services Inc
                        - type: REMOVE
                          key: bankName
                          oldValue: Chase Bank
                        - type: REMOVE
                          key: accountName
                          oldValue: Fast Transport LLC
                        - type: REMOVE
                          key: accountNumber
                          oldValue: '****1234'
                        - type: REMOVE
                          key: abaAch
                          oldValue: '021000021'
              vendor_payment_method_created:
                summary: Vendor payment method created
                value:
                  sentAt: '2025-01-15T16:00:05Z'
                  events:
                    - event: VENDOR_PAYMENT_METHOD_CREATED
                      timestamp: '2025-01-15T16:00:00Z'
                      data:
                        id: 330e8400-e29b-41d4-a716-446655440030
                        vendorId: 550e8400-e29b-41d4-a716-446655440000
                        vendor:
                          id: 550e8400-e29b-41d4-a716-446655440000
                          name: ABC Warehouse Services
                          friendlyId: V123456
                        paymentMethodType: ACH
                        isPreferred: true
                        bankName: Bank of America
                        accountName: ABC Warehouse Services
                        accountNumber: '****5678'
                        abaAch: '026009593'
                        currency: USD
                        createdAt: '2025-01-15T16:00:00Z'
                        updatedAt: '2025-01-15T16:00:00Z'
                        deletedAt: null
                      diff: null
              shipment_delivered:
                summary: Shipment delivered
                value:
                  sentAt: '2025-01-15T18:30:05Z'
                  events:
                    - event: SHIPMENT_DELIVERED
                      timestamp: '2025-01-15T18:30:00Z'
                      data:
                        id: 660e8400-e29b-41d4-a716-446655440000
                        friendlyId: SHP-12345
                        key: ERP-SHIP-789
                      diff: null
      responses:
        '200':
          description: Webhook received and processed successfully
        '401':
          description: Invalid or missing x-api-key header
paths:
  /companies/filter:
    post:
      tags:
        - Companies
      summary: Filter companies
      description: >
        Query companies using flexible filter criteria with AND/OR logic.


        By default, only non-deleted companies are returned (deletedAt: {
        isNull: true }).

        Override this by explicitly setting deletedAt filter criteria.
      operationId: filterCompanies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyFilterRequest'
      responses:
        '200':
          description: Filtered companies with pagination
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pageInfo
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Company'
                  pageInfo:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /companies:
    post:
      tags:
        - Companies
      summary: Create a new company
      description: Create a new company within an organization
      operationId: createCompany
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyInput'
      responses:
        '201':
          description: Company created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /companies/{id}:
    get:
      tags:
        - Companies
      summary: Get a company by ID
      description: Retrieve a single company by its unique identifier
      operationId: getCompanyById
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '200':
          description: Company found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Companies
      summary: Update a company
      description: |
        Partially update a company. Only provided fields will be updated.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      operationId: updateCompany
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyPatch'
      responses:
        '200':
          description: Company updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Companies
      summary: Delete a company
      description: >
        Soft delete a company (sets deletedAt timestamp).


        The company will no longer appear in default queries but can be
        retrieved

        by explicitly filtering for deleted records.
      operationId: deleteCompany
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '204':
          description: Company deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carrier-contacts/filter:
    post:
      tags:
        - Carrier Contacts
      summary: Filter carrier contacts
      description: >
        Query carrier contacts using flexible filter criteria with AND/OR logic.


        By default, only non-deleted carrier contacts are returned (deletedAt: {
        isNull: true }).

        Override this by explicitly setting deletedAt filter criteria.
      operationId: filterCarrierContacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierContactFilterRequest'
      responses:
        '200':
          description: Filtered carrier contacts with pagination
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pageInfo
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CarrierContact'
                  pageInfo:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carrier-contacts:
    post:
      tags:
        - Carrier Contacts
      summary: Create carrier contact
      description: >
        Create a new carrier contact. The contactInfo will create a new Contact
        record,

        and the CarrierContact will reference it via contactId (managed
        internally).
      operationId: createCarrierContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierContactInput'
      responses:
        '201':
          description: Carrier contact created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carrier-contacts/{id}:
    get:
      tags:
        - Carrier Contacts
      summary: Get carrier contact
      description: Retrieve a single carrier contact by its unique identifier
      operationId: getCarrierContactById
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '200':
          description: Carrier contact found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Carrier Contacts
      summary: Update carrier contact
      description: >
        Partially update a carrier contact. Only provided fields will be
        updated.


        - **Omitted fields**: Not modified (current value preserved)

        - **Provided fields**: Updated to the new value

        - **Null values**: Clear the field (set to null) where applicable


        When updating contactInfo, the underlying Contact record is updated.
      operationId: updateCarrierContact
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierContactPatch'
      responses:
        '200':
          description: Carrier contact updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Carrier Contacts
      summary: Delete carrier contact
      description: >
        Soft delete a carrier contact (sets deletedAt timestamp).


        The contact will no longer appear in default queries but can be
        retrieved

        by explicitly filtering for deleted records.
      operationId: deleteCarrierContact
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '204':
          description: Carrier contact deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carriers/filter:
    post:
      tags:
        - Carriers
      summary: Filter carriers
      description: >
        Query carriers using flexible filter criteria with AND/OR logic.


        By default, only non-deleted carriers are returned (deletedAt: { isNull:
        true }).

        Override this by explicitly setting deletedAt filter criteria.


        Returns carriers of all types (TRUCKLOAD, AIR, CARTAGE, LINEHAUL, LTL,
        OCEAN, RAIL)

        with type-specific fields included based on carrier type.
      operationId: filterCarriers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierFilterRequest'
      responses:
        '200':
          description: Filtered carriers with pagination
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pageInfo
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Carrier'
                  pageInfo:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carriers:
    post:
      tags:
        - Carriers
      summary: Create a new carrier
      description: >
        Create a new carrier within an organization.


        The carrier type must be specified and determines which fields are
        available:

        - **TRUCKLOAD**: Includes insurance, safety rating, and FMCSA inspection
        fields

        - **AIR, CARTAGE, LINEHAUL, LTL, OCEAN, RAIL**: Include only base
        carrier fields


        Note: In the backend, null carrier type is represented as TRUCKLOAD in
        the public API.
      operationId: createCarrier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierInput'
            examples:
              truckload:
                summary: Truckload carrier with insurance
                value:
                  name: Swift Transportation Co
                  type: TRUCKLOAD
                  email: dispatch@swifttrans.com
                  phone: +1-555-987-6543
                  status: ACTIVE
                  mcNumber: MC-123456
                  dotNumber: '1234567'
                  insuranceCompany: State Farm Insurance
                  insuranceAutoLiabilityLimit: 1000000
                  rating: SATISFACTORY
                  inFmcsa: true
              air:
                summary: Air carrier
                value:
                  name: FedEx Express
                  type: AIR
                  email: cargo@fedex.com
                  phone: +1-555-123-4567
                  status: ACTIVE
                  iataCode: FX
              ltl:
                summary: LTL carrier
                value:
                  name: XPO Logistics
                  type: LTL
                  email: dispatch@xpo.com
                  phone: +1-555-456-7890
                  status: ACTIVE
                  scac: XPOL
      responses:
        '201':
          description: Carrier created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Carrier'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carriers/{id}:
    get:
      tags:
        - Carriers
      summary: Get a carrier by ID
      description: >
        Retrieve a single carrier by its unique identifier.


        The response will include type-specific fields based on the carrier's
        type:

        - **TRUCKLOAD**: Includes insurance, safety rating, and FMCSA inspection
        fields

        - **AIR, CARTAGE, LINEHAUL, LTL, OCEAN, RAIL**: Include only base
        carrier fields
      operationId: getCarrierById
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '200':
          description: Carrier found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Carrier'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Carriers
      summary: Update a carrier
      description: >
        Partially update a carrier. Only provided fields will be updated.


        - **Omitted fields**: Not modified (current value preserved)

        - **Provided fields**: Updated to the new value

        - **Null values**: Clear the field (set to null) where applicable


        The carrier type determines which fields can be updated:

        - **TRUCKLOAD**: Can update insurance, safety rating, and FMCSA fields

        - **AIR, CARTAGE, LINEHAUL, LTL, OCEAN, RAIL**: Can only update base
        carrier fields


        Changing the carrier type will affect which specialized fields are
        available.
      operationId: updateCarrier
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierPatch'
      responses:
        '200':
          description: Carrier updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Carrier'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Carriers
      summary: Delete a carrier
      description: >
        Soft delete a carrier (sets deletedAt timestamp).


        The carrier will no longer appear in default queries but can be
        retrieved

        by explicitly filtering for deleted records.
      operationId: deleteCarrier
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '204':
          description: Carrier deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carriers/search:
    post:
      summary: Search carriers
      description: >
        Search carriers using OpenSearch-powered full-text and field-specific
        search.


        This endpoint searches both:

        - **ONBOARDED carriers**: Carriers with profiles in your organization

        - **FMCSA carriers**: Public carrier records from FMCSA database


        Features:

        - Full-text search across multiple fields

        - Field-specific filtering with various operators

        - Sorting and pagination

        - Saved search preferences


        **Note:** Only active (non-deleted) carriers 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 carrier objects with all relationships
      operationId: searchCarriers
      tags:
        - Carriers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierSearchRequest'
      responses:
        '200':
          description: Successful search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /carrier-factors/filter:
    post:
      tags:
        - Carrier Factors
      summary: Filter carrier factors
      description: >
        Query carrier factors (factoring companies) using flexible filter
        criteria with AND/OR logic.


        By default, only non-deleted carrier factors are returned (deletedAt: {
        isNull: true }).

        Override this by explicitly setting deletedAt filter criteria.


        Carrier factors represent factoring companies that provide payment
        services for carriers.
      operationId: filterCarrierFactors
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierFactorFilterRequest'
      responses:
        '200':
          description: Filtered carrier factors with pagination
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pageInfo
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CarrierFactor'
                  pageInfo:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carrier-factors:
    post:
      tags:
        - Carrier Factors
      summary: Create carrier factor
      description: >
        Create a new carrier factor (factoring company).


        Factoring companies provide payment services for carriers, allowing them
        to receive

        immediate payment for invoices.
      operationId: createCarrierFactor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierFactorInput'
            examples:
              basic:
                summary: Basic carrier factor
                value:
                  companyName: Capital Factoring Services Inc
                  email: accounting@capitalfactoring.com
                  phoneNumber: +1-555-234-5678
                  addressLine1: 789 Finance Ave
                  city: Dallas
                  state: TX
                  country: USA
                  zipCode: '75201'
              withBanking:
                summary: Carrier factor with banking details
                value:
                  companyName: Capital Factoring Services Inc
                  email: accounting@capitalfactoring.com
                  phoneNumber: +1-555-234-5678
                  addressLine1: 789 Finance Ave
                  city: Dallas
                  state: TX
                  country: USA
                  zipCode: '75201'
                  bankName: Chase Bank
                  accountName: Capital Factoring Services Inc
                  accountNumber: '1234567890'
                  abaAch: '021000021'
                  swiftCode: CHASUS33
                  currency: USD
      responses:
        '201':
          description: Carrier factor created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierFactor'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carrier-factors/{id}:
    get:
      tags:
        - Carrier Factors
      summary: Get carrier factor
      description: >
        Retrieve a single carrier factor by its unique identifier.


        Carrier factors represent factoring companies that provide payment
        services.
      operationId: getCarrierFactorById
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '200':
          description: Carrier factor found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierFactor'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Carrier Factors
      summary: Update carrier factor
      description: |
        Partially update a carrier factor. Only provided fields will be updated.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      operationId: updateCarrierFactor
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierFactorPatch'
            examples:
              updateContact:
                summary: Update contact information
                value:
                  email: newemail@capitalfactoring.com
                  phoneNumber: +1-555-999-8888
              updateBanking:
                summary: Update banking details
                value:
                  bankName: Bank of America
                  accountNumber: '9876543210'
                  abaAch: '026009593'
      responses:
        '200':
          description: Carrier factor updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierFactor'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Carrier Factors
      summary: Delete carrier factor
      description: >
        Soft delete a carrier factor (sets deletedAt timestamp).


        The carrier factor will no longer appear in default queries but can be
        retrieved

        by explicitly filtering for deleted records.
      operationId: deleteCarrierFactor
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '204':
          description: Carrier factor deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carrier-payment-methods/filter:
    post:
      tags:
        - Carrier Payment Methods
      summary: Filter carrier payment methods
      description: >
        Query carrier payment methods using flexible filter criteria with AND/OR
        logic.


        By default, only non-deleted payment methods are returned (deletedAt: {
        isNull: true }).

        Override this by explicitly setting deletedAt filter criteria.


        Carrier payment methods define how and where payments are sent for a
        specific carrier.
      operationId: filterCarrierPaymentMethods
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierPaymentMethodFilterRequest'
      responses:
        '200':
          description: Filtered carrier payment methods with pagination
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pageInfo
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CarrierPaymentMethod'
                  pageInfo:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carrier-payment-methods:
    post:
      tags:
        - Carrier Payment Methods
      summary: Create carrier payment method
      description: >
        Create a new carrier payment method.


        **Payment Recipient Type Constraints:**

        - **DIRECT**: Payment goes to carrier directly. `carrierFactorId` must
        be null or omitted.

        - **FACTOR**: Payment goes to factoring company. `carrierFactorId` is
        required.


        **Important**: The `carrierId` cannot be changed after creation.
      operationId: createCarrierPaymentMethod
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierPaymentMethodInput'
            examples:
              directPayment:
                summary: Direct ACH payment to carrier
                value:
                  carrierId: 770e8400-e29b-41d4-a716-446655440000
                  paymentRecipientType: DIRECT
                  paymentMethodType: ACH
                  isPreferred: true
                  bankName: Chase Bank
                  accountName: Carrier Transport Inc
                  accountNumber: '1234567890'
                  abaAch: '021000021'
                  currency: USD
              factorPayment:
                summary: Payment through factoring company
                value:
                  carrierId: 770e8400-e29b-41d4-a716-446655440000
                  paymentRecipientType: FACTOR
                  paymentMethodType: ACH_WIRE
                  carrierFactorId: 550e8400-e29b-41d4-a716-446655440000
                  isPreferred: false
              zelle:
                summary: Zelle payment
                value:
                  carrierId: 770e8400-e29b-41d4-a716-446655440000
                  paymentRecipientType: DIRECT
                  paymentMethodType: ZELLE
                  email: payments@carrier.com
                  phone: +1-555-123-4567
                  username: carrier_payments
      responses:
        '201':
          description: Carrier payment method created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierPaymentMethod'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /carrier-payment-methods/{id}:
    get:
      tags:
        - Carrier Payment Methods
      summary: Get carrier payment method
      description: >
        Retrieve a single carrier payment method by its unique identifier.


        Returns full details including banking information and associated
        carrier/factor references.
      operationId: getCarrierPaymentMethodById
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '200':
          description: Carrier payment method found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierPaymentMethod'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Carrier Payment Methods
      summary: Update carrier payment method
      description: >
        Partially update a carrier payment method. Only provided fields will be
        updated.


        **IMPORTANT**: The `carrierId` field cannot be changed after creation.


        **Payment Recipient Type Constraints:**

        - When changing to **DIRECT**: `carrierFactorId` must be set to null

        - When changing to **FACTOR**: `carrierFactorId` is required


        - **Omitted fields**: Not modified (current value preserved)

        - **Provided fields**: Updated to the new value

        - **Null values**: Clear the field (set to null) where applicable
      operationId: updateCarrierPaymentMethod
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierPaymentMethodPatch'
            examples:
              updateBanking:
                summary: Update banking details
                value:
                  bankName: Bank of America
                  accountNumber: '9876543210'
                  abaAch: '026009593'
              changeToFactor:
                summary: Change from direct to factor payment
                value:
                  paymentRecipientType: FACTOR
                  carrierFactorId: 550e8400-e29b-41d4-a716-446655440000
              makePreferred:
                summary: Set as preferred payment method
                value:
                  isPreferred: true
      responses:
        '200':
          description: Carrier payment method updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierPaymentMethod'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Carrier Payment Methods
      summary: Delete carrier payment method
      description: >
        Soft delete a carrier payment method (sets deletedAt timestamp).


        The payment method will no longer appear in default queries but can be
        retrieved

        by explicitly filtering for deleted records.
      operationId: deleteCarrierPaymentMethod
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '204':
          description: Carrier payment method deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /customer-contacts/filter:
    post:
      tags:
        - Customer Contacts
      summary: Filter customer contacts
      description: >
        Query customer contacts using flexible filter criteria with AND/OR
        logic.


        By default, only non-deleted customer contacts are returned (deletedAt:
        { isNull: true }).

        Override this by explicitly setting deletedAt filter criteria.
      operationId: filterCustomerContacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerContactFilterRequest'
      responses:
        '200':
          description: Filtered customer contacts with pagination
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pageInfo
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomerContact'
                  pageInfo:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /customer-contacts:
    post:
      tags:
        - Customer Contacts
      summary: Create customer contact
      description: >
        Create a new customer contact. The contactInfo will create a new Contact
        record,

        and the CustomerContact will reference it via parentContactId (managed
        internally).
      operationId: createCustomerContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerContactInput'
      responses:
        '201':
          description: Customer contact created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /customer-contacts/{id}:
    get:
      tags:
        - Customer Contacts
      summary: Get customer contact
      description: Retrieve a single customer contact by its unique identifier
      operationId: getCustomerContactById
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '200':
          description: Customer contact found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Customer Contacts
      summary: Update customer contact
      description: >
        Partially update a customer contact. Only provided fields will be
        updated.


        - **Omitted fields**: Not modified (current value preserved)

        - **Provided fields**: Updated to the new value

        - **Null values**: Clear the field (set to null) where applicable


        When updating contactInfo, the underlying Contact record is updated.
      operationId: updateCustomerContact
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerContactPatch'
      responses:
        '200':
          description: Customer contact updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Customer Contacts
      summary: Delete customer contact
      description: >
        Soft delete a customer contact (sets deletedAt timestamp).


        The contact will no longer appear in default queries but can be
        retrieved

        by explicitly filtering for deleted records.
      operationId: deleteCustomerContact
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '204':
          description: Customer contact deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /customers/filter:
    post:
      summary: Filter customers
      description: >
        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 }).
      operationId: filterCustomers
      tags:
        - Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerFilterRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 3
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: >-
                        Filter customers using comprehensive query criteria with
                        AND/OR logic and multiple operators.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes: {}
                    children: []
                    type: softbreak
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: >-
                        Supports complex filtering similar to GraphQL
                        capabilities.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes: {}
                    children: []
                    type: softbreak
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: >-
                        Note: Soft-deleted customers are excluded by default
                        (deletedAt defaults to { isNull: true }).
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
  /customers:
    post:
      summary: Create customer
      description: Create a new customer in your organization
      operationId: createCustomer
      tags:
        - Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerInput'
      responses:
        '201':
          description: Customer created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /customers/{id}:
    get:
      summary: Get customer
      description: Retrieve a customer by ID or client key
      operationId: getCustomer
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    patch:
      summary: Update customer
      description: Partially update a customer. Only provided fields will be updated.
      operationId: updateCustomer
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerPatch'
      responses:
        '200':
          description: Customer updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    delete:
      summary: Delete customer
      description: Soft delete a customer (sets deletedAt timestamp)
      operationId: deleteCustomer
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '204':
          description: Customer deleted successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /customers/search:
    post:
      summary: Search customers
      description: >
        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
      operationId: searchCustomers
      tags:
        - Customers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerSearchRequest'
      responses:
        '200':
          description: Successful search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /locations/filter:
    post:
      tags:
        - Locations
      summary: Filter locations
      description: >
        Query locations using flexible filter criteria with AND/OR logic.


        By default, only non-deleted locations are returned (deletedAt: {
        isNull: true }).

        Override this by explicitly setting deletedAt filter criteria.
      operationId: filterLocations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationFilterRequest'
      responses:
        '200':
          description: Filtered locations with pagination
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pageInfo
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Location'
                  pageInfo:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /locations:
    post:
      tags:
        - Locations
      summary: Create a new location
      description: >
        Create a new location for a customer.


        Locations represent pickup or delivery points (warehouses, distribution
        centers, etc.).
      operationId: createLocation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationInput'
            examples:
              warehouse:
                summary: Warehouse location
                value:
                  customerId: 550e8400-e29b-41d4-a716-446655440000
                  name: ABC Warehouse - Dallas
                  key: ERP-LOC-DALLAS-01
                  type: SHIPPER
                  isAppointmentRequired: true
                  notes: Call 24 hours ahead for appointment
              distribution_center:
                summary: Distribution center
                value:
                  customerId: 550e8400-e29b-41d4-a716-446655440000
                  name: XYZ Distribution Center
                  type: BOTH
                  isAppointmentRequired: false
      responses:
        '201':
          description: Location created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Location'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /locations/{id}:
    get:
      tags:
        - Locations
      summary: Get a location by ID
      description: |
        Retrieve a single location by its unique identifier.
      operationId: getLocationById
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '200':
          description: Location found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Location'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Locations
      summary: Update a location
      description: |
        Partially update a location. Only provided fields will be updated.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      operationId: updateLocation
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationPatch'
            examples:
              updateNotes:
                summary: Update notes
                value:
                  notes: Updated appointment requirements
              updateType:
                summary: Update location type
                value:
                  type: BOTH
      responses:
        '200':
          description: Location updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Location'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Locations
      summary: Delete a location
      description: >
        Soft delete a location (sets deletedAt timestamp).


        The location will no longer appear in default queries but can be
        retrieved

        by explicitly filtering for deleted records.
      operationId: deleteLocation
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '204':
          description: Location deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /locations/search:
    post:
      summary: Search locations
      description: >
        Search locations using OpenSearch-powered full-text and field-specific
        search.


        This endpoint provides fast, indexed search across location data with
        support for:

        - Full-text search across multiple fields

        - Field-specific filtering with various operators

        - Geographic search capabilities

        - Sorting and pagination

        - Saved search preferences


        **Note:** Only active (non-deleted) locations 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 location objects with all relationships
      operationId: searchLocations
      tags:
        - Locations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationSearchRequest'
      responses:
        '200':
          description: Successful search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /location-contacts/filter:
    post:
      tags:
        - Location Contacts
      summary: Filter location contacts
      description: >
        Query location contacts using flexible filter criteria with AND/OR
        logic.


        By default, only non-deleted location contacts are returned (deletedAt:
        { isNull: true }).

        Override this by explicitly setting deletedAt filter criteria.
      operationId: filterLocationContacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationContactFilterRequest'
      responses:
        '200':
          description: Filtered location contacts with pagination
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pageInfo
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/LocationContact'
                  pageInfo:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /location-contacts:
    post:
      tags:
        - Location Contacts
      summary: Create a new location contact
      description: >
        Link a customer contact to a location with specific contact types/roles.


        Location contacts represent the relationship between a customer contact

        and a specific location, defining what role the contact has at that
        location.
      operationId: createLocationContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationContactInput'
            examples:
              primary_manager:
                summary: Primary location manager
                value:
                  locationId: 770e8400-e29b-41d4-a716-446655440000
                  customerContactId: 660e8400-e29b-41d4-a716-446655440000
                  isPrimary: true
                  contactTypes:
                    - LOCATION_MANAGER
                    - SHIPPING
                  key: ERP-LOC-CONTACT-001
              billing_contact:
                summary: Billing contact
                value:
                  locationId: 770e8400-e29b-41d4-a716-446655440000
                  customerContactId: 660e8400-e29b-41d4-a716-446655440001
                  isPrimary: false
                  contactTypes:
                    - BILLING
      responses:
        '201':
          description: Location contact created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /location-contacts/{id}:
    get:
      tags:
        - Location Contacts
      summary: Get a location contact by ID
      description: |
        Retrieve a single location contact by its unique identifier.
      operationId: getLocationContactById
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '200':
          description: Location contact found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Location Contacts
      summary: Update a location contact
      description: >
        Partially update a location contact. Only provided fields will be
        updated.


        - **Omitted fields**: Not modified (current value preserved)

        - **Provided fields**: Updated to the new value

        - **Null values**: Clear the field (set to null) where applicable
      operationId: updateLocationContact
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationContactPatch'
            examples:
              updateContactTypes:
                summary: Update contact types
                value:
                  contactTypes:
                    - LOCATION_MANAGER
                    - SHIPPING
                    - RECEIVING
              updatePrimary:
                summary: Set as primary
                value:
                  isPrimary: true
      responses:
        '200':
          description: Location contact updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Location Contacts
      summary: Delete a location contact
      description: >
        Soft delete a location contact (sets deletedAt timestamp).


        The location contact will no longer appear in default queries but can be
        retrieved

        by explicitly filtering for deleted records.
      operationId: deleteLocationContact
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '204':
          description: Location contact deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /payment-terms/filter:
    post:
      summary: Filter payment terms
      description: >
        Filter payment terms using comprehensive query criteria with AND/OR
        logic and multiple operators.

        Supports complex filtering similar to GraphQL capabilities.

        Note: Soft-deleted payment terms are excluded by default (deletedAt
        defaults to { isNull: true }).
      operationId: filterPaymentTerms
      tags:
        - Payment Terms
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentTermFilterRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentTerm'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 3
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: >-
                        Filter payment terms using comprehensive query criteria
                        with AND/OR logic and multiple operators.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes: {}
                    children: []
                    type: softbreak
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: >-
                        Supports complex filtering similar to GraphQL
                        capabilities.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes: {}
                    children: []
                    type: softbreak
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: >-
                        Note: Soft-deleted payment terms are excluded by default
                        (deletedAt defaults to { isNull: true }).
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
  /payment-terms:
    post:
      summary: Create payment term
      description: Create a new payment term configuration in your organization
      operationId: createPaymentTerm
      tags:
        - Payment Terms
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentTermInput'
      responses:
        '201':
          description: Payment term created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentTerm'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /payment-terms/{id}:
    get:
      summary: Get payment term
      description: Retrieve a payment term by ID or client key
      operationId: getPaymentTerm
      tags:
        - Payment Terms
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentTerm'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    patch:
      summary: Update payment term
      description: Partially update a payment term. Only provided fields will be updated.
      operationId: updatePaymentTerm
      tags:
        - Payment Terms
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentTermPatch'
      responses:
        '200':
          description: Payment term updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentTerm'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    delete:
      summary: Delete payment term
      description: Soft delete a payment term (sets deletedAt timestamp)
      operationId: deletePaymentTerm
      tags:
        - Payment Terms
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '204':
          description: Payment term deleted successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /teams/filter:
    post:
      summary: Filter teams
      description: >
        Filter teams using comprehensive query criteria with AND/OR logic and
        multiple operators.

        Supports complex filtering similar to GraphQL capabilities.

        Note: Soft-deleted teams are excluded by default (deletedAt defaults to
        { isNull: true }).
      operationId: filterTeams
      tags:
        - Teams
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamFilterRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 3
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: >-
                        Filter teams using comprehensive query criteria with
                        AND/OR logic and multiple operators.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes: {}
                    children: []
                    type: softbreak
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: >-
                        Supports complex filtering similar to GraphQL
                        capabilities.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes: {}
                    children: []
                    type: softbreak
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: >-
                        Note: Soft-deleted teams are excluded by default
                        (deletedAt defaults to { isNull: true }).
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
  /teams:
    post:
      summary: Create team
      description: Create a new team in your organization
      operationId: createTeam
      tags:
        - Teams
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamInput'
      responses:
        '201':
          description: Team created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /teams/{id}:
    get:
      summary: Get team
      description: Retrieve a team by ID or client key
      operationId: getTeam
      tags:
        - Teams
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    patch:
      summary: Update team
      description: Partially update a team. Only provided fields will be updated.
      operationId: updateTeam
      tags:
        - Teams
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamPatch'
      responses:
        '200':
          description: Team updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    delete:
      summary: Delete team
      description: Soft delete a team (sets deletedAt timestamp)
      operationId: deleteTeam
      tags:
        - Teams
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '204':
          description: Team deleted successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /users/filter:
    post:
      summary: Filter users
      description: >
        Filter users using comprehensive query criteria with AND/OR logic and
        multiple operators.

        Supports complex filtering similar to GraphQL capabilities.

        Note: Soft-deleted users are excluded by default (deletedAt defaults to
        { isNull: true }).
      operationId: filterUsers
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserFilterRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 3
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: >-
                        Filter users using comprehensive query criteria with
                        AND/OR logic and multiple operators.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes: {}
                    children: []
                    type: softbreak
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: >-
                        Supports complex filtering similar to GraphQL
                        capabilities.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes: {}
                    children: []
                    type: softbreak
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: >-
                        Note: Soft-deleted users are excluded by default
                        (deletedAt defaults to { isNull: true }).
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
  /users:
    post:
      summary: Create user
      description: Create a new user in your organization
      operationId: createUser
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /users/{id}:
    get:
      summary: Get user
      description: Retrieve a user by ID or client key
      operationId: getUser
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    patch:
      summary: Update user
      description: Partially update a user. Only provided fields will be updated.
      operationId: updateUser
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserPatch'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    delete:
      summary: Delete user
      description: Soft delete a user (sets deletedAt timestamp)
      operationId: deleteUser
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
        - $ref: '#/components/parameters/LookupBy'
      responses:
        '204':
          description: User deleted successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /users/search:
    post:
      summary: Search users
      description: >
        Search users using OpenSearch-powered full-text and field-specific
        search.


        This endpoint provides fast, indexed search across user 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) users 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 user objects with all relationships
      operationId: searchUsers
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserSearchRequest'
      responses:
        '200':
          description: Successful search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /vendors/filter:
    post:
      tags:
        - Vendors
      summary: Filter vendors
      description: >
        Query vendors using flexible filter criteria with AND/OR logic.


        By default, only non-deleted vendors are returned (deletedAt: { isNull:
        true }).

        Override this by explicitly setting deletedAt filter criteria.
      operationId: filterVendors
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorFilterRequest'
      responses:
        '200':
          description: Filtered vendors with pagination
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pageInfo
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Vendor'
                  pageInfo:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /vendors:
    post:
      tags:
        - Vendors
      summary: Create a new vendor
      description: >
        Create a new vendor within an organization.


        Vendors represent service providers (warehousing, storage, etc.) that
        are not carriers.
      operationId: createVendor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorInput'
            examples:
              warehouse:
                summary: Warehouse vendor
                value:
                  name: ABC Warehouse Services
                  email: billing@abcwarehouse.com
                  phone: +1-555-123-4567
                  status: ACTIVE
                  currency: USD
                  taxId: 12-3456789
              storage:
                summary: Storage facility
                value:
                  name: SecureStore Facilities
                  email: accounts@securestore.com
                  phone: +1-555-987-6543
                  status: ACTIVE
                  currency: USD
      responses:
        '201':
          description: Vendor created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vendor'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /vendors/{id}:
    get:
      tags:
        - Vendors
      summary: Get a vendor by ID
      description: |
        Retrieve a single vendor by its unique identifier.
      operationId: getVendorById
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '200':
          description: Vendor found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vendor'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Vendors
      summary: Update a vendor
      description: |
        Partially update a vendor. Only provided fields will be updated.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      operationId: updateVendor
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorPatch'
            examples:
              updateContact:
                summary: Update contact information
                value:
                  email: newemail@abcwarehouse.com
                  phone: +1-555-999-8888
              updateStatus:
                summary: Update vendor status
                value:
                  status: INACTIVE
                  notes: Contract ended
      responses:
        '200':
          description: Vendor updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vendor'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Vendors
      summary: Delete a vendor
      description: |
        Soft delete a vendor (sets deletedAt timestamp).

        The vendor will no longer appear in default queries but can be retrieved
        by explicitly filtering for deleted records.
      operationId: deleteVendor
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '204':
          description: Vendor deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /vendors/search:
    post:
      summary: Search vendors
      description: >
        Search vendors using OpenSearch-powered full-text and field-specific
        search.


        This endpoint provides fast, indexed search across vendor 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) vendors 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 vendor objects with all relationships
      operationId: searchVendors
      tags:
        - Vendors
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorSearchRequest'
      responses:
        '200':
          description: Successful search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /vendor-contacts/filter:
    post:
      tags:
        - Vendor Contacts
      summary: Filter vendor contacts
      description: >
        Query vendor contacts using flexible filter criteria with AND/OR logic.


        By default, only non-deleted contacts are returned (deletedAt: { isNull:
        true }).

        Override this by explicitly setting deletedAt filter criteria.
      operationId: filterVendorContacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorContactFilterRequest'
      responses:
        '200':
          description: Filtered vendor contacts with pagination
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pageInfo
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/VendorContact'
                  pageInfo:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /vendor-contacts:
    post:
      tags:
        - Vendor Contacts
      summary: Create a new vendor contact
      description: >
        Create a new contact for a vendor.


        Contacts represent individuals at the vendor who can be reached for
        various purposes.
      operationId: createVendorContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorContactInput'
            examples:
              billing:
                summary: Billing contact
                value:
                  vendorId: 550e8400-e29b-41d4-a716-446655440001
                  email: billing@abcwarehouse.com
                  phone: +1-555-123-4567
                  roles:
                    - BILLING
              operations:
                summary: Operations contact
                value:
                  vendorId: 550e8400-e29b-41d4-a716-446655440001
                  email: ops@abcwarehouse.com
                  phone: +1-555-987-6543
                  roles:
                    - OPERATION
                    - AGENT
      responses:
        '201':
          description: Vendor contact created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /vendor-contacts/{id}:
    get:
      tags:
        - Vendor Contacts
      summary: Get a vendor contact by ID
      description: |
        Retrieve a single vendor contact by its unique identifier.
      operationId: getVendorContactById
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '200':
          description: Vendor contact found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Vendor Contacts
      summary: Update a vendor contact
      description: |
        Partially update a vendor contact. Only provided fields will be updated.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      operationId: updateVendorContact
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorContactPatch'
            examples:
              updateEmail:
                summary: Update email address
                value:
                  email: newemail@abcwarehouse.com
              updateRoles:
                summary: Update contact roles
                value:
                  roles:
                    - BILLING
                    - OWNER
      responses:
        '200':
          description: Vendor contact updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorContact'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Vendor Contacts
      summary: Delete a vendor contact
      description: >
        Soft delete a vendor contact (sets deletedAt timestamp).


        The contact will no longer appear in default queries but can be
        retrieved

        by explicitly filtering for deleted records.
      operationId: deleteVendorContact
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '204':
          description: Vendor contact deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /vendor-payment-methods/filter:
    post:
      tags:
        - Vendor Payment Methods
      summary: Filter vendor payment methods
      description: >
        Query vendor payment methods using flexible filter criteria with AND/OR
        logic.


        By default, only non-deleted payment methods are returned (deletedAt: {
        isNull: true }).

        Override this by explicitly setting deletedAt filter criteria.


        Vendor payment methods define how and where payments are sent for a
        specific vendor.
      operationId: filterVendorPaymentMethods
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorPaymentMethodFilterRequest'
      responses:
        '200':
          description: Filtered vendor payment methods with pagination
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pageInfo
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/VendorPaymentMethod'
                  pageInfo:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /vendor-payment-methods:
    post:
      tags:
        - Vendor Payment Methods
      summary: Create vendor payment method
      description: |
        Create a new vendor payment method.

        **Important**: The `vendorId` cannot be changed after creation.
      operationId: createVendorPaymentMethod
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorPaymentMethodInput'
            examples:
              achPayment:
                summary: ACH payment to vendor
                value:
                  vendorId: 770e8400-e29b-41d4-a716-446655440000
                  paymentMethodType: ACH
                  isPreferred: true
                  bankName: Chase Bank
                  accountName: Vendor Services Inc
                  accountNumber: '1234567890'
                  abaAch: '021000021'
                  currency: USD
              zelle:
                summary: Zelle payment
                value:
                  vendorId: 770e8400-e29b-41d4-a716-446655440000
                  paymentMethodType: ZELLE
                  email: payments@vendor.com
                  phone: +1-555-123-4567
                  username: vendor_payments
              check:
                summary: Check payment
                value:
                  vendorId: 770e8400-e29b-41d4-a716-446655440000
                  paymentMethodType: CHECK
                  companyName: Vendor Services Inc
                  isPreferred: false
      responses:
        '201':
          description: Vendor payment method created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorPaymentMethod'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /vendor-payment-methods/{id}:
    get:
      tags:
        - Vendor Payment Methods
      summary: Get vendor payment method
      description: >
        Retrieve a single vendor payment method by its unique identifier.


        Returns full details including banking information and associated vendor
        references.
      operationId: getVendorPaymentMethodById
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '200':
          description: Vendor payment method found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorPaymentMethod'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      tags:
        - Vendor Payment Methods
      summary: Update vendor payment method
      description: >
        Partially update a vendor payment method. Only provided fields will be
        updated.


        **IMPORTANT**: The `vendorId` field cannot be changed after creation.


        - **Omitted fields**: Not modified (current value preserved)

        - **Provided fields**: Updated to the new value

        - **Null values**: Clear the field (set to null) where applicable
      operationId: updateVendorPaymentMethod
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendorPaymentMethodPatch'
            examples:
              updateBanking:
                summary: Update banking details
                value:
                  bankName: Bank of America
                  accountNumber: '9876543210'
                  abaAch: '026009593'
              makePreferred:
                summary: Set as preferred payment method
                value:
                  isPreferred: true
              updateContact:
                summary: Update contact information
                value:
                  email: newemail@vendor.com
                  phone: +1-555-999-8888
      responses:
        '200':
          description: Vendor payment method updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorPaymentMethod'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
        - Vendor Payment Methods
      summary: Delete vendor payment method
      description: >
        Soft delete a vendor payment method (sets deletedAt timestamp).


        The payment method will no longer appear in default queries but can be
        retrieved

        by explicitly filtering for deleted records.
      operationId: deleteVendorPaymentMethod
      parameters:
        - $ref: '#/components/parameters/IdOrClientKey'
      responses:
        '204':
          description: Vendor payment method deleted successfully
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /saved-searches/filter:
    post:
      summary: Filter saved searches
      description: >
        Filter saved searches using comprehensive query criteria with AND/OR
        logic and multiple operators.

        Supports complex filtering similar to GraphQL capabilities.

        Returns only saved searches accessible to the authenticated user (either
        owned by them or public).
      operationId: filterSavedSearches
      tags:
        - Saved Searches
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavedSearchFilterRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SavedSearch'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /saved-searches:
    post:
      summary: Create saved search
      description: >
        Create a new saved search configuration in your organization.

        The saved search can be used to quickly apply predefined search
        criteria, sorting, and display preferences.


        The saved search will be owned by the authenticated user unless
        otherwise specified.
      operationId: createSavedSearch
      tags:
        - Saved Searches
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavedSearchInput'
      responses:
        '201':
          description: Saved search created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedSearch'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /saved-searches/{id}:
    get:
      summary: Get saved search
      description: >
        Retrieve a saved search by ID.

        You can only retrieve saved searches that you own or that are public in
        your organization.
      operationId: getSavedSearch
      tags:
        - Saved Searches
      parameters:
        - name: id
          in: path
          required: true
          description: Saved search UUID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedSearch'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    patch:
      summary: Update saved search
      description: |
        Partially update a saved search. Only provided fields will be updated.
        You can only update saved searches that you own.
      operationId: updateSavedSearch
      tags:
        - Saved Searches
      parameters:
        - name: id
          in: path
          required: true
          description: Saved search UUID
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavedSearchPatch'
      responses:
        '200':
          description: Saved search updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedSearch'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
    delete:
      summary: Delete saved search
      description: |
        Permanently delete a saved search.
        You can only delete saved searches that you own.
      operationId: deleteSavedSearch
      tags:
        - Saved Searches
      parameters:
        - name: id
          in: path
          required: true
          description: Saved search UUID
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Saved search deleted successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /global-search:
    post:
      summary: Search globally
      description: >
        Search across multiple entity types simultaneously (shipments,
        customers, carriers, users, vendors).


        **Use Cases:**

        - Unified search bar for finding any type of record

        - Quick lookup by name, ID, or reference number

        - Cross-entity discovery


        **Search Behavior:**

        - Searches across default searchable fields for each entity type

        - Results are sorted by object type priority: SHIPMENT → CUSTOMER →
        CARRIER → USER → VENDOR

        - Within each object type, results are sorted by most recently updated


        **Prefix Filtering:**

        Use "type:query" syntax to search specific object types:

        - `carrier:acme` - searches only carriers

        - `shipment:12345` - searches only shipments

        - `customer:west` - searches only customers


        **IMPORTANT: Eventually Consistent**

        This endpoint queries OpenSearch indices which are updated
        asynchronously.

        Changes typically appear within 2 seconds, but this is not guaranteed.
      operationId: globalSearch
      tags:
        - Search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GlobalSearchRequest'
            examples:
              simpleSearch:
                summary: Simple search
                value:
                  query: acme
              filteredSearch:
                summary: Filter by object types
                value:
                  query: acme
                  objects:
                    - SHIPMENT
                    - CUSTOMER
                  pagination:
                    pageNumber: 1
                    pageSize: 20
              prefixSearch:
                summary: Prefix-filtered search
                value:
                  query: carrier:trucking
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalSearchResponse'
              example:
                data:
                  - object: SHIPMENT
                    id: 550e8400-e29b-41d4-a716-446655440001
                    key: ERP-SHIP-001
                    entityName: SHIPMENT
                    title: SHIP-12345
                    subtitle: Acme Corporation
                    field: Customer
                    highlight: <em>Acme</em> Corporation
                  - object: CUSTOMER
                    id: 550e8400-e29b-41d4-a716-446655440002
                    key: ERP-CUST-001
                    entityName: SHIPPER_PROFILE
                    title: Acme Corporation
                    subtitle: CUST-001
                    field: Name
                    highlight: <em>Acme</em> Corporation
                pagination:
                  pageNumber: 1
                  pageSize: 20
                  totalPages: 3
                totalResults: 42
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
components:
  parameters:
    IdOrClientKey:
      name: id
      in: path
      required: true
      description: Resource ID (UUID) or client key
      schema:
        type: string
      example: 550e8400-e29b-41d4-a716-446655440000
    LookupBy:
      name: by
      in: query
      description: >
        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.
      schema:
        type: string
        enum:
          - id
          - key
      example: key
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 3
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: Specify lookup type for faster retrieval.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes: {}
                    children: []
                    type: softbreak
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: >-
                        If omitted, defaults to looking up by ID first, then
                        falls back to client key if not found.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes: {}
                    children: []
                    type: softbreak
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: 'Use '
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: by=key
                    children: []
                    type: code
                    annotations: []
                    slots: {}
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 3
                    inline: true
                    attributes:
                      content: ' when you know you''re providing a client key for best performance.'
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
  responses:
    BadRequestError:
      description: Bad request - invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: bad_request
            message: Invalid request parameters
    UnauthorizedError:
      description: Unauthorized - invalid or missing access token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: unauthorized
            message: Invalid or expired access token
    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: not_found
            message: Resource not found
    ConflictError:
      description: Conflict - resource already exists or constraint violation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: conflict
            message: A resource with this identifier already exists
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: internal_server_error
            message: An unexpected error occurred
    ValidationError:
      description: Validation error - invalid field values
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
          example:
            error: validation_error
            message: Invalid field values
            details:
              - field: email
                message: Must be a valid email address
              - field: status
                message: Must be one of PENDING, ACTIVE, INACTIVE
    RateLimitExceeded:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: rate_limit_exceeded
            message: Too many requests. Please retry after 60 seconds.
      headers:
        X-RateLimit-Limit:
          description: Request limit per minute
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Remaining requests in current window
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Unix timestamp when rate limit resets
          schema:
            type: integer
        Retry-After:
          description: Seconds to wait before retrying
          schema:
            type: integer
  schemas:
    PaginationInfo:
      type: object
      required:
        - pageSize
        - hasNextPage
      properties:
        pageSize:
          type: integer
          description: Number of items per page
          example: 50
        hasNextPage:
          type: boolean
          description: Whether there are more pages
          example: true
        hasPreviousPage:
          type: boolean
          description: Whether there are previous pages
          example: false
        endCursor:
          type:
            - string
            - 'null'
          description: Cursor for the next page (null if no next page)
          example: eyJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCJ9
    ResourceReference:
      type: object
      description: Reference to another resource (returned in responses)
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
          description: Resource UUID
        key:
          type:
            - string
            - 'null'
          description: Client-defined reference ID if set
      example:
        id: 550e8400-e29b-41d4-a716-446655440000
        key: ERP-USER-12345
    ResourceReferenceInput:
      type: object
      description: >-
        Reference to another resource by either ID or client key (used in
        create/update requests)
      properties:
        id:
          type: string
          format: uuid
          description: Resource UUID
        key:
          type: string
          description: Client-defined reference ID
      oneOf:
        - required:
            - id
        - required:
            - key
      example:
        id: 550e8400-e29b-41d4-a716-446655440000
    PaymentTermReference:
      type: object
      description: |
        Enhanced reference to a payment term resource (returned in responses).
        Includes full payment term details in addition to id/key.
      required:
        - id
        - name
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: Payment term UUID
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference ID if set
          example: ERP-PAYTERM-NET30
        name:
          type: string
          description: Payment term name
          example: Net 30
        description:
          type:
            - string
            - 'null'
          description: Payment term description or notes
          example: Payment due 30 days from invoice date
        days:
          type:
            - integer
            - 'null'
          description: Number of days until payment is due
          example: 30
        quickPayFee:
          type:
            - number
            - 'null'
          format: float
          description: Quick pay fee percentage (e.g., 0.05 for 5%)
          example: 0.05
          x-parsed-md-description:
            result:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 1
                        inline: true
                        attributes:
                          content: Quick pay fee percentage (e.g., 0.05 for 5%)
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: paragraph
                annotations: []
                slots: {}
        apOnly:
          type:
            - boolean
            - 'null'
          description: Whether this payment term is for accounts payable only
          example: false
        doNotUse:
          type:
            - boolean
            - 'null'
          description: Flag to prevent using this payment term for new transactions
          example: false
        createdAt:
          type: string
          format: date-time
          description: When the payment term was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          description: When the payment term was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: When the payment term was soft deleted (null if active)
          example: null
    UserReference:
      type: object
      description: >
        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.
      required:
        - id
        - email
        - status
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: User UUID
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference ID if set
          example: ERP-USER-12345
        email:
          type: string
          format: email
          description: User's email address
          example: john.doe@example.com
        name:
          type:
            - string
            - 'null'
          description: User's full name
          example: John Doe
        phone:
          type:
            - string
            - 'null'
          description: User's phone number
          example: +1-555-123-4567
        phoneExt:
          type:
            - string
            - 'null'
          description: Phone extension
          example: '123'
        status:
          type: string
          description: User account status
          enum:
            - PENDING
            - ACTIVE
            - INACTIVE
          example: ACTIVE
        avatarId:
          type:
            - string
            - 'null'
          format: uuid
          description: Profile avatar document ID
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        createdAt:
          type: string
          format: date-time
          description: When the user was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          description: When the user was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: When the user was soft deleted (null if active)
          example: null
    CustomerReference:
      type: object
      description: >
        Enhanced reference to a customer resource (returned in responses).

        Includes full customer details in addition to id/key.


        Note: Does NOT include nested references (paymentTerm, contacts, etc.)
        to prevent recursion.

        Maximum nesting depth: 1 level.
      required:
        - id
        - name
        - friendlyId
        - status
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: Customer UUID
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference ID if set
          example: ERP-CUSTOMER-ACME
        name:
          type: string
          description: Customer company name
          example: Acme Manufacturing Corp
        friendlyId:
          type: string
          description: Human-readable customer identifier
          example: A123456
        status:
          type: string
          description: Customer status
          enum:
            - PROSPECT
            - ACTIVE
            - INACTIVE
            - CHURNED
          example: ACTIVE
        phoneNumber:
          type:
            - string
            - 'null'
          description: Primary phone number
          example: +1-555-123-4567
        website:
          type:
            - string
            - 'null'
          description: Customer website URL
          example: https://acme-manufacturing.com
        createdAt:
          type: string
          format: date-time
          description: When the customer was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          description: When the customer was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: When the customer was soft deleted (null if active)
          example: null
    CarrierReference:
      type: object
      description: >
        Enhanced reference to a carrier resource (returned in responses).

        Includes full carrier details in addition to id/key.


        Note: Does NOT include nested references (contacts, etc.) to prevent
        recursion.

        Maximum nesting depth: 1 level.
      required:
        - id
        - name
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: Carrier UUID
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference ID if set
          example: ERP-CARRIER-SWIFT
        name:
          type: string
          description: Carrier company name
          example: Swift Transportation
        phoneNumber:
          type:
            - string
            - 'null'
          description: Primary phone number
          example: +1-555-987-6543
        email:
          type:
            - string
            - 'null'
          format: email
          description: Primary email address
          example: dispatch@swifttrans.com
        createdAt:
          type: string
          format: date-time
          description: When the carrier was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          description: When the carrier was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: When the carrier was soft deleted (null if active)
          example: null
    CarrierType:
      type: string
      description: >
        Type of carrier operation.


        Note: In the backend, null carrier type is represented as TRUCKLOAD in
        the public API.
      enum:
        - TRUCKLOAD
        - AIR
        - CARTAGE
        - LINEHAUL
        - LTL
        - OCEAN
        - RAIL
      example: TRUCKLOAD
    CarrierEquipment:
      type: string
      description: Equipment types that a carrier can operate
      enum:
        - CONTAINER
        - FLATBED
        - POWER_ONLY
        - REEFER
        - SPECIALIZED
        - TANKER
        - VAN
      example: VAN
    Currency:
      type: string
      description: Currency code (ISO 4217)
      enum:
        - ARS
        - AUD
        - BRL
        - CAD
        - CNY
        - EUR
        - GBP
        - IDR
        - INR
        - JPY
        - KRW
        - MXN
        - RUB
        - SAR
        - TRY
        - USD
        - ZAR
      example: USD
    CarrierBase:
      type: object
      required:
        - id
        - name
        - friendlyId
        - status
        - createdAt
        - updatedAt
      properties:
        object:
          type: string
          enum:
            - CARRIER
          readOnly: true
          description: Object type identifier
          example: CARRIER
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique carrier identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        friendlyId:
          type: string
          readOnly: true
          description: Human-readable carrier identifier
          example: C123456
        type:
          allOf:
            - $ref: '#/components/schemas/CarrierType'
          description: Carrier operation type (discriminator field)
        name:
          type: string
          description: Carrier legal name
          example: Swift Transportation Co
        dbaName:
          type:
            - string
            - 'null'
          description: Doing Business As name
          example: Swift Logistics
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CARRIER-SWIFT-001
        email:
          type:
            - string
            - 'null'
          format: email
          description: Primary email address
          example: dispatch@swifttrans.com
        phone:
          type:
            - string
            - 'null'
          description: Primary phone number
          example: +1-555-987-6543
        website:
          type:
            - string
            - 'null'
          description: Company website URL
          example: https://swifttrans.com
        status:
          type: string
          description: Carrier status
          example: ACTIVE
        statusReason:
          type:
            - string
            - 'null'
          description: Reason for current status
          example: Active and in good standing
        notes:
          type:
            - string
            - 'null'
          description: Internal notes about the carrier
          example: Preferred carrier for midwest routes
        corporateAddress:
          anyOf:
            - $ref: '#/components/schemas/Address'
            - type: 'null'
          description: Corporate headquarters address
        billingAddress:
          anyOf:
            - $ref: '#/components/schemas/Address'
            - type: 'null'
          description: Billing address for invoices
        mcNumber:
          type:
            - string
            - 'null'
          description: Motor Carrier (MC) number
          example: MC-123456
        dotNumber:
          type:
            - string
            - 'null'
          description: Department of Transportation (DOT) number
          example: '1234567'
        scac:
          type:
            - string
            - 'null'
          description: Standard Carrier Alpha Code
          example: SWFT
        einNumber:
          type:
            - string
            - 'null'
          description: Employer Identification Number
          example: 12-3456789
        ffNumber:
          type:
            - string
            - 'null'
          description: Freight Forwarder (FF) number
          example: FF-123456
        mxNumber:
          type:
            - string
            - 'null'
          description: Mexico carrier registration number
          example: MX-123456
        rfcNumber:
          type:
            - string
            - 'null'
          description: RFC (Mexico tax ID) number
          example: ABCD123456XYZ
        iataCode:
          type:
            - string
            - 'null'
          description: International Air Transport Association code
          example: AA
        equipments:
          type: array
          description: Equipment types this carrier operates
          items:
            $ref: '#/components/schemas/CarrierEquipment'
          example:
            - VAN
            - REEFER
        isHazmat:
          type:
            - boolean
            - 'null'
          description: Whether carrier is certified to transport hazardous materials
          example: false
        tsaApproved:
          type:
            - boolean
            - 'null'
          description: Whether carrier is TSA approved
          example: true
        trucks:
          type:
            - integer
            - 'null'
          description: Number of trucks in fleet
          example: 50
        trailers:
          type:
            - integer
            - 'null'
          description: Number of trailers in fleet
          example: 100
        drivers:
          type:
            - integer
            - 'null'
          description: Number of drivers employed
          example: 75
        powerUnits:
          type:
            - integer
            - 'null'
          description: Number of power units
          example: 50
        currency:
          anyOf:
            - $ref: '#/components/schemas/Currency'
            - type: 'null'
          description: Preferred currency for transactions
        paymentTerm:
          anyOf:
            - $ref: '#/components/schemas/PaymentTermReference'
            - type: 'null'
          description: Payment terms for this carrier
        isFactoringPreferred:
          type:
            - boolean
            - 'null'
          description: Whether carrier prefers factoring for payment
          example: false
        goldenCarrierId:
          type:
            - string
            - 'null'
          format: uuid
          description: Reference to golden carrier record (for deduplication)
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        paymentMethods:
          type: array
          description: Payment methods configured for this carrier
          items:
            $ref: '#/components/schemas/CarrierPaymentMethodReference'
        contacts:
          type: array
          description: Contacts for this carrier
          items:
            $ref: '#/components/schemas/CarrierContactReference'
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the carrier was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the carrier was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: When the carrier was soft deleted (null if active)
          example: null
    TruckloadCarrier:
      allOf:
        - $ref: '#/components/schemas/CarrierBase'
        - type: object
          description: Truckload carrier with insurance, safety rating, and FMCSA data
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - TRUCKLOAD
              description: Carrier type discriminator
              example: TRUCKLOAD
            insuranceCompany:
              type:
                - string
                - 'null'
              description: Insurance company name
              example: State Farm Insurance
            insuranceAgent:
              type:
                - string
                - 'null'
              description: Insurance agent name
              example: John Smith
            insuranceAgentPhone:
              type:
                - string
                - 'null'
              description: Insurance agent phone number
              example: +1-555-123-4567
            insuranceAuthorityDate:
              type:
                - string
                - 'null'
              format: date-time
              description: Date insurance authority was granted
              example: '2025-01-01T00:00:00Z'
            insuranceExpirationDate:
              type:
                - string
                - 'null'
              format: date-time
              description: Insurance policy expiration date
              example: '2025-12-31T23:59:59Z'
            insuranceAutoLiabilityLimit:
              type:
                - number
                - 'null'
              format: float
              description: Auto liability insurance limit (in dollars)
              example: 1000000
            insuranceCargoLiabilityLimit:
              type:
                - number
                - 'null'
              format: float
              description: Cargo liability insurance limit (in dollars)
              example: 100000
            insuranceGeneralLiabilityLimit:
              type:
                - number
                - 'null'
              format: float
              description: General liability insurance limit (in dollars)
              example: 1000000
            rating:
              type:
                - string
                - 'null'
              description: Carrier safety rating
              example: SATISFACTORY
            ratingDate:
              type:
                - string
                - 'null'
              format: date
              description: Date of last safety rating
              example: '2025-01-15'
            reviewType:
              type:
                - string
                - 'null'
              description: Type of safety review conducted
              example: COMPLIANCE_REVIEW
            reviewDate:
              type:
                - string
                - 'null'
              format: date
              description: Date of last safety review
              example: '2025-01-15'
            operatingAbility:
              type:
                - string
                - 'null'
              description: FMCSA operating authority status
              example: AUTHORIZED
            inFmcsa:
              type:
                - boolean
                - 'null'
              description: Whether carrier is registered in FMCSA database
              example: true
            usDriverInspections:
              type:
                - integer
                - 'null'
              description: Total number of US driver inspections
              example: 100
            usDriverInspectionsOos:
              type:
                - integer
                - 'null'
              description: Number of US driver inspections resulting in out-of-service
              example: 5
            usDriverInspectionsOosPct:
              type:
                - number
                - 'null'
              format: float
              description: Percentage of US driver inspections resulting in out-of-service
              example: 5
            usVehicleInspections:
              type:
                - integer
                - 'null'
              description: Total number of US vehicle inspections
              example: 150
            usVehicleInspectionsOos:
              type:
                - integer
                - 'null'
              description: Number of US vehicle inspections resulting in out-of-service
              example: 8
            usVehicleInspectionsOosPct:
              type:
                - number
                - 'null'
              format: float
              description: Percentage of US vehicle inspections resulting in out-of-service
              example: 5.33
    AirCarrier:
      allOf:
        - $ref: '#/components/schemas/CarrierBase'
        - type: object
          description: Air cargo carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - AIR
              description: Carrier type discriminator
              example: AIR
    CartageCarrier:
      allOf:
        - $ref: '#/components/schemas/CarrierBase'
        - type: object
          description: Cartage (local pickup/delivery) carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - CARTAGE
              description: Carrier type discriminator
              example: CARTAGE
    LinehaulCarrier:
      allOf:
        - $ref: '#/components/schemas/CarrierBase'
        - type: object
          description: Linehaul (long-distance) carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - LINEHAUL
              description: Carrier type discriminator
              example: LINEHAUL
    LtlCarrier:
      allOf:
        - $ref: '#/components/schemas/CarrierBase'
        - type: object
          description: Less-than-truckload (LTL) carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - LTL
              description: Carrier type discriminator
              example: LTL
    OceanCarrier:
      allOf:
        - $ref: '#/components/schemas/CarrierBase'
        - type: object
          description: Ocean freight carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - OCEAN
              description: Carrier type discriminator
              example: OCEAN
    RailCarrier:
      allOf:
        - $ref: '#/components/schemas/CarrierBase'
        - type: object
          description: Rail freight carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - RAIL
              description: Carrier type discriminator
              example: RAIL
    Carrier:
      oneOf:
        - $ref: '#/components/schemas/TruckloadCarrier'
        - $ref: '#/components/schemas/AirCarrier'
        - $ref: '#/components/schemas/CartageCarrier'
        - $ref: '#/components/schemas/LinehaulCarrier'
        - $ref: '#/components/schemas/LtlCarrier'
        - $ref: '#/components/schemas/OceanCarrier'
        - $ref: '#/components/schemas/RailCarrier'
      discriminator:
        propertyName: type
        mapping:
          TRUCKLOAD: '#/components/schemas/TruckloadCarrier'
          AIR: '#/components/schemas/AirCarrier'
          CARTAGE: '#/components/schemas/CartageCarrier'
          LINEHAUL: '#/components/schemas/LinehaulCarrier'
          LTL: '#/components/schemas/LtlCarrier'
          OCEAN: '#/components/schemas/OceanCarrier'
          RAIL: '#/components/schemas/RailCarrier'
    CarrierInputBase:
      type: object
      required:
        - name
        - type
      properties:
        name:
          type: string
          description: Carrier legal name
          example: Swift Transportation Co
        type:
          $ref: '#/components/schemas/CarrierType'
          description: Carrier operation type (discriminator field)
        dbaName:
          type: string
          description: Doing Business As name
          example: Swift Logistics
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CARRIER-SWIFT-001
        email:
          type: string
          format: email
          description: Primary email address
          example: dispatch@swifttrans.com
        phone:
          type: string
          description: Primary phone number
          example: +1-555-987-6543
        website:
          type: string
          description: Company website URL
          example: https://swifttrans.com
        status:
          type: string
          description: Carrier status
          example: ACTIVE
        statusReason:
          type: string
          description: Reason for current status
          example: Active and in good standing
        notes:
          type: string
          description: Internal notes about the carrier
          example: Preferred carrier for midwest routes
        corporateAddress:
          $ref: '#/components/schemas/AddressInput'
          description: Corporate headquarters address
        billingAddress:
          $ref: '#/components/schemas/AddressInput'
          description: Billing address for invoices
        mcNumber:
          type: string
          description: Motor Carrier (MC) number
          example: MC-123456
        dotNumber:
          type: string
          description: Department of Transportation (DOT) number
          example: '1234567'
        scac:
          type: string
          description: Standard Carrier Alpha Code
          example: SWFT
        einNumber:
          type: string
          description: Employer Identification Number
          example: 12-3456789
        ffNumber:
          type: string
          description: Freight Forwarder (FF) number
          example: FF-123456
        mxNumber:
          type: string
          description: Mexico carrier registration number
          example: MX-123456
        rfcNumber:
          type: string
          description: RFC (Mexico tax ID) number
          example: ABCD123456XYZ
        iataCode:
          type: string
          description: International Air Transport Association code
          example: AA
        equipments:
          type: array
          description: Equipment types this carrier operates
          items:
            $ref: '#/components/schemas/CarrierEquipment'
          example:
            - VAN
            - REEFER
        isHazmat:
          type: boolean
          description: Whether carrier is certified to transport hazardous materials
          example: false
        tsaApproved:
          type: boolean
          description: Whether carrier is TSA approved
          example: true
        trucks:
          type: integer
          description: Number of trucks in fleet
          example: 50
        trailers:
          type: integer
          description: Number of trailers in fleet
          example: 100
        drivers:
          type: integer
          description: Number of drivers employed
          example: 75
        powerUnits:
          type: integer
          description: Number of power units
          example: 50
        currency:
          $ref: '#/components/schemas/Currency'
          description: Preferred currency for transactions
        paymentTermId:
          type: string
          format: uuid
          description: Payment term ID
          example: 550e8400-e29b-41d4-a716-446655440002
        isFactoringPreferred:
          type: boolean
          description: Whether carrier prefers factoring for payment
          example: false
        goldenCarrierId:
          type: string
          format: uuid
          description: Reference to golden carrier record (for deduplication)
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
    TruckloadCarrierInput:
      allOf:
        - $ref: '#/components/schemas/CarrierInputBase'
        - type: object
          description: Input for creating a truckload carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - TRUCKLOAD
              description: Carrier type discriminator (must be TRUCKLOAD)
              example: TRUCKLOAD
            insuranceCompany:
              type: string
              description: Insurance company name
              example: State Farm Insurance
            insuranceAgent:
              type: string
              description: Insurance agent name
              example: John Smith
            insuranceAgentPhone:
              type: string
              description: Insurance agent phone number
              example: +1-555-123-4567
            insuranceAuthorityDate:
              type: string
              format: date-time
              description: Date insurance authority was granted
              example: '2025-01-01T00:00:00Z'
            insuranceExpirationDate:
              type: string
              format: date-time
              description: Insurance policy expiration date
              example: '2025-12-31T23:59:59Z'
            insuranceAutoLiabilityLimit:
              type: number
              format: float
              description: Auto liability insurance limit (in dollars)
              example: 1000000
            insuranceCargoLiabilityLimit:
              type: number
              format: float
              description: Cargo liability insurance limit (in dollars)
              example: 100000
            insuranceGeneralLiabilityLimit:
              type: number
              format: float
              description: General liability insurance limit (in dollars)
              example: 1000000
            rating:
              type: string
              description: Carrier safety rating
              example: SATISFACTORY
            ratingDate:
              type: string
              format: date
              description: Date of last safety rating
              example: '2025-01-15'
            reviewType:
              type: string
              description: Type of safety review conducted
              example: COMPLIANCE_REVIEW
            reviewDate:
              type: string
              format: date
              description: Date of last safety review
              example: '2025-01-15'
            operatingAbility:
              type: string
              description: FMCSA operating authority status
              example: AUTHORIZED
            inFmcsa:
              type: boolean
              description: Whether carrier is registered in FMCSA database
              example: true
            usDriverInspections:
              type: integer
              description: Total number of US driver inspections
              example: 100
            usDriverInspectionsOos:
              type: integer
              description: Number of US driver inspections resulting in out-of-service
              example: 5
            usDriverInspectionsOosPct:
              type: number
              format: float
              description: Percentage of US driver inspections resulting in out-of-service
              example: 5
            usVehicleInspections:
              type: integer
              description: Total number of US vehicle inspections
              example: 150
            usVehicleInspectionsOos:
              type: integer
              description: Number of US vehicle inspections resulting in out-of-service
              example: 8
            usVehicleInspectionsOosPct:
              type: number
              format: float
              description: Percentage of US vehicle inspections resulting in out-of-service
              example: 5.33
    AirCarrierInput:
      allOf:
        - $ref: '#/components/schemas/CarrierInputBase'
        - type: object
          description: Input for creating an air carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - AIR
              description: Carrier type discriminator (must be AIR)
              example: AIR
    CartageCarrierInput:
      allOf:
        - $ref: '#/components/schemas/CarrierInputBase'
        - type: object
          description: Input for creating a cartage carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - CARTAGE
              description: Carrier type discriminator (must be CARTAGE)
              example: CARTAGE
    LinehaulCarrierInput:
      allOf:
        - $ref: '#/components/schemas/CarrierInputBase'
        - type: object
          description: Input for creating a linehaul carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - LINEHAUL
              description: Carrier type discriminator (must be LINEHAUL)
              example: LINEHAUL
    LtlCarrierInput:
      allOf:
        - $ref: '#/components/schemas/CarrierInputBase'
        - type: object
          description: Input for creating an LTL carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - LTL
              description: Carrier type discriminator (must be LTL)
              example: LTL
    OceanCarrierInput:
      allOf:
        - $ref: '#/components/schemas/CarrierInputBase'
        - type: object
          description: Input for creating an ocean carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - OCEAN
              description: Carrier type discriminator (must be OCEAN)
              example: OCEAN
    RailCarrierInput:
      allOf:
        - $ref: '#/components/schemas/CarrierInputBase'
        - type: object
          description: Input for creating a rail carrier
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - RAIL
              description: Carrier type discriminator (must be RAIL)
              example: RAIL
    CarrierInput:
      oneOf:
        - $ref: '#/components/schemas/TruckloadCarrierInput'
        - $ref: '#/components/schemas/AirCarrierInput'
        - $ref: '#/components/schemas/CartageCarrierInput'
        - $ref: '#/components/schemas/LinehaulCarrierInput'
        - $ref: '#/components/schemas/LtlCarrierInput'
        - $ref: '#/components/schemas/OceanCarrierInput'
        - $ref: '#/components/schemas/RailCarrierInput'
      discriminator:
        propertyName: type
        mapping:
          TRUCKLOAD: '#/components/schemas/TruckloadCarrierInput'
          AIR: '#/components/schemas/AirCarrierInput'
          CARTAGE: '#/components/schemas/CartageCarrierInput'
          LINEHAUL: '#/components/schemas/LinehaulCarrierInput'
          LTL: '#/components/schemas/LtlCarrierInput'
          OCEAN: '#/components/schemas/OceanCarrierInput'
          RAIL: '#/components/schemas/RailCarrierInput'
    CarrierPatchBase:
      type: object
      description: |
        Partial carrier update. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        name:
          type: string
          description: Carrier legal name
          example: Swift Transportation Co
        type:
          $ref: '#/components/schemas/CarrierType'
          description: Carrier operation type
        dbaName:
          type:
            - string
            - 'null'
          description: Doing Business As name
          example: Swift Logistics
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CARRIER-SWIFT-001
        email:
          type:
            - string
            - 'null'
          format: email
          description: Primary email address
          example: dispatch@swifttrans.com
        phone:
          type:
            - string
            - 'null'
          description: Primary phone number
          example: +1-555-987-6543
        website:
          type:
            - string
            - 'null'
          description: Company website URL
          example: https://swifttrans.com
        status:
          type: string
          description: Carrier status
          example: ACTIVE
        statusReason:
          type:
            - string
            - 'null'
          description: Reason for current status
          example: Active and in good standing
        notes:
          type:
            - string
            - 'null'
          description: Internal notes about the carrier
          example: Preferred carrier for midwest routes
        corporateAddress:
          $ref: '#/components/schemas/AddressPatch'
          description: Corporate headquarters address
        billingAddress:
          $ref: '#/components/schemas/AddressPatch'
          description: Billing address for invoices
        mcNumber:
          type:
            - string
            - 'null'
          description: Motor Carrier (MC) number
          example: MC-123456
        dotNumber:
          type:
            - string
            - 'null'
          description: Department of Transportation (DOT) number
          example: '1234567'
        scac:
          type:
            - string
            - 'null'
          description: Standard Carrier Alpha Code
          example: SWFT
        einNumber:
          type:
            - string
            - 'null'
          description: Employer Identification Number
          example: 12-3456789
        ffNumber:
          type:
            - string
            - 'null'
          description: Freight Forwarder (FF) number
          example: FF-123456
        mxNumber:
          type:
            - string
            - 'null'
          description: Mexico carrier registration number
          example: MX-123456
        rfcNumber:
          type:
            - string
            - 'null'
          description: RFC (Mexico tax ID) number
          example: ABCD123456XYZ
        iataCode:
          type:
            - string
            - 'null'
          description: International Air Transport Association code
          example: AA
        equipments:
          type: array
          description: Equipment types this carrier operates
          items:
            $ref: '#/components/schemas/CarrierEquipment'
          example:
            - VAN
            - REEFER
        isHazmat:
          type:
            - boolean
            - 'null'
          description: Whether carrier is certified to transport hazardous materials
          example: false
        tsaApproved:
          type:
            - boolean
            - 'null'
          description: Whether carrier is TSA approved
          example: true
        trucks:
          type:
            - integer
            - 'null'
          description: Number of trucks in fleet
          example: 50
        trailers:
          type:
            - integer
            - 'null'
          description: Number of trailers in fleet
          example: 100
        drivers:
          type:
            - integer
            - 'null'
          description: Number of drivers employed
          example: 75
        powerUnits:
          type:
            - integer
            - 'null'
          description: Number of power units
          example: 50
        currency:
          anyOf:
            - $ref: '#/components/schemas/Currency'
            - type: 'null'
          description: Preferred currency for transactions
        paymentTermId:
          type:
            - string
            - 'null'
          format: uuid
          description: Payment term ID
          example: 550e8400-e29b-41d4-a716-446655440002
        isFactoringPreferred:
          type:
            - boolean
            - 'null'
          description: Whether carrier prefers factoring for payment
          example: false
        goldenCarrierId:
          type:
            - string
            - 'null'
          format: uuid
          description: Reference to golden carrier record (for deduplication)
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
    TruckloadCarrierPatch:
      allOf:
        - $ref: '#/components/schemas/CarrierPatchBase'
        - type: object
          description: Partial update for truckload carrier
          properties:
            type:
              type: string
              enum:
                - TRUCKLOAD
              description: >-
                Carrier type discriminator (optional - only needed if changing
                type)
              example: TRUCKLOAD
            insuranceCompany:
              type:
                - string
                - 'null'
              description: Insurance company name
              example: State Farm Insurance
            insuranceAgent:
              type:
                - string
                - 'null'
              description: Insurance agent name
              example: John Smith
            insuranceAgentPhone:
              type:
                - string
                - 'null'
              description: Insurance agent phone number
              example: +1-555-123-4567
            insuranceAuthorityDate:
              type:
                - string
                - 'null'
              format: date-time
              description: Date insurance authority was granted
              example: '2025-01-01T00:00:00Z'
            insuranceExpirationDate:
              type:
                - string
                - 'null'
              format: date-time
              description: Insurance policy expiration date
              example: '2025-12-31T23:59:59Z'
            insuranceAutoLiabilityLimit:
              type:
                - number
                - 'null'
              format: float
              description: Auto liability insurance limit (in dollars)
              example: 1000000
            insuranceCargoLiabilityLimit:
              type:
                - number
                - 'null'
              format: float
              description: Cargo liability insurance limit (in dollars)
              example: 100000
            insuranceGeneralLiabilityLimit:
              type:
                - number
                - 'null'
              format: float
              description: General liability insurance limit (in dollars)
              example: 1000000
            rating:
              type:
                - string
                - 'null'
              description: Carrier safety rating
              example: SATISFACTORY
            ratingDate:
              type:
                - string
                - 'null'
              format: date
              description: Date of last safety rating
              example: '2025-01-15'
            reviewType:
              type:
                - string
                - 'null'
              description: Type of safety review conducted
              example: COMPLIANCE_REVIEW
            reviewDate:
              type:
                - string
                - 'null'
              format: date
              description: Date of last safety review
              example: '2025-01-15'
            operatingAbility:
              type:
                - string
                - 'null'
              description: FMCSA operating authority status
              example: AUTHORIZED
            inFmcsa:
              type:
                - boolean
                - 'null'
              description: Whether carrier is registered in FMCSA database
              example: true
            usDriverInspections:
              type:
                - integer
                - 'null'
              description: Total number of US driver inspections
              example: 100
            usDriverInspectionsOos:
              type:
                - integer
                - 'null'
              description: Number of US driver inspections resulting in out-of-service
              example: 5
            usDriverInspectionsOosPct:
              type:
                - number
                - 'null'
              format: float
              description: Percentage of US driver inspections resulting in out-of-service
              example: 5
            usVehicleInspections:
              type:
                - integer
                - 'null'
              description: Total number of US vehicle inspections
              example: 150
            usVehicleInspectionsOos:
              type:
                - integer
                - 'null'
              description: Number of US vehicle inspections resulting in out-of-service
              example: 8
            usVehicleInspectionsOosPct:
              type:
                - number
                - 'null'
              format: float
              description: Percentage of US vehicle inspections resulting in out-of-service
              example: 5.33
    AirCarrierPatch:
      allOf:
        - $ref: '#/components/schemas/CarrierPatchBase'
        - type: object
          description: Partial update for air carrier
          properties:
            type:
              type: string
              enum:
                - AIR
              description: >-
                Carrier type discriminator (optional - only needed if changing
                type)
              example: AIR
    CartageCarrierPatch:
      allOf:
        - $ref: '#/components/schemas/CarrierPatchBase'
        - type: object
          description: Partial update for cartage carrier
          properties:
            type:
              type: string
              enum:
                - CARTAGE
              description: >-
                Carrier type discriminator (optional - only needed if changing
                type)
              example: CARTAGE
    LinehaulCarrierPatch:
      allOf:
        - $ref: '#/components/schemas/CarrierPatchBase'
        - type: object
          description: Partial update for linehaul carrier
          properties:
            type:
              type: string
              enum:
                - LINEHAUL
              description: >-
                Carrier type discriminator (optional - only needed if changing
                type)
              example: LINEHAUL
    LtlCarrierPatch:
      allOf:
        - $ref: '#/components/schemas/CarrierPatchBase'
        - type: object
          description: Partial update for LTL carrier
          properties:
            type:
              type: string
              enum:
                - LTL
              description: >-
                Carrier type discriminator (optional - only needed if changing
                type)
              example: LTL
    OceanCarrierPatch:
      allOf:
        - $ref: '#/components/schemas/CarrierPatchBase'
        - type: object
          description: Partial update for ocean carrier
          properties:
            type:
              type: string
              enum:
                - OCEAN
              description: >-
                Carrier type discriminator (optional - only needed if changing
                type)
              example: OCEAN
    RailCarrierPatch:
      allOf:
        - $ref: '#/components/schemas/CarrierPatchBase'
        - type: object
          description: Partial update for rail carrier
          properties:
            type:
              type: string
              enum:
                - RAIL
              description: >-
                Carrier type discriminator (optional - only needed if changing
                type)
              example: RAIL
    CarrierPatch:
      oneOf:
        - $ref: '#/components/schemas/TruckloadCarrierPatch'
        - $ref: '#/components/schemas/AirCarrierPatch'
        - $ref: '#/components/schemas/CartageCarrierPatch'
        - $ref: '#/components/schemas/LinehaulCarrierPatch'
        - $ref: '#/components/schemas/LtlCarrierPatch'
        - $ref: '#/components/schemas/OceanCarrierPatch'
        - $ref: '#/components/schemas/RailCarrierPatch'
      discriminator:
        propertyName: type
        mapping:
          TRUCKLOAD: '#/components/schemas/TruckloadCarrierPatch'
          AIR: '#/components/schemas/AirCarrierPatch'
          CARTAGE: '#/components/schemas/CartageCarrierPatch'
          LINEHAUL: '#/components/schemas/LinehaulCarrierPatch'
          LTL: '#/components/schemas/LtlCarrierPatch'
          OCEAN: '#/components/schemas/OceanCarrierPatch'
          RAIL: '#/components/schemas/RailCarrierPatch'
    CarrierFilter:
      type: object
      description: Filter criteria for carriers with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/CarrierFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/CarrierFilter'
        not:
          $ref: '#/components/schemas/CarrierFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        friendlyId:
          $ref: '#/components/schemas/StringFilter'
        name:
          $ref: '#/components/schemas/StringFilter'
        dbaName:
          $ref: '#/components/schemas/StringFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        email:
          $ref: '#/components/schemas/StringFilter'
        phone:
          $ref: '#/components/schemas/StringFilter'
        website:
          $ref: '#/components/schemas/StringFilter'
        status:
          $ref: '#/components/schemas/StringFilter'
        statusReason:
          $ref: '#/components/schemas/StringFilter'
        type:
          $ref: '#/components/schemas/StringFilter'
        mcNumber:
          $ref: '#/components/schemas/StringFilter'
        dotNumber:
          $ref: '#/components/schemas/StringFilter'
        scac:
          $ref: '#/components/schemas/StringFilter'
        einNumber:
          $ref: '#/components/schemas/StringFilter'
        ffNumber:
          $ref: '#/components/schemas/StringFilter'
        mxNumber:
          $ref: '#/components/schemas/StringFilter'
        rfcNumber:
          $ref: '#/components/schemas/StringFilter'
        iataCode:
          $ref: '#/components/schemas/StringFilter'
        isHazmat:
          $ref: '#/components/schemas/BooleanFilter'
        tsaApproved:
          $ref: '#/components/schemas/BooleanFilter'
        trucks:
          $ref: '#/components/schemas/IntFilter'
        trailers:
          $ref: '#/components/schemas/IntFilter'
        drivers:
          $ref: '#/components/schemas/IntFilter'
        powerUnits:
          $ref: '#/components/schemas/IntFilter'
        currency:
          $ref: '#/components/schemas/StringFilter'
        isFactoringPreferred:
          $ref: '#/components/schemas/BooleanFilter'
        goldenCarrierId:
          $ref: '#/components/schemas/UUIDFilter'
        paymentTermId:
          $ref: '#/components/schemas/UUIDFilter'
        rating:
          $ref: '#/components/schemas/StringFilter'
        ratingDate:
          $ref: '#/components/schemas/DatetimeFilter'
        operatingAbility:
          $ref: '#/components/schemas/StringFilter'
        inFmcsa:
          $ref: '#/components/schemas/BooleanFilter'
        insuranceCompany:
          $ref: '#/components/schemas/StringFilter'
        insuranceExpirationDate:
          $ref: '#/components/schemas/DatetimeFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    CarrierFilterRequest:
      type: object
      description: Request body for filtering carriers
      properties:
        filter:
          $ref: '#/components/schemas/CarrierFilter'
          description: >
            Filter criteria (optional - omit to return all carriers).


            Note: deletedAt automatically defaults to { isNull: true } unless
            explicitly overridden.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - type:
                equalTo: TRUCKLOAD
            - status:
                equalTo: ACTIVE
            - inFmcsa:
                equalTo: true
        pageSize: 50
    CarrierFactor:
      type: object
      required:
        - id
        - companyName
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique carrier factor identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        companyName:
          type: string
          description: Factoring company legal name
          example: Capital Factoring Services Inc
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-FACTOR-001
        email:
          type:
            - string
            - 'null'
          format: email
          description: Primary email address
          example: accounting@capitalfactoring.com
        phoneNumber:
          type:
            - string
            - 'null'
          description: Primary phone number
          example: +1-555-234-5678
        addressLine1:
          type:
            - string
            - 'null'
          description: Primary street address
          example: 789 Finance Ave
        addressLine2:
          type:
            - string
            - 'null'
          description: Secondary address line (suite, floor, etc.)
          example: Suite 500
        city:
          type:
            - string
            - 'null'
          description: City name
          example: Dallas
        state:
          type:
            - string
            - 'null'
          description: State or province
          example: TX
        country:
          type:
            - string
            - 'null'
          description: Country code or name
          example: USA
        zipCode:
          type:
            - string
            - 'null'
          description: Postal/ZIP code
          example: '75201'
        bankName:
          type:
            - string
            - 'null'
          description: Bank name
          example: Chase Bank
        bankAddress:
          type:
            - string
            - 'null'
          description: Bank address
          example: 123 Bank Street, Dallas, TX 75201
        accountName:
          type:
            - string
            - 'null'
          description: Bank account holder name
          example: Capital Factoring Services Inc
        accountNumber:
          type:
            - string
            - 'null'
          description: Bank account number
          example: '****1234'
        abaAch:
          type:
            - string
            - 'null'
          description: ABA/ACH routing number for electronic transfers
          example: '021000021'
        wire:
          type:
            - string
            - 'null'
          description: Wire transfer routing number
          example: '026009593'
        swiftCode:
          type:
            - string
            - 'null'
          description: SWIFT/BIC code for international transfers
          example: CHASUS33
        eftInstitution:
          type:
            - string
            - 'null'
          description: EFT institution number (Canadian banking)
          example: '001'
        eftTransit:
          type:
            - string
            - 'null'
          description: EFT transit number (Canadian banking)
          example: '00010'
        clabe:
          type:
            - string
            - 'null'
          description: CLABE number (Mexican banking identifier)
          example: '012180001234567897'
        currency:
          type:
            - string
            - 'null'
          description: Preferred currency code (ISO 4217)
          example: USD
        paymentTerm:
          anyOf:
            - $ref: '#/components/schemas/PaymentTermReference'
            - type: 'null'
          description: Payment terms for this factoring company
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the carrier factor was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the carrier factor was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: When the carrier factor was soft deleted (null if active)
          example: null
    CarrierFactorInput:
      type: object
      required:
        - companyName
      properties:
        companyName:
          type: string
          description: Factoring company legal name
          example: Capital Factoring Services Inc
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-FACTOR-001
        email:
          type: string
          format: email
          description: Primary email address
          example: accounting@capitalfactoring.com
        phoneNumber:
          type: string
          description: Primary phone number
          example: +1-555-234-5678
        addressLine1:
          type: string
          description: Primary street address
          example: 789 Finance Ave
        addressLine2:
          type: string
          description: Secondary address line (suite, floor, etc.)
          example: Suite 500
        city:
          type: string
          description: City name
          example: Dallas
        state:
          type: string
          description: State or province
          example: TX
        country:
          type: string
          description: Country code or name
          example: USA
        zipCode:
          type: string
          description: Postal/ZIP code
          example: '75201'
        bankName:
          type: string
          description: Bank name
          example: Chase Bank
        bankAddress:
          type: string
          description: Bank address
          example: 123 Bank Street, Dallas, TX 75201
        accountName:
          type: string
          description: Bank account holder name
          example: Capital Factoring Services Inc
        accountNumber:
          type: string
          description: Bank account number
          example: '1234567890'
        abaAch:
          type: string
          description: ABA/ACH routing number for electronic transfers
          example: '021000021'
        wire:
          type: string
          description: Wire transfer routing number
          example: '026009593'
        swiftCode:
          type: string
          description: SWIFT/BIC code for international transfers
          example: CHASUS33
        eftInstitution:
          type: string
          description: EFT institution number (Canadian banking)
          example: '001'
        eftTransit:
          type: string
          description: EFT transit number (Canadian banking)
          example: '00010'
        clabe:
          type: string
          description: CLABE number (Mexican banking identifier)
          example: '012180001234567897'
        currency:
          type: string
          description: Preferred currency code (ISO 4217)
          example: USD
        paymentTermId:
          type: string
          format: uuid
          description: Payment term ID
          example: 550e8400-e29b-41d4-a716-446655440002
    CarrierFactorPatch:
      type: object
      description: |
        Partial carrier factor update. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        companyName:
          type: string
          description: Factoring company legal name
          example: Capital Factoring Services Inc
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-FACTOR-001
        email:
          type:
            - string
            - 'null'
          format: email
          description: Primary email address
          example: accounting@capitalfactoring.com
        phoneNumber:
          type:
            - string
            - 'null'
          description: Primary phone number
          example: +1-555-234-5678
        addressLine1:
          type:
            - string
            - 'null'
          description: Primary street address
          example: 789 Finance Ave
        addressLine2:
          type:
            - string
            - 'null'
          description: Secondary address line
          example: Suite 500
        city:
          type:
            - string
            - 'null'
          description: City name
          example: Dallas
        state:
          type:
            - string
            - 'null'
          description: State or province
          example: TX
        country:
          type:
            - string
            - 'null'
          description: Country code or name
          example: USA
        zipCode:
          type:
            - string
            - 'null'
          description: Postal/ZIP code
          example: '75201'
        bankName:
          type:
            - string
            - 'null'
          description: Bank name
          example: Chase Bank
        bankAddress:
          type:
            - string
            - 'null'
          description: Bank address
          example: 123 Bank Street, Dallas, TX 75201
        accountName:
          type:
            - string
            - 'null'
          description: Bank account holder name
          example: Capital Factoring Services Inc
        accountNumber:
          type:
            - string
            - 'null'
          description: Bank account number
          example: '1234567890'
        abaAch:
          type:
            - string
            - 'null'
          description: ABA/ACH routing number
          example: '021000021'
        wire:
          type:
            - string
            - 'null'
          description: Wire transfer routing number
          example: '026009593'
        swiftCode:
          type:
            - string
            - 'null'
          description: SWIFT/BIC code for international transfers
          example: CHASUS33
        eftInstitution:
          type:
            - string
            - 'null'
          description: EFT institution number (Canadian banking)
          example: '001'
        eftTransit:
          type:
            - string
            - 'null'
          description: EFT transit number (Canadian banking)
          example: '00010'
        clabe:
          type:
            - string
            - 'null'
          description: CLABE number (Mexican banking)
          example: '012180001234567897'
        currency:
          type:
            - string
            - 'null'
          description: Preferred currency code (ISO 4217)
          example: USD
        paymentTermId:
          type:
            - string
            - 'null'
          format: uuid
          description: Payment term ID
          example: 550e8400-e29b-41d4-a716-446655440002
    CarrierFactorFilter:
      type: object
      description: Filter criteria for carrier factors with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/CarrierFactorFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/CarrierFactorFilter'
        not:
          $ref: '#/components/schemas/CarrierFactorFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        companyName:
          $ref: '#/components/schemas/StringFilter'
        email:
          $ref: '#/components/schemas/StringFilter'
        phoneNumber:
          $ref: '#/components/schemas/StringFilter'
        city:
          $ref: '#/components/schemas/StringFilter'
        state:
          $ref: '#/components/schemas/StringFilter'
        country:
          $ref: '#/components/schemas/StringFilter'
        zipCode:
          $ref: '#/components/schemas/StringFilter'
        bankName:
          $ref: '#/components/schemas/StringFilter'
        currency:
          $ref: '#/components/schemas/StringFilter'
        paymentTermId:
          $ref: '#/components/schemas/UUIDFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    CarrierFactorFilterRequest:
      type: object
      description: Request body for filtering carrier factors
      properties:
        filter:
          $ref: '#/components/schemas/CarrierFactorFilter'
          description: >
            Filter criteria (optional - omit to return all carrier factors).


            Note: deletedAt automatically defaults to { isNull: true } unless
            explicitly overridden.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - companyName:
                includes: Capital
            - currency:
                equalTo: USD
        pageSize: 50
    CarrierFactorReference:
      type: object
      description: |
        Enhanced reference to a carrier factor (factoring company).
        Includes full carrier factor details in addition to id/key.
      required:
        - id
        - companyName
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: Carrier factor UUID
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference ID if set
          example: ERP-FACTOR-001
        companyName:
          type: string
          description: Factoring company legal name
          example: Capital Factoring Services Inc
        email:
          type:
            - string
            - 'null'
          format: email
          description: Primary email address
          example: accounting@capitalfactoring.com
        phoneNumber:
          type:
            - string
            - 'null'
          description: Primary phone number
          example: +1-555-234-5678
        currency:
          type:
            - string
            - 'null'
          description: Preferred currency code (ISO 4217)
          example: USD
        createdAt:
          type: string
          format: date-time
          description: When the carrier factor was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          description: When the carrier factor was last updated
          example: '2025-01-15T14:30:00Z'
    PaymentRecipientType:
      type: string
      description: >
        Who receives the payment.


        - `DIRECT`: Payment goes directly to the carrier

        - `FACTOR`: Payment goes to a factoring company (requires
        carrierFactorId)
      enum:
        - DIRECT
        - FACTOR
      example: DIRECT
    PaymentRecipientTypeFilter:
      type: object
      description: Filter for payment recipient type
      properties:
        equalTo:
          $ref: '#/components/schemas/PaymentRecipientType'
        notEqualTo:
          $ref: '#/components/schemas/PaymentRecipientType'
        in:
          type: array
          items:
            $ref: '#/components/schemas/PaymentRecipientType'
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/PaymentRecipientType'
    PaymentMethodType:
      type: string
      description: Payment method type
      enum:
        - ACH_WIRE
        - ZELLE
        - VENMO
        - ACH
        - CHECK
        - WIRE
        - CAD_EFT
        - TRIUMPH_PAY
        - COMCHECK
        - EFS
        - ECHECK
      example: ACH
    PaymentMethodTypeFilter:
      type: object
      description: Filter for payment method type
      properties:
        equalTo:
          $ref: '#/components/schemas/PaymentMethodType'
        notEqualTo:
          $ref: '#/components/schemas/PaymentMethodType'
        in:
          type: array
          items:
            $ref: '#/components/schemas/PaymentMethodType'
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/PaymentMethodType'
    CarrierPaymentMethod:
      type: object
      required:
        - id
        - carrierId
        - carrier
        - paymentRecipientType
        - paymentMethodType
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique carrier payment method identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        carrierId:
          type: string
          format: uuid
          readOnly: true
          description: |
            Carrier profile ID (read-only after creation).

            This field cannot be changed after the payment method is created.
          example: 770e8400-e29b-41d4-a716-446655440000
        carrier:
          $ref: '#/components/schemas/CarrierReference'
          description: Carrier profile reference with full details
        paymentRecipientType:
          $ref: '#/components/schemas/PaymentRecipientType'
          description: >
            Who receives the payment.


            - **DIRECT**: Payment goes directly to the carrier (carrierFactorId
            must be null)

            - **FACTOR**: Payment goes to a factoring company (carrierFactorId
            is required)
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType'
          description: How payment is made
        status:
          type:
            - string
            - 'null'
          description: Payment method status
          example: ACTIVE
        isPreferred:
          type:
            - boolean
            - 'null'
          description: Whether this is the preferred payment method for the carrier
          example: true
        email:
          type:
            - string
            - 'null'
          format: email
          description: Email address for payment notifications
          example: payments@carrier.com
        phone:
          type:
            - string
            - 'null'
          description: Phone number for payment contact
          example: +1-555-123-4567
        companyName:
          type:
            - string
            - 'null'
          description: Company name for this payment method (may differ from carrier name)
          example: Carrier Payments LLC
        username:
          type:
            - string
            - 'null'
          description: Username for payment platforms (e.g., Zelle, Venmo)
          example: carrier_payments
        bankName:
          type:
            - string
            - 'null'
          description: Bank name
          example: Chase Bank
        bankAddress:
          type:
            - string
            - 'null'
          description: Bank address
          example: 123 Bank Street, Dallas, TX 75201
        accountName:
          type:
            - string
            - 'null'
          description: Bank account holder name
          example: Carrier Transport Inc
        accountNumber:
          type:
            - string
            - 'null'
          description: Bank account number (masked in responses)
          example: '****1234'
        abaAch:
          type:
            - string
            - 'null'
          description: ABA/ACH routing number for electronic transfers
          example: '021000021'
        wire:
          type:
            - string
            - 'null'
          description: Wire transfer routing number
          example: '026009593'
        swiftCode:
          type:
            - string
            - 'null'
          description: SWIFT/BIC code for international transfers
          example: CHASUS33
        eftInstitution:
          type:
            - string
            - 'null'
          description: EFT institution number (Canadian banking)
          example: '001'
        eftTransit:
          type:
            - string
            - 'null'
          description: EFT transit number (Canadian banking)
          example: '00010'
        clabe:
          type:
            - string
            - 'null'
          description: CLABE number (Mexican banking identifier)
          example: '012180001234567897'
        currency:
          type:
            - string
            - 'null'
          description: Preferred currency code (ISO 4217)
          example: USD
        carrierFactor:
          anyOf:
            - $ref: '#/components/schemas/CarrierFactorReference'
            - type: 'null'
          description: >
            Factoring company reference (required when paymentRecipientType is
            FACTOR).


            When paymentRecipientType is DIRECT, this must be null.
        paymentTerm:
          anyOf:
            - $ref: '#/components/schemas/PaymentTermReference'
            - type: 'null'
          description: Payment terms for this payment method
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment method was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment method was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: When the payment method was soft deleted (null if active)
          example: null
        deletedBy:
          anyOf:
            - $ref: '#/components/schemas/UserReference'
            - type: 'null'
          readOnly: true
          description: User who deleted this payment method
    CarrierPaymentMethodInput:
      type: object
      required:
        - carrierId
        - paymentRecipientType
        - paymentMethodType
      properties:
        carrierId:
          type: string
          format: uuid
          description: |
            Carrier profile ID.

            **IMPORTANT**: This field cannot be changed after creation.
          example: 770e8400-e29b-41d4-a716-446655440000
        paymentRecipientType:
          $ref: '#/components/schemas/PaymentRecipientType'
          description: |
            Who receives the payment.

            - **DIRECT**: carrierFactorId must be null or omitted
            - **FACTOR**: carrierFactorId is required
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType'
          description: How payment is made
        status:
          type: string
          description: Payment method status
          example: ACTIVE
        isPreferred:
          type: boolean
          description: Whether this is the preferred payment method
          example: true
        email:
          type: string
          format: email
          description: Email address for payment notifications
          example: payments@carrier.com
        phone:
          type: string
          description: Phone number for payment contact
          example: +1-555-123-4567
        companyName:
          type: string
          description: Company name for this payment method
          example: Carrier Payments LLC
        username:
          type: string
          description: Username for payment platforms
          example: carrier_payments
        bankName:
          type: string
          description: Bank name
          example: Chase Bank
        bankAddress:
          type: string
          description: Bank address
          example: 123 Bank Street, Dallas, TX 75201
        accountName:
          type: string
          description: Bank account holder name
          example: Carrier Transport Inc
        accountNumber:
          type: string
          description: Bank account number
          example: '1234567890'
        abaAch:
          type: string
          description: ABA/ACH routing number
          example: '021000021'
        wire:
          type: string
          description: Wire transfer routing number
          example: '026009593'
        swiftCode:
          type: string
          description: SWIFT/BIC code for international transfers
          example: CHASUS33
        eftInstitution:
          type: string
          description: EFT institution number (Canadian banking)
          example: '001'
        eftTransit:
          type: string
          description: EFT transit number (Canadian banking)
          example: '00010'
        clabe:
          type: string
          description: CLABE number (Mexican banking)
          example: '012180001234567897'
        currency:
          type: string
          description: Preferred currency code (ISO 4217)
          example: USD
        carrierFactorId:
          type: string
          format: uuid
          description: >
            Carrier factor (factoring company) ID.


            **Constraint**: Required when paymentRecipientType is FACTOR, must
            be null when DIRECT.
          example: 550e8400-e29b-41d4-a716-446655440000
        paymentTermId:
          type: string
          format: uuid
          description: Payment term ID
          example: 550e8400-e29b-41d4-a716-446655440002
    CarrierPaymentMethodPatch:
      type: object
      description: |
        Partial carrier payment method update. All fields are optional.

        **IMPORTANT**: The `carrierId` field cannot be changed after creation.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        paymentRecipientType:
          $ref: '#/components/schemas/PaymentRecipientType'
          description: |
            Who receives the payment.

            - **DIRECT**: carrierFactorId must be null
            - **FACTOR**: carrierFactorId is required
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType'
          description: How payment is made
        status:
          type:
            - string
            - 'null'
          description: Payment method status
          example: ACTIVE
        isPreferred:
          type:
            - boolean
            - 'null'
          description: Whether this is the preferred payment method
          example: true
        email:
          type:
            - string
            - 'null'
          format: email
          description: Email address for payment notifications
          example: payments@carrier.com
        phone:
          type:
            - string
            - 'null'
          description: Phone number for payment contact
          example: +1-555-123-4567
        companyName:
          type:
            - string
            - 'null'
          description: Company name for this payment method
          example: Carrier Payments LLC
        username:
          type:
            - string
            - 'null'
          description: Username for payment platforms
          example: carrier_payments
        bankName:
          type:
            - string
            - 'null'
          description: Bank name
          example: Chase Bank
        bankAddress:
          type:
            - string
            - 'null'
          description: Bank address
          example: 123 Bank Street, Dallas, TX 75201
        accountName:
          type:
            - string
            - 'null'
          description: Bank account holder name
          example: Carrier Transport Inc
        accountNumber:
          type:
            - string
            - 'null'
          description: Bank account number
          example: '1234567890'
        abaAch:
          type:
            - string
            - 'null'
          description: ABA/ACH routing number
          example: '021000021'
        wire:
          type:
            - string
            - 'null'
          description: Wire transfer routing number
          example: '026009593'
        swiftCode:
          type:
            - string
            - 'null'
          description: SWIFT/BIC code
          example: CHASUS33
        eftInstitution:
          type:
            - string
            - 'null'
          description: EFT institution number
          example: '001'
        eftTransit:
          type:
            - string
            - 'null'
          description: EFT transit number
          example: '00010'
        clabe:
          type:
            - string
            - 'null'
          description: CLABE number
          example: '012180001234567897'
        currency:
          type:
            - string
            - 'null'
          description: Preferred currency code
          example: USD
        carrierFactorId:
          type:
            - string
            - 'null'
          format: uuid
          description: >
            Carrier factor ID.


            **Constraint**: Required when paymentRecipientType is FACTOR, must
            be null when DIRECT.
          example: 550e8400-e29b-41d4-a716-446655440000
        paymentTermId:
          type:
            - string
            - 'null'
          format: uuid
          description: Payment term ID
          example: 550e8400-e29b-41d4-a716-446655440002
    CarrierPaymentMethodFilter:
      type: object
      description: Filter criteria for carrier payment methods with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/CarrierPaymentMethodFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/CarrierPaymentMethodFilter'
        not:
          $ref: '#/components/schemas/CarrierPaymentMethodFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        carrierId:
          $ref: '#/components/schemas/UUIDFilter'
        paymentRecipientType:
          $ref: '#/components/schemas/PaymentRecipientTypeFilter'
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodTypeFilter'
        status:
          $ref: '#/components/schemas/StringFilter'
        isPreferred:
          $ref: '#/components/schemas/BooleanFilter'
        email:
          $ref: '#/components/schemas/StringFilter'
        companyName:
          $ref: '#/components/schemas/StringFilter'
        bankName:
          $ref: '#/components/schemas/StringFilter'
        currency:
          $ref: '#/components/schemas/StringFilter'
        carrierFactorId:
          $ref: '#/components/schemas/UUIDFilter'
        paymentTermId:
          $ref: '#/components/schemas/UUIDFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    CarrierPaymentMethodFilterRequest:
      type: object
      description: Request body for filtering carrier payment methods
      properties:
        filter:
          $ref: '#/components/schemas/CarrierPaymentMethodFilter'
          description: >
            Filter criteria (optional - omit to return all carrier payment
            methods).


            Note: deletedAt automatically defaults to { isNull: true } unless
            explicitly overridden.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - carrierId:
                equalTo: 770e8400-e29b-41d4-a716-446655440000
            - paymentRecipientType:
                equalTo: DIRECT
            - isPreferred:
                equalTo: true
        pageSize: 50
    Address:
      type: object
      description: >
        Physical address/location details (nested, without id).


        This is an embedded object representing a Location record. The id is
        managed

        internally and not exposed in the API.
      required:
        - line1
        - city
        - country
        - market
        - isAirportOrAirbase
        - isConstructionOrUtilitySite
        - isSmartyValidated
        - obeysDst
      properties:
        line1:
          type: string
          description: Primary street address line
          example: 123 Main St
        line2:
          type:
            - string
            - 'null'
          description: Secondary address line (suite, floor, etc.)
          example: Suite 400
        city:
          type: string
          description: City name
          example: Chicago
        country:
          type: string
          description: Country name or code
          example: USA
        market:
          type: string
          description: Market or region identifier
          example: CHI
        latitude:
          type:
            - string
            - 'null'
          description: Latitude coordinate
          example: '41.8781'
        longitude:
          type:
            - string
            - 'null'
          description: Longitude coordinate
          example: '-87.6298'
        isAirportOrAirbase:
          type: boolean
          description: Whether this location is an airport or airbase
          example: false
        isConstructionOrUtilitySite:
          type: boolean
          description: Whether this location is a construction or utility site
          example: false
        isSmartyValidated:
          type: boolean
          description: Whether address has been validated by SmartyStreets
          example: true
        obeysDst:
          type: boolean
          description: Whether this location observes daylight saving time
          example: true
        cityId:
          type:
            - string
            - 'null'
          format: uuid
          description: Reference to standardized city record (internal use)
          example: null
    AddressInput:
      type: object
      description: Address data for creating a new location
      required:
        - line1
        - city
        - country
        - market
      properties:
        line1:
          type: string
          description: Primary street address line
          example: 123 Main St
        line2:
          type: string
          description: Secondary address line (suite, floor, etc.)
          example: Suite 400
        city:
          type: string
          description: City name
          example: Chicago
        country:
          type: string
          description: Country name or code
          example: USA
        market:
          type: string
          description: Market or region identifier
          example: CHI
        latitude:
          type: string
          description: Latitude coordinate
          example: '41.8781'
        longitude:
          type: string
          description: Longitude coordinate
          example: '-87.6298'
        isAirportOrAirbase:
          type: boolean
          default: false
          description: Whether this location is an airport or airbase
          example: false
        isConstructionOrUtilitySite:
          type: boolean
          default: false
          description: Whether this location is a construction or utility site
          example: false
        isSmartyValidated:
          type: boolean
          default: false
          description: Whether address has been validated by SmartyStreets
          example: true
        obeysDst:
          type: boolean
          default: true
          description: Whether this location observes daylight saving time
          example: true
        cityId:
          type: string
          format: uuid
          description: Reference to standardized city record (internal use)
    AddressPatch:
      type: object
      description: |
        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
      properties:
        line1:
          type: string
          description: Primary street address line
          example: 123 Main St
        line2:
          type:
            - string
            - 'null'
          description: Secondary address line
          example: Suite 400
        city:
          type: string
          description: City name
          example: Chicago
        country:
          type: string
          description: Country name or code
          example: USA
        market:
          type: string
          description: Market or region identifier
          example: CHI
        latitude:
          type:
            - string
            - 'null'
          description: Latitude coordinate
          example: '41.8781'
        longitude:
          type:
            - string
            - 'null'
          description: Longitude coordinate
          example: '-87.6298'
        isAirportOrAirbase:
          type: boolean
          description: Whether this location is an airport or airbase
          example: false
        isConstructionOrUtilitySite:
          type: boolean
          description: Whether this location is a construction or utility site
          example: false
        isSmartyValidated:
          type: boolean
          description: Whether address has been validated by SmartyStreets
          example: true
        obeysDst:
          type: boolean
          description: Whether this location observes daylight saving time
          example: true
        cityId:
          type:
            - string
            - 'null'
          format: uuid
          description: Reference to standardized city record
          example: null
    ContactInfo:
      type: object
      description: >
        Contact information details (nested, without id).


        This is an embedded object representing a Contact record. The id is
        managed

        internally and not exposed in the API.
      required:
        - name
      properties:
        name:
          type: string
          description: Contact person's full name
          example: John Smith
        email:
          type:
            - string
            - 'null'
          format: email
          description: Email address
          example: john.smith@example.com
        phoneNumber:
          type:
            - string
            - 'null'
          description: Phone number
          example: +1-555-0100
        title:
          type:
            - string
            - 'null'
          description: Job title or position
          example: Operations Manager
    ContactInfoInput:
      type: object
      description: Contact information for creating a new contact record
      required:
        - name
      properties:
        name:
          type: string
          description: Contact person's full name
          example: John Smith
        email:
          type: string
          format: email
          description: Email address
          example: john.smith@example.com
        phoneNumber:
          type: string
          description: Phone number
          example: +1-555-0100
        title:
          type: string
          description: Job title or position
          example: Operations Manager
    ContactInfoPatch:
      type: object
      description: |
        Partial contact information update. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        name:
          type: string
          description: Contact person's full name
          example: John Smith
        email:
          type:
            - string
            - 'null'
          format: email
          description: Email address
          example: john.smith@example.com
        phoneNumber:
          type:
            - string
            - 'null'
          description: Phone number
          example: +1-555-0100
        title:
          type:
            - string
            - 'null'
          description: Job title or position
          example: Operations Manager
    StringFilter:
      type: object
      description: Filter options for string fields
      properties:
        equalTo:
          type: string
          description: Exact match
        notEqualTo:
          type: string
          description: Not equal to
        in:
          type: array
          items:
            type: string
          description: Matches any value in the array
        notIn:
          type: array
          items:
            type: string
          description: Does not match any value in the array
        includes:
          type: string
          description: Contains substring (case-insensitive)
        notIncludes:
          type: string
          description: Does not contain substring (case-insensitive)
        startsWith:
          type: string
          description: Starts with prefix (case-insensitive)
        notStartsWith:
          type: string
          description: Does not start with prefix (case-insensitive)
        endsWith:
          type: string
          description: Ends with suffix (case-insensitive)
        notEndsWith:
          type: string
          description: Does not end with suffix (case-insensitive)
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    IntFilter:
      type: object
      description: Filter options for integer fields
      properties:
        equalTo:
          type: integer
          description: Exact match
        notEqualTo:
          type: integer
          description: Not equal to
        lessThan:
          type: integer
          description: Less than
        lessThanOrEqualTo:
          type: integer
          description: Less than or equal to
        greaterThan:
          type: integer
          description: Greater than
        greaterThanOrEqualTo:
          type: integer
          description: Greater than or equal to
        in:
          type: array
          items:
            type: integer
          description: Matches any value in the array
        notIn:
          type: array
          items:
            type: integer
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    FloatFilter:
      type: object
      description: Filter options for float/number fields
      properties:
        equalTo:
          type: number
          format: float
          description: Exact match
        notEqualTo:
          type: number
          format: float
          description: Not equal to
        lessThan:
          type: number
          format: float
          description: Less than
        lessThanOrEqualTo:
          type: number
          format: float
          description: Less than or equal to
        greaterThan:
          type: number
          format: float
          description: Greater than
        greaterThanOrEqualTo:
          type: number
          format: float
          description: Greater than or equal to
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    BooleanFilter:
      type: object
      description: Filter options for boolean fields
      properties:
        equalTo:
          type: boolean
          description: Exact match
        notEqualTo:
          type: boolean
          description: Not equal to
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    DatetimeFilter:
      type: object
      description: Filter options for datetime fields
      properties:
        equalTo:
          type: string
          format: date-time
          description: Exact match
        notEqualTo:
          type: string
          format: date-time
          description: Not equal to
        lessThan:
          type: string
          format: date-time
          description: Before this datetime
        lessThanOrEqualTo:
          type: string
          format: date-time
          description: On or before this datetime
        greaterThan:
          type: string
          format: date-time
          description: After this datetime
        greaterThanOrEqualTo:
          type: string
          format: date-time
          description: On or after this datetime
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    IDFilter:
      type: object
      description: Filter options for ID fields (limited operations - exact match only)
      properties:
        equalTo:
          type: string
          format: uuid
          description: Exact match
        in:
          type: array
          description: Matches any UUID in the array
          items:
            type: string
            format: uuid
    ClientKeyFilter:
      type: object
      description: >-
        Filter options for client key fields (limited operations - exact match
        only)
      properties:
        equalTo:
          type: string
          description: Exact match
        in:
          type: array
          description: Matches any value in the array
          items:
            type: string
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CompanyFilter:
      type: object
      description: Filter criteria for companies with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/CompanyFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/CompanyFilter'
        not:
          $ref: '#/components/schemas/CompanyFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        name:
          $ref: '#/components/schemas/StringFilter'
        addressLine1:
          $ref: '#/components/schemas/StringFilter'
        addressLine2:
          $ref: '#/components/schemas/StringFilter'
        city:
          $ref: '#/components/schemas/StringFilter'
        country:
          $ref: '#/components/schemas/StringFilter'
        fax:
          $ref: '#/components/schemas/StringFilter'
        invoiceOnly:
          $ref: '#/components/schemas/BooleanFilter'
        invoiceVerbiage:
          $ref: '#/components/schemas/StringFilter'
        primaryContactName:
          $ref: '#/components/schemas/StringFilter'
        primaryContactEmail:
          $ref: '#/components/schemas/StringFilter'
        primaryContactPhone:
          $ref: '#/components/schemas/StringFilter'
        createdById:
          $ref: '#/components/schemas/UUIDFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    CompanyFilterRequest:
      type: object
      description: Request body for filtering companies
      properties:
        filter:
          $ref: '#/components/schemas/CompanyFilter'
          description: >
            Filter criteria (optional - omit to return all companies).


            Note: deletedAt automatically defaults to { isNull: true } unless
            explicitly overridden.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - invoiceOnly:
                equalTo: false
            - name:
                includes: Inc
        pageSize: 50
    Company:
      type: object
      required:
        - id
        - name
        - createdAt
        - updatedAt
      properties:
        object:
          type: string
          enum:
            - COMPANY
          readOnly: true
          description: Object type identifier
          example: COMPANY
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique company identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          description: Company legal name
          example: Acme Logistics Inc
        addressLine1:
          type:
            - string
            - 'null'
          description: Primary street address
          example: 123 Main St
        addressLine2:
          type:
            - string
            - 'null'
          description: Secondary address line (suite, floor, etc.)
          example: Suite 400
        city:
          type:
            - string
            - 'null'
          description: City name
          example: Chicago
        country:
          type:
            - string
            - 'null'
          description: Country code or name
          example: USA
        fax:
          type:
            - string
            - 'null'
          description: Fax number
          example: +1-555-0123
        invoiceOnly:
          type:
            - boolean
            - 'null'
          description: Whether this company is used only for invoicing purposes
          example: false
        invoiceVerbiage:
          type:
            - string
            - 'null'
          description: Custom text to include on invoices for this company
          example: Please remit payment within 30 days
        primaryContactName:
          type:
            - string
            - 'null'
          description: Name of primary contact person
          example: John Smith
        primaryContactEmail:
          type:
            - string
            - 'null'
          format: email
          description: Email address of primary contact
          example: john.smith@acmelogistics.com
        primaryContactPhone:
          type:
            - string
            - 'null'
          description: Phone number of primary contact
          example: +1-555-0100
        createdBy:
          anyOf:
            - $ref: '#/components/schemas/UserReference'
            - type: 'null'
          readOnly: true
          description: User who created this company (full user details)
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-COMPANY-ACME-001
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the company was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the company was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: When the company was soft deleted (null if active)
          example: null
    CompanyInput:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Company legal name
          example: Acme Logistics Inc
        addressLine1:
          type: string
          description: Primary street address
          example: 123 Main St
        addressLine2:
          type: string
          description: Secondary address line (suite, floor, etc.)
          example: Suite 400
        city:
          type: string
          description: City name
          example: Chicago
        country:
          type: string
          description: Country code or name
          example: USA
        fax:
          type: string
          description: Fax number
          example: +1-555-0123
        invoiceOnly:
          type: boolean
          description: Whether this company is used only for invoicing purposes
          example: false
        invoiceVerbiage:
          type: string
          description: Custom text to include on invoices for this company
          example: Please remit payment within 30 days
        primaryContactName:
          type: string
          description: Name of primary contact person
          example: John Smith
        primaryContactEmail:
          type: string
          format: email
          description: Email address of primary contact
          example: john.smith@acmelogistics.com
        primaryContactPhone:
          type: string
          description: Phone number of primary contact
          example: +1-555-0100
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-COMPANY-ACME-001
    CompanyPatch:
      type: object
      description: |
        Partial company update. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        name:
          type: string
          description: Company legal name
          example: Acme Logistics Inc
        addressLine1:
          type:
            - string
            - 'null'
          description: Primary street address
          example: 123 Main St
        addressLine2:
          type:
            - string
            - 'null'
          description: Secondary address line
          example: Suite 400
        city:
          type:
            - string
            - 'null'
          description: City name
          example: Chicago
        country:
          type:
            - string
            - 'null'
          description: Country code or name
          example: USA
        fax:
          type:
            - string
            - 'null'
          description: Fax number
          example: +1-555-0123
        invoiceOnly:
          type:
            - boolean
            - 'null'
          description: Whether this company is used only for invoicing purposes
          example: false
        invoiceVerbiage:
          type:
            - string
            - 'null'
          description: Custom text to include on invoices
          example: Please remit payment within 30 days
        primaryContactName:
          type:
            - string
            - 'null'
          description: Name of primary contact person
          example: John Smith
        primaryContactEmail:
          type:
            - string
            - 'null'
          format: email
          description: Email address of primary contact
          example: john.smith@acmelogistics.com
        primaryContactPhone:
          type:
            - string
            - 'null'
          description: Phone number of primary contact
          example: +1-555-0100
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-COMPANY-ACME-001
    CarrierContactType:
      type: string
      description: Type of carrier contact role
      enum:
        - ACCOUNTING
        - AFTER_HOURS
        - CENSUS
        - CLAIMS
        - DISPATCH
        - DRIVER
        - EMERGENCY
        - MANAGER
        - OWNER
    CarrierContactTypeFilter:
      type: object
      description: Filter for contact type enum array field
      properties:
        includes:
          $ref: '#/components/schemas/CarrierContactType'
          description: Array contains this contact type
        notIncludes:
          $ref: '#/components/schemas/CarrierContactType'
          description: Array does not contain this contact type
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CarrierContactFilter:
      type: object
      description: Filter criteria for carrier contacts with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/CarrierContactFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/CarrierContactFilter'
        not:
          $ref: '#/components/schemas/CarrierContactFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        carrierId:
          $ref: '#/components/schemas/UUIDFilter'
        name:
          $ref: '#/components/schemas/StringFilter'
        email:
          $ref: '#/components/schemas/StringFilter'
        phoneNumber:
          $ref: '#/components/schemas/StringFilter'
        contactTypes:
          $ref: '#/components/schemas/CarrierContactTypeFilter'
        invitedUserId:
          $ref: '#/components/schemas/UUIDFilter'
        deletedById:
          $ref: '#/components/schemas/UUIDFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    CarrierContactFilterRequest:
      type: object
      description: Request body for filtering carrier contacts
      properties:
        filter:
          $ref: '#/components/schemas/CarrierContactFilter'
          description: >
            Filter criteria (optional - omit to return all contacts).


            Note: deletedAt automatically defaults to { isNull: true } unless
            explicitly overridden.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - contactTypes:
                includes: DISPATCH
            - email:
                isNotNull: true
        pageSize: 50
    CarrierContact:
      type: object
      required:
        - id
        - carrier
        - name
        - contactInfo
        - createdAt
      properties:
        object:
          type: string
          enum:
            - CARRIER_CONTACT
          readOnly: true
          description: Object type identifier
          example: CARRIER_CONTACT
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique contact identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        carrier:
          $ref: '#/components/schemas/CarrierReference'
          description: Carrier this contact belongs to (full carrier details)
        name:
          type: string
          description: >-
            Contact person's name (denormalized from ContactInfo for
            convenience)
          example: Jane Dispatcher
        contactInfo:
          allOf:
            - $ref: '#/components/schemas/ContactInfo'
          description: >-
            Contact information details (email, phone, title) - nested from
            parent Contact record
        contactTypes:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/CarrierContactType'
          description: Types/roles this contact serves
          example:
            - DISPATCH
            - AFTER_HOURS
        invitedUser:
          anyOf:
            - $ref: '#/components/schemas/UserReference'
            - type: 'null'
          readOnly: true
          description: User account invited/created for this contact (full user details)
        deletedBy:
          anyOf:
            - $ref: '#/components/schemas/UserReference'
            - type: 'null'
          readOnly: true
          description: User who deleted this contact (full user details)
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CARRIER-CONTACT-001
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the contact was created
          example: '2025-01-15T10:00:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: When the contact was soft deleted (null if active)
          example: null
    CarrierContactInput:
      type: object
      required:
        - carrierId
        - name
        - contactInfo
      properties:
        carrierId:
          type: string
          format: uuid
          description: Carrier this contact belongs to
          example: 550e8400-e29b-41d4-a716-446655440001
        name:
          type: string
          description: Contact person's name (should match contactInfo.name)
          example: Jane Dispatcher
        contactInfo:
          $ref: '#/components/schemas/ContactInfoInput'
          description: Contact information details (will create new Contact record)
        contactTypes:
          type: array
          items:
            $ref: '#/components/schemas/CarrierContactType'
          description: Types/roles this contact serves
          example:
            - DISPATCH
            - AFTER_HOURS
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CARRIER-CONTACT-001
    CarrierContactPatch:
      type: object
      description: |
        Partial carrier contact update. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable

        Note: carrierId cannot be updated after creation.
      properties:
        name:
          type: string
          description: >-
            Contact person's name (should match contactInfo.name if updating
            both)
          example: Jane Dispatcher
        contactInfo:
          anyOf:
            - $ref: '#/components/schemas/ContactInfoPatch'
            - type: 'null'
          description: >
            Contact information update. Provide partial or full contact data to
            update the parent Contact record.

            Cannot be set to null (contact info is required).
        contactTypes:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/CarrierContactType'
          description: Types/roles this contact serves (replaces entire array)
          example:
            - DISPATCH
            - AFTER_HOURS
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CARRIER-CONTACT-001
    CustomerContactType:
      type: string
      description: Type of customer contact role
      enum:
        - ACCOUNT_MANAGER
        - BILLING
        - DOCK_SHIPPING
        - EMERGENCY
        - LOCATION_MANAGER
        - OWNER
        - PROCUREMENT
        - PURCHASING
        - RATES_PRICING
        - RECEIVING
        - SHIPPING
    CustomerContactNotificationType:
      type: string
      description: Types of shipment notifications the contact should receive
      enum:
        - SHIPMENT_DELIVERED
        - SHIPMENT_IN_TRANSIT
        - SHIPMENT_LOADING
        - SHIPMENT_OUT_FOR_DELIVERY
        - SHIPMENT_PICKED_UP
        - SHIPMENT_TENDER_REJECTED
        - SHIPMENT_UNLOADING
    CustomerContactTypeFilter:
      type: object
      description: Filter for contact type enum array field
      properties:
        includes:
          $ref: '#/components/schemas/CustomerContactType'
          description: Array contains this contact type
        notIncludes:
          $ref: '#/components/schemas/CustomerContactType'
          description: Array does not contain this contact type
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerContactNotificationTypeFilter:
      type: object
      description: Filter for notification type enum array field
      properties:
        includes:
          $ref: '#/components/schemas/CustomerContactNotificationType'
          description: Array contains this notification type
        notIncludes:
          $ref: '#/components/schemas/CustomerContactNotificationType'
          description: Array does not contain this notification type
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerContactFilter:
      type: object
      description: Filter criteria for contacts with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/CustomerContactFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/CustomerContactFilter'
        not:
          $ref: '#/components/schemas/CustomerContactFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        customerId:
          $ref: '#/components/schemas/UUIDFilter'
        name:
          $ref: '#/components/schemas/StringFilter'
        email:
          $ref: '#/components/schemas/StringFilter'
        phoneNumber:
          $ref: '#/components/schemas/StringFilter'
        phoneExtension:
          $ref: '#/components/schemas/StringFilter'
        isPrimary:
          $ref: '#/components/schemas/BooleanFilter'
        contactTypes:
          $ref: '#/components/schemas/CustomerContactTypeFilter'
        notifications:
          $ref: '#/components/schemas/CustomerContactNotificationTypeFilter'
        invitedUserId:
          $ref: '#/components/schemas/UUIDFilter'
        deletedById:
          $ref: '#/components/schemas/UUIDFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    CustomerContactFilterRequest:
      type: object
      description: Request body for filtering contacts
      properties:
        filter:
          $ref: '#/components/schemas/CustomerContactFilter'
          description: >
            Filter criteria (optional - omit to return all contacts).


            Note: deletedAt automatically defaults to { isNull: true } unless
            explicitly overridden.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - isPrimary:
                equalTo: true
            - contactTypes:
                includes: BILLING
        pageSize: 50
    CustomerContact:
      type: object
      required:
        - id
        - customer
        - name
        - isPrimary
        - contactInfo
        - createdAt
      properties:
        object:
          type: string
          enum:
            - CUSTOMER_CONTACT
          readOnly: true
          description: Object type identifier
          example: CUSTOMER_CONTACT
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique contact identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        customer:
          $ref: '#/components/schemas/CustomerReference'
          description: Customer this contact belongs to (full customer details)
        name:
          type: string
          description: >-
            Contact person's name (denormalized from ContactInfo for
            convenience)
          example: John Smith
        contactInfo:
          allOf:
            - $ref: '#/components/schemas/ContactInfo'
          description: >-
            Contact information details (email, phone, title) - nested from
            parent Contact record
        phoneExtension:
          type:
            - string
            - 'null'
          description: Phone extension specific to this contact role
          example: '1234'
        isPrimary:
          type: boolean
          description: Whether this is the primary contact for the customer
          example: true
        contactTypes:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/CustomerContactType'
          description: Types/roles this contact serves
          example:
            - BILLING
            - ACCOUNT_MANAGER
        notifications:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/CustomerContactNotificationType'
          description: Shipment notification types to send to this contact
          example:
            - SHIPMENT_PICKED_UP
            - SHIPMENT_DELIVERED
        invitedUser:
          anyOf:
            - $ref: '#/components/schemas/UserReference'
            - type: 'null'
          readOnly: true
          description: User account invited/created for this contact (full user details)
        deletedBy:
          anyOf:
            - $ref: '#/components/schemas/UserReference'
            - type: 'null'
          readOnly: true
          description: User who deleted this contact (full user details)
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CONTACT-JOHN-001
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the contact was created
          example: '2025-01-15T10:00:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: When the contact was soft deleted (null if active)
          example: null
    CustomerContactInput:
      type: object
      required:
        - customerId
        - name
        - contactInfo
      properties:
        customerId:
          type: string
          format: uuid
          description: Customer this contact belongs to
          example: 550e8400-e29b-41d4-a716-446655440001
        name:
          type: string
          description: Contact person's name (should match contactInfo.name)
          example: John Smith
        contactInfo:
          $ref: '#/components/schemas/ContactInfoInput'
          description: Contact information details (will create new Contact record)
        phoneExtension:
          type: string
          description: Phone extension specific to this contact role
          example: '1234'
        isPrimary:
          type: boolean
          default: false
          description: Whether this is the primary contact for the customer
          example: true
        contactTypes:
          type: array
          items:
            $ref: '#/components/schemas/CustomerContactType'
          description: Types/roles this contact serves
          example:
            - BILLING
            - ACCOUNT_MANAGER
        notifications:
          type: array
          items:
            $ref: '#/components/schemas/CustomerContactNotificationType'
          description: Shipment notification types to send to this contact
          example:
            - SHIPMENT_PICKED_UP
            - SHIPMENT_DELIVERED
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CONTACT-JOHN-001
    CustomerContactPatch:
      type: object
      description: |
        Partial contact update. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable

        Note: customerId cannot be updated after creation.
      properties:
        name:
          type: string
          description: >-
            Contact person's name (should match contactInfo.name if updating
            both)
          example: John Smith
        contactInfo:
          anyOf:
            - $ref: '#/components/schemas/ContactInfoPatch'
            - type: 'null'
          description: >
            Contact information update. Provide partial or full contact data to
            update the parent Contact record.

            Cannot be set to null (contact info is required).
        phoneExtension:
          type:
            - string
            - 'null'
          description: Phone extension
          example: '1234'
        isPrimary:
          type: boolean
          description: Whether this is the primary contact
          example: true
        contactTypes:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/CustomerContactType'
          description: Types/roles this contact serves (replaces entire array)
          example:
            - BILLING
            - ACCOUNT_MANAGER
        notifications:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/CustomerContactNotificationType'
          description: Notification types (replaces entire array)
          example:
            - SHIPMENT_PICKED_UP
            - SHIPMENT_DELIVERED
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CONTACT-JOHN-001
    CustomerStatus:
      type: string
      enum:
        - NEW
        - CONTACTED
        - QUALIFIED
        - QUOTED
        - NURTURING
        - PENDING
        - ACTIVE
        - INACTIVE
        - BLOCKED
        - CLOSED
      description: |
        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
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 1
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: true
                    attributes:
                      content: 'Customer account status (includes lead stages):'
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
          - $$mdtype: Node
            errors: []
            lines:
              - 1
              - 11
            inline: false
            attributes:
              ordered: false
              marker: '-'
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 1
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 1
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: NEW
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: ': New lead, not yet contacted'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 2
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 2
                      - 3
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: CONTACTED
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: ': Initial contact made with lead'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 3
                  - 4
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 3
                      - 4
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: QUALIFIED
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: ': Lead has been qualified as potential customer'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 4
                  - 5
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 4
                      - 5
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 4
                          - 5
                        inline: true
                        attributes:
                          content: QUOTED
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 4
                          - 5
                        inline: true
                        attributes:
                          content: ': Quote has been provided to lead'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 5
                  - 6
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 5
                      - 6
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 5
                          - 6
                        inline: true
                        attributes:
                          content: NURTURING
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 5
                          - 6
                        inline: true
                        attributes:
                          content: ': Lead being nurtured for future opportunity'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 6
                  - 7
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 6
                      - 7
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 6
                          - 7
                        inline: true
                        attributes:
                          content: PENDING
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 6
                          - 7
                        inline: true
                        attributes:
                          content: ': Customer prospect pending activation'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 7
                  - 8
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 7
                      - 8
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 7
                          - 8
                        inline: true
                        attributes:
                          content: ACTIVE
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 7
                          - 8
                        inline: true
                        attributes:
                          content: ': Active customer account'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 8
                  - 9
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 8
                      - 9
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 8
                          - 9
                        inline: true
                        attributes:
                          content: INACTIVE
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 8
                          - 9
                        inline: true
                        attributes:
                          content: ': Deactivated customer account'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 9
                  - 10
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 9
                      - 10
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 9
                          - 10
                        inline: true
                        attributes:
                          content: BLOCKED
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 9
                          - 10
                        inline: true
                        attributes:
                          content: ': Customer account blocked from operations'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 10
                  - 11
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 10
                      - 11
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 10
                          - 11
                        inline: true
                        attributes:
                          content: CLOSED
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 10
                          - 11
                        inline: true
                        attributes:
                          content: ': Customer account permanently closed'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
            type: list
            annotations: []
            slots: {}
    CustomerServiceTier:
      type: string
      enum:
        - TIER_1
        - TIER_2
        - TIER_3
      description: Service tier level for the customer
    CustomerSpendType:
      type: string
      enum:
        - CONTRACT
        - SPOT
      description: |
        Customer spend type:
        - `CONTRACT`: Customer operates under contract pricing
        - `SPOT`: Customer operates on spot market pricing
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 1
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: true
                    attributes:
                      content: 'Customer spend type:'
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
          - $$mdtype: Node
            errors: []
            lines:
              - 1
              - 3
            inline: false
            attributes:
              ordered: false
              marker: '-'
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 1
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 1
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: CONTRACT
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: ': Customer operates under contract pricing'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 2
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 2
                      - 3
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: SPOT
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: ': Customer operates on spot market pricing'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
            type: list
            annotations: []
            slots: {}
    CustomerDeactivationReason:
      type: string
      enum:
        - NOT_PAYING_INVOICE
        - ACQUIRED
        - DUPLICATE
        - NOT_IN_BUSINESS
        - OTHER
      description: |
        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)
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 1
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: true
                    attributes:
                      content: 'Reason for customer deactivation:'
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
          - $$mdtype: Node
            errors: []
            lines:
              - 1
              - 6
            inline: false
            attributes:
              ordered: false
              marker: '-'
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 1
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 1
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: NOT_PAYING_INVOICE
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: ': Customer is not paying invoices'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 2
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 2
                      - 3
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: ACQUIRED
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: ': Customer was acquired by another company'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 3
                  - 4
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 3
                      - 4
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: DUPLICATE
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: ': Duplicate customer record'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 4
                  - 5
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 4
                      - 5
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 4
                          - 5
                        inline: true
                        attributes:
                          content: NOT_IN_BUSINESS
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 4
                          - 5
                        inline: true
                        attributes:
                          content: ': Customer is no longer in business'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 5
                  - 6
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 5
                      - 6
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 5
                          - 6
                        inline: true
                        attributes:
                          content: OTHER
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 5
                          - 6
                        inline: true
                        attributes:
                          content: ': Other reason (see deactivationNotes for details)'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
            type: list
            annotations: []
            slots: {}
    CustomerIndustry:
      type: string
      enum:
        - AGRICULTURE_FORESTRY
        - CONSTRUCTION
        - CONSUMER_GOODS
        - EDUCATIONAL_SERVICES
        - ENTERTAINMENT
        - FOOD_SERVICES
        - HEALTHCARE
        - INDUSTRIAL_MACHINERY
        - MANUFACTURING
        - MINING
        - RETAIL_TRADE
        - TRANSPORTATION_WAREHOUSING
        - UTILITIES
        - WHOLESALE_TRADE
      description: Industry classification for the customer
    CustomerAnnualSpend:
      type: string
      enum:
        - _0_TO_25K
        - _25_TO_150K
        - _150K_TO_300K
        - _300K_TO_1M
        - _1_TO_5M
        - _5M_TO_25M
        - _25M_TO_75M
        - _75M_PLUS
      description: Annual freight spend estimate range
    CustomerAnnualRevenue:
      type: string
      enum:
        - _0_TO_500K
        - _500K_TO_3M
        - _3M_TO_10M
        - _10M_TO_25M
        - _25M_TO_50M
        - _50M_TO_100M
        - _100M_TO_500M
        - _500M_PLUS
      description: Annual revenue range
    CustomerNumberOfEmployees:
      type: string
      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
      description: Number of employees in the company
    CustomerCurrency:
      type: string
      enum:
        - USD
        - CAD
        - MXN
        - EUR
        - GBP
        - JPY
        - CNY
        - AUD
        - BRL
        - INR
        - KRW
        - RUB
        - SAR
        - TRY
        - IDR
        - ARS
        - ZAR
      description: Preferred currency for transactions
    CustomerTransportationMode:
      type: string
      enum:
        - FTL
        - LTL
        - AIR
        - OCEAN
        - RAIL
        - INTERMODAL
        - DRAYAGE
        - EXPEDITED_GROUND
        - EXPEDITED_AIR
        - AUTO
        - PTL
      description: Transportation mode type
    CustomerStatusFilter:
      type: object
      description: Filter options for CustomerStatus enum
      properties:
        equalTo:
          $ref: '#/components/schemas/CustomerStatus'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/CustomerStatus'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/CustomerStatus'
          description: Matches any value in the array
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/CustomerStatus'
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerServiceTierFilter:
      type: object
      description: Filter options for CustomerServiceTier enum
      properties:
        equalTo:
          $ref: '#/components/schemas/CustomerServiceTier'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/CustomerServiceTier'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/CustomerServiceTier'
          description: Matches any value in the array
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/CustomerServiceTier'
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerSpendTypeFilter:
      type: object
      description: Filter options for CustomerSpendType enum
      properties:
        equalTo:
          $ref: '#/components/schemas/CustomerSpendType'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/CustomerSpendType'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/CustomerSpendType'
          description: Matches any value in the array
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/CustomerSpendType'
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerDeactivationReasonFilter:
      type: object
      description: Filter options for CustomerDeactivationReason enum
      properties:
        equalTo:
          $ref: '#/components/schemas/CustomerDeactivationReason'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/CustomerDeactivationReason'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/CustomerDeactivationReason'
          description: Matches any value in the array
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/CustomerDeactivationReason'
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerIndustryFilter:
      type: object
      description: Filter options for CustomerIndustry enum
      properties:
        equalTo:
          $ref: '#/components/schemas/CustomerIndustry'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/CustomerIndustry'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/CustomerIndustry'
          description: Matches any value in the array
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/CustomerIndustry'
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerAnnualSpendFilter:
      type: object
      description: Filter options for CustomerAnnualSpend enum
      properties:
        equalTo:
          $ref: '#/components/schemas/CustomerAnnualSpend'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/CustomerAnnualSpend'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/CustomerAnnualSpend'
          description: Matches any value in the array
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/CustomerAnnualSpend'
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerAnnualRevenueFilter:
      type: object
      description: Filter options for CustomerAnnualRevenue enum
      properties:
        equalTo:
          $ref: '#/components/schemas/CustomerAnnualRevenue'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/CustomerAnnualRevenue'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/CustomerAnnualRevenue'
          description: Matches any value in the array
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/CustomerAnnualRevenue'
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerNumberOfEmployeesFilter:
      type: object
      description: Filter options for CustomerNumberOfEmployees enum
      properties:
        equalTo:
          $ref: '#/components/schemas/CustomerNumberOfEmployees'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/CustomerNumberOfEmployees'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/CustomerNumberOfEmployees'
          description: Matches any value in the array
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/CustomerNumberOfEmployees'
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerCurrencyFilter:
      type: object
      description: Filter options for CustomerCurrency enum
      properties:
        equalTo:
          $ref: '#/components/schemas/CustomerCurrency'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/CustomerCurrency'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/CustomerCurrency'
          description: Matches any value in the array
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/CustomerCurrency'
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerTransportationModeFilter:
      type: object
      description: Filter options for CustomerTransportationMode enum
      properties:
        equalTo:
          $ref: '#/components/schemas/CustomerTransportationMode'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/CustomerTransportationMode'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/CustomerTransportationMode'
          description: Matches any value in the array
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/CustomerTransportationMode'
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    CustomerFilter:
      type: object
      description: Filter criteria for customers with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/CustomerFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/CustomerFilter'
        not:
          $ref: '#/components/schemas/CustomerFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        name:
          $ref: '#/components/schemas/StringFilter'
        friendlyId:
          $ref: '#/components/schemas/StringFilter'
        status:
          $ref: '#/components/schemas/CustomerStatusFilter'
        serviceTier:
          $ref: '#/components/schemas/CustomerServiceTierFilter'
        website:
          $ref: '#/components/schemas/StringFilter'
        phoneNumber:
          $ref: '#/components/schemas/StringFilter'
        industry:
          $ref: '#/components/schemas/CustomerIndustryFilter'
        annualRevenue:
          $ref: '#/components/schemas/CustomerAnnualRevenueFilter'
        annualSpend:
          $ref: '#/components/schemas/CustomerAnnualSpendFilter'
        spendType:
          $ref: '#/components/schemas/CustomerSpendTypeFilter'
        naics:
          $ref: '#/components/schemas/StringFilter'
        ein:
          $ref: '#/components/schemas/StringFilter'
        duns:
          $ref: '#/components/schemas/StringFilter'
        leadSource:
          $ref: '#/components/schemas/StringFilter'
        deactivationReason:
          $ref: '#/components/schemas/CustomerDeactivationReasonFilter'
        numberOfEmployees:
          $ref: '#/components/schemas/CustomerNumberOfEmployeesFilter'
        currency:
          $ref: '#/components/schemas/CustomerCurrencyFilter'
        defaultMode:
          $ref: '#/components/schemas/CustomerTransportationModeFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        closedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deactivationDate:
          $ref: '#/components/schemas/DatetimeFilter'
    CustomerFilterRequest:
      type: object
      description: Request body for filtering customers
      properties:
        filter:
          $ref: '#/components/schemas/CustomerFilter'
          description: >
            Filter criteria (optional - omit to return all customers).

            Note: deletedAt automatically defaults to { isNull: true } unless
            explicitly overridden.
          x-parsed-md-description:
            result:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes:
                          content: >-
                            Filter criteria (optional - omit to return all
                            customers).
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes: {}
                        children: []
                        type: softbreak
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes:
                          content: >-
                            Note: deletedAt automatically defaults to { isNull:
                            true } unless explicitly overridden.
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: paragraph
                annotations: []
                slots: {}
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - status:
                equalTo: ACTIVE
            - industry:
                includes: Manufacturing
        pageSize: 50
    Customer:
      type: object
      required:
        - id
        - name
        - status
        - friendlyId
        - createdAt
        - updatedAt
      properties:
        object:
          type: string
          enum:
            - CUSTOMER
          readOnly: true
          description: Object type identifier
          example: CUSTOMER
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique customer identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          description: Customer company name
          example: Acme Manufacturing Corp
        friendlyId:
          type: string
          readOnly: true
          description: Human-readable customer identifier, starts with "A"
          example: A123456
        status:
          $ref: '#/components/schemas/CustomerStatus'
        serviceTier:
          anyOf:
            - $ref: '#/components/schemas/CustomerServiceTier'
            - type: 'null'
          description: Service tier level
        website:
          type:
            - string
            - 'null'
          description: Customer website URL
          example: https://acme-manufacturing.com
        phoneNumber:
          type:
            - string
            - 'null'
          description: Primary phone number
          example: +1-555-123-4567
        industry:
          anyOf:
            - $ref: '#/components/schemas/CustomerIndustry'
            - type: 'null'
          description: Industry classification
        annualRevenue:
          anyOf:
            - $ref: '#/components/schemas/CustomerAnnualRevenue'
            - type: 'null'
          description: Annual revenue range
        annualSpend:
          anyOf:
            - $ref: '#/components/schemas/CustomerAnnualSpend'
            - type: 'null'
          description: Annual freight spend estimate
        spendType:
          anyOf:
            - $ref: '#/components/schemas/CustomerSpendType'
            - type: 'null'
          description: Customer spend type (contract vs spot pricing)
        naics:
          type:
            - string
            - 'null'
          description: NAICS industry code
          example: '336411'
        ein:
          type:
            - string
            - 'null'
          description: Employer Identification Number
          example: 12-3456789
        duns:
          type:
            - string
            - 'null'
          description: Dun & Bradstreet number
          example: '123456789'
          x-parsed-md-description:
            result:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 1
                        inline: true
                        attributes:
                          content: Dun & Bradstreet number
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: paragraph
                annotations: []
                slots: {}
        leadSource:
          type:
            - string
            - 'null'
          description: How this customer was acquired
          example: Referral
        dbaName:
          type:
            - string
            - 'null'
          description: Doing business as name
          example: Acme Corp DBA
        numberOfEmployees:
          anyOf:
            - $ref: '#/components/schemas/CustomerNumberOfEmployees'
            - type: 'null'
          description: Company size by number of employees
        externalId:
          type:
            - string
            - 'null'
          description: External system identifier
          example: EXT-12345
        currency:
          anyOf:
            - $ref: '#/components/schemas/CustomerCurrency'
            - type: 'null'
          description: Preferred currency for transactions
        creditLimit:
          type:
            - number
            - 'null'
          format: float
          description: Maximum credit allowed
          example: 50000
        creditUsageWarning:
          type:
            - number
            - 'null'
          format: float
          description: Credit usage warning threshold
          example: 40000
        freeCreditReq:
          type:
            - number
            - 'null'
          format: float
          description: Free credit requirement
          example: 5000
        defaultMode:
          anyOf:
            - $ref: '#/components/schemas/CustomerTransportationMode'
            - type: 'null'
          description: Default transportation mode
        defaultMargin:
          type:
            - number
            - 'null'
          format: float
          description: Default margin percentage (0-1, e.g., 0.15 for 15%)
          example: 0.15
        minMargin:
          type:
            - number
            - 'null'
          format: float
          description: Minimum margin threshold
          example: 0.1
        maxMargin:
          type:
            - number
            - 'null'
          format: float
          description: Maximum margin threshold
          example: 0.25
        defaultInternalNotes:
          type:
            - string
            - 'null'
          description: Default internal notes template
          example: Contact via email only
        defaultExternalNotes:
          type:
            - string
            - 'null'
          description: Default external notes template
          example: Please call 1 hour before delivery
        autoAcceptTender:
          type:
            - boolean
            - 'null'
          description: Auto-accept tender flag
          example: false
        group:
          anyOf:
            - $ref: '#/components/schemas/ResourceReference'
            - type: 'null'
          description: Customer group reference (minimal - id and key only)
        paymentTerm:
          anyOf:
            - $ref: '#/components/schemas/PaymentTermReference'
            - type: 'null'
          description: Payment term configuration reference with full details
        notes:
          type:
            - string
            - 'null'
          description: Internal notes about this customer
          example: Prefers email communication
        deactivationReason:
          anyOf:
            - $ref: '#/components/schemas/CustomerDeactivationReason'
            - type: 'null'
          description: Reason for deactivation if status is INACTIVE
        deactivationNotes:
          type:
            - string
            - 'null'
          description: Additional details about deactivation
        deactivationDate:
          type:
            - string
            - 'null'
          format: date-time
          description: When the customer was deactivated
          example: null
        closedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: When the customer account was closed
          example: null
        closedBy:
          anyOf:
            - $ref: '#/components/schemas/UserReference'
            - type: 'null'
          readOnly: true
          description: User who closed the account (full user details)
        closedNotes:
          type:
            - string
            - 'null'
          description: Notes about account closure
        corporateAddress:
          anyOf:
            - $ref: '#/components/schemas/Address'
            - type: 'null'
          description: Corporate headquarters address (nested location data)
        billingAddress:
          anyOf:
            - $ref: '#/components/schemas/Address'
            - type: 'null'
          description: Billing address (nested location data)
        qboCustomerId:
          type:
            - string
            - 'null'
          description: QuickBooks Online customer ID
          example: null
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier for this customer
          example: ERP-CUSTOMER-12345
        contacts:
          type: array
          description: Contacts for this customer
          items:
            $ref: '#/components/schemas/CustomerContactReference'
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when customer was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when customer was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: Timestamp when customer was soft-deleted (null if active)
          example: null
        deletedBy:
          anyOf:
            - $ref: '#/components/schemas/UserReference'
            - type: 'null'
          readOnly: true
          description: User who deleted the customer (full user details)
    CustomerInput:
      type: object
      required:
        - name
        - status
      properties:
        name:
          type: string
          description: Customer company name (required)
          example: Acme Manufacturing Corp
        status:
          $ref: '#/components/schemas/CustomerStatus'
        serviceTier:
          $ref: '#/components/schemas/CustomerServiceTier'
        website:
          type: string
          description: Customer website URL
          example: https://acme-manufacturing.com
        phoneNumber:
          type: string
          description: Primary phone number
          example: +1-555-123-4567
        industry:
          $ref: '#/components/schemas/CustomerIndustry'
        annualRevenue:
          $ref: '#/components/schemas/CustomerAnnualRevenue'
        annualSpend:
          $ref: '#/components/schemas/CustomerAnnualSpend'
        spendType:
          $ref: '#/components/schemas/CustomerSpendType'
        naics:
          type: string
          description: NAICS industry code
          example: '336411'
        ein:
          type: string
          description: Employer Identification Number
          example: 12-3456789
        duns:
          type: string
          description: Dun & Bradstreet number
          example: '123456789'
          x-parsed-md-description:
            result:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 1
                        inline: true
                        attributes:
                          content: Dun & Bradstreet number
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: paragraph
                annotations: []
                slots: {}
        leadSource:
          type: string
          description: How this customer was acquired
          example: Referral
        dbaName:
          type: string
          description: Doing business as name
          example: Acme Corp DBA
        numberOfEmployees:
          $ref: '#/components/schemas/CustomerNumberOfEmployees'
        externalId:
          type: string
          description: External system identifier
          example: EXT-12345
        currency:
          $ref: '#/components/schemas/CustomerCurrency'
        creditLimit:
          type: number
          format: float
          description: Maximum credit allowed
          example: 50000
        creditUsageWarning:
          type: number
          format: float
          description: Credit usage warning threshold
          example: 40000
        freeCreditReq:
          type: number
          format: float
          description: Free credit requirement
          example: 5000
        defaultMode:
          $ref: '#/components/schemas/CustomerTransportationMode'
        defaultMargin:
          type: number
          format: float
          description: Default margin percentage (0-1, e.g., 0.15 for 15%)
          example: 0.15
        minMargin:
          type: number
          format: float
          description: Minimum margin threshold
          example: 0.1
        maxMargin:
          type: number
          format: float
          description: Maximum margin threshold
          example: 0.25
        defaultInternalNotes:
          type: string
          description: Default internal notes template
          example: Contact via email only
        defaultExternalNotes:
          type: string
          description: Default external notes template
          example: Please call 1 hour before delivery
        autoAcceptTender:
          type: boolean
          description: Auto-accept tender flag
          example: false
        groupId:
          type: string
          format: uuid
          description: Customer group reference
        paymentTerm:
          $ref: '#/components/schemas/ResourceReferenceInput'
        notes:
          type: string
          description: Internal notes about this customer
          example: Prefers email communication
        deactivationReason:
          $ref: '#/components/schemas/CustomerDeactivationReason'
        deactivationNotes:
          type: string
          description: Additional details about deactivation
        deactivationDate:
          type: string
          format: date-time
          description: When the customer was deactivated
        corporateAddress:
          $ref: '#/components/schemas/AddressInput'
          description: Corporate headquarters address (will create new location record)
        billingAddress:
          $ref: '#/components/schemas/AddressInput'
          description: Billing address (will create new location record)
        qboCustomerId:
          type: string
          description: QuickBooks Online customer ID
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CUSTOMER-12345
    CustomerPatch:
      type: object
      description: |
        Partial customer update. All fields are optional.
        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        name:
          type: string
          description: Customer company name
          example: Acme Manufacturing Corp
        status:
          $ref: '#/components/schemas/CustomerStatus'
        serviceTier:
          anyOf:
            - $ref: '#/components/schemas/CustomerServiceTier'
            - type: 'null'
          description: Service tier level
        website:
          type:
            - string
            - 'null'
          description: Customer website URL
          example: https://acme-manufacturing.com
        phoneNumber:
          type:
            - string
            - 'null'
          description: Primary phone number
          example: +1-555-123-4567
        industry:
          anyOf:
            - $ref: '#/components/schemas/CustomerIndustry'
            - type: 'null'
          description: Industry classification
        annualRevenue:
          anyOf:
            - $ref: '#/components/schemas/CustomerAnnualRevenue'
            - type: 'null'
          description: Annual revenue range
        annualSpend:
          anyOf:
            - $ref: '#/components/schemas/CustomerAnnualSpend'
            - type: 'null'
          description: Annual freight spend estimate
        spendType:
          anyOf:
            - $ref: '#/components/schemas/CustomerSpendType'
            - type: 'null'
          description: Customer spend type (contract vs spot pricing)
        naics:
          type:
            - string
            - 'null'
          description: NAICS industry code
          example: '336411'
        ein:
          type:
            - string
            - 'null'
          description: Employer Identification Number
          example: 12-3456789
        duns:
          type:
            - string
            - 'null'
          description: Dun & Bradstreet number
          example: '123456789'
          x-parsed-md-description:
            result:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 1
                        inline: true
                        attributes:
                          content: Dun & Bradstreet number
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: paragraph
                annotations: []
                slots: {}
        leadSource:
          type:
            - string
            - 'null'
          description: How this customer was acquired
          example: Referral
        dbaName:
          type:
            - string
            - 'null'
          description: Doing business as name
          example: Acme Corp DBA
        numberOfEmployees:
          anyOf:
            - $ref: '#/components/schemas/CustomerNumberOfEmployees'
            - type: 'null'
          description: Company size by number of employees
        externalId:
          type:
            - string
            - 'null'
          description: External system identifier
          example: EXT-12345
        currency:
          anyOf:
            - $ref: '#/components/schemas/CustomerCurrency'
            - type: 'null'
          description: Preferred currency for transactions
        creditLimit:
          type:
            - number
            - 'null'
          format: float
          description: Maximum credit allowed
          example: 50000
        creditUsageWarning:
          type:
            - number
            - 'null'
          format: float
          description: Credit usage warning threshold
          example: 40000
        freeCreditReq:
          type:
            - number
            - 'null'
          format: float
          description: Free credit requirement
          example: 5000
        defaultMode:
          anyOf:
            - $ref: '#/components/schemas/CustomerTransportationMode'
            - type: 'null'
          description: Default transportation mode
        defaultMargin:
          type:
            - number
            - 'null'
          format: float
          description: Default margin percentage (0-1, e.g., 0.15 for 15%)
          example: 0.15
        minMargin:
          type:
            - number
            - 'null'
          format: float
          description: Minimum margin threshold
          example: 0.1
        maxMargin:
          type:
            - number
            - 'null'
          format: float
          description: Maximum margin threshold
          example: 0.25
        defaultInternalNotes:
          type:
            - string
            - 'null'
          description: Default internal notes template
          example: Contact via email only
        defaultExternalNotes:
          type:
            - string
            - 'null'
          description: Default external notes template
          example: Please call 1 hour before delivery
        autoAcceptTender:
          type:
            - boolean
            - 'null'
          description: Auto-accept tender flag
          example: false
        groupId:
          type:
            - string
            - 'null'
          format: uuid
          description: Customer group reference
          example: null
        paymentTerm:
          anyOf:
            - $ref: '#/components/schemas/ResourceReferenceInput'
            - type: 'null'
          description: Payment term configuration reference
        notes:
          type:
            - string
            - 'null'
          description: Internal notes
          example: Prefers email communication
        deactivationReason:
          anyOf:
            - $ref: '#/components/schemas/CustomerDeactivationReason'
            - type: 'null'
          description: Reason for deactivation
        deactivationNotes:
          type:
            - string
            - 'null'
          description: Additional deactivation details
        deactivationDate:
          type:
            - string
            - 'null'
          format: date-time
          description: Deactivation date
        corporateAddress:
          anyOf:
            - $ref: '#/components/schemas/AddressPatch'
            - type: 'null'
          description: >
            Corporate address update. Provide partial or full address data to
            update the existing location.

            Set to null to clear the address reference.
        billingAddress:
          anyOf:
            - $ref: '#/components/schemas/AddressPatch'
            - type: 'null'
          description: >
            Billing address update. Provide partial or full address data to
            update the existing location.

            Set to null to clear the address reference.
        qboCustomerId:
          type:
            - string
            - 'null'
          description: QuickBooks Online customer ID
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CUSTOMER-12345
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 1
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: true
                    attributes:
                      content: Partial customer update. All fields are optional.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
          - $$mdtype: Node
            errors: []
            lines:
              - 1
              - 4
            inline: false
            attributes:
              ordered: false
              marker: '-'
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 1
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 1
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 1
                              - 2
                            inline: true
                            attributes:
                              content: Omitted fields
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: ': Not modified (current value preserved)'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 2
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 2
                      - 3
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 2
                              - 3
                            inline: true
                            attributes:
                              content: Provided fields
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: ': Updated to the new value'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 3
                  - 4
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 3
                      - 4
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 3
                              - 4
                            inline: true
                            attributes:
                              content: Null values
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: ': Clear the field (set to null) where applicable'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
            type: list
            annotations: []
            slots: {}
    LocationType:
      type: string
      enum:
        - SHIPPER
        - RECEIVER
        - BOTH
      description: |
        The type of location:
        - `SHIPPER`: Pickup location only
        - `RECEIVER`: Delivery location only
        - `BOTH`: Can be used for both pickup and delivery
    LocationFilter:
      type: object
      description: Filter criteria for locations with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/LocationFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/LocationFilter'
        not:
          $ref: '#/components/schemas/LocationFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        customerId:
          $ref: '#/components/schemas/IDFilter'
        name:
          $ref: '#/components/schemas/StringFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        type:
          $ref: '#/components/schemas/StringFilter'
        isAppointmentRequired:
          $ref: '#/components/schemas/BooleanFilter'
        notes:
          $ref: '#/components/schemas/StringFilter'
        internalNotes:
          $ref: '#/components/schemas/StringFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    LocationFilterRequest:
      type: object
      description: Request body for filtering locations
      properties:
        filter:
          $ref: '#/components/schemas/LocationFilter'
          description: >
            Filter criteria (optional - omit to return all locations).


            Note: deletedAt automatically defaults to { isNull: true } unless
            explicitly overridden.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - customerId:
                equalTo: 550e8400-e29b-41d4-a716-446655440000
            - type:
                equalTo: SHIPPER
        pageSize: 50
    Location:
      type: object
      required:
        - id
        - customerId
        - name
        - isAppointmentRequired
        - createdAt
        - updatedAt
      properties:
        object:
          type: string
          enum:
            - LOCATION
          readOnly: true
          description: Object type identifier
          example: LOCATION
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique location identifier
          example: 770e8400-e29b-41d4-a716-446655440000
        customerId:
          type: string
          format: uuid
          description: Customer (shipper profile) this location belongs to
          example: 550e8400-e29b-41d4-a716-446655440000
        customer:
          $ref: '#/components/schemas/Customer'
          readOnly: true
          description: The customer this location belongs to
        name:
          type: string
          description: Location name
          example: ABC Warehouse - Dallas
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier for this location
          example: ERP-LOC-DALLAS-01
        type:
          $ref: '#/components/schemas/LocationType'
          description: Type of location (SHIPPER, RECEIVER, or BOTH)
          example: SHIPPER
        isAppointmentRequired:
          type: boolean
          description: Whether appointments are required for this location
          example: true
        notes:
          type:
            - string
            - 'null'
          description: External notes visible to carriers
          example: Call 24 hours ahead for appointment
        internalNotes:
          type:
            - string
            - 'null'
          description: Internal notes (not visible to carriers)
          example: Use dock door 5 for expedited shipments
        contacts:
          type: array
          description: Contacts for this location
          items:
            $ref: '#/components/schemas/LocationContactReference'
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when location was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when location was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: Timestamp when location was soft-deleted (null if active)
          example: null
    LocationInput:
      type: object
      required:
        - customerId
        - name
        - isAppointmentRequired
      properties:
        customerId:
          type: string
          format: uuid
          description: Customer (shipper profile) this location belongs to (required)
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          description: Location name (required)
          example: ABC Warehouse - Dallas
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-LOC-DALLAS-01
        type:
          $ref: '#/components/schemas/LocationType'
          description: Type of location (SHIPPER, RECEIVER, or BOTH)
          example: SHIPPER
        isAppointmentRequired:
          type: boolean
          description: Whether appointments are required for this location (required)
          example: true
        notes:
          type: string
          description: External notes visible to carriers
          example: Call 24 hours ahead for appointment
        internalNotes:
          type: string
          description: Internal notes (not visible to carriers)
          example: Use dock door 5 for expedited shipments
    LocationPatch:
      type: object
      description: |
        Partial location update. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        customerId:
          type: string
          format: uuid
          description: Customer (shipper profile) this location belongs to
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          description: Location name
          example: ABC Warehouse - Dallas
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-LOC-DALLAS-01
        type:
          $ref: '#/components/schemas/LocationType'
          description: Type of location (SHIPPER, RECEIVER, or BOTH)
          example: SHIPPER
        isAppointmentRequired:
          type: boolean
          description: Whether appointments are required for this location
          example: true
        notes:
          type:
            - string
            - 'null'
          description: External notes visible to carriers
          example: Call 24 hours ahead for appointment
        internalNotes:
          type:
            - string
            - 'null'
          description: Internal notes (not visible to carriers)
          example: Use dock door 5 for expedited shipments
    LocationContactType:
      type: string
      description: Type of location contact role
      enum:
        - ACCOUNT_MANAGER
        - BILLING
        - DOCK_SHIPPING
        - EMERGENCY
        - LOCATION_MANAGER
        - OWNER
        - PROCUREMENT
        - PURCHASING
        - RATES_PRICING
        - RECEIVING
        - SHIPPING
    LocationContactTypeFilter:
      type: object
      description: Filter for contact type enum array field
      properties:
        includes:
          $ref: '#/components/schemas/LocationContactType'
          description: Array contains this contact type
        notIncludes:
          $ref: '#/components/schemas/LocationContactType'
          description: Array does not contain this contact type
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    LocationContactFilter:
      type: object
      description: Filter criteria for location contacts with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/LocationContactFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/LocationContactFilter'
        not:
          $ref: '#/components/schemas/LocationContactFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        locationId:
          $ref: '#/components/schemas/UUIDFilter'
        customerContactId:
          $ref: '#/components/schemas/UUIDFilter'
        isPrimary:
          $ref: '#/components/schemas/BooleanFilter'
        contactTypes:
          $ref: '#/components/schemas/LocationContactTypeFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    LocationContactFilterRequest:
      type: object
      description: Request body for filtering location contacts
      properties:
        filter:
          $ref: '#/components/schemas/LocationContactFilter'
          description: >
            Filter criteria (optional - omit to return all location contacts).


            Note: deletedAt automatically defaults to { isNull: true } unless
            explicitly overridden.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - locationId:
                equalTo: 770e8400-e29b-41d4-a716-446655440000
            - isPrimary:
                equalTo: true
        pageSize: 50
    LocationContact:
      type: object
      required:
        - id
        - locationId
        - customerContactId
        - isPrimary
        - createdAt
        - updatedAt
      properties:
        object:
          type: string
          enum:
            - LOCATION_CONTACT
          readOnly: true
          description: Object type identifier
          example: LOCATION_CONTACT
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique location contact identifier
          example: 880e8400-e29b-41d4-a716-446655440000
        locationId:
          type: string
          format: uuid
          description: Location this contact is associated with
          example: 770e8400-e29b-41d4-a716-446655440000
        location:
          $ref: '#/components/schemas/Location'
          readOnly: true
          description: The location this contact is associated with
        customerContactId:
          type: string
          format: uuid
          description: Customer contact linked to this location
          example: 660e8400-e29b-41d4-a716-446655440000
        customerContact:
          $ref: '#/components/schemas/CustomerContact'
          readOnly: true
          description: The customer contact details
        isPrimary:
          type: boolean
          description: Whether this is the primary contact for the location
          example: true
        contactTypes:
          type: array
          items:
            $ref: '#/components/schemas/LocationContactType'
          description: Roles/types for this location contact
          example:
            - LOCATION_MANAGER
            - SHIPPING
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier for this location contact
          example: ERP-LOC-CONTACT-001
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when location contact was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when location contact was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: Timestamp when location contact was soft-deleted (null if active)
          example: null
    LocationContactReference:
      type: object
      description: >
        Location contact reference for embedding in Location responses.

        Identical to LocationContact but excludes the location and locationId
        fields to avoid circular references.
      required:
        - id
        - customerContactId
        - isPrimary
        - createdAt
        - updatedAt
      properties:
        object:
          type: string
          enum:
            - LOCATION_CONTACT
          readOnly: true
          description: Object type identifier
          example: LOCATION_CONTACT
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique location contact identifier
          example: 880e8400-e29b-41d4-a716-446655440000
        customerContactId:
          type: string
          format: uuid
          description: Customer contact linked to this location
          example: 660e8400-e29b-41d4-a716-446655440000
        customerContact:
          $ref: '#/components/schemas/CustomerContact'
          readOnly: true
          description: The customer contact details
        isPrimary:
          type: boolean
          description: Whether this is the primary contact for the location
          example: true
        contactTypes:
          type: array
          items:
            $ref: '#/components/schemas/LocationContactType'
          description: Roles/types for this location contact
          example:
            - LOCATION_MANAGER
            - SHIPPING
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier for this location contact
          example: ERP-LOC-CONTACT-001
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when location contact was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when location contact was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: Timestamp when location contact was soft-deleted (null if active)
          example: null
    LocationContactInput:
      type: object
      required:
        - locationId
        - customerContactId
        - isPrimary
      properties:
        locationId:
          type: string
          format: uuid
          description: Location this contact is associated with (required)
          example: 770e8400-e29b-41d4-a716-446655440000
        customerContactId:
          type: string
          format: uuid
          description: Customer contact to link to this location (required)
          example: 660e8400-e29b-41d4-a716-446655440000
        isPrimary:
          type: boolean
          description: Whether this is the primary contact for the location (required)
          example: true
        contactTypes:
          type: array
          items:
            $ref: '#/components/schemas/LocationContactType'
          description: Roles/types for this location contact
          example:
            - LOCATION_MANAGER
            - SHIPPING
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-LOC-CONTACT-001
    LocationContactPatch:
      type: object
      description: |
        Partial location contact update. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        locationId:
          type: string
          format: uuid
          description: Location this contact is associated with
          example: 770e8400-e29b-41d4-a716-446655440000
        customerContactId:
          type: string
          format: uuid
          description: Customer contact linked to this location
          example: 660e8400-e29b-41d4-a716-446655440000
        isPrimary:
          type: boolean
          description: Whether this is the primary contact for the location
          example: true
        contactTypes:
          type: array
          items:
            $ref: '#/components/schemas/LocationContactType'
          description: Roles/types for this location contact
          example:
            - LOCATION_MANAGER
            - SHIPPING
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-LOC-CONTACT-001
    PaymentTermFilter:
      type: object
      description: Filter criteria for payment terms with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/PaymentTermFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/PaymentTermFilter'
        not:
          $ref: '#/components/schemas/PaymentTermFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        name:
          $ref: '#/components/schemas/StringFilter'
        description:
          $ref: '#/components/schemas/StringFilter'
        days:
          $ref: '#/components/schemas/IntFilter'
        quickPayFee:
          $ref: '#/components/schemas/FloatFilter'
        apOnly:
          $ref: '#/components/schemas/BooleanFilter'
        doNotUse:
          $ref: '#/components/schemas/BooleanFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    PaymentTermFilterRequest:
      type: object
      description: Request body for filtering payment terms
      properties:
        filter:
          $ref: '#/components/schemas/PaymentTermFilter'
          description: >
            Filter criteria (optional - omit to return all payment terms).

            Note: deletedAt automatically defaults to { isNull: true } unless
            explicitly overridden.
          x-parsed-md-description:
            result:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes:
                          content: >-
                            Filter criteria (optional - omit to return all
                            payment terms).
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes: {}
                        children: []
                        type: softbreak
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes:
                          content: >-
                            Note: deletedAt automatically defaults to { isNull:
                            true } unless explicitly overridden.
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: paragraph
                annotations: []
                slots: {}
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - doNotUse:
                equalTo: false
            - days:
                greaterThan: 0
        pageSize: 50
    PaymentTerm:
      type: object
      required:
        - id
        - name
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique payment term identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          description: Payment term name
          example: Net 30
        description:
          type:
            - string
            - 'null'
          description: Payment term description or notes
          example: Payment due 30 days from invoice date
        days:
          type:
            - integer
            - 'null'
          description: Number of days until payment is due
          example: 30
        quickPayFee:
          type:
            - number
            - 'null'
          format: float
          description: Quick pay fee percentage (e.g., 0.05 for 5%)
          example: 0.05
          x-parsed-md-description:
            result:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 1
                        inline: true
                        attributes:
                          content: Quick pay fee percentage (e.g., 0.05 for 5%)
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: paragraph
                annotations: []
                slots: {}
        apOnly:
          type:
            - boolean
            - 'null'
          description: Whether this payment term is for accounts payable only
          example: false
        doNotUse:
          type:
            - boolean
            - 'null'
          description: Flag to prevent using this payment term for new transactions
          example: false
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-PAYTERM-NET30
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment term was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment term was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: When the payment term was soft deleted (null if active)
          example: null
    PaymentTermInput:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Payment term name
          example: Net 30
        description:
          type: string
          description: Payment term description or notes
          example: Payment due 30 days from invoice date
        days:
          type: integer
          description: Number of days until payment is due
          example: 30
        quickPayFee:
          type: number
          format: float
          description: Quick pay fee percentage (e.g., 0.05 for 5%)
          example: 0.05
          x-parsed-md-description:
            result:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 1
                        inline: true
                        attributes:
                          content: Quick pay fee percentage (e.g., 0.05 for 5%)
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: paragraph
                annotations: []
                slots: {}
        apOnly:
          type: boolean
          description: Whether this payment term is for accounts payable only
          example: false
        doNotUse:
          type: boolean
          description: Flag to prevent using this payment term for new transactions
          example: false
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-PAYTERM-NET30
    PaymentTermPatch:
      type: object
      description: |
        Partial payment term update. All fields are optional.
        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        name:
          type: string
          description: Payment term name
          example: Net 30
        description:
          type:
            - string
            - 'null'
          description: Payment term description
          example: Payment due 30 days from invoice date
        days:
          type:
            - integer
            - 'null'
          description: Number of days until payment is due
          example: 30
        quickPayFee:
          type:
            - number
            - 'null'
          format: float
          description: Quick pay fee percentage
          example: 0.05
        apOnly:
          type:
            - boolean
            - 'null'
          description: Whether this payment term is for accounts payable only
          example: false
        doNotUse:
          type:
            - boolean
            - 'null'
          description: Flag to prevent using this payment term
          example: false
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-PAYTERM-NET30
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 1
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: true
                    attributes:
                      content: Partial payment term update. All fields are optional.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
          - $$mdtype: Node
            errors: []
            lines:
              - 1
              - 4
            inline: false
            attributes:
              ordered: false
              marker: '-'
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 1
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 1
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 1
                              - 2
                            inline: true
                            attributes:
                              content: Omitted fields
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: ': Not modified (current value preserved)'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 2
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 2
                      - 3
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 2
                              - 3
                            inline: true
                            attributes:
                              content: Provided fields
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: ': Updated to the new value'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 3
                  - 4
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 3
                      - 4
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 3
                              - 4
                            inline: true
                            attributes:
                              content: Null values
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: ': Clear the field (set to null) where applicable'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
            type: list
            annotations: []
            slots: {}
    TeamFilter:
      type: object
      description: Filter criteria for teams with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/TeamFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/TeamFilter'
        not:
          $ref: '#/components/schemas/TeamFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        name:
          $ref: '#/components/schemas/StringFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    TeamFilterRequest:
      type: object
      description: Request body for filtering teams
      properties:
        filter:
          $ref: '#/components/schemas/TeamFilter'
          description: >
            Filter criteria (optional - omit to return all teams).

            Note: deletedAt automatically defaults to { isNull: true } unless
            explicitly overridden.
          x-parsed-md-description:
            result:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes:
                          content: >-
                            Filter criteria (optional - omit to return all
                            teams).
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes: {}
                        children: []
                        type: softbreak
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes:
                          content: >-
                            Note: deletedAt automatically defaults to { isNull:
                            true } unless explicitly overridden.
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: paragraph
                annotations: []
                slots: {}
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          name:
            includes: Sales
        pageSize: 50
    Team:
      type: object
      required:
        - id
        - name
        - createdAt
        - updatedAt
      properties:
        object:
          type: string
          enum:
            - TEAM
          readOnly: true
          description: Object type identifier
          example: TEAM
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique team identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        name:
          type: string
          description: Team name
          example: Sales Team - West Coast
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier for this team
          example: ERP-TEAM-WEST
        users:
          type: array
          description: Users who are members of this team
          items:
            $ref: '#/components/schemas/users_UserReference'
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when team was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when team was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: Timestamp when team was soft-deleted (null if active)
          example: null
    TeamInput:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Team name (required)
          example: Sales Team - West Coast
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-TEAM-WEST
        users:
          type: array
          description: Users to add to this team
          items:
            $ref: '#/components/schemas/ResourceReferenceInput'
          example:
            - id: 550e8400-e29b-41d4-a716-446655440000
            - key: ERP-USER-12345
    TeamPatch:
      type: object
      description: |
        Partial team update. All fields are optional.
        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        name:
          type: string
          description: Team name
          example: Sales Team - West Coast
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-TEAM-WEST
        users:
          type: array
          description: Team members (replaces all existing memberships)
          items:
            $ref: '#/components/schemas/ResourceReferenceInput'
          example:
            - id: 550e8400-e29b-41d4-a716-446655440000
            - key: ERP-USER-12345
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 1
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: true
                    attributes:
                      content: Partial team update. All fields are optional.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
          - $$mdtype: Node
            errors: []
            lines:
              - 1
              - 4
            inline: false
            attributes:
              ordered: false
              marker: '-'
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 1
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 1
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 1
                              - 2
                            inline: true
                            attributes:
                              content: Omitted fields
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: ': Not modified (current value preserved)'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 2
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 2
                      - 3
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 2
                              - 3
                            inline: true
                            attributes:
                              content: Provided fields
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: ': Updated to the new value'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 3
                  - 4
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 3
                      - 4
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 3
                              - 4
                            inline: true
                            attributes:
                              content: Null values
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: ': Clear the field (set to null) where applicable'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
            type: list
            annotations: []
            slots: {}
    UserStatus:
      type: string
      enum:
        - PENDING
        - ACTIVE
        - INACTIVE
      description: |
        User account status:
        - `PENDING`: User invited but has not completed onboarding
        - `ACTIVE`: User account is active and can access the system
        - `INACTIVE`: User account is deactivated
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 1
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: true
                    attributes:
                      content: 'User account status:'
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
          - $$mdtype: Node
            errors: []
            lines:
              - 1
              - 4
            inline: false
            attributes:
              ordered: false
              marker: '-'
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 1
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 1
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: PENDING
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: ': User invited but has not completed onboarding'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 2
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 2
                      - 3
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: ACTIVE
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: ': User account is active and can access the system'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 3
                  - 4
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 3
                      - 4
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: INACTIVE
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: ': User account is deactivated'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
            type: list
            annotations: []
            slots: {}
    UserRole:
      type: string
      enum:
        - CUSTOMER_REP
        - CARRIER_REP
        - AR_AP
        - COMPLIANCE
        - ADMIN
      description: |
        User role within the organization:
        - `CUSTOMER_REP`: Customer service representative
        - `CARRIER_REP`: Carrier service representative
        - `AR_AP`: Accounts receivable/payable
        - `COMPLIANCE`: Compliance officer
        - `ADMIN`: System administrator
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 1
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: true
                    attributes:
                      content: 'User role within the organization:'
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
          - $$mdtype: Node
            errors: []
            lines:
              - 1
              - 6
            inline: false
            attributes:
              ordered: false
              marker: '-'
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 1
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 1
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: CUSTOMER_REP
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: ': Customer service representative'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 2
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 2
                      - 3
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: CARRIER_REP
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: ': Carrier service representative'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 3
                  - 4
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 3
                      - 4
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: AR_AP
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: ': Accounts receivable/payable'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 4
                  - 5
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 4
                      - 5
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 4
                          - 5
                        inline: true
                        attributes:
                          content: COMPLIANCE
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 4
                          - 5
                        inline: true
                        attributes:
                          content: ': Compliance officer'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 5
                  - 6
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 5
                      - 6
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 5
                          - 6
                        inline: true
                        attributes:
                          content: ADMIN
                        children: []
                        type: code
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 5
                          - 6
                        inline: true
                        attributes:
                          content: ': System administrator'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
            type: list
            annotations: []
            slots: {}
    UserStatusFilter:
      type: object
      description: Filter options for UserStatus enum
      properties:
        equalTo:
          $ref: '#/components/schemas/UserStatus'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/UserStatus'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/UserStatus'
          description: Matches any value in the array
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/UserStatus'
          description: Does not match any value in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    UserRoleFilter:
      type: object
      description: Filter options for UserRole enum array
      properties:
        contains:
          $ref: '#/components/schemas/UserRole'
          description: Array contains this role
        containsAll:
          type: array
          items:
            $ref: '#/components/schemas/UserRole'
          description: Array contains all of these roles
        containsAny:
          type: array
          items:
            $ref: '#/components/schemas/UserRole'
          description: Array contains at least one of these roles
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    UserFilter:
      type: object
      description: Filter criteria for users with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/UserFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/UserFilter'
        not:
          $ref: '#/components/schemas/UserFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        email:
          $ref: '#/components/schemas/StringFilter'
        name:
          $ref: '#/components/schemas/StringFilter'
        phone:
          $ref: '#/components/schemas/StringFilter'
        status:
          $ref: '#/components/schemas/UserStatusFilter'
        roles:
          $ref: '#/components/schemas/UserRoleFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        datUsername:
          $ref: '#/components/schemas/StringFilter'
        mcpUsername:
          $ref: '#/components/schemas/StringFilter'
        avatarId:
          $ref: '#/components/schemas/UUIDFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    UserFilterRequest:
      type: object
      description: Request body for filtering users
      properties:
        filter:
          $ref: '#/components/schemas/UserFilter'
          description: >
            Filter criteria (optional - omit to return all users).

            Note: deletedAt automatically defaults to { isNull: true } unless
            explicitly overridden.
          x-parsed-md-description:
            result:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes:
                          content: >-
                            Filter criteria (optional - omit to return all
                            users).
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes: {}
                        children: []
                        type: softbreak
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 0
                          - 2
                        inline: true
                        attributes:
                          content: >-
                            Note: deletedAt automatically defaults to { isNull:
                            true } unless explicitly overridden.
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: paragraph
                annotations: []
                slots: {}
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - status:
                equalTo: ACTIVE
            - roles:
                contains: CUSTOMER_REP
            - email:
                includes: '@example.com'
        pageSize: 50
    User:
      type: object
      required:
        - id
        - email
        - status
        - roles
        - createdAt
        - updatedAt
      properties:
        object:
          type: string
          enum:
            - USER
          readOnly: true
          description: Object type identifier
          example: USER
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique user identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        email:
          type: string
          format: email
          description: User's email address
          example: john.doe@example.com
        name:
          type:
            - string
            - 'null'
          description: User's full name
          example: John Doe
        phone:
          type:
            - string
            - 'null'
          description: User's phone number
          example: +1-555-123-4567
        phoneExt:
          type:
            - string
            - 'null'
          description: Phone extension
          example: '123'
        status:
          $ref: '#/components/schemas/UserStatus'
        roles:
          type: array
          description: User's roles within the organization
          items:
            $ref: '#/components/schemas/UserRole'
          example:
            - CUSTOMER_REP
            - ADMIN
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier for this user
          example: ERP-USER-12345
        datUsername:
          type:
            - string
            - 'null'
          description: DAT (Load Board) integration username
          example: johndoe_dat
        mcpUsername:
          type:
            - string
            - 'null'
          description: MyCarrierPortal integration username
          example: johndoe_mcp
        avatarId:
          type:
            - string
            - 'null'
          format: uuid
          description: Profile avatar document ID
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        teams:
          type: array
          description: Teams this user belongs to
          items:
            $ref: '#/components/schemas/TeamReference'
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when user was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when user was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: Timestamp when user was soft-deleted (null if active)
          example: null
    UserInput:
      type: object
      required:
        - email
        - status
        - roles
      properties:
        email:
          type: string
          format: email
          description: User's email address (required)
          example: john.doe@example.com
        name:
          type: string
          description: User's full name
          example: John Doe
        phone:
          type: string
          description: User's phone number
          example: +1-555-123-4567
        phoneExt:
          type: string
          description: Phone extension
          example: '123'
        status:
          $ref: '#/components/schemas/UserStatus'
        roles:
          type: array
          description: User's roles within the organization (required)
          items:
            $ref: '#/components/schemas/UserRole'
          minItems: 1
          example:
            - CUSTOMER_REP
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-USER-12345
        datUsername:
          type: string
          description: DAT (Load Board) integration username
          example: johndoe_dat
        mcpUsername:
          type: string
          description: MyCarrierPortal integration username
          example: johndoe_mcp
        avatarId:
          type: string
          format: uuid
          description: Profile avatar document ID
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        teams:
          type: array
          description: Teams to add this user to
          items:
            $ref: '#/components/schemas/ResourceReferenceInput'
          example:
            - id: 123e4567-e89b-12d3-a456-426614174000
            - key: TEAM-WEST-COAST
    UserPatch:
      type: object
      description: |
        Partial user update. All fields are optional.
        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        email:
          type: string
          format: email
          description: User's email address
          example: john.doe@example.com
        name:
          type:
            - string
            - 'null'
          description: User's full name
          example: John Doe
        phone:
          type:
            - string
            - 'null'
          description: User's phone number
          example: +1-555-123-4567
        phoneExt:
          type:
            - string
            - 'null'
          description: Phone extension
          example: '123'
        status:
          $ref: '#/components/schemas/UserStatus'
        roles:
          type: array
          description: User's roles (replaces all existing roles)
          items:
            $ref: '#/components/schemas/UserRole'
          minItems: 1
          example:
            - CUSTOMER_REP
            - ADMIN
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-USER-12345
        datUsername:
          type:
            - string
            - 'null'
          description: DAT integration username
          example: johndoe_dat
        mcpUsername:
          type:
            - string
            - 'null'
          description: MyCarrierPortal integration username
          example: johndoe_mcp
        avatarId:
          type:
            - string
            - 'null'
          format: uuid
          description: Profile avatar document ID
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        teams:
          type: array
          description: Teams this user belongs to (replaces all existing team memberships)
          items:
            $ref: '#/components/schemas/ResourceReferenceInput'
          example:
            - id: 123e4567-e89b-12d3-a456-426614174000
            - key: TEAM-WEST-COAST
      x-parsed-md-description:
        result:
          - $$mdtype: Node
            errors: []
            lines:
              - 0
              - 1
            inline: false
            attributes: {}
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 0
                  - 1
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 0
                      - 1
                    inline: true
                    attributes:
                      content: Partial user update. All fields are optional.
                    children: []
                    type: text
                    annotations: []
                    slots: {}
                type: inline
                annotations: []
                slots: {}
            type: paragraph
            annotations: []
            slots: {}
          - $$mdtype: Node
            errors: []
            lines:
              - 1
              - 4
            inline: false
            attributes:
              ordered: false
              marker: '-'
            children:
              - $$mdtype: Node
                errors: []
                lines:
                  - 1
                  - 2
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 1
                      - 2
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 1
                              - 2
                            inline: true
                            attributes:
                              content: Omitted fields
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 1
                          - 2
                        inline: true
                        attributes:
                          content: ': Not modified (current value preserved)'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 2
                  - 3
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 2
                      - 3
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 2
                              - 3
                            inline: true
                            attributes:
                              content: Provided fields
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 2
                          - 3
                        inline: true
                        attributes:
                          content: ': Updated to the new value'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
              - $$mdtype: Node
                errors: []
                lines:
                  - 3
                  - 4
                inline: false
                attributes: {}
                children:
                  - $$mdtype: Node
                    errors: []
                    lines:
                      - 3
                      - 4
                    inline: false
                    attributes: {}
                    children:
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          marker: '**'
                        children:
                          - $$mdtype: Node
                            errors: []
                            lines:
                              - 3
                              - 4
                            inline: true
                            attributes:
                              content: Null values
                            children: []
                            type: text
                            annotations: []
                            slots: {}
                        type: strong
                        annotations: []
                        slots: {}
                      - $$mdtype: Node
                        errors: []
                        lines:
                          - 3
                          - 4
                        inline: true
                        attributes:
                          content: ': Clear the field (set to null) where applicable'
                        children: []
                        type: text
                        annotations: []
                        slots: {}
                    type: inline
                    annotations: []
                    slots: {}
                type: item
                annotations: []
                slots: {}
            type: list
            annotations: []
            slots: {}
    VendorStatus:
      type: string
      description: Vendor status
      enum:
        - ACTIVE
        - INACTIVE
    VendorStatusFilter:
      type: object
      description: Filter for vendor status enum field
      properties:
        equalTo:
          $ref: '#/components/schemas/VendorStatus'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/VendorStatus'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/VendorStatus'
          description: Matches any value in the list
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/VendorStatus'
          description: Does not match any value in the list
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    VendorFilter:
      type: object
      description: Filter criteria for vendors with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/VendorFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/VendorFilter'
        not:
          $ref: '#/components/schemas/VendorFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        friendlyId:
          $ref: '#/components/schemas/StringFilter'
        name:
          $ref: '#/components/schemas/StringFilter'
        key:
          $ref: '#/components/schemas/ClientKeyFilter'
        email:
          $ref: '#/components/schemas/StringFilter'
        phone:
          $ref: '#/components/schemas/StringFilter'
        status:
          $ref: '#/components/schemas/VendorStatusFilter'
        notes:
          $ref: '#/components/schemas/StringFilter'
        taxId:
          $ref: '#/components/schemas/StringFilter'
        currency:
          $ref: '#/components/schemas/CurrencyFilter'
        paymentTermId:
          $ref: '#/components/schemas/UUIDFilter'
        isMvmnt:
          $ref: '#/components/schemas/BooleanFilter'
        deletedById:
          $ref: '#/components/schemas/UUIDFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    VendorFilterRequest:
      type: object
      description: Request body for filtering vendors
      properties:
        filter:
          $ref: '#/components/schemas/VendorFilter'
          description: >
            Filter criteria (optional - omit to return all vendors).


            Note: deletedAt automatically defaults to { isNull: true } unless
            explicitly overridden.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - status:
                equalTo: ACTIVE
            - currency:
                equalTo: USD
        pageSize: 50
    Vendor:
      type: object
      required:
        - id
        - friendlyId
        - name
        - createdAt
        - updatedAt
      properties:
        object:
          type: string
          enum:
            - VENDOR
          readOnly: true
          description: Object type identifier
          example: VENDOR
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique vendor identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        friendlyId:
          type: string
          readOnly: true
          description: Human-readable vendor identifier
          example: V123456
        name:
          type: string
          description: Vendor legal name
          example: ABC Warehouse Services
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-VENDOR-ABC-001
        email:
          type:
            - string
            - 'null'
          format: email
          description: Primary email address
          example: billing@abcwarehouse.com
        phone:
          type:
            - string
            - 'null'
          description: Primary phone number
          example: +1-555-123-4567
        status:
          type:
            - string
            - 'null'
          description: Vendor status
          example: ACTIVE
        notes:
          type:
            - string
            - 'null'
          description: Internal notes about the vendor
          example: Preferred vendor for warehouse services
        taxId:
          type:
            - string
            - 'null'
          description: Tax identification number
          example: 12-3456789
        currency:
          anyOf:
            - $ref: '#/components/schemas/vendors_Currency'
            - type: 'null'
          description: Preferred currency for transactions
        corporateAddress:
          anyOf:
            - $ref: '#/components/schemas/Address'
            - type: 'null'
          description: Corporate headquarters address
        billingAddress:
          anyOf:
            - $ref: '#/components/schemas/Address'
            - type: 'null'
          description: Billing address for invoices
        paymentTerm:
          anyOf:
            - $ref: '#/components/schemas/PaymentTermReference'
            - type: 'null'
          description: Payment terms for this vendor
        isMvmnt:
          type:
            - boolean
            - 'null'
          description: Whether this vendor is MVMNT itself
          example: false
        requiredDocuments:
          type:
            - array
            - 'null'
          items:
            type: string
          description: List of required document types
          example:
            - W9
            - INSURANCE_CERTIFICATE
        paymentMethods:
          type: array
          description: Payment methods configured for this vendor
          items:
            $ref: '#/components/schemas/VendorPaymentMethodReference'
        contacts:
          type: array
          description: Contacts for this vendor
          items:
            $ref: '#/components/schemas/VendorContactReference'
        deletedBy:
          anyOf:
            - $ref: '#/components/schemas/UserReference'
            - type: 'null'
          readOnly: true
          description: User who deleted this vendor (full user details)
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the vendor was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the vendor was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: When the vendor was soft deleted (null if active)
          example: null
    VendorInput:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Vendor legal name
          example: ABC Warehouse Services
        key:
          type: string
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-VENDOR-ABC-001
        email:
          type: string
          format: email
          description: Primary email address
          example: billing@abcwarehouse.com
        phone:
          type: string
          description: Primary phone number
          example: +1-555-123-4567
        status:
          type: string
          description: Vendor status
          example: ACTIVE
        notes:
          type: string
          description: Internal notes about the vendor
          example: Preferred vendor for warehouse services
        taxId:
          type: string
          description: Tax identification number
          example: 12-3456789
        currency:
          $ref: '#/components/schemas/vendors_Currency'
          description: Preferred currency for transactions
        corporateAddress:
          $ref: '#/components/schemas/AddressInput'
          description: Corporate headquarters address
        billingAddress:
          $ref: '#/components/schemas/AddressInput'
          description: Billing address for invoices
        paymentTermId:
          type: string
          format: uuid
          description: Payment term ID
          example: 550e8400-e29b-41d4-a716-446655440001
        isMvmnt:
          type: boolean
          description: Whether this vendor is MVMNT itself
          example: false
        requiredDocuments:
          type: array
          items:
            type: string
          description: List of required document types
          example:
            - W9
            - INSURANCE_CERTIFICATE
    VendorPatch:
      type: object
      description: |
        Partial vendor update. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        name:
          type: string
          description: Vendor legal name
          example: ABC Warehouse Services
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-VENDOR-ABC-001
        email:
          type:
            - string
            - 'null'
          format: email
          description: Primary email address
          example: billing@abcwarehouse.com
        phone:
          type:
            - string
            - 'null'
          description: Primary phone number
          example: +1-555-123-4567
        status:
          type:
            - string
            - 'null'
          description: Vendor status
          example: ACTIVE
        notes:
          type:
            - string
            - 'null'
          description: Internal notes about the vendor
          example: Preferred vendor for warehouse services
        taxId:
          type:
            - string
            - 'null'
          description: Tax identification number
          example: 12-3456789
        currency:
          anyOf:
            - $ref: '#/components/schemas/vendors_Currency'
            - type: 'null'
          description: Preferred currency for transactions
        corporateAddress:
          anyOf:
            - $ref: '#/components/schemas/AddressInput'
            - type: 'null'
          description: Corporate headquarters address
        billingAddress:
          anyOf:
            - $ref: '#/components/schemas/AddressInput'
            - type: 'null'
          description: Billing address for invoices
        paymentTermId:
          type:
            - string
            - 'null'
          format: uuid
          description: Payment term ID
          example: 550e8400-e29b-41d4-a716-446655440001
        isMvmnt:
          type:
            - boolean
            - 'null'
          description: Whether this vendor is MVMNT itself
          example: false
        requiredDocuments:
          type:
            - array
            - 'null'
          items:
            type: string
          description: List of required document types
          example:
            - W9
            - INSURANCE_CERTIFICATE
    VendorContactRole:
      type: string
      description: Type of vendor contact role
      enum:
        - AGENT
        - BILLING
        - OPERATION
        - OWNER
    VendorContactRoleFilter:
      type: object
      description: Filter for contact role enum array field
      properties:
        includes:
          $ref: '#/components/schemas/VendorContactRole'
          description: Array contains this contact role
        notIncludes:
          $ref: '#/components/schemas/VendorContactRole'
          description: Array does not contain this contact role
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    VendorContactFilter:
      type: object
      description: Filter criteria for vendor contacts with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/VendorContactFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/VendorContactFilter'
        not:
          $ref: '#/components/schemas/VendorContactFilter'
          description: Negates the filter
        vendorId:
          $ref: '#/components/schemas/UUIDFilter'
        email:
          $ref: '#/components/schemas/StringFilter'
        phone:
          $ref: '#/components/schemas/StringFilter'
        role:
          $ref: '#/components/schemas/StringFilter'
        roles:
          $ref: '#/components/schemas/VendorContactRoleFilter'
        deletedById:
          $ref: '#/components/schemas/UUIDFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    VendorContactFilterRequest:
      type: object
      description: Request body for filtering vendor contacts
      properties:
        filter:
          $ref: '#/components/schemas/VendorContactFilter'
          description: >
            Filter criteria (optional - omit to return all vendor contacts).


            Note: deletedAt automatically defaults to { isNull: true } unless
            explicitly overridden.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - roles:
                includes: BILLING
            - vendorId:
                equalTo: 550e8400-e29b-41d4-a716-446655440001
        pageSize: 50
    VendorContact:
      type: object
      required:
        - vendor
        - createdAt
      properties:
        object:
          type: string
          enum:
            - VENDOR_CONTACT
          readOnly: true
          description: Object type identifier
          example: VENDOR_CONTACT
        vendor:
          $ref: '#/components/schemas/ResourceReference'
          description: Vendor this contact belongs to (id and key only)
        email:
          type:
            - string
            - 'null'
          format: email
          description: Contact email address
          example: john.smith@abcwarehouse.com
        phone:
          type:
            - string
            - 'null'
          description: Contact phone number
          example: +1-555-123-4567
        role:
          type:
            - string
            - 'null'
          description: Contact role or title (deprecated - use roles array)
          example: Billing Manager
        roles:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/VendorContactRole'
          description: Types/roles this contact serves
          example:
            - BILLING
            - AGENT
        deletedBy:
          anyOf:
            - $ref: '#/components/schemas/UserReference'
            - type: 'null'
          readOnly: true
          description: User who deleted this contact (full user details)
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the contact was created
          example: '2025-01-15T10:00:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: When the contact was soft deleted (null if active)
          example: null
    VendorContactInput:
      type: object
      required:
        - vendorId
      properties:
        vendorId:
          type: string
          format: uuid
          description: Vendor this contact belongs to
          example: 550e8400-e29b-41d4-a716-446655440001
        email:
          type: string
          format: email
          description: Contact email address
          example: john.smith@abcwarehouse.com
        phone:
          type: string
          description: Contact phone number
          example: +1-555-123-4567
        role:
          type: string
          description: Contact role or title (deprecated - use roles array)
          example: Billing Manager
        roles:
          type: array
          items:
            $ref: '#/components/schemas/VendorContactRole'
          description: Types/roles this contact serves
          example:
            - BILLING
            - AGENT
    VendorContactPatch:
      type: object
      description: |
        Partial vendor contact update. All fields are optional.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable

        Note: vendorId cannot be updated after creation.
      properties:
        email:
          type:
            - string
            - 'null'
          format: email
          description: Contact email address
          example: john.smith@abcwarehouse.com
        phone:
          type:
            - string
            - 'null'
          description: Contact phone number
          example: +1-555-123-4567
        role:
          type:
            - string
            - 'null'
          description: Contact role or title (deprecated - use roles array)
          example: Billing Manager
        roles:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/VendorContactRole'
          description: Types/roles this contact serves (replaces entire array)
          example:
            - BILLING
            - AGENT
    VendorReference:
      type: object
      description: |
        Enhanced reference to a vendor profile.
        Includes full vendor details in addition to id/key.
      required:
        - id
        - friendlyId
        - name
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: Vendor UUID
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference ID if set
          example: ERP-VENDOR-ABC-001
        friendlyId:
          type: string
          description: Human-readable vendor identifier
          example: V123456
        name:
          type: string
          description: Vendor legal name
          example: ABC Warehouse Services
        email:
          type:
            - string
            - 'null'
          format: email
          description: Primary email address
          example: billing@abcwarehouse.com
        phone:
          type:
            - string
            - 'null'
          description: Primary phone number
          example: +1-555-123-4567
        status:
          type:
            - string
            - 'null'
          description: Vendor status
          example: ACTIVE
        currency:
          type:
            - string
            - 'null'
          description: Preferred currency code (ISO 4217)
          example: USD
        createdAt:
          type: string
          format: date-time
          description: When the vendor was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          description: When the vendor was last updated
          example: '2025-01-15T14:30:00Z'
    VendorPaymentMethodType:
      $ref: '#/components/schemas/PaymentMethodType'
    VendorPaymentMethodTypeFilter:
      $ref: '#/components/schemas/PaymentMethodTypeFilter'
    VendorPaymentMethod:
      type: object
      required:
        - id
        - vendorId
        - vendor
        - paymentMethodType
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique vendor payment method identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        vendorId:
          type: string
          format: uuid
          readOnly: true
          description: |
            Vendor profile ID (read-only after creation).

            This field cannot be changed after the payment method is created.
          example: 770e8400-e29b-41d4-a716-446655440000
        vendor:
          $ref: '#/components/schemas/VendorReference'
          description: Vendor profile reference with full details
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType'
          description: How payment is made
        status:
          type:
            - string
            - 'null'
          description: Payment method status
          example: ACTIVE
        isPreferred:
          type:
            - boolean
            - 'null'
          description: Whether this is the preferred payment method for the vendor
          example: true
        email:
          type:
            - string
            - 'null'
          format: email
          description: Email address for payment notifications
          example: payments@vendor.com
        phone:
          type:
            - string
            - 'null'
          description: Phone number for payment contact
          example: +1-555-123-4567
        companyName:
          type:
            - string
            - 'null'
          description: Company name for this payment method (may differ from vendor name)
          example: Vendor Payments LLC
        username:
          type:
            - string
            - 'null'
          description: Username for payment platforms (e.g., Zelle, Venmo)
          example: vendor_payments
        bankName:
          type:
            - string
            - 'null'
          description: Bank name
          example: Chase Bank
        bankAddress:
          type:
            - string
            - 'null'
          description: Bank address
          example: 123 Bank Street, Dallas, TX 75201
        accountName:
          type:
            - string
            - 'null'
          description: Bank account holder name
          example: Vendor Services Inc
        accountNumber:
          type:
            - string
            - 'null'
          description: Bank account number (masked in responses)
          example: '****1234'
        abaAch:
          type:
            - string
            - 'null'
          description: ABA/ACH routing number for electronic transfers
          example: '021000021'
        wire:
          type:
            - string
            - 'null'
          description: Wire transfer routing number
          example: '026009593'
        swiftCode:
          type:
            - string
            - 'null'
          description: SWIFT/BIC code for international transfers
          example: CHASUS33
        eftInstitution:
          type:
            - string
            - 'null'
          description: EFT institution number (Canadian banking)
          example: '001'
        eftTransit:
          type:
            - string
            - 'null'
          description: EFT transit number (Canadian banking)
          example: '00010'
        clabe:
          type:
            - string
            - 'null'
          description: CLABE number (Mexican banking identifier)
          example: '012180001234567897'
        currency:
          type:
            - string
            - 'null'
          description: Preferred currency code (ISO 4217)
          example: USD
        paymentTerm:
          anyOf:
            - $ref: '#/components/schemas/PaymentTermReference'
            - type: 'null'
          description: Payment terms for this payment method
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment method was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment method was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: When the payment method was soft deleted (null if active)
          example: null
        deletedBy:
          anyOf:
            - $ref: '#/components/schemas/UserReference'
            - type: 'null'
          readOnly: true
          description: User who deleted this payment method
    VendorPaymentMethodInput:
      type: object
      required:
        - vendorId
        - paymentMethodType
      properties:
        vendorId:
          type: string
          format: uuid
          description: |
            Vendor profile ID.

            **IMPORTANT**: This field cannot be changed after creation.
          example: 770e8400-e29b-41d4-a716-446655440000
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType'
          description: How payment is made
        status:
          type: string
          description: Payment method status
          example: ACTIVE
        isPreferred:
          type: boolean
          description: Whether this is the preferred payment method
          example: true
        email:
          type: string
          format: email
          description: Email address for payment notifications
          example: payments@vendor.com
        phone:
          type: string
          description: Phone number for payment contact
          example: +1-555-123-4567
        companyName:
          type: string
          description: Company name for this payment method
          example: Vendor Payments LLC
        username:
          type: string
          description: Username for payment platforms
          example: vendor_payments
        bankName:
          type: string
          description: Bank name
          example: Chase Bank
        bankAddress:
          type: string
          description: Bank address
          example: 123 Bank Street, Dallas, TX 75201
        accountName:
          type: string
          description: Bank account holder name
          example: Vendor Services Inc
        accountNumber:
          type: string
          description: Bank account number
          example: '1234567890'
        abaAch:
          type: string
          description: ABA/ACH routing number
          example: '021000021'
        wire:
          type: string
          description: Wire transfer routing number
          example: '026009593'
        swiftCode:
          type: string
          description: SWIFT/BIC code for international transfers
          example: CHASUS33
        eftInstitution:
          type: string
          description: EFT institution number (Canadian banking)
          example: '001'
        eftTransit:
          type: string
          description: EFT transit number (Canadian banking)
          example: '00010'
        clabe:
          type: string
          description: CLABE number (Mexican banking)
          example: '012180001234567897'
        currency:
          type: string
          description: Preferred currency code (ISO 4217)
          example: USD
        paymentTermId:
          type: string
          format: uuid
          description: Payment term ID
          example: 550e8400-e29b-41d4-a716-446655440002
    VendorPaymentMethodPatch:
      type: object
      description: |
        Partial vendor payment method update. All fields are optional.

        **IMPORTANT**: The `vendorId` field cannot be changed after creation.

        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType'
          description: How payment is made
        status:
          type:
            - string
            - 'null'
          description: Payment method status
          example: ACTIVE
        isPreferred:
          type:
            - boolean
            - 'null'
          description: Whether this is the preferred payment method
          example: true
        email:
          type:
            - string
            - 'null'
          format: email
          description: Email address for payment notifications
          example: payments@vendor.com
        phone:
          type:
            - string
            - 'null'
          description: Phone number for payment contact
          example: +1-555-123-4567
        companyName:
          type:
            - string
            - 'null'
          description: Company name for this payment method
          example: Vendor Payments LLC
        username:
          type:
            - string
            - 'null'
          description: Username for payment platforms
          example: vendor_payments
        bankName:
          type:
            - string
            - 'null'
          description: Bank name
          example: Chase Bank
        bankAddress:
          type:
            - string
            - 'null'
          description: Bank address
          example: 123 Bank Street, Dallas, TX 75201
        accountName:
          type:
            - string
            - 'null'
          description: Bank account holder name
          example: Vendor Services Inc
        accountNumber:
          type:
            - string
            - 'null'
          description: Bank account number
          example: '1234567890'
        abaAch:
          type:
            - string
            - 'null'
          description: ABA/ACH routing number
          example: '021000021'
        wire:
          type:
            - string
            - 'null'
          description: Wire transfer routing number
          example: '026009593'
        swiftCode:
          type:
            - string
            - 'null'
          description: SWIFT/BIC code
          example: CHASUS33
        eftInstitution:
          type:
            - string
            - 'null'
          description: EFT institution number
          example: '001'
        eftTransit:
          type:
            - string
            - 'null'
          description: EFT transit number
          example: '00010'
        clabe:
          type:
            - string
            - 'null'
          description: CLABE number
          example: '012180001234567897'
        currency:
          type:
            - string
            - 'null'
          description: Preferred currency code
          example: USD
        paymentTermId:
          type:
            - string
            - 'null'
          format: uuid
          description: Payment term ID
          example: 550e8400-e29b-41d4-a716-446655440002
    VendorPaymentMethodFilter:
      type: object
      description: Filter criteria for vendor payment methods with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/VendorPaymentMethodFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/VendorPaymentMethodFilter'
        not:
          $ref: '#/components/schemas/VendorPaymentMethodFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        vendorId:
          $ref: '#/components/schemas/UUIDFilter'
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodTypeFilter'
        status:
          $ref: '#/components/schemas/StringFilter'
        isPreferred:
          $ref: '#/components/schemas/BooleanFilter'
        email:
          $ref: '#/components/schemas/StringFilter'
        companyName:
          $ref: '#/components/schemas/StringFilter'
        bankName:
          $ref: '#/components/schemas/StringFilter'
        currency:
          $ref: '#/components/schemas/StringFilter'
        paymentTermId:
          $ref: '#/components/schemas/UUIDFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
        deletedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    VendorPaymentMethodFilterRequest:
      type: object
      description: Request body for filtering vendor payment methods
      properties:
        filter:
          $ref: '#/components/schemas/VendorPaymentMethodFilter'
          description: >
            Filter criteria (optional - omit to return all vendor payment
            methods).


            Note: deletedAt automatically defaults to { isNull: true } unless
            explicitly overridden.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          and:
            - vendorId:
                equalTo: 770e8400-e29b-41d4-a716-446655440000
            - isPreferred:
                equalTo: true
        pageSize: 50
    SavedSearchType:
      type: string
      description: >
        Type of entity this saved search applies to. Each type corresponds to a
        specific entity's search view.


        **Entity Mapping:**

        - `INVOICE`: Customer invoices (AR Invoices) - money owed to you

        - `BILL`: Vendor/Carrier bills (AP Invoices) - money you owe

        - `INVOICE_PAYMENT`: Customer payment groups (AR Payment Groups)

        - `BILL_PAYMENT`: Vendor/Carrier payment groups (AP Payment Groups)
      enum:
        - SHIPMENT
        - INVOICE
        - BILL
        - USER
        - CUSTOMER
        - VENDOR
        - QUOTE
        - COMMISSION
        - CARRIER
        - INVOICE_PAYMENT
        - BILL_PAYMENT
        - LOAD
        - TRUCK_POSTING
        - LOCATION
      example: SHIPMENT
    SavedSearchFilter:
      type: object
      description: Filter criteria for saved searches with AND/OR logic support
      properties:
        and:
          type: array
          description: All conditions must match (recursive)
          items:
            $ref: '#/components/schemas/SavedSearchFilter'
        or:
          type: array
          description: At least one condition must match (recursive)
          items:
            $ref: '#/components/schemas/SavedSearchFilter'
        not:
          $ref: '#/components/schemas/SavedSearchFilter'
          description: Negates the filter
        id:
          $ref: '#/components/schemas/IDFilter'
        name:
          $ref: '#/components/schemas/StringFilter'
        preferenceType:
          $ref: '#/components/schemas/StringFilter'
        isPublic:
          $ref: '#/components/schemas/BooleanFilter'
        pinned:
          $ref: '#/components/schemas/BooleanFilter'
        createdAt:
          $ref: '#/components/schemas/DatetimeFilter'
        updatedAt:
          $ref: '#/components/schemas/DatetimeFilter'
    SavedSearchFilterRequest:
      type: object
      description: Request body for filtering saved searches
      properties:
        filter:
          $ref: '#/components/schemas/SavedSearchFilter'
          description: |
            Filter criteria (optional - omit to return all saved searches).
            Returns only saved searches accessible to the authenticated user.
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page
        cursor:
          type: string
          description: Pagination cursor for next page
      example:
        filter:
          preferenceType:
            equalTo: SHIPMENT
          isPublic:
            equalTo: true
        pageSize: 50
    SearchConfigurationState:
      type: object
      description: >
        The saved search configuration state containing criteria, sorting, and
        display preferences.

        This is stored in the jsonValue field.
      properties:
        searchCriteria:
          type: object
          description: Search criteria configuration
          properties:
            filters:
              type: array
              description: Array of field-level search filters
              items:
                type: object
                required:
                  - field
                  - searchCriteria
                properties:
                  field:
                    type: string
                    description: The field name to filter on
                    example: status
                  searchCriteria:
                    type: object
                    description: The search criteria for this field
                    required:
                      - operator
                    properties:
                      operator:
                        type: string
                        description: Search operator (e.g., EQUALS, ONE_OF, BETWEEN)
                        example: ONE_OF
                      values:
                        type: array
                        description: Array of values for multi-value operators
                        items:
                          oneOf:
                            - type: string
                            - type: number
                            - type: boolean
                        example:
                          - ACTIVE
                          - PENDING
                      value:
                        oneOf:
                          - type: string
                          - type: number
                          - type: boolean
                        description: Single value for single-value operators
                      min:
                        oneOf:
                          - type: string
                          - type: number
                        description: Minimum value for range operators
                      max:
                        oneOf:
                          - type: string
                          - type: number
                        description: Maximum value for range operators
                      minRelative:
                        type: integer
                        description: Relative minimum (e.g., -7 for 7 units ago)
                      minRelativeUnit:
                        type: string
                        description: Time unit for minRelative
                        enum:
                          - YEAR
                          - MONTH
                          - WEEK
                          - DAY
                          - HOUR
                          - MINUTE
                          - SECOND
                      maxRelative:
                        type: integer
                        description: Relative maximum
                      maxRelativeUnit:
                        type: string
                        description: Time unit for maxRelative
                        enum:
                          - YEAR
                          - MONTH
                          - WEEK
                          - DAY
                          - HOUR
                          - MINUTE
                          - SECOND
                      valueRelative:
                        type: integer
                        description: Relative value
                      valueRelativeUnit:
                        type: string
                        description: Time unit for valueRelative
                        enum:
                          - YEAR
                          - MONTH
                          - WEEK
                          - DAY
                          - HOUR
                          - MINUTE
                          - SECOND
        sorting:
          type: array
          description: Sort configuration
          items:
            type: object
            required:
              - id
              - desc
            properties:
              id:
                type: string
                description: Field name to sort by
                example: createdAt
              desc:
                type: boolean
                description: Sort in descending order if true
                example: true
        columnVisibility:
          type: object
          description: Column visibility settings (key is column name, value is visibility)
          additionalProperties:
            type: boolean
          example:
            status: true
            createdAt: true
            updatedAt: false
        columnOrder:
          type: array
          description: Order of columns for display
          items:
            type: string
          example:
            - id
            - name
            - status
            - createdAt
      example:
        searchCriteria:
          filters:
            - field: status
              searchCriteria:
                operator: ONE_OF
                values:
                  - ACTIVE
                  - PENDING
        sorting:
          - id: createdAt
            desc: true
        columnVisibility:
          status: true
          createdAt: true
        columnOrder:
          - id
          - status
          - createdAt
    SavedSearch:
      type: object
      required:
        - id
        - name
        - preferenceType
        - createdAt
        - updatedAt
      description: >
        A saved search configuration that can be used to quickly apply
        predefined search criteria,

        sorting, and display preferences. Saved searches are stored per
        organization and can be

        shared publicly or kept private to a specific user.
      properties:
        object:
          type: string
          enum:
            - SAVED_SEARCH
          readOnly: true
          description: Object type identifier
          example: SAVED_SEARCH
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique saved search identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          description: Display name for the saved search
          example: Active Shipments - West Coast
        preferenceType:
          allOf:
            - $ref: '#/components/schemas/SavedSearchType'
          description: |
            The entity type this saved search applies to.
            Must match the search endpoint where this saved search will be used.
        jsonValue:
          allOf:
            - $ref: '#/components/schemas/SearchConfigurationState'
          description: >-
            The saved search configuration (criteria, sorting, display
            preferences)
        isPublic:
          type:
            - boolean
            - 'null'
          description: >
            Whether this saved search is visible to all users in the
            organization.

            If false or null, only the owner can see it.
          example: true
        pinned:
          type:
            - boolean
            - 'null'
          description: Whether this saved search is pinned for quick access
          example: true
        ownedByUser:
          type:
            - string
            - 'null'
          format: uuid
          readOnly: true
          description: |
            User ID who owns this saved search.
            Null means it's an organization-level saved search.
          example: 550e8400-e29b-41d4-a716-446655440001
        groupId:
          type:
            - string
            - 'null'
          format: uuid
          description: Optional group this saved search belongs to
          example: null
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when saved search was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when saved search was last updated
          example: '2025-01-15T14:30:00Z'
    SavedSearchInput:
      type: object
      required:
        - name
        - preferenceType
        - jsonValue
      description: Input for creating a new saved search
      properties:
        name:
          type: string
          description: Display name for the saved search (required)
          example: Active Shipments - West Coast
        preferenceType:
          allOf:
            - $ref: '#/components/schemas/SavedSearchType'
          description: |
            The entity type this saved search applies to (required).
            Determines which search endpoint can use this saved search.
        jsonValue:
          allOf:
            - $ref: '#/components/schemas/SearchConfigurationState'
          description: The saved search configuration (required)
        isPublic:
          type: boolean
          description: >-
            Whether this saved search is visible to all users in the
            organization
          default: false
          example: true
        pinned:
          type: boolean
          description: Whether this saved search is pinned for quick access
          default: false
          example: true
        groupId:
          type: string
          format: uuid
          description: Optional group this saved search belongs to
      example:
        name: Active Shipments - West Coast
        preferenceType: SHIPMENT
        jsonValue:
          searchCriteria:
            filters:
              - field: status
                searchCriteria:
                  operator: ONE_OF
                  values:
                    - ACTIVE
                    - PENDING
          sorting:
            - id: createdAt
              desc: true
        isPublic: true
        pinned: true
    SavedSearchPatch:
      type: object
      description: |
        Partial saved search update. All fields are optional.
        - **Omitted fields**: Not modified (current value preserved)
        - **Provided fields**: Updated to the new value
        - **Null values**: Clear the field (set to null) where applicable
      properties:
        name:
          type: string
          description: Display name for the saved search
          example: Updated Shipments View
        jsonValue:
          allOf:
            - $ref: '#/components/schemas/SearchConfigurationState'
          description: The saved search configuration
        isPublic:
          type:
            - boolean
            - 'null'
          description: Whether this saved search is visible to all users
          example: true
        pinned:
          type:
            - boolean
            - 'null'
          description: Whether this saved search is pinned for quick access
          example: false
        groupId:
          type:
            - string
            - 'null'
          format: uuid
          description: Optional group this saved search belongs to
          example: null
      example:
        name: Updated Shipments View
        isPublic: true
        pinned: false
    CustomerSearchCriteria:
      type: object
      description: >
        Search criteria for filtering customers.

        Note: Only active (non-deleted) customers are searchable. Soft-deleted
        records are automatically excluded.
      properties:
        id:
          $ref: '#/components/schemas/UUIDSearchCriteria'
        friendlyId:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        name:
          $ref: '#/components/schemas/TextSearchCriteria'
        dbaName:
          $ref: '#/components/schemas/TextSearchCriteria'
        status:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Customer status (ACTIVE, INACTIVE, PENDING, SUSPENDED, ARCHIVED)
        city:
          $ref: '#/components/schemas/TextSearchCriteria'
        state:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: State/Province code (uppercase)
        location:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Computed field "city, state"
        zip:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        country:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Country code (uppercase)
        teamId:
          $ref: '#/components/schemas/UUIDSearchCriteria'
          description: Team ID (internal field groupId)
        teamName:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Team name (internal field groupName)
        userIds:
          $ref: '#/components/schemas/UUIDSearchCriteria'
          description: IDs of users associated with this customer
        userNames:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Names of users associated with this customer
        accountOwnerId:
          $ref: '#/components/schemas/UUIDSearchCriteria'
          description: Primary account owner user ID
        accountOwnerName:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Primary account owner name
        operatedById:
          $ref: '#/components/schemas/UUIDSearchCriteria'
          description: Operations representative user ID
        operatedByName:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Operations representative name
        primaryContactName:
          $ref: '#/components/schemas/TextSearchCriteria'
        primaryContactEmail:
          $ref: '#/components/schemas/TextSearchCriteria'
        primaryContactPhone:
          $ref: '#/components/schemas/TextSearchCriteria'
        serviceTier:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        yearsInBusiness:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        numberOfEmployees:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        industry:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        sic:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Standard Industrial Classification code
        naics:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: North American Industry Classification System code
        paymentTermName:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        creditLimit:
          $ref: '#/components/schemas/FloatSearchCriteria'
        outstandingBalance:
          $ref: '#/components/schemas/FloatSearchCriteria'
        totalRevenue:
          $ref: '#/components/schemas/FloatSearchCriteria'
        totalTransportationCost:
          $ref: '#/components/schemas/FloatSearchCriteria'
        totalGrossProfit:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Computed as totalRevenue - totalTransportationCost
        ordersCount:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of non-canceled/rejected shipments
        quotesCount:
          $ref: '#/components/schemas/IntSearchCriteria'
        quotesWon:
          $ref: '#/components/schemas/IntSearchCriteria'
        quoteWinRate:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Computed win rate (quotesWon / quotesCount)
        mostRecentOrderCreationAt:
          $ref: '#/components/schemas/DatetimeSearchCriteria'
          description: Date of the most recent order
        nextFollowUp:
          $ref: '#/components/schemas/DateSearchCriteria'
        lastOutreach:
          $ref: '#/components/schemas/DatetimeSearchCriteria'
        quickbooksCustomerId:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: QuickBooks Online customer ID (internal field qboCustomerId)
        tags:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Tag labels associated with the customer
        createdAt:
          $ref: '#/components/schemas/DatetimeSearchCriteria'
        updatedAt:
          $ref: '#/components/schemas/DatetimeSearchCriteria'
    CustomerSearchRequest:
      type: object
      description: Request body for searching customers
      properties:
        criteria:
          $ref: '#/components/schemas/CustomerSearchCriteria'
          description: Search criteria to filter customers
        pagination:
          $ref: '#/components/schemas/SearchPaginationInput'
        sort:
          type: array
          items:
            $ref: '#/components/schemas/SearchSortOption'
          maxItems: 3
          description: Sort options for the search results
        savedSearch:
          $ref: '#/components/schemas/SavedSearchLookup'
          description: >
            Optional saved search to load preferences from.

            When provided, the saved search criteria will be loaded and merged
            with any explicit criteria.
        format:
          type: string
          enum:
            - flat
            - full
          default: flat
          description: |
            Response format:
            - flat: Returns only indexed fields (default, faster)
            - full: Returns complete customer objects
    CustomerSearchRow:
      type: object
      description: >
        Flattened customer data from search index.

        Note: This represents only active customers. Soft-deleted records are
        never returned.
      properties:
        object:
          type: string
          enum:
            - CUSTOMER_SEARCH_ROW
          description: >-
            Object type identifier for discriminating between flat and full
            response formats
        id:
          type: string
          format: uuid
        friendlyId:
          type: string
          example: CUST-0001
        name:
          type: string
        dbaName:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
            - PENDING
            - SUSPENDED
            - ARCHIVED
        city:
          type:
            - string
            - 'null'
        state:
          type:
            - string
            - 'null'
          description: State/Province code (uppercase)
        location:
          type:
            - string
            - 'null'
          description: Computed as "city, state"
        zip:
          type:
            - string
            - 'null'
        country:
          type:
            - string
            - 'null'
          description: Country code (uppercase)
        teamId:
          type:
            - string
            - 'null'
          format: uuid
          description: Team ID (maps from groupId)
        teamName:
          type:
            - string
            - 'null'
          description: Team name (maps from groupName)
        userIds:
          type: array
          items:
            type: string
            format: uuid
          description: IDs of users associated with this customer
        userNames:
          type: array
          items:
            type: string
          description: >-
            Names of users associated with this customer (may be hidden in some
            contexts)
        accountOwnerId:
          type:
            - string
            - 'null'
          format: uuid
        accountOwnerName:
          type:
            - string
            - 'null'
        operatedById:
          type:
            - string
            - 'null'
          format: uuid
        operatedByName:
          type:
            - string
            - 'null'
        primaryContactName:
          type:
            - string
            - 'null'
        primaryContactEmail:
          type:
            - string
            - 'null'
          format: email
        primaryContactPhone:
          type:
            - string
            - 'null'
        serviceTier:
          type:
            - string
            - 'null'
        yearsInBusiness:
          type:
            - string
            - 'null'
        numberOfEmployees:
          type:
            - string
            - 'null'
        industry:
          type:
            - string
            - 'null'
        sic:
          type:
            - string
            - 'null'
          description: Standard Industrial Classification code
        naics:
          type:
            - string
            - 'null'
          description: North American Industry Classification System code
        paymentTermName:
          type:
            - string
            - 'null'
        creditLimit:
          type:
            - number
            - 'null'
          format: float
        outstandingBalance:
          type:
            - number
            - 'null'
          format: float
        totalRevenue:
          type:
            - number
            - 'null'
          format: float
        totalTransportationCost:
          type:
            - number
            - 'null'
          format: float
        totalGrossProfit:
          type:
            - number
            - 'null'
          format: float
          description: Computed as totalRevenue - totalTransportationCost
        ordersCount:
          type:
            - integer
            - 'null'
          description: Number of non-canceled/rejected shipments
        quotesCount:
          type:
            - integer
            - 'null'
        quotesWon:
          type:
            - integer
            - 'null'
        quoteWinRate:
          type:
            - number
            - 'null'
          format: float
          description: Win rate percentage (0-100)
        mostRecentOrderCreationAt:
          type:
            - string
            - 'null'
          format: date-time
        nextFollowUp:
          type:
            - string
            - 'null'
          format: date
        lastOutreach:
          type:
            - string
            - 'null'
          format: date-time
        quickbooksCustomerId:
          type:
            - string
            - 'null'
          description: QuickBooks Online customer ID (maps from qboCustomerId)
        tags:
          type: array
          items:
            type: string
          description: Tag labels
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - object
        - id
        - friendlyId
        - name
        - status
        - createdAt
        - updatedAt
    CustomerSearchResponse:
      type: object
      description: |
        Response for customer search requests.
        Note: Only active (non-deleted) customers are included in results.
      required:
        - data
        - pagination
        - totalResults
      properties:
        data:
          type: array
          description: >-
            Search results - either flat rows or full customer objects based on
            format parameter
          items:
            oneOf:
              - $ref: '#/components/schemas/CustomerSearchRow'
              - $ref: '#/components/schemas/Customer'
            discriminator:
              propertyName: object
              mapping:
                CUSTOMER_SEARCH_ROW: '#/components/schemas/CustomerSearchRow'
                CUSTOMER: '#/components/schemas/Customer'
        pagination:
          $ref: '#/components/schemas/SearchPaginationInfo'
        totalResults:
          type: integer
          description: Total number of matching results (excluding soft-deleted records)
          minimum: 0
    CarrierSearchCriteria:
      type: object
      description: >
        Search criteria for filtering carriers.

        Note: Only active (non-deleted) carriers are searchable. Soft-deleted
        records are automatically excluded.
      properties:
        id:
          $ref: '#/components/schemas/UUIDSearchCriteria'
          description: >-
            Carrier ID (carrierProfileId for onboarded, goldenCarrierId
            otherwise)
        carrierProfileId:
          $ref: '#/components/schemas/UUIDSearchCriteria'
          description: Profile ID for onboarded carriers only
        goldenCarrierId:
          $ref: '#/components/schemas/UUIDSearchCriteria'
          description: Golden carrier ID from FMCSA data
        friendlyId:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Account ID for onboarded carriers
        name:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Carrier company name
        carrierStatus:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Status within the system (pending, active, inactive, doNotUse)
        type:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Carrier type (TL, LTL, LINEHAUL, CARTAGE, AIR, OCEAN, RAIL)
        city:
          $ref: '#/components/schemas/TextSearchCriteria'
        market:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: DAT market
        zone:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: DAT zone
        primaryContactName:
          $ref: '#/components/schemas/TextSearchCriteria'
        primaryContactPhone:
          $ref: '#/components/schemas/TextSearchCriteria'
        primaryContactEmail:
          $ref: '#/components/schemas/TextSearchCriteria'
        fmcsaStatus:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: FMCSA status (active, inactive)
        mcNumber:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Motor Carrier number
        dotNumber:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: DOT number
        einNumber:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Employer Identification Number
        safetyRating:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: FMCSA safety rating
        equipments:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: >-
            Equipment types (VAN, REEFER, FLATBED, POWER_ONLY, SPECIALIZED,
            CONTAINER, TANKER)
        powerUnits:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of power units
        trucks:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of trucks
        monthsActiveAuthority:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Months of active authority
        highwayId:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Highway ID
        highwayRulesAssessment:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Highway rules assessment
        rmisId:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: RMIS ID
        rmisOperatingStatus:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: RMIS operating status
        rmisInvitationStatus:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: RMIS invitation status (ERROR, INVITED, SUCCESS)
        mcpStatus:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: MyCarrierPortal invite status
        mcpReviewStatus:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: MyCarrierPortal review status (acceptable, moderate, unacceptable)
        quickbooksVendorId:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: QuickBooks Online vendor ID (internal field qboVendorId)
        factorBankNames:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Factoring company names
        paymentTermName:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Payment term
        quickPayFee:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Quick pay discount rate
        accountOwnerId:
          $ref: '#/components/schemas/UUIDSearchCriteria'
          description: Account owner user ID
        accountOwnerName:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Carrier owner name
        loadsCount:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of loads delivered
        totalMiles:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Total miles driven
        totalRevenue:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Total revenue generated
        totalCostOfGoodsSold:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Total COGS
        ratePerMile:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Average rate per mile
        quotesCount:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of quotes
        createdAt:
          $ref: '#/components/schemas/DatetimeSearchCriteria'
          description: Onboarding date
    CarrierSearchRequest:
      type: object
      description: Request body for searching carriers
      properties:
        criteria:
          $ref: '#/components/schemas/CarrierSearchCriteria'
          description: Search criteria to filter carriers
        pagination:
          $ref: '#/components/schemas/SearchPaginationInput'
        sort:
          type: array
          items:
            $ref: '#/components/schemas/SearchSortOption'
          maxItems: 3
          description: Sort options for the search results
        savedSearch:
          $ref: '#/components/schemas/SavedSearchLookup'
          description: >
            Optional saved search to load preferences from.

            When provided, the saved search criteria will be loaded and merged
            with any explicit criteria.
        format:
          type: string
          enum:
            - flat
            - full
          default: flat
          description: |
            Response format:
            - flat: Returns only indexed fields (default, faster)
            - full: Returns complete carrier objects
    CarrierSearchRow:
      type: object
      description: |
        Flattened carrier data from search index.
        Includes both ONBOARDED carriers and FMCSA records.
      properties:
        object:
          type: string
          enum:
            - CARRIER_SEARCH_ROW
          description: >-
            Object type identifier for discriminating between flat and full
            response formats
        id:
          type: string
          format: uuid
          description: >-
            Carrier ID (carrierProfileId if onboarded, goldenCarrierId
            otherwise)
        carrierProfileId:
          type:
            - string
            - 'null'
          format: uuid
          description: Profile ID (only for onboarded carriers)
        goldenCarrierId:
          type: string
          format: uuid
          description: Golden carrier ID from FMCSA
        friendlyId:
          type:
            - string
            - 'null'
          description: Account ID (only for onboarded carriers)
        name:
          type: string
          description: Carrier company name
        carrierStatus:
          type:
            - string
            - 'null'
          enum:
            - pending
            - active
            - inactive
            - doNotUse
          description: Status (only for onboarded carriers)
        type:
          type:
            - string
            - 'null'
          enum:
            - TL
            - LTL
            - LINEHAUL
            - CARTAGE
            - AIR
            - OCEAN
            - RAIL
        city:
          type:
            - string
            - 'null'
        market:
          type:
            - string
            - 'null'
          description: DAT market
        zone:
          type:
            - string
            - 'null'
          description: DAT zone
        primaryContactName:
          type:
            - string
            - 'null'
        primaryContactPhone:
          type:
            - string
            - 'null'
        primaryContactEmail:
          type:
            - string
            - 'null'
          format: email
        fmcsaStatus:
          type:
            - string
            - 'null'
          enum:
            - active
            - inactive
        mcNumber:
          type:
            - string
            - 'null'
        dotNumber:
          type:
            - string
            - 'null'
        einNumber:
          type:
            - string
            - 'null'
        safetyRating:
          type:
            - string
            - 'null'
        equipments:
          type: array
          items:
            type: string
            enum:
              - VAN
              - REEFER
              - FLATBED
              - POWER_ONLY
              - SPECIALIZED
              - CONTAINER
              - TANKER
          description: Equipment types available
        powerUnits:
          type:
            - integer
            - 'null'
        trucks:
          type:
            - integer
            - 'null'
        monthsActiveAuthority:
          type:
            - integer
            - 'null'
          description: Months of active authority
        highwayId:
          type:
            - string
            - 'null'
        highwayRulesAssessment:
          type:
            - string
            - 'null'
        rmisId:
          type:
            - string
            - 'null'
        rmisOperatingStatus:
          type:
            - string
            - 'null'
        rmisInvitationStatus:
          type:
            - string
            - 'null'
          enum:
            - ERROR
            - INVITED
            - SUCCESS
        mcpStatus:
          type:
            - string
            - 'null'
          enum:
            - complete
            - invited
            - notInvited
            - inProcess
            - incomplete
          description: MyCarrierPortal invite status
        mcpReviewStatus:
          type:
            - string
            - 'null'
          enum:
            - acceptable
            - moderate
            - unacceptable
          description: MyCarrierPortal review status
        quickbooksVendorId:
          type:
            - string
            - 'null'
          description: QuickBooks Online vendor ID
        factorBankNames:
          type: array
          items:
            type: string
          description: Factoring companies
        paymentTermName:
          type:
            - string
            - 'null'
        quickPayFee:
          type:
            - number
            - 'null'
          format: float
          description: Quick pay discount rate
        accountOwnerId:
          type:
            - string
            - 'null'
          format: uuid
        accountOwnerName:
          type:
            - string
            - 'null'
        loadsCount:
          type:
            - integer
            - 'null'
          description: Number of loads delivered
        totalMiles:
          type:
            - number
            - 'null'
          format: float
        totalRevenue:
          type:
            - number
            - 'null'
          format: float
        totalCostOfGoodsSold:
          type:
            - number
            - 'null'
          format: float
        ratePerMile:
          type:
            - number
            - 'null'
          format: float
          description: Average rate per mile
        quotesCount:
          type:
            - integer
            - 'null'
        createdAt:
          type:
            - string
            - 'null'
          format: date-time
          description: Onboarding date
      required:
        - object
        - id
        - goldenCarrierId
        - name
    CarrierSearchResponse:
      type: object
      description: |
        Response for carrier search requests.
        Note: Only active (non-deleted) carriers are included in results.
      required:
        - data
        - pagination
        - totalResults
      properties:
        data:
          type: array
          description: >-
            Search results - either flat rows or full carrier objects based on
            format parameter
          items:
            oneOf:
              - $ref: '#/components/schemas/CarrierSearchRow'
              - $ref: '#/components/schemas/Carrier'
            discriminator:
              propertyName: object
              mapping:
                CARRIER_SEARCH_ROW: '#/components/schemas/CarrierSearchRow'
                CARRIER: '#/components/schemas/Carrier'
        pagination:
          $ref: '#/components/schemas/SearchPaginationInfo'
        totalResults:
          type: integer
          description: Total number of matching results (excluding soft-deleted records)
          minimum: 0
    VendorSearchCriteria:
      type: object
      description: >
        Search criteria for filtering vendors.

        Note: Only active (non-deleted) vendors are searchable. Soft-deleted
        records are automatically excluded.
      properties:
        id:
          $ref: '#/components/schemas/UUIDSearchCriteria'
        friendlyId:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Vendor ID
        name:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Vendor name
        status:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Status (active, inactive, do_not_use)
        service:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Services provided by the vendor
        taxId:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: EIN or other tax ID
        location:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Computed field "city, state"
        city:
          $ref: '#/components/schemas/TextSearchCriteria'
        state:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        zip:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Postal code
        country:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        primaryContactName:
          $ref: '#/components/schemas/TextSearchCriteria'
        primaryContactEmail:
          $ref: '#/components/schemas/TextSearchCriteria'
        primaryContactPhone:
          $ref: '#/components/schemas/TextSearchCriteria'
        paymentTermName:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        quickbooksVendorId:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: QuickBooks Online vendor ID (internal field qboVendorId)
        numberOfTimesUsed:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of times vendor was used
        lastUsed:
          $ref: '#/components/schemas/DateSearchCriteria'
          description: Last date vendor was used
        createdAt:
          $ref: '#/components/schemas/DatetimeSearchCriteria'
    VendorSearchRequest:
      type: object
      description: Request body for searching vendors
      properties:
        criteria:
          $ref: '#/components/schemas/VendorSearchCriteria'
          description: Search criteria to filter vendors
        pagination:
          $ref: '#/components/schemas/SearchPaginationInput'
        sort:
          type: array
          items:
            $ref: '#/components/schemas/SearchSortOption'
          maxItems: 3
          description: Sort options for the search results
        savedSearch:
          $ref: '#/components/schemas/SavedSearchLookup'
          description: >
            Optional saved search to load preferences from.

            When provided, the saved search criteria will be loaded and merged
            with any explicit criteria.
        format:
          type: string
          enum:
            - flat
            - full
          default: flat
          description: |
            Response format:
            - flat: Returns only indexed fields (default, faster)
            - full: Returns complete vendor objects
    VendorSearchRow:
      type: object
      description: >
        Flattened vendor data from search index.

        Note: This represents only active vendors. Soft-deleted records are
        never returned.
      properties:
        object:
          type: string
          enum:
            - VENDOR_SEARCH_ROW
          description: >-
            Object type identifier for discriminating between flat and full
            response formats
        id:
          type: string
          format: uuid
        friendlyId:
          type: string
          description: Vendor ID
        name:
          type: string
        status:
          type:
            - string
            - 'null'
          enum:
            - active
            - inactive
            - do_not_use
        taxId:
          type:
            - string
            - 'null'
          description: EIN or other tax ID
        service:
          type: array
          items:
            type: string
          description: Services provided
        location:
          type:
            - string
            - 'null'
          description: Computed as "city, state"
        city:
          type:
            - string
            - 'null'
        state:
          type:
            - string
            - 'null'
        zip:
          type:
            - string
            - 'null'
          description: Postal code
        country:
          type:
            - string
            - 'null'
        primaryContactName:
          type:
            - string
            - 'null'
        primaryContactEmail:
          type:
            - string
            - 'null'
          format: email
        primaryContactPhone:
          type:
            - string
            - 'null'
        paymentTermName:
          type:
            - string
            - 'null'
        quickbooksVendorId:
          type:
            - string
            - 'null'
          description: QuickBooks Online vendor ID
        numberOfTimesUsed:
          type: integer
          description: Number of times used
        lastUsed:
          type:
            - string
            - 'null'
          format: date
          description: Last date used
        createdAt:
          type: string
          format: date-time
      required:
        - object
        - id
        - friendlyId
        - name
        - numberOfTimesUsed
        - createdAt
    VendorSearchResponse:
      type: object
      description: |
        Response for vendor search requests.
        Note: Only active (non-deleted) vendors are included in results.
      required:
        - data
        - pagination
        - totalResults
      properties:
        data:
          type: array
          description: >-
            Search results - either flat rows or full vendor objects based on
            format parameter
          items:
            oneOf:
              - $ref: '#/components/schemas/VendorSearchRow'
              - $ref: '#/components/schemas/Vendor'
            discriminator:
              propertyName: object
              mapping:
                VENDOR_SEARCH_ROW: '#/components/schemas/VendorSearchRow'
                VENDOR: '#/components/schemas/Vendor'
        pagination:
          $ref: '#/components/schemas/SearchPaginationInfo'
        totalResults:
          type: integer
          description: Total number of matching results (excluding soft-deleted records)
          minimum: 0
    UserSearchCriteria:
      type: object
      description: >
        Search criteria for filtering users.

        Note: Only active (non-deleted) users are searchable. Soft-deleted
        records are automatically excluded.
      properties:
        id:
          $ref: '#/components/schemas/UUIDSearchCriteria'
        name:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: User name
        email:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Email address
        emailVerified:
          $ref: '#/components/schemas/BooleanSearchCriteria'
          description: Whether email is verified
        phone:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Phone number
        status:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Status (pending, active, inactive)
        roles:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: User roles
        visibility:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Visibility level (ALL, LIMITED)
        teamIds:
          $ref: '#/components/schemas/UUIDSearchCriteria'
          description: Team IDs (internal field groupIds)
        teamNames:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Team names (internal field groupNames)
        customersCount:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of customers (internal field shippersCount)
        quotesCount:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of quotes
        quotesWon:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of quotes won
        quoteWinRate:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Quote win rate percentage
        ordersCount:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of shipments
        ordersTotalRevenue:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Total shipment revenue
        ordersTotalTransportationCost:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Total shipment transportation cost
        ordersTotalGrossProfit:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Total shipment gross profit
        averageGrossProfitPerOrder:
          $ref: '#/components/schemas/FloatSearchCriteria'
          description: Average gross profit per shipment
        carriersCount:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of carriers
        createdAt:
          $ref: '#/components/schemas/DatetimeSearchCriteria'
        lastInvitedAt:
          $ref: '#/components/schemas/DatetimeSearchCriteria'
          description: When the user was last invited
    UserSearchRequest:
      type: object
      description: Request body for searching users
      properties:
        criteria:
          $ref: '#/components/schemas/UserSearchCriteria'
          description: Search criteria to filter users
        pagination:
          $ref: '#/components/schemas/SearchPaginationInput'
        sort:
          type: array
          items:
            $ref: '#/components/schemas/SearchSortOption'
          maxItems: 3
          description: Sort options for the search results
        savedSearch:
          $ref: '#/components/schemas/SavedSearchLookup'
          description: >
            Optional saved search to load preferences from.

            When provided, the saved search criteria will be loaded and merged
            with any explicit criteria.
        format:
          type: string
          enum:
            - flat
            - full
          default: flat
          description: |
            Response format:
            - flat: Returns only indexed fields (default, faster)
            - full: Returns complete user objects
    UserSearchRow:
      type: object
      description: >
        Flattened user data from search index.

        Note: This represents only active users. Soft-deleted records are never
        returned.
      properties:
        object:
          type: string
          enum:
            - USER_SEARCH_ROW
          description: >-
            Object type identifier for discriminating between flat and full
            response formats
        id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type: string
          format: email
        emailVerified:
          type: boolean
          description: Whether email is verified
        phone:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - pending
            - active
            - inactive
        roles:
          type: array
          items:
            type: string
          description: User roles
        visibility:
          type:
            - string
            - 'null'
          enum:
            - ALL
            - LIMITED
        teamIds:
          type: array
          items:
            type: string
            format: uuid
          description: Team IDs (maps from groupIds)
        teamNames:
          type: array
          items:
            type: string
          description: Team names (maps from groupNames)
        customersCount:
          type: integer
          description: Number of customers (maps from shippersCount)
        quotesCount:
          type:
            - integer
            - 'null'
        quotesWon:
          type:
            - integer
            - 'null'
        quoteWinRate:
          type:
            - number
            - 'null'
          format: float
          description: Win rate percentage
        ordersCount:
          type: integer
          description: Number of shipments
        ordersTotalRevenue:
          type: number
          format: float
          description: Total shipment revenue
        ordersTotalTransportationCost:
          type: number
          format: float
          description: Total transportation cost
        ordersTotalGrossProfit:
          type: number
          format: float
          description: Total gross profit
        averageGrossProfitPerOrder:
          type:
            - number
            - 'null'
          format: float
          description: Average gross profit per shipment
        carriersCount:
          type: integer
          description: Number of carriers
        createdAt:
          type: string
          format: date-time
        lastInvitedAt:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - object
        - id
        - name
        - email
        - emailVerified
        - status
        - customersCount
        - ordersCount
        - ordersTotalRevenue
        - ordersTotalTransportationCost
        - ordersTotalGrossProfit
        - carriersCount
        - createdAt
    UserSearchResponse:
      type: object
      description: |
        Response for user search requests.
        Note: Only active (non-deleted) users are included in results.
      required:
        - data
        - pagination
        - totalResults
      properties:
        data:
          type: array
          description: >-
            Search results - either flat rows or full user objects based on
            format parameter
          items:
            oneOf:
              - $ref: '#/components/schemas/UserSearchRow'
              - $ref: '#/components/schemas/User'
            discriminator:
              propertyName: object
              mapping:
                USER_SEARCH_ROW: '#/components/schemas/UserSearchRow'
                USER: '#/components/schemas/User'
        pagination:
          $ref: '#/components/schemas/SearchPaginationInfo'
        totalResults:
          type: integer
          description: Total number of matching results (excluding soft-deleted records)
          minimum: 0
    LocationSearchCriteria:
      type: object
      description: >
        Search criteria for filtering locations (shipper/receiver locations).

        Note: Only active (non-deleted) locations are searchable. Soft-deleted
        records are automatically excluded.
      properties:
        id:
          $ref: '#/components/schemas/UUIDSearchCriteria'
        customerId:
          $ref: '#/components/schemas/UUIDSearchCriteria'
          description: Customer ID (internal field shipperProfileId)
        customerName:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Customer name (internal field shipperProfileName)
        customerFriendlyId:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Customer company ID (internal field shipperProfileFriendlyId)
        type:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: Location type (SHIPPER, RECEIVER, BOTH)
        name:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Location name
        externalId:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: External reference ID
        line1:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Address line 1
        line2:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Address line 2
        city:
          $ref: '#/components/schemas/TextSearchCriteria'
        state:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        postalCode:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        country:
          $ref: '#/components/schemas/KeywordSearchCriteria'
        market:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: DAT market
        zone:
          $ref: '#/components/schemas/KeywordSearchCriteria'
          description: DAT zone
        phoneNumber:
          $ref: '#/components/schemas/TextSearchCriteria'
          description: Primary contact phone
        appointmentRequired:
          $ref: '#/components/schemas/BooleanSearchCriteria'
          description: Whether appointments are required (internal field apptReq)
        stopsCount:
          $ref: '#/components/schemas/IntSearchCriteria'
          description: Number of stops at this location
        createdAt:
          $ref: '#/components/schemas/DatetimeSearchCriteria'
    LocationSearchRequest:
      type: object
      description: Request body for searching locations
      properties:
        criteria:
          $ref: '#/components/schemas/LocationSearchCriteria'
          description: Search criteria to filter locations
        pagination:
          $ref: '#/components/schemas/SearchPaginationInput'
        sort:
          type: array
          items:
            $ref: '#/components/schemas/SearchSortOption'
          maxItems: 3
          description: Sort options for the search results
        savedSearch:
          $ref: '#/components/schemas/SavedSearchLookup'
          description: >
            Optional saved search to load preferences from.

            When provided, the saved search criteria will be loaded and merged
            with any explicit criteria.
        format:
          type: string
          enum:
            - flat
            - full
          default: flat
          description: |
            Response format:
            - flat: Returns only indexed fields (default, faster)
            - full: Returns complete location objects
    LocationSearchRow:
      type: object
      description: >
        Flattened location data from search index.

        Note: This represents only active locations. Soft-deleted records are
        never returned.
      properties:
        object:
          type: string
          enum:
            - LOCATION_SEARCH_ROW
          description: >-
            Object type identifier for discriminating between flat and full
            response formats
        id:
          type: string
          format: uuid
        customerId:
          type: string
          format: uuid
          description: Customer ID (maps from shipperProfileId)
        customerName:
          type: string
          description: Customer name (maps from shipperProfileName)
        customerFriendlyId:
          type: string
          description: Customer company ID (maps from shipperProfileFriendlyId)
        type:
          type: string
          enum:
            - SHIPPER
            - RECEIVER
            - BOTH
          description: Location type
        name:
          type: string
          description: Location name
        externalId:
          type:
            - string
            - 'null'
          description: External reference ID
        line1:
          type:
            - string
            - 'null'
        line2:
          type:
            - string
            - 'null'
        city:
          type:
            - string
            - 'null'
        state:
          type:
            - string
            - 'null'
        postalCode:
          type:
            - string
            - 'null'
        country:
          type:
            - string
            - 'null'
        market:
          type:
            - string
            - 'null'
          description: DAT market
        zone:
          type:
            - string
            - 'null'
          description: DAT zone
        point:
          type:
            - object
            - 'null'
          properties:
            lat:
              type: number
              format: float
            lon:
              type: number
              format: float
          description: Geographic coordinates
        phoneNumber:
          type:
            - string
            - 'null'
          description: Primary contact phone
        appointmentRequired:
          type:
            - boolean
            - 'null'
          description: Whether appointments are required (maps from apptReq)
        stopsCount:
          type:
            - integer
            - 'null'
          description: Number of stops
        createdAt:
          type: string
          format: date-time
      required:
        - object
        - id
        - customerId
        - customerName
        - name
        - createdAt
    LocationSearchResponse:
      type: object
      description: |
        Response for location search requests.
        Note: Only active (non-deleted) locations are included in results.
      required:
        - data
        - pagination
        - totalResults
      properties:
        data:
          type: array
          description: >-
            Search results - either flat rows or full location objects based on
            format parameter
          items:
            oneOf:
              - $ref: '#/components/schemas/LocationSearchRow'
              - $ref: '#/components/schemas/Location'
            discriminator:
              propertyName: object
              mapping:
                LOCATION_SEARCH_ROW: '#/components/schemas/LocationSearchRow'
                LOCATION: '#/components/schemas/Location'
        pagination:
          $ref: '#/components/schemas/SearchPaginationInfo'
        totalResults:
          type: integer
          description: Total number of matching results (excluding soft-deleted records)
          minimum: 0
    GlobalSearchObjectType:
      type: string
      enum:
        - SHIPMENT
        - CUSTOMER
        - CARRIER
        - USER
        - VENDOR
      description: |
        Object types available for global search:
        - `SHIPMENT`: Shipment records
        - `CUSTOMER`: Customer/shipper profiles
        - `CARRIER`: Carrier profiles
        - `USER`: User accounts
        - `VENDOR`: Vendor profiles
    GlobalSearchRequest:
      type: object
      description: Request body for global search across multiple entity types
      required:
        - query
      properties:
        query:
          type: string
          description: >
            Search query string. Searches across default searchable fields for
            each entity type.


            Supports prefix filtering using "type:query" syntax:

            - `carrier:acme` - searches only carriers for "acme"

            - `shipment:12345` - searches only shipments for "12345"

            - `user:john` - searches only users for "john"
          example: acme corp
        objects:
          type: array
          items:
            $ref: '#/components/schemas/GlobalSearchObjectType'
          description: |
            Optional filter to limit search to specific object types.
            If not provided, searches across all object types.
          example:
            - SHIPMENT
            - CUSTOMER
        pagination:
          $ref: '#/components/schemas/SearchPaginationInput'
    GlobalSearchRow:
      type: object
      description: >
        A single global search result row.

        Results are sorted by object type priority: SHIPMENT, CUSTOMER, CARRIER,
        USER, VENDOR.
      required:
        - object
        - id
        - entityName
        - title
        - field
      properties:
        object:
          $ref: '#/components/schemas/GlobalSearchObjectType'
          description: The type of object this result represents
        id:
          type: string
          format: uuid
          description: Unique identifier of the matched record
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier if set
          example: ERP-CUST-12345
        entityName:
          type: string
          description: |
            Internal entity type name (for backwards compatibility).
            Prefer using the `object` field instead.
          example: SHIPPER_PROFILE
        title:
          type: string
          description: Primary display text for the result (e.g., name, friendlyId)
          example: Acme Corporation
        subtitle:
          type:
            - string
            - 'null'
          description: Secondary display text (varies by entity type)
          example: CUST-12345
        field:
          type: string
          description: Name of the field that matched the search query
          example: Name
        highlight:
          type:
            - string
            - 'null'
          description: |
            Matched text with highlight markers.
            Contains HTML &lt;em&gt; tags around matched portions.
          example: <em>Acme</em> Corporation
    GlobalSearchResponse:
      type: object
      description: Response for global search requests
      required:
        - data
        - pagination
        - totalResults
      properties:
        data:
          type: array
          description: |
            Search results sorted by object type priority:
            SHIPMENT → CUSTOMER → CARRIER → USER → VENDOR
          items:
            $ref: '#/components/schemas/GlobalSearchRow'
        pagination:
          $ref: '#/components/schemas/SearchPaginationInfo'
        totalResults:
          type: integer
          description: Total number of matching results across all object types
          minimum: 0
          example: 42
    SavedSearchLookup:
      type: object
      description: |
        Reference to a saved search by ID or client key.
        Provide either id or key (not both).
      properties:
        id:
          type: string
          format: uuid
          description: Saved search UUID
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type: string
          maxLength: 512
          description: Client-defined key for the saved search
          example: my-carrier-search
      example:
        id: 550e8400-e29b-41d4-a716-446655440000
    UUIDFilter:
      type: object
      description: Filter options for UUID fields (all operations)
      properties:
        equalTo:
          type: string
          format: uuid
          description: Exact match
        notEqualTo:
          type: string
          format: uuid
          description: Not equal to
        in:
          type: array
          items:
            type: string
            format: uuid
          description: Matches any UUID in the array
        notIn:
          type: array
          items:
            type: string
            format: uuid
          description: Does not match any UUID in the array
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error message
    ValidationError:
      type: object
      required:
        - error
        - message
        - details
      properties:
        error:
          type: string
          description: Error code
          example: validation_error
        message:
          type: string
          description: Human-readable error message
        details:
          type: array
          description: Validation error details
          items:
            type: object
            required:
              - field
              - message
            properties:
              field:
                type: string
                description: Field name that failed validation
              message:
                type: string
                description: Validation error message
    WebhookEvent:
      type: string
      description: The type of webhook event
      enum:
        - CARRIER_ACTIVATED
        - CARRIER_CONTACT_CREATED
        - CARRIER_CONTACT_UPDATED
        - CARRIER_CONTACT_DELETED
        - CARRIER_CREATED
        - CARRIER_DEACTIVATED
        - CARRIER_DELETED
        - CARRIER_FACTOR_CREATED
        - CARRIER_FACTOR_UPDATED
        - CARRIER_FACTOR_DELETED
        - CARRIER_INVOICE_CREATED
        - CARRIER_PAYMENT_CREATED
        - CARRIER_PAYMENT_METHOD_CREATED
        - CARRIER_PAYMENT_METHOD_UPDATED
        - CARRIER_PAYMENT_METHOD_DELETED
        - CARRIER_UPDATED
        - COMMISSION_APPROVED
        - COMMISSION_CREATED
        - COMPANY_CREATED
        - COMPANY_UPDATED
        - COMPANY_DELETED
        - CUSTOMER_CREATED
        - CUSTOMER_UPDATED
        - CUSTOMER_DELETED
        - CUSTOMER_CONTACT_CREATED
        - CUSTOMER_CONTACT_UPDATED
        - CUSTOMER_CONTACT_DELETED
        - CUSTOMER_INVOICE_CREATED
        - CUSTOMER_PAYMENT_CREATED
        - DOCUMENT_UPLOADED
        - QUOTE_CREATED
        - QUOTE_LOST
        - QUOTE_QUOTED
        - QUOTE_REQUESTED
        - QUOTE_WON
        - SHIPMENT_BOOKED
        - SHIPMENT_CANCELED
        - SHIPMENT_CHECK_CALL
        - SHIPMENT_CREATED
        - SHIPMENT_DELETED
        - SHIPMENT_DELIVERED
        - SHIPMENT_DISPATCHED
        - SHIPMENT_DRAFT
        - SHIPMENT_IN_TRANSIT
        - SHIPMENT_LOADING
        - SHIPMENT_NEXT_CHECK_CALL_DUE
        - SHIPMENT_NEXT_CHECK_CALL_OVERDUE
        - SHIPMENT_OPEN
        - SHIPMENT_PICK_UP_NEAR_NOT_BOOKED
        - SHIPMENT_PICK_UP_NEAR_NOT_DISPATCHED
        - SHIPMENT_RATE_CON_EXPIRED
        - SHIPMENT_RATE_CON_NOT_SIGNED
        - SHIPMENT_RATE_CON_SIGNED
        - SHIPMENT_TENDER_PENDING
        - SHIPMENT_TENDER_REJECTED
        - SHIPMENT_UNLOADING
        - VENDOR_CREATED
        - VENDOR_UPDATED
        - VENDOR_DELETED
        - VENDOR_CONTACT_CREATED
        - VENDOR_CONTACT_UPDATED
        - VENDOR_CONTACT_DELETED
        - VENDOR_INVOICE_CREATED
        - VENDOR_PAYMENT_CREATED
        - VENDOR_PAYMENT_METHOD_CREATED
        - VENDOR_PAYMENT_METHOD_UPDATED
        - VENDOR_PAYMENT_METHOD_DELETED
        - LOCATION_CREATED
        - LOCATION_UPDATED
        - LOCATION_DELETED
        - LOCATION_CONTACT_CREATED
        - LOCATION_CONTACT_UPDATED
        - LOCATION_CONTACT_DELETED
    WebhookPayload:
      type: object
      required:
        - event
        - timestamp
        - data
      discriminator:
        propertyName: event
        mapping:
          CUSTOMER_CREATED: '#/components/schemas/CustomerChangedPayload'
          CUSTOMER_UPDATED: '#/components/schemas/CustomerChangedPayload'
          CUSTOMER_DELETED: '#/components/schemas/CustomerChangedPayload'
          COMPANY_CREATED: '#/components/schemas/CompanyChangedPayload'
          COMPANY_UPDATED: '#/components/schemas/CompanyChangedPayload'
          COMPANY_DELETED: '#/components/schemas/CompanyChangedPayload'
          CUSTOMER_CONTACT_CREATED: '#/components/schemas/CustomerContactChangedPayload'
          CUSTOMER_CONTACT_UPDATED: '#/components/schemas/CustomerContactChangedPayload'
          CUSTOMER_CONTACT_DELETED: '#/components/schemas/CustomerContactChangedPayload'
          CARRIER_CONTACT_CREATED: '#/components/schemas/CarrierContactChangedPayload'
          CARRIER_CONTACT_UPDATED: '#/components/schemas/CarrierContactChangedPayload'
          CARRIER_CONTACT_DELETED: '#/components/schemas/CarrierContactChangedPayload'
          CARRIER_CREATED: '#/components/schemas/CarrierChangedPayload'
          CARRIER_UPDATED: '#/components/schemas/CarrierChangedPayload'
          CARRIER_DELETED: '#/components/schemas/CarrierChangedPayload'
          CARRIER_ACTIVATED: '#/components/schemas/CarrierChangedPayload'
          CARRIER_DEACTIVATED: '#/components/schemas/CarrierChangedPayload'
          CARRIER_FACTOR_CREATED: '#/components/schemas/CarrierFactorChangedPayload'
          CARRIER_FACTOR_UPDATED: '#/components/schemas/CarrierFactorChangedPayload'
          CARRIER_FACTOR_DELETED: '#/components/schemas/CarrierFactorChangedPayload'
          CARRIER_PAYMENT_METHOD_CREATED: '#/components/schemas/CarrierPaymentMethodChangedPayload'
          CARRIER_PAYMENT_METHOD_UPDATED: '#/components/schemas/CarrierPaymentMethodChangedPayload'
          CARRIER_PAYMENT_METHOD_DELETED: '#/components/schemas/CarrierPaymentMethodChangedPayload'
          VENDOR_CREATED: '#/components/schemas/VendorChangedPayload'
          VENDOR_UPDATED: '#/components/schemas/VendorChangedPayload'
          VENDOR_DELETED: '#/components/schemas/VendorChangedPayload'
          VENDOR_CONTACT_CREATED: '#/components/schemas/VendorContactChangedPayload'
          VENDOR_CONTACT_UPDATED: '#/components/schemas/VendorContactChangedPayload'
          VENDOR_CONTACT_DELETED: '#/components/schemas/VendorContactChangedPayload'
          VENDOR_PAYMENT_METHOD_CREATED: '#/components/schemas/VendorPaymentMethodChangedPayload'
          VENDOR_PAYMENT_METHOD_UPDATED: '#/components/schemas/VendorPaymentMethodChangedPayload'
          VENDOR_PAYMENT_METHOD_DELETED: '#/components/schemas/VendorPaymentMethodChangedPayload'
          LOCATION_CREATED: '#/components/schemas/LocationChangedPayload'
          LOCATION_UPDATED: '#/components/schemas/LocationChangedPayload'
          LOCATION_DELETED: '#/components/schemas/LocationChangedPayload'
          LOCATION_CONTACT_CREATED: '#/components/schemas/LocationContactChangedPayload'
          LOCATION_CONTACT_UPDATED: '#/components/schemas/LocationContactChangedPayload'
          LOCATION_CONTACT_DELETED: '#/components/schemas/LocationContactChangedPayload'
          SHIPMENT_DELIVERED: '#/components/schemas/ShipmentDeliveredPayload'
      properties:
        event:
          $ref: '#/components/schemas/WebhookEvent'
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the event occurred
          example: '2025-01-15T14:30:00Z'
        data:
          type: object
          description: Event-specific data. Structure varies by event type.
          additionalProperties: true
        diff:
          type:
            - array
            - 'null'
          description: |
            Array of changes made during an UPDATE operation using json-diff-ts.
            Only present for UPDATE events. Null for CREATE and DELETE events.
            Each change follows the IChange interface from json-diff-ts library.
          items:
            $ref: '#/components/schemas/DiffChange'
    CustomerChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - CUSTOMER_CREATED
                - CUSTOMER_UPDATED
                - CUSTOMER_DELETED
            data:
              $ref: '#/components/schemas/Customer'
    CompanyChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - COMPANY_CREATED
                - COMPANY_UPDATED
                - COMPANY_DELETED
            data:
              $ref: '#/components/schemas/Company'
    CustomerContactChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - CUSTOMER_CONTACT_CREATED
                - CUSTOMER_CONTACT_UPDATED
                - CUSTOMER_CONTACT_DELETED
            data:
              $ref: '#/components/schemas/CustomerContact'
    CarrierChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - CARRIER_CREATED
                - CARRIER_UPDATED
                - CARRIER_DELETED
            data:
              $ref: '#/components/schemas/Carrier'
    VendorChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - VENDOR_CREATED
                - VENDOR_UPDATED
                - VENDOR_DELETED
            data:
              $ref: '#/components/schemas/Vendor'
    VendorContactChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - VENDOR_CONTACT_CREATED
                - VENDOR_CONTACT_UPDATED
                - VENDOR_CONTACT_DELETED
            data:
              $ref: '#/components/schemas/VendorContact'
    ShipmentDeliveredPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - SHIPMENT_DELIVERED
            data:
              type: object
              required:
                - id
                - friendlyId
              properties:
                id:
                  type: string
                  format: uuid
                  description: Shipment UUID
                  example: 660e8400-e29b-41d4-a716-446655440000
                friendlyId:
                  type: string
                  description: Human-readable shipment ID
                  example: SHP-12345
                key:
                  type:
                    - string
                    - 'null'
                  description: Your system's reference ID for this shipment (if set)
                  example: ERP-SHIP-789
    CarrierPaymentMethodReference:
      type: object
      description: >
        Carrier payment method reference for embedding in Carrier responses.

        Identical to CarrierPaymentMethod but excludes the carrier and carrierId
        fields to avoid circular references.
      required:
        - id
        - paymentRecipientType
        - paymentMethodType
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique carrier payment method identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: CARRIER-PM-001
        paymentRecipientType:
          $ref: '#/components/schemas/PaymentRecipientType'
          description: Who receives the payment (DIRECT or FACTOR)
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType'
          description: How payment is made
        status:
          type:
            - string
            - 'null'
          description: Payment method status
          example: ACTIVE
        isPreferred:
          type:
            - boolean
            - 'null'
          description: Whether this is the preferred payment method
          example: true
        email:
          type:
            - string
            - 'null'
          format: email
          description: Email address for payment notifications
          example: payments@carrier.com
        phone:
          type:
            - string
            - 'null'
          description: Phone number for payment contact
          example: +1-555-123-4567
        companyName:
          type:
            - string
            - 'null'
          description: Company name for this payment method
          example: Carrier Payments LLC
        username:
          type:
            - string
            - 'null'
          description: Username for payment platforms
          example: carrier_payments
        bankName:
          type:
            - string
            - 'null'
          description: Bank name
          example: Chase Bank
        bankAddress:
          type:
            - string
            - 'null'
          description: Bank address
          example: 123 Bank Street, Dallas, TX 75201
        accountName:
          type:
            - string
            - 'null'
          description: Bank account holder name
          example: Carrier Transport Inc
        accountNumber:
          type:
            - string
            - 'null'
          description: Bank account number (masked in responses)
          example: '****1234'
        abaAch:
          type:
            - string
            - 'null'
          description: ABA/ACH routing number
          example: '021000021'
        wire:
          type:
            - string
            - 'null'
          description: Wire transfer routing number
          example: '026009593'
        swiftCode:
          type:
            - string
            - 'null'
          description: SWIFT/BIC code
          example: CHASUS33
        eftInstitution:
          type:
            - string
            - 'null'
          description: EFT institution number (Canadian banking)
          example: '001'
        eftTransit:
          type:
            - string
            - 'null'
          description: EFT transit number (Canadian banking)
          example: '00010'
        clabe:
          type:
            - string
            - 'null'
          description: CLABE number (Mexican banking)
          example: '012180001234567897'
        currency:
          type:
            - string
            - 'null'
          description: Preferred currency code
          example: USD
        carrierFactor:
          anyOf:
            - $ref: '#/components/schemas/CarrierFactorReference'
            - type: 'null'
          description: Factoring company reference (when paymentRecipientType is FACTOR)
        paymentTerm:
          anyOf:
            - $ref: '#/components/schemas/PaymentTermReference'
            - type: 'null'
          description: Payment terms
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment method was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment method was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: When the payment method was soft deleted
          example: null
        deletedBy:
          anyOf:
            - $ref: '#/components/schemas/UserReference'
            - type: 'null'
          readOnly: true
          description: User who deleted this payment method
    CarrierContactReference:
      type: object
      description: >
        Carrier contact reference for embedding in Carrier responses.

        Identical to CarrierContact but excludes the carrier and carrierId
        fields to avoid circular references.
      required:
        - id
        - name
        - contactInfo
        - createdAt
      properties:
        object:
          type: string
          enum:
            - CARRIER_CONTACT
          readOnly: true
          description: Object type identifier
          example: CARRIER_CONTACT
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique contact identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CARRIER-CONTACT-001
        name:
          type: string
          description: Contact person's name
          example: Jane Dispatcher
        contactInfo:
          allOf:
            - $ref: '#/components/schemas/ContactInfo'
          description: Contact information details (email, phone, title)
        contactTypes:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/CarrierContactType'
          description: Types/roles this contact serves
          example:
            - DISPATCH
            - AFTER_HOURS
        invitedUser:
          anyOf:
            - $ref: '#/components/schemas/UserReference'
            - type: 'null'
          readOnly: true
          description: User account invited/created for this contact
        deletedBy:
          anyOf:
            - $ref: '#/components/schemas/UserReference'
            - type: 'null'
          readOnly: true
          description: User who deleted this contact
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the contact was created
          example: '2025-01-15T10:00:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: When the contact was soft deleted
          example: null
    UUIDSearchCriteria:
      type: object
      required:
        - operator
      description: Search criteria for UUID fields
      properties:
        operator:
          type: string
          enum:
            - EQUALS
            - NOT_EQUALS
            - ONE_OF
            - NOT_ONE_OF
            - EXISTS
            - DOES_NOT_EXIST
          description: |
            Search operator:
            - `EQUALS`: Exact match
            - `NOT_EQUALS`: Not equal to
            - `ONE_OF`: Matches any UUID in array
            - `NOT_ONE_OF`: Does not match any UUID in array
            - `EXISTS`: Field has a value (not null)
            - `DOES_NOT_EXIST`: Field is null
        values:
          type: array
          items:
            type: string
            format: uuid
          description: Array of UUIDs for ONE_OF or NOT_ONE_OF operators
          example:
            - 550e8400-e29b-41d4-a716-446655440000
            - 550e8400-e29b-41d4-a716-446655440001
      example:
        operator: EQUALS
        values:
          - 550e8400-e29b-41d4-a716-446655440000
    KeywordSearchCriteria:
      type: object
      required:
        - operator
      description: Search criteria for keyword fields (exact match, no partial matching)
      properties:
        operator:
          type: string
          enum:
            - EQUALS
            - NOT_EQUALS
            - ONE_OF
            - NOT_ONE_OF
            - EXISTS
            - DOES_NOT_EXIST
          description: |
            Search operator:
            - `EQUALS`: Exact match
            - `NOT_EQUALS`: Not equal to
            - `ONE_OF`: Matches any value in array
            - `NOT_ONE_OF`: Does not match any value in array
            - `EXISTS`: Field has a value (not null)
            - `DOES_NOT_EXIST`: Field is null
        values:
          type: array
          items:
            type: string
          description: Array of values for ONE_OF or NOT_ONE_OF operators
          example:
            - ACTIVE
            - PENDING
      example:
        operator: ONE_OF
        values:
          - ACTIVE
          - PENDING
    TextSearchCriteria:
      type: object
      required:
        - operator
      description: >-
        Search criteria for text fields (supports wildcards and partial
        matching)
      properties:
        operator:
          type: string
          enum:
            - EQUALS
            - NOT_EQUALS
            - STARTS_WITH
            - ENDS_WITH
            - INCLUDES
            - ONE_OF
            - NOT_ONE_OF
            - EXISTS
            - DOES_NOT_EXIST
          description: |
            Search operator:
            - `EQUALS`: Exact match
            - `NOT_EQUALS`: Not equal to
            - `STARTS_WITH`: Begins with prefix
            - `ENDS_WITH`: Ends with suffix
            - `INCLUDES`: Contains substring
            - `ONE_OF`: Matches any value in array
            - `NOT_ONE_OF`: Does not match any value in array
            - `EXISTS`: Field has a value (not null)
            - `DOES_NOT_EXIST`: Field is null
        values:
          type: array
          items:
            type: string
          description: Array of values for ONE_OF or NOT_ONE_OF operators
          example:
            - value1
            - value2
      example:
        operator: INCLUDES
        values:
          - search term
    IntSearchCriteria:
      type: object
      required:
        - operator
      description: Search criteria for integer fields
      properties:
        operator:
          type: string
          enum:
            - EQUALS
            - NOT_EQUALS
            - GREATER_THAN
            - LESS_THAN
            - BETWEEN
            - NOT_BETWEEN
            - EXISTS
            - DOES_NOT_EXIST
          description: |
            Search operator:
            - `EQUALS`: Exact match
            - `NOT_EQUALS`: Not equal to
            - `GREATER_THAN`: Greater than value
            - `LESS_THAN`: Less than value
            - `BETWEEN`: Between min and max (inclusive)
            - `NOT_BETWEEN`: Not between min and max
            - `EXISTS`: Field has a value (not null)
            - `DOES_NOT_EXIST`: Field is null
        value:
          type: integer
          description: Single value for EQUALS, NOT_EQUALS, GREATER_THAN, LESS_THAN
        min:
          type: integer
          description: Minimum value for BETWEEN or NOT_BETWEEN
        max:
          type: integer
          description: Maximum value for BETWEEN or NOT_BETWEEN
      example:
        operator: BETWEEN
        min: 10
        max: 100
    FloatSearchCriteria:
      type: object
      required:
        - operator
      description: Search criteria for float/decimal fields
      properties:
        operator:
          type: string
          enum:
            - EQUALS
            - NOT_EQUALS
            - GREATER_THAN
            - LESS_THAN
            - BETWEEN
            - NOT_BETWEEN
            - EXISTS
            - DOES_NOT_EXIST
          description: |
            Search operator:
            - `EQUALS`: Exact match
            - `NOT_EQUALS`: Not equal to
            - `GREATER_THAN`: Greater than value
            - `LESS_THAN`: Less than value
            - `BETWEEN`: Between min and max (inclusive)
            - `NOT_BETWEEN`: Not between min and max
            - `EXISTS`: Field has a value (not null)
            - `DOES_NOT_EXIST`: Field is null
        value:
          type: number
          format: float
          description: Single value for EQUALS, NOT_EQUALS, GREATER_THAN, LESS_THAN
        min:
          type: number
          format: float
          description: Minimum value for BETWEEN or NOT_BETWEEN
        max:
          type: number
          format: float
          description: Maximum value for BETWEEN or NOT_BETWEEN
      example:
        operator: GREATER_THAN
        value: 1000.5
    RelativeTimeUnit:
      type: string
      enum:
        - YEAR
        - MONTH
        - WEEK
        - DAY
        - HOUR
        - MINUTE
        - SECOND
      description: |
        Time unit for relative time calculations:
        - `YEAR`: Years
        - `MONTH`: Months
        - `WEEK`: Weeks
        - `DAY`: Days
        - `HOUR`: Hours
        - `MINUTE`: Minutes
        - `SECOND`: Seconds
    DatetimeSearchCriteria:
      type: object
      required:
        - operator
      description: |
        Search criteria for datetime fields.
        Supports both absolute datetime values and relative time expressions.
      properties:
        operator:
          type: string
          enum:
            - EQUALS
            - NOT_EQUALS
            - BEFORE
            - AFTER
            - BETWEEN
            - NOT_BETWEEN
            - EXISTS
            - DOES_NOT_EXIST
          description: |
            Search operator:
            - `EQUALS`: Exact match
            - `NOT_EQUALS`: Not equal to
            - `BEFORE`: Before datetime
            - `AFTER`: After datetime
            - `BETWEEN`: Between min and max (inclusive)
            - `NOT_BETWEEN`: Not between min and max
            - `EXISTS`: Field has a value (not null)
            - `DOES_NOT_EXIST`: Field is null
        value:
          type: string
          format: date-time
          description: Absolute datetime for EQUALS, NOT_EQUALS
          example: '2025-01-15T10:00:00Z'
        min:
          type: string
          format: date-time
          description: Minimum datetime for BETWEEN or NOT_BETWEEN
          example: '2025-01-01T00:00:00Z'
        max:
          type: string
          format: date-time
          description: Maximum datetime for BETWEEN or NOT_BETWEEN
          example: '2025-12-31T23:59:59Z'
        valueRelative:
          type: integer
          description: |
            Relative time from now (negative for past, positive for future).
            Example: -7 with WEEK unit means 7 weeks ago.
        valueRelativeUnit:
          $ref: '#/components/schemas/RelativeTimeUnit'
        minRelative:
          type: integer
          description: Relative time for min boundary
        minRelativeUnit:
          $ref: '#/components/schemas/RelativeTimeUnit'
        maxRelative:
          type: integer
          description: Relative time for max boundary
        maxRelativeUnit:
          $ref: '#/components/schemas/RelativeTimeUnit'
      example:
        operator: AFTER
        value: '2025-01-01T00:00:00Z'
    SearchPaginationInput:
      type: object
      description: Pagination options for search requests
      properties:
        pageNumber:
          type: integer
          minimum: 1
          default: 1
          description: Page number (1-based)
          example: 1
        pageSize:
          type: integer
          minimum: 1
          maximum: 250
          default: 50
          description: Number of results per page (max 250)
          example: 50
      example:
        pageNumber: 1
        pageSize: 50
    SearchSortOption:
      type: object
      required:
        - field
        - order
      description: Sort option for search results
      properties:
        field:
          type: string
          description: Field name to sort by (must be an indexed field)
          example: createdAt
        order:
          type: string
          enum:
            - asc
            - desc
          description: Sort direction (ascending or descending)
          example: desc
      example:
        field: createdAt
        order: desc
    SearchPaginationInfo:
      type: object
      required:
        - pageNumber
        - pageSize
        - totalPages
      description: Pagination information for search results
      properties:
        pageNumber:
          type: integer
          description: Current page number
          example: 1
        pageSize:
          type: integer
          description: Number of results returned on this page
          example: 50
        totalPages:
          type: integer
          description: Total number of pages available
          example: 25
      example:
        pageNumber: 1
        pageSize: 50
        totalPages: 25
    CustomerContactReference:
      type: object
      description: >
        Customer contact reference for embedding in Customer responses.

        Identical to CustomerContact but excludes the customer and customerId
        fields to avoid circular references.
      required:
        - id
        - name
        - isPrimary
        - contactInfo
        - createdAt
      properties:
        object:
          type: string
          enum:
            - CUSTOMER_CONTACT
          readOnly: true
          description: Object type identifier
          example: CUSTOMER_CONTACT
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique contact identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-CONTACT-JOHN-001
        name:
          type: string
          description: Contact person's name
          example: John Smith
        contactInfo:
          allOf:
            - $ref: '#/components/schemas/ContactInfo'
          description: Contact information details (email, phone, title)
        phoneExtension:
          type:
            - string
            - 'null'
          description: Phone extension specific to this contact role
          example: '1234'
        isPrimary:
          type: boolean
          description: Whether this is the primary contact
          example: true
        contactTypes:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/CustomerContactType'
          description: Types/roles this contact serves
          example:
            - BILLING
            - ACCOUNT_MANAGER
        notifications:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/CustomerContactNotificationType'
          description: Shipment notification types
          example:
            - SHIPMENT_PICKED_UP
            - SHIPMENT_DELIVERED
        invitedUser:
          anyOf:
            - $ref: '#/components/schemas/UserReference'
            - type: 'null'
          readOnly: true
          description: User account invited/created for this contact
        deletedBy:
          anyOf:
            - $ref: '#/components/schemas/UserReference'
            - type: 'null'
          readOnly: true
          description: User who deleted this contact
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the contact was created
          example: '2025-01-15T10:00:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: When the contact was soft deleted
          example: null
    DateSearchCriteria:
      type: object
      required:
        - operator
      description: |
        Search criteria for date fields (no time component).
        Supports both absolute date values and relative time expressions.
      properties:
        operator:
          type: string
          enum:
            - EQUALS
            - NOT_EQUALS
            - BEFORE
            - AFTER
            - BETWEEN
            - NOT_BETWEEN
            - EXISTS
            - DOES_NOT_EXIST
          description: Search operator (same as DatetimeSearchCriteria)
        value:
          type: string
          format: date
          description: Absolute date for EQUALS, NOT_EQUALS
          example: '2025-01-15'
        min:
          type: string
          format: date
          description: Minimum date for BETWEEN or NOT_BETWEEN
          example: '2025-01-01'
        max:
          type: string
          format: date
          description: Maximum date for BETWEEN or NOT_BETWEEN
          example: '2025-12-31'
        valueRelative:
          type: integer
          description: Relative time from now
        valueRelativeUnit:
          $ref: '#/components/schemas/RelativeTimeUnit'
        minRelative:
          type: integer
        minRelativeUnit:
          $ref: '#/components/schemas/RelativeTimeUnit'
        maxRelative:
          type: integer
        maxRelativeUnit:
          $ref: '#/components/schemas/RelativeTimeUnit'
      example:
        operator: BETWEEN
        min: '2025-01-01'
        max: '2025-01-31'
    BooleanSearchCriteria:
      type: object
      required:
        - operator
      description: Search criteria for boolean fields
      properties:
        operator:
          type: string
          enum:
            - 'TRUE'
            - 'FALSE'
          description: |
            Search operator:
            - `TRUE`: Field is true
            - `FALSE`: Field is false
      example:
        operator: 'TRUE'
    users_UserReference:
      type: object
      description: >
        User reference for embedding in Team responses.

        Identical to User but excludes the teams array to avoid circular
        references.
      required:
        - id
        - email
        - status
        - roles
        - createdAt
        - updatedAt
      properties:
        object:
          type: string
          enum:
            - USER
          readOnly: true
          description: Object type identifier
          example: USER
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique user identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        email:
          type: string
          format: email
          description: User's email address
          example: john.doe@example.com
        name:
          type:
            - string
            - 'null'
          description: User's full name
          example: John Doe
        phone:
          type:
            - string
            - 'null'
          description: User's phone number
          example: +1-555-123-4567
        phoneExt:
          type:
            - string
            - 'null'
          description: Phone extension
          example: '123'
        status:
          $ref: '#/components/schemas/UserStatus'
        roles:
          type: array
          description: User's roles within the organization
          items:
            $ref: '#/components/schemas/UserRole'
          example:
            - CUSTOMER_REP
            - ADMIN
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier for this user
          example: ERP-USER-12345
        datUsername:
          type:
            - string
            - 'null'
          description: DAT (Load Board) integration username
          example: johndoe_dat
        mcpUsername:
          type:
            - string
            - 'null'
          description: MyCarrierPortal integration username
          example: johndoe_mcp
        avatarId:
          type:
            - string
            - 'null'
          format: uuid
          description: Profile avatar document ID
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when user was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when user was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: Timestamp when user was soft-deleted (null if active)
          example: null
    TeamReference:
      type: object
      description: >
        Team reference for embedding in User responses.

        Identical to Team but excludes the users array to avoid circular
        references.
      required:
        - id
        - name
        - createdAt
        - updatedAt
      properties:
        object:
          type: string
          enum:
            - TEAM
          readOnly: true
          description: Object type identifier
          example: TEAM
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique team identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        name:
          type: string
          description: Team name
          example: Sales Team - West Coast
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier for this team
          example: ERP-TEAM-WEST
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when team was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp when team was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: Timestamp when team was soft-deleted (null if active)
          example: null
    vendors_Currency:
      type: string
      description: Currency code
      enum:
        - USD
        - CAD
        - MXN
        - EUR
        - GBP
    CurrencyFilter:
      type: object
      description: Filter for currency enum field
      properties:
        equalTo:
          $ref: '#/components/schemas/vendors_Currency'
          description: Exact match
        notEqualTo:
          $ref: '#/components/schemas/vendors_Currency'
          description: Not equal to
        in:
          type: array
          items:
            $ref: '#/components/schemas/vendors_Currency'
          description: Matches any value in the list
        notIn:
          type: array
          items:
            $ref: '#/components/schemas/vendors_Currency'
          description: Does not match any value in the list
        isNull:
          type: boolean
          description: Field is null (true) or not null (false)
    VendorPaymentMethodReference:
      type: object
      description: >
        Vendor payment method reference for embedding in Vendor responses.

        Identical to VendorPaymentMethod but excludes the vendor and vendorId
        fields to avoid circular references.
      required:
        - id
        - paymentMethodType
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique vendor payment method identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: VENDOR-PM-001
        paymentMethodType:
          $ref: '#/components/schemas/PaymentMethodType'
          description: How payment is made
        status:
          type:
            - string
            - 'null'
          description: Payment method status
          example: ACTIVE
        isPreferred:
          type:
            - boolean
            - 'null'
          description: Whether this is the preferred payment method
          example: true
        email:
          type:
            - string
            - 'null'
          format: email
          description: Email address for payment notifications
          example: payments@vendor.com
        phone:
          type:
            - string
            - 'null'
          description: Phone number for payment contact
          example: +1-555-123-4567
        companyName:
          type:
            - string
            - 'null'
          description: Company name for this payment method
          example: Vendor Payments LLC
        username:
          type:
            - string
            - 'null'
          description: Username for payment platforms
          example: vendor_payments
        bankName:
          type:
            - string
            - 'null'
          description: Bank name
          example: Chase Bank
        bankAddress:
          type:
            - string
            - 'null'
          description: Bank address
          example: 123 Bank Street, Dallas, TX 75201
        accountName:
          type:
            - string
            - 'null'
          description: Bank account holder name
          example: Vendor Services Inc
        accountNumber:
          type:
            - string
            - 'null'
          description: Bank account number (masked in responses)
          example: '****1234'
        abaAch:
          type:
            - string
            - 'null'
          description: ABA/ACH routing number
          example: '021000021'
        wire:
          type:
            - string
            - 'null'
          description: Wire transfer routing number
          example: '026009593'
        swiftCode:
          type:
            - string
            - 'null'
          description: SWIFT/BIC code
          example: CHASUS33
        eftInstitution:
          type:
            - string
            - 'null'
          description: EFT institution number (Canadian banking)
          example: '001'
        eftTransit:
          type:
            - string
            - 'null'
          description: EFT transit number (Canadian banking)
          example: '00010'
        clabe:
          type:
            - string
            - 'null'
          description: CLABE number (Mexican banking)
          example: '012180001234567897'
        currency:
          type:
            - string
            - 'null'
          description: Preferred currency code
          example: USD
        paymentTerm:
          anyOf:
            - $ref: '#/components/schemas/PaymentTermReference'
            - type: 'null'
          description: Payment terms
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment method was created
          example: '2025-01-15T10:00:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: When the payment method was last updated
          example: '2025-01-15T14:30:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: When the payment method was soft deleted
          example: null
        deletedBy:
          anyOf:
            - $ref: '#/components/schemas/UserReference'
            - type: 'null'
          readOnly: true
          description: User who deleted this payment method
    VendorContactReference:
      type: object
      description: >
        Vendor contact reference for embedding in Vendor responses.

        Identical to VendorContact but excludes the vendor and vendorId fields
        to avoid circular references.
      required:
        - id
        - createdAt
      properties:
        object:
          type: string
          enum:
            - VENDOR_CONTACT
          readOnly: true
          description: Object type identifier
          example: VENDOR_CONTACT
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique contact identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        key:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Client-defined reference identifier
          example: ERP-VENDOR-CONTACT-001
        email:
          type:
            - string
            - 'null'
          format: email
          description: Contact email address
          example: john.smith@abcwarehouse.com
        phone:
          type:
            - string
            - 'null'
          description: Contact phone number
          example: +1-555-123-4567
        role:
          type:
            - string
            - 'null'
          description: Contact role or title (deprecated - use roles array)
          example: Billing Manager
        roles:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/VendorContactRole'
          description: Types/roles this contact serves
          example:
            - BILLING
            - AGENT
        deletedBy:
          anyOf:
            - $ref: '#/components/schemas/UserReference'
            - type: 'null'
          readOnly: true
          description: User who deleted this contact
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: When the contact was created
          example: '2025-01-15T10:00:00Z'
        deletedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: When the contact was soft deleted
          example: null
    CarrierContactChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - CARRIER_CONTACT_CREATED
                - CARRIER_CONTACT_UPDATED
                - CARRIER_CONTACT_DELETED
            data:
              $ref: '#/components/schemas/CarrierContact'
    CarrierFactorChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - CARRIER_FACTOR_CREATED
                - CARRIER_FACTOR_UPDATED
                - CARRIER_FACTOR_DELETED
            data:
              $ref: '#/components/schemas/CarrierFactor'
    CarrierPaymentMethodChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - CARRIER_PAYMENT_METHOD_CREATED
                - CARRIER_PAYMENT_METHOD_UPDATED
                - CARRIER_PAYMENT_METHOD_DELETED
            data:
              $ref: '#/components/schemas/CarrierPaymentMethod'
    VendorPaymentMethodChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - VENDOR_PAYMENT_METHOD_CREATED
                - VENDOR_PAYMENT_METHOD_UPDATED
                - VENDOR_PAYMENT_METHOD_DELETED
            data:
              $ref: '#/components/schemas/VendorPaymentMethod'
    LocationChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - LOCATION_CREATED
                - LOCATION_UPDATED
                - LOCATION_DELETED
            data:
              $ref: '#/components/schemas/Location'
    LocationContactChangedPayload:
      allOf:
        - $ref: '#/components/schemas/WebhookPayload'
        - type: object
          properties:
            event:
              type: string
              enum:
                - LOCATION_CONTACT_CREATED
                - LOCATION_CONTACT_UPDATED
                - LOCATION_CONTACT_DELETED
            data:
              $ref: '#/components/schemas/LocationContact'
    DiffOperation:
      type: string
      description: The type of diff operation from json-diff-ts
      enum:
        - REMOVE
        - ADD
        - UPDATE
    DiffChange:
      type: object
      description: |
        Represents a single change from json-diff-ts IChange interface.
        For nested object changes, the changes array will contain child changes.
      required:
        - type
        - key
      properties:
        type:
          $ref: '#/components/schemas/DiffOperation'
        key:
          type: string
          description: The property name that changed
          example: status
        embeddedKey:
          type: string
          description: Optional key used when comparing array elements by identifier
          example: id
        value:
          description: |
            The new value being set.
            - For ADD: The value being added
            - For UPDATE: The new value replacing the old one
            - For REMOVE: Not present
          example: INACTIVE
        oldValue:
          description: |
            The previous value (only present for UPDATE operations).
          example: ACTIVE
        changes:
          type: array
          description: Nested changes for complex objects
          items:
            $ref: '#/components/schemas/DiffChange'
    WebhookDelivery:
      type: object
      description: The top-level webhook delivery payload containing one or more events
      required:
        - sentAt
        - events
      properties:
        sentAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the webhook was sent from MVMNT
          example: '2025-01-15T14:30:00Z'
        events:
          type: array
          description: Array of webhook events (typically contains a single event)
          minItems: 1
          items:
            $ref: '#/components/schemas/WebhookPayload'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 access token obtained via client credentials flow
security:
  - BearerAuth: []
