{
  "openapi": "3.0.0",
  "paths": {
    "/deals/{partnerId}": {
      "get": {
        "operationId": "listDeals",
        "parameters": [
          {
            "name": "partnerId",
            "required": true,
            "in": "path",
            "description": "Your partner identifier (e.g. mypartner)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "_page",
            "required": false,
            "in": "query",
            "description": "Zero-based page index",
            "schema": {
              "default": 0,
              "type": "number"
            }
          },
          {
            "name": "_limit",
            "required": false,
            "in": "query",
            "description": "Page size (max 100)",
            "schema": {
              "default": 50,
              "type": "number"
            }
          },
          {
            "name": "status",
            "required": false,
            "in": "query",
            "description": "Filter by status",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerDealListResponseV1"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired Bearer token"
          },
          "404": {
            "description": "Partner or resource not found"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List deals where the partner org is buyer or seller",
        "tags": [
          "data"
        ]
      }
    },
    "/deals/{partnerId}/{dealId}": {
      "get": {
        "operationId": "getDeal",
        "parameters": [
          {
            "name": "partnerId",
            "required": true,
            "in": "path",
            "description": "Your partner identifier (e.g. mypartner)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "dealId",
            "required": true,
            "in": "path",
            "description": "Deal Mongo _id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerDealResponseV1"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired Bearer token"
          },
          "404": {
            "description": "Partner or resource not found"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get a single deal scoped to the partner org",
        "tags": [
          "data"
        ]
      }
    },
    "/offers/{partnerId}": {
      "get": {
        "operationId": "listOffers",
        "parameters": [
          {
            "name": "partnerId",
            "required": true,
            "in": "path",
            "description": "Your partner identifier (e.g. mypartner)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "_page",
            "required": false,
            "in": "query",
            "description": "Zero-based page index",
            "schema": {
              "default": 0,
              "type": "number"
            }
          },
          {
            "name": "_limit",
            "required": false,
            "in": "query",
            "description": "Page size (max 100)",
            "schema": {
              "default": 50,
              "type": "number"
            }
          },
          {
            "name": "status",
            "required": false,
            "in": "query",
            "description": "Filter by status",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerOfferListResponseV1"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired Bearer token"
          },
          "404": {
            "description": "Partner or resource not found"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List offers where the partner org is offering or being offered to",
        "tags": [
          "data"
        ]
      }
    },
    "/offers/{partnerId}/{offerId}": {
      "get": {
        "operationId": "getOffer",
        "parameters": [
          {
            "name": "partnerId",
            "required": true,
            "in": "path",
            "description": "Your partner identifier (e.g. mypartner)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offerId",
            "required": true,
            "in": "path",
            "description": "Offer Mongo _id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerOfferResponseV1"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired Bearer token"
          },
          "404": {
            "description": "Partner or resource not found"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get a single offer scoped to the partner org",
        "tags": [
          "data"
        ]
      }
    },
    "/listings/{partnerId}": {
      "get": {
        "operationId": "listListings",
        "parameters": [
          {
            "name": "partnerId",
            "required": true,
            "in": "path",
            "description": "Your partner identifier (e.g. mypartner)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "_page",
            "required": false,
            "in": "query",
            "description": "Zero-based page index",
            "schema": {
              "default": 0,
              "type": "number"
            }
          },
          {
            "name": "_limit",
            "required": false,
            "in": "query",
            "description": "Page size (max 100)",
            "schema": {
              "default": 50,
              "type": "number"
            }
          },
          {
            "name": "status",
            "required": false,
            "in": "query",
            "description": "Filter by status",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerListingListResponseV1"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired Bearer token"
          },
          "404": {
            "description": "Partner or resource not found"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List listings owned by the partner org",
        "tags": [
          "data"
        ]
      }
    },
    "/listings/{partnerId}/{listingId}": {
      "get": {
        "operationId": "getListing",
        "parameters": [
          {
            "name": "partnerId",
            "required": true,
            "in": "path",
            "description": "Your partner identifier (e.g. mypartner)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "listingId",
            "required": true,
            "in": "path",
            "description": "Listing Mongo _id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerListingResponseV1"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired Bearer token"
          },
          "404": {
            "description": "Partner or resource not found"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get a single listing scoped to the partner org",
        "tags": [
          "data"
        ]
      }
    },
    "/webhook-deliveries/{partnerId}": {
      "get": {
        "operationId": "listWebhookDeliveries",
        "parameters": [
          {
            "name": "partnerId",
            "required": true,
            "in": "path",
            "description": "Your partner identifier (e.g. mypartner)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "_page",
            "required": false,
            "in": "query",
            "description": "Zero-based page index",
            "schema": {
              "default": 0,
              "type": "number"
            }
          },
          {
            "name": "_limit",
            "required": false,
            "in": "query",
            "description": "Page size (max 100)",
            "schema": {
              "default": 50,
              "type": "number"
            }
          },
          {
            "name": "status",
            "required": false,
            "in": "query",
            "description": "Filter by delivery status",
            "schema": {
              "type": "string",
              "enum": [
                "delivered",
                "failed",
                "skipped"
              ]
            }
          },
          {
            "name": "event",
            "required": false,
            "in": "query",
            "description": "Filter by event name (e.g. deal.created)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "dateFrom",
            "required": false,
            "in": "query",
            "description": "ISO 8601 — only deliveries attempted at or after this time",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "dateTo",
            "required": false,
            "in": "query",
            "description": "ISO 8601 — only deliveries attempted at or before this time",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerWebhookDeliveryListResponseV1"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired Bearer token"
          },
          "404": {
            "description": "Partner or resource not found"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "List webhook delivery attempts for this partner",
        "tags": [
          "data"
        ]
      }
    },
    "/webhook-deliveries/{partnerId}/{logId}": {
      "get": {
        "operationId": "getWebhookDelivery",
        "parameters": [
          {
            "name": "partnerId",
            "required": true,
            "in": "path",
            "description": "Your partner identifier (e.g. mypartner)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "logId",
            "required": true,
            "in": "path",
            "description": "Outbound delivery log Mongo _id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerWebhookDeliveryResponseV1"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired Bearer token"
          },
          "404": {
            "description": "Partner or resource not found"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get a single webhook delivery attempt",
        "tags": [
          "data"
        ]
      }
    },
    "/deals/{partnerId}/{dealId}/documents": {
      "get": {
        "description": "Returns title attachment + every `documents`-collection row + every `platoforms_generated_documents` row (Bill of Sale, etc.) linked to this deal. Use this to re-fetch documents after the original webhook signed-URL window has expired.",
        "operationId": "getDealDocuments",
        "parameters": [
          {
            "name": "partnerId",
            "required": true,
            "in": "path",
            "description": "Your partner identifier (e.g. mypartner)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "dealId",
            "required": true,
            "in": "path",
            "description": "Deal Mongo _id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerDealDocumentsResponseV1"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired Bearer token"
          },
          "404": {
            "description": "Partner or resource not found"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get all documents for a deal with fresh 4-hour signed URLs",
        "tags": [
          "data"
        ]
      },
      "post": {
        "description": "Attach a file (signed title, lien release, payoff letter, POA, disclosure) to a deal your org is a party to. Multipart `file` + `documentType` + `callerReferenceId` (+ optional `description`). Idempotent on `callerReferenceId` (unique across all your uploads). Returns 404 if the deal is not in your scope, 409 `deal_not_uploadable` if the deal is cancelled/expired, 409 `duplicate_reference` if the reference is reused with a different file.",
        "operationId": "uploadDealDocument",
        "parameters": [
          {
            "name": "partnerId",
            "required": true,
            "in": "path",
            "description": "Your partner identifier (e.g. mypartner)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "dealId",
            "required": true,
            "in": "path",
            "description": "Deal Mongo _id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/PartnerDocumentUploadV1Dto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerDocumentUploadResponseV1"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired Bearer token"
          },
          "404": {
            "description": "Partner or resource not found"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Upload a document onto a deal",
        "tags": [
          "data"
        ]
      }
    },
    "/documents/{partnerId}/{documentId}": {
      "get": {
        "description": "Returns 404 if the document does not belong to a deal your org is on.",
        "operationId": "getDocument",
        "parameters": [
          {
            "name": "partnerId",
            "required": true,
            "in": "path",
            "description": "Your partner identifier (e.g. mypartner)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "documentId",
            "required": true,
            "in": "path",
            "description": "Document Mongo _id (from `documents` collection)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerDocumentDetailResponseV1"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired Bearer token"
          },
          "404": {
            "description": "Partner or resource not found"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get a single document (POA, deal doc) with a fresh signed URL",
        "tags": [
          "data"
        ]
      },
      "delete": {
        "description": "Hides a document you uploaded (never a hard delete). Returns 404 if it is not your upload, 409 `document_acted_on` if it has been signed/acknowledged (must be replaced, not voided).",
        "operationId": "voidDealDocument",
        "parameters": [
          {
            "name": "partnerId",
            "required": true,
            "in": "path",
            "description": "Your partner identifier (e.g. mypartner)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "documentId",
            "required": true,
            "in": "path",
            "description": "Document Mongo _id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Voided — returns `{ documentId, status: \"voided\" }`"
          },
          "401": {
            "description": "Missing, invalid, or expired Bearer token"
          },
          "404": {
            "description": "Partner or resource not found"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Soft-void a document you uploaded",
        "tags": [
          "data"
        ]
      }
    },
    "/generated-documents/{partnerId}/{documentId}": {
      "get": {
        "description": "Returns 404 if the document does not belong to a deal your org is on.",
        "operationId": "getGeneratedDocument",
        "parameters": [
          {
            "name": "partnerId",
            "required": true,
            "in": "path",
            "description": "Your partner identifier (e.g. mypartner)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "documentId",
            "required": true,
            "in": "path",
            "description": "Generated-document Mongo _id (from `platoforms_generated_documents` collection)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerGeneratedDocumentDetailResponseV1"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired Bearer token"
          },
          "404": {
            "description": "Partner or resource not found"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Get a single generated document (e.g. Bill of Sale) with a fresh signed URL",
        "tags": [
          "data"
        ]
      }
    },
    "/sell/{partnerId}": {
      "get": {
        "description": "Initiate a DealNow transaction via browser redirect. The user is redirected to their\nbuyer link (or a `redirectUrl` you specify).\n\n**Auth:** Inline — JWT (Formats 1/2) or HMAC-signed short-key query (Format 3). No Authorization header needed; all three formats authenticate against the partner shared secret.\n\n### Query Parameter Formats\n\n**Format 1 — Explicit JWT**\n```\nGET /sell/mypartner?jwt=<token>\n```\n\n**Format 2 — VIN param is a JWT**\n```\nGET /sell/mypartner?v=<token>\n```\nIf the `v` param contains dots, it is treated as a JWT. The JWT payload may use either full field names or the short keys.\n\n**Format 3 — Signed short key query params**\n```\nGET /sell/mypartner?v=1HGBH41JXMN109186&y=2021&m=Honda&o=Civic&a=18500&be=buyer@example.com&r=https://yoursite.com/thanks&ts=<epochSec>&sig=<hex>\n```\nFormat 3 requires `ts` (current epoch seconds, ±5 min skew allowed) and `sig` — a hex-encoded HMAC-SHA256 of the canonical query string, signed with the partner's shared secret (the same secret used for JWT signing).\n\n**Canonical string:** every query param except `sig`, sorted alphabetically by key, URL-encoded `k=v` joined by `&`.\n\n```bash\n# Node example\nnode -e '\n  const crypto = require(\"crypto\");\n  const secret = Buffer.from(\"YOUR_BASE64_SECRET\", \"base64\").toString(\"utf-8\");\n  const params = { v: \"1HGBH41JXMN109186\", y: 2021, m: \"Honda\", o: \"Civic\",\n                   a: 18500, be: \"buyer@example.com\", ts: Math.floor(Date.now()/1000) };\n  const canonical = Object.keys(params).sort()\n    .map(k => encodeURIComponent(k) + \"=\" + encodeURIComponent(params[k]))\n    .join(\"&\");\n  const sig = crypto.createHmac(\"sha256\", secret).update(canonical).digest(\"hex\");\n  console.log(canonical + \"&sig=\" + sig);\n'\n```\n\n### Short Key Reference\n\n| Short | Full Field | Type |\n|-------|-----------|------|\n| `v` | vin | string |\n| `y` | year | number |\n| `m` | make | string |\n| `o` | model | string |\n| `t` | trim | string |\n| `a` | amount | number |\n| `bn` | buyerName | string |\n| `be` | buyerEmail | string |\n| `bl` | buyerSendLink | boolean |\n| `sn` | sellerName | string |\n| `se` | sellerEmail | string |\n| `sl` | sellerSendLink | boolean |\n| `r` | redirectUrl | string |\n| `ro` | role | buyer or seller (default: buyer) |\n\n### Redirect Behavior\n\n- If `redirectUrl` is provided, the user is redirected there after the deal is created.\n- If no `redirectUrl` is provided, the user is redirected to the link for the party specified by `role` (default: buyer).\n- Use `role=seller` when the initiating user is the vehicle seller rather than the buyer.\n\n### Acting for a linked dealership\n\nIf the buyer or seller email belongs to a user of a dealership your partner account is linked to, the deal is started\nfor that dealership: that user is your side of the deal, and the offer and any new listing belong to their dealership.\nOtherwise your own organization is your side, as before.\n\nA dealership becomes linked when `POST /dealers/lookup/{partnerId}` first returns it, or when the dealer group\napproves your OAuth client and that credential is first used. Both give the same standing, including to your own\ncredentials, and it lasts until PrivateAuto revokes the link: withdrawing OAuth consent does not end it.\n\nA deal can belong to only one dealership. If both emails match, or one email's user belongs to several linked\ndealerships, the request is rejected with `400` and a `code` — `ambiguous_dealership_both_parties` or\n`ambiguous_dealership_multiple_orgs` — whose `message` names the dealerships that collided. Nothing is created.\n\nYou can read these deals back: `/data` returns the offers and deals you started and their documents, with the\nlistings you created or that belong to the dealership, even though they belong to the dealership's organization.\n\nWebhooks for these offers, deals and new listings reach you only through `appSource` routing, so only with a\n`webhookScope` of `appSource` or `both` (the default). With `organization` you receive none of them: they\ncarry the dealership's organization, not yours.",
        "operationId": "initiateGet[1]",
        "parameters": [
          {
            "name": "partnerId",
            "required": true,
            "in": "path",
            "description": "Your partner identifier, provided during onboarding (e.g. mypartner)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "v",
            "required": false,
            "in": "query",
            "description": "VIN or JWT token (Format 2/3)",
            "schema": {}
          },
          {
            "name": "jwt",
            "required": false,
            "in": "query",
            "description": "Explicit JWT token (Format 1)",
            "schema": {}
          }
        ],
        "responses": {
          "302": {
            "description": "Redirects to the role-appropriate deal link, or redirectUrl if provided. A refusal also redirects, to the page it names (PA-7530): `402 subscription_inactive` to the subscription page, `403 onboarding_incomplete` to wallet setup, and any other refusal to the error page. Other refusals include: missing VIN; vehicle not found without year/make/model; VIN within the relist cooldown; emails matching more than one linked dealership; Format 3 missing `sig`/`ts`, expired `ts` or signature mismatch; partner not found."
          },
          "500": {
            "description": "Server error. The JSON body carries `redirectUrl` to the error page."
          }
        },
        "summary": "Initiate DealNow via GET (URL params or JWT)",
        "tags": [
          "sell"
        ]
      },
      "post": {
        "description": "Initiate a DealNow transaction. Returns buyer and seller deep links.\n\nRequires a **HS256, HS384, or HS512 JWT** Bearer token signed with your partner shared secret.\n\nIf this VIN is not already listed under your account, `year`, `make`, and `model` are required in addition to `vin`. A listing owned by another dealer, partner or PrivateAuto user does not count.\n\n> **Note:** `redirectUrl` and `role` are GET-only parameters and are not applicable to this endpoint.\n\n### Generating the JWT\n\nYour shared secret is delivered as a base64-encoded string — decode it to a UTF-8 string before signing. Pick one of the following:\n\n**Node.js** (`npm install jsonwebtoken`):\n```bash\nJWT=$(node -e '\n  const jwt = require(\"jsonwebtoken\");\n  const secret = Buffer.from(\"YOUR_BASE64_SECRET\", \"base64\").toString(\"utf-8\");\n  console.log(jwt.sign(\n    { p: \"YOUR_PARTNER_ID\", iat: Math.floor(Date.now() / 1000) },\n    secret,\n    { algorithm: \"HS256\", expiresIn: \"5m\" }\n  ));\n')\n```\n\n**Python** (`pip install pyjwt`):\n```bash\nJWT=$(python3 -c '\nimport base64, jwt, time\nsecret = base64.b64decode(\"YOUR_BASE64_SECRET\").decode(\"utf-8\")\nnow = int(time.time())\nprint(jwt.encode(\n    {\"p\": \"YOUR_PARTNER_ID\", \"iat\": now, \"exp\": now + 300},\n    secret,\n    algorithm=\"HS256\",\n))\n')\n```\n\n**CLI** ([jwt-cli](https://github.com/mike-engel/jwt-cli), `brew install mike-engel/jwt-cli/jwt-cli`):\n```bash\nSECRET=$(printf '%s' 'YOUR_BASE64_SECRET' | base64 -d)\nJWT=$(jwt encode \\\n  --alg HS256 \\\n  --secret \"$SECRET\" \\\n  --exp '+5m' \\\n  -P p=YOUR_PARTNER_ID)\n```\n\n### Making the request\n\n```bash\ncurl -X POST \"https://partner-api.padev.xyz/sell/YOUR_PARTNER_ID\" \\\n  -H \"Authorization: Bearer $JWT\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"vin\": \"1HGBH41JXMN109186\",\n    \"year\": 2021,\n    \"make\": \"Honda\",\n    \"model\": \"Accord\",\n    \"trim\": \"EX-L\",\n    \"amount\": 18500,\n    \"buyerName\": \"Jane Buyer\",\n    \"buyerEmail\": \"jane@example.com\",\n    \"buyerSendLink\": true,\n    \"sellerName\": \"John Seller\",\n    \"sellerEmail\": \"john@example.com\",\n    \"sellerSendLink\": true\n  }'\n```\n\nProduction host: `https://partner-api.privateauto.com`.\n\n### Acting for a linked dealership\n\nIf the buyer or seller email belongs to a user of a dealership your partner account is linked to, the deal is started\nfor that dealership: that user is your side of the deal, and the offer and any new listing belong to their dealership.\nOtherwise your own organization is your side, as before.\n\nA dealership becomes linked when `POST /dealers/lookup/{partnerId}` first returns it, or when the dealer group\napproves your OAuth client and that credential is first used. Both give the same standing, including to your own\ncredentials, and it lasts until PrivateAuto revokes the link: withdrawing OAuth consent does not end it.\n\nA deal can belong to only one dealership. If both emails match, or one email's user belongs to several linked\ndealerships, the request is rejected with `400` and a `code` — `ambiguous_dealership_both_parties` or\n`ambiguous_dealership_multiple_orgs` — whose `message` names the dealerships that collided. Nothing is created.\n\nYou can read these deals back: `/data` returns the offers and deals you started and their documents, with the\nlistings you created or that belong to the dealership, even though they belong to the dealership's organization.\n\nWebhooks for these offers, deals and new listings reach you only through `appSource` routing, so only with a\n`webhookScope` of `appSource` or `both` (the default). With `organization` you receive none of them: they\ncarry the dealership's organization, not yours.",
        "operationId": "initiatePost[1]",
        "parameters": [
          {
            "name": "partnerId",
            "required": true,
            "in": "path",
            "description": "Your partner identifier, provided during onboarding (e.g. mypartner)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InitiateDealNowV1Dto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Deal created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InitiateDealNowResponseV1Dto"
                }
              }
            }
          },
          "400": {
            "description": "Missing VIN; vehicle not found and year/make/model not provided; the VIN was sold within the partner relist cooldown window and is not yet eligible to be relisted (message states the eligible-again date); or the emails match more than one dealership you are linked to (`code`: `ambiguous_dealership_both_parties` / `ambiguous_dealership_multiple_orgs`)"
          },
          "401": {
            "description": "Missing, invalid, or expired Bearer token"
          },
          "404": {
            "description": "Partner not found"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Initiate DealNow via POST (JSON body)",
        "tags": [
          "sell"
        ]
      }
    },
    "/sell/{partnerId}/widget": {
      "post": {
        "description": "Browser-safe variant of `POST /sell/:partnerId` for the embeddable make-offer widget.\n\n**Auth:** send your **publishable key** (non-secret, embeddable) in the `X-PA-Widget-Key` header. The\nrequest is accepted only when the key matches the partner AND the request `Origin` (or `Referer`) host is\nin the partner's configured `widgetOrigins` allowlist. No shared secret or JWT is used — the origin\nallowlist is the trust boundary, appropriate for this low-risk (no funds move) endpoint.\n\nBody is identical to `POST /sell/:partnerId` (`InitiateDealNowV1Dto`), including `contingencies`,\n`expirationDate`, `customConditions`, and `customMessage`.\n\n**Differences from the server route:** `buyerSendLink` / `sellerSendLink` are ignored and no email is\nsent; show or deliver the returned links yourself. A posted email always names the counterparty (`buyerEmail`\n→ you are the seller; `sellerEmail` or no email → you are the buyer), is never matched to an existing\naccount (the counterparty is bound when they follow their link), and posting both emails is rejected.\n\nUnlike `POST /sell/:partnerId`, the widget never starts a deal for a linked dealership: a publishable key cannot\nvouch for who entered the email, so your own organization is always your side.",
        "operationId": "initiateWidget[1]",
        "parameters": [
          {
            "name": "partnerId",
            "required": true,
            "in": "path",
            "description": "Your partner identifier, provided during onboarding (e.g. mypartner)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InitiateDealNowV1Dto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Deal created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InitiateDealNowResponseV1Dto"
                }
              }
            }
          },
          "400": {
            "description": "Missing VIN, vehicle not found and year/make/model not provided, or both buyerEmail and sellerEmail posted"
          },
          "401": {
            "description": "Missing X-PA-Widget-Key header, invalid key, or Origin/Referer not in the partner allowlist"
          },
          "404": {
            "description": "Partner not found"
          }
        },
        "summary": "Initiate DealNow from an embedded make-offer widget (publishable key)",
        "tags": [
          "sell"
        ]
      }
    },
    "/leads/{partnerId}": {
      "post": {
        "description": "Submit a lead for a dealer organization.\n\nRequires a **HS256, HS384, or HS512 JWT** Bearer token signed with your partner shared secret.\n\n### Idempotent Submission\n\nThe `callerReferenceId` is your own identifier for this lead (e.g. your CRM record ID).\nSubmitting the same `callerReferenceId` twice returns `409 Conflict` with the existing lead ID,\nso you can safely retry without creating duplicates.\n\n### Organization Authorization\n\nYour partner account has an allowlist of organization IDs you can submit leads to.\nSubmitting to an org not on your allowlist returns `403 Forbidden`.\n\n### Request Example\n\n```json\n{\n  \"callerReferenceId\": \"LDR-98234\",\n  \"organizationId\": \"663a1f...\",\n  \"leadCode\": \"CONQUEST\",\n  \"contact\": {\n    \"name\": \"Jane Smith\",\n    \"email\": \"jane@example.com\",\n    \"phone\": \"555-867-5309\",\n    \"message\": \"Interested in trading in my truck\"\n  },\n  \"vehicle\": {\n    \"vin\": \"1HGBH41JXMN109186\",\n    \"year\": 2019,\n    \"make\": \"Honda\",\n    \"model\": \"Accord\",\n    \"trim\": \"Sport\",\n    \"mileage\": 42000\n  }\n}\n```",
        "operationId": "submitLead[1]",
        "parameters": [
          {
            "name": "partnerId",
            "required": true,
            "in": "path",
            "description": "Your partner identifier",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubmitLeadV1Dto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Lead created",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Request quota in the current window"
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests remaining in the current window"
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Epoch seconds at which the current window resets"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubmitLeadResponseV1Dto"
                }
              }
            }
          },
          "400": {
            "description": "Validation error"
          },
          "401": {
            "description": "Missing, invalid, or expired Bearer token"
          },
          "403": {
            "description": "Not authorized for this organization"
          },
          "409": {
            "description": "Duplicate callerReferenceId",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DuplicateLeadResponseV1Dto"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded — inspect the X-RateLimit-* response headers to pace retries",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Request quota in the current window"
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests remaining (will be 0 on 429)"
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Epoch seconds at which the current window resets"
              },
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying"
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Submit a lead",
        "tags": [
          "leads"
        ]
      },
      "get": {
        "description": "Look up a previously submitted lead using your own reference ID.\n\nRequires a **HS256, HS384, or HS512 JWT** Bearer token signed with your partner shared secret.\n\nReturns the current lead status and metadata. Use this to check whether a lead was already submitted\n(e.g. before retrying) or to poll for status updates.",
        "operationId": "lookupLead[1]",
        "parameters": [
          {
            "name": "partnerId",
            "required": true,
            "in": "path",
            "description": "Your partner identifier",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "callerReferenceId",
            "required": true,
            "in": "query",
            "description": "Your reference ID for the lead — the same value you passed on submission",
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lead found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubmitLeadResponseV1Dto"
                }
              }
            }
          },
          "400": {
            "description": "Missing or empty callerReferenceId query parameter"
          },
          "401": {
            "description": "Missing, invalid, or expired Bearer token"
          },
          "404": {
            "description": "No lead found for this callerReferenceId"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Look up a lead by callerReferenceId",
        "tags": [
          "leads"
        ]
      }
    },
    "/dealers/lookup/{partnerId}": {
      "post": {
        "description": "Resolve a PrivateAuto user's email address to the dealership(s) they belong to.\n\nRequires a **HS256, HS384, or HS512 JWT** Bearer token signed with your partner shared secret, **and**\nthe `dealers:lookup` permission on your partner account — contact PrivateAuto to have it enabled.\n\nLimited to 60 requests per minute per partner; over the limit returns `429` with\n`X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers.\n\nMatching is exact and case-insensitive. Dealerships that are deleted or banned are never returned, and an\naddress whose dealerships are all deleted or banned returns the same `404` as an unknown address.\n\n**A successful lookup links your partner account to every dealership it returns.** Once linked, a deal you\nstart with `POST /sell/{partnerId}` or `POST /v2/deal-invites` whose buyer or seller email belongs to that\ndealership is started for it. Each new link fires a `dealer.linked` webhook; repeat lookups do not. Your own organization is always linked. This is an interim\nmodel until dealer authorization moves to OAuth.",
        "operationId": "lookup[1]",
        "parameters": [
          {
            "name": "partnerId",
            "required": true,
            "in": "path",
            "description": "Your partner identifier",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DealerLookupV1Dto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Dealership(s) found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DealerLookupResponseV1Dto"
                }
              }
            }
          },
          "400": {
            "description": "Missing or malformed `email`"
          },
          "401": {
            "description": "Missing, invalid or expired token"
          },
          "403": {
            "description": "Your partner account does not have `dealers:lookup`"
          },
          "404": {
            "description": "No dealership found for this email. When your partner account has a co-brand sign-up page, the body also carries `signupUrl`, the page to send the dealer to so they can create a DealNow account. It is the same for every miss."
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "summary": "Look up dealer ids by user email",
        "tags": [
          "dealer-lookup"
        ]
      }
    }
  },
  "info": {
    "title": "PrivateAuto Partner API",
    "description": "<sub>build `2026.1119.5730-f196d97817`</sub>\n\nPartner integration API for DealNow initiation, lead ingestion, partner-scoped read access, and real-time webhook notifications.\n\n## Authentication\n\nAll `POST` endpoints require a Bearer token in the `Authorization` header. The `/data` read endpoints (deals, offers, listings, webhook-deliveries, documents) use the same Bearer token. The `GET /sell/{partnerId}` endpoint additionally supports inline JWT auth via query params — see its own description.\n\nThe token must be a **HS256, HS384, or HS512 JWT** signed with your partner shared secret, which PrivateAuto provides during onboarding.\n\n### Generating the JWT\n\nYour shared secret is delivered as a base64-encoded string — decode it to a UTF-8 string before signing. The JWT payload must include `p` (your partner identifier) and a short expiry (we recommend `≤ 5 minutes`). Pick one of the following:\n\n**Node.js** (`npm install jsonwebtoken`):\n\n```bash\nJWT=$(node -e '\n  const jwt = require(\"jsonwebtoken\");\n  const secret = Buffer.from(\"YOUR_BASE64_SECRET\", \"base64\").toString(\"utf-8\");\n  console.log(jwt.sign(\n    { p: \"YOUR_PARTNER_ID\", iat: Math.floor(Date.now() / 1000) },\n    secret,\n    { algorithm: \"HS256\", expiresIn: \"5m\" }\n  ));\n')\n```\n\n**Python** (`pip install pyjwt`):\n\n```bash\nJWT=$(python3 -c '\nimport base64, jwt, time\nsecret = base64.b64decode(\"YOUR_BASE64_SECRET\").decode(\"utf-8\")\nnow = int(time.time())\nprint(jwt.encode(\n    {\"p\": \"YOUR_PARTNER_ID\", \"iat\": now, \"exp\": now + 300},\n    secret,\n    algorithm=\"HS256\",\n))\n')\n```\n\n**CLI** ([jwt-cli](https://github.com/mike-engel/jwt-cli), `brew install mike-engel/jwt-cli/jwt-cli`):\n\n```bash\nSECRET=$(printf '%s' 'YOUR_BASE64_SECRET' | base64 -d)\nJWT=$(jwt encode \\\n  --alg HS256 \\\n  --secret \"$SECRET\" \\\n  --exp '+5m' \\\n  -P p=YOUR_PARTNER_ID)\n```\n\n### Making an authenticated request\n\n```bash\ncurl -X POST \"https://partner-api.privateauto.com/sell/YOUR_PARTNER_ID\" \\\n  -H \"Authorization: Bearer $JWT\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"vin\": \"1HGBH41JXMN109186\", \"amount\": 18500 }'\n```\n\nProduction host: `https://partner-api.privateauto.com`. Padev host: `https://partner-api.padev.xyz`.\n\n\n## Webhooks\n\nPrivateAuto pushes real-time event notifications to your server whenever key actions happen on a deal, listing, offer, or user that originated through your partner integration.\n\nWebhooks are configured per-partner during onboarding. You provide an HTTPS endpoint URL, a list of event types to subscribe to, and a webhook secret for signature verification.\n\n> **Looking for the per-transaction event sequence?** See the [Event sequences by transaction type](#event-sequences-by-transaction-type) section below for the canonical event chain per deal shape (C2D / D2C / D2D / C2C, plus the partner-initiated `/sell` flow) and minimum-viable subscription sets.\n\n> **Reading this against a specific release?** Anything marked *\"not yet in production\"* is present in this reference but not yet serving production traffic. See [Availability by release](#availability-by-release) for the full list and how to check what your environment is running.\n\n### Configuration\n\n| Setting | Description |\n|---------|-------------|\n| **Endpoint URL** | Your public HTTPS URL. Private/internal IP addresses are rejected. |\n| **Webhook secret** | A shared secret used to sign every delivery. PrivateAuto provides this during onboarding. |\n| **Events** | The event types you want to receive. Supports wildcards (e.g. `deal.*`, `*`). |\n\n### Delivery Format\n\nWebhooks are delivered as `POST` requests with the following headers:\n\n| Header | Description |\n|--------|-------------|\n| `Content-Type` | `application/json` |\n| `X-PA-Event` | Event type, e.g. `deal.completed` |\n| `X-PA-Timestamp` | When this delivery attempt was sent — ISO 8601 by default, or Unix seconds if your account is configured for them. A retry carries a fresh timestamp |\n| `X-PA-Signature` | HMAC-SHA256 signature (see Verifying Signatures) |\n| `X-PA-Partner` | Your partner ID |\n| `X-PA-Event-Id` | Stable per-event idempotency identifier (see Idempotency) |\n| `User-Agent` | `PrivateAuto-Webhooks/1.0` |\n\nEvery payload also carries `eventId` and `eventKey` at the top level — see Idempotency.\n\n### Verifying Signatures\n\nEvery delivery includes an `X-PA-Signature` header of the form `sha256={hex}`. To verify:\n\n1. Extract `X-PA-Timestamp` from the request headers.\n2. Concatenate: `{timestamp}.{raw_body}`.\n3. Compute HMAC-SHA256 of that string using your webhook secret.\n4. Compare (hex-encoded) to the value after `sha256=` in `X-PA-Signature`.\n5. Reject the delivery if `X-PA-Timestamp` is more than **5 minutes** from your own clock.\n\nThe timestamp is inside the signed material so that step 5 can stop a captured delivery being\nreplayed later. Every attempt, including a retry, is signed with the time it was sent, so a\n5-minute tolerance never rejects a legitimate delivery — allow more only if your clock is not\nNTP-synchronised.\n\n```javascript\nconst crypto = require('crypto');\n\nfunction verifySignature(req, secret) {\n  const timestamp = req.headers['x-pa-timestamp'];\n  const received  = req.headers['x-pa-signature']; // \"sha256=abc123...\"\n  const body      = req.rawBody;                   // raw bytes, not parsed JSON\n\n  const expected = 'sha256=' + crypto\n    .createHmac('sha256', secret)\n    .update(`${timestamp}.${body}`)\n    .digest('hex');\n\n  return crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));\n}\n```\n\n> Always use the raw request body (before JSON parsing) for signature verification.\n\n### Idempotency\n\nEvery webhook payload carries two fields that let you safely dedupe duplicate deliveries:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `eventId` | string | sha256 hex (64 chars). The canonical idempotency key. Stable across delivery retries and across our own internal replay (e.g. resume after a worker restart). |\n| `eventKey` | string | Composite key the `eventId` was derived from. Informational only — see warning below. |\n\nThe same `eventId` value is also delivered as the `X-PA-Event-Id` HTTP header.\n\n**Recommended:** keep a cache of received `eventId`s for at least 24 hours and skip processing on a hit. 24 hours covers the retry schedule — about 21 minutes from first attempt to dead letter — with a wide margin.\n\n> **Do not parse `eventKey`.** Its internal structure (resume token, partner id, event name, emission index, separator) is an implementation detail and may change without an API version bump. It is provided for log correlation and support tickets only — only `eventId` is a stable contract.\n\n`eventId` is included in the signed body, so it is automatically covered by the existing `X-PA-Signature` HMAC. No extra verification step is needed beyond the standard signature check.\n\n### Retry Behavior\n\nIf your endpoint returns a non-2xx status, answers with a redirect, or does not respond within 10 seconds, PrivateAuto retries the delivery:\n\n| Retry | When |\n|---------|-------|\n| 1 | 1 minute after the first attempt |\n| 2 | 5 minutes after retry 1 |\n| 3 | 15 minutes after retry 2 |\n\nEach retry sends the same payload and `eventId` (so your idempotency check applies), signed afresh with the time of that attempt. Retries normally run within about 15 seconds of their scheduled time, but can run later when many are due at once — during a widespread outage, for example.\n\nIf the third retry fails, the event is dead-lettered and not retried again: it is listed with status `dlq` in `GET /v2/webhooks/deliveries`, and you should reconcile it from the API. A pending retry is dropped instead — and logged as `skipped` — if, before it runs, the endpoint is disabled or deleted or unsubscribes from that event.\n\nReturn `2xx` as quickly as possible — process events asynchronously if needed.\n\n### Event Types\n\nSubscribe to individual events or use wildcard namespaces:\n\n| Wildcard | Matches |\n|----------|---------|\n| `deal.*` | All deal events |\n| `dealer.*` | All dealer-link events |\n| `document.*` | All document events |\n| `listing.*` | All listing events |\n| `offer.*` | All offer events |\n| `user.*` | All user events |\n| `*` | All events |\n\n#### Deal Events\n\n| Event | When it fires |\n|-------|---------------|\n| `deal.created` | A deal is initiated via the Partner API |\n| `deal.completed` | Deal fully completed (both parties confirmed, funds transferred) |\n| `deal.cancelled` | Deal cancelled by either party |\n| `deal.expired` | Deal expired without completion |\n| `deal.offer_accepted` | Both buyer and seller have confirmed deal terms |\n| `deal.buyer_joined` | Buyer has joined the deal |\n| `deal.seller_joined` | Seller has joined the deal |\n| `deal.buyer_ready` | Buyer has confirmed all steps and is ready to close |\n| `deal.seller_ready` | Seller has confirmed all steps and is ready to close |\n| `deal.co_seller_invited` | A co-seller invitation email is sent |\n| `deal.title_submitted` | Either party confirms the title-information step (ownership, registration, lien holder). Fires once per deal, on whichever side confirms first |\n| `deal.title_approved` | Seller marks title attachment complete after uploading photos (seller-driven, not admin review) |\n| `deal.docs_submitted` | Buyer/seller submit closing documents |\n| `deal.docs_approved` | Closing documents are approved |\n| `deal.payment_initiated` | Payment transfer is initiated |\n| `deal.payment_acknowledged` | Seller acknowledges receipt of payment |\n| `deal.amount_changed` | Deal amount updated after creation |\n| `deal.negative_equity_identified` | Payoff amount exceeds deal amount — stamped by the admin/service-side payoff path |\n| `deal.negative_equity_reported` | Payoff amount exceeds deal amount — reached via the consumer-facing (user-side) path. Same `negativeEquity: true` payload as `deal.negative_equity_identified`; the event name is the only discriminator, so **subscribe to both** |\n| `deal.negative_equity_funded` | Negative equity balance has been funded |\n| `deal.loan_payoff_docs` | Seller's loan payoff documents are uploaded |\n| `deal.loan_payoff_confirmed` | Loan payoff is manually confirmed |\n| `deal.poa_approved` | **Deprecated — removal on or after 1 February 2027.** Power of Attorney document is fully signed. Replaced by `document.completed` with `docClassification: 'poa'` |\n| `deal.bill_of_sale_approved` | **Deprecated — removal on or after 1 February 2027.** Bill of Sale is fully signed by all required parties. Replaced by `document.completed` with `docClassification: 'bill-of-sale'` |\n\n**Deal event payload:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | string | Deal document ID |\n| `guid` | string | UUID for the deal (e.g. `d30d5242-c880-4534-8c51-0032dde02093`) |\n| `status` | string | Current deal status |\n| `amount` | number | Deal amount in dollars |\n| `buyerId` | string | Buyer's user ID |\n| `sellerId` | string | Seller's user ID |\n| `callerReferenceId` | string \\| null | The `callerReferenceId` you sent on `POST /v2/deal-invites` for the invitation this deal started from. Null when you sent none, and always null for every partner other than the one that set it |\n| `documents` | array | Present on document-upload events only — see below |\n\n> Deal payloads do not carry a `vin`. Fetch `GET /data/deals/:partnerId/:dealId` to obtain the deal's `listingId`, then `GET /data/listings/:partnerId/:listingId` for `vehicle.vin` and the full vehicle spec.\n\n**Document events (`deal.title_submitted`, `deal.title_approved`, `deal.loan_payoff_docs`, `deal.poa_approved`, `deal.bill_of_sale_approved`)** also carry a `documents` array with short-lived signed S3 URLs:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `documents[].filename` | string | Original filename |\n| `documents[].signedUrl` | string | Pre-signed HTTPS URL — fetch within the expiry window |\n| `documents[].expiresAt` | string | ISO 8601 timestamp when the signed URL stops working (4 hours after the event) |\n\nSigned URLs expire 4 hours after the event is emitted. Download and persist the file promptly — if you need the document later, request a fresh event or contact PrivateAuto support.\n\nExample `deal.title_submitted` payload:\n```json\n{\n  \"id\": \"64a1f2e3b5c8d90012345678\",\n  \"eventId\": \"a2f1e9c4b7d8...\",\n  \"eventKey\": \"82f1...:partner-acme:deal.title_submitted:0\",\n  \"entityType\": \"deals\",\n  \"status\": \"active\",\n  \"guid\": \"d30d5242-c880-4534-8c51-0032dde02093\",\n  \"amount\": 18500,\n  \"buyerId\": \"64a1f2e3b5c8d90012340001\",\n  \"sellerId\": \"64a1f2e3b5c8d90012340002\",\n  \"documents\": [\n    {\n      \"filename\": \"title-front.jpg\",\n      \"signedUrl\": \"https://pa-uploads.s3.us-east-2.amazonaws.com/...\",\n      \"expiresAt\": \"2026-04-21T18:00:00.000Z\"\n    },\n    {\n      \"filename\": \"title-back.jpg\",\n      \"signedUrl\": \"https://pa-uploads.s3.us-east-2.amazonaws.com/...\",\n      \"expiresAt\": \"2026-04-21T18:00:00.000Z\"\n    }\n  ]\n}\n```\n\n**`deal.poa_approved` and `deal.bill_of_sale_approved`** are deal-level events carried on the underlying document record. The payload looks different from other deal events:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | string | Document ID (not the deal ID) |\n| `entityType` | string | `documents` for POA; `platoforms_generated_documents` for Bill of Sale |\n| `dealId` | string | Deal this document belongs to — use this to join with your deal records |\n| `status` | string | Document status (`signed` / `completed`) |\n| `docClassification` | string | `poa` or `bill-of-sale` |\n| `documents` | array | Signed S3 URLs for the completed document (same shape as above) |\n\nExample `deal.poa_approved` payload:\n```json\n{\n  \"id\": \"64a1f2e3b5c8d90012349999\",\n  \"entityType\": \"documents\",\n  \"dealId\": \"64a1f2e3b5c8d90012345678\",\n  \"status\": \"signed\",\n  \"docClassification\": \"poa\",\n  \"documents\": [\n    {\n      \"filename\": \"signed_poa.pdf\",\n      \"signedUrl\": \"https://pa-uploads.s3.us-east-2.amazonaws.com/...\",\n      \"expiresAt\": \"2026-04-21T18:00:00.000Z\"\n    }\n  ]\n}\n```\n\n#### Document Events\n\nThese are the **current** per-document signature events. Prefer them over the legacy\ndeal-level `deal.poa_approved` / `deal.bill_of_sale_approved` events, which remain in the\ndeprecation window described under \"Document signing — per-signer detail\".\n\n| Event | When it fires |\n|-------|---------------|\n| `document.signature_added` | One signer completes their slot on a document. Fires once per signer — a 3-signer document (seller + co-seller + buyer) fires it three times |\n| `document.completed` | Every required signer on a document has signed. Fires once per document, regardless of classification |\n| `deal.document_uploaded` | A partner uploads a document to a deal via `POST /data/deals/{partnerId}/{dealId}/documents`. *Not yet available in production — see \"Availability by release\" below.* |\n\nDiscriminate document types by `docClassification` on the payload, **not** by event name.\nBoth events carry the document payload shape documented under `deal.poa_approved` above\n(`id` = document ID, plus `dealId`, `status`, `docClassification`, `documents[]`), and\n`document.signature_added` additionally carries the `signers[]` array.\n\n#### Offer Events\n\n| Event | When it fires |\n|-------|---------------|\n| `offer.created` | Buyer submits an offer |\n| `offer.accepted` | Seller accepts the offer |\n| `offer.rejected` | Seller rejects the offer |\n| `offer.cancelled` | Offer withdrawn by buyer |\n\n**Offer event payload:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | string | Offer document ID |\n| `guid` | string | UUID for the offer (matches the deal guid once a deal is created) |\n| `status` | string | Current offer status |\n| `listingId` | string | Associated listing ID |\n| `amount` | number | Offer amount in dollars |\n| `buyerId` | string | Buyer's user ID |\n| `sellerId` | string | Seller's user ID |\n| `callerReferenceId` | string \\| null | The `callerReferenceId` you sent on `POST /v2/deal-invites` for this invitation. Null when you sent none, and always null for every partner other than the one that set it |\n\n#### Listing Events\n\n| Event | When it fires |\n|-------|---------------|\n| `listing.created` | A new listing is created |\n| `listing.updated` | Listing details edited |\n| `listing.published` | Listing goes live |\n| `listing.sold` | Vehicle marked sold |\n| `listing.deleted` | Listing deactivated or expired |\n| `listing.ownership_set` | Vehicle ownership type set on the listing by an admin/internal path (owned / financed / leased) |\n| `listing.ownership_submitted` | Vehicle ownership type set by a partner/consumer user on the listing flow. Same payload as `listing.ownership_set`; the event name distinguishes the write path, so **subscribe to both** to catch every ownership declaration |\n\n**Listing event payload:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | string | Listing document ID |\n| `status` | string | Current listing status |\n| `vin` | string | Vehicle Identification Number |\n| `year` | number | Vehicle model year |\n| `make` | string | Vehicle make |\n| `model` | string | Vehicle model |\n| `trim` | string | Vehicle trim level |\n| `price` | number | Listing price in dollars |\n| `sellerId` | string | Seller's user ID |\n| `ownershipType` | string | `owned`, `financed`, or `leased` (present when ownership is declared) |\n| `vehicleHaveLien` | boolean | Whether the vehicle has an active lien |\n\n#### User Events\n\n| Event | When it fires |\n|-------|---------------|\n| `user.registered` | A user registers on your branded PrivateAuto site |\n\n**User event payload:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | string | User document ID |\n| `email` | string | User email address |\n| `firstName` | string | User first name |\n| `lastName` | string | User last name |\n\n#### Dealer Events\n\n| Event | When it fires |\n|-------|---------------|\n| `dealer.linked` | Your partner account gained standing to act for a dealership: the first time `POST /dealers/lookup/{partnerId}` returns it, or the first request made with a dealer-approved OAuth credential (one event per location in that dealer group). Both give the same standing, your own credentials included, until PrivateAuto revokes it |\n| `dealer.unlinked` | That standing was revoked. Deals you start afterwards are no longer started for that dealership |\n\nDelivered only to the partner the link belongs to, whatever your `webhookScope` — never to another partner linked to the same dealership. Your own organization is always linked and never produces these events. Looking a dealer up again, or making further requests with the same OAuth credential, does not re-send `dealer.linked`. For OAuth, `linkedAt` is when PrivateAuto first saw the credential used, not when the dealer approved it — WorkOS reports no consent event. *Not yet in production — see \"Availability by release\".*\n\n**Dealer event payload:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | string | Link document ID |\n| `organizationId` | string | PrivateAuto dealership ID |\n| `partnerId` | string | Your partner ID |\n| `via` | string | How the link was made: `dealer-lookup`, `oauth-delegation` or `admin` |\n| `credentialMode` | string | How the request that made the link authenticated — the same values as the v2 credential modes: `hmac`, `api-key`, `m2m`, `oauth` |\n| `clientId` | string \\| null | OAuth links: the WorkOS Connect client the dealer approved |\n| `actingUserId` | string \\| null | OAuth links: the user who approved it |\n| `onBehalfOfOrganization` | string \\| null | OAuth links: the dealer's WorkOS organization. One approval covers the dealer group, so every location in it gets its own link with the same value |\n| `linkedAt` | string | ISO 8601 time the link was created |\n| `unlinkedAt` | string \\| null | ISO 8601 time the link was revoked; `null` while linked |\n| `reason` | string \\| null | Revocation reason, when one was recorded |\n\n### Responding to Webhooks\n\n- Return any `2xx` status to acknowledge receipt.\n- Return `2xx` immediately and process the event asynchronously if your handler is slow.\n- Return `401` for signature failures so PrivateAuto can flag delivery issues.\n\n### UI Trigger Reference\n\nEach partner event is emitted when a specific document change is observed on a Mongo change stream. The columns below name the underlying state change (authoritative — taken from `lambda/trigger-distiller/src/reducers/`) and the user-facing action that produces it. If your testing shows an event is not firing for an action listed here, file a ticket with the specific deal/listing ID — the field-change column is the contract.\n\n#### Deal events\n\n| Event | Mongo trigger | User action |\n|-------|---------------|-------------|\n| `deal.created` | `deals` insert, **or** `status` → `active` from `negotiating` | Buyer accepts an offer (DealNow flow); partner-api `POST /sell/:partnerId` creating a DealNow-pending offer that finalizes into a deal. Fires once per deal either way — a deal that begins life in a pre-acceptance `negotiating` state is not reported until it is accepted, so `deal.created` always means \"a deal you can fetch now exists\" |\n| `deal.completed` | `deals.status` → `sold` | Final closing step (payment acknowledged + title released) |\n| `deal.cancelled` | `deals.status` → `dealCancelled` | Either party cancels the deal from Deal Settings |\n| `deal.expired` | `deals.status` → `dealExpired` | Background expiration job marks a stale deal expired |\n| `deal.offer_accepted` | `deals.buyer.confirmedDate` AND `deals.seller.confirmedDate` both set | Both buyer and seller hit \"Confirm Deal Terms\" on the Offer step. Fires on the write that completes the pair — both timestamps are exposed on the deal response as `buyer.confirmedDate` / `seller.confirmedDate` |\n| `deal.buyer_joined` | `dealState.buyer.status` → `joined` | Buyer signs in, accepts the deal invitation, and lands on the deal |\n| `deal.seller_joined` | `dealState.seller.status` → `joined` | Seller signs in and joins the deal |\n| `deal.buyer_ready` | `dealState.buyer.status` → `readyToClose` | Buyer marks \"Ready to Close\" after completing all required steps |\n| `deal.seller_ready` | `dealState.seller.status` → `readyToClose` | Seller marks \"Ready to Close\" after completing all required steps |\n| `deal.co_seller_invited` | `deals.coSeller.emailTrigger` → `true` | Seller sends a co-seller invitation email. The co-seller block itself is not exposed on the deal response — track this event if you need to know a third signer is coming |\n| `deal.title_submitted` | `buyer.titleConfirmedDate` OR `seller.titleConfirmedDate` set | Either party confirms the title-information step (ownership, registration, lien holder); file uploads may or may not have happened yet. The stamp lands on whichever party the acting user belongs to — in dealer-acquisition (C2D) deals that is usually the **buyer** (the dealer). Fires **once per deal**, on the first confirmation |\n| `deal.title_approved` | `titleAttachment.completedDate` set | Seller marks their uploaded title attachment \"complete\" (clicks Done in the title-attachment modal). Seller-driven, not admin review |\n| `deal.docs_submitted` | `dealState.documentsStatus` → `pending` | Buyer/seller sign all required closing documents, kicking off review |\n| `deal.docs_approved` | `dealState.documentsStatus` → `complete` | Internal/admin reviewer approves the closing document set |\n| `deal.payment_initiated` | `dealState.closingStatus` → `initiated` | Buyer initiates the payment transfer (PrivateAuto Pay) |\n| `deal.payment_acknowledged` | `dealState.closingStatus` → `acknowledged` | Seller acknowledges receipt of payment |\n| `deal.amount_changed` | `payment.privateAutoPay.amount` updated on existing deal | Either party (or admin) adjusts the deal amount after creation; not fired on insert |\n| `deal.negative_equity_identified` | `negativeEquity` set `true` (admin/service path) | Loan payoff acceptance where payoff > PA pay amount (flag stamped by `spinwheel.service` when `manualPayoffInfo.status` → `ACCEPTED`) |\n| `deal.negative_equity_reported` | `negativeEquity` set `true` (user path) | Consumer-facing flow updates `deal.payment.privateAutoPay.amount` and crosses the payoff threshold. Subscribe alongside `deal.negative_equity_identified` — the two paths are mutually exclusive per deal |\n| `deal.negative_equity_funded` | `negativeEquityFunded` set `true` | Negative-equity loan payoff dispatch succeeds |\n| `deal.loan_payoff_docs` | `creditreports.manualPayoffInfo.loanPayoffDocuments` populated | Seller uploads loan payoff documents on the Title step |\n| `deal.loan_payoff_confirmed` | `creditreports.manualPayoffInfo.status` → confirmed | Internal reviewer confirms the loan payoff |\n| `deal.poa_approved` | `documents` (POA) becomes fully signed | All required signers complete Power of Attorney signing |\n| `deal.bill_of_sale_approved` | `platoforms_generated_documents` (BoS) marked complete | Bill of Sale fully signed by all required parties |\n\n#### Offer events\n\n| Event | Mongo trigger | User action |\n|-------|---------------|-------------|\n| `offer.created` | `offers` insert | Buyer submits an offer on a listing; partner-api `POST /sell/:partnerId` creates a DealNow offer |\n| `offer.accepted` | `offers.status` → `accepted` | Seller accepts an offer from the Listing/Offers screen |\n| `offer.rejected` | `offers.status` → `declined` | Seller declines an offer (internal status `declined` → external `rejected`) |\n| `offer.cancelled` | `offers.status` → `deleted` | Buyer withdraws an offer (internal status `deleted` → external `cancelled`) |\n\n#### Listing events\n\n| Event | Mongo trigger | User action |\n|-------|---------------|-------------|\n| `listing.created` | `seller_listings` insert | Seller saves a new listing (initial document insert) |\n| `listing.updated` | `seller_listings` update where no more specific tag matches | Seller edits a listing field that doesn't already trigger a more specific event (i.e. not a status transition, ownership-set, or cash-offer). One Mongo update produces at most one listing event — `listing.updated` is the catch-all for everything else. |\n| `listing.published` | `status` → `live` | Seller hits \"Publish\" on a draft listing |\n| `listing.sold` | `status` → `sold` | Listing marked sold (manual or via accepted DealNow flow) |\n| `listing.deleted` | `status` → `deactivated` or `expired`, OR soft-delete via `deleted: true`, OR physical delete (no `fullDocument` — not delivered) | Seller deactivates a listing, expiration job marks it expired, or admin tools soft-delete the document |\n| `listing.ownership_set` | `ownershipInfo.ownershipType` set/changed (admin/internal path) | Ownership type written by an admin or internal tool. Also fires on insert when ownership is included in the initial document. |\n| `listing.ownership_submitted` | `ownershipInfo.ownershipType` set/changed (user path) | Seller answers the \"Do you own this vehicle outright, finance it, or lease it?\" question on listing setup. Subscribe alongside `listing.ownership_set` — the write path, not the value, decides which of the two fires |\n\n#### Document events\n\n| Event | Mongo trigger | User action |\n|-------|---------------|-------------|\n| `document.signature_added` | `manualSignatures[n].signedAt` set on `documents` or `platoforms_generated_documents` | A signer completes their slot. One event per slot |\n| `document.completed` | All `manualSignatures[]` slots on the document have `signedAt` | The last required signer signs |\n| `deal.document_uploaded` | `documents` insert via the partner upload endpoint | A partner uploads a document to a deal. *Not yet in production — see \"Availability by release\"* |\n\n#### User events\n\n| Event | Mongo trigger | User action |\n|-------|---------------|-------------|\n| `user.registered` | `users` insert with `appRegisteredFrom = <partnerId>` | A user completes registration on your branded PrivateAuto experience |\n\n#### Dealer events\n\n| Event | Mongo trigger | User action |\n|-------|---------------|-------------|\n| `dealer.linked` | `partner_organization_links` insert, or `revokedAt` cleared | A partner looks a dealer up, a dealer-approved OAuth credential is first used, or a revoked link is restored |\n| `dealer.unlinked` | `partner_organization_links.revokedAt` set | A partner's link to a dealership is revoked |\n\n#### Notes for partners diagnosing missing events\n\n- Webhook routing is gated on either `appSource` (the partner who originated the entity) or `organization` linkage (per the partner's `webhookScope` — see admin-api). If neither match holds for a deal/listing/offer, no event will be queued.\n- Each partner has an event subscription list (default: `[\"*\"]`). Events absent from that list are silently dropped before delivery.\n- A change-stream event with no `fullDocument` (i.e. a physical delete) does not produce partner webhooks. Soft-deletes (`deleted: true`) do.\n\n#### Link host policy\n\nAny deal/listing/document URL that PrivateAuto generates for a partner — whether returned by the sell endpoint or embedded in a future webhook payload — uses the `app.` subdomain (`https://app.<host>/...`), never the apex. The host is selected per-partner via the `linkPlatform` config on the partner record:\n\n| `linkPlatform` | Host |\n|----------------|------|\n| `dealnow` (default) | `https://app.${dealNowDomain}` |\n| `pa-app` | `https://app.${appDomain}` |\n\nApex domains (`https://${dealNowDomain}`, `https://${appDomain}`) are reserved for marketing pages and are not partner deep-link targets.\n\n### Webhook → `/data` endpoint cross-reference\n\nWebhook payloads are intentionally compact — they carry the IDs, status fields, and a small set of stable identifiers, but not the full document. To pull the rich shape of a deal, offer, listing, or document, follow the IDs in the payload to a `GET /data/...` endpoint. The response shapes are stable, authoritative, and described in `data-endpoints.md`.\n\nUse the webhook as the **signal**, the `/data` endpoint as the **source of truth**.\n\nThat includes deals you start for a linked dealership (see \"Acting for a linked dealership\" on `POST /sell`): `/data` returns the offers and deals you originated through `/sell` or `/deal-invites` and their documents, with the listings you created or that belong to the dealership, although they belong to the dealership's organization.\n\n| Event family | Payload ID field | Fetch full record from |\n|--------------|------------------|------------------------|\n| `deal.*` | `id` (deal `_id`) | `GET /data/deals/:partnerId/:dealId` → `PartnerDealResponse` |\n| `offer.*` | `id` (offer `_id`); also `listingId` | `GET /data/offers/:partnerId/:offerId`; `GET /data/listings/:partnerId/:listingId` |\n| `listing.*` | `id` (listing `_id`) | `GET /data/listings/:partnerId/:listingId` → `PartnerListingResponse` |\n| `user.registered` | `id` (user `_id`) | _Not exposed via `/data`._ The webhook payload is the only delivery — capture `email/firstName/lastName` from the body. |\n| `deal.*_docs`, `deal.title_*`, `deal.poa_approved`, `deal.bill_of_sale_approved`, `document.*` | `dealId` (plus optional `documentId`) | `GET /data/deals/:partnerId/:dealId/documents` (re-issues fresh 4-hour signed URLs); single-doc fetches via `GET /data/documents/:partnerId/:documentId` or `GET /data/generated-documents/:partnerId/:documentId` |\n| Any delivery — replay/inspect | `eventId` (header `X-PA-Event-Id`) | `GET /data/webhook-deliveries/:partnerId/:logId` returns the dispatched body + attempt metadata. Use `GET /data/webhook-deliveries/:partnerId` (filterable) to find the `logId`. |\n\nPer-event field mapping (which payload field unlocks which `/data` field on the corresponding response DTO):\n\n#### `deal.*` payload → `PartnerDealResponse`\n\n| Payload field | `PartnerDealResponse` field |\n|---------------|------------------------------|\n| `id` | `id` (use as `:dealId`) |\n| `guid` | `guid` |\n| `status` | `status` |\n| `amount` | `payment.privateAutoPay.amount` |\n| `buyerId` | `buyer.id` |\n| `sellerId` | `seller.id` |\n| _(none — not on the payload)_ | `listingId`, `dealState.*`, `seller.organizationId`, `buyer.organizationId`, `payment.*`, `titleApprovedAt`, timestamps. Fetch via `getDeal` to get all. |\n\n#### `offer.*` payload → `PartnerOfferResponse`\n\n| Payload field | `PartnerOfferResponse` field |\n|---------------|-------------------------------|\n| `id` | `id` (use as `:offerId`) |\n| `guid` | `guid` |\n| `status` | `status` |\n| `amount` | `price` |\n| `listingId` | `listingId` (use as `:listingId` on `getListing`) |\n| `buyerId` | `offeredByUserId` |\n| `sellerId` | `offeredToUserId` |\n\n#### `listing.*` payload → `PartnerListingResponse`\n\n| Payload field | `PartnerListingResponse` field |\n|---------------|---------------------------------|\n| `id` | `id` (use as `:listingId`) |\n| `status` | `status` |\n| `vin` | `vehicle.vin` |\n| `year` | `vehicle.year` |\n| `make` | `vehicle.make` |\n| `model` | `vehicle.model` |\n| `trim` | `vehicle.trim` |\n| `price` | `price` |\n| `sellerId` | `sellerId` |\n| `ownershipType` | `ownershipInfo.ownershipType` |\n| `vehicleHaveLien` | `ownershipInfo.vehicleHaveLien` |\n\n#### Document events payload → `PartnerDealDocumentsResponse` / detail DTOs\n\n| Payload field | Where to follow it |\n|---------------|--------------------|\n| `dealId` | `GET /data/deals/:partnerId/:dealId/documents` → full doc set (title + `documents[]` + `generatedDocuments[]`) with fresh signed URLs |\n| `documentId` (when present) | `GET /data/documents/:partnerId/:documentId` (`documents` collection) **or** `GET /data/generated-documents/:partnerId/:documentId` (`platoforms_generated_documents`) — choose by `entityType` on the payload |\n| `docClassification` | Filter on the `/data` response — same vocabulary (`bill-of-sale`, `poa`, etc.) |\n| `documents[].signedUrl` | Short-lived (4h). When expired, re-fetch via the `/data` endpoint above to receive freshly-signed URLs. |\n\n\n### Event sequences by transaction type\n\nHow the events above sequence depends on which side the partner sits on and how the deal originated. The rest of this section walks each shape end-to-end.\n\n#### Workflow type — how PrivateAuto classifies a deal\n\nEvery deal record carries an internal `workflow_type` field derived from the org membership of each party:\n\n| `seller.organizationId` | `buyer.organizationId` | `workflow_type` | Plain-English shape |\n|---|---|---|---|\n| ∅ | ∅ | **C2C** | Consumer sells to consumer (no dealer involved) |\n| ∅ | ✓ | **C2D** | Dealer acquires from a consumer (dealer-acquisition) |\n| ✓ | ∅ | **D2C** | Dealer sells to a consumer (retail) |\n| ✓ | ✓ | **D2D** | Wholesale between two dealers |\n\nPartners always show up on the side that has `organizationId === partner.organizationId`. Deals where the partner org is on **neither** side don't fire any partner webhooks for that partner (org-routed scope) or rely on `appSource` (appSource-routed scope) — see the routing notes at the end of this page.\n\n#### 1. C2D — partner is the buyer (dealer-acquisition)\n\nThe most common partner shape: a dealer integration acquiring a vehicle from a consumer. Two sub-flows depending on entry point:\n\n#### 1a. C2D — partner-initiated via `POST /sell/:partnerId`\n\nThe partner kicks off the flow from their own UI. The seller receives a deep-link to confirm ownership and the rest of the steps happen via the consumer-facing app (or via further partner-api calls).\n\n```\n                    HTTP        Event delivered                Notes\n─────────────────────────────  ────────────────────────────  ──────────────────────────────────\nPOST /sell/:partnerId          listing.created               Stub listing created for the VIN\n                               offer.created                 dealNowPending offer with the\n                                                              partner-org user pre-bound on\n                                                              the buyer side (per PA-4489)\n─────────────────────────────  ────────────────────────────  ──────────────────────────────────\nseller follows seller-link     offer.accepted                dealer + consumer both bound\n(consumer confirms ownership)  deal.created                  deal record materializes\n─────────────────────────────  ────────────────────────────  ──────────────────────────────────\ndocs round (per signer)        document.signature_added      one per manualSignatures slot\nlast signer signs              document.completed            terminal per-doc event\n                               deal.bill_of_sale_approved    (legacy, deprecating; same event\n                                                              filtered to bill-of-sale only)\n─────────────────────────────  ────────────────────────────  ──────────────────────────────────\nadmin reviews & approves docs  deal.docs_approved            dealState.documentsStatus →\n                                                              complete\n─────────────────────────────  ────────────────────────────  ──────────────────────────────────\nPOST /api/deals/start-transfer deal.payment_initiated        buyer (dealer) clicks \"send\n                                                              funds\"\n─────────────────────────────  ────────────────────────────  ──────────────────────────────────\nPOST /api/deals/confirm-       deal.payment_acknowledged     seller (consumer) confirms\n  payment                      deal.completed                receipt; updateTransferDates\n                                                              auto-flips deal.status to 'sold'\n```\n\n**Minimum event subscription** to track this flow: `deal.created`, `document.completed`, `deal.payment_initiated`, `deal.payment_acknowledged`, `deal.completed`. Adding `deal.docs_approved` lets you mirror PA's \"all docs reviewed\" state for buyer-side UI.\n\n#### 1b. C2D — consumer-initiated (in-app)\n\nConsumer lists the vehicle on PrivateAuto, the dealer (your partner-org user) offers via the consumer-facing app, and both parties accept. Webhooks for partners on the **buyer** side:\n\n```\nlisting.created          consumer creates the listing (only if appSource match)\nlisting.published        consumer publishes\noffer.created            dealer submits an offer (offer.appSource matches partner)\noffer.accepted           consumer accepts\ndeal.created             materializes from accepted offer\n{ same docs / payment / completion chain as 1a }\n```\n\nIdentical from `offer.accepted` onward.\n\n#### 2. D2C — partner is the seller\n\nMirror of C2D with the partner on the seller side. Webhooks the partner cares about:\n\n```\nlisting.created              partner (or partner-API) creates the listing\nlisting.published            listing goes live\nlisting.ownership_set OR     ownershipInfo.ownershipType set by admin/internal\n  listing.ownership_submitted ownershipInfo.ownershipType set by partner user\n─────────────────────────────────────────────────────────────────────────────\noffer.created                consumer (buyer) offers\noffer.accepted               partner-side acceptance (or counter-offer chain)\ndeal.created                 deal record materializes\n{ docs round — partner signs Bill of Sale, POA, etc. as the seller }\ndeal.docs_approved\ndeal.payment_initiated       consumer initiates payment\ndeal.payment_acknowledged    partner confirms receipt\ndeal.completed\nlisting.sold                 listing's status flips to 'sold' after deal completes\n```\n\n#### 3. D2D — wholesale between two partner organizations\n\nBoth sides are org users. Each subscribed partner receives webhooks where their org appears on either side. The event set is the same as D2C / C2D but the partner sees BOTH a `listing.published` (seller side) and an `offer.created` (buyer side) for the same deal if they're routing both partners. Dedupe via the deal's `guid`.\n\n#### 4. C2C — pure consumer-to-consumer\n\nPartner webhooks only fire if the offer or deal carries `appSource = <partnerId>` (i.e. the partner branded the originating user experience even though neither party joined the partner's org). Subscribe with **`webhookScope: \"appSource\"`** in your partner config; org-routed partners receive nothing for C2C.\n\n#### Document signing — per-signer detail\n\nThe Bill of Sale and POA (and any other generated document with `manualSignatures`) drive **two new events** per document (and the legacy classifier-specific event during the deprecation window):\n\n```\nmanualSignatures[0].signedAt set    document.signature_added (slot=0, role=seller)\nmanualSignatures[1].signedAt set    document.signature_added (slot=1, role=buyer)\n                                    document.completed       (all signers complete)\n                                    deal.bill_of_sale_approved  (legacy, BoS only)\n                                    deal.poa_approved           (legacy, POA only)\n```\n\nEach `document.signature_added` payload carries:\n\n```json\n{\n  \"id\": \"<documentId>\",\n  \"dealId\": \"<dealId>\",\n  \"docClassification\": \"bill-of-sale\" | \"poa\" | \"addendum\" | …,\n  \"signers\": [{ \"signerRole\": \"seller\" | \"buyer\", \"signedAt\": \"<ISO date>\" }]\n}\n```\n\nIntegrators discriminate document types by `docClassification` rather than by event name — `document.completed` arrives once per document regardless of which classification it carries. The legacy `deal.bill_of_sale_approved` and `deal.poa_approved` events keep firing until **1 February 2027** for backward compatibility; see [Deprecations](#deprecations).\n\n#### Negative-equity events\n\nWhen the consumer side's loan payoff exceeds the offered price:\n\n| User vs admin path | Event | Triggered by |\n|---|---|---|\n| User-side | `deal.negative_equity_reported` | Consumer-facing flow updates `deal.payment.privateAutoPay.amount` and crosses the payoff threshold |\n| Admin/service-side | `deal.negative_equity_identified` | Admin SpinwheelService stamps `negativeEquity: true` |\n\nBoth events carry `negativeEquity: true` on the payload. The event name is the discriminator — no `source` field. Once the negative-equity payoff is dispatched, `deal.negative_equity_funded` fires.\n\n#### Loan payoff document flow\n\nSpecific to deals where the consumer-side seller has an outstanding loan on the vehicle:\n\n```\nseller uploads loan payoff doc  →  deal.loan_payoff_docs       (only the first upload)\ninternal reviewer confirms     →  deal.loan_payoff_confirmed\n```\n\nThe `deal.loan_payoff_docs` event references the underlying `credit_reports` document by id (not the deal id) — fetch the full deal via `getDealDocuments` to see the attached doc.\n\n#### Documents generated per transaction type\n\nWhat appears on a deal — and therefore what signatures and document events you should expect — varies by who's on each side. PrivateAuto generates a different document set depending on whether the parties are consumers, dealers, or a mix. The table below lists the docs you should plan to see; each row is a separate row in `deal.documents[]` (collection: `documents` or `platoforms_generated_documents`) with its own signers and its own `document.signature_added` / `document.completed` / `deal.docs_approved` chain.\n\n| Document | C2C | C2D | D2C | D2D | Notes |\n|---|---|---|---|---|---|\n| **Title attachment** (front / back photos) | ✅ | ✅ | ✅ | ✅ | Seller confirms title info → `deal.title_submitted`; seller uploads photos + marks attachment complete → `deal.title_approved`. Both are seller-driven |\n| **Bill of Sale** (`docClassification: 'bill-of-sale'`) | ✅ | ✅ | ✅ | ✅ | Always generated; both parties sign — fires `document.signature_added` (×2) + `document.completed` (+ legacy `deal.bill_of_sale_approved`) |\n| **Power of Attorney** (`docClassification: 'poa'`) | — | ✅ | ✅ | ✅ | Generated when a dealer is on either side (the dealer signs as buyer-rep / seller-rep). Fires `document.signature_added` per signer + `document.completed` (+ legacy `deal.poa_approved`) |\n| **Loan payoff documents** | seller-lien only | seller-lien only | — | — | Only when the consumer-side seller's vehicle has an outstanding loan. Stored in `credit_reports.manualPayoffInfo.loanPayoffDocuments`; surfaces via `deal.loan_payoff_docs` + `deal.loan_payoff_confirmed` |\n| **Self-inspection photos** | optional | optional | — | — | Buyer-requested third-party inspection; not signed via PrivateAuto, stored as attached photos. No webhook today |\n| **State-specific paperwork** (odometer, lien-release, title application) | varies | varies | varies | varies | Generated as needed based on `deal.state` (US state code). Not surfaced as distinct events; tracked as part of `dealState.documentsStatus` |\n\n#### How docs are linked to a deal\n\n- `deal.documents[]` is an array of references to the `documents` collection (POA + state paperwork + addendum docs).\n- `platoforms_generated_documents.*.sharedDeals[]` references back to the deal(s) the BoS lives on (the BoS can be re-used across co-seller scenarios).\n- Title front/back live on `deal.titleAttachment` (not in `documents` collection).\n- Loan-payoff docs live in `credit_reports.manualPayoffInfo.loanPayoffDocuments` (not in `documents` collection).\n\nWhen you call `GET /data/deals/:partnerId/:dealId/documents`, the response merges all of the above into a single `documents[]` array with fresh 4-hour signed S3 URLs. That's the canonical \"what's on this deal\" endpoint — partners don't need to know the storage split.\n\n#### Co-seller multiplier\n\nWhen `deal.coSeller` is populated, the **Bill of Sale and POA each pick up an extra signer slot** for the co-seller. The signature events still fire once per slot — `document.signature_added` fires three times for a 3-signer document (seller + co-seller + buyer), and `document.completed` fires once when all three have signed. Watch the `signers[]` array on the payload to track who has signed.\n\n#### What's NOT generated\n\n- **No purchase agreement separate from the BoS.** PrivateAuto's BoS template serves as the purchase agreement; states that distinguish the two are handled inside the BoS body.\n- **No financing addendum.** Loan information lives on `credit_reports`, not in a separate signed doc.\n- **No retail-style \"we-owe\" or addendum docs.** These are dealer-CRM concerns, not PrivateAuto deal state.\n\n#### Routing — `webhookScope` summary\n\nHow `partner.webhookScope` affects which of the above events you receive:\n\n| `webhookScope` | Listings | Deals & offers | Documents | Users | Dealer links |\n|---|---|---|---|---|---|\n| `appSource` | Only if `listing.appSource === partnerId` | Only if `offer.appSource === partnerId` or `deal.appSource === partnerId` | Inherits from linked deal's appSource | `user.registered` only when `user.appRegisteredFrom === partnerId` | Your own links only |\n| `organization` | Listing owner is in `partner.organizationId` (not a listing you created for a linked dealership) | Either side of the deal is in `partner.organizationId`. Not deals you start for a linked dealership: those carry the dealer's org, so they reach you only with `appSource` or `both` | Linked deal's seller or buyer is in `partner.organizationId` | User's `userDetails.organizationId === partner.organizationId` | Your own links only |\n| `both` (default) | Either of the above matches | Either of the above matches | Either of the above matches | Either of the above matches | Your own links only |\n\n> If listings / documents / `user.registered` events aren't firing on `webhookScope=organization`, the cause is almost always that the source user / document has no org link populated. See the gotcha box in [`webhooks.md`](./webhooks.md#organization-scope-gotchas) for the conditional-routing matrix.\n\n#### What you should write in your integration to be future-proof\n\n1. **Subscribe to events by name, not order.** Multiple events can land in the same Mongo change-stream tick (e.g. `offer.accepted` + `deal.created`). Process by name; treat sequence as informational.\n2. **Dedupe on `eventId`.** The same partner webhook will retry on transient delivery failures; `eventId` is stable per (resume token, partner, event, emission index) so you can safely treat it as an idempotency key.\n3. **Always fetch full state from `/data/...` endpoints** if you need anything beyond what the webhook payload exposes — payloads are intentionally compact and stable; full DTOs are the place to read.\n4. **Migrate off the legacy document events before 1 February 2027.** `deal.bill_of_sale_approved` and `deal.poa_approved` are deprecated in favour of `document.completed` + `docClassification`. Until the removal date you receive **both**, so migrating early costs you nothing but duplicate deliveries you can ignore. Subscribing to `document.*` is forward-compatible; subscribing only to the legacy names will go silent on removal. See [Deprecations](#deprecations).\n5. **Treat absent events as legitimately absent**, not as failures. The dealer-acquisition flow doesn't pass through `offer.accepted` in some lifecycle shapes; the user-driven path skips `MARK_SOLD` because the seller's `confirm-payment` call writes `status='sold'` directly. The event catalog tells you what `can` fire, not what `must`.\n\n### Deprecations\n\nDeprecated surfaces keep working until their removal date. Nothing is removed without a date\npublished here first, and dates only ever move outward.\n\n| Surface | Kind | Replacement | Removal on or after |\n|---|---|---|---|\n| `deal.poa_approved` | Event | `document.completed` where `docClassification === 'poa'` | **1 February 2027** |\n| `deal.bill_of_sale_approved` | Event | `document.completed` where `docClassification === 'bill-of-sale'` | **1 February 2027** |\n\nBoth legacy events fire **in addition to** their replacements today, so you can migrate at any\npoint before the removal date and simply ignore the duplicates in the meantime. After removal,\nonly the `document.*` events fire.\n\n**Migrating:** subscribe to `document.signature_added` and `document.completed` (or the\n`document.*` wildcard), then branch on `docClassification` instead of on the event name. The\nreplacement events are strictly richer — they fire per document rather than per classification,\ncarry the `signers[]` array, and cover document types the legacy pair never had an event for.\n\n### Availability by release\n\nThe partner API contract is **frozen at v1 and additive-only**: fields, endpoints, and events\nare added over time, but nothing documented here is renamed, retyped, or removed without a new\nmajor version. That means this reference is always a **superset** of what any given environment\nis serving — everything it documents that your environment has, it documents correctly.\n\n**Check what you're running:** `GET /api/docs-json` returns the live spec for the environment\nyou're pointed at, and its `info.description` opens with the deployed build version\n(`YYYY.MMDD.BUILD-SHA`). The OpenAPI schema returned there is authoritative for your\nenvironment; this page is authoritative for the contract.\n\nThe following are documented above but **not yet in production** (`2026.603.1516-aca8c42`):\n\n| Addition | Kind | Available in |\n|---|---|---|\n| `deal.document_uploaded` | Event | Not yet released |\n| `POST /data/deals/{partnerId}/{dealId}/documents` | Endpoint | Not yet released |\n| `DELETE /data/documents/{partnerId}/{documentId}` | Endpoint | Not yet released |\n| `GET /sell/{partnerId}/widget` | Endpoint | Not yet released |\n| `PartnerDealResponse.dealStateCurrent` | Field | Not yet released |\n| `InitiateDealNow.contingencies` / `.customConditions` / `.customMessage` / `.expirationDate` | Request fields | Not yet released |\n| `dealer.linked`, `dealer.unlinked` | Event | Not yet released |\n\nEverything else on this page is live in production today.\n\n> **Integration guidance:** treat unknown fields and unknown event names as ignorable rather\n> than as errors. Because the contract is additive-only, an integration that tolerates\n> additions never needs a coordinated upgrade when PrivateAuto ships.\n",
    "version": "1.0.0",
    "contact": {}
  },
  "tags": [
    {
      "name": "sell",
      "description": "DealNow deal initiation — redirect a prospect into a PrivateAuto deal or create one programmatically"
    },
    {
      "name": "leads",
      "description": "Lead ingestion — submit and look up leads for dealer organizations on your partner allowlist. POST is idempotent via `callerReferenceId` and subject to per-partner rate limits."
    },
    {
      "name": "dealer-lookup",
      "description": "Resolve a PrivateAuto user's email to the dealership ids they belong to — any dealer on PrivateAuto, not only those on your partner allowlist. Requires the `dealers:lookup` permission."
    }
  ],
  "servers": [],
  "components": {
    "securitySchemes": {
      "bearer": {
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "type": "http"
      }
    },
    "schemas": {
      "PartnerDealPartyV1": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "6a0243d9a30d4d0026d00e7c",
            "nullable": true
          },
          "organizationId": {
            "type": "string",
            "example": "67e446a09d2eb254a3b130e7",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "invited",
              "joined",
              "readyToClose"
            ],
            "nullable": true,
            "description": "Party progression within the deal state machine"
          },
          "titleConfirmedDate": {
            "type": "string",
            "format": "date-time",
            "description": "When this party confirmed the title-information step. Written directly on the Deal subdoc, on whichever party the **acting user** belongs to — not on a fixed role. In dealer-acquisition (C2D) deals the dealer is the buyer and typically drives this step, so in production this is set on `buyer` far more often than on `seller` (2656 vs 37 across 4088 deals). Despite the `Date` suffix it is not the legacy sibling of `titleConfirmedAt` — the two are written by different code paths. **Poll this field rather than relying on the `deal.title_submitted` webhook**, which only fires on the `seller` side and so misses most deals.",
            "nullable": true
          },
          "confirmedDate": {
            "type": "string",
            "format": "date-time",
            "description": "Legacy party-join timestamp on the Deal subdoc. For event-driven state, prefer `infoCompletedAt`.",
            "nullable": true
          },
          "infoCompletedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Deal-state machine: when party info was validated (`BUYER_INFO_COMPLETED` / `SELLER_INFO_COMPLETED`).",
            "nullable": true
          },
          "termsConfirmedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Deal-state machine: when party confirmed deal terms.",
            "nullable": true
          },
          "paymentConfirmedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Deal-state machine: when payment was confirmed (seller-only today).",
            "nullable": true
          },
          "titleConfirmedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Deal-state machine: when title was confirmed by this party (`BUYER_TITLE_OK` / `SELLER_TITLE_OK`). Sourced from the deal-state reducer. **No webhook fires on this field** — the `deal.title_submitted` event is driven by `titleConfirmedDate` instead.",
            "nullable": true
          },
          "servicesConfirmedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Deal-state machine: when this party confirmed the optional add-on services step (inspection, shipping, title service and similar). Populated in production — 181 buyer / 135 seller across 4088 deals — but it drives no webhook and no documented deal-page step, so poll it if you need it.",
            "nullable": true
          },
          "titleSubmittedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When this party submitted the vehicle title (front + back photos uploaded and finalized). Title submission is a seller action, so this is populated on the `seller` block and null on `buyer`. Same value as the top-level `titleApprovedAt`, sourced from `listing.titleAttachment.completedDate`.",
            "nullable": true
          }
        },
        "required": [
          "id",
          "organizationId",
          "status"
        ]
      },
      "PartnerPrivateAutoPayAllocationV1": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "number",
            "description": "Amount in dollars",
            "nullable": true
          },
          "transferDate": {
            "type": "string",
            "format": "date-time",
            "description": "When the transfer was initiated",
            "nullable": true
          },
          "checkDelivery": {
            "type": "string",
            "enum": [
              "pickup",
              "mail",
              null
            ],
            "description": "Check delivery preference when the payout is a paper check",
            "nullable": true
          },
          "payoutSourceType": {
            "type": "string",
            "enum": [
              "wallet",
              "bank",
              "check",
              "external",
              null
            ],
            "description": "How the payout will be / was disbursed",
            "nullable": true
          }
        }
      },
      "PartnerPaymentAllocationV1": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "number",
            "description": "Amount in dollars",
            "nullable": true
          },
          "transferDate": {
            "type": "string",
            "format": "date-time",
            "description": "When the transfer was initiated",
            "nullable": true
          }
        }
      },
      "PartnerCryptoPaymentV1": {
        "type": "object",
        "properties": {
          "btc": {
            "description": "Bitcoin payment allocation",
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/PartnerPaymentAllocationV1"
              }
            ]
          }
        }
      },
      "PartnerPaymentV1": {
        "type": "object",
        "properties": {
          "privateAutoPay": {
            "description": "PrivateAuto Pay (managed escrow) allocation — internal payout IDs are intentionally not exposed",
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/PartnerPrivateAutoPayAllocationV1"
              }
            ]
          },
          "cash": {
            "description": "Cash allocation — what the buyer is paying outside PrivateAuto Pay",
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/PartnerPaymentAllocationV1"
              }
            ]
          },
          "loan": {
            "description": "Buyer financing allocation — amount disbursed via an external loan",
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/PartnerPaymentAllocationV1"
              }
            ]
          },
          "crypto": {
            "description": "Crypto payment block. `btc` is the only currency today and is a **fixed key**, not a map — read `crypto.btc` directly rather than iterating. Any future currency arrives as an additional named sibling key, which is additive and will not move `btc`.",
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/PartnerCryptoPaymentV1"
              }
            ]
          }
        }
      },
      "PartnerDealDocumentRefV1": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Mongo _id of the documents-collection entry"
          },
          "status": {
            "type": "string",
            "description": "Document lifecycle status (e.g. pending, signed, void)",
            "nullable": true
          },
          "docClassification": {
            "type": "string",
            "description": "Document classification (e.g. poa, bill-of-sale, other)",
            "nullable": true
          }
        },
        "required": [
          "id"
        ]
      },
      "PartnerDealStateBlockV1": {
        "type": "object",
        "properties": {
          "documentsStatus": {
            "type": "string",
            "enum": [
              "empty",
              "pending",
              "complete",
              null
            ],
            "nullable": true
          }
        }
      },
      "PartnerLoanPayoffDocumentV1": {
        "type": "object",
        "properties": {
          "fileUrl": {
            "type": "string",
            "description": "Short-lived signed URL for the loan payoff document. Same signing and expiry as every other document URL in this API — download promptly rather than storing the URL."
          },
          "filename": {
            "type": "string",
            "description": "Original file name, derived from the stored object key",
            "nullable": true
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "description": "When `fileUrl` stops working. Request the deal again for a fresh URL.",
            "nullable": true
          }
        },
        "required": [
          "fileUrl"
        ]
      },
      "PartnerDealStatusHistoryEntryV1": {
        "type": "object",
        "properties": {
          "value": {
            "type": "string",
            "description": "New status value",
            "nullable": true
          },
          "previous": {
            "type": "string",
            "description": "Previous status value (null on the first transition / deal creation)",
            "nullable": true
          },
          "date": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "PartnerDealResponseV1": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "6a0243d9a30d4d0026d00e7c"
          },
          "guid": {
            "type": "string",
            "description": "Stable cross-system deal identifier — safe to log and dedupe on",
            "example": "653a905c-73b2-4e4b-bdf6-0e25b1e71363",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "cancelled",
              "sold",
              "expired",
              "pending"
            ],
            "description": "Deal status. Allow-list guarded (see deal-status.ts): any internal status outside the documented set maps to null rather than leaking onto the contract.",
            "nullable": true
          },
          "closingStatus": {
            "type": "string",
            "enum": [
              "none",
              "ready",
              "initiated",
              "acknowledged",
              null
            ],
            "description": "Funds-movement substate within an active deal. `none` → `ready` (both parties ready to close and all documents complete, payment not yet initiated) → `initiated` (buyer started the transfer) → `acknowledged` (seller confirmed receipt). `ready` is transient and rarely observed — deals typically move straight to `initiated`.",
            "nullable": true
          },
          "closingFeePayer": {
            "type": "string",
            "enum": [
              "buyer",
              "seller",
              "split"
            ],
            "nullable": true
          },
          "state": {
            "type": "string",
            "description": "US state code for the transaction (e.g. `UT`, `TX`) — a **geographic** field, despite sitting alongside `status`, `closingStatus` and `dealState`. Not a workflow state. Synced from the listing's registered state when a party confirms title.",
            "example": "UT",
            "nullable": true
          },
          "odometer": {
            "type": "string",
            "description": "Odometer reading recorded at closing, as entered on the deal. Free-text **string**, not a number — it is captured verbatim from the closing form and is not normalised or validated, so expect values like \"125,000\" or \"125000 mi\". Distinct from `vehicle.mileage` on the listing response, which is the numeric reading at listing time: this is the closing figure and the listing is the advertised figure. Where they disagree, this one is the later value.",
            "nullable": true
          },
          "appSource": {
            "type": "string",
            "description": "Originating partner integration identifier (matches partner config)",
            "nullable": true
          },
          "listingId": {
            "type": "string",
            "description": "Listing the deal originated from",
            "nullable": true
          },
          "offerId": {
            "type": "string",
            "description": "Most-recent offer pointing at this deal (offer.deal = deal._id, newest-first). Matches the `dealId` returned by POST /sell/:partnerId, which is actually the offer _id.",
            "nullable": true
          },
          "currentOfferStatus": {
            "type": "string",
            "enum": [
              "pending",
              "accepted",
              "declined",
              "countered",
              "deleted",
              null
            ],
            "description": "Status of the most-recent offer on this deal (the offer referenced by `offerId`), surfaced inline so partners can read disposition without a separate GET /offers call. Internal `dealNowPending` is collapsed to `pending`, matching the /offers endpoint; any status outside the documented set maps to null. Distinct from the top-level `status` field, which is the deal status.",
            "nullable": true
          },
          "documentsStatus": {
            "type": "string",
            "enum": [
              "empty",
              "pending",
              "complete",
              null
            ],
            "description": "Aggregate documents-required progression",
            "nullable": true
          },
          "dealStateCurrent": {
            "type": "boolean",
            "description": "_Added after the `2026.603.1516` production release — not yet serving production traffic._ Freshness of the event-sourced `dealState` mirror. The status/progression fields in this response are computed authoritatively from the deal on read (the same reducer the async materializer runs). This flag reports whether the stored `dealState` mirror already agreed with that authoritative recompute: true = in sync; false = the mirror was stale and this response reflects the authoritative values ahead of the mirror; null = not evaluated (list responses do not recompute per-deal). Scope: the comparison covers the STATUS fields only — `closingStatus`, `documentsStatus`, `buyer.status`, `seller.status` — not the dealState timestamp fields, which the reducer re-stamps on every recompute and so cannot be compared meaningfully on read.",
            "nullable": true
          },
          "negativeEquity": {
            "type": "boolean",
            "description": "True when the loan payoff exceeds the PrivateAuto Pay amount. Reported from the stored deal flag OR derived live from the credit report (payoff status accepted-or-later and manualPayoffInfo.payoffAmount > payment.privateAutoPay.amount) — whichever indicates true. Derivation covers historical deals whose stored flag was never stamped (PA-4598).",
            "nullable": true
          },
          "negativeEquityFunded": {
            "type": "boolean",
            "description": "True once the negative-equity payoff has been dispatched",
            "nullable": true
          },
          "amount": {
            "type": "number",
            "description": "PrivateAuto Pay amount in dollars",
            "nullable": true
          },
          "currency": {
            "type": "string",
            "default": "USD",
            "nullable": true
          },
          "buyer": {
            "$ref": "#/components/schemas/PartnerDealPartyV1"
          },
          "seller": {
            "$ref": "#/components/schemas/PartnerDealPartyV1"
          },
          "payment": {
            "description": "Full payment block — privateAutoPay / cash / loan / crypto allocations. Internal payout routing IDs (payoutFinancialAccountId, payoutFundingSourceId, payoutTransactionId, payoutPlaidPendingVerification) are intentionally excluded.",
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/PartnerPaymentV1"
              }
            ]
          },
          "documents": {
            "description": "Merged summary of every document attached to the deal — both uploaded references (POA, addendum, state-specific paperwork) and platoform-generated documents (e.g. Bill of Sale) are folded into this single array, each with status and classification. This is a lightweight summary: signed URLs and signer detail are NOT included here, and the two sources are not split out. For the richer per-source view (separate `documents` vs `generatedDocuments`, with signers and signed URLs) call GET /data/deals/:partnerId/:dealId/documents, or GET /data/documents/:partnerId/:documentId for a single doc.",
            "nullable": true,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerDealDocumentRefV1"
            }
          },
          "dealState": {
            "description": "Back-compat: mirrors `documentsStatus` only. Other state fields are now top-level.",
            "allOf": [
              {
                "$ref": "#/components/schemas/PartnerDealStateBlockV1"
              }
            ]
          },
          "titleApprovedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the seller marked their title attachment complete (front + back photos uploaded and finalized). Seller-driven action, not an admin/reviewer signoff. Sourced from the listing (`listing.titleAttachment.completedDate`), where the seller upload writes it. This is the poll target for the `deal.title_approved` webhook event — non-null means the seller has confirmed the title attachment.",
            "nullable": true
          },
          "ownershipType": {
            "type": "string",
            "enum": [
              "owned",
              "financed",
              "leased",
              null
            ],
            "description": "Seller's self-declared ownership status from the source listing (`listings.ownershipInfo.ownershipType`). Captures seller intent at listing time; see `payoffType` for the value confirmed by the lender during the payoff workflow. These can disagree — `ownershipType` reflects what the seller said, `payoffType` reflects what the bank data shows.",
            "nullable": true
          },
          "payoffType": {
            "type": "string",
            "enum": [
              "LOAN",
              "LEASE",
              null
            ],
            "description": "Transaction classification confirmed during the credit-report / payoff workflow (`credit_reports.payoffType`). Null when no credit report has been pulled. Set independently of the seller-declared `ownershipType`; the two can diverge. Note the **upper-case** values — this enum comes from the credit-report provider and is stored verbatim, unlike the lower-case/kebab vocabularies elsewhere in this API. Compare case-sensitively.",
            "nullable": true
          },
          "loanPayoffDocs": {
            "description": "Loan payoff documents uploaded by the buyer for this deal. Sourced from `credit_reports.manualPayoffInfo.loanPayoffDocuments` joined by dealId.",
            "nullable": true,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerLoanPayoffDocumentV1"
            }
          },
          "loanPayoffConfirmed": {
            "type": "boolean",
            "description": "True once the loan payoff has been confirmed by the lender (`credit_reports.manualPayoffInfo.status === \"CONFIRMED\"`). Null when no credit report or no manualPayoffInfo.status is set.",
            "nullable": true
          },
          "statusHistory": {
            "description": "Append-only audit trail of `deal.status` transitions (value, previous, date)",
            "nullable": true,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerDealStatusHistoryEntryV1"
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "id",
          "guid",
          "status",
          "buyer",
          "seller",
          "dealState"
        ]
      },
      "PartnerOfferResponseV1": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "6a0243d8a30d4d0026d00e7a"
          },
          "guid": {
            "type": "string",
            "description": "Stable cross-system offer identifier — safe to log and dedupe on",
            "example": "653a905c-73b2-4e4b-bdf6-0e25b1e71363",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "accepted",
              "declined",
              "countered",
              "deleted"
            ],
            "nullable": true
          },
          "price": {
            "type": "number",
            "description": "Offered price in dollars",
            "nullable": true
          },
          "currency": {
            "type": "string",
            "default": "USD",
            "nullable": true
          },
          "listingId": {
            "type": "string",
            "nullable": true
          },
          "offeredByUserId": {
            "type": "string",
            "nullable": true
          },
          "offeredByOrganizationId": {
            "type": "string",
            "nullable": true
          },
          "offeredToUserId": {
            "type": "string",
            "nullable": true
          },
          "offeredToOrganizationId": {
            "type": "string",
            "nullable": true
          },
          "externalId": {
            "type": "string",
            "description": "Partner-provided opaque offer reference",
            "nullable": true
          },
          "buyerExternalId": {
            "type": "string",
            "nullable": true
          },
          "sellerExternalId": {
            "type": "string",
            "nullable": true
          },
          "appSource": {
            "type": "string",
            "nullable": true
          },
          "dealNowExpiration": {
            "type": "string",
            "format": "date-time",
            "description": "DealNow link expiration time",
            "nullable": true
          },
          "titleDeliveryMethod": {
            "type": "string",
            "enum": [
              "InPerson",
              "Transport",
              "Mail",
              "VehicleTransport",
              "MailService",
              "PurchaseTitleService",
              "ReleasedAndDelivered",
              null
            ],
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "id",
          "guid",
          "status"
        ]
      },
      "PartnerVehicleV1": {
        "type": "object",
        "properties": {
          "year": {
            "type": "number",
            "description": "Registration year",
            "nullable": true
          },
          "make": {
            "type": "string",
            "description": "Manufacturer (CarMake)",
            "nullable": true
          },
          "model": {
            "type": "string",
            "description": "Model name (CarModel)",
            "nullable": true
          },
          "trim": {
            "type": "string",
            "description": "Trim level",
            "nullable": true
          },
          "vin": {
            "type": "string",
            "description": "17-character VIN (sourced from listing.vinNumber, uppercase-normalized at write time)",
            "nullable": true,
            "example": "WBA3B9C59FJ466190"
          },
          "bodyStyle": {
            "type": "string",
            "description": "Body style — sedan, SUV, coupe, etc.",
            "nullable": true
          },
          "mileage": {
            "type": "number",
            "description": "Odometer reading at listing time",
            "nullable": true
          },
          "exteriorColor": {
            "type": "string",
            "description": "Exterior color",
            "nullable": true
          },
          "interiorColor": {
            "type": "string",
            "description": "Interior color",
            "nullable": true
          },
          "transmission": {
            "type": "string",
            "description": "Transmission type",
            "nullable": true
          },
          "driveType": {
            "type": "string",
            "description": "Drive type (FWD, AWD, etc.)",
            "nullable": true
          },
          "fuel": {
            "type": "string",
            "description": "Fuel type",
            "nullable": true
          },
          "cylinders": {
            "type": "string",
            "description": "Cylinder count",
            "nullable": true
          }
        }
      },
      "PartnerOwnershipInfoV1": {
        "type": "object",
        "properties": {
          "ownershipType": {
            "type": "string",
            "enum": [
              "owned",
              "financed",
              "leased",
              null
            ],
            "description": "Seller's self-declared ownership status. Same value and vocabulary as `PartnerDealResponse.ownershipType` — the deal response sources it from this listing field.",
            "nullable": true
          },
          "vehicleHaveLien": {
            "type": "boolean",
            "nullable": true
          }
        }
      },
      "PartnerListingResponseV1": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "6a024361a30d4d0026d00db2"
          },
          "listingNo": {
            "type": "string",
            "description": "Public listing number (e.g. used in URLs)",
            "nullable": true
          },
          "slug": {
            "type": "string",
            "description": "URL slug for the listing on privateauto.com",
            "nullable": true
          },
          "title": {
            "type": "string",
            "description": "Listing title text",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "live",
              "sold",
              "deactivated",
              "expired"
            ],
            "nullable": true
          },
          "sellerId": {
            "type": "string",
            "nullable": true
          },
          "organizationId": {
            "type": "string",
            "nullable": true
          },
          "price": {
            "type": "number",
            "description": "Asking price in dollars",
            "nullable": true
          },
          "vehicle": {
            "$ref": "#/components/schemas/PartnerVehicleV1"
          },
          "ownershipInfo": {
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/PartnerOwnershipInfoV1"
              }
            ]
          },
          "condition": {
            "type": "string",
            "description": "Listing condition — seller's characterisation of the vehicle's overall state.",
            "enum": [
              "new",
              "used"
            ],
            "nullable": true
          },
          "appSource": {
            "type": "string",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "id",
          "status",
          "vehicle"
        ]
      },
      "PartnerWebhookDeliveryResponseV1": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "partnerId": {
            "type": "string",
            "nullable": true
          },
          "event": {
            "type": "string",
            "description": "Event name as sent in the X-PA-Event header",
            "example": "deal.created",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "delivered",
              "failed",
              "pending",
              "retrying",
              null
            ],
            "nullable": true
          },
          "url": {
            "type": "string",
            "description": "Target webhook URL",
            "nullable": true
          },
          "statusCode": {
            "type": "number",
            "description": "HTTP status code returned by partner",
            "nullable": true
          },
          "attemptedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "responseBodyExcerpt": {
            "type": "string",
            "description": "Truncated excerpt of the partner's HTTP response body",
            "nullable": true
          },
          "error": {
            "type": "string",
            "description": "Error message when status=failed",
            "nullable": true
          },
          "payload": {
            "type": "object",
            "description": "The exact payload that was sent to the partner endpoint",
            "additionalProperties": true,
            "nullable": true
          }
        },
        "required": [
          "id"
        ]
      },
      "ListMetaV1": {
        "type": "object",
        "properties": {
          "page": {
            "type": "number",
            "description": "Zero-based page index"
          },
          "limit": {
            "type": "number",
            "description": "Page size"
          },
          "total": {
            "type": "number",
            "description": "Total matching records"
          },
          "hasMore": {
            "type": "boolean"
          }
        },
        "required": [
          "page",
          "limit",
          "total",
          "hasMore"
        ]
      },
      "PartnerDealListResponseV1": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerDealResponseV1"
            }
          },
          "_meta": {
            "$ref": "#/components/schemas/ListMetaV1"
          }
        },
        "required": [
          "data",
          "_meta"
        ]
      },
      "PartnerOfferListResponseV1": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerOfferResponseV1"
            }
          },
          "_meta": {
            "$ref": "#/components/schemas/ListMetaV1"
          }
        },
        "required": [
          "data",
          "_meta"
        ]
      },
      "PartnerListingListResponseV1": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerListingResponseV1"
            }
          },
          "_meta": {
            "$ref": "#/components/schemas/ListMetaV1"
          }
        },
        "required": [
          "data",
          "_meta"
        ]
      },
      "PartnerWebhookDeliveryListResponseV1": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerWebhookDeliveryResponseV1"
            }
          },
          "_meta": {
            "$ref": "#/components/schemas/ListMetaV1"
          }
        },
        "required": [
          "data",
          "_meta"
        ]
      },
      "PartnerDealRefV1": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "guid": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "id"
        ]
      },
      "PartnerSignedDocumentV1": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "description": "S3 object key",
            "nullable": true
          },
          "url": {
            "type": "string",
            "description": "4-hour pre-signed S3 URL",
            "nullable": true
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "key",
          "url",
          "expiresAt"
        ]
      },
      "PartnerDealDocumentSignerV1": {
        "type": "object",
        "properties": {
          "signerRole": {
            "type": "string",
            "enum": [
              "seller",
              "buyer",
              "coSeller",
              null
            ],
            "nullable": true
          },
          "signedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "PartnerDealDocumentRowV1": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "docClassification": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "nullable": true
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "Display name (set on Platoforms-generated docs; null for CardinalGray)"
          },
          "signers": {
            "nullable": true,
            "description": "Per-role signature progress from the doc's manualSignatures[] array. Absent on inline list-path responses; fetch full signer detail via GET /data/deals/:partnerId/:dealId/documents.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerDealDocumentSignerV1"
            }
          },
          "signed": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerSignedDocumentV1"
            }
          }
        },
        "required": [
          "id",
          "signed"
        ]
      },
      "PartnerDealDocumentsResponseV1": {
        "type": "object",
        "properties": {
          "deal": {
            "$ref": "#/components/schemas/PartnerDealRefV1"
          },
          "title": {
            "description": "Title attachment (front + back if present)",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerSignedDocumentV1"
            }
          },
          "documents": {
            "description": "Merged document set: `documents` collection rows (CardinalGray, e.g. POA) and `platoforms_generated_documents` rows (e.g. Bill of Sale) returned in a single array. Disambiguate via `docClassification`. **Breaking change (2026-05-20):** the previous `generatedDocuments[]` array has been removed; its rows now appear here.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerDealDocumentRowV1"
            }
          }
        },
        "required": [
          "deal",
          "title",
          "documents"
        ]
      },
      "PartnerDocumentDetailResponseV1": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "dealId": {
            "type": "string",
            "nullable": true
          },
          "docClassification": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "nullable": true
          },
          "signers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerDealDocumentSignerV1"
            }
          },
          "signed": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerSignedDocumentV1"
            }
          }
        },
        "required": [
          "id",
          "dealId",
          "signers",
          "signed"
        ]
      },
      "PartnerGeneratedDocumentDetailResponseV1": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "docClassification": {
            "type": "string",
            "nullable": true
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "signers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerDealDocumentSignerV1"
            }
          },
          "signed": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PartnerSignedDocumentV1"
            }
          }
        },
        "required": [
          "id",
          "signers",
          "signed"
        ]
      },
      "PartnerDocumentUploadV1Dto": {
        "type": "object",
        "properties": {
          "file": {
            "type": "string",
            "format": "binary",
            "description": "The document file (multipart field `file`)"
          },
          "documentType": {
            "type": "string",
            "enum": [
              "signed_title",
              "lien_release",
              "payoff_letter",
              "power_of_attorney",
              "disclosure",
              "other"
            ],
            "description": "Document classification"
          },
          "callerReferenceId": {
            "type": "string",
            "description": "Your own identifier for this upload — unique across ALL your uploads (namespace it, e.g. embed your deal/order id). Enables idempotent retry."
          },
          "description": {
            "type": "string",
            "description": "Free-text label surfaced in the deal UI and read endpoints"
          }
        },
        "required": [
          "file",
          "documentType",
          "callerReferenceId"
        ]
      },
      "PartnerDocumentUploadResponseV1": {
        "type": "object",
        "properties": {
          "documentId": {
            "type": "string"
          },
          "duplicate": {
            "type": "boolean",
            "nullable": true,
            "description": "Present only on an idempotent replay"
          },
          "dealId": {
            "type": "string",
            "nullable": true
          },
          "documentType": {
            "type": "string",
            "enum": [
              "signed_title",
              "lien_release",
              "payoff_letter",
              "power_of_attorney",
              "disclosure",
              "other"
            ]
          },
          "callerReferenceId": {
            "type": "string"
          },
          "uploadedVia": {
            "type": "string",
            "description": "'party' | 'marketplace' — which scope authorized the write"
          },
          "status": {
            "type": "string",
            "description": "pending-scan | available | quarantined | voided | superseded"
          },
          "contentType": {
            "type": "string",
            "nullable": true
          },
          "sizeBytes": {
            "type": "number",
            "nullable": true
          },
          "sha256": {
            "type": "string",
            "nullable": true
          },
          "url": {
            "type": "string",
            "nullable": true,
            "description": "4-hour pre-signed URL. Withheld (null) until status is `available`."
          },
          "urlExpiresAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "documentId",
          "dealId",
          "documentType",
          "callerReferenceId",
          "uploadedVia",
          "status",
          "contentType",
          "sizeBytes",
          "sha256",
          "createdAt"
        ]
      },
      "InitiateDealNowV1Dto": {
        "type": "object",
        "properties": {
          "vin": {
            "type": "string",
            "description": "Vehicle Identification Number (17 characters)",
            "example": "1HGBH41JXMN109186"
          },
          "buyerName": {
            "type": "string",
            "description": "Buyer full name",
            "example": "Jane Smith"
          },
          "buyerEmail": {
            "type": "string",
            "description": "Buyer email address. Convention: this field describes the OTHER party — the side being invited via the deal link. If your integration is on the buyer side, do NOT pass your own email here; pass the seller's email in `sellerEmail` instead. The supplied email determines which `dealNowType` is inferred for the resulting offer.",
            "example": "buyer@example.com"
          },
          "buyerSendLink": {
            "type": "boolean",
            "description": "If true, emails the buyer their deal link (requires buyerEmail)"
          },
          "sellerName": {
            "type": "string",
            "description": "Seller full name",
            "example": "John Doe"
          },
          "sellerEmail": {
            "type": "string",
            "description": "Seller email address. Same convention as `buyerEmail`: this is the OTHER party from the partner. If your integration is on the seller side, do NOT pass your own email here.",
            "example": "seller@example.com"
          },
          "sellerSendLink": {
            "type": "boolean",
            "description": "If true, emails the seller their deal link (requires sellerEmail)"
          },
          "year": {
            "type": "number",
            "description": "Vehicle model year. Required unless this VIN is already listed under your account.",
            "example": 2021
          },
          "make": {
            "type": "string",
            "description": "Vehicle make. Required unless this VIN is already listed under your account.",
            "example": "Honda"
          },
          "model": {
            "type": "string",
            "description": "Vehicle model. Required unless this VIN is already listed under your account.",
            "example": "Civic"
          },
          "trim": {
            "type": "string",
            "description": "Vehicle trim level",
            "example": "EX"
          },
          "amount": {
            "type": "number",
            "description": "Deal amount in dollars",
            "example": 18500
          },
          "expirationDate": {
            "type": "string",
            "description": "Offer expiration as an ISO 8601 date/time. Must be in the future. Persisted to offer.expirationDate.",
            "example": "2026-08-01T00:00:00.000Z"
          },
          "contingencies": {
            "type": "array",
            "description": "Offer contingencies as an array of enum values. Each maps to a backing Offer boolean.",
            "example": [
              "ai_self_inspection",
              "test_drive"
            ],
            "items": {
              "type": "string",
              "enum": [
                "ai_self_inspection",
                "in_person_mechanical_inspection",
                "personal_inspection",
                "mechanic_inspection",
                "test_drive",
                "title_check"
              ]
            }
          },
          "customConditions": {
            "description": "Free-text contingency riders shown to the counterparty (max 10, 250 chars each)",
            "example": [
              "Subject to clean title",
              "Pending finance approval"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "customMessage": {
            "type": "string",
            "description": "Message to the counterparty (max 1000 chars)"
          }
        },
        "required": [
          "vin"
        ]
      },
      "InitiateDealNowResponseV1Dto": {
        "type": "object",
        "properties": {
          "dealId": {
            "type": "string",
            "description": "Unique identifier for the created deal",
            "example": "64a1f2e3b5c8d90012345678"
          },
          "guid": {
            "type": "string",
            "description": "Stable opaque GUID for the deal — matches the `guid` field on subsequent partner webhook payloads",
            "example": "b3c4d5e6-7f8a-49b0-a1b2-c3d4e5f6a7b8"
          },
          "buyerLink": {
            "type": "string",
            "description": "Deep link for the buyer to access the DealNow flow",
            "example": "https://app.privateauto.com/deal-now/64a1f2e3b5c8d90012345678?role=buyer"
          },
          "sellerLink": {
            "type": "string",
            "description": "Deep link for the seller to access the DealNow flow",
            "example": "https://app.privateauto.com/deal-now/64a1f2e3b5c8d90012345678?role=seller"
          }
        },
        "required": [
          "dealId",
          "guid",
          "buyerLink",
          "sellerLink"
        ]
      },
      "LeadContactV1Dto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Prospect full name",
            "example": "Jane Smith"
          },
          "email": {
            "type": "string",
            "description": "Prospect email address",
            "example": "jane@example.com"
          },
          "phone": {
            "type": "string",
            "description": "Prospect phone number",
            "example": "555-867-5309"
          },
          "message": {
            "type": "string",
            "description": "Prospect message or notes",
            "example": "Interested in trading in my truck"
          }
        }
      },
      "LeadVehicleV1Dto": {
        "type": "object",
        "properties": {
          "vin": {
            "type": "string",
            "description": "17-character Vehicle Identification Number",
            "example": "1HGBH41JXMN109186"
          },
          "year": {
            "type": "number",
            "description": "Model year",
            "example": 2019
          },
          "make": {
            "type": "string",
            "description": "Vehicle make",
            "example": "Honda"
          },
          "model": {
            "type": "string",
            "description": "Vehicle model",
            "example": "Accord"
          },
          "trim": {
            "type": "string",
            "description": "Vehicle trim level",
            "example": "Sport"
          },
          "mileage": {
            "type": "number",
            "description": "Odometer reading in miles",
            "example": 42000
          }
        }
      },
      "SubmitLeadV1Dto": {
        "type": "object",
        "properties": {
          "callerReferenceId": {
            "type": "string",
            "description": "Your own reference ID for this lead — used for idempotent dedup. Resubmitting the same value returns 409 with the existing lead ID.",
            "example": "LDR-98234"
          },
          "organizationId": {
            "type": "string",
            "description": "Target dealer organization ID. Must be on your partner allowlist.",
            "example": "663a1f2b4e8c9a001234abcd"
          },
          "leadCode": {
            "type": "string",
            "description": "Lead code tag for categorization (e.g. CONQUEST, SERVICE, TRADE_IN)",
            "example": "CONQUEST"
          },
          "contact": {
            "description": "Prospect contact information",
            "allOf": [
              {
                "$ref": "#/components/schemas/LeadContactV1Dto"
              }
            ]
          },
          "vehicle": {
            "description": "Vehicle of interest",
            "allOf": [
              {
                "$ref": "#/components/schemas/LeadVehicleV1Dto"
              }
            ]
          },
          "listingId": {
            "type": "string",
            "description": "Link to an existing PrivateAuto listing ID",
            "example": "663b2f3c5e9d0b002345bcde"
          }
        },
        "required": [
          "callerReferenceId",
          "organizationId"
        ]
      },
      "SubmitLeadResponseV1Dto": {
        "type": "object",
        "properties": {
          "leadId": {
            "type": "string",
            "description": "PrivateAuto lead ID",
            "example": "663c3f4d6fae0c003456cdef"
          },
          "callerReferenceId": {
            "type": "string",
            "description": "Your reference ID echoed back",
            "example": "LDR-98234"
          },
          "status": {
            "type": "string",
            "description": "Current lead status",
            "example": "new",
            "enum": [
              "new",
              "contacted",
              "qualified",
              "closed"
            ]
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "description": "Timestamp when the lead was created",
            "example": "2026-04-16T14:22:00.000Z"
          }
        },
        "required": [
          "leadId",
          "callerReferenceId",
          "status",
          "createdAt"
        ]
      },
      "DuplicateLeadResponseV1Dto": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error code",
            "example": "duplicate_reference"
          },
          "leadId": {
            "type": "string",
            "description": "Existing lead ID for this callerReferenceId",
            "example": "663c3f4d6fae0c003456cdef"
          },
          "callerReferenceId": {
            "type": "string",
            "description": "The duplicate callerReferenceId",
            "example": "LDR-98234"
          }
        },
        "required": [
          "error",
          "leadId",
          "callerReferenceId"
        ]
      },
      "DealerLookupV1Dto": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "Email address of a PrivateAuto user",
            "example": "jane@example.com"
          }
        },
        "required": [
          "email"
        ]
      },
      "DealerLookupResponseV1Dto": {
        "type": "object",
        "properties": {
          "organizationIds": {
            "description": "PrivateAuto dealership ids this user belongs to — use them wherever an organization id is expected. More than one is possible where the user has access to several dealerships.",
            "example": [
              "663a1f2b9c1e4a0012345678"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "organizationIds"
        ]
      }
    }
  }
}