{
  "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\ndirectly with our Transportation Management System.\n\nPostman setup guide: [API Clients](/getting-started/api-clients).\n\n## Authentication\n\nOAuth 2.0 client credentials flow. See [Authentication Guide](/getting-started/authentication)\nfor details.\n\n### Token Endpoint\n\n```\nPOST https://api.mvmnt.io/oauth2/token\n```\n\n#### Request\n\n**Headers:**\n```http\nContent-Type: application/x-www-form-urlencoded\n```\n\n**Body Parameters:**\n```\ngrant_type=client_credentials\nclient_id=YOUR_CLIENT_ID\nclient_secret=YOUR_CLIENT_SECRET\n```\n\n#### Example Request\n\n```bash\ncurl -X POST https://api.mvmnt.io/oauth2/token \\\n  -H \"Content-Type: application/x-www-form-urlencoded\" \\\n  -d \"grant_type=client_credentials\" \\\n  -d \"client_id=YOUR_CLIENT_ID\" \\\n  -d \"client_secret=YOUR_CLIENT_SECRET\"\n```\n\n#### Success Response\n\n**Status:** `200 OK`\n\n```json\n{\n  \"access_token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...\",\n  \"token_type\": \"Bearer\",\n  \"expires_in\": 3600\n}\n```\n\n**Response Fields:**\n- `access_token`: JWT Bearer token to use for API requests\n- `token_type`: Always `Bearer`\n- `expires_in`: Token lifetime in seconds (3600 = 1 hour)\n\n## Idempotency\n\nMutating requests (POST, PATCH, DELETE) accept an optional `Idempotency-Key`\nheader (up to 255 characters). Retrying a request with the same key and the\nsame body returns the original result instead of repeating the operation;\nreusing a key with a different body fails. Keys are scoped to your\norganization — keys chosen by other tenants can never collide with yours.\nUse a stable identifier from your system (for example your own record id\nplus the action) rather than a random value per attempt.\n",
    "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"
    },
    {
      "url": "https://api.demo.mvmnt.io/v1",
      "description": "Demo (non-production)"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Carriers",
      "description": "Carrier management operations"
    },
    {
      "name": "Carrier Contacts",
      "description": "Carrier contact management operations"
    },
    {
      "name": "Carrier Factors",
      "description": "Carrier factor (factoring company) management operations"
    },
    {
      "name": "Carrier Payment Methods",
      "description": "Carrier payment method management operations"
    },
    {
      "name": "Companies",
      "description": "Company management operations"
    },
    {
      "name": "Credit Memos",
      "description": "AR credit memo management operations.\nCredit memos represent customer credits that can be applied to invoices.\n"
    },
    {
      "name": "Bills",
      "description": "AP bill management operations.\nBills represent carrier and vendor invoices to be paid.\n"
    },
    {
      "name": "Bill Payments",
      "description": "AP bill payment management operations.\nBill payments record payments made to carriers and vendors.\n"
    },
    {
      "name": "Customers",
      "description": "Customer management operations"
    },
    {
      "name": "Customer Contacts",
      "description": "Customer contact management operations"
    },
    {
      "name": "Documents",
      "description": "Document management operations.\nDocuments are files (PDFs, images) that can be attached to orders, loads, or services.\n"
    },
    {
      "name": "Invoices",
      "description": "AR invoice management operations.\nInvoices represent customer billing for shipment services.\n"
    },
    {
      "name": "Loads",
      "description": "Load management operations.\nLoads represent carrier execution - which carrier is moving the freight.\n"
    },
    {
      "name": "Locations",
      "description": "Location management operations"
    },
    {
      "name": "Location Contacts",
      "description": "Location contact management operations"
    },
    {
      "name": "Payment Terms",
      "description": "Payment term management operations"
    },
    {
      "name": "Reference Data",
      "description": "Read-only catalogs (equipment, charge codes, special requirements)\nreferenced by id from other resources.\n\nEvery catalog also answers on its short top-level path, so\n`GET /v1/charge-codes` and `GET /v1/reference-data/charge-codes` are\nthe same endpoint. The documented `/reference-data/*` form is canonical\n— it keeps the catalogs grouped here as more are added (port codes,\ncities, zip codes) — and the short form is a convenience alias.\n"
    },
    {
      "name": "Payments",
      "description": "AR payment management operations.\nPayments represent received customer payments applied to invoices.\n"
    },
    {
      "name": "Quotes",
      "description": "Quote management operations.\nQuotes are pricing requests/responses that can be converted to shipments.\n"
    },
    {
      "name": "Saved Searches",
      "description": "Saved search management operations"
    },
    {
      "name": "Search",
      "description": "Global search operations"
    },
    {
      "name": "Services",
      "description": "Service (vended service) management operations.\nServices represent non-carrier vendor work (drayage, customs, warehousing).\n"
    },
    {
      "name": "Shipments",
      "description": "Shipment tracking and management operations.\nShipments contain orders, loads, and services.\n"
    },
    {
      "name": "Teams",
      "description": "Team management operations"
    },
    {
      "name": "Users",
      "description": "User management operations"
    },
    {
      "name": "Vendors",
      "description": "Vendor management operations"
    },
    {
      "name": "Vendor Contacts",
      "description": "Vendor contact management operations"
    },
    {
      "name": "Vendor Payment Methods",
      "description": "Vendor payment method management operations"
    }
  ],
  "paths": {
    "/companies/filter": {
      "post": {
        "tags": [
          "Companies"
        ],
        "summary": "Filter companies",
        "description": "Query companies using flexible filter criteria with AND/OR logic.\n\nBy default, only non-deleted companies are returned (deletedAt: { isNull: true }).\nOverride this by explicitly setting deletedAt filter criteria.\n",
        "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.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "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).\n\nThe company will no longer appear in default queries but can be retrieved\nby explicitly filtering for deleted records.\n",
        "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.\n\nBy default, only non-deleted carrier contacts are returned (deletedAt: { isNull: true }).\nOverride this by explicitly setting deletedAt filter criteria.\n",
        "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,\nand the CarrierContact will reference it via contactId (managed internally).\n",
        "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.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n\nWhen updating contactInfo, the underlying Contact record is updated.\n",
        "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).\n\nThe contact will no longer appear in default queries but can be retrieved\nby explicitly filtering for deleted records.\n",
        "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.\n\nBy default, only non-deleted carriers are returned (deletedAt: { isNull: true }).\nOverride this by explicitly setting deletedAt filter criteria.\n\nReturns carriers of all types (TRUCKLOAD, AIR, CARTAGE, LINEHAUL, LTL, OCEAN, RAIL)\nwith type-specific fields included based on carrier type.\n",
        "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.\n\nThe carrier type must be specified and determines which fields are available:\n- **TRUCKLOAD**: Includes insurance, safety rating, and FMCSA inspection fields\n- **AIR, CARTAGE, LINEHAUL, LTL, OCEAN, RAIL**: Include only base carrier fields\n\nNote: In the backend, null carrier type is represented as TRUCKLOAD in the public API.\n",
        "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.\n\nThe response will include type-specific fields based on the carrier's type:\n- **TRUCKLOAD**: Includes insurance, safety rating, and FMCSA inspection fields\n- **AIR, CARTAGE, LINEHAUL, LTL, OCEAN, RAIL**: Include only base carrier fields\n",
        "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.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n\nThe carrier type determines which fields can be updated:\n- **TRUCKLOAD**: Can update insurance, safety rating, and FMCSA fields\n- **AIR, CARTAGE, LINEHAUL, LTL, OCEAN, RAIL**: Can only update base carrier fields\n\nChanging the carrier type will affect which specialized fields are available.\n",
        "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).\n\nThe carrier will no longer appear in default queries but can be retrieved\nby explicitly filtering for deleted records.\n",
        "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.\n\nThis endpoint searches both:\n- **ONBOARDED carriers**: Carriers with profiles in your organization\n- **FMCSA carriers**: Public carrier records from FMCSA database\n\nFeatures:\n- Full-text search across multiple fields\n- Field-specific filtering with various operators\n- Sorting and pagination\n- Saved search preferences\n\n**Note:** Only active (non-deleted) carriers are searchable. Soft-deleted records are automatically excluded from all search results.\n\n**Response Formats:**\n- `flat` (default): Returns indexed fields only for faster performance\n- `full`: Returns complete carrier objects with all relationships\n",
        "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.\n\nBy default, only non-deleted carrier factors are returned (deletedAt: { isNull: true }).\nOverride this by explicitly setting deletedAt filter criteria.\n\nCarrier factors represent factoring companies that provide payment services for carriers.\n",
        "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).\n\nFactoring companies provide payment services for carriers, allowing them to receive\nimmediate payment for invoices.\n",
        "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.\n\nCarrier factors represent factoring companies that provide payment services.\n",
        "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.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "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).\n\nThe carrier factor will no longer appear in default queries but can be retrieved\nby explicitly filtering for deleted records.\n",
        "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.\n\nBy default, only non-deleted payment methods are returned (deletedAt: { isNull: true }).\nOverride this by explicitly setting deletedAt filter criteria.\n\nCarrier payment methods define how and where payments are sent for a specific carrier.\n",
        "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.\n\n**Payment Recipient Type Constraints:**\n- **DIRECT**: Payment goes to carrier directly. `carrierFactorId` must be null or omitted.\n- **FACTOR**: Payment goes to factoring company. `carrierFactorId` is required.\n\n**Important**: The `carrierId` cannot be changed after creation.\n",
        "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.\n\nReturns full details including banking information and associated carrier/factor references.\n",
        "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.\n\n**IMPORTANT**: The `carrierId` field cannot be changed after creation.\n\n**Payment Recipient Type Constraints:**\n- When changing to **DIRECT**: `carrierFactorId` must be set to null\n- When changing to **FACTOR**: `carrierFactorId` is required\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "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).\n\nThe payment method will no longer appear in default queries but can be retrieved\nby explicitly filtering for deleted records.\n",
        "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.\n\nBy default, only non-deleted customer contacts are returned (deletedAt: { isNull: true }).\nOverride this by explicitly setting deletedAt filter criteria.\n",
        "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 contact details are provided inline\nvia contactInfo; no internal identifiers are required or exposed.\n",
        "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.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n\nWhen updating contactInfo, the underlying Contact record is updated.\n",
        "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).\n\nThe contact will no longer appear in default queries but can be retrieved\nby explicitly filtering for deleted records.\n",
        "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.\nSupports complex filtering similar to GraphQL capabilities.\nNote: Soft-deleted customers are excluded by default (deletedAt defaults to { isNull: true }).\n",
        "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.\n\nThis endpoint provides fast, indexed search across customer data with support for:\n- Full-text search across multiple fields\n- Field-specific filtering with various operators\n- Sorting and pagination\n- Saved search preferences\n\n**Note:** Only active (non-deleted) customers are searchable. Soft-deleted records are automatically excluded from all search results.\n\n**Response Formats:**\n- `flat` (default): Returns indexed fields only for faster performance\n- `full`: Returns complete customer objects with all relationships\n",
        "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.\n\nBy default, only non-deleted locations are returned (deletedAt: { isNull: true }).\nOverride this by explicitly setting deletedAt filter criteria.\n",
        "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.\n\nLocations represent pickup or delivery points (warehouses, distribution centers, etc.).\n",
        "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",
                    "address": {
                      "line1": "2100 Ross Ave",
                      "city": "Dallas",
                      "state": "TX",
                      "zipCode": "75201",
                      "country": "US"
                    },
                    "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",
                    "address": {
                      "line1": "500 Commerce St",
                      "city": "Fort Worth",
                      "state": "TX",
                      "zipCode": "76102",
                      "country": "US"
                    },
                    "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.\n",
        "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.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "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).\n\nThe location will no longer appear in default queries but can be retrieved\nby explicitly filtering for deleted records.\n",
        "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.\n\nThis endpoint provides fast, indexed search across location data with support for:\n- Full-text search across multiple fields\n- Field-specific filtering with various operators\n- Geographic search capabilities\n- Sorting and pagination\n- Saved search preferences\n\n**Note:** Only active (non-deleted) locations are searchable. Soft-deleted records are automatically excluded from all search results.\n\n**Response Formats:**\n- `flat` (default): Returns indexed fields only for faster performance\n- `full`: Returns complete location objects with all relationships\n",
        "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.\n\nBy default, only non-deleted location contacts are returned (deletedAt: { isNull: true }).\nOverride this by explicitly setting deletedAt filter criteria.\n",
        "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.\n\nLocation contacts represent the relationship between a customer contact\nand a specific location, defining what role the contact has at that location.\n",
        "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.\n",
        "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.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "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).\n\nThe location contact will no longer appear in default queries but can be retrieved\nby explicitly filtering for deleted records.\n",
        "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.\nSupports complex filtering similar to GraphQL capabilities.\nNote: Soft-deleted payment terms are excluded by default (deletedAt defaults to { isNull: true }).\n",
        "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"
          }
        }
      }
    },
    "/reference-data/equipment": {
      "get": {
        "summary": "List equipment",
        "description": "Read-only catalog of equipment types. The ids are what order and load\n`equipment` arrays reference. The list is system-managed and small —\nfetch it once and cache it, or hardcode the ids your integration uses.\n\nThe catalog is global and organization-independent: every\nauthenticated organization sees the same rows.\n",
        "operationId": "listReferenceEquipment",
        "tags": [
          "Reference Data"
        ],
        "parameters": [
          {
            "name": "categoryId",
            "in": "query",
            "required": false,
            "description": "Only return equipment in this category",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "groupId",
            "in": "query",
            "required": false,
            "description": "Only return equipment in this top-level group",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "subcategoryId",
            "in": "query",
            "required": false,
            "description": "Only return equipment in this subcategory",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Equipment"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          }
        }
      }
    },
    "/reference-data/charge-codes": {
      "get": {
        "summary": "List charge codes",
        "description": "Read-only catalog of charge codes. The integer ids are what charge\n`chargeCodeId` fields reference. The list is system-managed — fetch it\nonce and cache it.\n\nThe catalog is global and organization-independent: every\nauthenticated organization sees the same rows.\n",
        "operationId": "listReferenceChargeCodes",
        "tags": [
          "Reference Data"
        ],
        "parameters": [
          {
            "name": "code",
            "in": "query",
            "required": false,
            "description": "Only return the charge code with this exact accounting code",
            "schema": {
              "type": "string",
              "example": "LH"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ChargeCode"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          }
        }
      }
    },
    "/reference-data/special-requirements": {
      "get": {
        "summary": "List special requirements",
        "description": "Read-only catalog of special requirements (equipment accessories,\ndriver services, freight handling, location constraints). The ids are\nwhat order and load `specialRequirements` arrays reference. Filter by\n`type` to get one category.\n\nThe catalog is global and organization-independent: every\nauthenticated organization sees the same rows.\n",
        "operationId": "listReferenceSpecialRequirements",
        "tags": [
          "Reference Data"
        ],
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Only return requirements of this type",
            "schema": {
              "$ref": "#/components/schemas/SpecialRequirementType"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SpecialRequirement"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "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.\nSupports complex filtering similar to GraphQL capabilities.\nNote: Soft-deleted teams are excluded by default (deletedAt defaults to { isNull: true }).\n",
        "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.\nSupports complex filtering similar to GraphQL capabilities.\nNote: Soft-deleted users are excluded by default (deletedAt defaults to { isNull: true }).\n",
        "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.\n\nThis endpoint provides fast, indexed search across user data with support for:\n- Full-text search across multiple fields\n- Field-specific filtering with various operators\n- Sorting and pagination\n- Saved search preferences\n\n**Note:** Only active (non-deleted) users are searchable. Soft-deleted records are automatically excluded from all search results.\n\n**Response Formats:**\n- `flat` (default): Returns indexed fields only for faster performance\n- `full`: Returns complete user objects with all relationships\n",
        "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.\n\nBy default, only non-deleted vendors are returned (deletedAt: { isNull: true }).\nOverride this by explicitly setting deletedAt filter criteria.\n",
        "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.\n\nVendors represent service providers (warehousing, storage, etc.) that are not carriers.\n",
        "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.\n",
        "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.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "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).\n\nThe vendor will no longer appear in default queries but can be retrieved\nby explicitly filtering for deleted records.\n",
        "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.\n\nThis endpoint provides fast, indexed search across vendor data with support for:\n- Full-text search across multiple fields\n- Field-specific filtering with various operators\n- Sorting and pagination\n- Saved search preferences\n\n**Note:** Only active (non-deleted) vendors are searchable. Soft-deleted records are automatically excluded from all search results.\n\n**Response Formats:**\n- `flat` (default): Returns indexed fields only for faster performance\n- `full`: Returns complete vendor objects with all relationships\n",
        "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.\n\nBy default, only non-deleted contacts are returned (deletedAt: { isNull: true }).\nOverride this by explicitly setting deletedAt filter criteria.\n",
        "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.\n\nContacts represent individuals at the vendor who can be reached for various purposes.\n",
        "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",
                    "name": "Dana Reyes",
                    "email": "billing@abcwarehouse.com",
                    "phone": "+1-555-123-4567",
                    "roles": [
                      "BILLING"
                    ]
                  }
                },
                "operations": {
                  "summary": "Operations contact",
                  "value": {
                    "vendorId": "550e8400-e29b-41d4-a716-446655440001",
                    "name": "Sam Okafor",
                    "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.\n",
        "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.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "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).\n\nThe contact will no longer appear in default queries but can be retrieved\nby explicitly filtering for deleted records.\n",
        "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.\n\nBy default, only non-deleted payment methods are returned (deletedAt: { isNull: true }).\nOverride this by explicitly setting deletedAt filter criteria.\n\nVendor payment methods define how and where payments are sent for a specific vendor.\n",
        "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.\n\n**Important**: The `vendorId` cannot be changed after creation.\n",
        "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.\n\nReturns full details including banking information and associated vendor references.\n",
        "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.\n\n**IMPORTANT**: The `vendorId` field cannot be changed after creation.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "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).\n\nThe payment method will no longer appear in default queries but can be retrieved\nby explicitly filtering for deleted records.\n",
        "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.\nSupports complex filtering similar to GraphQL capabilities.\nReturns only saved searches accessible to the authenticated user (either owned by them or public).\n",
        "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.\nThe saved search can be used to quickly apply predefined search criteria, sorting, and display preferences.\n\nThe saved search will be owned by the authenticated user unless otherwise specified.\n",
        "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.\nYou can only retrieve saved searches that you own or that are public in your organization.\n",
        "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.\nYou can only update saved searches that you own.\n",
        "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.\nYou can only delete saved searches that you own.\n",
        "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"
          }
        }
      }
    },
    "/shipments/track": {
      "post": {
        "summary": "Get tracking link",
        "description": "Search for shipments by reference field values (BOL #, PRO #, MAWB #, etc.)\nand return tracking information.\n\n## Usage\n\n1. Provide an array of search queries in the `searches` field\n2. Optionally filter which reference field types to search using `referenceFields`\n3. Results are returned in the same order as input searches\n4. If no match is found, the result contains only the original `query` (other fields are null)\n\n## Matching Behavior\n\n- Searches are case-insensitive\n- If multiple shipments match a query, the most recently created shipment is returned\n- If `referenceFields` is omitted, all reference field types are searched\n\n## Example Use Cases\n\n- **Customer portal**: Look up shipment status by BOL or PRO number\n- **EDI integration**: Validate shipment references before sending updates\n- **Bulk status check**: Query multiple shipments in a single request\n\n## Rate Limits\n\n- Maximum 100 searches per request\n- Standard API rate limits apply (see Rate Limiting documentation)\n",
        "operationId": "trackShipments",
        "tags": [
          "Shipments"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ShipmentTrackRequest"
              },
              "examples": {
                "singleSearch": {
                  "summary": "Single shipment lookup",
                  "description": "Look up a single shipment by reference value",
                  "value": {
                    "searches": [
                      {
                        "query": "MAWB123456"
                      }
                    ]
                  }
                },
                "multipleSearches": {
                  "summary": "Multiple shipments with field filter",
                  "description": "Look up multiple shipments, limiting search to specific reference field types",
                  "value": {
                    "searches": [
                      {
                        "query": "MAWB123456"
                      },
                      {
                        "query": "BOL789"
                      },
                      {
                        "query": "PRO-001"
                      }
                    ],
                    "referenceFields": [
                      "MASTER_AIRWAYBILL_NUMBER",
                      "BOL_NUMBER",
                      "PRO_NUMBER"
                    ]
                  }
                },
                "bulkLookup": {
                  "summary": "Bulk BOL lookup",
                  "description": "Look up multiple shipments by BOL number only",
                  "value": {
                    "searches": [
                      {
                        "query": "BOL-2025-001"
                      },
                      {
                        "query": "BOL-2025-002"
                      },
                      {
                        "query": "BOL-2025-003"
                      },
                      {
                        "query": "BOL-2025-004"
                      }
                    ],
                    "referenceFields": [
                      "BOL_NUMBER"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Track results returned successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShipmentTrackResponse"
                },
                "examples": {
                  "allFound": {
                    "summary": "All shipments found",
                    "description": "All search queries returned matching shipments",
                    "value": {
                      "results": [
                        {
                          "query": "MAWB123456",
                          "id": "550e8400-e29b-41d4-a716-446655440000",
                          "key": "SHIP-001",
                          "friendlyId": "SHP-12345",
                          "status": "IN_TRANSIT",
                          "field": "MASTER_AIRWAYBILL_NUMBER",
                          "value": "MAWB123456",
                          "origin": "Los Angeles, CA 90210",
                          "destination": "New York, NY 10001",
                          "pickUpDate": "2025-01-15",
                          "deliveryDate": "2025-01-20",
                          "trackingUrl": "https://app.mvmnt.io/shipments/550e8400-e29b-41d4-a716-446655440000"
                        },
                        {
                          "query": "BOL789012",
                          "id": "660e8400-e29b-41d4-a716-446655440001",
                          "key": "SHIP-002",
                          "friendlyId": "SHP-12346",
                          "status": "DELIVERED",
                          "field": "BOL_NUMBER",
                          "value": "BOL-789012",
                          "origin": "Chicago, IL 60601",
                          "destination": "Miami, FL 33101",
                          "pickUpDate": "2025-01-16",
                          "deliveryDate": "2025-01-21",
                          "trackingUrl": "https://app.mvmnt.io/shipments/660e8400-e29b-41d4-a716-446655440001"
                        }
                      ]
                    }
                  },
                  "mixedResults": {
                    "summary": "Some found, some not found",
                    "description": "Mix of found and not-found results",
                    "value": {
                      "results": [
                        {
                          "query": "MAWB123456",
                          "id": "550e8400-e29b-41d4-a716-446655440000",
                          "key": "SHIP-001",
                          "friendlyId": "SHP-12345",
                          "status": "PICKED_UP",
                          "field": "MASTER_AIRWAYBILL_NUMBER",
                          "value": "MAWB123456",
                          "origin": "Los Angeles, CA 90210",
                          "destination": "New York, NY 10001",
                          "pickUpDate": "2025-01-15",
                          "deliveryDate": "2025-01-20",
                          "trackingUrl": "https://app.mvmnt.io/shipments/550e8400-e29b-41d4-a716-446655440000"
                        },
                        {
                          "query": "NOTFOUND123",
                          "id": null,
                          "key": null,
                          "friendlyId": null,
                          "status": null,
                          "field": null,
                          "value": null,
                          "origin": null,
                          "destination": null,
                          "pickUpDate": null,
                          "deliveryDate": null,
                          "trackingUrl": null
                        }
                      ]
                    }
                  },
                  "noneFound": {
                    "summary": "No shipments found",
                    "description": "No matching shipments for any query",
                    "value": {
                      "results": [
                        {
                          "query": "UNKNOWN-REF-1",
                          "id": null,
                          "key": null,
                          "friendlyId": null,
                          "status": null,
                          "field": null,
                          "value": null,
                          "origin": null,
                          "destination": null,
                          "pickUpDate": null,
                          "deliveryDate": null,
                          "trackingUrl": null
                        },
                        {
                          "query": "UNKNOWN-REF-2",
                          "id": null,
                          "key": null,
                          "friendlyId": null,
                          "status": null,
                          "field": null,
                          "value": null,
                          "origin": null,
                          "destination": null,
                          "pickUpDate": null,
                          "deliveryDate": null,
                          "trackingUrl": null
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          }
        }
      }
    },
    "/documents/filter": {
      "post": {
        "summary": "Filter documents",
        "description": "Search for documents using filter criteria.\n\n## Usage\n\nDocuments are typically associated with other entities (orders, loads, services).\nUse filters to find documents by type, status, or date range.\n\n## Example Filters\n\n- Find all invoices: `{ \"filter\": { \"type\": { \"equalTo\": \"INVOICE\" } } }`\n- Find uploaded documents: `{ \"filter\": { \"status\": { \"equalTo\": \"UPLOADED\" } } }`\n- Find documents created today: `{ \"filter\": { \"createdAt\": { \"greaterThanOrEqualTo\": \"2025-01-15T00:00:00Z\" } } }`\n",
        "operationId": "filterDocuments",
        "tags": [
          "Documents"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocumentFilterRequest"
              },
              "examples": {
                "filterByType": {
                  "summary": "Filter by document type",
                  "value": {
                    "filter": {
                      "type": {
                        "equalTo": "INVOICE"
                      }
                    },
                    "pageSize": 50
                  }
                },
                "filterByStatus": {
                  "summary": "Filter by upload status",
                  "value": {
                    "filter": {
                      "status": {
                        "equalTo": "UPLOADED"
                      }
                    }
                  }
                },
                "filterByDateRange": {
                  "summary": "Filter by creation date",
                  "value": {
                    "filter": {
                      "createdAt": {
                        "greaterThanOrEqualTo": "2025-01-01T00:00:00Z",
                        "lessThanOrEqualTo": "2025-01-31T23:59:59Z"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Documents matching filter criteria",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Document"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/PaginationInfo"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/documents": {
      "post": {
        "summary": "Create a document",
        "description": "Create a new document record and receive a pre-signed URL for uploading the file.\n\n## Workflow\n\n1. Call this endpoint with document metadata (type, fileName, contentType)\n2. Receive the created document with an `uploadUrl`\n3. Upload the file directly to S3 using the `uploadUrl` (PUT request)\n4. Document status changes from `PENDING_UPLOAD` to `UPLOADED` automatically\n\n## Upload Instructions\n\nThe `uploadUrl` is a pre-signed S3 URL. Upload your file with:\n\n```bash\ncurl -X PUT -H \"Content-Type: application/pdf\" \\\n  --data-binary @your-file.pdf \\\n  \"https://s3.amazonaws.com/bucket/key?signature=...\"\n```\n\n**Important:**\n- The `uploadUrl` expires after 15 minutes\n- Use the exact `contentType` specified in the request\n- Maximum file size: 100MB\n",
        "operationId": "createDocument",
        "tags": [
          "Documents"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocumentInput"
              },
              "examples": {
                "pdfInvoice": {
                  "summary": "Create PDF invoice document",
                  "value": {
                    "type": "INVOICE",
                    "fileName": "invoice-2025-001.pdf",
                    "contentType": "application/pdf",
                    "fileSize": 102400,
                    "tags": {
                      "invoiceNumber": "INV-2025-001"
                    }
                  }
                },
                "podImage": {
                  "summary": "Create POD image",
                  "value": {
                    "type": "PROOF_OF_DELIVERY",
                    "fileName": "pod-delivery-photo.jpg",
                    "contentType": "image/jpeg"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Document created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Document"
                },
                "examples": {
                  "created": {
                    "summary": "Newly created document with upload URL",
                    "value": {
                      "id": "550e8400-e29b-41d4-a716-446655440000",
                      "type": "INVOICE",
                      "fileName": "invoice-2025-001.pdf",
                      "extension": "pdf",
                      "contentType": "application/pdf",
                      "fileSize": 102400,
                      "status": "PENDING_UPLOAD",
                      "uploadUrl": "https://s3.amazonaws.com/bucket/key?X-Amz-Signature=...",
                      "downloadUrl": null,
                      "tags": {
                        "invoiceNumber": "INV-2025-001"
                      },
                      "createdAt": "2025-01-15T10:30:00Z",
                      "updatedAt": null
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/documents/{id}": {
      "get": {
        "summary": "Get a document",
        "description": "Retrieve a document by ID or key.\n\nReturns the document metadata including a fresh `downloadUrl` if the file is uploaded.\n\n**Note:** The `downloadUrl` is a pre-signed S3 URL that expires after 1 hour.\nEach GET request generates a fresh URL.\n",
        "operationId": "getDocument",
        "tags": [
          "Documents"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Document retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Document"
                },
                "examples": {
                  "uploaded": {
                    "summary": "Document with download URL",
                    "value": {
                      "id": "550e8400-e29b-41d4-a716-446655440000",
                      "key": "doc-inv-2025-001",
                      "type": "INVOICE",
                      "fileName": "invoice-2025-001.pdf",
                      "extension": "pdf",
                      "contentType": "application/pdf",
                      "fileSize": 102400,
                      "status": "UPLOADED",
                      "uploadUrl": null,
                      "downloadUrl": "https://s3.amazonaws.com/bucket/key?X-Amz-Signature=...",
                      "tags": {
                        "invoiceNumber": "INV-2025-001"
                      },
                      "createdAt": "2025-01-15T10:30:00Z",
                      "updatedAt": "2025-01-15T10:35:00Z"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      },
      "patch": {
        "summary": "Update a document",
        "description": "Update document metadata.\n\n**Note:** File content cannot be changed after upload.\nTo replace a file, create a new document.\n",
        "operationId": "updateDocument",
        "tags": [
          "Documents"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocumentPatch"
              },
              "examples": {
                "updateTags": {
                  "summary": "Update document tags",
                  "value": {
                    "tags": {
                      "invoiceNumber": "INV-2025-001-REVISED",
                      "approved": true
                    }
                  }
                },
                "updateType": {
                  "summary": "Change document type",
                  "value": {
                    "type": "PROOF_OF_DELIVERY"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Document updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Document"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      },
      "delete": {
        "summary": "Delete a document",
        "description": "Soft delete a document.\n\nThe document record is marked as deleted but not permanently removed.\nAssociated files in S3 may be cleaned up asynchronously.\n",
        "operationId": "deleteDocument",
        "tags": [
          "Documents"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "204": {
            "description": "Document deleted successfully"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/quotes/filter": {
      "post": {
        "summary": "Filter quotes",
        "description": "Search for quotes using filter criteria.\n\n## Common Filters\n\n- Active quotes: `{ \"filter\": { \"status\": { \"in\": [\"DRAFT\", \"REQUESTED\", \"QUOTED\"] } } }`\n- Won quotes: `{ \"filter\": { \"status\": { \"equalTo\": \"WON\" } } }`\n- By customer: `{ \"filter\": { \"customerId\": { \"equalTo\": \"uuid\" } } }`\n- Expiring soon: `{ \"filter\": { \"expiresAt\": { \"lessThanOrEqualTo\": \"2025-01-20T00:00:00Z\" } } }`\n",
        "operationId": "filterQuotes",
        "tags": [
          "Quotes"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuoteFilterRequest"
              },
              "examples": {
                "activeQuotes": {
                  "summary": "Filter active quotes",
                  "value": {
                    "filter": {
                      "status": {
                        "in": [
                          "DRAFT",
                          "REQUESTED",
                          "QUOTED"
                        ]
                      }
                    },
                    "pageSize": 50
                  }
                },
                "byCustomer": {
                  "summary": "Filter by customer",
                  "value": {
                    "filter": {
                      "customerId": {
                        "equalTo": "550e8400-e29b-41d4-a716-446655440000"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Quotes matching filter criteria",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Quote"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/PaginationInfo"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/quotes": {
      "post": {
        "summary": "Create a quote",
        "description": "Create a new quote with order details.\n\n## How it works\n\nCreating a quote also creates an associated Order containing the route and freight details.\nThe Order is embedded in the Quote and cannot be managed separately.\n\n## Required fields\n\n- `customer`: Reference to the customer (shipper profile)\n- `order`: Order details including stops and mode\n\n## Example workflow\n\n1. Create quote with customer and order details\n2. Add pricing (amount) via PATCH\n3. Send to customer (status changes to QUOTED)\n4. Convert to shipment when accepted (POST /quotes/{id}/convert-to-shipment)\n",
        "operationId": "createQuote",
        "tags": [
          "Quotes"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuoteInput"
              },
              "examples": {
                "basicQuote": {
                  "summary": "Basic FTL quote",
                  "value": {
                    "customer": {
                      "id": "550e8400-e29b-41d4-a716-446655440000"
                    },
                    "order": {
                      "mode": "FTL",
                      "stops": [
                        {
                          "type": "PICKUP",
                          "address": {
                            "line1": "123 Warehouse Ave",
                            "city": "Los Angeles",
                            "country": "US",
                            "market": "LAX"
                          },
                          "requestedStartDate": "2025-01-20"
                        },
                        {
                          "type": "DELIVERY",
                          "address": {
                            "line1": "456 Distribution Center",
                            "city": "New York",
                            "country": "US",
                            "market": "JFK"
                          },
                          "requestedStartDate": "2025-01-25"
                        }
                      ],
                      "freight": {
                        "handlingUnitQuantity": 10,
                        "handlingUnitType": "PALLET",
                        "weight": 15000
                      }
                    },
                    "amount": 2500,
                    "expiresAt": "2025-01-18T23:59:59Z"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Quote created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Quote"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/quotes/{id}": {
      "get": {
        "summary": "Get a quote",
        "description": "Retrieve a quote by ID or key.\n\nThe response includes embedded order details (route, freight, equipment).\n",
        "operationId": "getQuote",
        "tags": [
          "Quotes"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Quote retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Quote"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      },
      "patch": {
        "summary": "Update a quote",
        "description": "Update quote fields including status changes.\n\n## Status changes\n\nStatus changes use this endpoint (not separate action endpoints):\n- Set to QUOTED: `{ \"status\": \"QUOTED\", \"amount\": 2500 }`\n- Set to WON: `{ \"status\": \"WON\" }`\n- Set to LOST: `{ \"status\": \"LOST\", \"lostReason\": \"TOO_HIGH\" }`\n\n## Validation rules\n\n- When setting `status` to `LOST`, `lostReason` is required\n- When `lostReason` is `OTHER`, `lostReasonText` is required\n\n## Note\n\nTo convert a won quote to a shipment, use POST /quotes/{id}/convert-to-shipment\n",
        "operationId": "updateQuote",
        "tags": [
          "Quotes"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuotePatch"
              },
              "examples": {
                "setQuoted": {
                  "summary": "Set quote as quoted",
                  "value": {
                    "status": "QUOTED",
                    "amount": 2500
                  }
                },
                "setWon": {
                  "summary": "Mark quote as won",
                  "value": {
                    "status": "WON"
                  }
                },
                "setLost": {
                  "summary": "Mark quote as lost",
                  "value": {
                    "status": "LOST",
                    "lostReason": "TOO_HIGH"
                  }
                },
                "setLostOther": {
                  "summary": "Mark lost with custom reason",
                  "value": {
                    "status": "LOST",
                    "lostReason": "OTHER",
                    "lostReasonText": "Customer chose competitor with faster transit time"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Quote updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Quote"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      },
      "delete": {
        "summary": "Delete a quote",
        "description": "Soft delete a quote.\n\nThe quote record is marked as deleted but not permanently removed.\nAssociated orders are also soft deleted.\n",
        "operationId": "deleteQuote",
        "tags": [
          "Quotes"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "204": {
            "description": "Quote deleted successfully"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/quotes/{id}/convert-to-shipment": {
      "post": {
        "summary": "Convert quote to shipment",
        "description": "Convert an accepted quote into a shipment.\n\n## What happens\n\n1. Quote status is set to WON (if not already)\n2. A new Shipment is created\n3. The Order from the quote is linked to the shipment\n4. Optionally, additional orders can be added\n\n## Prerequisites\n\n- Quote must be in QUOTED or WON status\n- Quote cannot already have a shipment\n\n## Response\n\nReturns the IDs of both the quote and the newly created shipment.\n",
        "operationId": "convertQuoteToShipment",
        "tags": [
          "Quotes"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConvertToShipmentRequest"
              },
              "examples": {
                "simpleConvert": {
                  "summary": "Simple conversion",
                  "value": {}
                },
                "withAdditionalOrder": {
                  "summary": "Add additional order",
                  "value": {
                    "additionalOrders": [
                      {
                        "mode": "FTL",
                        "stops": [
                          {
                            "type": "PICKUP",
                            "location": {
                              "id": "550e8400-e29b-41d4-a716-446655440001"
                            },
                            "requestedStartDate": "2025-01-22"
                          },
                          {
                            "type": "DELIVERY",
                            "location": {
                              "id": "550e8400-e29b-41d4-a716-446655440002"
                            },
                            "requestedStartDate": "2025-01-27"
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Quote converted to shipment successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConvertToShipmentResponse"
                },
                "examples": {
                  "converted": {
                    "summary": "Successful conversion",
                    "value": {
                      "quoteId": "550e8400-e29b-41d4-a716-446655440000",
                      "quoteStatus": "WON",
                      "shipmentId": "660e8400-e29b-41d4-a716-446655440001",
                      "shipmentKey": "SHP-12345",
                      "orderId": "770e8400-e29b-41d4-a716-446655440002"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "409": {
            "$ref": "#/components/responses/ConflictError"
          }
        }
      }
    },
    "/shipments/search": {
      "post": {
        "summary": "Search shipments",
        "description": "Search shipments using OpenSearch-powered full-text and field-specific search.\n\nThis endpoint provides fast, indexed search across shipment data with support for:\n- Full-text search across multiple fields (references, locations, parties)\n- Field-specific filtering with various operators\n- Sorting and pagination\n- Saved search preferences\n\n**Note:** Only active (non-deleted) shipments are searchable. Soft-deleted records are\nautomatically excluded from all search results.\n\n**Response Formats:**\n- `flat` (default): Returns indexed fields only for faster performance\n- `full`: Returns complete shipment objects with all relationships\n",
        "operationId": "searchShipments",
        "tags": [
          "Shipments"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ShipmentSearchRequest"
              },
              "examples": {
                "byCustomer": {
                  "summary": "Shipments for a customer",
                  "value": {
                    "criteria": {
                      "shipperName": {
                        "operator": "INCLUDES",
                        "values": [
                          "Acme"
                        ]
                      }
                    },
                    "pagination": {
                      "pageNumber": 1,
                      "pageSize": 50
                    }
                  }
                },
                "byStatus": {
                  "summary": "In-transit shipments",
                  "value": {
                    "criteria": {
                      "status": {
                        "operator": "ONE_OF",
                        "values": [
                          "IN_TRANSIT"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful search results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShipmentSearchResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitExceeded"
          }
        }
      }
    },
    "/shipments/filter": {
      "post": {
        "summary": "Filter shipments",
        "description": "Search for shipments using filter criteria.\n\nEach row in the response carries the fully nested shipment payload\n(orders with stops, freight, references, charges; loads with\ncarriers). With a large `pageSize`, responses can be sizable — use a\nsmaller page size if you only need scalar fields.\n\n## Common Filters\n\n- Active shipments: `{ \"filter\": { \"status\": { \"notIn\": [\"DELIVERED\", \"CANCELED\"] } } }`\n- Delivered today: `{ \"filter\": { \"deliveredAt\": { \"greaterThanOrEqualTo\": \"2025-01-15T00:00:00Z\" } } }`\n- By customer: `{ \"filter\": { \"customerId\": { \"equalTo\": \"uuid\" } } }`\n",
        "operationId": "filterShipments",
        "tags": [
          "Shipments"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ShipmentFilterRequest"
              },
              "examples": {
                "activeShipments": {
                  "summary": "Filter active shipments",
                  "value": {
                    "filter": {
                      "status": {
                        "notIn": [
                          "DELIVERED",
                          "CANCELED"
                        ]
                      }
                    },
                    "pageSize": 50
                  }
                },
                "inTransit": {
                  "summary": "Filter in-transit shipments",
                  "value": {
                    "filter": {
                      "status": {
                        "equalTo": "IN_TRANSIT"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Shipments matching filter criteria",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Shipment"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/PaginationInfo"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/shipments": {
      "post": {
        "summary": "Create a shipment",
        "description": "Create a new shipment with orders, loads, and services.\n\n## Required fields\n\n- `customer`: Reference to the customer\n- `orders`: At least one order with stops and mode\n\n## What gets created\n\n- Shipment record\n- Order(s) with stops, freight, and charges\n- Optionally: Load(s) and Service(s)\n\n## Relationship to Quotes\n\nIf you have a Quote, use `POST /quotes/{id}/convert-to-shipment` instead.\nDirect shipment creation is for cases without a quote.\n",
        "operationId": "createShipment",
        "tags": [
          "Shipments"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ShipmentInput"
              },
              "examples": {
                "basicShipment": {
                  "summary": "Basic FTL shipment",
                  "value": {
                    "customer": {
                      "id": "550e8400-e29b-41d4-a716-446655440000"
                    },
                    "orders": [
                      {
                        "mode": "FTL",
                        "stops": [
                          {
                            "type": "PICKUP",
                            "location": {
                              "id": "660e8400-e29b-41d4-a716-446655440001"
                            },
                            "requestedStartDate": "2025-01-20"
                          },
                          {
                            "type": "DELIVERY",
                            "location": {
                              "id": "770e8400-e29b-41d4-a716-446655440002"
                            },
                            "requestedStartDate": "2025-01-25"
                          }
                        ],
                        "freight": {
                          "handlingUnitQuantity": 10,
                          "handlingUnitType": "PALLET",
                          "weight": 15000
                        }
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Shipment created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Shipment"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/shipments/{id}": {
      "get": {
        "summary": "Get a shipment",
        "description": "Retrieve a shipment by ID or key.\n\nThe response includes embedded orders, loads, and services.\nThe internal ShipmentDetail layer is hidden - all data is flattened.\n",
        "operationId": "getShipment",
        "tags": [
          "Shipments"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Shipment retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Shipment"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      },
      "patch": {
        "summary": "Update a shipment",
        "description": "Update shipment fields.\n\n**Note:** To update orders, loads, or services, use their respective endpoints:\n- Orders: Updates happen via order-specific endpoints\n- Loads: PATCH /loads/{id}\n- Services: PATCH /services/{id}\n",
        "operationId": "updateShipment",
        "tags": [
          "Shipments"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ShipmentPatch"
              },
              "examples": {
                "changeCustomerRep": {
                  "summary": "Change customer rep",
                  "value": {
                    "customerRep": {
                      "id": "550e8400-e29b-41d4-a716-446655440001"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Shipment updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Shipment"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      },
      "delete": {
        "summary": "Delete a shipment",
        "description": "Soft delete a shipment.\n\nThe shipment and all associated orders, loads, and services are marked as deleted.\n",
        "operationId": "deleteShipment",
        "tags": [
          "Shipments"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "204": {
            "description": "Shipment deleted successfully"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/shipments/{id}/cancel": {
      "post": {
        "summary": "Cancel a shipment",
        "description": "Cancel a shipment.\n\n## What happens\n\n- Shipment status is set to CANCELED\n- All orders are canceled\n- All loads are canceled\n- All services are canceled\n\n## Prerequisites\n\n- Shipment must not already be delivered or canceled\n",
        "operationId": "cancelShipment",
        "tags": [
          "Shipments"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CancelShipmentRequest"
              },
              "examples": {
                "withReason": {
                  "summary": "Cancel with reason",
                  "value": {
                    "reason": "Customer requested cancellation due to production delay"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Shipment canceled successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Shipment"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "409": {
            "description": "Cannot cancel - shipment is delivered or already canceled",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/shipments/{id}/uncancel": {
      "post": {
        "summary": "Un-cancel a shipment",
        "description": "Reactivate a canceled shipment.\n\n## What happens\n\n- Shipment status is restored to previous state\n- Orders, loads, and services are reactivated\n\n## Prerequisites\n\n- Shipment must be in CANCELED status\n",
        "operationId": "uncancelShipment",
        "tags": [
          "Shipments"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Shipment un-canceled successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Shipment"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "409": {
            "description": "Cannot un-cancel - shipment is not canceled",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/shipments/{id}/duplicate": {
      "post": {
        "summary": "Duplicate a shipment",
        "description": "Create a copy of an existing shipment.\n\n## What gets duplicated\n\n- Customer and customer rep\n- Order(s) with stops, freight, and references\n- Equipment and special requirements\n\n## What is NOT duplicated\n\n- Loads and carriers\n- Services\n- Documents\n- Status history\n\n## New shipment\n\nThe duplicate is created in DRAFT status with new dates if provided.\n",
        "operationId": "duplicateShipment",
        "tags": [
          "Shipments"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DuplicateShipmentRequest"
              },
              "examples": {
                "withNewDates": {
                  "summary": "Duplicate with new dates",
                  "value": {
                    "pickUpDate": "2025-02-01",
                    "deliveryDate": "2025-02-05"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Shipment duplicated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DuplicateShipmentResponse"
                },
                "example": {
                  "originalShipmentId": "550e8400-e29b-41d4-a716-446655440000",
                  "newShipmentId": "660e8400-e29b-41d4-a716-446655440001",
                  "newShipmentKey": "SHP-12346"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/shipments/{id}/ready-to-invoice": {
      "post": {
        "summary": "Mark shipment ready to invoice",
        "description": "Mark a shipment as ready for invoicing.\n\n## What happens\n\n- Shipment billing status changes to READY_TO_INVOICE\n- Shipment is now visible in invoice generation workflows\n\n## Prerequisites\n\n- Shipment must have delivery documents attached\n- Shipment must be in DOCS_NEEDED or NOT_READY_TO_INVOICE status\n",
        "operationId": "markShipmentReadyToInvoice",
        "tags": [
          "Shipments"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Shipment marked ready to invoice",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Shipment"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "409": {
            "description": "Shipment not in valid status for this action",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/shipments/{id}/not-ready-to-invoice": {
      "post": {
        "summary": "Revert shipment to not ready",
        "description": "Revert a shipment from ready-to-invoice back to not ready.\n\n## What happens\n\n- Shipment billing status changes back to NOT_READY_TO_INVOICE\n\n## Prerequisites\n\n- Shipment must be in READY_TO_INVOICE status\n- Shipment must not already be invoiced\n",
        "operationId": "markShipmentNotReadyToInvoice",
        "tags": [
          "Shipments"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Shipment reverted to not ready",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Shipment"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "409": {
            "description": "Shipment not in valid status for this action",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/shipments/{id}/invoice/generate": {
      "post": {
        "summary": "Generate invoice for shipment",
        "description": "Generate an invoice PDF for the shipment.\n\n## What happens\n\n- Invoice PDF is generated\n- Invoice document is attached to the shipment\n- Shipment billing status changes to INVOICED\n\n## Prerequisites\n\n- Shipment must be in READY_TO_INVOICE status\n",
        "operationId": "generateShipmentInvoice",
        "tags": [
          "Shipments"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Invoice generated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "shipmentId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "invoiceId": {
                      "type": "string",
                      "format": "uuid",
                      "description": "The generated invoice ID"
                    },
                    "documentId": {
                      "type": "string",
                      "format": "uuid",
                      "description": "The invoice PDF document ID"
                    },
                    "downloadUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "URL to download the invoice PDF"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "409": {
            "description": "Shipment not in valid status for invoice generation",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/loads/filter": {
      "post": {
        "summary": "Filter loads",
        "description": "Search for loads using filter criteria.\n\nEach row carries the fully nested load payload (stops with addresses,\ncarriers with charges). With a large `pageSize`, responses can be\nsizable.\n\n## Common Filters\n\n- By shipment: `{ \"filter\": { \"shipmentId\": { \"equalTo\": \"uuid\" } } }`\n- Active loads: `{ \"filter\": { \"status\": { \"notIn\": [\"COMPLETE\", \"CANCELED\"] } } }`\n- FTL loads: `{ \"filter\": { \"mode\": { \"equalTo\": \"FTL\" } } }`\n",
        "operationId": "filterLoads",
        "tags": [
          "Loads"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoadFilterRequest"
              },
              "examples": {
                "byShipment": {
                  "summary": "Filter by shipment",
                  "value": {
                    "filter": {
                      "shipmentId": {
                        "equalTo": "550e8400-e29b-41d4-a716-446655440000"
                      }
                    }
                  }
                },
                "activeLoads": {
                  "summary": "Active loads only",
                  "value": {
                    "filter": {
                      "status": {
                        "notIn": [
                          "COMPLETE",
                          "CANCELED"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Loads matching filter criteria",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Load"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/PaginationInfo"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/loads": {
      "post": {
        "summary": "Add an additional load",
        "description": "Add an additional load to an **existing shipment**. This endpoint\nrequires a shipment — it cannot create one. Creating a shipment\nalready creates its first load structure; use this endpoint only for\nmulti-load scenarios (extra legs, split moves).\n\n## What happens\n\n- Load is created for the specified shipment\n- Optionally assigns an initial carrier\n\nTo book a carrier on a load afterwards, use the load-carrier\nendpoints — that is the primary booking flow.\n",
        "operationId": "createLoad",
        "tags": [
          "Loads"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "shipmentId",
                  "load"
                ],
                "properties": {
                  "shipmentId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Parent shipment ID"
                  },
                  "load": {
                    "$ref": "#/components/schemas/LoadInput"
                  }
                }
              },
              "examples": {
                "basicLoad": {
                  "summary": "Create FTL load",
                  "value": {
                    "shipmentId": "550e8400-e29b-41d4-a716-446655440000",
                    "load": {
                      "mode": "FTL"
                    }
                  }
                },
                "withCarrier": {
                  "summary": "Create load with carrier",
                  "value": {
                    "shipmentId": "550e8400-e29b-41d4-a716-446655440000",
                    "load": {
                      "mode": "FTL",
                      "carrier": {
                        "carrier": {
                          "id": "660e8400-e29b-41d4-a716-446655440001"
                        },
                        "charges": [
                          {
                            "chargeCode": {
                              "key": "LINEHAUL"
                            },
                            "amount": 2000
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Load created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Load"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/loads/{id}": {
      "get": {
        "summary": "Get a load",
        "description": "Retrieve a load by ID.\n\nThe response includes embedded carriers and stops.\n",
        "operationId": "getLoad",
        "tags": [
          "Loads"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Load retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Load"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      },
      "patch": {
        "summary": "Update a load",
        "description": "Update load fields.\n\n**Note:** To manage carriers, use the carrier-specific endpoints.\n",
        "operationId": "updateLoad",
        "tags": [
          "Loads"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoadPatch"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Load updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Load"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      },
      "delete": {
        "summary": "Delete a load",
        "description": "Soft delete a load.\n\n## Prerequisites\n\n- Load must not have any active carriers\n",
        "operationId": "deleteLoad",
        "tags": [
          "Loads"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "204": {
            "description": "Load deleted successfully"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "409": {
            "description": "Cannot delete - load has active carriers",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/loads/{id}/add-carrier": {
      "post": {
        "summary": "Add carrier to load",
        "description": "Add an additional carrier to a load.\n\n## Use cases\n\n- Split loads (multiple carriers for same load)\n- Adding backup carrier\n- Re-assigning after TONU/bounce\n\n## What happens\n\n- New LoadCarrier record is created\n- Carrier is notified (if configured)\n",
        "operationId": "addCarrierToLoad",
        "tags": [
          "Loads"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoadCarrierInput"
              },
              "examples": {
                "addCarrier": {
                  "summary": "Add carrier with costs",
                  "value": {
                    "carrier": {
                      "id": "550e8400-e29b-41d4-a716-446655440000"
                    },
                    "contact": {
                      "id": "660e8400-e29b-41d4-a716-446655440001"
                    },
                    "charges": [
                      {
                        "chargeCode": {
                          "key": "LINEHAUL"
                        },
                        "amount": 2000
                      }
                    ],
                    "driverName": "John Smith",
                    "driverPhone": "+15551234567"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Carrier added successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AddCarrierResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/loads/{id}/rebook": {
      "post": {
        "summary": "Rebook a TONU load",
        "description": "Create a new load to replace a TONU'd load.\n\n## Use case\n\nAfter a carrier reports TONU, use this to create a replacement load\nthat can be assigned to a new carrier.\n\n## What happens\n\n- New Load is created with same stops\n- Original load remains in TONU status\n- New load is ready for carrier assignment\n",
        "operationId": "rebookLoad",
        "tags": [
          "Loads"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "201": {
            "description": "Load rebooked successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RebookLoadResponse"
                },
                "example": {
                  "originalLoadId": "550e8400-e29b-41d4-a716-446655440000",
                  "newLoadId": "660e8400-e29b-41d4-a716-446655440001",
                  "newLoadKey": "LD-12346"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "409": {
            "description": "Load is not in TONU status",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/loads/{loadId}/carriers/{carrierId}": {
      "get": {
        "summary": "Get load carrier",
        "description": "Retrieve a specific carrier assignment for a load.",
        "operationId": "getLoadCarrier",
        "tags": [
          "Loads"
        ],
        "parameters": [
          {
            "name": "loadId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Load ID"
          },
          {
            "name": "carrierId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "LoadCarrier ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Load carrier retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LoadCarrier"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      },
      "patch": {
        "summary": "Update load carrier",
        "description": "Update carrier assignment details.\n\nUse this to update driver info, truck/trailer numbers, or contact.\n",
        "operationId": "updateLoadCarrier",
        "tags": [
          "Loads"
        ],
        "parameters": [
          {
            "name": "loadId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "carrierId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoadCarrierPatch"
              },
              "examples": {
                "updateDriver": {
                  "summary": "Update driver info",
                  "value": {
                    "driverName": "Jane Doe",
                    "driverPhone": "+15559876543",
                    "truckNumber": "TRK-123",
                    "trailerNumber": "TRL-456"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Load carrier updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LoadCarrier"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/loads/{loadId}/carriers/{carrierId}/bounce": {
      "post": {
        "summary": "Bounce carrier",
        "description": "Mark carrier as bounced (rejected load without payment).\n\n## What happens\n\n- LoadCarrier status changes to BOUNCED\n- Carrier is removed from active execution\n- No payment is recorded\n\n## When to use\n\nUse bounce when carrier rejects the load before dispatch,\nor fails to show up without prior notice.\n\nFor carriers who were dispatched but cancelled, use TONU instead.\n",
        "operationId": "bounceCarrier",
        "tags": [
          "Loads"
        ],
        "parameters": [
          {
            "name": "loadId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "carrierId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BounceCarrierRequest"
              },
              "examples": {
                "bounceWithReason": {
                  "summary": "Bounce with reason",
                  "value": {
                    "reason": "CAN_NO_LONGER_TAKE_LOAD",
                    "reasonText": "Driver did not show up at scheduled time"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Carrier bounced successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LoadCarrier"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "409": {
            "description": "Carrier is not in valid status for bounce",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/loads/{loadId}/carriers/{carrierId}/tonu": {
      "post": {
        "summary": "Report TONU",
        "description": "Report Truck Ordered Not Used (TONU).\n\n## What happens\n\n- LoadCarrier status changes to TONU\n- TONU costs are recorded if provided\n- Optionally creates a replacement load\n\n## When to use\n\nUse TONU when:\n- Carrier was dispatched but load was cancelled\n- Carrier arrived but freight wasn't ready\n- Carrier was turned away at shipper\n\nTONU typically involves some payment to the carrier.\n",
        "operationId": "reportTonu",
        "tags": [
          "Loads"
        ],
        "parameters": [
          {
            "name": "loadId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "carrierId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReportTonuRequest"
              },
              "examples": {
                "tonuWithCosts": {
                  "summary": "TONU with costs",
                  "value": {
                    "reason": "Freight not ready at shipper",
                    "costs": [
                      {
                        "chargeCode": {
                          "key": "TONU"
                        },
                        "amount": 250,
                        "description": "TONU fee"
                      }
                    ],
                    "createReplacementLoad": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "TONU reported successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "loadCarrier": {
                      "$ref": "#/components/schemas/LoadCarrier"
                    },
                    "replacementLoadId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "uuid",
                      "description": "New load ID if replacement was requested"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "409": {
            "description": "Carrier is not in valid status for TONU",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/services/filter": {
      "post": {
        "summary": "Filter services",
        "description": "Search for services using filter criteria.\n\n## Common Filters\n\n- By shipment: `{ \"filter\": { \"shipmentId\": { \"equalTo\": \"uuid\" } } }`\n- By vendor: `{ \"filter\": { \"vendorId\": { \"equalTo\": \"uuid\" } } }`\n- Awaiting invoice: `{ \"filter\": { \"status\": { \"equalTo\": \"AWAITING_INVOICE\" } } }`\n",
        "operationId": "filterServices",
        "tags": [
          "Services"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ServiceFilterRequest"
              },
              "examples": {
                "byShipment": {
                  "summary": "Filter by shipment",
                  "value": {
                    "filter": {
                      "shipmentId": {
                        "equalTo": "550e8400-e29b-41d4-a716-446655440000"
                      }
                    }
                  }
                },
                "awaitingInvoice": {
                  "summary": "Awaiting invoice",
                  "value": {
                    "filter": {
                      "status": {
                        "equalTo": "AWAITING_INVOICE"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Services matching filter criteria",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Service"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/PaginationInfo"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/services": {
      "post": {
        "summary": "Create a service",
        "description": "Create a new service for a shipment.\n\n## What happens\n\n- Service is created for the specified shipment\n- Vendor is associated with the service\n- Charges are recorded\n\n## Note\n\nServices are typically created as part of shipment creation.\nUse this endpoint to add additional services to an existing shipment.\n",
        "operationId": "createService",
        "tags": [
          "Services"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "shipmentId",
                  "service"
                ],
                "properties": {
                  "shipmentId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Parent shipment ID"
                  },
                  "service": {
                    "$ref": "#/components/schemas/ServiceInput"
                  }
                }
              },
              "examples": {
                "drayageService": {
                  "summary": "Create drayage service",
                  "value": {
                    "shipmentId": "550e8400-e29b-41d4-a716-446655440000",
                    "service": {
                      "vendor": {
                        "id": "660e8400-e29b-41d4-a716-446655440001"
                      },
                      "description": "Port drayage from Long Beach",
                      "charges": [
                        {
                          "chargeCode": {
                            "key": "DRAY"
                          },
                          "amount": 450
                        }
                      ],
                      "scheduledDate": "2025-01-20"
                    }
                  }
                },
                "customsService": {
                  "summary": "Create customs service",
                  "value": {
                    "shipmentId": "550e8400-e29b-41d4-a716-446655440000",
                    "service": {
                      "vendor": {
                        "id": "770e8400-e29b-41d4-a716-446655440002"
                      },
                      "description": "Import customs clearance",
                      "charges": [
                        {
                          "chargeCode": {
                            "key": "CUSTOMS"
                          },
                          "amount": 175
                        }
                      ],
                      "referenceNumber": "CB-2025-1234"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Service created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Service"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/services/{id}": {
      "get": {
        "summary": "Get a service",
        "description": "Retrieve a service by ID.\n\nThe response includes vendor info and charges.\n",
        "operationId": "getService",
        "tags": [
          "Services"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Service retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Service"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      },
      "patch": {
        "summary": "Update a service",
        "description": "Update service fields.\n\n**Note:** Status changes happen automatically based on billing workflow.\n",
        "operationId": "updateService",
        "tags": [
          "Services"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ServicePatch"
              },
              "examples": {
                "updateSchedule": {
                  "summary": "Update scheduled date",
                  "value": {
                    "scheduledDate": "2025-01-22"
                  }
                },
                "markComplete": {
                  "summary": "Mark as completed",
                  "value": {
                    "completedDate": "2025-01-20"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Service updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Service"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      },
      "delete": {
        "summary": "Delete a service",
        "description": "Soft delete a service.\n\n## Prerequisites\n\n- Service must not be paid\n",
        "operationId": "deleteService",
        "tags": [
          "Services"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "204": {
            "description": "Service deleted successfully"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "409": {
            "description": "Cannot delete - service is paid",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/invoices/filter": {
      "post": {
        "summary": "Filter invoices",
        "description": "Search for AR invoices using filter criteria.\n\n## Common Filters\n\n- By customer: `{ \"filter\": { \"customerId\": { \"equalTo\": \"uuid\" } } }`\n- Unpaid: `{ \"filter\": { \"status\": { \"in\": [\"AWAITING_PAYMENT\", \"PARTIALLY_PAID\"] } } }`\n- Overdue: `{ \"filter\": { \"overdue\": true } }`\n- By shipment: `{ \"filter\": { \"shipmentId\": { \"equalTo\": \"uuid\" } } }`\n",
        "operationId": "filterInvoices",
        "tags": [
          "Invoices"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InvoiceFilterRequest"
              },
              "examples": {
                "unpaidInvoices": {
                  "summary": "Unpaid invoices",
                  "value": {
                    "filter": {
                      "status": {
                        "in": [
                          "AWAITING_PAYMENT",
                          "PARTIALLY_PAID"
                        ]
                      }
                    }
                  }
                },
                "overdueByCustomer": {
                  "summary": "Overdue invoices for customer",
                  "value": {
                    "filter": {
                      "customerId": {
                        "equalTo": "550e8400-e29b-41d4-a716-446655440000"
                      },
                      "overdue": true
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Invoices matching filter criteria",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Invoice"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/PaginationInfo"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/invoices": {
      "post": {
        "summary": "Create an invoice",
        "description": "Create a new invoice for an order.\n\n## What happens\n\n- Invoice record is created for the order\n- Order status updates to `DELIVERED_UNPAID`\n- Due date calculated from payment term if not provided\n\n## Note\n\nEach shipment can have only one AR invoice. Use `POST /shipments/{id}/invoice/generate`\nto generate the invoice PDF document.\n",
        "operationId": "createInvoice",
        "tags": [
          "Invoices"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InvoiceInput"
              },
              "examples": {
                "basic": {
                  "summary": "Create invoice",
                  "value": {
                    "orderId": "550e8400-e29b-41d4-a716-446655440000",
                    "invoiceDate": "2025-01-15",
                    "dueDate": "2025-02-14",
                    "amount": 2500,
                    "currency": "USD"
                  }
                },
                "withTerm": {
                  "summary": "With payment term",
                  "value": {
                    "orderId": "550e8400-e29b-41d4-a716-446655440000",
                    "invoiceDate": "2025-01-15",
                    "amount": 2500,
                    "paymentTermId": "660e8400-e29b-41d4-a716-446655440001"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Invoice created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invoice"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "409": {
            "description": "Order already has an invoice",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/invoices/{id}": {
      "get": {
        "summary": "Get an invoice",
        "description": "Retrieve an invoice by ID.\n\nThe response includes payments, credits, and document info.\n",
        "operationId": "getInvoice",
        "tags": [
          "Invoices"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Invoice retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invoice"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      },
      "patch": {
        "summary": "Update an invoice",
        "description": "Update invoice fields.\n\n**Note:** Amount cannot be changed directly. Update order charges instead.\n",
        "operationId": "updateInvoice",
        "tags": [
          "Invoices"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InvoicePatch"
              },
              "examples": {
                "updateDueDate": {
                  "summary": "Update due date",
                  "value": {
                    "dueDate": "2025-02-28"
                  }
                },
                "updateReference": {
                  "summary": "Update reference",
                  "value": {
                    "reference": "INV-CUST-123-REV"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Invoice updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invoice"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      },
      "delete": {
        "summary": "Void an invoice",
        "description": "Void/cancel an invoice.\n\n## Prerequisites\n\n- Invoice must not have any payments applied\n- Invoice must not be factored\n",
        "operationId": "voidInvoice",
        "tags": [
          "Invoices"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "204": {
            "description": "Invoice voided successfully"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "409": {
            "description": "Cannot void - invoice has payments or is factored",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/invoices/{id}/mark-awaiting": {
      "post": {
        "summary": "Mark invoice as awaiting payment",
        "description": "Mark invoice as awaiting payment.\n\n## What happens\n\n- Sets invoice date and due date\n- Updates order status to `DELIVERED_UNPAID`\n- Invoice is now ready for payment collection\n",
        "operationId": "markInvoiceAwaiting",
        "tags": [
          "Invoices"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MarkAwaitingPaymentRequest"
              },
              "examples": {
                "withDates": {
                  "summary": "With dates",
                  "value": {
                    "invoiceDate": "2025-01-15",
                    "dueDate": "2025-02-14"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Invoice marked as awaiting payment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invoice"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/invoices/{id}/send": {
      "post": {
        "summary": "Email invoice",
        "description": "Send invoice to customer via email.\n\n## What happens\n\n- Generates invoice PDF if not already generated\n- Sends email with PDF attachment\n- Logs email in activity feed\n",
        "operationId": "sendInvoiceEmail",
        "tags": [
          "Invoices"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendInvoiceEmailRequest"
              },
              "examples": {
                "basic": {
                  "summary": "Basic email",
                  "value": {
                    "toEmails": [
                      "billing@customer.com"
                    ]
                  }
                },
                "withMessage": {
                  "summary": "With custom message",
                  "value": {
                    "toEmails": [
                      "billing@customer.com"
                    ],
                    "ccEmails": [
                      "accounts@broker.com"
                    ],
                    "subject": "Invoice INV-00001 for Shipment SHP-00123",
                    "message": "Please find attached your invoice for recent shipment services."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Email sent successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "emailId": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/invoices/{id}/payments": {
      "get": {
        "summary": "Get invoice payments",
        "description": "List all payments applied to a specific invoice.",
        "operationId": "getInvoicePayments",
        "tags": [
          "Invoices"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Payments retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/InvoicePayment"
                      }
                    },
                    "totalPaid": {
                      "type": "number"
                    },
                    "openBalance": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/invoices/batch-generate": {
      "post": {
        "summary": "Batch generate invoices",
        "description": "Generate invoices for multiple shipments in a single request.\n\n## What happens\n\n- Creates invoice records for each shipment\n- Generates PDF documents\n- Optionally sends emails grouped by customer\n\n## Note\n\nShipments that already have invoices or are missing requirements\nwill be skipped and returned in the `failed` array.\n",
        "operationId": "batchGenerateInvoices",
        "tags": [
          "Invoices"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchGenerateInvoicesRequest"
              },
              "examples": {
                "basic": {
                  "summary": "Generate only",
                  "value": {
                    "orderIds": [
                      "550e8400-e29b-41d4-a716-446655440000",
                      "550e8400-e29b-41d4-a716-446655440001"
                    ]
                  }
                },
                "withEmail": {
                  "summary": "Generate and email",
                  "value": {
                    "orderIds": [
                      "550e8400-e29b-41d4-a716-446655440000",
                      "550e8400-e29b-41d4-a716-446655440001"
                    ],
                    "sendEmail": true,
                    "emailConfig": {
                      "groupByCustomer": true
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch generation completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchGenerateInvoicesResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    },
    "/invoices/aging-report": {
      "get": {
        "summary": "Get aging report",
        "description": "Generate accounts receivable aging report.\n\n## Report buckets\n\nBy default: Current, 1-30, 31-60, 61-90, 90+ days\n\n## Export formats\n\n- JSON (default)\n- CSV (set Accept header to text/csv)\n",
        "operationId": "getAgingReport",
        "tags": [
          "Invoices"
        ],
        "parameters": [
          {
            "name": "customerId",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter by specific customer"
          },
          {
            "name": "daysPerBucket",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 30
            },
            "description": "Days per aging bucket"
          },
          {
            "name": "maxDays",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 120
            },
            "description": "Maximum days to track"
          }
        ],
        "responses": {
          "200": {
            "description": "Aging report generated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgingReportResponse"
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    },
    "/payments/filter": {
      "post": {
        "summary": "Filter payments",
        "description": "Search for AR payments using filter criteria.\n\n## Common Filters\n\n- By customer: `{ \"filter\": { \"customerId\": { \"equalTo\": \"uuid\" } } }`\n- By invoice: `{ \"filter\": { \"invoiceId\": { \"equalTo\": \"uuid\" } } }`\n- By date range: `{ \"filter\": { \"paymentDate\": { \"greaterThanOrEqualTo\": \"2025-01-01\" } } }`\n- By method: `{ \"filter\": { \"paymentMethodType\": { \"equalTo\": \"check\" } } }`\n",
        "operationId": "filterPayments",
        "tags": [
          "Payments"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentFilterRequest"
              },
              "examples": {
                "byCustomer": {
                  "summary": "Filter by customer",
                  "value": {
                    "filter": {
                      "customerId": {
                        "equalTo": "550e8400-e29b-41d4-a716-446655440000"
                      }
                    }
                  }
                },
                "byDateRange": {
                  "summary": "Filter by date range",
                  "value": {
                    "filter": {
                      "paymentDate": {
                        "greaterThanOrEqualTo": "2025-01-01T00:00:00Z",
                        "lessThanOrEqualTo": "2025-01-31T23:59:59Z"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payments matching filter criteria",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Payment"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/PaginationInfo"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/payments": {
      "post": {
        "summary": "Create a payment",
        "description": "Record a customer payment applied to invoices.\n\n## What happens\n\n- Payment record is created\n- Specified amounts are applied to invoices\n- Invoice/order status updated to `PAID` when fully paid\n- Overpayment creates a credit memo automatically\n\n## Validations\n\n- Payment date must be >= invoice date for all applied invoices\n- Application amounts must not exceed invoice open balances\n- Customer must match invoice customer\n",
        "operationId": "createPayment",
        "tags": [
          "Payments"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentInput"
              },
              "examples": {
                "singleInvoice": {
                  "summary": "Single invoice payment",
                  "value": {
                    "customerId": "550e8400-e29b-41d4-a716-446655440000",
                    "paymentDate": "2025-01-15",
                    "paymentMethodType": "CHECK",
                    "reference": "CHK-12345",
                    "applications": [
                      {
                        "invoiceId": "660e8400-e29b-41d4-a716-446655440001",
                        "amount": 2500
                      }
                    ]
                  }
                },
                "multipleInvoices": {
                  "summary": "Multiple invoices",
                  "value": {
                    "customerId": "550e8400-e29b-41d4-a716-446655440000",
                    "paymentDate": "2025-01-15",
                    "paymentMethodType": "ACH_WIRE",
                    "reference": "ACH-98765",
                    "notes": "January payment batch",
                    "applications": [
                      {
                        "invoiceId": "660e8400-e29b-41d4-a716-446655440001",
                        "amount": 1500
                      },
                      {
                        "invoiceId": "660e8400-e29b-41d4-a716-446655440002",
                        "amount": 2500
                      }
                    ]
                  }
                },
                "withCredits": {
                  "summary": "With credits applied",
                  "value": {
                    "customerId": "550e8400-e29b-41d4-a716-446655440000",
                    "paymentDate": "2025-01-15",
                    "paymentMethodType": "CHECK",
                    "reference": "CHK-12345",
                    "applications": [
                      {
                        "invoiceId": "660e8400-e29b-41d4-a716-446655440001",
                        "amount": 2000
                      }
                    ],
                    "creditApplications": [
                      {
                        "creditMemoId": "770e8400-e29b-41d4-a716-446655440003",
                        "amount": 500
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Payment created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Payment"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/payments/{id}": {
      "get": {
        "summary": "Get a payment",
        "description": "Retrieve a payment by ID.\n\nThe response includes all invoice applications and credit applications.\n",
        "operationId": "getPayment",
        "tags": [
          "Payments"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Payment retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Payment"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      },
      "patch": {
        "summary": "Update a payment",
        "description": "Update payment details or reassign invoice applications.\n\n## What happens\n\n- Payment fields are updated\n- Invoice applications are replaced if provided\n- Order statuses are recalculated\n\n## Note\n\nUpdating applications replaces all existing applications.\nInclude all desired applications in the request.\n",
        "operationId": "updatePayment",
        "tags": [
          "Payments"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentPatch"
              },
              "examples": {
                "updateReference": {
                  "summary": "Update reference",
                  "value": {
                    "reference": "CHK-12345-REV",
                    "notes": "Corrected check number"
                  }
                },
                "updateMethod": {
                  "summary": "Update method",
                  "value": {
                    "paymentMethodType": "ACH_WIRE"
                  }
                },
                "reassignApplications": {
                  "summary": "Reassign to different invoices",
                  "value": {
                    "applications": [
                      {
                        "invoiceId": "660e8400-e29b-41d4-a716-446655440001",
                        "amount": 1500
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Payment"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      },
      "delete": {
        "summary": "Delete a payment",
        "description": "Delete a payment and remove all invoice applications.\n\n## What happens\n\n- Payment record is deleted\n- Invoice applications are removed\n- Order statuses revert if needed (PAID → UNPAID)\n\n## Note\n\nThis action cannot be undone. Consider voiding instead\nif you need to maintain a record.\n",
        "operationId": "deletePayment",
        "tags": [
          "Payments"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "204": {
            "description": "Payment deleted successfully"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "409": {
            "description": "Cannot delete - payment is synced to QBO",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/payments/{id}/applications": {
      "get": {
        "summary": "Get payment applications",
        "description": "List all invoice applications for a payment.",
        "operationId": "getPaymentApplications",
        "tags": [
          "Payments"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Applications retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PaymentApplication"
                      }
                    },
                    "totalApplied": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/customers/{id}/payments": {
      "get": {
        "summary": "Get customer payments",
        "description": "List all payments from a specific customer.",
        "operationId": "getCustomerPayments",
        "tags": [
          "Customers"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Payments retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Payment"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/PaginationInfo"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/customers/{id}/outstanding-invoices": {
      "get": {
        "summary": "Get outstanding invoices",
        "description": "List invoices available for payment from a customer.\n\nReturns invoices with status `AWAITING_PAYMENT` or `PARTIALLY_PAID`.\n",
        "operationId": "getCustomerOutstandingInvoices",
        "tags": [
          "Customers"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Outstanding invoices retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OutstandingInvoicesResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/credit-memos/filter": {
      "post": {
        "summary": "Filter credit memos",
        "description": "Search for credit memos using filter criteria.\n\n## Common Filters\n\n- By customer: `{ \"filter\": { \"customerId\": { \"equalTo\": \"uuid\" } } }`\n- With balance: `{ \"filter\": { \"hasRemainingBalance\": true } }`\n- Open credits: `{ \"filter\": { \"status\": { \"in\": [\"OPEN\", \"PARTIALLY_APPLIED\"] } } }`\n",
        "operationId": "filterCreditMemos",
        "tags": [
          "Credit Memos"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreditMemoFilterRequest"
              },
              "examples": {
                "byCustomer": {
                  "summary": "Filter by customer",
                  "value": {
                    "filter": {
                      "customerId": {
                        "equalTo": "550e8400-e29b-41d4-a716-446655440000"
                      }
                    }
                  }
                },
                "availableCredits": {
                  "summary": "Credits with balance",
                  "value": {
                    "filter": {
                      "hasRemainingBalance": true,
                      "status": {
                        "notEqualTo": "VOIDED"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Credit memos matching filter criteria",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CreditMemo"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/PaginationInfo"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/credit-memos": {
      "post": {
        "summary": "Create a credit memo",
        "description": "Create a new credit memo for a customer.\n\n## Use cases\n\n- Customer refunds\n- Service adjustments\n- Promotional credits\n- Manual corrections\n\n## Note\n\nCredit memos from overpayments are created automatically\nwhen a payment exceeds invoice totals.\n",
        "operationId": "createCreditMemo",
        "tags": [
          "Credit Memos"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreditMemoInput"
              },
              "examples": {
                "refund": {
                  "summary": "Customer refund",
                  "value": {
                    "customerId": "550e8400-e29b-41d4-a716-446655440000",
                    "amount": 500,
                    "currency": "USD",
                    "memoDate": "2025-01-15",
                    "reference": "CM-00001",
                    "notes": "Refund for damaged goods"
                  }
                },
                "adjustment": {
                  "summary": "Service adjustment",
                  "value": {
                    "customerId": "550e8400-e29b-41d4-a716-446655440000",
                    "amount": 150,
                    "memoDate": "2025-01-15",
                    "notes": "Price adjustment per agreement"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Credit memo created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreditMemo"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/credit-memos/{id}": {
      "get": {
        "summary": "Get a credit memo",
        "description": "Retrieve a credit memo by ID.\n\nThe response includes all applications showing how the credit has been used.\n",
        "operationId": "getCreditMemo",
        "tags": [
          "Credit Memos"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Credit memo retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreditMemo"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      },
      "patch": {
        "summary": "Update a credit memo",
        "description": "Update credit memo fields.\n\n## Constraints\n\n- Amount cannot be changed if any applications exist\n- Customer cannot be changed once created\n",
        "operationId": "updateCreditMemo",
        "tags": [
          "Credit Memos"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreditMemoPatch"
              },
              "examples": {
                "updateReference": {
                  "summary": "Update reference",
                  "value": {
                    "reference": "CM-00001-REV"
                  }
                },
                "updateNotes": {
                  "summary": "Update notes",
                  "value": {
                    "notes": "Updated: Refund for damaged goods and shipping issues"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Credit memo updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreditMemo"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/credit-memos/{id}/void": {
      "post": {
        "summary": "Void a credit memo",
        "description": "Void/cancel a credit memo.\n\n## Prerequisites\n\n- Credit memo must have no applications (full balance remaining)\n- Must unapply all applications before voiding\n\n## What happens\n\n- Credit memo status changes to VOIDED\n- Credit is no longer available for application\n- QBO sync will delete the credit memo\n",
        "operationId": "voidCreditMemo",
        "tags": [
          "Credit Memos"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VoidCreditMemoRequest"
              },
              "examples": {
                "withReason": {
                  "summary": "Void with reason",
                  "value": {
                    "reason": "Credit issued in error"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Credit memo voided successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreditMemo"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "409": {
            "description": "Cannot void - credit memo has applications",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/credit-memos/{id}/apply": {
      "post": {
        "summary": "Apply credit to invoice",
        "description": "Apply credit memo amount to an invoice.\n\n## What happens\n\n- Creates credit application record\n- Reduces credit memo remaining balance\n- Reduces invoice open balance\n- Updates order status if invoice is fully paid\n\n## Constraints\n\n- Amount must not exceed remaining balance\n- Invoice must belong to same customer\n- Invoice must have outstanding balance\n- Currency must match\n",
        "operationId": "applyCreditMemo",
        "tags": [
          "Credit Memos"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApplyCreditRequest"
              },
              "examples": {
                "applyCredit": {
                  "summary": "Apply credit",
                  "value": {
                    "invoiceId": "660e8400-e29b-41d4-a716-446655440001",
                    "amount": 200
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Credit applied successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApplyCreditResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "409": {
            "description": "Cannot apply - insufficient balance or invalid invoice",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/credit-memos/{id}/applications": {
      "get": {
        "summary": "Get credit applications",
        "description": "List all invoice applications for a credit memo.",
        "operationId": "getCreditMemoApplications",
        "tags": [
          "Credit Memos"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Applications retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CreditMemoApplication"
                      }
                    },
                    "totalApplied": {
                      "type": "number"
                    },
                    "remainingBalance": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/credit-memos/{creditMemoId}/applications/{applicationId}": {
      "delete": {
        "summary": "Unapply credit from invoice",
        "description": "Remove a credit application from an invoice.\n\n## What happens\n\n- Application record is deleted\n- Credit memo remaining balance increases\n- Invoice open balance increases\n- Order status may revert if invoice becomes unpaid\n",
        "operationId": "unapplyCreditMemo",
        "tags": [
          "Credit Memos"
        ],
        "parameters": [
          {
            "name": "creditMemoId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Credit memo ID"
          },
          {
            "name": "applicationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Application ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Credit unapplied successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreditMemo"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/invoices/{id}/available-credits": {
      "get": {
        "summary": "Get available credits for invoice",
        "description": "List credit memos that can be applied to an invoice.\n\nReturns credits for the same customer with remaining balance\nand matching currency.\n",
        "operationId": "getAvailableCreditsForInvoice",
        "tags": [
          "Invoices"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Available credits retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AvailableCreditsResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/bills/filter": {
      "post": {
        "summary": "Filter bills",
        "description": "Search for AP bills using filter criteria.\n\n## Common Filters\n\n- By carrier: `{ \"filter\": { \"carrierId\": { \"equalTo\": \"uuid\" } } }`\n- By vendor: `{ \"filter\": { \"vendorId\": { \"equalTo\": \"uuid\" } } }`\n- Awaiting approval: `{ \"filter\": { \"status\": { \"equalTo\": \"IN_REVIEW\" } } }`\n- By shipment: `{ \"filter\": { \"shipmentId\": { \"equalTo\": \"uuid\" } } }`\n- Overdue: `{ \"filter\": { \"overdue\": true } }`\n",
        "operationId": "filterBills",
        "tags": [
          "Bills"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BillFilterRequest"
              },
              "examples": {
                "awaitingApproval": {
                  "summary": "Bills awaiting approval",
                  "value": {
                    "filter": {
                      "status": {
                        "equalTo": "IN_REVIEW"
                      }
                    }
                  }
                },
                "byCarrier": {
                  "summary": "Bills by carrier",
                  "value": {
                    "filter": {
                      "carrierId": {
                        "equalTo": "550e8400-e29b-41d4-a716-446655440000"
                      },
                      "entityType": {
                        "equalTo": "CARRIER"
                      }
                    }
                  }
                },
                "approvedToPay": {
                  "summary": "Bills approved to pay",
                  "value": {
                    "filter": {
                      "status": {
                        "equalTo": "APPROVED_TO_PAY"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bills matching filter criteria",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Bill"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/PaginationInfo"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/bills": {
      "post": {
        "summary": "Record a bill",
        "description": "Record a carrier or vendor bill (invoice).\n\n## What happens\n\n- Bill record is created for the load carrier or vended service\n- Entity status updates to `IN_REVIEW`\n- Due date calculated from payment term if not provided\n\n## Prerequisites\n\n- LoadCarrier or VendedService must exist\n- Entity must be in `AWAITING_INVOICE` status\n",
        "operationId": "createBill",
        "tags": [
          "Bills"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BillInput"
              },
              "examples": {
                "carrierBill": {
                  "summary": "Record carrier bill",
                  "value": {
                    "entityType": "CARRIER",
                    "entityId": "550e8400-e29b-41d4-a716-446655440000",
                    "invoiceDate": "2025-01-15",
                    "dueDate": "2025-02-14",
                    "amount": 2500,
                    "reference": "INV-CARRIER-123",
                    "currency": "USD"
                  }
                },
                "vendorBill": {
                  "summary": "Record vendor bill",
                  "value": {
                    "entityType": "VENDOR",
                    "entityId": "660e8400-e29b-41d4-a716-446655440001",
                    "invoiceDate": "2025-01-15",
                    "amount": 500,
                    "reference": "VS-2025-001"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Bill created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Bill"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "409": {
            "description": "Entity already has a bill or is not in correct status",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/bills/{id}": {
      "get": {
        "summary": "Get a bill",
        "description": "Retrieve a bill by ID.\n\nThe response includes payments applied and carrier/vendor details.\n",
        "operationId": "getBill",
        "tags": [
          "Bills"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Bill retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Bill"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      },
      "patch": {
        "summary": "Update a bill",
        "description": "Update bill fields.\n\n## Constraints\n\n- Cannot change amount if payments have been applied\n- Status changes use action endpoints\n",
        "operationId": "updateBill",
        "tags": [
          "Bills"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BillPatch"
              },
              "examples": {
                "updateDueDate": {
                  "summary": "Update due date",
                  "value": {
                    "dueDate": "2025-02-28"
                  }
                },
                "updateReference": {
                  "summary": "Update reference",
                  "value": {
                    "reference": "INV-CARRIER-123-REV"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bill updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Bill"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "409": {
            "description": "Cannot update - bill has payments",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      },
      "delete": {
        "summary": "Delete a bill",
        "description": "Delete a bill.\n\n## Prerequisites\n\n- Bill must not have any payments applied\n\n## What happens\n\n- Bill record is deleted\n- Entity status reverts to `AWAITING_INVOICE`\n",
        "operationId": "deleteBill",
        "tags": [
          "Bills"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "204": {
            "description": "Bill deleted successfully"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "409": {
            "description": "Cannot delete - bill has payments",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/bills/{id}/approve": {
      "post": {
        "summary": "Approve bill for payment",
        "description": "Approve a bill for payment.\n\n## What happens\n\n- Bill status changes to `APPROVED_TO_PAY`\n- Bill is now ready for payment\n\n## Prerequisites\n\n- Bill must be in `IN_REVIEW` status\n",
        "operationId": "approveBill",
        "tags": [
          "Bills"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Bill approved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Bill"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "409": {
            "description": "Bill is not in valid status for approval",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/bills/batch-approve": {
      "post": {
        "summary": "Batch approve bills",
        "description": "Approve multiple bills for payment in a single request.\n\nBills that cannot be approved will be returned in the `failed` array.\n",
        "operationId": "batchApproveBills",
        "tags": [
          "Bills"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApproveBillsRequest"
              },
              "examples": {
                "approveBills": {
                  "summary": "Approve multiple bills",
                  "value": {
                    "billIds": [
                      "550e8400-e29b-41d4-a716-446655440000",
                      "550e8400-e29b-41d4-a716-446655440001"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch approval completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApproveBillsResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    },
    "/bills/{id}/unapprove": {
      "post": {
        "summary": "Unapprove bill",
        "description": "Revert bill from approved back to in review.\n\n## What happens\n\n- Bill status changes to `IN_REVIEW`\n\n## Prerequisites\n\n- Bill must be in `APPROVED_TO_PAY` status\n- Bill must not have any payments\n",
        "operationId": "unapproveBill",
        "tags": [
          "Bills"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Bill unapproved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Bill"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "409": {
            "description": "Bill is not in valid status or has payments",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/bills/{id}/revert": {
      "post": {
        "summary": "Revert bill to awaiting invoice",
        "description": "Revert bill completely back to awaiting invoice state.\n\n## What happens\n\n- Bill record is deleted\n- Any payments are deleted\n- Entity status reverts to `AWAITING_INVOICE`\n\n## Use case\n\nUse when a bill was recorded incorrectly and needs to start over.\n",
        "operationId": "revertBill",
        "tags": [
          "Bills"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RevertBillRequest"
              },
              "examples": {
                "withReason": {
                  "summary": "Revert with reason",
                  "value": {
                    "reason": "Invoice amount was incorrect"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bill reverted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "entityStatus": {
                      "type": "string",
                      "description": "New status of the load carrier or vended service"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/bills/{id}/payments": {
      "get": {
        "summary": "Get bill payments",
        "description": "List all payments applied to a specific bill.",
        "operationId": "getBillPayments",
        "tags": [
          "Bills"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Payments retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/BillPaymentApplied"
                      }
                    },
                    "totalPaid": {
                      "type": "number"
                    },
                    "openBalance": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/carriers/{id}/outstanding-bills": {
      "get": {
        "summary": "Get carrier outstanding bills",
        "description": "List outstanding (unpaid) bills for a carrier.\n\nReturns bills with status `APPROVED_TO_PAY`.\n",
        "operationId": "getCarrierOutstandingBills",
        "tags": [
          "Carriers"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Outstanding bills retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OutstandingBillsResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/vendors/{id}/outstanding-bills": {
      "get": {
        "summary": "Get vendor outstanding bills",
        "description": "List outstanding (unpaid) bills for a vendor.\n\nReturns bills with status `APPROVED_TO_PAY`.\n",
        "operationId": "getVendorOutstandingBills",
        "tags": [
          "Vendors"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Outstanding bills retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OutstandingBillsResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/bills/aging-report": {
      "get": {
        "summary": "Get AP aging report",
        "description": "Generate accounts payable aging report.\n\n## Report buckets\n\nBy default: Current, 1-30, 31-60, 61-90, 90+ days\n\n## Export formats\n\n- JSON (default)\n- CSV (set Accept header to text/csv)\n",
        "operationId": "getApAgingReport",
        "tags": [
          "Bills"
        ],
        "parameters": [
          {
            "name": "carrierId",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter by specific carrier"
          },
          {
            "name": "vendorId",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter by specific vendor"
          },
          {
            "name": "entityType",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/BillEntityType"
            },
            "description": "Filter by entity type"
          },
          {
            "name": "daysPerBucket",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 30
            },
            "description": "Days per aging bucket"
          },
          {
            "name": "maxDays",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 120
            },
            "description": "Maximum days to track"
          }
        ],
        "responses": {
          "200": {
            "description": "AP aging report generated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApAgingReportResponse"
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    },
    "/bill-payments/filter": {
      "post": {
        "summary": "Filter bill payments",
        "description": "Search for bill payments using filter criteria.\n\n## Common Filters\n\n- By carrier: `{ \"filter\": { \"carrierId\": { \"equalTo\": \"uuid\" } } }`\n- By vendor: `{ \"filter\": { \"vendorId\": { \"equalTo\": \"uuid\" } } }`\n- By factor: `{ \"filter\": { \"carrierFactorId\": { \"equalTo\": \"uuid\" } } }`\n- By date range: `{ \"filter\": { \"paymentDate\": { \"gte\": \"2025-01-01\", \"lte\": \"2025-01-31\" } } }`\n- By method: `{ \"filter\": { \"paymentMethodType\": { \"equalTo\": \"check\" } } }`\n",
        "operationId": "filterBillPayments",
        "tags": [
          "Bill Payments"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BillPaymentFilterRequest"
              },
              "examples": {
                "byCarrier": {
                  "summary": "Payments by carrier",
                  "value": {
                    "filter": {
                      "carrierId": {
                        "equalTo": "550e8400-e29b-41d4-a716-446655440000"
                      }
                    }
                  }
                },
                "byDateRange": {
                  "summary": "Payments in date range",
                  "value": {
                    "filter": {
                      "paymentDate": {
                        "greaterThanOrEqualTo": "2025-01-01T00:00:00Z",
                        "lessThanOrEqualTo": "2025-01-31T23:59:59Z"
                      }
                    }
                  }
                },
                "byMethod": {
                  "summary": "Check payments",
                  "value": {
                    "filter": {
                      "paymentMethodType": {
                        "equalTo": "CHECK"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bill payments matching filter criteria",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/BillPayment"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/PaginationInfo"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/bill-payments": {
      "post": {
        "summary": "Create a bill payment",
        "description": "Record a payment for one or more carrier/vendor bills.\n\n## What happens\n\n- PaymentGroup record is created\n- Payment applications are created for each bill\n- Bill open balances are reduced\n- Load/service status updates to PAID when fully paid\n\n## Carrier factor payments\n\nTo pay a carrier's factor instead of the carrier directly,\nspecify `carrierFactorId` in the request.\n\n## Overpayments\n\nIf `allowOverpayment` is true and payment exceeds bill totals,\na credit memo is automatically created for the difference.\n",
        "operationId": "createBillPayment",
        "tags": [
          "Bill Payments"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BillPaymentInput"
              },
              "examples": {
                "singleBill": {
                  "summary": "Pay single bill",
                  "value": {
                    "paymentDate": "2025-01-15",
                    "paymentMethodType": "CHECK",
                    "reference": "CHK-12345",
                    "applications": [
                      {
                        "billId": "550e8400-e29b-41d4-a716-446655440000",
                        "amount": 2500
                      }
                    ]
                  }
                },
                "multipleBills": {
                  "summary": "Pay multiple bills",
                  "value": {
                    "paymentDate": "2025-01-15",
                    "paymentMethodType": "ACH_WIRE",
                    "reference": "ACH-2025-001",
                    "notes": "January carrier payments",
                    "applications": [
                      {
                        "billId": "550e8400-e29b-41d4-a716-446655440000",
                        "amount": 2500
                      },
                      {
                        "billId": "550e8400-e29b-41d4-a716-446655440001",
                        "amount": 3500
                      }
                    ]
                  }
                },
                "factorPayment": {
                  "summary": "Pay carrier factor",
                  "value": {
                    "paymentDate": "2025-01-15",
                    "paymentMethodType": "ACH_WIRE",
                    "carrierFactorId": "770e8400-e29b-41d4-a716-446655440002",
                    "reference": "ACH-FACTOR-001",
                    "applications": [
                      {
                        "billId": "550e8400-e29b-41d4-a716-446655440000",
                        "amount": 2500
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Bill payment created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillPayment"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "409": {
            "description": "Conflict - bill already paid or invalid state",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    },
    "/bill-payments/{id}": {
      "get": {
        "summary": "Get a bill payment",
        "description": "Retrieve a bill payment by ID.\n\nThe response includes all payment applications and their associated bills.\n",
        "operationId": "getBillPayment",
        "tags": [
          "Bill Payments"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Bill payment retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillPayment"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      },
      "patch": {
        "summary": "Update a bill payment",
        "description": "Update bill payment fields.\n\n## Constraints\n\n- Cannot change carrier factor after creation\n- Can add/remove/update payment applications\n\n## Updating applications\n\nIn the `applications` array:\n- Include `id` to update an existing application\n- Omit `id` and include `billId` to add a new application\n- Set `delete: true` with `id` to remove an application\n",
        "operationId": "updateBillPayment",
        "tags": [
          "Bill Payments"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BillPaymentPatch"
              },
              "examples": {
                "updateReference": {
                  "summary": "Update reference",
                  "value": {
                    "reference": "CHK-12345-UPDATED"
                  }
                },
                "updateAmounts": {
                  "summary": "Update payment amounts",
                  "value": {
                    "applications": [
                      {
                        "id": "660e8400-e29b-41d4-a716-446655440001",
                        "amount": 2600
                      }
                    ]
                  }
                },
                "addApplication": {
                  "summary": "Add new bill to payment",
                  "value": {
                    "applications": [
                      {
                        "billId": "770e8400-e29b-41d4-a716-446655440002",
                        "amount": 1000
                      }
                    ]
                  }
                },
                "removeApplication": {
                  "summary": "Remove bill from payment",
                  "value": {
                    "applications": [
                      {
                        "id": "660e8400-e29b-41d4-a716-446655440001",
                        "delete": true
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bill payment updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillPayment"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "409": {
            "description": "Conflict - invalid state for update",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      },
      "delete": {
        "summary": "Delete a bill payment",
        "description": "Delete a bill payment and all its applications.\n\n## What happens\n\n- PaymentGroup record is deleted\n- All Payment applications are deleted\n- Bill open balances are restored\n- Load/service status may revert if payment made them PAID\n",
        "operationId": "deleteBillPayment",
        "tags": [
          "Bill Payments"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "204": {
            "description": "Bill payment deleted successfully"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/bill-payments/{id}/applications": {
      "get": {
        "summary": "Get bill payment applications",
        "description": "List all bills paid by this payment group.",
        "operationId": "getBillPaymentApplications",
        "tags": [
          "Bill Payments"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Applications retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/BillPaymentApplication"
                      }
                    },
                    "totalAmount": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/carriers/{id}/bills-for-payment": {
      "get": {
        "summary": "Get carrier bills available for payment",
        "description": "List bills available for payment from a carrier.\n\nReturns bills with status `APPROVED_TO_PAY` and open balance.\n\n## Carrier factor\n\nIf the carrier has a factor configured, factor details are included.\n",
        "operationId": "getCarrierBillsForPayment",
        "tags": [
          "Carriers"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Bills for payment retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OutstandingBillsForPaymentResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/vendors/{id}/bills-for-payment": {
      "get": {
        "summary": "Get vendor bills available for payment",
        "description": "List bills available for payment from a vendor.\n\nReturns bills with status `APPROVED_TO_PAY` and open balance.\n",
        "operationId": "getVendorBillsForPayment",
        "tags": [
          "Vendors"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Bills for payment retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OutstandingBillsForPaymentResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/carrier-factors/{id}/bills-for-payment": {
      "get": {
        "summary": "Get bills payable to a carrier factor",
        "description": "List bills that should be paid to this carrier factor.\n\nReturns bills from carriers that use this factor with status `APPROVED_TO_PAY`.\n",
        "operationId": "getCarrierFactorBillsForPayment",
        "tags": [
          "Carrier Factors"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Bills for payment retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OutstandingBillsForPaymentResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/bill-payments/{id}/remittance-advice": {
      "get": {
        "summary": "Generate remittance advice",
        "description": "Generate a remittance advice document for a bill payment.\n\n## Formats\n\n- PDF (default): Set Accept header to application/pdf\n- JSON: Set Accept header to application/json\n",
        "operationId": "getBillPaymentRemittanceAdvice",
        "tags": [
          "Bill Payments"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "responses": {
          "200": {
            "description": "Remittance advice generated",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "paymentDate": {
                      "type": "string",
                      "format": "date"
                    },
                    "paymentMethod": {
                      "type": "string"
                    },
                    "reference": {
                      "type": "string"
                    },
                    "payee": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "address": {
                          "type": "string"
                        }
                      }
                    },
                    "applications": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "billFriendlyId": {
                            "type": "string"
                          },
                          "shipmentFriendlyId": {
                            "type": "string"
                          },
                          "invoiceDate": {
                            "type": "string",
                            "format": "date"
                          },
                          "amount": {
                            "type": "number"
                          }
                        }
                      }
                    },
                    "totalAmount": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          }
        }
      }
    },
    "/bill-payments/{id}/send-remittance": {
      "post": {
        "summary": "Send remittance advice email",
        "description": "Email the remittance advice to the carrier or vendor.\n\nUses the recipient's default email from their profile.\n",
        "operationId": "sendBillPaymentRemittance",
        "tags": [
          "Bill Payments"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdOrClientKey"
          },
          {
            "$ref": "#/components/parameters/LookupBy"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "toEmail": {
                    "type": "string",
                    "format": "email",
                    "description": "Override recipient email"
                  },
                  "ccEmails": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "email"
                    },
                    "description": "CC recipients"
                  },
                  "message": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "Additional message in email body"
                  }
                }
              },
              "examples": {
                "defaultEmail": {
                  "summary": "Send to default contact",
                  "value": {}
                },
                "customRecipient": {
                  "summary": "Send to specific email",
                  "value": {
                    "toEmail": "accounts@carrier.com",
                    "message": "Please find attached remittance advice for recent payments."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Remittance advice sent successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "sentTo": {
                      "type": "string",
                      "format": "email"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "422": {
            "description": "No email address available",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/global-search": {
      "post": {
        "summary": "Search globally",
        "description": "Search across multiple entity types simultaneously (shipments, customers, carriers, users, vendors).\n\n**Use Cases:**\n- Unified search bar for finding any type of record\n- Quick lookup by name, ID, or reference number\n- Cross-entity discovery\n\n**Search Behavior:**\n- Searches across default searchable fields for each entity type\n- Results are sorted by object type priority: SHIPMENT → CUSTOMER → CARRIER → USER → VENDOR\n- Within each object type, results are sorted by most recently updated\n\n**Prefix Filtering:**\nUse \"type:query\" syntax to search specific object types:\n- `carrier:acme` - searches only carriers\n- `shipment:12345` - searches only shipments\n- `customer:west` - searches only customers\n\n**IMPORTANT: Eventually Consistent**\nThis endpoint queries OpenSearch indices which are updated asynchronously.\nChanges typically appear within 2 seconds, but this is not guaranteed.\n",
        "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"
          }
        }
      }
    }
  },
  "webhooks": {
    "your-endpoint": {
      "post": {
        "summary": "Webhook Event",
        "description": "All webhook events are delivered to your configured endpoint URL.\n\nThe `event` field in the payload determines which type of webhook was triggered.\nYour endpoint should handle all event types or gracefully ignore unknown events.\n\n**Event Types:**\n- Entity changes: `CUSTOMER_*`, `COMPANY_*`, `CARRIER_*`, `CUSTOMER_CONTACT_*`\n- Shipment events: `SHIPMENT_DELIVERED`, `SHIPMENT_BOOKED`, `SHIPMENT_DISPATCHED`, etc.\n- Financial events: `CARRIER_INVOICE_CREATED`, `CUSTOMER_PAYMENT_CREATED`, etc.\n\n**Security:** All webhook requests include an `x-api-key` header containing your webhook token configured in the MVMNT UI.\n\n**Best Practices:**\n- Return 200 OK quickly and process asynchronously\n- Implement idempotency using event ID and timestamp\n- Handle unknown event types gracefully for forward compatibility\n",
        "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",
                          "defaultCarrierNotes": "Call pickup contact before arrival",
                          "defaultExternalNotes": "Please call 1 hour before delivery",
                          "defaultShowNotes": "SPLIT",
                          "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",
                          "defaultCarrierNotes": "Call pickup contact before arrival",
                          "defaultExternalNotes": "Please call 1 hour before delivery",
                          "defaultShowNotes": "SPLIT",
                          "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"
          }
        }
      }
    }
  },
  "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.\nIf omitted, defaults to looking up by ID first, then falls back to client key if not found.\nUse `by=key` when you know you're providing a client key for best performance.\n",
        "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).\nIncludes full payment term details in addition to id/key.\n",
        "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).\nIncludes full user details in addition to id/key.\n\nNote: Does NOT include nested references (teams, etc.) to prevent recursion.\nMaximum nesting depth: 1 level.\n",
        "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).\nIncludes full customer details in addition to id/key.\n\nNote: Does NOT include nested references (paymentTerm, contacts, etc.) to prevent recursion.\nMaximum nesting depth: 1 level.\n",
        "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": [
              "NEW",
              "CONTACTED",
              "QUALIFIED",
              "QUOTED",
              "NURTURING",
              "PENDING",
              "ACTIVE",
              "INACTIVE",
              "BLOCKED",
              "CLOSED"
            ],
            "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).\nIncludes full carrier details in addition to id/key.\n\nNote: Does NOT include nested references (contacts, etc.) to prevent recursion.\nMaximum nesting depth: 1 level.\n",
        "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.\n\nNote: In the backend, null carrier type is represented as TRUCKLOAD in the public API.\n",
        "enum": [
          "TRUCKLOAD",
          "AIR",
          "CARTAGE",
          "LINEHAUL",
          "LTL",
          "OCEAN",
          "AGENT",
          "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"
          },
          {
            "$ref": "#/components/schemas/AgentCarrier"
          }
        ],
        "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",
            "AGENT": "#/components/schemas/AgentCarrier"
          }
        }
      },
      "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"
          },
          {
            "$ref": "#/components/schemas/AgentCarrierInput"
          }
        ],
        "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",
            "AGENT": "#/components/schemas/AgentCarrierInput"
          }
        }
      },
      "CarrierPatchBase": {
        "type": "object",
        "description": "Partial carrier update. All fields are optional.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "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": {
        "description": "Partial carrier update, discriminated by `type`. All fields are optional.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable — except\n  `type`, which only changes through a discriminator value\n",
        "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"
          },
          {
            "$ref": "#/components/schemas/AgentCarrierPatch"
          }
        ],
        "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",
            "AGENT": "#/components/schemas/AgentCarrierPatch"
          }
        }
      },
      "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).\n\nNote: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.\n"
          },
          "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"
          },
          "phoneExtension": {
            "type": [
              "string",
              "null"
            ],
            "description": "Primary phone extension",
            "example": "123"
          },
          "fax": {
            "type": [
              "string",
              "null"
            ],
            "description": "Fax number",
            "example": "+1-555-234-9999"
          },
          "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"
          },
          "phoneExtension": {
            "type": "string",
            "description": "Primary phone extension",
            "example": "123"
          },
          "fax": {
            "type": "string",
            "description": "Fax number",
            "example": "+1-555-234-9999"
          },
          "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.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "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"
          },
          "phoneExtension": {
            "type": [
              "string",
              "null"
            ],
            "description": "Primary phone extension",
            "example": "123"
          },
          "fax": {
            "type": [
              "string",
              "null"
            ],
            "description": "Fax number",
            "example": "+1-555-234-9999"
          },
          "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"
          },
          "phoneExtension": {
            "$ref": "#/components/schemas/StringFilter"
          },
          "fax": {
            "$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).\n\nNote: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.\n"
          },
          "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).\nIncludes full carrier factor details in addition to id/key.\n",
        "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.\n\n- `DIRECT`: Payment goes directly to the carrier\n- `FACTOR`: Payment goes to a factoring company (requires carrierFactorId)\n",
        "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",
          "E_TRANSFER",
          "EFT_DIRECT_DEPOSIT",
          "SPEI"
        ],
        "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).\n\nThis field cannot be changed after the payment method is created.\n",
            "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.\n\n- **DIRECT**: Payment goes directly to the carrier (carrierFactorId must be null)\n- **FACTOR**: Payment goes to a factoring company (carrierFactorId is required)\n"
          },
          "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).\n\nWhen paymentRecipientType is DIRECT, this must be null.\n"
          },
          "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.\n\n**IMPORTANT**: This field cannot be changed after creation.\n",
            "example": "770e8400-e29b-41d4-a716-446655440000"
          },
          "paymentRecipientType": {
            "$ref": "#/components/schemas/PaymentRecipientType",
            "description": "Who receives the payment.\n\n- **DIRECT**: carrierFactorId must be null or omitted\n- **FACTOR**: carrierFactorId is required\n"
          },
          "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.\n\n**Constraint**: Required when paymentRecipientType is FACTOR, must be null when DIRECT.\n",
            "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.\n\n**IMPORTANT**: The `carrierId` field cannot be changed after creation.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "properties": {
          "paymentRecipientType": {
            "$ref": "#/components/schemas/PaymentRecipientType",
            "description": "Who receives the payment.\n\n- **DIRECT**: carrierFactorId must be null\n- **FACTOR**: carrierFactorId is required\n"
          },
          "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.\n\n**Constraint**: Required when paymentRecipientType is FACTOR, must be null when DIRECT.\n",
            "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).\n\nNote: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.\n"
          },
          "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).\n\nThis is an embedded object representing a Location record. The id is managed\ninternally and not exposed in the API.\n",
        "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"
          },
          "state": {
            "type": [
              "string",
              "null"
            ],
            "description": "State or province code",
            "example": "IL"
          },
          "zipCode": {
            "type": [
              "string",
              "null"
            ],
            "description": "Postal / ZIP code",
            "example": "60601"
          },
          "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"
        ],
        "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"
          },
          "state": {
            "type": "string",
            "description": "State or province code",
            "example": "IL"
          },
          "zipCode": {
            "type": "string",
            "description": "Postal / ZIP code",
            "example": "60601"
          },
          "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.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Treated as omitted (null-clears are not yet\n  supported for address fields)\n",
        "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"
          },
          "state": {
            "type": "string",
            "description": "State or province code",
            "example": "IL"
          },
          "zipCode": {
            "type": "string",
            "description": "Postal / ZIP code",
            "example": "60601"
          },
          "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).\n\nThis is an embedded object representing a Contact record. The id is managed\ninternally and not exposed in the API.\n",
        "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.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "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).\n\nNote: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.\n"
          },
          "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.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "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).\n\nNote: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.\n"
          },
          "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": {
                  "isNull": false
                }
              }
            ]
          },
          "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.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n\nNote: carrierId cannot be updated after creation.\n",
        "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.\nCannot be set to null (contact info is required).\n"
          },
          "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).\n\nNote: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.\n"
          },
          "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.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n\nNote: customerId cannot be updated after creation.\n",
        "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.\nCannot be set to null (contact info is required).\n"
          },
          "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):\n- `NEW`: New lead, not yet contacted\n- `CONTACTED`: Initial contact made with lead\n- `QUALIFIED`: Lead has been qualified as potential customer\n- `QUOTED`: Quote has been provided to lead\n- `NURTURING`: Lead being nurtured for future opportunity\n- `PENDING`: Customer prospect pending activation\n- `ACTIVE`: Active customer account\n- `INACTIVE`: Deactivated customer account\n- `BLOCKED`: Customer account blocked from operations\n- `CLOSED`: Customer account permanently closed\n",
        "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:\n- `CONTRACT`: Customer operates under contract pricing\n- `SPOT`: Customer operates on spot market pricing\n",
        "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:\n- `NOT_PAYING_INVOICE`: Customer is not paying invoices\n- `ACQUIRED`: Customer was acquired by another company\n- `DUPLICATE`: Duplicate customer record\n- `NOT_IN_BUSINESS`: Customer is no longer in business\n- `OTHER`: Other reason (see deactivationNotes for details)\n",
        "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",
          "RLTL"
        ],
        "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).\nNote: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.\n",
            "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": {
                  "equalTo": "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. Values outside the enum are rejected\nwith 400; customers whose internal mode isn't in the public enum\nreturn the field omitted.\n"
          },
          "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"
          },
          "defaultCarrierNotes": {
            "type": [
              "string",
              "null"
            ],
            "description": "Default carrier-facing notes template used when note splitting is enabled",
            "example": "Call pickup contact before arrival"
          },
          "defaultExternalNotes": {
            "type": [
              "string",
              "null"
            ],
            "description": "Default external notes template",
            "example": "Please call 1 hour before delivery"
          },
          "defaultShowNotes": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ShowNotes"
              },
              {
                "type": "null"
              }
            ],
            "description": "Controls whether default external notes are reused on carrier docs or split from default carrier notes"
          },
          "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"
          },
          "defaultCarrierNotes": {
            "type": "string",
            "description": "Default carrier-facing notes template used when note splitting is enabled",
            "example": "Call pickup contact before arrival"
          },
          "defaultExternalNotes": {
            "type": "string",
            "description": "Default external notes template",
            "example": "Please call 1 hour before delivery"
          },
          "defaultShowNotes": {
            "$ref": "#/components/schemas/ShowNotes"
          },
          "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.\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "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. Values outside the enum are rejected\nwith 400; customers whose internal mode isn't in the public enum\nreturn the field omitted.\n"
          },
          "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"
          },
          "defaultCarrierNotes": {
            "type": [
              "string",
              "null"
            ],
            "description": "Default carrier-facing notes template used when note splitting is enabled",
            "example": "Call pickup contact before arrival"
          },
          "defaultExternalNotes": {
            "type": [
              "string",
              "null"
            ],
            "description": "Default external notes template",
            "example": "Please call 1 hour before delivery"
          },
          "defaultShowNotes": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ShowNotes"
              },
              {
                "type": "null"
              }
            ],
            "description": "Controls whether default external notes are reused on carrier docs or split from default carrier notes"
          },
          "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.\nSet to null to clear the address reference.\n"
          },
          "billingAddress": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/AddressPatch"
              },
              {
                "type": "null"
              }
            ],
            "description": "Billing address update. Provide partial or full address data to update the existing location.\nSet to null to clear the address reference.\n"
          },
          "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:\n- `SHIPPER`: Pickup location only\n- `RECEIVER`: Delivery location only\n- `BOTH`: Can be used for both pickup and delivery\n"
      },
      "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).\n\nNote: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.\n"
          },
          "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"
          },
          "address": {
            "$ref": "#/components/schemas/Address",
            "readOnly": true,
            "description": "Physical address of this location"
          },
          "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",
          "address",
          "name",
          "isAppointmentRequired"
        ],
        "properties": {
          "customerId": {
            "type": "string",
            "format": "uuid",
            "description": "Customer (shipper profile) this location belongs to (required)",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "address": {
            "$ref": "#/components/schemas/LocationAddressInput",
            "description": "Physical address for this location (required). The backing address\nrecord is created and linked automatically — no separate address or\nlocation id is needed. `country` accepts US, CA, or MX.\n"
          },
          "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.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "properties": {
          "customerId": {
            "type": "string",
            "format": "uuid",
            "description": "Customer (shipper profile) this location belongs to",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "address": {
            "$ref": "#/components/schemas/AddressPatch",
            "description": "Partial update of the location's physical address. Provided fields\nupdate the backing address record in place. Null values are treated\nas omitted for address fields (null-clears are not yet supported).\n"
          },
          "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).\n\nNote: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.\n"
          },
          "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.\nIdentical to LocationContact but excludes the location and locationId fields to avoid circular references.\n",
        "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.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "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).\nNote: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.\n",
            "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.\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "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).\nNote: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.\n",
            "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/UserReference-2"
            }
          },
          "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.\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "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:\n- `PENDING`: User invited but has not completed onboarding\n- `ACTIVE`: User account is active and can access the system\n- `INACTIVE`: User account is deactivated\n",
        "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",
          "MANAGER",
          "ADMIN"
        ],
        "description": "User role within the organization:\n- `CUSTOMER_REP`: Customer service representative\n- `CARRIER_REP`: Carrier service representative\n- `AR_AP`: Accounts receivable/payable\n- `COMPLIANCE`: Compliance officer\n- `ADMIN`: System administrator\n",
        "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).\nNote: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.\n",
            "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.\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "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",
          "DO_NOT_USE"
        ]
      },
      "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).\n\nNote: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.\n"
          },
          "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/Currency-2"
              },
              {
                "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/Currency-2",
            "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.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "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/Currency-2"
              },
              {
                "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).\n\nNote: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.\n"
          },
          "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",
          "name"
        ],
        "properties": {
          "vendorId": {
            "type": "string",
            "format": "uuid",
            "description": "Vendor this contact belongs to",
            "example": "550e8400-e29b-41d4-a716-446655440001"
          },
          "name": {
            "type": "string",
            "description": "Contact person's name (required)",
            "example": "John Smith"
          },
          "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.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n\nNote: vendorId cannot be updated after creation.\n",
        "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.\nIncludes full vendor details in addition to id/key.\n",
        "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-2"
      },
      "VendorPaymentMethodTypeFilter": {
        "$ref": "#/components/schemas/PaymentMethodTypeFilter-2"
      },
      "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).\n\nThis field cannot be changed after the payment method is created.\n",
            "example": "770e8400-e29b-41d4-a716-446655440000"
          },
          "vendor": {
            "$ref": "#/components/schemas/VendorReference",
            "description": "Vendor profile reference with full details"
          },
          "paymentMethodType": {
            "$ref": "#/components/schemas/PaymentMethodType-2",
            "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.\n\n**IMPORTANT**: This field cannot be changed after creation.\n",
            "example": "770e8400-e29b-41d4-a716-446655440000"
          },
          "paymentMethodType": {
            "$ref": "#/components/schemas/PaymentMethodType-2",
            "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.\n\n**IMPORTANT**: The `vendorId` field cannot be changed after creation.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "properties": {
          "paymentMethodType": {
            "$ref": "#/components/schemas/PaymentMethodType-2",
            "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-2"
          },
          "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).\n\nNote: deletedAt automatically defaults to { isNull: true } unless explicitly overridden.\n"
          },
          "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.\n\n**Entity Mapping:**\n- `INVOICE`: Customer invoices (AR Invoices) - money owed to you\n- `BILL`: Vendor/Carrier bills (AP Invoices) - money you owe\n- `INVOICE_PAYMENT`: Customer payment groups (AR Payment Groups)\n- `BILL_PAYMENT`: Vendor/Carrier payment groups (AP Payment Groups)\n",
        "enum": [
          "SHIPMENT",
          "INVOICE",
          "BILL",
          "USER",
          "CUSTOMER",
          "VENDOR",
          "QUOTE",
          "COMMISSION",
          "CARRIER",
          "INVOICE_PAYMENT",
          "BILL_PAYMENT",
          "LOAD",
          "TRUCK_POSTING",
          "LOCATION",
          "CARRIER_FACTOR",
          "COMMISSION_PAYMENT",
          "AR_CREDIT_MEMO",
          "AP_CREDIT_MEMO"
        ],
        "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"
          },
          "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).\nReturns only saved searches accessible to the authenticated user.\n"
          },
          "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.\nThis is stored in the jsonValue field.\n",
        "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,\nsorting, and display preferences. Saved searches are stored per organization and can be\nshared publicly or kept private to a specific user.\n",
        "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.\nMust match the search endpoint where this saved search will be used.\n"
          },
          "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.\nIf false or null, only the owner can see it.\n",
            "example": true
          },
          "ownedByUser": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "readOnly": true,
            "description": "User ID who owns this saved search.\nNull means it's an organization-level saved search.\n",
            "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).\nDetermines which search endpoint can use this saved search.\n"
          },
          "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
          },
          "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
        }
      },
      "SavedSearchPatch": {
        "type": "object",
        "description": "Partial saved search update. All fields are optional.\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "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
          },
          "groupId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Optional group this saved search belongs to",
            "example": null
          }
        },
        "example": {
          "name": "Updated Shipments View",
          "isPublic": true
        }
      },
      "CustomerSearchCriteria": {
        "type": "object",
        "description": "Search criteria for filtering customers.\nNote: Only active (non-deleted) customers are searchable. Soft-deleted records are automatically excluded.\n",
        "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 (new, contacted, qualified, quoted, nurturing, pending, active, inactive, blocked, closed)"
          },
          "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.\nWhen provided, the saved search criteria will be loaded and merged with any explicit criteria.\n"
          },
          "format": {
            "type": "string",
            "enum": [
              "flat",
              "full"
            ],
            "default": "flat",
            "description": "Response format:\n- flat: Returns only indexed fields (default, faster)\n- full: Returns complete customer objects\n"
          }
        }
      },
      "CustomerSearchRow": {
        "type": "object",
        "description": "Flattened customer data from search index.\nNote: This represents only active customers. Soft-deleted records are never returned.\n",
        "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": [
              "new",
              "contacted",
              "qualified",
              "quoted",
              "nurturing",
              "pending",
              "active",
              "inactive",
              "blocked",
              "closed"
            ]
          },
          "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.\nNote: Only active (non-deleted) customers are included in results.\n",
        "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.\nNote: Only active (non-deleted) carriers are searchable. Soft-deleted records are automatically excluded.\n",
        "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, review)"
          },
          "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, no_docket)"
          },
          "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 (e.g. ACCEPTABLE, MODERATE, UNACCEPTABLE, UNACCEPTABLE_REVIEW, UNACCEPTABLE_FAIL)"
          },
          "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.\nWhen provided, the saved search criteria will be loaded and merged with any explicit criteria.\n"
          },
          "format": {
            "type": "string",
            "enum": [
              "flat",
              "full"
            ],
            "default": "flat",
            "description": "Response format:\n- flat: Returns only indexed fields (default, faster)\n- full: Returns complete carrier objects\n"
          }
        }
      },
      "CarrierSearchRow": {
        "type": "object",
        "description": "Flattened carrier data from search index.\nIncludes both ONBOARDED carriers and FMCSA records.\n",
        "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",
              "review"
            ],
            "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",
              "no_docket"
            ]
          },
          "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"
            ],
            "description": "MyCarrierPortal invite status. Open-ended passthrough from the MCP\nfeed; commonly seen values include COMPLETE, INCOMPLETE, INVITED,\nIN_PROCESS, NOT_INVITED.\n"
          },
          "mcpReviewStatus": {
            "type": [
              "string",
              "null"
            ],
            "description": "MyCarrierPortal risk assessment. Open-ended passthrough from the MCP\nfeed; commonly seen values include ACCEPTABLE, MODERATE,\nUNACCEPTABLE, UNACCEPTABLE_REVIEW, UNACCEPTABLE_FAIL.\n"
          },
          "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.\nNote: Only active (non-deleted) carriers are included in results.\n",
        "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.\nNote: Only active (non-deleted) vendors are searchable. Soft-deleted records are automatically excluded.\n",
        "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.\nWhen provided, the saved search criteria will be loaded and merged with any explicit criteria.\n"
          },
          "format": {
            "type": "string",
            "enum": [
              "flat",
              "full"
            ],
            "default": "flat",
            "description": "Response format:\n- flat: Returns only indexed fields (default, faster)\n- full: Returns complete vendor objects\n"
          }
        }
      },
      "VendorSearchRow": {
        "type": "object",
        "description": "Flattened vendor data from search index.\nNote: This represents only active vendors. Soft-deleted records are never returned.\n",
        "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.\nNote: Only active (non-deleted) vendors are included in results.\n",
        "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.\nNote: Only active (non-deleted) users are searchable. Soft-deleted records are automatically excluded.\n",
        "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.\nWhen provided, the saved search criteria will be loaded and merged with any explicit criteria.\n"
          },
          "format": {
            "type": "string",
            "enum": [
              "flat",
              "full"
            ],
            "default": "flat",
            "description": "Response format:\n- flat: Returns only indexed fields (default, faster)\n- full: Returns complete user objects\n"
          }
        }
      },
      "UserSearchRow": {
        "type": "object",
        "description": "Flattened user data from search index.\nNote: This represents only active users. Soft-deleted records are never returned.\n",
        "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.\nNote: Only active (non-deleted) users are included in results.\n",
        "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).\nNote: Only active (non-deleted) locations are searchable. Soft-deleted records are automatically excluded.\n",
        "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.\nWhen provided, the saved search criteria will be loaded and merged with any explicit criteria.\n"
          },
          "format": {
            "type": "string",
            "enum": [
              "flat",
              "full"
            ],
            "default": "flat",
            "description": "Response format:\n- flat: Returns only indexed fields (default, faster)\n- full: Returns complete location objects\n"
          }
        }
      },
      "LocationSearchRow": {
        "type": "object",
        "description": "Flattened location data from search index.\nNote: This represents only active locations. Soft-deleted records are never returned.\n",
        "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.\nNote: Only active (non-deleted) locations are included in results.\n",
        "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:\n- `SHIPMENT`: Shipment records\n- `CUSTOMER`: Customer/shipper profiles\n- `CARRIER`: Carrier profiles\n- `USER`: User accounts\n- `VENDOR`: Vendor profiles\n"
      },
      "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.\n\nSupports prefix filtering using \"type:query\" syntax:\n- `carrier:acme` - searches only carriers for \"acme\"\n- `shipment:12345` - searches only shipments for \"12345\"\n- `user:john` - searches only users for \"john\"\n",
            "example": "acme corp"
          },
          "objects": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GlobalSearchObjectType"
            },
            "description": "Optional filter to limit search to specific object types.\nIf not provided, searches across all object types.\n",
            "example": [
              "SHIPMENT",
              "CUSTOMER"
            ]
          },
          "pagination": {
            "$ref": "#/components/schemas/SearchPaginationInput"
          }
        }
      },
      "GlobalSearchRow": {
        "type": "object",
        "description": "A single global search result row.\nResults are sorted by object type priority: SHIPMENT, CUSTOMER, CARRIER, USER, VENDOR.\n",
        "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).\nPrefer using the `object` field instead.\n",
            "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.\nContains HTML &lt;em&gt; tags around matched portions.\n",
            "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:\nSHIPMENT → CUSTOMER → CARRIER → USER → VENDOR\n",
            "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
          }
        }
      },
      "ShipmentReferenceField": {
        "type": "string",
        "enum": [
          "BOL_NUMBER",
          "PICKUP_NUMBER",
          "DELIVERY_NUMBER",
          "PURCHASE_ORDER_NUMBER",
          "GENERAL_LEDGER_CODE",
          "CUSTOMER_REFERENCE_NUMBER",
          "PRO_NUMBER",
          "ITEM_IDENTIFICATION",
          "PART_NUMBER",
          "ACCOUNT_NUMBER",
          "CONSIGNEE_ACCOUNT_NUMBER",
          "PICKUP_LOCATION_IDENTIFICATION",
          "DELIVER_LOCATION_IDENTIFICATION",
          "PRODUCT_IDENTIFICATION",
          "OTHER_IDENTIFICATION",
          "CONTAINER_NUMBER",
          "MACROPOINT_REFERENCE_NUMBER",
          "DROP_TRAILER_NUMBER",
          "APPOINTMENT_NUMBER",
          "MASTER_BILL_OF_LADING_NUMBER",
          "HOUSE_BILL_OF_LADING_NUMBER",
          "LOCATION_IDENTIFICATION",
          "TENDER_METHOD",
          "ROUTE_NUMBER",
          "SHOW_DECORATOR_NAME",
          "SHOW_BOOTH_NUMBER",
          "CARE_OF",
          "TENDER_ID",
          "ORDER_NUMBER",
          "SHOW_NAME",
          "AES_ITN",
          "FIRMS_CODE",
          "IT_NUMBER",
          "JOB_NUMBER",
          "TMS_ID",
          "MASTER_AIRWAYBILL_NUMBER",
          "HOUSE_AIRWAYBILL_NUMBER",
          "AMS_HOUSE_BILL_OF_LADING_NUMBER",
          "QUOTE_NUMBER",
          "BOOKING_NUMBER",
          "PAPS_NUMBER",
          "PARS_NUMBER",
          "INTERNAL_ID",
          "LOT_NUMBER"
        ],
        "description": "Reference field types for shipment tracking.\n\nCommon field types:\n- `BOL_NUMBER`: Bill of Lading Number\n- `PRO_NUMBER`: PRO Number (carrier tracking number)\n- `PURCHASE_ORDER_NUMBER`: Purchase Order Number\n- `CUSTOMER_REFERENCE_NUMBER`: Customer Reference Number\n- `CONTAINER_NUMBER`: Container Number\n- `MASTER_BILL_OF_LADING_NUMBER`: Master Bill of Lading Number\n- `HOUSE_BILL_OF_LADING_NUMBER`: House Bill of Lading Number\n- `MASTER_AIRWAYBILL_NUMBER`: Master Airway Bill Number\n- `HOUSE_AIRWAYBILL_NUMBER`: House Airway Bill Number\n\nAdditional field types:\n- `PICKUP_NUMBER`: Pickup Number\n- `DELIVERY_NUMBER`: Delivery Number\n- `GENERAL_LEDGER_CODE`: GL Code\n- `ITEM_IDENTIFICATION`: Item ID\n- `PART_NUMBER`: Part Number\n- `ACCOUNT_NUMBER`: Account Number\n- `CONSIGNEE_ACCOUNT_NUMBER`: Consignee Account Number\n- `PICKUP_LOCATION_IDENTIFICATION`: Pickup Location ID\n- `DELIVER_LOCATION_IDENTIFICATION`: Delivery Location ID\n- `PRODUCT_IDENTIFICATION`: Product ID\n- `OTHER_IDENTIFICATION`: Other ID\n- `MACROPOINT_REFERENCE_NUMBER`: MacroPoint Reference Number\n- `DROP_TRAILER_NUMBER`: Drop Trailer Number\n- `APPOINTMENT_NUMBER`: Appointment Number\n- `LOCATION_IDENTIFICATION`: Location ID\n- `TENDER_METHOD`: Tender Method\n- `ROUTE_NUMBER`: Route Number\n- `SHOW_DECORATOR_NAME`: Show Decorator Name\n- `SHOW_BOOTH_NUMBER`: Show Booth Number\n- `CARE_OF`: Care Of\n- `TENDER_ID`: EDI Tender ID\n- `ORDER_NUMBER`: Order Number\n- `SHOW_NAME`: Show Name\n- `AES_ITN`: AES ITN (Automated Export System Internal Transaction Number)\n- `FIRMS_CODE`: FIRMS Code (Facility Information and Resources Management System)\n- `IT_NUMBER`: IT Number (Immediate Transportation)\n- `JOB_NUMBER`: Job Number\n- `TMS_ID`: TMS ID\n- `AMS_HOUSE_BILL_OF_LADING_NUMBER`: AMS House Bill of Lading Number\n- `QUOTE_NUMBER`: Quote Number\n- `BOOKING_NUMBER`: Booking Number\n- `PAPS_NUMBER`: PAPS Number\n- `PARS_NUMBER`: PARS Number\n- `INTERNAL_ID`: Internal ID\n- `LOT_NUMBER`: Lot Number\n"
      },
      "ShipmentTrackSearch": {
        "type": "object",
        "required": [
          "query"
        ],
        "properties": {
          "query": {
            "type": "string",
            "minLength": 4,
            "maxLength": 255,
            "description": "Reference value to search for (minimum 4 characters)",
            "example": "MAWB123456"
          }
        }
      },
      "ShipmentTrackRequest": {
        "type": "object",
        "required": [
          "searches"
        ],
        "properties": {
          "searches": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/ShipmentTrackSearch"
            },
            "description": "Array of search queries. Results are returned in the same order as the input searches.\nMaximum 100 searches per request.\n"
          },
          "referenceFields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShipmentReferenceField"
            },
            "description": "Optional filter for reference field types to search.\nIf omitted, searches all reference field types.\n\nCommon use: limit search to specific field types for faster results\nor to avoid false matches across different reference types.\n",
            "example": [
              "MASTER_AIRWAYBILL_NUMBER",
              "BOL_NUMBER",
              "PRO_NUMBER"
            ]
          }
        },
        "example": {
          "searches": [
            {
              "query": "MAWB123456"
            },
            {
              "query": "BOL789"
            }
          ],
          "referenceFields": [
            "MASTER_AIRWAYBILL_NUMBER",
            "BOL_NUMBER"
          ]
        }
      },
      "ShipmentTrackResult": {
        "type": "object",
        "required": [
          "query"
        ],
        "properties": {
          "query": {
            "type": "string",
            "description": "Original search query (always present, even when no match found)",
            "example": "MAWB123456"
          },
          "id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Shipment UUID (null if not found)",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "key": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512,
            "description": "Client-defined key (null if not found or not set)",
            "example": "SHIP-001"
          },
          "friendlyId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Human-readable shipment ID (null if not found)",
            "example": "SHP-12345"
          },
          "status": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ShipmentStatus"
              },
              {
                "type": "null"
              }
            ],
            "description": "Current shipment status (null if not found)",
            "example": "IN_TRANSIT"
          },
          "field": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ShipmentReferenceField"
              },
              {
                "type": "null"
              }
            ],
            "description": "Reference field type that matched the query (null if not found)"
          },
          "value": {
            "type": [
              "string",
              "null"
            ],
            "description": "The actual value stored in the matched reference field (null if not found)",
            "example": "MAWB123456"
          },
          "origin": {
            "type": [
              "string",
              "null"
            ],
            "description": "Origin city, state/region, and zip code (null if not found).\nFormat: \"City, ST\" or \"City, ST ZIP\" if zip code is available.\n",
            "example": "Los Angeles, CA 90210"
          },
          "destination": {
            "type": [
              "string",
              "null"
            ],
            "description": "Destination city, state/region, and zip code (null if not found).\nFormat: \"City, ST\" or \"City, ST ZIP\" if zip code is available.\n",
            "example": "New York, NY 10001"
          },
          "pickUpDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Scheduled or actual pickup date in ISO 8601 date format (YYYY-MM-DD).\nNull if not found or not set.\n",
            "example": "2025-01-15"
          },
          "deliveryDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Scheduled or actual delivery date in ISO 8601 date format (YYYY-MM-DD).\nNull if not found or not set.\n",
            "example": "2025-01-20"
          },
          "trackingUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Direct URL to view shipment details in MVMNT (null if not found).\nUses the organization's configured domain or defaults to app.mvmnt.io.\n",
            "example": "https://app.mvmnt.io/shipments/550e8400-e29b-41d4-a716-446655440000"
          },
          "truckerToolsUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Direct link to the Trucker Tools tracking page for the shipment's\nload, when live tracking is active. The MVMNT `trackingUrl` embeds\nthe same map plus shipment milestones; use this one only if you want\nthe raw Trucker Tools view.\n"
          }
        }
      },
      "ShipmentTrackResponse": {
        "type": "object",
        "required": [
          "results"
        ],
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShipmentTrackResult"
            },
            "description": "Array of tracking results in the same order as input searches.\n\nEach result contains the original query plus matching shipment data.\nIf no match is found, only the `query` field is populated (all other fields are null).\n\nIf multiple shipments match a query, the most recently created shipment is returned.\n"
          }
        },
        "example": {
          "results": [
            {
              "query": "MAWB123456",
              "id": "550e8400-e29b-41d4-a716-446655440000",
              "key": "SHIP-001",
              "friendlyId": "SHP-12345",
              "status": "IN_TRANSIT",
              "field": "MASTER_AIRWAYBILL_NUMBER",
              "value": "MAWB123456",
              "origin": "Los Angeles, CA 90210",
              "destination": "New York, NY 10001",
              "pickUpDate": "2025-01-15",
              "deliveryDate": "2025-01-20",
              "trackingUrl": "https://app.mvmnt.io/shipments/550e8400-e29b-41d4-a716-446655440000"
            },
            {
              "query": "NOTFOUND123",
              "id": null,
              "key": null,
              "friendlyId": null,
              "status": null,
              "field": null,
              "value": null,
              "origin": null,
              "destination": null,
              "pickUpDate": null,
              "deliveryDate": null,
              "trackingUrl": null
            }
          ]
        }
      },
      "DocumentType": {
        "type": "string",
        "enum": [
          "INVOICE",
          "BILL_OF_LADING",
          "RATE_CON",
          "PROOF_OF_DELIVERY",
          "CERTIFICATE_OF_INSURANCE",
          "W9",
          "CARRIER_INVOICE",
          "LUMPER_RECEIPT",
          "DETENTION",
          "DELIVERY_ORDER",
          "LOAD_TENDER",
          "HOUSE_AIRWAY_BILL",
          "MASTER_AIRWAY_BILL",
          "QUOTE",
          "AIR_CARGO_MANIFEST",
          "AIR_CHUTE",
          "AIR_FREIGHT_DEPARTURE_CARTAGE_ADVICE_WITH_RECEIPT",
          "AUTHORITY",
          "AUTHORITY_TO_MAKE_ENTRY",
          "BROKER_CARRIER_AGREEMENT",
          "COI_AUTO",
          "COI_BIPD",
          "COI_CARGO",
          "COMMERCIAL_DRIVERS_LICENSE",
          "COMMERCIAL_INVOICE",
          "CUSTOMER_ACCESSORIAL_SCHEDULE",
          "CUSTOMER_AGREEMENT",
          "CUSTOMER_AWARDED_BIDS",
          "CUSTOMER_AWARDED_RATES_LANES",
          "CUSTOMER_CREDIT_REPORT",
          "DELIVERY_ALERT",
          "FACTOR_NOTICE_OF_ASSIGNMENT",
          "FREIGHT_BILL",
          "FUEL_RECEIPT",
          "GBL",
          "HOUSE_AIRWAY_BILL_LABEL",
          "HOUSE_AIRWAY_BILL_LABEL_MULTI",
          "IAC_CERTIFICATION",
          "INTERNATIONAL_HOUSE_AIRWAY_BILL",
          "INTERNATIONAL_MASTER_AIRWAY_BILL",
          "LOAD_SUMMARY",
          "LOG",
          "LOGO",
          "LOGO_DOC",
          "LOGO_RECTANGLE",
          "PACKING_LIST",
          "PHOTOGRAPH",
          "PROOF_OF_PERFORMANCE",
          "REEFER_KEYPAD",
          "ROUTING_ALERT",
          "SCALE_RECEIPT",
          "SEAL",
          "SHIPPING_LABEL",
          "SIDE_OF_TRUCK",
          "SIGNED_CARRIER_AGREEMENT",
          "TRIP_SHEET",
          "OTHER"
        ],
        "description": "Type of document.\n\nCommon types:\n- `INVOICE`: Customer invoice\n- `BILL_OF_LADING`: Bill of lading document\n- `RATE_CON`: Rate confirmation\n- `PROOF_OF_DELIVERY`: Proof of delivery (POD)\n- `CERTIFICATE_OF_INSURANCE`: Certificate of insurance (COI)\n- `W9`: W-9 tax form\n- `CARRIER_INVOICE`: Carrier invoice/bill\n- `LUMPER_RECEIPT`: Lumper receipt\n- `DETENTION`: Detention documentation\n- `DELIVERY_ORDER`: Delivery order\n- `LOAD_TENDER`: Load tender\n- `HOUSE_AIRWAY_BILL`: House airway bill (HAWB)\n- `MASTER_AIRWAY_BILL`: Master airway bill (MAWB)\n- `QUOTE`: Quote document\n- `OTHER`: Other document type\n\nThe remaining values mirror the document types available in the MVMNT\nTMS UI (carrier compliance, air freight, customer agreements, receipts,\nalerts, and branding assets).\n\nValues outside this list are rejected with 400. Documents created\ninternally with other types are returned as `OTHER`.\n"
      },
      "DocumentStatus": {
        "type": "string",
        "enum": [
          "PENDING_UPLOAD",
          "UPLOADED"
        ],
        "description": "Upload status of the document.\n- `PENDING_UPLOAD`: Document record created, file not yet uploaded\n- `UPLOADED`: File has been uploaded to storage\n"
      },
      "Document": {
        "type": "object",
        "required": [
          "id",
          "type",
          "fileName",
          "contentType",
          "status",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the document",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "key": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512,
            "description": "Client-defined key for external reference",
            "example": "doc-inv-2025-001"
          },
          "type": {
            "$ref": "#/components/schemas/DocumentType"
          },
          "fileName": {
            "type": "string",
            "description": "Original file name",
            "example": "invoice-2025-001.pdf"
          },
          "extension": {
            "type": "string",
            "description": "File extension (without dot)",
            "example": "pdf"
          },
          "contentType": {
            "type": "string",
            "description": "MIME content type",
            "example": "application/pdf"
          },
          "fileSize": {
            "type": [
              "integer",
              "null"
            ],
            "description": "File size in bytes",
            "example": 102400
          },
          "status": {
            "$ref": "#/components/schemas/DocumentStatus"
          },
          "uploadUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Pre-signed URL for uploading the file.\nOnly present immediately after document creation.\nExpires after 15 minutes.\n",
            "example": "https://s3.amazonaws.com/bucket/key?signature=..."
          },
          "downloadUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Pre-signed URL for downloading the file.\nPresent when document status is UPLOADED.\nExpires after 1 hour.\n",
            "example": "https://s3.amazonaws.com/bucket/key?signature=..."
          },
          "tags": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "description": "Arbitrary key-value tags for the document",
            "example": {
              "invoiceNumber": "INV-2025-001",
              "customerPO": "PO-12345"
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the document was created",
            "example": "2025-01-15T10:30:00Z"
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the document was last updated",
            "example": "2025-01-15T10:35:00Z"
          }
        }
      },
      "DocumentInput": {
        "type": "object",
        "required": [
          "type",
          "fileName",
          "contentType"
        ],
        "properties": {
          "key": {
            "type": "string",
            "maxLength": 512,
            "description": "Optional client-defined key for external reference",
            "example": "doc-inv-2025-001"
          },
          "type": {
            "$ref": "#/components/schemas/DocumentType"
          },
          "fileName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "description": "File name (including extension)",
            "example": "invoice-2025-001.pdf"
          },
          "contentType": {
            "type": "string",
            "description": "MIME content type of the file",
            "example": "application/pdf"
          },
          "fileSize": {
            "type": "integer",
            "minimum": 1,
            "description": "File size in bytes (optional, for validation)",
            "example": 102400
          },
          "tags": {
            "type": "object",
            "additionalProperties": true,
            "description": "Optional key-value tags",
            "example": {
              "invoiceNumber": "INV-2025-001"
            }
          }
        }
      },
      "DocumentPatch": {
        "type": "object",
        "description": "Partial document update. All fields are optional.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "properties": {
          "key": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512,
            "description": "Update client-defined key"
          },
          "type": {
            "$ref": "#/components/schemas/DocumentType"
          },
          "fileName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "description": "Update file name"
          },
          "tags": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "description": "Update or clear tags (null to clear)"
          }
        }
      },
      "DocumentFilter": {
        "type": "object",
        "properties": {
          "entityType": {
            "$ref": "#/components/schemas/DocumentEntityType"
          },
          "entityId": {
            "type": "string",
            "format": "uuid",
            "description": "Scope results to documents attached to this entity. Must be provided\ntogether with `entityType`. Must appear at the top level of the\nfilter (not nested inside `or` or `not` clauses). Combines with the\nother filter fields (they apply on top of the entity scope).\n"
          },
          "id": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "type": {
            "$ref": "#/components/schemas/DocumentTypeFilter"
          },
          "status": {
            "$ref": "#/components/schemas/DocumentStatusFilter"
          },
          "fileName": {
            "$ref": "#/components/schemas/StringFilter"
          },
          "contentType": {
            "$ref": "#/components/schemas/StringFilter"
          },
          "extension": {
            "$ref": "#/components/schemas/StringFilter"
          },
          "createdAt": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "updatedAt": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "and": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DocumentFilter"
            }
          },
          "or": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DocumentFilter"
            }
          },
          "not": {
            "$ref": "#/components/schemas/DocumentFilter"
          }
        },
        "description": "Filter criteria for documents"
      },
      "DocumentFilterRequest": {
        "type": "object",
        "properties": {
          "filter": {
            "$ref": "#/components/schemas/DocumentFilter"
          },
          "pageSize": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50,
            "description": "Number of results per page"
          },
          "cursor": {
            "type": "string",
            "description": "Pagination cursor from previous response"
          }
        },
        "description": "Request body for filtering documents"
      },
      "QuoteStatus": {
        "type": "string",
        "enum": [
          "CREATED",
          "NOT_A_QUOTE",
          "DRAFT",
          "REQUESTED",
          "QUOTED",
          "RECEIVED_REPLY",
          "SENT_REPLY",
          "RECEIVED_COUNTER",
          "SENT_COUNTER",
          "WON",
          "LOST",
          "PASS",
          "CANCELED"
        ],
        "description": "Current status in the quote lifecycle.\n\nInitial states:\n- `CREATED`: Quote being built (not yet drafted)\n- `NOT_A_QUOTE`: Marked as not an actual quote\n- `DRAFT`: Quote being drafted\n- `REQUESTED`: Customer requested a quote (needs pricing)\n\nActive states:\n- `QUOTED`: Price sent to customer\n- `RECEIVED_REPLY`: Received reply from customer\n- `SENT_REPLY`: Sent reply to customer\n- `RECEIVED_COUNTER`: Received counter-offer\n- `SENT_COUNTER`: Sent counter-offer\n\nFinal states:\n- `WON`: Customer accepted the quote\n- `LOST`: Quote not accepted\n- `PASS`: Broker declined to quote\n- `CANCELED`: Quote canceled\n"
      },
      "QuoteSide": {
        "type": "string",
        "enum": [
          "SELL",
          "BUY"
        ],
        "description": "Quote direction.\n- `SELL`: Selling to shipper (customer quote)\n- `BUY`: Buying from carrier (carrier quote)\n"
      },
      "QuoteLostReason": {
        "type": "string",
        "enum": [
          "EXPIRED",
          "NO_REASON",
          "NO_RESPONSE",
          "TOO_HIGH",
          "TOO_SLOW",
          "TRUCK_NOT_AVAILABLE",
          "WITHDRAWN",
          "OTHER"
        ],
        "description": "Reason why the quote was lost.\n- `EXPIRED`: Quote expired without response\n- `NO_REASON`: No specific reason given\n- `NO_RESPONSE`: Customer didn't respond\n- `TOO_HIGH`: Price was too high\n- `TOO_SLOW`: Response was too slow\n- `TRUCK_NOT_AVAILABLE`: Capacity not available\n- `WITHDRAWN`: The offer was withdrawn before it was accepted\n- `OTHER`: Other reason (see lostReasonText)\n"
      },
      "TransportMode": {
        "type": "string",
        "enum": [
          "FTL",
          "TL",
          "LTL",
          "PTL",
          "RLTL",
          "AIR",
          "OCEAN",
          "RAIL",
          "INTERMODAL",
          "DRAYAGE",
          "AUTO",
          "EXPEDITED_AIR",
          "EXPEDITED_GROUND"
        ],
        "description": "Transportation mode. Optional on write — a shipment or load created\nwithout one is stored with no mode, the same as one created in the TMS.\n- `FTL`: Full Truckload — the value the TMS stores and always returns\n- `TL`: legacy spelling of `FTL`, still accepted on write, never returned\n- `LTL`: Less than Truckload\n- `PTL`: Partial Truckload\n- `RLTL`: Retail LTL\n- `AUTO`: Auto transport\n- `EXPEDITED_AIR`: Expedited air\n- `EXPEDITED_GROUND`: Expedited ground\n- `AIR`: Air freight\n- `OCEAN`: Ocean freight\n- `RAIL`: Rail freight\n- `INTERMODAL`: Intermodal (multiple modes)\n- `DRAYAGE`: Drayage/cartage\n"
      },
      "OrderInput": {
        "type": "object",
        "required": [
          "stops",
          "mode"
        ],
        "properties": {
          "mode": {
            "$ref": "#/components/schemas/TransportMode"
          },
          "stops": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderStopInput"
            },
            "minItems": 2,
            "description": "At least origin and destination stops"
          },
          "freight": {
            "$ref": "#/components/schemas/OrderFreightInput"
          },
          "equipment": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResourceReferenceInput"
            },
            "description": "Equipment types required"
          },
          "references": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "type",
                "value"
              ],
              "properties": {
                "type": {
                  "type": "string",
                  "description": "Reference type (e.g., BOL_NUMBER, PO_NUMBER)"
                },
                "value": {
                  "type": "string",
                  "description": "Reference value"
                }
              }
            },
            "description": "Reference numbers for the order"
          },
          "specialRequirements": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResourceReferenceInput"
            },
            "description": "Special requirements (e.g., liftgate, team drivers)"
          }
        },
        "description": "Order definition used when creating Quotes or Shipments.\nContains route (stops), freight details, and requirements.\n"
      },
      "OrderStopInput": {
        "type": "object",
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "PICKUP",
              "DELIVERY"
            ],
            "description": "Type of stop"
          },
          "location": {
            "$ref": "#/components/schemas/ResourceReferenceInput",
            "description": "Reference to an existing location"
          },
          "address": {
            "$ref": "#/components/schemas/AddressInput",
            "description": "Address for ad-hoc stop (if no location reference)"
          },
          "requestedStartDate": {
            "type": "string",
            "format": "date",
            "description": "Requested start date for the stop"
          },
          "requestedEndDate": {
            "type": "string",
            "format": "date",
            "description": "Requested end date for the stop"
          },
          "requestedStartTime": {
            "type": "string",
            "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$",
            "description": "Requested start time (HH:MM format)"
          },
          "requestedEndTime": {
            "type": "string",
            "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$",
            "description": "Requested end time (HH:MM format)"
          },
          "appointmentRequired": {
            "type": "boolean",
            "default": false,
            "description": "Whether an appointment is required"
          },
          "notes": {
            "type": "string",
            "maxLength": 2000,
            "description": "Special instructions for the stop"
          }
        },
        "description": "Stop definition for an order"
      },
      "OrderFreightInput": {
        "type": "object",
        "properties": {
          "handlingUnitQuantity": {
            "type": "integer",
            "minimum": 1,
            "description": "Number of handling units"
          },
          "handlingUnitType": {
            "type": "string",
            "description": "Handling unit name. Org-configurable list (e.g. Pallet, Skid, Crate,\nDrum, Roll, Gaylord, Totes) — not a closed enum; match the names your\norganization uses in the TMS.\n"
          },
          "weight": {
            "type": "number",
            "minimum": 0,
            "description": "Total weight in pounds"
          },
          "volume": {
            "type": "number",
            "minimum": 0,
            "description": "Total volume in cubic feet. Accepted for compatibility but not\ncurrently persisted.\n"
          },
          "length": {
            "type": "number",
            "minimum": 0,
            "description": "Length in inches"
          },
          "width": {
            "type": "number",
            "minimum": 0,
            "description": "Width in inches"
          },
          "height": {
            "type": "number",
            "minimum": 0,
            "description": "Height in inches"
          },
          "commodityDescription": {
            "type": "string",
            "maxLength": 500,
            "description": "Description of the commodity"
          },
          "hazmat": {
            "type": "boolean",
            "default": false,
            "description": "Whether freight is hazardous materials"
          },
          "stackable": {
            "type": "boolean",
            "default": true,
            "description": "Whether freight is stackable"
          }
        },
        "description": "Freight details for an order"
      },
      "Quote": {
        "type": "object",
        "required": [
          "id",
          "friendlyId",
          "side",
          "status",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "friendlyId": {
            "type": "string",
            "description": "Human-readable quote ID (e.g., \"Q003602\")",
            "example": "Q003602"
          },
          "key": {
            "type": [
              "string",
              "null"
            ],
            "description": "Client-defined reference identifier for this quote",
            "example": "my-quote-001"
          },
          "side": {
            "$ref": "#/components/schemas/QuoteSide"
          },
          "status": {
            "$ref": "#/components/schemas/QuoteStatus"
          },
          "amount": {
            "type": [
              "number",
              "null"
            ],
            "description": "Quoted price",
            "example": 2500
          },
          "target": {
            "type": [
              "number",
              "null"
            ],
            "description": "Target price for margin calculation",
            "example": 2200
          },
          "margin": {
            "type": [
              "number",
              "null"
            ],
            "description": "Calculated margin percentage",
            "example": 12
          },
          "expiresAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Quote expiration timestamp"
          },
          "customer": {
            "$ref": "#/components/schemas/CustomerReference",
            "description": "Customer (for SELL quotes)"
          },
          "carrier": {
            "$ref": "#/components/schemas/CarrierReference",
            "description": "Carrier (for BUY quotes)"
          },
          "order": {
            "$ref": "#/components/schemas/OrderSummary",
            "description": "Order details (route, freight)"
          },
          "lostReason": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/QuoteLostReason"
              },
              {
                "type": "null"
              }
            ],
            "description": "Why the quote was lost"
          },
          "lostReasonText": {
            "type": [
              "string",
              "null"
            ],
            "description": "Additional text for lost reason"
          },
          "closedTime": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the quote was closed (won/lost)"
          },
          "assignee": {
            "$ref": "#/components/schemas/UserReference",
            "description": "Assigned sales rep"
          },
          "shipmentId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Shipment ID if converted"
          },
          "shipmentKey": {
            "type": [
              "string",
              "null"
            ],
            "description": "Shipment friendly ID if converted"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "QuoteInput": {
        "type": "object",
        "required": [
          "customer",
          "order"
        ],
        "properties": {
          "customer": {
            "$ref": "#/components/schemas/ResourceReferenceInput",
            "description": "Customer reference (for SELL quotes)"
          },
          "carrier": {
            "$ref": "#/components/schemas/ResourceReferenceInput",
            "description": "Carrier reference (for BUY quotes)"
          },
          "order": {
            "$ref": "#/components/schemas/OrderInput",
            "description": "Order details (route, freight)"
          },
          "amount": {
            "type": "number",
            "minimum": 0,
            "description": "Quoted price"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "description": "Quote expiration"
          },
          "assignee": {
            "$ref": "#/components/schemas/ResourceReferenceInput",
            "description": "Assigned user"
          }
        },
        "description": "Input for creating a new quote"
      },
      "QuotePatch": {
        "type": "object",
        "properties": {
          "status": {
            "$ref": "#/components/schemas/QuoteStatus"
          },
          "amount": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0
          },
          "target": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0
          },
          "expiresAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "lostReason": {
            "$ref": "#/components/schemas/QuoteLostReason",
            "description": "Required when status is LOST"
          },
          "lostReasonText": {
            "type": "string",
            "description": "Required when lostReason is OTHER"
          },
          "assignee": {
            "$ref": "#/components/schemas/ResourceReferenceInput"
          }
        },
        "description": "Partial update fields for a quote.\n\n**Validation rules:**\n- When `status` is `LOST`, `lostReason` is required\n- When `lostReason` is `OTHER`, `lostReasonText` is required\n"
      },
      "QuoteFilter": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "status": {
            "$ref": "#/components/schemas/QuoteStatusFilter"
          },
          "side": {
            "$ref": "#/components/schemas/QuoteSideFilter"
          },
          "customerId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "carrierId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "assigneeId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "amount": {
            "$ref": "#/components/schemas/FloatFilter"
          },
          "expiresAt": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "createdAt": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "updatedAt": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "and": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QuoteFilter"
            }
          },
          "or": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QuoteFilter"
            }
          },
          "not": {
            "$ref": "#/components/schemas/QuoteFilter"
          }
        }
      },
      "QuoteFilterRequest": {
        "type": "object",
        "properties": {
          "filter": {
            "$ref": "#/components/schemas/QuoteFilter"
          },
          "pageSize": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          },
          "cursor": {
            "type": "string"
          }
        }
      },
      "ConvertToShipmentRequest": {
        "type": "object",
        "properties": {
          "additionalOrders": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderInput"
            },
            "description": "Optional additional orders to add to the shipment"
          }
        },
        "description": "Request body for converting a quote to a shipment"
      },
      "ConvertToShipmentResponse": {
        "type": "object",
        "required": [
          "quoteId",
          "quoteStatus",
          "shipmentId",
          "shipmentKey",
          "orderId"
        ],
        "properties": {
          "quoteId": {
            "type": "string",
            "format": "uuid",
            "description": "Quote ID that was converted"
          },
          "quoteStatus": {
            "type": "string",
            "enum": [
              "WON"
            ],
            "description": "Quote status after conversion (always WON)"
          },
          "shipmentId": {
            "type": "string",
            "format": "uuid",
            "description": "Created shipment ID"
          },
          "shipmentKey": {
            "type": "string",
            "description": "Created shipment friendly ID"
          },
          "orderId": {
            "type": "string",
            "format": "uuid",
            "description": "Order ID from the quote"
          }
        }
      },
      "ShipmentLifecycleStatus": {
        "type": "string",
        "enum": [
          "DRAFT",
          "TENDER_PENDING",
          "ON_HOLD",
          "PLANNING",
          "SELECTED",
          "BOOKED",
          "DISPATCHED",
          "LOADING",
          "PICKED_UP",
          "IN_TRANSIT",
          "UNLOADING",
          "ARRIVED_AT_DELIVERY_TERMINAL",
          "OUT_FOR_DELIVERY",
          "RECOVERED",
          "DELIVERED",
          "CANCELED",
          "TENDER_REJECTED",
          "CONSOLIDATED"
        ],
        "description": "Current status of the shipment lifecycle.\n\n**Pre-transit:**\n- `DRAFT`: Shipment being created\n- `TENDER_PENDING`: Awaiting carrier tender acceptance\n- `TENDER_REJECTED`: Carrier rejected the tender\n- `ON_HOLD`: Shipment temporarily paused\n- `PLANNING`: Being planned/scheduled\n- `SELECTED`: Carrier selected\n- `BOOKED`: Carrier confirmed booking\n- `DISPATCHED`: Dispatched to carrier\n\n**In-transit:**\n- `LOADING`: Loading at pickup\n- `PICKED_UP`: Picked up\n- `IN_TRANSIT`: In transit\n- `UNLOADING`: Unloading at delivery\n- `ARRIVED_AT_DELIVERY_TERMINAL`: At delivery terminal (LTL)\n- `OUT_FOR_DELIVERY`: Out for final delivery\n- `RECOVERED`: Shipment has been recovered\n\n**Final:**\n- `DELIVERED`: Delivered\n- `CANCELED`: Canceled\n- `CONSOLIDATED`: Merged into a consolidated shipment\n"
      },
      "OrderBillingStatus": {
        "type": "string",
        "enum": [
          "DOCS_NEEDED",
          "NOT_READY_TO_INVOICE",
          "READY_TO_INVOICE",
          "INVOICED",
          "PAID"
        ],
        "description": "Billing status for the order (AR side).\n- `DOCS_NEEDED`: Waiting for delivery documents\n- `NOT_READY_TO_INVOICE`: Not ready to invoice\n- `READY_TO_INVOICE`: Ready to generate invoice\n- `INVOICED`: Invoice generated and sent\n- `PAID`: Fully paid\n"
      },
      "Order": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "friendlyId": {
            "type": "string",
            "description": "Human-readable order ID (e.g., \"ORD-12345\")"
          },
          "key": {
            "type": [
              "string",
              "null"
            ],
            "description": "Client-defined reference identifier for this order"
          },
          "mode": {
            "$ref": "#/components/schemas/TransportMode"
          },
          "status": {
            "$ref": "#/components/schemas/ShipmentLifecycleStatus"
          },
          "billingStatus": {
            "$ref": "#/components/schemas/OrderBillingStatus"
          },
          "stops": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderStop"
            },
            "description": "Flattened stops array"
          },
          "freight": {
            "$ref": "#/components/schemas/OrderFreight"
          },
          "references": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderReference"
            }
          },
          "charges": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderCharge"
            }
          },
          "equipment": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Equipment ids. Resolve names via the reference-data equipment endpoint."
          },
          "specialRequirements": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Special-requirement ids. Resolve names via the reference-data endpoint."
          },
          "mileage": {
            "type": [
              "number",
              "null"
            ]
          },
          "totalRevenue": {
            "type": [
              "number",
              "null"
            ],
            "description": "Sum of all charges"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "OrderStop": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "type": {
            "type": "string",
            "enum": [
              "PICKUP",
              "DELIVERY"
            ]
          },
          "sequence": {
            "type": "integer",
            "description": "Stop order in the route"
          },
          "location": {
            "$ref": "#/components/schemas/ResourceReference"
          },
          "address": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Address"
              }
            ],
            "description": "Full address from the stop's linked location. Absent when the stop\nhas no linked shipper location.\n"
          },
          "requestedStartDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "requestedEndDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "requestedStartTime": {
            "type": [
              "string",
              "null"
            ]
          },
          "requestedEndTime": {
            "type": [
              "string",
              "null"
            ]
          },
          "actualArrival": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "actualDeparture": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "appointmentRequired": {
            "type": "boolean"
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "OrderFreight": {
        "type": "object",
        "properties": {
          "handlingUnitQuantity": {
            "type": [
              "integer",
              "null"
            ]
          },
          "handlingUnitType": {
            "type": [
              "string",
              "null"
            ]
          },
          "weight": {
            "type": [
              "number",
              "null"
            ],
            "description": "Weight in pounds"
          },
          "volume": {
            "type": [
              "number",
              "null"
            ],
            "description": "Volume in cubic feet"
          },
          "length": {
            "type": [
              "number",
              "null"
            ]
          },
          "width": {
            "type": [
              "number",
              "null"
            ]
          },
          "height": {
            "type": [
              "number",
              "null"
            ]
          },
          "commodityDescription": {
            "type": [
              "string",
              "null"
            ]
          },
          "hazmat": {
            "type": "boolean"
          },
          "stackable": {
            "type": "boolean"
          }
        }
      },
      "OrderCharge": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "chargeCodeId": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Charge code id. Resolve code/name via the reference-data charge-codes endpoint."
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "amount": {
            "type": "number"
          },
          "quantity": {
            "type": "number",
            "default": 1
          },
          "rate": {
            "type": [
              "number",
              "null"
            ]
          }
        }
      },
      "Shipment": {
        "type": "object",
        "required": [
          "id",
          "friendlyId",
          "status",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "friendlyId": {
            "type": "string",
            "description": "Human-readable shipment ID (e.g., \"SHP-12345\")",
            "example": "SHP-12345"
          },
          "key": {
            "type": [
              "string",
              "null"
            ],
            "description": "Client-defined reference identifier for this shipment",
            "example": "my-shipment-001"
          },
          "status": {
            "$ref": "#/components/schemas/ShipmentLifecycleStatus"
          },
          "customer": {
            "$ref": "#/components/schemas/CustomerReference"
          },
          "customerRep": {
            "$ref": "#/components/schemas/UserReference",
            "description": "Customer representative"
          },
          "orders": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Order"
            },
            "description": "Orders in this shipment"
          },
          "loads": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LoadSummary"
            },
            "description": "Loads for carrier execution"
          },
          "services": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ServiceSummary"
            },
            "description": "Vended services"
          },
          "totalRevenue": {
            "type": [
              "number",
              "null"
            ],
            "description": "Sum of all order charges"
          },
          "totalCost": {
            "type": [
              "number",
              "null"
            ],
            "description": "Sum of all load and service costs"
          },
          "margin": {
            "type": [
              "number",
              "null"
            ],
            "description": "Revenue minus cost"
          },
          "marginPercent": {
            "type": [
              "number",
              "null"
            ],
            "description": "Margin as percentage of revenue"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "deliveredAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "ShipmentInput": {
        "type": "object",
        "required": [
          "customer",
          "orders"
        ],
        "properties": {
          "customer": {
            "$ref": "#/components/schemas/ResourceReferenceInput",
            "description": "Customer reference"
          },
          "customerRep": {
            "$ref": "#/components/schemas/ResourceReferenceInput",
            "description": "Assigned customer rep"
          },
          "orders": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderInput"
            },
            "minItems": 1,
            "description": "Orders to create (at least one required)"
          },
          "loads": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LoadInput"
            },
            "description": "Optional loads to create"
          },
          "services": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ServiceInput"
            },
            "description": "Optional services to create"
          }
        }
      },
      "ShipmentPatch": {
        "type": "object",
        "properties": {
          "customer": {
            "$ref": "#/components/schemas/ResourceReferenceInput"
          },
          "customerRep": {
            "$ref": "#/components/schemas/ResourceReferenceInput"
          }
        },
        "description": "Partial update fields for a shipment"
      },
      "ShipmentFilter": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "key": {
            "$ref": "#/components/schemas/StringFilter"
          },
          "status": {
            "$ref": "#/components/schemas/ShipmentStatusFilter"
          },
          "customerId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "customerRepId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "createdAt": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "updatedAt": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "deliveredAt": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "and": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShipmentFilter"
            }
          },
          "or": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShipmentFilter"
            }
          },
          "not": {
            "$ref": "#/components/schemas/ShipmentFilter"
          }
        }
      },
      "ShipmentFilterRequest": {
        "type": "object",
        "properties": {
          "filter": {
            "$ref": "#/components/schemas/ShipmentFilter"
          },
          "pageSize": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          },
          "cursor": {
            "type": "string"
          }
        }
      },
      "CancelShipmentRequest": {
        "type": "object",
        "properties": {
          "reason": {
            "type": "string",
            "maxLength": 1000,
            "description": "Reason for cancellation"
          }
        },
        "description": "Request body for canceling a shipment"
      },
      "DuplicateShipmentRequest": {
        "type": "object",
        "properties": {
          "pickUpDate": {
            "type": "string",
            "format": "date",
            "description": "New pickup date for the duplicate"
          },
          "deliveryDate": {
            "type": "string",
            "format": "date",
            "description": "New delivery date for the duplicate"
          }
        },
        "description": "Request body for duplicating a shipment"
      },
      "DuplicateShipmentResponse": {
        "type": "object",
        "required": [
          "originalShipmentId",
          "newShipmentId",
          "newShipmentKey"
        ],
        "properties": {
          "originalShipmentId": {
            "type": "string",
            "format": "uuid"
          },
          "newShipmentId": {
            "type": "string",
            "format": "uuid"
          },
          "newShipmentKey": {
            "type": "string"
          }
        }
      },
      "LoadStatus": {
        "type": "string",
        "enum": [
          "SOURCING",
          "SELECTED",
          "BOOKED",
          "DISPATCHED",
          "LOADING",
          "PICKED_UP",
          "IN_TRANSIT",
          "UNLOADING",
          "ARRIVED_AT_DELIVERY_TERMINAL",
          "OUT_FOR_DELIVERY",
          "RECOVERED",
          "DELIVERED_AWAITING_INVOICE",
          "DELIVERED_INVOICE_IN_REVIEW",
          "DELIVERED_APPROVED_TO_BE_PAID",
          "DELIVERED_PAID",
          "COMPLETE",
          "SERVICE_FAILURE",
          "ON_HOLD",
          "CANCELED"
        ],
        "description": "Current status of the load.\n\n**Pre-transit:**\n- `SOURCING`: Looking for carrier\n- `SELECTED`: Carrier selected\n- `BOOKED`: Carrier booked\n- `DISPATCHED`: Dispatched to carrier\n\n**In-transit:**\n- `LOADING`: Loading at pickup\n- `PICKED_UP`: Picked up\n- `IN_TRANSIT`: In transit\n- `UNLOADING`: Unloading at delivery\n- `ARRIVED_AT_DELIVERY_TERMINAL`: Arrived at delivery terminal\n- `OUT_FOR_DELIVERY`: Out for delivery\n- `RECOVERED`: Recovered after a service issue\n\n**Delivered (accounts payable lifecycle):**\n- `DELIVERED_AWAITING_INVOICE`: Delivered, awaiting carrier invoice\n- `DELIVERED_INVOICE_IN_REVIEW`: Carrier invoice in review\n- `DELIVERED_APPROVED_TO_BE_PAID`: Approved to be paid\n- `DELIVERED_PAID`: Paid\n\n**Final / exceptions:**\n- `COMPLETE`: Complete\n- `SERVICE_FAILURE`: Service failure\n- `ON_HOLD`: On hold\n- `CANCELED`: Canceled\n"
      },
      "LoadCarrierStatus": {
        "type": "string",
        "enum": [
          "ACTIVE",
          "TONU",
          "BOUNCED"
        ],
        "description": "Status of the carrier assignment.\n- `ACTIVE`: Carrier is actively assigned\n- `TONU`: Truck Ordered Not Used (carrier dispatched but cancelled)\n- `BOUNCED`: Carrier bounced/rejected load\n"
      },
      "LoadBillingStatus": {
        "type": "string",
        "enum": [
          "AWAITING_INVOICE",
          "INVOICE_IN_REVIEW",
          "APPROVED_TO_PAY",
          "PAID"
        ],
        "description": "Billing status for the load (AP side).\n- `AWAITING_INVOICE`: Waiting for carrier invoice\n- `INVOICE_IN_REVIEW`: Invoice received, under review\n- `APPROVED_TO_PAY`: Approved for payment\n- `PAID`: Paid to carrier\n"
      },
      "Load": {
        "type": "object",
        "required": [
          "id",
          "status",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "friendlyId": {
            "type": "string",
            "description": "Human-readable load ID (e.g., \"LD-12345\")",
            "example": "LD-12345"
          },
          "key": {
            "type": [
              "string",
              "null"
            ],
            "description": "Client-defined reference identifier for this load",
            "example": "my-load-001"
          },
          "shipmentId": {
            "type": "string",
            "format": "uuid",
            "description": "Parent shipment"
          },
          "shipmentKey": {
            "type": [
              "string",
              "null"
            ],
            "description": "Parent shipment human-readable ID (friendlyId)"
          },
          "mode": {
            "$ref": "#/components/schemas/TransportMode"
          },
          "status": {
            "$ref": "#/components/schemas/LoadStatus"
          },
          "stops": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LoadStop"
            },
            "description": "Load stops"
          },
          "carriers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LoadCarrier"
            },
            "description": "Carrier assignments (flattened from LoadCarriersConnection)"
          },
          "totalCost": {
            "type": [
              "number",
              "null"
            ],
            "description": "Total carrier costs"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "pickedUpAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "deliveredAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "LoadCarrier": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "carrier": {
            "$ref": "#/components/schemas/CarrierReference"
          },
          "contact": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string"
              },
              "phone": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "email": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "status": {
            "$ref": "#/components/schemas/LoadCarrierStatus"
          },
          "billingStatus": {
            "$ref": "#/components/schemas/LoadBillingStatus"
          },
          "bookedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "dispatchedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "removedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When this assignment was removed from the load (bounce, TONU, rebook).\nRemoved assignments stay in `carriers` as history but their charges\nare excluded from the load `totalCost`.\n"
          },
          "charges": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LoadCarrierCharge"
            },
            "description": "Flattened charges array"
          },
          "totalCost": {
            "type": [
              "number",
              "null"
            ],
            "description": "Sum of all charges"
          },
          "driverName": {
            "type": [
              "string",
              "null"
            ]
          },
          "driverPhone": {
            "type": [
              "string",
              "null"
            ]
          },
          "truckNumber": {
            "type": [
              "string",
              "null"
            ]
          },
          "trailerNumber": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "LoadInput": {
        "type": "object",
        "properties": {
          "mode": {
            "$ref": "#/components/schemas/TransportMode"
          },
          "orderStopIds": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Order stop IDs to include in this load"
          },
          "carrier": {
            "$ref": "#/components/schemas/LoadCarrierInput",
            "description": "Initial carrier assignment"
          }
        }
      },
      "LoadCarrierInput": {
        "type": "object",
        "required": [
          "carrier"
        ],
        "properties": {
          "carrier": {
            "$ref": "#/components/schemas/ResourceReferenceInput",
            "description": "Carrier reference"
          },
          "contact": {
            "$ref": "#/components/schemas/ResourceReferenceInput",
            "description": "Carrier contact"
          },
          "charges": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "chargeCode",
                "amount"
              ],
              "properties": {
                "chargeCode": {
                  "$ref": "#/components/schemas/ResourceReferenceInput"
                },
                "description": {
                  "type": "string"
                },
                "amount": {
                  "type": "number"
                },
                "quantity": {
                  "type": "number",
                  "default": 1
                }
              }
            }
          },
          "driverName": {
            "type": "string"
          },
          "driverPhone": {
            "type": "string"
          },
          "truckNumber": {
            "type": "string"
          },
          "trailerNumber": {
            "type": "string"
          }
        }
      },
      "LoadPatch": {
        "type": "object",
        "properties": {
          "mode": {
            "$ref": "#/components/schemas/TransportMode"
          }
        }
      },
      "LoadCarrierPatch": {
        "type": "object",
        "properties": {
          "contact": {
            "$ref": "#/components/schemas/ResourceReferenceInput"
          },
          "driverName": {
            "type": [
              "string",
              "null"
            ]
          },
          "driverPhone": {
            "type": [
              "string",
              "null"
            ]
          },
          "truckNumber": {
            "type": [
              "string",
              "null"
            ]
          },
          "trailerNumber": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "LoadFilter": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "shipmentId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "status": {
            "$ref": "#/components/schemas/LoadStatusFilter"
          },
          "mode": {
            "type": "object",
            "properties": {
              "equalTo": {
                "$ref": "#/components/schemas/TransportMode"
              },
              "in": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/TransportMode"
                }
              }
            }
          },
          "createdAt": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "deliveredAt": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "and": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LoadFilter"
            }
          },
          "or": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LoadFilter"
            }
          },
          "not": {
            "$ref": "#/components/schemas/LoadFilter"
          }
        }
      },
      "LoadFilterRequest": {
        "type": "object",
        "properties": {
          "filter": {
            "$ref": "#/components/schemas/LoadFilter"
          },
          "pageSize": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          },
          "cursor": {
            "type": "string"
          }
        }
      },
      "ReportTonuRequest": {
        "type": "object",
        "properties": {
          "reason": {
            "type": "string",
            "maxLength": 1000,
            "description": "Reason for TONU"
          },
          "costs": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "chargeCode",
                "amount"
              ],
              "properties": {
                "chargeCode": {
                  "$ref": "#/components/schemas/ResourceReferenceInput"
                },
                "description": {
                  "type": "string"
                },
                "amount": {
                  "type": "number"
                }
              }
            },
            "description": "TONU costs to record"
          },
          "createReplacementLoad": {
            "type": "boolean",
            "default": false,
            "description": "Whether to create a replacement load"
          }
        },
        "description": "Request body for reporting TONU"
      },
      "BounceCarrierRequest": {
        "type": "object",
        "properties": {
          "reason": {
            "$ref": "#/components/schemas/LoadCarrierRemovalReason"
          },
          "reasonText": {
            "type": "string",
            "maxLength": 1000,
            "description": "Additional reason details"
          }
        },
        "description": "Request body for bouncing a carrier"
      },
      "ServiceStatus": {
        "type": "string",
        "enum": [
          "ACTIVE",
          "AWAITING_INVOICE",
          "INVOICE_IN_REVIEW",
          "APPROVED_TO_PAY",
          "PAID",
          "CANCELED"
        ],
        "description": "Current status of the service.\n\n**Active states:**\n- `ACTIVE`: Service is active/in progress\n\n**Billing states (AP):**\n- `AWAITING_INVOICE`: Waiting for vendor invoice\n- `INVOICE_IN_REVIEW`: Invoice received, under review\n- `APPROVED_TO_PAY`: Approved for payment\n- `PAID`: Paid to vendor\n\n**Final states:**\n- `CANCELED`: Service canceled\n"
      },
      "Service": {
        "type": "object",
        "required": [
          "id",
          "status",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "key": {
            "type": [
              "string",
              "null"
            ],
            "description": "Human-readable service ID",
            "example": "SVC-12345"
          },
          "shipmentId": {
            "type": "string",
            "format": "uuid",
            "description": "Parent shipment"
          },
          "shipmentKey": {
            "type": [
              "string",
              "null"
            ],
            "description": "Parent shipment friendly ID"
          },
          "vendor": {
            "$ref": "#/components/schemas/VendorReference"
          },
          "vendorContact": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string"
              },
              "phone": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "email": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "status": {
            "$ref": "#/components/schemas/ServiceStatus"
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Service description"
          },
          "charges": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ServiceCharge"
            },
            "description": "Flattened charges array"
          },
          "totalCost": {
            "type": [
              "number",
              "null"
            ],
            "description": "Sum of all charges"
          },
          "scheduledDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "completedDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "referenceNumber": {
            "type": [
              "string",
              "null"
            ],
            "description": "Vendor reference number"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "ServiceInput": {
        "type": "object",
        "required": [
          "vendor"
        ],
        "properties": {
          "vendor": {
            "$ref": "#/components/schemas/ResourceReferenceInput",
            "description": "Vendor reference"
          },
          "vendorContact": {
            "$ref": "#/components/schemas/ResourceReferenceInput",
            "description": "Vendor contact"
          },
          "description": {
            "type": "string",
            "maxLength": 2000
          },
          "charges": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "chargeCode",
                "amount"
              ],
              "properties": {
                "chargeCode": {
                  "$ref": "#/components/schemas/ResourceReferenceInput"
                },
                "description": {
                  "type": "string"
                },
                "amount": {
                  "type": "number"
                },
                "quantity": {
                  "type": "number",
                  "default": 1
                }
              }
            }
          },
          "scheduledDate": {
            "type": "string",
            "format": "date"
          },
          "referenceNumber": {
            "type": "string"
          }
        }
      },
      "ServicePatch": {
        "type": "object",
        "description": "Partial service update. All fields are optional.\n\n- **Omitted fields**: Not modified (current value preserved)\n- **Provided fields**: Updated to the new value\n- **Null values**: Clear the field (set to null) where applicable\n",
        "properties": {
          "vendorContact": {
            "$ref": "#/components/schemas/ResourceReferenceInput"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "scheduledDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "completedDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "referenceNumber": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ServiceFilter": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "shipmentId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "vendorId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "status": {
            "$ref": "#/components/schemas/ServiceStatusFilter"
          },
          "scheduledDate": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "completedDate": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "createdAt": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "and": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ServiceFilter"
            }
          },
          "or": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ServiceFilter"
            }
          },
          "not": {
            "$ref": "#/components/schemas/ServiceFilter"
          }
        }
      },
      "ServiceFilterRequest": {
        "type": "object",
        "properties": {
          "filter": {
            "$ref": "#/components/schemas/ServiceFilter"
          },
          "pageSize": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          },
          "cursor": {
            "type": "string"
          }
        }
      },
      "InvoiceStatus": {
        "type": "string",
        "enum": [
          "DRAFT",
          "AWAITING_PAYMENT",
          "PARTIALLY_PAID",
          "PAID",
          "VOIDED"
        ],
        "description": "Current status of the invoice.\n- `DRAFT`: Invoice record exists but not finalized\n- `AWAITING_PAYMENT`: Invoice finalized, awaiting payment\n- `PARTIALLY_PAID`: Some payments received, balance remains\n- `PAID`: Fully paid\n- `VOIDED`: Invoice cancelled/voided\n"
      },
      "FactoringProvider": {
        "type": "string",
        "enum": [
          "ARTISPAY",
          "DENIM",
          "HAUL_PAY",
          "TRIUMPH"
        ],
        "description": "Factoring provider for invoice financing.\n- `DENIM`: Denim factoring\n- `HAULPAY`: HaulPay factoring\n"
      },
      "InvoicePayment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "paymentGroupId": {
            "type": "string",
            "format": "uuid"
          },
          "amount": {
            "type": "number",
            "description": "Amount applied to this invoice"
          },
          "paymentDate": {
            "type": "string",
            "format": "date"
          },
          "reference": {
            "type": [
              "string",
              "null"
            ],
            "description": "Check number, transaction ID, etc."
          },
          "paymentMethodType": {
            "type": [
              "string",
              "null"
            ],
            "description": "Payment method (check, ach_wire, etc.)"
          }
        }
      },
      "InvoiceCredit": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "creditMemoId": {
            "type": "string",
            "format": "uuid"
          },
          "creditMemoReference": {
            "type": [
              "string",
              "null"
            ]
          },
          "amount": {
            "type": "number",
            "description": "Credit amount applied"
          },
          "appliedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Invoice": {
        "type": "object",
        "required": [
          "id",
          "friendlyId",
          "status",
          "invoiceDate",
          "amount",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "friendlyId": {
            "type": "string",
            "description": "Human-readable invoice ID",
            "example": "INV-00001"
          },
          "key": {
            "type": [
              "string",
              "null"
            ],
            "description": "Client-defined key"
          },
          "orderId": {
            "type": "string",
            "format": "uuid",
            "description": "Associated order ID"
          },
          "orderKey": {
            "type": [
              "string",
              "null"
            ],
            "description": "Order friendly ID"
          },
          "shipmentId": {
            "type": "string",
            "format": "uuid",
            "description": "Associated shipment ID"
          },
          "shipmentKey": {
            "type": [
              "string",
              "null"
            ],
            "description": "Shipment friendly ID"
          },
          "customer": {
            "$ref": "#/components/schemas/CustomerReference"
          },
          "status": {
            "$ref": "#/components/schemas/InvoiceStatus"
          },
          "invoiceDate": {
            "type": "string",
            "format": "date",
            "description": "Date invoice was issued"
          },
          "dueDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Payment due date"
          },
          "amount": {
            "type": "number",
            "description": "Total invoice amount"
          },
          "currency": {
            "type": [
              "string",
              "null"
            ],
            "description": "Currency code (USD, CAD)",
            "example": "USD"
          },
          "reference": {
            "type": [
              "string",
              "null"
            ],
            "description": "External reference number"
          },
          "amountPaid": {
            "type": "number",
            "description": "Total payments received"
          },
          "amountOwed": {
            "type": "number",
            "description": "Outstanding balance"
          },
          "creditsApplied": {
            "type": [
              "number",
              "null"
            ],
            "description": "Total credits applied"
          },
          "paymentTerm": {
            "$ref": "#/components/schemas/PaymentTermReference"
          },
          "payments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InvoicePayment"
            },
            "description": "Payments applied to this invoice"
          },
          "credits": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InvoiceCredit"
            },
            "description": "Credits applied to this invoice"
          },
          "factorName": {
            "$ref": "#/components/schemas/FactoringProvider"
          },
          "factorJobId": {
            "type": [
              "string",
              "null"
            ],
            "description": "External factoring job ID"
          },
          "factorStatus": {
            "type": [
              "string",
              "null"
            ],
            "description": "Current factoring status"
          },
          "qboId": {
            "type": [
              "string",
              "null"
            ],
            "description": "QuickBooks Online invoice ID"
          },
          "documentId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Generated invoice PDF document ID"
          },
          "documentUrl": {
            "type": [
              "string",
              "null"
            ],
            "description": "Download URL for invoice PDF"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "InvoiceInput": {
        "type": "object",
        "required": [
          "orderId",
          "invoiceDate",
          "amount"
        ],
        "properties": {
          "orderId": {
            "type": "string",
            "format": "uuid",
            "description": "Order to invoice"
          },
          "invoiceDate": {
            "type": "string",
            "format": "date",
            "description": "Invoice date"
          },
          "dueDate": {
            "type": "string",
            "format": "date",
            "description": "Payment due date"
          },
          "amount": {
            "type": "number",
            "description": "Invoice amount (typically calculated from order charges)"
          },
          "reference": {
            "type": "string",
            "maxLength": 500,
            "description": "External reference number"
          },
          "currency": {
            "type": "string",
            "description": "Currency code (defaults to customer currency)"
          },
          "paymentTermId": {
            "type": "string",
            "format": "uuid",
            "description": "Payment term (defaults to customer default)"
          }
        }
      },
      "InvoicePatch": {
        "type": "object",
        "properties": {
          "dueDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "paymentTermId": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "InvoiceFilter": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "orderId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "shipmentId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "customerId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "status": {
            "$ref": "#/components/schemas/InvoiceStatusFilter"
          },
          "invoiceDate": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "dueDate": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "amount": {
            "$ref": "#/components/schemas/FloatFilter"
          },
          "amountOwed": {
            "$ref": "#/components/schemas/FloatFilter"
          },
          "overdue": {
            "type": "boolean",
            "description": "Filter to overdue invoices only"
          },
          "factored": {
            "type": "boolean",
            "description": "Filter to factored invoices only"
          },
          "createdAt": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "and": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InvoiceFilter"
            }
          },
          "or": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InvoiceFilter"
            }
          },
          "not": {
            "$ref": "#/components/schemas/InvoiceFilter"
          }
        }
      },
      "InvoiceFilterRequest": {
        "type": "object",
        "properties": {
          "filter": {
            "$ref": "#/components/schemas/InvoiceFilter"
          },
          "pageSize": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          },
          "cursor": {
            "type": "string"
          }
        }
      },
      "GenerateInvoiceRequest": {
        "type": "object",
        "properties": {
          "invoiceDate": {
            "type": "string",
            "format": "date",
            "description": "Invoice date (defaults to today)"
          },
          "dueDate": {
            "type": "string",
            "format": "date",
            "description": "Due date (defaults based on payment term)"
          },
          "attachmentDocumentIds": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Document IDs to attach to invoice PDF"
          }
        }
      },
      "GenerateInvoiceResponse": {
        "type": "object",
        "required": [
          "invoice",
          "document"
        ],
        "properties": {
          "invoice": {
            "$ref": "#/components/schemas/Invoice"
          },
          "document": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "url": {
                "type": "string",
                "description": "Download URL for invoice PDF"
              }
            }
          }
        }
      },
      "BatchGenerateInvoicesRequest": {
        "type": "object",
        "required": [
          "orderIds"
        ],
        "properties": {
          "orderIds": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Order IDs to generate invoices for",
            "maxItems": 100
          },
          "sendEmail": {
            "type": "boolean",
            "default": false,
            "description": "Email invoices to customers after generation"
          },
          "emailConfig": {
            "type": "object",
            "properties": {
              "ccEmails": {
                "type": "array",
                "items": {
                  "type": "string",
                  "format": "email"
                }
              },
              "groupByCustomer": {
                "type": "boolean",
                "default": true,
                "description": "Group invoices by customer in emails"
              }
            }
          }
        }
      },
      "BatchGenerateInvoicesResponse": {
        "type": "object",
        "properties": {
          "generated": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "orderId": {
                  "type": "string",
                  "format": "uuid"
                },
                "invoiceId": {
                  "type": "string",
                  "format": "uuid"
                },
                "documentId": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            }
          },
          "failed": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "orderId": {
                  "type": "string",
                  "format": "uuid"
                },
                "error": {
                  "type": "string"
                }
              }
            }
          },
          "emailsSent": {
            "type": "integer"
          }
        }
      },
      "SendInvoiceEmailRequest": {
        "type": "object",
        "required": [
          "toEmails"
        ],
        "properties": {
          "toEmails": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "email"
            },
            "minItems": 1
          },
          "ccEmails": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "email"
            }
          },
          "subject": {
            "type": "string",
            "description": "Email subject (defaults to standard invoice subject)"
          },
          "message": {
            "type": "string",
            "description": "Email body message"
          }
        }
      },
      "MarkAwaitingPaymentRequest": {
        "type": "object",
        "properties": {
          "invoiceDate": {
            "type": "string",
            "format": "date",
            "description": "Invoice date (defaults to today)"
          },
          "dueDate": {
            "type": "string",
            "format": "date",
            "description": "Due date (defaults based on payment term)"
          }
        }
      },
      "AgingReportResponse": {
        "type": "object",
        "required": [
          "asOfDate",
          "buckets",
          "customers",
          "totals"
        ],
        "properties": {
          "asOfDate": {
            "type": "string",
            "format": "date"
          },
          "buckets": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Current",
              "1-30",
              "31-60",
              "61-90",
              "90+"
            ]
          },
          "customers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "name": {
                  "type": "string"
                },
                "friendlyId": {
                  "type": "string"
                },
                "current": {
                  "type": "number"
                },
                "days1to30": {
                  "type": "number"
                },
                "days31to60": {
                  "type": "number"
                },
                "days61to90": {
                  "type": "number"
                },
                "over90": {
                  "type": "number"
                },
                "total": {
                  "type": "number"
                }
              }
            }
          },
          "totals": {
            "type": "object",
            "properties": {
              "current": {
                "type": "number"
              },
              "days1to30": {
                "type": "number"
              },
              "days31to60": {
                "type": "number"
              },
              "days61to90": {
                "type": "number"
              },
              "over90": {
                "type": "number"
              },
              "total": {
                "type": "number"
              }
            }
          }
        }
      },
      "ARPaymentMethodType": {
        "$ref": "#/components/schemas/PaymentMethodType-3"
      },
      "PaymentApplication": {
        "type": "object",
        "required": [
          "id",
          "invoiceId",
          "amount"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "invoiceId": {
            "type": "string",
            "format": "uuid"
          },
          "invoiceFriendlyId": {
            "type": [
              "string",
              "null"
            ]
          },
          "invoiceAmount": {
            "type": [
              "number",
              "null"
            ],
            "description": "Total invoice amount"
          },
          "invoiceOpenBalance": {
            "type": [
              "number",
              "null"
            ],
            "description": "Invoice balance before this payment"
          },
          "amount": {
            "type": "number",
            "description": "Amount applied to this invoice"
          }
        }
      },
      "PaymentCreditApplication": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "creditMemoId": {
            "type": "string",
            "format": "uuid"
          },
          "creditMemoReference": {
            "type": [
              "string",
              "null"
            ]
          },
          "amount": {
            "type": "number",
            "description": "Credit amount applied in this payment"
          }
        }
      },
      "Payment": {
        "type": "object",
        "required": [
          "id",
          "paymentDate",
          "totalAmount",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "key": {
            "type": [
              "string",
              "null"
            ],
            "description": "Human-readable payment key",
            "example": "PMT-00001"
          },
          "customer": {
            "$ref": "#/components/schemas/CustomerReference"
          },
          "paymentDate": {
            "type": "string",
            "format": "date",
            "description": "Date payment was received"
          },
          "paymentMethodType": {
            "$ref": "#/components/schemas/PaymentMethodType-3"
          },
          "reference": {
            "type": [
              "string",
              "null"
            ],
            "description": "Check number, transaction ID, etc."
          },
          "notes": {
            "type": [
              "string",
              "null"
            ],
            "description": "Payment notes"
          },
          "currency": {
            "type": [
              "string",
              "null"
            ],
            "description": "Currency code",
            "example": "USD"
          },
          "totalAmount": {
            "type": "number",
            "description": "Total payment amount"
          },
          "applications": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PaymentApplication"
            },
            "description": "Invoices this payment is applied to"
          },
          "creditApplications": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PaymentCreditApplication"
            },
            "description": "Credits applied in this payment"
          },
          "overpaymentAmount": {
            "type": [
              "number",
              "null"
            ],
            "description": "Amount in excess of invoice totals"
          },
          "overpaymentCreditMemoId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Credit memo created from overpayment"
          },
          "shipmentIds": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Related shipment IDs"
          },
          "shipmentKeys": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Related shipment friendly IDs"
          },
          "qboId": {
            "type": [
              "string",
              "null"
            ],
            "description": "QuickBooks Online payment ID"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "PaymentApplicationInput": {
        "type": "object",
        "required": [
          "invoiceId",
          "amount"
        ],
        "properties": {
          "invoiceId": {
            "type": "string",
            "format": "uuid",
            "description": "Invoice to apply payment to"
          },
          "amount": {
            "type": "number",
            "minimum": 0.01,
            "description": "Amount to apply to this invoice"
          }
        }
      },
      "PaymentCreditApplicationInput": {
        "type": "object",
        "required": [
          "creditMemoId",
          "amount"
        ],
        "properties": {
          "creditMemoId": {
            "type": "string",
            "format": "uuid",
            "description": "Credit memo to apply"
          },
          "amount": {
            "type": "number",
            "minimum": 0.01,
            "description": "Credit amount to apply"
          }
        }
      },
      "PaymentInput": {
        "type": "object",
        "required": [
          "customerId",
          "paymentDate",
          "applications"
        ],
        "properties": {
          "customerId": {
            "type": "string",
            "format": "uuid",
            "description": "Customer making the payment"
          },
          "paymentDate": {
            "type": "string",
            "format": "date",
            "description": "Date payment was received"
          },
          "paymentMethodType": {
            "$ref": "#/components/schemas/PaymentMethodType-3"
          },
          "reference": {
            "type": "string",
            "maxLength": 500,
            "description": "Check number, transaction ID, etc."
          },
          "notes": {
            "type": "string",
            "maxLength": 2000,
            "description": "Payment notes"
          },
          "applications": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PaymentApplicationInput"
            },
            "minItems": 1,
            "description": "Invoices to apply payment to"
          },
          "creditApplications": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PaymentCreditApplicationInput"
            },
            "description": "Credits to apply in this payment"
          }
        }
      },
      "PaymentPatch": {
        "type": "object",
        "properties": {
          "paymentDate": {
            "type": "string",
            "format": "date"
          },
          "paymentMethodType": {
            "$ref": "#/components/schemas/PaymentMethodType-3"
          },
          "reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          },
          "applications": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PaymentApplicationInput"
            },
            "description": "Replace all invoice applications"
          },
          "creditApplications": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PaymentCreditApplicationInput"
            },
            "description": "Replace all credit applications"
          }
        }
      },
      "PaymentFilter": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "customerId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "invoiceId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "shipmentId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "paymentDate": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "paymentMethodType": {
            "$ref": "#/components/schemas/PaymentMethodTypeFilter-3"
          },
          "totalAmount": {
            "$ref": "#/components/schemas/FloatFilter"
          },
          "reference": {
            "$ref": "#/components/schemas/StringFilter"
          },
          "createdAt": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "and": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PaymentFilter"
            }
          },
          "or": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PaymentFilter"
            }
          },
          "not": {
            "$ref": "#/components/schemas/PaymentFilter"
          }
        }
      },
      "PaymentFilterRequest": {
        "type": "object",
        "properties": {
          "filter": {
            "$ref": "#/components/schemas/PaymentFilter"
          },
          "pageSize": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          },
          "cursor": {
            "type": "string"
          }
        }
      },
      "OutstandingInvoicesResponse": {
        "type": "object",
        "required": [
          "invoices",
          "totalOutstanding"
        ],
        "properties": {
          "invoices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "friendlyId": {
                  "type": "string"
                },
                "amount": {
                  "type": "number"
                },
                "invoiceDate": {
                  "type": "string",
                  "format": "date"
                },
                "dueDate": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date"
                },
                "openBalance": {
                  "type": "number"
                },
                "isOverdue": {
                  "type": "boolean"
                },
                "payments": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "amount": {
                        "type": "number"
                      },
                      "paymentDate": {
                        "type": "string",
                        "format": "date"
                      }
                    }
                  }
                }
              }
            }
          },
          "totalOutstanding": {
            "type": "number",
            "description": "Total outstanding balance for customer"
          }
        }
      },
      "CreditMemoStatus": {
        "type": "string",
        "enum": [
          "OPEN",
          "PARTIALLY_APPLIED",
          "APPLIED",
          "VOIDED"
        ],
        "description": "Current status of the credit memo (derived from remaining balance).\n- `OPEN`: No applications, full balance available\n- `PARTIALLY_APPLIED`: Some amount applied, balance remains\n- `APPLIED`: Fully applied to invoices\n- `VOIDED`: Credit memo cancelled\n"
      },
      "CreditMemoApplication": {
        "type": "object",
        "required": [
          "id",
          "invoiceId",
          "amount"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "invoiceId": {
            "type": "string",
            "format": "uuid"
          },
          "invoiceFriendlyId": {
            "type": [
              "string",
              "null"
            ]
          },
          "paymentId": {
            "type": "string",
            "format": "uuid",
            "description": "Payment through which this credit was applied"
          },
          "paymentKey": {
            "type": [
              "string",
              "null"
            ]
          },
          "amount": {
            "type": "number",
            "description": "Amount applied"
          },
          "appliedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CreditMemo": {
        "type": "object",
        "required": [
          "id",
          "amount",
          "remainingBalance",
          "status",
          "memoDate",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "key": {
            "type": [
              "string",
              "null"
            ],
            "description": "Client-defined key"
          },
          "reference": {
            "type": [
              "string",
              "null"
            ],
            "description": "Reference number",
            "example": "CM-00001"
          },
          "customer": {
            "$ref": "#/components/schemas/CustomerReference"
          },
          "amount": {
            "type": "number",
            "description": "Original credit amount"
          },
          "appliedAmount": {
            "type": "number",
            "description": "Total amount applied to invoices"
          },
          "remainingBalance": {
            "type": "number",
            "description": "Available balance"
          },
          "currency": {
            "type": [
              "string",
              "null"
            ],
            "description": "Currency code",
            "example": "USD"
          },
          "status": {
            "$ref": "#/components/schemas/CreditMemoStatus"
          },
          "memoDate": {
            "type": "string",
            "format": "date",
            "description": "Credit memo date"
          },
          "notes": {
            "type": [
              "string",
              "null"
            ],
            "description": "Notes or description"
          },
          "sourcePaymentGroupId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Payment that created this credit (if from overpayment)"
          },
          "sourcePaymentKey": {
            "type": [
              "string",
              "null"
            ]
          },
          "applications": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CreditMemoApplication"
            },
            "description": "Invoices this credit is applied to"
          },
          "qboId": {
            "type": [
              "string",
              "null"
            ],
            "description": "QuickBooks Online credit memo ID"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "voidedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "voidReason": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdBy": {
            "$ref": "#/components/schemas/UserReference"
          }
        }
      },
      "CreditMemoInput": {
        "type": "object",
        "required": [
          "customerId",
          "amount",
          "memoDate"
        ],
        "properties": {
          "customerId": {
            "type": "string",
            "format": "uuid",
            "description": "Customer to credit"
          },
          "amount": {
            "type": "number",
            "minimum": 0.01,
            "description": "Credit amount"
          },
          "currency": {
            "type": "string",
            "description": "Currency code (defaults to customer currency)"
          },
          "memoDate": {
            "type": "string",
            "format": "date",
            "description": "Credit memo date"
          },
          "reference": {
            "type": "string",
            "maxLength": 500,
            "description": "Reference number"
          },
          "notes": {
            "type": "string",
            "maxLength": 2000,
            "description": "Notes or description"
          }
        }
      },
      "CreditMemoPatch": {
        "type": "object",
        "properties": {
          "reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          },
          "memoDate": {
            "type": "string",
            "format": "date"
          }
        }
      },
      "CreditMemoFilter": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "customerId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "status": {
            "$ref": "#/components/schemas/CreditMemoStatusFilter"
          },
          "memoDate": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "amount": {
            "$ref": "#/components/schemas/FloatFilter"
          },
          "remainingBalance": {
            "$ref": "#/components/schemas/FloatFilter"
          },
          "hasRemainingBalance": {
            "type": "boolean",
            "description": "Filter to credits with available balance"
          },
          "sourcePaymentGroupId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "createdAt": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "and": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CreditMemoFilter"
            }
          },
          "or": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CreditMemoFilter"
            }
          },
          "not": {
            "$ref": "#/components/schemas/CreditMemoFilter"
          }
        }
      },
      "CreditMemoFilterRequest": {
        "type": "object",
        "properties": {
          "filter": {
            "$ref": "#/components/schemas/CreditMemoFilter"
          },
          "pageSize": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          },
          "cursor": {
            "type": "string"
          }
        }
      },
      "ApplyCreditRequest": {
        "type": "object",
        "required": [
          "invoiceId",
          "amount"
        ],
        "properties": {
          "invoiceId": {
            "type": "string",
            "format": "uuid",
            "description": "Invoice to apply credit to"
          },
          "amount": {
            "type": "number",
            "minimum": 0.01,
            "description": "Amount to apply"
          }
        }
      },
      "ApplyCreditResponse": {
        "type": "object",
        "required": [
          "application",
          "creditMemo"
        ],
        "properties": {
          "application": {
            "$ref": "#/components/schemas/CreditMemoApplication"
          },
          "creditMemo": {
            "$ref": "#/components/schemas/CreditMemo"
          }
        }
      },
      "VoidCreditMemoRequest": {
        "type": "object",
        "properties": {
          "reason": {
            "type": "string",
            "maxLength": 1000,
            "description": "Reason for voiding"
          }
        }
      },
      "AvailableCreditsResponse": {
        "type": "object",
        "required": [
          "availableCredits",
          "totalAvailable"
        ],
        "properties": {
          "availableCredits": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "reference": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "remainingBalance": {
                  "type": "number"
                },
                "currency": {
                  "type": "string"
                },
                "memoDate": {
                  "type": "string",
                  "format": "date"
                },
                "notes": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            }
          },
          "totalAvailable": {
            "type": "number",
            "description": "Total available credit balance"
          }
        }
      },
      "BillStatus": {
        "type": "string",
        "enum": [
          "AWAITING_INVOICE",
          "IN_REVIEW",
          "APPROVED_TO_PAY",
          "PAID"
        ],
        "description": "Current status of the bill (AP invoice).\n- `AWAITING_INVOICE`: Waiting for carrier/vendor to submit invoice\n- `IN_REVIEW`: Invoice received, under review\n- `APPROVED_TO_PAY`: Approved and ready for payment\n- `PAID`: Fully paid\n"
      },
      "BillEntityType": {
        "type": "string",
        "enum": [
          "CARRIER",
          "VENDOR"
        ],
        "description": "Type of entity the bill is for.\n- `CARRIER`: Bill for a carrier (LoadCarrier)\n- `VENDOR`: Bill for a vendor service (VendedService)\n"
      },
      "BillPaymentApplied": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "paymentGroupId": {
            "type": "string",
            "format": "uuid"
          },
          "amount": {
            "type": "number",
            "description": "Amount applied to this bill"
          },
          "paymentDate": {
            "type": "string",
            "format": "date"
          },
          "reference": {
            "type": [
              "string",
              "null"
            ],
            "description": "Check number, transaction ID, etc."
          }
        }
      },
      "Bill": {
        "type": "object",
        "required": [
          "id",
          "friendlyId",
          "status",
          "entityType",
          "amount",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "friendlyId": {
            "type": "string",
            "description": "Human-readable bill ID",
            "example": "BILL-00001"
          },
          "key": {
            "type": [
              "string",
              "null"
            ],
            "description": "Client-defined key"
          },
          "entityType": {
            "$ref": "#/components/schemas/BillEntityType"
          },
          "loadCarrierId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Associated load carrier ID (if carrier bill)"
          },
          "vendedServiceId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Associated vended service ID (if vendor bill)"
          },
          "carrier": {
            "$ref": "#/components/schemas/CarrierReference"
          },
          "vendor": {
            "$ref": "#/components/schemas/VendorReference"
          },
          "loadId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "loadKey": {
            "type": [
              "string",
              "null"
            ]
          },
          "shipmentId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "shipmentKey": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "$ref": "#/components/schemas/BillStatus"
          },
          "invoiceDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Date of carrier/vendor invoice"
          },
          "dueDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Payment due date"
          },
          "amount": {
            "type": "number",
            "description": "Bill amount"
          },
          "currency": {
            "type": [
              "string",
              "null"
            ],
            "description": "Currency code",
            "example": "USD"
          },
          "reference": {
            "type": [
              "string",
              "null"
            ],
            "description": "Carrier/vendor invoice reference number"
          },
          "amountPaid": {
            "type": "number",
            "description": "Total payments received"
          },
          "amountOwed": {
            "type": "number",
            "description": "Outstanding balance"
          },
          "payments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BillPaymentApplied"
            },
            "description": "Payments applied to this bill"
          },
          "paymentTerm": {
            "$ref": "#/components/schemas/PaymentTermReference"
          },
          "carrierFactor": {
            "$ref": "#/components/schemas/CarrierFactorReference"
          },
          "factorJobId": {
            "type": [
              "string",
              "null"
            ],
            "description": "External factoring job ID"
          },
          "factorStatus": {
            "type": [
              "string",
              "null"
            ],
            "description": "Current factoring status"
          },
          "qboId": {
            "type": [
              "string",
              "null"
            ],
            "description": "QuickBooks Online bill ID"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "BillInput": {
        "type": "object",
        "required": [
          "entityType",
          "entityId",
          "invoiceDate",
          "amount"
        ],
        "properties": {
          "entityType": {
            "$ref": "#/components/schemas/BillEntityType"
          },
          "entityId": {
            "type": "string",
            "format": "uuid",
            "description": "LoadCarrier ID or VendedService ID"
          },
          "invoiceDate": {
            "type": "string",
            "format": "date",
            "description": "Invoice date from carrier/vendor"
          },
          "dueDate": {
            "type": "string",
            "format": "date",
            "description": "Payment due date"
          },
          "amount": {
            "type": "number",
            "description": "Invoice amount"
          },
          "reference": {
            "type": "string",
            "maxLength": 500,
            "description": "Carrier/vendor invoice reference number"
          },
          "currency": {
            "type": "string",
            "description": "Currency code (defaults to carrier/vendor currency)"
          },
          "paymentTermId": {
            "type": "string",
            "format": "uuid",
            "description": "Payment term"
          }
        }
      },
      "BillPatch": {
        "type": "object",
        "properties": {
          "invoiceDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "dueDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "amount": {
            "type": "number"
          },
          "reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "paymentTermId": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "BillFilter": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "loadCarrierId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "vendedServiceId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "carrierId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "vendorId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "loadId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "shipmentId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "status": {
            "$ref": "#/components/schemas/BillStatusFilter"
          },
          "entityType": {
            "$ref": "#/components/schemas/BillEntityTypeFilter"
          },
          "invoiceDate": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "dueDate": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "amount": {
            "$ref": "#/components/schemas/FloatFilter"
          },
          "overdue": {
            "type": "boolean",
            "description": "Filter to overdue bills only"
          },
          "createdAt": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "and": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BillFilter"
            }
          },
          "or": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BillFilter"
            }
          },
          "not": {
            "$ref": "#/components/schemas/BillFilter"
          }
        }
      },
      "BillFilterRequest": {
        "type": "object",
        "properties": {
          "filter": {
            "$ref": "#/components/schemas/BillFilter"
          },
          "pageSize": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          },
          "cursor": {
            "type": "string"
          }
        }
      },
      "ApproveBillsRequest": {
        "type": "object",
        "required": [
          "billIds"
        ],
        "properties": {
          "billIds": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "minItems": 1,
            "maxItems": 100,
            "description": "Bill IDs to approve"
          }
        }
      },
      "ApproveBillsResponse": {
        "type": "object",
        "properties": {
          "approved": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "billId": {
                  "type": "string",
                  "format": "uuid"
                },
                "status": {
                  "$ref": "#/components/schemas/BillStatus"
                }
              }
            }
          },
          "failed": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "billId": {
                  "type": "string",
                  "format": "uuid"
                },
                "error": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "RevertBillRequest": {
        "type": "object",
        "properties": {
          "reason": {
            "type": "string",
            "maxLength": 1000,
            "description": "Reason for reverting"
          }
        }
      },
      "OutstandingBillsResponse": {
        "type": "object",
        "required": [
          "bills",
          "totalOutstanding"
        ],
        "properties": {
          "bills": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "friendlyId": {
                  "type": "string"
                },
                "entityType": {
                  "$ref": "#/components/schemas/BillEntityType"
                },
                "carrier": {
                  "$ref": "#/components/schemas/CarrierReference"
                },
                "vendor": {
                  "$ref": "#/components/schemas/VendorReference"
                },
                "amount": {
                  "type": "number"
                },
                "invoiceDate": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date"
                },
                "dueDate": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date"
                },
                "openBalance": {
                  "type": "number"
                },
                "isOverdue": {
                  "type": "boolean"
                }
              }
            }
          },
          "totalOutstanding": {
            "type": "number",
            "description": "Total outstanding balance"
          }
        }
      },
      "ApAgingReportResponse": {
        "type": "object",
        "required": [
          "asOfDate",
          "buckets",
          "payees",
          "totals"
        ],
        "properties": {
          "asOfDate": {
            "type": "string",
            "format": "date"
          },
          "buckets": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Current",
              "1-30",
              "31-60",
              "61-90",
              "90+"
            ]
          },
          "payees": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "name": {
                  "type": "string"
                },
                "friendlyId": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "entityType": {
                  "$ref": "#/components/schemas/BillEntityType"
                },
                "current": {
                  "type": "number"
                },
                "days1to30": {
                  "type": "number"
                },
                "days31to60": {
                  "type": "number"
                },
                "days61to90": {
                  "type": "number"
                },
                "over90": {
                  "type": "number"
                },
                "total": {
                  "type": "number"
                }
              }
            }
          },
          "totals": {
            "type": "object",
            "properties": {
              "current": {
                "type": "number"
              },
              "days1to30": {
                "type": "number"
              },
              "days31to60": {
                "type": "number"
              },
              "days61to90": {
                "type": "number"
              },
              "over90": {
                "type": "number"
              },
              "total": {
                "type": "number"
              }
            }
          }
        }
      },
      "BillPaymentMethodType": {
        "type": "string",
        "enum": [
          "ACH_WIRE",
          "CHECK",
          "CREDIT_CARD",
          "EFT_DIRECT_DEPOSIT",
          "E_TRANSFER",
          "VENMO",
          "ZELLE"
        ],
        "description": "Payment method used for the bill payment.\n- `ACH_WIRE`: ACH wire transfer\n- `CHECK`: Paper check\n- `CREDIT_CARD`: Credit card payment\n- `EFT_DIRECT_DEPOSIT`: EFT direct deposit\n- `E_TRANSFER`: Electronic transfer\n- `VENMO`: Venmo payment\n- `ZELLE`: Zelle payment\n"
      },
      "BillPaymentRecipientType": {
        "type": "string",
        "enum": [
          "CARRIER",
          "VENDOR"
        ],
        "description": "Type of recipient for the payment.\n- `CARRIER`: Payment to a carrier\n- `VENDOR`: Payment to a vendor\n"
      },
      "BillPaymentApplication": {
        "type": "object",
        "required": [
          "id",
          "billId",
          "amount"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "billId": {
            "type": "string",
            "format": "uuid",
            "description": "Bill (invoice) this payment applies to"
          },
          "billFriendlyId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Human-readable bill ID"
          },
          "amount": {
            "type": "number",
            "description": "Amount applied to this bill"
          },
          "loadCarrierId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Associated load carrier (for carrier bills)"
          },
          "vendedServiceId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Associated vended service (for vendor bills)"
          },
          "shipmentId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "shipmentFriendlyId": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "BillPayment": {
        "type": "object",
        "required": [
          "id",
          "paymentDate",
          "recipientType",
          "totalAmount",
          "applications",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "key": {
            "type": [
              "string",
              "null"
            ],
            "description": "Client-defined key"
          },
          "recipientType": {
            "$ref": "#/components/schemas/BillPaymentRecipientType"
          },
          "carrier": {
            "$ref": "#/components/schemas/CarrierReference"
          },
          "vendor": {
            "$ref": "#/components/schemas/VendorReference"
          },
          "carrierFactor": {
            "$ref": "#/components/schemas/CarrierFactorReference-2"
          },
          "paymentDate": {
            "type": "string",
            "format": "date",
            "description": "Date the payment was made"
          },
          "paymentMethodType": {
            "$ref": "#/components/schemas/BillPaymentMethodType"
          },
          "reference": {
            "type": [
              "string",
              "null"
            ],
            "description": "Check number, transaction ID, etc."
          },
          "notes": {
            "type": [
              "string",
              "null"
            ],
            "description": "Additional notes"
          },
          "totalAmount": {
            "type": "number",
            "description": "Total payment amount (sum of all applications)"
          },
          "overpayment": {
            "type": [
              "number",
              "null"
            ],
            "description": "Amount paid in excess of invoice totals"
          },
          "overpaymentCreditMemoId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Credit memo created for overpayment"
          },
          "applications": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BillPaymentApplication"
            },
            "description": "Individual bill payments in this group"
          },
          "qboId": {
            "type": [
              "string",
              "null"
            ],
            "description": "QuickBooks Online bill payment ID"
          },
          "syncStatus": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "pending",
              "synced",
              "error"
            ],
            "description": "QuickBooks sync status"
          },
          "syncError": {
            "type": [
              "string",
              "null"
            ],
            "description": "QuickBooks sync error message"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "BillPaymentApplicationInput": {
        "type": "object",
        "required": [
          "billId",
          "amount"
        ],
        "properties": {
          "billId": {
            "type": "string",
            "format": "uuid",
            "description": "Bill (invoice) to apply payment to"
          },
          "amount": {
            "type": "number",
            "minimum": 0.01,
            "description": "Amount to apply to this bill"
          }
        }
      },
      "BillPaymentInput": {
        "type": "object",
        "required": [
          "paymentDate",
          "applications"
        ],
        "properties": {
          "paymentDate": {
            "type": "string",
            "format": "date",
            "description": "Date of payment"
          },
          "paymentMethodType": {
            "$ref": "#/components/schemas/BillPaymentMethodType"
          },
          "carrierFactorId": {
            "type": "string",
            "format": "uuid",
            "description": "Carrier factor to pay (for factored payments)"
          },
          "reference": {
            "type": "string",
            "maxLength": 500,
            "description": "Check number, transaction ID, etc."
          },
          "notes": {
            "type": "string",
            "maxLength": 2000,
            "description": "Additional notes"
          },
          "applications": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BillPaymentApplicationInput"
            },
            "minItems": 1,
            "description": "Bills to pay"
          },
          "allowOverpayment": {
            "type": "boolean",
            "default": false,
            "description": "Allow payment amount to exceed bill totals"
          }
        }
      },
      "BillPaymentPatch": {
        "type": "object",
        "properties": {
          "paymentDate": {
            "type": "string",
            "format": "date"
          },
          "paymentMethodType": {
            "$ref": "#/components/schemas/BillPaymentMethodType"
          },
          "reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "notes": {
            "type": [
              "string",
              "null"
            ]
          },
          "applications": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BillPaymentApplicationPatch"
            },
            "description": "Update payment applications"
          }
        }
      },
      "BillPaymentFilter": {
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "carrierId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "vendorId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "carrierFactorId": {
            "$ref": "#/components/schemas/UUIDFilter"
          },
          "recipientType": {
            "type": "object",
            "properties": {
              "equalTo": {
                "$ref": "#/components/schemas/BillPaymentRecipientType"
              },
              "in": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/BillPaymentRecipientType"
                }
              }
            }
          },
          "paymentMethodType": {
            "$ref": "#/components/schemas/BillPaymentMethodTypeFilter"
          },
          "paymentDate": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "totalAmount": {
            "$ref": "#/components/schemas/FloatFilter"
          },
          "reference": {
            "$ref": "#/components/schemas/StringFilter"
          },
          "createdAt": {
            "$ref": "#/components/schemas/DatetimeFilter"
          },
          "and": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BillPaymentFilter"
            }
          },
          "or": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BillPaymentFilter"
            }
          },
          "not": {
            "$ref": "#/components/schemas/BillPaymentFilter"
          }
        }
      },
      "BillPaymentFilterRequest": {
        "type": "object",
        "properties": {
          "filter": {
            "$ref": "#/components/schemas/BillPaymentFilter"
          },
          "pageSize": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          },
          "cursor": {
            "type": "string"
          }
        }
      },
      "OutstandingBill": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "friendlyId": {
            "type": "string"
          },
          "entityType": {
            "$ref": "#/components/schemas/BillEntityType"
          },
          "carrier": {
            "$ref": "#/components/schemas/CarrierReference"
          },
          "vendor": {
            "$ref": "#/components/schemas/VendorReference"
          },
          "invoiceDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "dueDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "amount": {
            "type": "number"
          },
          "amountPaid": {
            "type": "number"
          },
          "openBalance": {
            "type": "number"
          },
          "isOverdue": {
            "type": "boolean"
          },
          "shipmentId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "shipmentFriendlyId": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "OutstandingBillsForPaymentResponse": {
        "type": "object",
        "required": [
          "bills",
          "totalOutstanding"
        ],
        "properties": {
          "bills": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OutstandingBill"
            }
          },
          "totalOutstanding": {
            "type": "number",
            "description": "Total outstanding balance"
          },
          "carrier": {
            "$ref": "#/components/schemas/CarrierReference"
          },
          "vendor": {
            "$ref": "#/components/schemas/VendorReference"
          },
          "carrierFactor": {
            "$ref": "#/components/schemas/CarrierFactorReference-2"
          }
        }
      },
      "SavedSearchLookup": {
        "type": "object",
        "description": "Reference to a saved search by ID or client key.\nProvide either id or key (not both).\n",
        "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.\nOnly present for UPDATE events. Null for CREATE and DELETE events.\nEach change follows the IChange interface from json-diff-ts library.\n",
            "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.\nIdentical to CarrierPaymentMethod but excludes the carrier and carrierId fields to avoid circular references.\n",
        "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.\nIdentical to CarrierContact but excludes the carrier and carrierId fields to avoid circular references.\n",
        "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
          }
        }
      },
      "AgentCarrier": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CarrierBase"
          },
          {
            "type": "object",
            "description": "Agent (interline/partner agent) carrier",
            "required": [
              "type"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "AGENT"
                ],
                "description": "Carrier type discriminator",
                "example": "AGENT"
              }
            }
          }
        ]
      },
      "AgentCarrierInput": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CarrierInputBase"
          },
          {
            "type": "object",
            "description": "Input for creating an agent carrier",
            "required": [
              "type"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "AGENT"
                ],
                "description": "Carrier type discriminator (must be AGENT)",
                "example": "AGENT"
              }
            }
          }
        ]
      },
      "AgentCarrierPatch": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CarrierPatchBase"
          },
          {
            "type": "object",
            "description": "Partial update for agent carrier",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "AGENT"
                ],
                "description": "Carrier type discriminator (optional - only needed if changing type)",
                "example": "AGENT"
              }
            }
          }
        ]
      },
      "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:\n- `EQUALS`: Exact match\n- `NOT_EQUALS`: Not equal to\n- `ONE_OF`: Matches any UUID in array\n- `NOT_ONE_OF`: Does not match any UUID in array\n- `EXISTS`: Field has a value (not null)\n- `DOES_NOT_EXIST`: Field is null\n"
          },
          "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:\n- `EQUALS`: Exact match\n- `NOT_EQUALS`: Not equal to\n- `ONE_OF`: Matches any value in array\n- `NOT_ONE_OF`: Does not match any value in array\n- `EXISTS`: Field has a value (not null)\n- `DOES_NOT_EXIST`: Field is null\n"
          },
          "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:\n- `EQUALS`: Exact match\n- `NOT_EQUALS`: Not equal to\n- `STARTS_WITH`: Begins with prefix\n- `ENDS_WITH`: Ends with suffix\n- `INCLUDES`: Contains substring\n- `ONE_OF`: Matches any value in array\n- `NOT_ONE_OF`: Does not match any value in array\n- `EXISTS`: Field has a value (not null)\n- `DOES_NOT_EXIST`: Field is null\n"
          },
          "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:\n- `EQUALS`: Exact match\n- `NOT_EQUALS`: Not equal to\n- `GREATER_THAN`: Greater than value\n- `LESS_THAN`: Less than value\n- `BETWEEN`: Between min and max (inclusive)\n- `NOT_BETWEEN`: Not between min and max\n- `EXISTS`: Field has a value (not null)\n- `DOES_NOT_EXIST`: Field is null\n"
          },
          "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:\n- `EQUALS`: Exact match\n- `NOT_EQUALS`: Not equal to\n- `GREATER_THAN`: Greater than value\n- `LESS_THAN`: Less than value\n- `BETWEEN`: Between min and max (inclusive)\n- `NOT_BETWEEN`: Not between min and max\n- `EXISTS`: Field has a value (not null)\n- `DOES_NOT_EXIST`: Field is null\n"
          },
          "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:\n- `YEAR`: Years\n- `MONTH`: Months\n- `WEEK`: Weeks\n- `DAY`: Days\n- `HOUR`: Hours\n- `MINUTE`: Minutes\n- `SECOND`: Seconds\n"
      },
      "DatetimeSearchCriteria": {
        "type": "object",
        "required": [
          "operator"
        ],
        "description": "Search criteria for datetime fields.\nSupports both absolute datetime values and relative time expressions.\n",
        "properties": {
          "operator": {
            "type": "string",
            "enum": [
              "EQUALS",
              "NOT_EQUALS",
              "BEFORE",
              "AFTER",
              "BETWEEN",
              "NOT_BETWEEN",
              "EXISTS",
              "DOES_NOT_EXIST"
            ],
            "description": "Search operator:\n- `EQUALS`: Exact match\n- `NOT_EQUALS`: Not equal to\n- `BEFORE`: Before datetime\n- `AFTER`: After datetime\n- `BETWEEN`: Between min and max (inclusive)\n- `NOT_BETWEEN`: Not between min and max\n- `EXISTS`: Field has a value (not null)\n- `DOES_NOT_EXIST`: Field is null\n"
          },
          "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).\nExample: -7 with WEEK unit means 7 weeks ago.\n"
          },
          "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
        }
      },
      "ShowNotes": {
        "type": "string",
        "enum": [
          "ALL",
          "SPLIT"
        ],
        "description": "Controls whether external notes are shown on all documents or split from carrier-facing notes.\n- `ALL`: Use external notes on customer-facing and carrier-facing documents\n- `SPLIT`: Use external notes on customer-facing documents and carrier notes on carrier-facing documents\n"
      },
      "CustomerContactReference": {
        "type": "object",
        "description": "Customer contact reference for embedding in Customer responses.\nIdentical to CustomerContact but excludes the customer and customerId fields to avoid circular references.\n",
        "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).\nSupports both absolute date values and relative time expressions.\n",
        "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"
        }
      },
      "LocationAddressInput": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AddressInput"
          },
          {
            "type": "object",
            "required": [
              "state",
              "zipCode"
            ]
          }
        ],
        "description": "Address for a customer location. Same shape as AddressInput, but `state`\nand `zipCode` are required (location addresses always carry them).\n"
      },
      "BooleanSearchCriteria": {
        "type": "object",
        "required": [
          "operator"
        ],
        "description": "Search criteria for boolean fields",
        "properties": {
          "operator": {
            "type": "string",
            "enum": [
              "TRUE",
              "FALSE"
            ],
            "description": "Search operator:\n- `TRUE`: Field is true\n- `FALSE`: Field is false\n"
          }
        },
        "example": {
          "operator": "TRUE"
        }
      },
      "EquipmentCategory": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Category id (use as the `categoryId` list filter)"
          },
          "name": {
            "type": "string",
            "description": "Category display name",
            "example": "Van"
          }
        }
      },
      "EquipmentGroup": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Group id (use as the `groupId` list filter)"
          },
          "name": {
            "type": "string",
            "description": "Top-level group display name",
            "example": "Trailer"
          }
        }
      },
      "EquipmentSubcategory": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Subcategory id (use as the `subcategoryId` list filter)"
          },
          "name": {
            "type": "string",
            "description": "Subcategory display name"
          }
        }
      },
      "Equipment": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Equipment id (referenced by order/load equipment arrays)"
          },
          "name": {
            "type": "string",
            "description": "Display name (e.g., \"Van 53'\")",
            "example": "Van 53'"
          },
          "category": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/EquipmentCategory"
              },
              {
                "type": "null"
              }
            ],
            "description": "Equipment category"
          },
          "group": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/EquipmentGroup"
              },
              {
                "type": "null"
              }
            ],
            "description": "Top-level equipment group"
          },
          "subcategory": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/EquipmentSubcategory"
              },
              {
                "type": "null"
              }
            ],
            "description": "Equipment subcategory"
          }
        }
      },
      "ChargeCode": {
        "type": "object",
        "required": [
          "id",
          "code",
          "name",
          "description"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "description": "Charge code id (referenced by charge `chargeCodeId` fields)",
            "example": 1
          },
          "code": {
            "type": "string",
            "description": "Short accounting code",
            "example": "LH"
          },
          "name": {
            "type": "string",
            "description": "Display name",
            "example": "Linehaul"
          },
          "description": {
            "type": "string",
            "description": "Full description",
            "example": "Linehaul charges"
          }
        }
      },
      "SpecialRequirementType": {
        "type": "string",
        "enum": [
          "EQUIPMENT",
          "DRIVER",
          "FREIGHT",
          "SHIPPER_LOCATION"
        ],
        "description": "What the requirement applies to.\n- `EQUIPMENT`: Equipment accessories (e.g., tarps, straps)\n- `DRIVER`: Driver services (e.g., team service, TWIC)\n- `FREIGHT`: Freight handling characteristics\n- `SHIPPER_LOCATION`: Location constraints\n"
      },
      "SpecialRequirement": {
        "type": "object",
        "required": [
          "id",
          "name",
          "type"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Special-requirement id (referenced by order/load specialRequirements arrays)"
          },
          "name": {
            "type": "string",
            "description": "Display name (e.g., \"Tarps\")",
            "example": "Tarps"
          },
          "type": {
            "$ref": "#/components/schemas/SpecialRequirementType"
          }
        }
      },
      "UserReference-2": {
        "type": "object",
        "description": "User reference for embedding in Team responses.\nIdentical to User but excludes the teams array to avoid circular references.\n",
        "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.\nIdentical to Team but excludes the users array to avoid circular references.\n",
        "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
          }
        }
      },
      "Currency-2": {
        "type": "string",
        "description": "Currency code",
        "enum": [
          "ARS",
          "AUD",
          "BRL",
          "CAD",
          "CNY",
          "EUR",
          "GBP",
          "IDR",
          "INR",
          "JPY",
          "KRW",
          "MXN",
          "RUB",
          "SAR",
          "TRY",
          "USD",
          "ZAR"
        ]
      },
      "CurrencyFilter": {
        "type": "object",
        "description": "Filter for currency enum field",
        "properties": {
          "equalTo": {
            "$ref": "#/components/schemas/Currency-2",
            "description": "Exact match"
          },
          "notEqualTo": {
            "$ref": "#/components/schemas/Currency-2",
            "description": "Not equal to"
          },
          "in": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Currency-2"
            },
            "description": "Matches any value in the list"
          },
          "notIn": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Currency-2"
            },
            "description": "Does not match any value in the list"
          },
          "isNull": {
            "type": "boolean",
            "description": "Field is null (true) or not null (false)"
          }
        }
      },
      "PaymentMethodType-2": {
        "type": "string",
        "description": "Payment method type",
        "enum": [
          "ACH_WIRE",
          "ZELLE",
          "VENMO",
          "ACH",
          "CHECK",
          "WIRE",
          "CAD_EFT",
          "TRIUMPH_PAY",
          "COMCHECK",
          "EFS",
          "ECHECK"
        ],
        "example": "ACH"
      },
      "VendorPaymentMethodReference": {
        "type": "object",
        "description": "Vendor payment method reference for embedding in Vendor responses.\nIdentical to VendorPaymentMethod but excludes the vendor and vendorId fields to avoid circular references.\n",
        "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-2",
            "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.\nIdentical to VendorContact but excludes the vendor and vendorId fields to avoid circular references.\n",
        "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
          }
        }
      },
      "PaymentMethodTypeFilter-2": {
        "type": "object",
        "description": "Filter for payment method type",
        "properties": {
          "equalTo": {
            "$ref": "#/components/schemas/PaymentMethodType-2"
          },
          "notEqualTo": {
            "$ref": "#/components/schemas/PaymentMethodType-2"
          },
          "in": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PaymentMethodType-2"
            }
          },
          "notIn": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PaymentMethodType-2"
            }
          }
        }
      },
      "ShipmentStatus": {
        "type": "string",
        "enum": [
          "DRAFT",
          "TENDER_PENDING",
          "ON_HOLD",
          "PLANNING",
          "SELECTED",
          "BOOKED",
          "DISPATCHED",
          "LOADING",
          "PICKED_UP",
          "IN_TRANSIT",
          "UNLOADING",
          "ARRIVED_AT_DELIVERY_TERMINAL",
          "OUT_FOR_DELIVERY",
          "RECOVERED",
          "DELIVERED",
          "CANCELED",
          "TENDER_REJECTED",
          "CONSOLIDATED"
        ],
        "description": "Current status of the shipment.\n\nLifecycle stages:\n- `DRAFT`: Shipment is being created, not yet ready for processing\n- `TENDER_PENDING`: Awaiting carrier tender acceptance\n- `TENDER_REJECTED`: Carrier rejected the tender\n- `ON_HOLD`: Shipment is temporarily paused\n- `PLANNING`: Shipment is being planned/scheduled\n- `SELECTED`: Carrier has been selected\n- `BOOKED`: Carrier has confirmed the booking\n- `DISPATCHED`: Shipment has been dispatched to carrier\n\nIn-transit stages:\n- `LOADING`: Freight is being loaded at pickup\n- `PICKED_UP`: Freight has been picked up\n- `IN_TRANSIT`: Shipment is in transit\n- `UNLOADING`: Freight is being unloaded at delivery\n- `ARRIVED_AT_DELIVERY_TERMINAL`: Arrived at delivery terminal (LTL)\n- `OUT_FOR_DELIVERY`: Out for final delivery\n- `RECOVERED`: Shipment has been recovered\n\nFinal stages:\n- `DELIVERED`: Shipment has been delivered\n- `CANCELED`: Shipment has been canceled\n- `CONSOLIDATED`: Merged into a consolidated shipment\n"
      },
      "DocumentEntityType": {
        "type": "string",
        "enum": [
          "ORDER",
          "LOAD",
          "SHIPMENT",
          "CARRIER",
          "CUSTOMER",
          "VENDOR"
        ],
        "description": "Entity kind for entity-scoped document filtering.\n- `ORDER`: Customer-side documents attached to an order\n- `LOAD`: Carrier-side documents attached to a load's carrier assignments\n- `SHIPMENT`: Everything on the shipment — order and load documents combined\n- `CARRIER`: Documents on a carrier profile\n- `CUSTOMER`: Documents on a customer\n- `VENDOR`: Documents on a vendor\n"
      },
      "DocumentTypeFilter": {
        "type": "object",
        "properties": {
          "equalTo": {
            "$ref": "#/components/schemas/DocumentType"
          },
          "notEqualTo": {
            "$ref": "#/components/schemas/DocumentType"
          },
          "in": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DocumentType"
            }
          },
          "notIn": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DocumentType"
            }
          }
        },
        "description": "Filter for document type field"
      },
      "DocumentStatusFilter": {
        "type": "object",
        "properties": {
          "equalTo": {
            "$ref": "#/components/schemas/DocumentStatus"
          },
          "notEqualTo": {
            "$ref": "#/components/schemas/DocumentStatus"
          },
          "in": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DocumentStatus"
            }
          },
          "notIn": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DocumentStatus"
            }
          }
        },
        "description": "Filter for document status field"
      },
      "QuoteStatusFilter": {
        "type": "object",
        "properties": {
          "equalTo": {
            "$ref": "#/components/schemas/QuoteStatus"
          },
          "notEqualTo": {
            "$ref": "#/components/schemas/QuoteStatus"
          },
          "in": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QuoteStatus"
            }
          },
          "notIn": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QuoteStatus"
            }
          }
        }
      },
      "QuoteSideFilter": {
        "type": "object",
        "properties": {
          "equalTo": {
            "$ref": "#/components/schemas/QuoteSide"
          },
          "notEqualTo": {
            "$ref": "#/components/schemas/QuoteSide"
          },
          "in": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QuoteSide"
            }
          }
        }
      },
      "OrderSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "key": {
            "type": [
              "string",
              "null"
            ]
          },
          "mode": {
            "$ref": "#/components/schemas/TransportMode"
          },
          "origin": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string"
              },
              "stateProvince": {
                "type": "string"
              },
              "postalCode": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "destination": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string"
              },
              "stateProvince": {
                "type": "string"
              },
              "postalCode": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "pickUpDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "deliveryDate": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "equipment": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "weight": {
            "type": [
              "number",
              "null"
            ]
          },
          "mileage": {
            "type": [
              "number",
              "null"
            ]
          }
        },
        "description": "Summary of order details (embedded in Quote response)"
      },
      "ShipmentSearchCriteria": {
        "type": "object",
        "description": "Search criteria for filtering shipments.\nNote: Only active (non-deleted) shipments are searchable.\n",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/UUIDSearchCriteria"
          },
          "friendlyId": {
            "$ref": "#/components/schemas/KeywordSearchCriteria"
          },
          "status": {
            "$ref": "#/components/schemas/KeywordSearchCriteria",
            "description": "Shipment status (PENDING, BOOKED, IN_TRANSIT, DELIVERED, CANCELED, etc.)"
          },
          "orderStatus": {
            "$ref": "#/components/schemas/KeywordSearchCriteria",
            "description": "AR (accounts receivable) status"
          },
          "loadStatuses": {
            "$ref": "#/components/schemas/KeywordSearchCriteria",
            "description": "AP (accounts payable) statuses for carriers/vendors"
          },
          "mode": {
            "$ref": "#/components/schemas/KeywordSearchCriteria",
            "description": "Transportation mode (TL, LTL, AIR, OCEAN, RAIL)"
          },
          "tonu": {
            "$ref": "#/components/schemas/BooleanSearchCriteria",
            "description": "Truck Order Not Used flag"
          },
          "pickUp": {
            "$ref": "#/components/schemas/TextSearchCriteria",
            "description": "Origin city and state"
          },
          "pickUpCity": {
            "$ref": "#/components/schemas/TextSearchCriteria"
          },
          "pickUpState": {
            "$ref": "#/components/schemas/KeywordSearchCriteria"
          },
          "pickUpZipCode": {
            "$ref": "#/components/schemas/KeywordSearchCriteria"
          },
          "pickUpCountry": {
            "$ref": "#/components/schemas/KeywordSearchCriteria"
          },
          "dropOff": {
            "$ref": "#/components/schemas/TextSearchCriteria",
            "description": "Destination city and state"
          },
          "dropOffCity": {
            "$ref": "#/components/schemas/TextSearchCriteria"
          },
          "dropOffState": {
            "$ref": "#/components/schemas/KeywordSearchCriteria"
          },
          "dropOffZipCode": {
            "$ref": "#/components/schemas/KeywordSearchCriteria"
          },
          "dropOffCountry": {
            "$ref": "#/components/schemas/KeywordSearchCriteria"
          },
          "pickUpStartDatetime": {
            "$ref": "#/components/schemas/DatetimeSearchCriteria",
            "description": "Scheduled pickup datetime"
          },
          "dropOffStartDatetime": {
            "$ref": "#/components/schemas/DatetimeSearchCriteria",
            "description": "Scheduled delivery datetime"
          },
          "bookedAt": {
            "$ref": "#/components/schemas/DatetimeSearchCriteria",
            "description": "When carrier was booked"
          },
          "shipperId": {
            "$ref": "#/components/schemas/UUIDSearchCriteria",
            "description": "Customer ID"
          },
          "shipperName": {
            "$ref": "#/components/schemas/TextSearchCriteria",
            "description": "Customer name"
          },
          "carrierIds": {
            "$ref": "#/components/schemas/UUIDSearchCriteria",
            "description": "Carrier IDs"
          },
          "carrierNames": {
            "$ref": "#/components/schemas/TextSearchCriteria",
            "description": "Carrier names"
          },
          "primaryRepId": {
            "$ref": "#/components/schemas/UUIDSearchCriteria"
          },
          "primaryRepName": {
            "$ref": "#/components/schemas/TextSearchCriteria"
          },
          "bookingRepIds": {
            "$ref": "#/components/schemas/UUIDSearchCriteria"
          },
          "bookingRepNames": {
            "$ref": "#/components/schemas/TextSearchCriteria"
          },
          "groupId": {
            "$ref": "#/components/schemas/UUIDSearchCriteria",
            "description": "Team ID"
          },
          "groupName": {
            "$ref": "#/components/schemas/TextSearchCriteria",
            "description": "Team name"
          },
          "equipmentType": {
            "$ref": "#/components/schemas/KeywordSearchCriteria"
          },
          "weight": {
            "$ref": "#/components/schemas/FloatSearchCriteria"
          },
          "totalMiles": {
            "$ref": "#/components/schemas/FloatSearchCriteria"
          },
          "revenue": {
            "$ref": "#/components/schemas/FloatSearchCriteria"
          },
          "cost": {
            "$ref": "#/components/schemas/FloatSearchCriteria"
          },
          "profit": {
            "$ref": "#/components/schemas/FloatSearchCriteria",
            "description": "Gross profit"
          },
          "profitMargin": {
            "$ref": "#/components/schemas/FloatSearchCriteria"
          },
          "referenceValues": {
            "$ref": "#/components/schemas/TextSearchCriteria",
            "description": "Reference values (PO, BOL, customer ref, etc.)"
          },
          "customerRef": {
            "$ref": "#/components/schemas/KeywordSearchCriteria"
          },
          "bol": {
            "$ref": "#/components/schemas/KeywordSearchCriteria"
          },
          "po": {
            "$ref": "#/components/schemas/KeywordSearchCriteria"
          },
          "quoteId": {
            "$ref": "#/components/schemas/UUIDSearchCriteria"
          },
          "quoteFriendlyId": {
            "$ref": "#/components/schemas/KeywordSearchCriteria"
          },
          "arInvoiceId": {
            "$ref": "#/components/schemas/UUIDSearchCriteria"
          },
          "arInvoiceFriendlyId": {
            "$ref": "#/components/schemas/KeywordSearchCriteria"
          },
          "apInvoiceIds": {
            "$ref": "#/components/schemas/UUIDSearchCriteria"
          },
          "apInvoiceFriendlyIds": {
            "$ref": "#/components/schemas/KeywordSearchCriteria"
          },
          "createdAt": {
            "$ref": "#/components/schemas/DatetimeSearchCriteria"
          },
          "orderCreatedAt": {
            "$ref": "#/components/schemas/DatetimeSearchCriteria"
          }
        }
      },
      "ShipmentSearchRequest": {
        "type": "object",
        "description": "Request body for searching shipments",
        "properties": {
          "criteria": {
            "$ref": "#/components/schemas/ShipmentSearchCriteria",
            "description": "Search criteria to filter shipments"
          },
          "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"
          },
          "format": {
            "type": "string",
            "enum": [
              "flat",
              "full"
            ],
            "default": "flat",
            "description": "Response format:\n- flat: Returns only indexed fields (default, faster)\n- full: Returns complete shipment objects\n"
          }
        }
      },
      "ShipmentSearchRow": {
        "type": "object",
        "description": "Flattened shipment data from the search index. Pickup location arrays are\nordered by ascending stop sequence. Drop-off location arrays are ordered by\ndescending stop sequence, with the final destination first. For a side with\nmultiple stops, its location arrays use matching stop indexes and empty\nstrings preserve missing values. For a side with one stop, an individual\nmissing field is omitted instead of returned as an array containing an empty\nstring, so sibling arrays can be omitted independently.\n",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "SHIPMENT_SEARCH_ROW"
            ],
            "description": "Object type identifier"
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "friendlyId": {
            "type": "string",
            "example": "SHP-0001"
          },
          "status": {
            "type": "string"
          },
          "orderStatus": {
            "type": [
              "string",
              "null"
            ]
          },
          "mode": {
            "type": [
              "string",
              "null"
            ]
          },
          "tonu": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "pickUp": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Origin city and state values for all pickup stops"
          },
          "pickUpCity": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "pickUpState": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "pickUpZipCode": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "pickUpCountry": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "dropOff": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Destination city and state values for all drop-off stops"
          },
          "dropOffCity": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "dropOffState": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "dropOffZipCode": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "dropOffCountry": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "pickUpStartDatetime": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "dropOffStartDatetime": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "bookedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "shipperId": {
            "type": "string",
            "format": "uuid"
          },
          "shipperName": {
            "type": "string"
          },
          "carrierIds": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "carrierNames": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "primaryRepId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "primaryRepName": {
            "type": [
              "string",
              "null"
            ]
          },
          "groupId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "groupName": {
            "type": [
              "string",
              "null"
            ]
          },
          "equipmentType": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "weight": {
            "type": [
              "number",
              "null"
            ]
          },
          "totalMiles": {
            "type": "number"
          },
          "stopsCount": {
            "type": "integer"
          },
          "revenue": {
            "type": "number"
          },
          "cost": {
            "type": "number"
          },
          "profit": {
            "type": [
              "number",
              "null"
            ]
          },
          "profitMargin": {
            "type": [
              "number",
              "null"
            ]
          },
          "referenceValues": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "orderCreatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "object",
          "id",
          "friendlyId",
          "status",
          "shipperId",
          "shipperName",
          "createdAt"
        ]
      },
      "OrderReference": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "type": {
            "type": "string",
            "description": "Reference type (e.g., BOL_NUMBER)"
          },
          "value": {
            "type": "string",
            "description": "Reference value"
          }
        }
      },
      "LoadCarrierSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "carrier": {
            "$ref": "#/components/schemas/CarrierReference"
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "TONU",
              "BOUNCED"
            ]
          },
          "bookedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "dispatchedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "removedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When this carrier was removed from the load (bounce/TONU). Removed\ncarriers stay in the array as history, but their charges are NOT\nincluded in the load's `totalCost`.\n"
          },
          "totalCost": {
            "type": [
              "number",
              "null"
            ]
          }
        }
      },
      "LoadSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "friendlyId": {
            "type": "string",
            "description": "Human-readable load ID (e.g., \"LD-12345\")"
          },
          "key": {
            "type": [
              "string",
              "null"
            ],
            "description": "Client-defined reference identifier for this load"
          },
          "status": {
            "$ref": "#/components/schemas/ShipmentLifecycleStatus"
          },
          "mode": {
            "$ref": "#/components/schemas/TransportMode"
          },
          "carriers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LoadCarrierSummary"
            },
            "description": "Flattened carriers array"
          },
          "totalCost": {
            "type": [
              "number",
              "null"
            ]
          }
        }
      },
      "ServiceSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "key": {
            "type": [
              "string",
              "null"
            ]
          },
          "vendor": {
            "$ref": "#/components/schemas/VendorReference"
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "AWAITING_INVOICE",
              "INVOICE_IN_REVIEW",
              "APPROVED_TO_PAY",
              "PAID",
              "CANCELED"
            ]
          },
          "cost": {
            "type": [
              "number",
              "null"
            ]
          }
        }
      },
      "ShipmentSearchResponse": {
        "type": "object",
        "description": "Response for shipment search requests",
        "required": [
          "data",
          "pagination",
          "totalResults"
        ],
        "properties": {
          "data": {
            "type": "array",
            "description": "Search results - either flat rows or full shipment objects based on format parameter",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/ShipmentSearchRow"
                },
                {
                  "$ref": "#/components/schemas/Shipment"
                }
              ],
              "discriminator": {
                "propertyName": "object",
                "mapping": {
                  "SHIPMENT_SEARCH_ROW": "#/components/schemas/ShipmentSearchRow",
                  "SHIPMENT": "#/components/schemas/Shipment"
                }
              }
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/SearchPaginationInfo"
          },
          "totalResults": {
            "type": "integer",
            "description": "Total number of matching results",
            "minimum": 0
          }
        }
      },
      "ShipmentStatusFilter": {
        "type": "object",
        "properties": {
          "equalTo": {
            "$ref": "#/components/schemas/ShipmentLifecycleStatus"
          },
          "notEqualTo": {
            "$ref": "#/components/schemas/ShipmentLifecycleStatus"
          },
          "in": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShipmentLifecycleStatus"
            }
          },
          "notIn": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShipmentLifecycleStatus"
            }
          }
        }
      },
      "LoadStatusFilter": {
        "type": "object",
        "properties": {
          "equalTo": {
            "$ref": "#/components/schemas/LoadStatus"
          },
          "notEqualTo": {
            "$ref": "#/components/schemas/LoadStatus"
          },
          "in": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LoadStatus"
            }
          },
          "notIn": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LoadStatus"
            }
          }
        }
      },
      "LoadStop": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "orderStopId": {
            "type": "string",
            "format": "uuid",
            "description": "Reference to the order stop"
          },
          "sequence": {
            "type": "integer"
          },
          "type": {
            "type": "string",
            "enum": [
              "PICKUP",
              "DELIVERY"
            ]
          },
          "address": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Address"
              }
            ],
            "description": "Full address from the stop's linked location. Absent when the stop\nhas no linked shipper location.\n"
          },
          "scheduledArrival": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "actualArrival": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "actualDeparture": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "LoadCarrierCharge": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "chargeCodeId": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Charge code id. Resolve code/name via the reference-data charge-codes endpoint."
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "amount": {
            "type": "number",
            "description": "Extended line total (rate × quantity)"
          },
          "quantity": {
            "type": "number",
            "default": 1
          },
          "rate": {
            "type": [
              "number",
              "null"
            ],
            "description": "Unit rate for one quantity of this charge"
          }
        }
      },
      "AddCarrierResponse": {
        "type": "object",
        "required": [
          "loadId",
          "loadCarrierId"
        ],
        "properties": {
          "loadId": {
            "type": "string",
            "format": "uuid"
          },
          "loadCarrierId": {
            "type": "string",
            "format": "uuid",
            "description": "The new load carrier ID"
          },
          "loadCarrier": {
            "$ref": "#/components/schemas/LoadCarrier"
          }
        }
      },
      "RebookLoadResponse": {
        "type": "object",
        "required": [
          "originalLoadId",
          "newLoadId"
        ],
        "properties": {
          "originalLoadId": {
            "type": "string",
            "format": "uuid"
          },
          "newLoadId": {
            "type": "string",
            "format": "uuid"
          },
          "newLoadKey": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "LoadCarrierRemovalReason": {
        "type": "string",
        "enum": [
          "CAN_NO_LONGER_TAKE_LOAD",
          "LOAD_GIVEN_BACK",
          "RATE_CON_REJECTED",
          "CUSTOMER_NOT_READY_FOR_PU",
          "CONSIGNEE_NOT_READY_FOR_DEL",
          "FORGOT_TO_BOUNCE_CARRIER",
          "OTHER"
        ],
        "description": "Reason for removing a carrier from a load. Whether the removal counts as\na bounce or a TONU is the removal type, tracked separately.\n"
      },
      "ServiceStatusFilter": {
        "type": "object",
        "properties": {
          "equalTo": {
            "$ref": "#/components/schemas/ServiceStatus"
          },
          "notEqualTo": {
            "$ref": "#/components/schemas/ServiceStatus"
          },
          "in": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ServiceStatus"
            }
          },
          "notIn": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ServiceStatus"
            }
          }
        }
      },
      "ServiceCharge": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "chargeCode": {
            "$ref": "#/components/schemas/ResourceReference"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "amount": {
            "type": "number"
          },
          "quantity": {
            "type": "number",
            "default": 1
          }
        }
      },
      "InvoiceStatusFilter": {
        "type": "object",
        "properties": {
          "equalTo": {
            "$ref": "#/components/schemas/InvoiceStatus"
          },
          "notEqualTo": {
            "$ref": "#/components/schemas/InvoiceStatus"
          },
          "in": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InvoiceStatus"
            }
          },
          "notIn": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InvoiceStatus"
            }
          }
        }
      },
      "PaymentMethodType-3": {
        "type": "string",
        "enum": [
          "ACH_WIRE",
          "ZELLE",
          "VENMO",
          "CHECK",
          "EFT_DIRECT_DEPOSIT",
          "E_TRANSFER",
          "CREDIT_CARD"
        ],
        "description": "Payment method type.\n- `ACH_WIRE`: ACH or wire transfer\n- `ZELLE`: Zelle payment\n- `VENMO`: Venmo payment\n- `CHECK`: Paper check\n- `EFT_DIRECT_DEPOSIT`: EFT direct deposit\n- `E_TRANSFER`: Electronic transfer\n- `CREDIT_CARD`: Credit card payment\n"
      },
      "PaymentMethodTypeFilter-3": {
        "type": "object",
        "properties": {
          "equalTo": {
            "$ref": "#/components/schemas/PaymentMethodType-3"
          },
          "notEqualTo": {
            "$ref": "#/components/schemas/PaymentMethodType-3"
          },
          "in": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PaymentMethodType-3"
            }
          }
        }
      },
      "CreditMemoStatusFilter": {
        "type": "object",
        "properties": {
          "equalTo": {
            "$ref": "#/components/schemas/CreditMemoStatus"
          },
          "notEqualTo": {
            "$ref": "#/components/schemas/CreditMemoStatus"
          },
          "in": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CreditMemoStatus"
            }
          }
        }
      },
      "BillStatusFilter": {
        "type": "object",
        "properties": {
          "equalTo": {
            "$ref": "#/components/schemas/BillStatus"
          },
          "notEqualTo": {
            "$ref": "#/components/schemas/BillStatus"
          },
          "in": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BillStatus"
            }
          },
          "notIn": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BillStatus"
            }
          }
        }
      },
      "BillEntityTypeFilter": {
        "type": "object",
        "properties": {
          "equalTo": {
            "$ref": "#/components/schemas/BillEntityType"
          },
          "in": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BillEntityType"
            }
          }
        }
      },
      "BillPaymentMethodTypeFilter": {
        "type": "object",
        "properties": {
          "equalTo": {
            "$ref": "#/components/schemas/BillPaymentMethodType"
          },
          "in": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BillPaymentMethodType"
            }
          }
        }
      },
      "CarrierFactorReference-2": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "companyName": {
            "type": "string"
          },
          "bankName": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "BillPaymentApplicationPatch": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Existing application ID (for update)"
          },
          "billId": {
            "type": "string",
            "format": "uuid",
            "description": "Bill ID (for new applications)"
          },
          "amount": {
            "type": "number",
            "minimum": 0.01
          },
          "delete": {
            "type": "boolean",
            "description": "Set to true to remove this application"
          }
        }
      },
      "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.\nFor nested object changes, the changes array will contain child changes.\n",
        "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.\n- For ADD: The value being added\n- For UPDATE: The new value replacing the old one\n- For REMOVE: Not present\n",
            "example": "INACTIVE"
          },
          "oldValue": {
            "description": "The previous value (only present for UPDATE operations).\n",
            "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"
      }
    }
  }
}